paramour 0.5.0 → 0.6.0

package/dist/search.js

@@ -1,4 +1,5 @@
-import { describeType, foreignMessage, ParamourError, ParseError, rebrandForeign, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+import { codecShapeLabel } from "./describe.js";
+import { describeType, foreignMessage, ParamourError, ParseError, parseIssueReason, rebrandForeign, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
 import { runStandardSchemaSync } from "./schema.js";
 /**
  * Builds the byte-layer query string from decoded pairs. Hand-rolled on
@@ -19,14 +20,18 @@ export function buildSearchString(pairs) {
  * under keys paramour doesn't own can never fail a decode.
  * Throws {@link SearchDecodeError} carrying one issue per failed key.
  *
- * A `RawSearch` config (design-04 SS2) branches to the whole-object schema
+ * A `RawSearch` config (SS2) branches to the whole-object schema
  * path instead: every source key reaches the schema (P8 does not apply
  * there — the schema owns stripping or passing through extras).
+ *
+ * `routePath` anchors a thrown {@link SearchDecodeError} to the owning
+ * route's path pattern — route-level surfaces pass `route.path`; standalone
+ * callers (nuqs, devtools) omit it and the error stays route-less.
  */
-export function decodeSearch(config, source) {
+export function decodeSearch(config, source, routePath) {
     requireSearchConfig(config);
     if (isRawSearch(config)) {
-        return decodeRawSearch(config, source);
+        return decodeRawSearch(config, source, routePath ?? null);
     }
     // The conditional SearchSlot doesn't narrow inside the generic body once
     // the RawSearch branch returns (S stays a generic type parameter); this
@@ -47,12 +52,21 @@ export function decodeSearch(config, source) {
     const sourceValues = readDeclaredValues(searchConfig, source);
     // Absence is presence's job — .catch() only ever recovers parse
     // *failures* (D2), which is why this is shared by both arity branches.
-    const recoverParseError = (error, key, codec) => {
+    const recoverParseError = (error, key, codec, wire, reason) => {
         if (error instanceof ParseError && codec["~catchValue"] !== undefined) {
             entries.push([key, codec["~catchValue"]()]);
         }
         else if (error instanceof ParseError) {
-            issues.push({ key, message: error.message });
+            issues.push({
+                expected: codecShapeLabel(codec),
+                key,
+                message: error.message,
+                // An explicitly passed reason (the duplicate-scalar rejection) wins;
+                // otherwise the ParseError's own selfDescribing flag decides
+                // "parse" vs "validate" — structural, never message sniffing.
+                reason: reason ?? parseIssueReason(error),
+                ...(wire === undefined ? {} : { wire }),
+            });
         }
         else {
             throw error;
@@ -64,11 +78,17 @@ export function decodeSearch(config, source) {
             // Array codecs consume all values in wire order; absent → [] (P6).
             // Presence modifiers are banned on array codecs, so no absence
             // handling exists here.
+            let offending;
             try {
-                entries.push([key, values.map((raw) => codec["~parseElement"](raw))]);
+                const parsed = [];
+                for (const raw of values) {
+                    offending = raw;
+                    parsed.push(codec["~parseElement"](raw));
+                }
+                entries.push([key, parsed]);
             }
             catch (error) {
-                recoverParseError(error, key, codec);
+                recoverParseError(error, key, codec, offending);
             }
             continue;
         }
@@ -84,7 +104,12 @@ export function decodeSearch(config, source) {
                     entries.push([key, undefined]);
                     break;
                 case "required":
-                    issues.push({ key, message: "required search param is missing" });
+                    issues.push({
+                        expected: codecShapeLabel(codec),
+                        key,
+                        message: "required search param is missing",
+                        reason: "missing",
+                    });
                     break;
             }
             continue;
@@ -100,18 +125,21 @@ export function decodeSearch(config, source) {
             entries.push([key, codec["~parseElement"](first)]);
         }
         catch (error) {
-            recoverParseError(error, key, codec);
+            // The duplicate-scalar rejection (P5) has no SINGLE offending value —
+            // only a genuine one-value parse cites its wire form — and its reason
+            // is passed explicitly: duplication is what failed, not the grammar.
+            recoverParseError(error, key, codec, values.length > 1 ? undefined : first, values.length > 1 ? "duplicate" : undefined);
         }
     }
     if (issues.length > 0) {
-        throw new SearchDecodeError(issues);
+        throw new SearchDecodeError(issues, routePath ?? null);
     }
     return Object.fromEntries(entries);
 }
 /**
  * encodeURIComponent throws a raw URIError on lone surrogates; wrap it so
  * the documented "every error is a ParamourError" contract holds (S7).
- * Exported for path.ts (the byte-layer chokepoint is shared with RL5's
+ * Exported for path.ts (the byte-layer chokepoint is shared with path
  * segment encoding), not from the package barrel.
  */
 export function encodeComponent(text) {
@@ -123,7 +151,7 @@ export function encodeComponent(text) {
  * Caveat: JS property enumeration puts integer-like keys ("0", "42") first
  * in ascending numeric order regardless of declaration — declaration order
  * is unrecoverable for those, so they sort numerically before all others.
- * Params equal to their `.default()` are elided (design-02 D8), compared by
+ * Params equal to their `.default()` are elided (D8), compared by
  * serialized wire form against the live default (re-serialized per encode —
  * a build-time snapshot would go stale if a reference-typed default were
  * mutated, silently dropping explicit values that then decode differently).
@@ -131,9 +159,9 @@ export function encodeComponent(text) {
  * time-varying factory would elide an explicit value that later decodes as
  * a different one.
  *
- * A `RawSearch` config (design-04 SS5) branches to a raw pass-through
- * instead: no serializer exists for a whole-object schema, so the caller's
- * record goes straight to the byte layer and the schema never runs on encode.
+ * A `RawSearch` config (SS5) branches to a raw pass-through instead: no
+ * serializer exists for a whole-object schema, so the caller's record goes
+ * straight to the byte layer and the schema never runs on encode.
  */
 export function encodeSearch(config, input) {
     requireSearchConfig(config);
@@ -192,7 +220,7 @@ export function encodeSearch(config, input) {
     return pairs;
 }
 /**
- * Runtime discriminant for the `search:` slot (design-04 SS2): probes the
+ * Runtime discriminant for the `search:` slot (SS2): probes the
  * `~kind` marker's VALUE, which is unambiguous against a codec map — a map
  * key literally named "~kind" would hold a codec object, never the marker
  * string. Exported from the package barrel so derived surfaces
@@ -208,10 +236,10 @@ export function isRawSearch(config) {
  * the codec's `.catch()` recovery applied (decodeSearch always recovers a
  * caught failure, so a probe through it cannot tell "parsed cleanly" from
  * "failed and was caught"). Exists for reflection-driven tooling — the
- * devtools panel's catch-attribution probe (design-12 DT7) — and any other
- * derived surface that must observe the raw parse outcome. A parse failure
- * throws the codec's own {@link ParseError}; foreign throws from a custom
- * codec propagate unwrapped, matching decodeSearch's taxonomy. For
+ * devtools panel's catch-attribution probe — and any other derived surface
+ * that must observe the raw parse outcome. A parse failure throws the
+ * codec's own {@link ParseError}; foreign throws from a custom codec
+ * propagate unwrapped, matching decodeSearch's taxonomy. For
  * arity-"many" codecs this parses ONE element of the repeated-key array,
  * not the whole array (the same contract as `~parseElement` itself).
  */
@@ -219,13 +247,13 @@ export function parseValue(codec, raw) {
     return codec["~parseElement"](raw);
 }
 /**
- * The whole-object search escape hatch (design-04 SS1, maintainer ruling):
- * an explicit, greppable wrapper around a bare Standard Schema so a route's
- * `search:` slot never falls into the degraded raw mode by accident — a
- * bare `search: schema` could be confused for a codec map, but `rawSearch`
- * is a conscious act. Per-key defaults/`.catch()` and round-trip encoding
- * are deliberately unavailable here (SS7); reach for `p.custom` if you need
- * bidirectional per-key transforms instead.
+ * The whole-object search escape hatch (SS1): an explicit, greppable wrapper
+ * around a bare Standard Schema so a route's `search:` slot never falls into
+ * the degraded raw mode by accident — a bare `search: schema` could be
+ * confused for a codec map, but `rawSearch` is a conscious act. Per-key
+ * defaults/`.catch()` and round-trip encoding are deliberately unavailable
+ * here (SS7); reach for `p.custom` if you need bidirectional per-key
+ * transforms instead.
  */
 export function rawSearch(schema) {
     return { "~kind": "raw-search", "~schema": schema };
@@ -296,17 +324,17 @@ export function serializeValue(codec, label, value) {
     return serialized;
 }
 /**
- * The `RawSearch` decode path (design-04 SS3/SS4). The schema receives EVERY
+ * The `RawSearch` decode path (SS3/SS4). The schema receives EVERY
  * source key, normalized to Next's own `searchParams` shape — P8's
  * declared-keys-only stance doesn't apply to a whole-object schema, which
- * owns stripping or passing through extras itself. Sync only, per D7 (the
- * shared runner throws on an async `validate`). A validator that THROWS
+ * owns stripping or passing through extras itself. Sync only — the shared
+ * runner throws on an async `validate`. A validator that THROWS
  * (rather than returning issues) is rebranded at this chokepoint — the
- * shared runner deliberately stays throw-preserving (plan-04 step 1) so this
- * call site owns the wrap, mirroring how a foreign throw is branded
- * elsewhere in the package.
+ * shared runner deliberately stays throw-preserving so this call site owns
+ * the wrap, mirroring how a foreign throw is branded elsewhere in the
+ * package.
  */
-function decodeRawSearch(config, source) {
+function decodeRawSearch(config, source, routePath) {
     const record = readAllValues(source);
     const result = rebrandForeign(() => runStandardSchemaSync(config["~schema"], record), (error) => new ParamourError(`raw-search schema validation threw: ${foreignMessage(error)}`, { cause: error }));
     if (result.issues) {
@@ -324,14 +352,20 @@ function decodeRawSearch(config, source) {
         // always produces a plain Array and is immune.
         const issues = Array.from(result.issues, (issue) => {
             const key = Array.from(issue.path ?? [], (seg) => String(typeof seg === "object" ? seg.key : seg)).join(".");
-            return { key: key === "" ? "<search>" : key, message: issue.message };
+            // "validate": the prose belongs to the user's whole-object schema —
+            // same classification as a per-key schema failure.
+            return {
+                key: key === "" ? "<search>" : key,
+                message: issue.message,
+                reason: "validate",
+            };
         });
-        throw new SearchDecodeError(issues);
+        throw new SearchDecodeError(issues, routePath);
     }
     return result.value;
 }
 /**
- * The `RawSearch` encode path (design-04 SS5): no serializer exists for a
+ * The `RawSearch` encode path (SS5): no serializer exists for a
  * whole-object schema, so the caller's already-wire-shaped record is pushed
  * straight to the byte layer — one pair per string value, one repeated pair
  * per array element — and the schema never runs on encode.
@@ -362,10 +396,10 @@ function encodeRawSearch(input) {
  * whole-object schema's `validate`) runs — sibling of
  * {@link readDeclaredValues} that reads all keys instead of declared-only
  * ones (SS3: a whole-object schema has no declared keys of its own).
- * Collapses each key's values by occurrence count (plan-04 point 2): one
- * value → `string`, multiple → `string[]`, uniformly for both
- * `URLSearchParams` and Next-record sources, so the schema author writes one
- * mental model regardless of which source it came from.
+ * Collapses each key's values by occurrence count: one value → `string`,
+ * multiple → `string[]`, uniformly for both `URLSearchParams` and
+ * Next-record sources, so the schema author writes one mental model
+ * regardless of which source it came from.
  */
 function readAllValues(source) {
     // The TS contract forbids non-object sources, but plain-JS callers reach

package/dist/standard-schema.d.ts

@@ -2,26 +2,26 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { AnyRoute } from "./route.js";
 import { type SearchOutputOf } from "./search.js";
 /**
- * Standard Schema generate-OUT (design-08): exports a route's `search:`
- * config as a spec-compliant Standard Schema. The mirror of schema.ts, which
- * runs Standard Schemas coming IN.
+ * Standard Schema generate-OUT: exports a route's `search:` config as a
+ * spec-compliant Standard Schema. The mirror of schema.ts, which runs
+ * Standard Schemas coming IN.
  */
 /**
- * The schema {@link standardSearchSchema} returns (STD1/STD3): input is
- * advertised as the wire-shaped record only — `URLSearchParams` is accepted
- * at runtime but kept out of the type, so client-side inference (tRPC) never
- * sees a shape that cannot serialize over JSON. Output is the route's decoded
- * search shape. `types` is carried by this annotation alone; the spec reads
- * it at the type level only, so no runtime key exists.
+ * The schema {@link standardSearchSchema} returns: input is advertised as
+ * the wire-shaped record only — `URLSearchParams` is accepted at runtime but
+ * kept out of the type, so client-side inference (tRPC) never sees a shape
+ * that cannot serialize over JSON. Output is the route's decoded search
+ * shape. `types` is carried by this annotation alone; the spec reads it at
+ * the type level only, so no runtime key exists.
  */
 export type StandardSearchSchema<SC> = StandardSchemaV1<Record<string, string | string[] | undefined>, SearchOutputOf<SC>>;
 /**
  * Exports a route's `search:` config as the URL wire contract in Standard
- * Schema form (design-08 STD1/STD5), for consumers like tRPC inputs or
- * TanStack `validateSearch`. Semantics are byte-identical to `decodeSearch`
- * (STD6): defaults apply, `.catch()` recovers parse failures — invalid API
- * input silently coerces to the fallback — unknown keys strip (P8), and
- * duplicate values on a scalar codec reject (P5). No coercion, ever (STD2):
- * the schema accepts wire strings (`"42"`), not decoded values (`42`).
+ * Schema form, for consumers like tRPC inputs or TanStack `validateSearch`.
+ * Semantics are byte-identical to `decodeSearch`: defaults apply, `.catch()`
+ * recovers parse failures — invalid API input silently coerces to the
+ * fallback — unknown keys strip (P8), and duplicate values on a scalar codec
+ * reject (P5). No coercion, ever: the schema accepts wire strings (`"42"`),
+ * not decoded values (`42`).
  */
 export declare function standardSearchSchema<R extends AnyRoute>(route: R): StandardSearchSchema<R["~search"]>;

package/dist/standard-schema.js

@@ -3,16 +3,16 @@ import { safeDecodeSearch } from "./safe-decode.js";
 import { isRawSearch, requireSearchConfig, } from "./search.js";
 /**
  * Exports a route's `search:` config as the URL wire contract in Standard
- * Schema form (design-08 STD1/STD5), for consumers like tRPC inputs or
- * TanStack `validateSearch`. Semantics are byte-identical to `decodeSearch`
- * (STD6): defaults apply, `.catch()` recovers parse failures — invalid API
- * input silently coerces to the fallback — unknown keys strip (P8), and
- * duplicate values on a scalar codec reject (P5). No coercion, ever (STD2):
- * the schema accepts wire strings (`"42"`), not decoded values (`42`).
+ * Schema form, for consumers like tRPC inputs or TanStack `validateSearch`.
+ * Semantics are byte-identical to `decodeSearch`: defaults apply, `.catch()`
+ * recovers parse failures — invalid API input silently coerces to the
+ * fallback — unknown keys strip (P8), and duplicate values on a scalar codec
+ * reject (P5). No coercion, ever: the schema accepts wire strings (`"42"`),
+ * not decoded values (`42`).
  */
 export function standardSearchSchema(route) {
     const config = route["~search"];
-    // A missing/malformed config is a programming error and stays loud (STD7);
+    // A missing/malformed config is a programming error and stays loud;
     // checking eagerly fails at construction, not at first validate().
     requireSearchConfig(config);
     // A config's raw/codec-map shape is fixed at construction; hoisted so the
@@ -31,7 +31,7 @@ export function standardSearchSchema(route) {
                     return { value: result.data };
                 }
                 catch (error) {
-                    // STD7: validate() receives genuinely untrusted input, so the
+                    // validate() receives genuinely untrusted input, so the
                     // source-shape contract the read layer enforces with loud throws
                     // softens to issues at this one boundary — SearchSourceError exists
                     // as its own branded class exactly so this catch can't swallow
@@ -39,9 +39,9 @@ export function standardSearchSchema(route) {
                     if (error instanceof SearchSourceError) {
                         return { issues: [toSourceIssue(error)] };
                     }
-                    // Async raw schema (design-02 D7), throwing raw validators, and
-                    // throwing .default()/.catch() factories are true programming
-                    // errors: loud (STD7).
+                    // Async raw schema, throwing raw validators, and throwing
+                    // .default()/.catch() factories are true programming errors: they
+                    // stay loud.
                     throw error;
                 }
             },
@@ -51,8 +51,8 @@ export function standardSearchSchema(route) {
     };
 }
 /**
- * Maps a source-shape violation to spec shape (STD7): keyed where the read
- * layer could attribute it, root-level (absent path) for a malformed source.
+ * Maps a source-shape violation to spec shape: keyed where the read layer
+ * could attribute it, root-level (absent path) for a malformed source.
  */
 function toSourceIssue(error) {
     return error.key === null
@@ -62,8 +62,8 @@ function toSourceIssue(error) {
 /**
  * Maps a decode issue to spec shape. decodeRawSearch collapses a root-level
  * schema issue to the "<search>" sentinel key (SS3/SS4); a Standard Schema
- * expresses "root" as an ABSENT path, so the sentinel un-maps here (STD7
- * "root-level otherwise") — for raw configs only, since a codec map's issues
+ * expresses "root" as an ABSENT path, so the sentinel un-maps back to a
+ * root-level issue here — for raw configs only, since a codec map's issues
  * are always keyed and a param may literally be named "<search>". (A raw
  * vendor issue whose real path is ["<search>"] still collides with the
  * sentinel — indistinguishable after the flat-key collapse.) Nested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paramour",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "exports": {
     ".": {
@@ -33,7 +33,7 @@
     "url": "git+https://github.com/JasonPaff/paramour.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/JasonPaff/paramour#readme",
+  "homepage": "https://paramour.dev",
   "bugs": {
     "url": "https://github.com/JasonPaff/paramour/issues"
   },