zod-funnel — accept many input shapes, parse to one canonical schema

[Roman86]

Hi! I built a small utility on top of Zod 4 and would love to share it with the ecosystem.

The problem. APIs evolve: a field gets renamed, an old client still sends the legacy payload, a third party uses its own naming. Plain Zod can express this — an .or(...).transform(...).pipe(...) chain — but that's a fairly advanced corner of the API: not every Zod user knows to reach for it, the target schema has to be repeated in every branch, and forgetting the final .pipe(target) re-validation silently leaks unvalidated data. In practice people fall back to ad-hoc normalizers scattered around the codebase. zod-funnel packages that pattern into one small high-level primitive, so the correct wiring is the only wiring you can write.

The idea. Declare the canonical schema once, then funnel each alternate shape into it with a small, type-checked mapper:

import * as z from 'zod';
import { funnel } from 'zod-funnel';

const Person = z.object({
  firstName: z.string(),
  lastName: z.string(),
});

const PersonFlex = funnel(Person)
  .from(
    z.object({ first_name: z.string(), last_name: z.string() }),
    ({ first_name, last_name }) => ({
      firstName: first_name,
      lastName: last_name,
    }),
  )
  .from(z.object({ full_name: z.string() }), ({ full_name }) => ({
    firstName: full_name.split(' ')[0],
    lastName: full_name.split(' ')[1],
  }))
  .from(z.object({ name: z.string() }), ({ name }) => ({
    firstName: name.split(' ')[0],
    lastName: name.split(' ')[1],
  }));

PersonFlex.parse({ firstName: 'John', lastName: 'Doe' }); // canonical
PersonFlex.parse({ first_name: 'John', last_name: 'Doe' }); // → { firstName: 'John', lastName: 'Doe' }
PersonFlex.parse({ full_name: 'John Doe' }); // → { firstName: 'John', lastName: 'Doe' }

PersonFlex is a real Zod schema — parse, safeParse, .array(), .optional() and the rest of the API work as usual. Sources don't have to be objects: a bare string, number, or tuple works too.

Design notes:

• Deliberately thin sugar over Zod itself: it builds a flat z.union([target, ...mapped]), nothing custom at parse time.
• Every mapper's output is re-validated against the target schema, so a mapping that produces invalid data fails the parse instead of leaking a broken value.
• Each mapper's return type is checked against the canonical schema's input type.
• No performance cost: the benchmark in the repo compares against the equivalent hand-written schema on every CI push (a flat union actually measures slightly faster than a nested .or() chain).

Links: GitHub · npm

I'd be happy to add it to the ecosystem page — PR incoming, will link it here.

Feedback very welcome — naming, semantics, edge cases I've missed.

[Roman86]

I've prepared the ecosystem page entry as a one-line addition to the Zod Utilities section, but PR creation on this repo seems to be limited to collaborators, so linking the ready branch instead:

main...Roman86:zod:ecosystem-zod-funnel

(single commit on top of current main, touches only packages/docs/components/ecosystem.tsx — happy to open it as a PR if that becomes possible, or feel free to cherry-pick.)