feat!: Introduce @seamapi/url-search-params-parser behind useLegacyQueryParamsParser

[razor-x]

Summary

Targets beta (v4). Introduces query string parsing with @seamapi/url-search-params-parser (in generous mode, strict: false) behind a new useLegacyQueryParamsParser option — with the legacy parser remaining the default.

The release plan:

• v4 (this PR, on beta): dropping CJS/ESM-only is the headline breaking change (already on beta via 4.0.0-beta.1). The new parser ships behind an option; upgrading changes no query parsing behavior by default.
• v5: the default swaps to the new parser; useLegacyQueryParamsParser sticks around as the escape hatch before being removed in a later release.

The option

Settable in two places; the route spec overrides the factory:

// Opt a whole factory into the new parser:
export const withRouteSpec = createWithRouteSpec({ ..., useLegacyQueryParamsParser: false })

// Or migrate route by route on a shared factory (e.g. seam-connect):
export const route_spec = checkRouteSpec({
  methods: ["GET"],
  useLegacyQueryParamsParser: false, // this route uses the new parser
  queryParams,
  ...
})

The parser module is loaded lazily (dynamic import()), so routes on the legacy default never load it, and consumers loading nextlove through a CommonJS transform (e.g. tsx/cjs, esbuild-register test setups) don't need to resolve the ESM-only dependency unless they opt in.

Breaking change (beyond the ESM-only change already on beta)

• supportedArrayFormats is removed from SetupParams/RequestInput, along with the QueryArrayFormat/QueryArrayFormats types and the DEFAULT_ARRAY_FORMATS export. All callers were using the default (all three formats), and both parsers now accept the repeated, bracket, and comma formats on every route. Routes that restricted formats lose the Bracket syntax not supported... / Repeated parameters not supported... 400s.

What changes when a route opts in (useLegacyQueryParamsParser: false)

None of this applies on the default; it's the v5 migration checklist.

New capabilities (previously rejected, now accepted):

1. z.number() / z.date() query params parse without z.coerce (?limit=5 → 5); whitespace is trimmed around numbers/booleans/dates.
2. Generous booleans: true/True/TRUE/yes/Yes/YES/1 → true; false/False/FALSE/no/No/NO/0 → false (legacy: only "true" is truthy, anything else is false).
3. Nested objects and records via dot notation: ?address.city=SF, ?tags.a=1&tags.b=2.
4. Top-level and property-level z.union() / z.discriminatedUnion() of objects are parsed.

Stricter parsing (previously accepted, now 400):

5. Junk boolean values fail (?flag=yolo was silently false, now 400 invalid_input).
6. Empty string params are null (?name= passed z.string() as "", now fails unless nullable; omitting the param still works for optional fields).
7. Ambiguous input → 400 invalid_query_params: repeated non-array params (?id=1&id=2), mixed array formats (?ids=1&ids[]=2), commas inside bracket values (?ids[]=a,b, previously split), repeated values containing commas (?ids=a,b&ids=c,d, previously literal), arrays mixing empty and non-empty values. Net: array values containing a literal comma can't be transmitted in generous mode.
8. commonParams body values are no longer coerced ({"ids": "a,b"} was comma-split, {"flag": "true"} coerced) — bodies validate as-is.
9. Boolean dynamic route params stay raw strings (legacy coerced them).

Schema restrictions (route authors): unsupported constructs fail every request with 500 unparseable_schema instead of validating raw strings — z.array(z.boolean()), arrays of objects, nullable arrays, z.tuple() (see #180), z.any()/z.unknown()/z.bigint() props, intersections/maps/sets, records of non-primitives, unions of incompatible primitives. Inventory route schemas before opting in (or opt in per route and keep the offenders on legacy until adjusted). Error type changes: ambiguity errors move from Zod's invalid_input to invalid_query_params.

Implementation notes

• New-parser path: parse req.url's search params (strict: false), strip absent (undefined) keys, overlay Next.js dynamic route params and unknown params (preserving .strict()/.passthrough() semantics), then schema.parse. UnparseableSearchParamError → 400 invalid_query_params; UnparseableSchemaError → 500 unparseable_schema.
• Legacy path is byte-for-byte the previous coercion, with all array formats enabled (the removed option's default).
• commonParams merges the raw (pre-validation) body over the query in both paths.

Testing

• Root package: typecheck + 8 ava tests pass.
• Example app: 42/42 integration tests pass against the published parser 0.2.1, including:
  • legacy default coverage (no option set): all three array formats, "yolo" → false, repeated values keeping commas
  • new-parser factory coverage: all formats, mixed-format 400, junk-boolean 400, generous booleans
  • per-route override on a legacy-default factory (the seam-connect migration path)