paramour 0.5.1 → 0.6.0

package/dist/route.js

@@ -2,10 +2,10 @@ import { describeType, foreignMessage, ParamourError, ParamsDecodeError, SearchD
 import { decodeParams, tokenizePath, } from "./path.js";
 import { decodeSearch, } from "./search.js";
 /**
- * Defines an App Router route: the URL-shaped path literal (RL2) plus its
- * param/search codec configs. Validates the literal eagerly (RL1 —
- * fail-fast at config definition time, same stance as eager `.default()`
- * serialization). The router is a *declaration*, not an inference (PR7):
+ * Defines an App Router route: the URL-shaped path literal plus its
+ * param/search codec configs. Validates the literal eagerly — fail-fast at
+ * config definition time, the same stance as eager `.default()`
+ * serialization. The router is a *declaration*, not an inference:
  * pre-codegen the registry cannot distinguish routers, so an inferred brand
  * would silently degrade in world A — the split constructor is what keeps
  * the brand intact there.
@@ -15,11 +15,11 @@ export function defineAppRoute(path, config) {
         ...routeData("app", path, config),
         async parse(props) {
             const [paramsSource, searchSource] = await awaitProps(props);
-            // RL6: params first — a params failure throws before search decodes.
+            // Params first — a params failure throws before search decodes.
             const decodedParams = decodeParams(route, paramsSource ?? {});
             return {
                 params: decodedParams,
-                search: decodeSearch(route["~search"], searchSource ?? {}),
+                search: decodeSearch(route["~search"], searchSource ?? {}, route.path),
             };
         },
         async parseParams(props) {
@@ -28,7 +28,7 @@ export function defineAppRoute(path, config) {
         },
         async parseSearch(props) {
             const source = await awaitProp(props.searchParams);
-            return decodeSearch(route["~search"], source ?? {});
+            return decodeSearch(route["~search"], source ?? {}, route.path);
         },
         safeParse(props) {
             return safely(() => route.parse(props));
@@ -43,16 +43,16 @@ export function defineAppRoute(path, config) {
     return route;
 }
 /**
- * Defines a Pages Router route (PR7 — neither router is the default; see
+ * Defines a Pages Router route — neither router is the default; see
  * {@link defineAppRoute} for why the constructor is split rather than
- * inferred). Same eager literal validation (RL1); the parse surface is the
- * sync context pair (PR10).
+ * inferred. Same eager literal validation; the parse surface is the sync
+ * context pair.
  */
 export function definePagesRoute(path, config) {
     const data = routeData("pages", path, config);
-    // PR10: the query→params extraction and query→search subtraction both key
-    // on the dynamic-segment names; computed once at define time (the
-    // ~segments ethos — per-call parses never re-derive them).
+    // The query→params extraction and query→search subtraction both key on
+    // the dynamic-segment names; computed once at define time (the ~segments
+    // ethos — per-call parses never re-derive them).
     const paramNames = new Set();
     for (const segment of data["~segments"]) {
         if (segment.kind !== "static")
@@ -62,7 +62,7 @@ export function definePagesRoute(path, config) {
         ...data,
         parseContext(context) {
             const [paramsSource, searchSource] = splitPagesContext(context, paramNames);
-            // PR10: params first — same morally-a-404 rule as the app surface.
+            // Params first — same morally-a-404 rule as the app surface.
             // R5: pages sources (ctx.params / ctx.query) are already percent-decoded
             // by Node's querystring layer, so skip core's decode to avoid a
             // double-decode (App-Router's decodeParams keeps the default).
@@ -71,12 +71,12 @@ export function definePagesRoute(path, config) {
             });
             return {
                 params: decodedParams,
-                search: decodeSearch(route["~search"], searchSource),
+                search: decodeSearch(route["~search"], searchSource, route.path),
             };
         },
         safeParseContext(context) {
-            // safely's taxonomy (PR12), minus the await: only decode failures
-            // become the error arm; contract violations stay loud.
+            // safely's taxonomy, minus the await: only decode failures become the
+            // error arm; contract violations stay loud.
             try {
                 return { data: route.parseContext(context), status: "success" };
             }
@@ -96,17 +96,17 @@ function awaitProp(value) {
     return rebrandRejection(Promise.resolve(value));
 }
 /**
- * Awaits BOTH props members before any decode runs (RL6): the
- * params-before-search rule is about *decode* order, not await order —
- * throwing while the searchParams promise is still pending would turn a
- * rejecting props promise into an unhandled rejection.
+ * Awaits BOTH props members before any decode runs: the params-before-search
+ * rule is about *decode* order, not await order — throwing while the
+ * searchParams promise is still pending would turn a rejecting props promise
+ * into an unhandled rejection.
  */
 function awaitProps(props) {
     return rebrandRejection(Promise.all([props.params, props.searchParams]));
 }
 /**
  * Own enumerable properties of `source` whose keys are NOT in `keys` —
- * the query→search subtraction (PR10). Entries → fromEntries so keys like
+ * the query→search subtraction. Entries → fromEntries so keys like
  * "__proto__" stay ordinary own properties (decodeParams's ethos).
  */
 function omitOwn(source, keys) {
@@ -114,7 +114,7 @@ function omitOwn(source, keys) {
 }
 /**
  * Own properties of `source` at exactly `keys` — the query→params
- * extraction (PR10). A name missing from the source is simply omitted, so
+ * extraction. A name missing from the source is simply omitted, so
  * it surfaces downstream as decodeParams's ordinary required-missing issue,
  * never a crash here.
  */
@@ -153,9 +153,9 @@ async function rebrandRejection(promise) {
     }
 }
 /**
- * Shared define-time core of both constructors (PR7): validates the literal
- * eagerly (RL1 — throws ParamourError on an invalid literal) and pins the
- * data members both parse surfaces build on. The conditional RouteConfig is
+ * Shared define-time core of both constructors: validates the literal
+ * eagerly (throwing ParamourError on an invalid literal) and pins the data
+ * members both parse surfaces build on. The conditional RouteConfig is
  * unresolved inside a generic body; the cast here is the one place its two
  * branches are unified.
  */
@@ -171,7 +171,7 @@ function routeData(router, path, config) {
     };
 }
 /**
- * Wraps a throwing parse into the status-discriminated shape (RL6, PR12).
+ * Wraps a throwing parse into the status-discriminated shape.
  * Only decode failures become the `error` arm; source-contract violations
  * and rebranded foreign errors stay loud.
  */
@@ -188,13 +188,13 @@ async function safely(run) {
     }
 }
 /**
- * Splits a pages context into its params/search decode sources (PR10).
+ * Splits a pages context into its params/search decode sources.
  * `params` is authoritative when present — handed to decodeParams whole,
  * whose own contract check rejects a garbage member; absent, path params
  * are extracted from `query` by name. Search is always `query` minus the
  * path-param names. A missing `query` is a CONTRACT violation, not a decode
  * issue: `getStaticProps` has no query string, so composing its context
- * here would be a lie (PR10) — the error names the supported path instead.
+ * here would be a lie — the error names the supported path instead.
  */
 function splitPagesContext(context, paramNames) {
     const untrusted = context;
@@ -204,7 +204,7 @@ function splitPagesContext(context, paramNames) {
     const { params, query } = untrusted;
     const untrustedQuery = query;
     if (typeof untrustedQuery !== "object" || untrustedQuery === null) {
-        throw new ParamourError(`pages context has no query object (got ${describeType(untrustedQuery)}): getStaticProps contexts carry no query string — decode ctx.params with safeDecodeParams instead (PR10)`);
+        throw new ParamourError(`pages context has no query object (got ${describeType(untrustedQuery)}): getStaticProps contexts carry no query string — decode ctx.params with safeDecodeParams instead`);
     }
     return [params ?? pickOwn(query, paramNames), omitOwn(query, paramNames)];
 }

package/dist/safe-decode.d.ts

@@ -2,15 +2,16 @@ import type { AnyRoute, InferRouteParams, SafeResult } from "./route.js";
 import { type DecodeParamsOptions, type ParamsSource } from "./path.js";
 import { type SearchOutputOf, type SearchSource } from "./search.js";
 /**
- * Sync `SafeResult` twins of {@link decodeParams} / {@link decodeSearch}
- * (RL6's stance at the standalone-function layer): the route methods'
- * `safeParse*` surface awaits props, but sync callers — client hooks,
- * middleware, route handlers — already hold a decoded-value-layer source.
- * Same taxonomy as route.ts's `safely`: only a decode failure becomes the
- * `error` arm; source-contract violations, rebranded foreign errors, and
- * async-schema misuse (design-02 D7) stay loud and propagate unchanged.
+ * Sync `SafeResult` twins of {@link decodeParams} / {@link decodeSearch},
+ * carrying the route methods' safe-parse stance down to the
+ * standalone-function layer: `safeParse*` awaits props, but sync callers —
+ * client hooks, middleware, route handlers — already hold a
+ * decoded-value-layer source. Same taxonomy as route.ts's `safely`: only a
+ * decode failure becomes the `error` arm; source-contract violations,
+ * rebranded foreign errors, and async-schema misuse stay loud and propagate
+ * unchanged.
  */
-/** Decoded route params as a `SafeResult` (discriminated on `status`, PR12). */
+/** Decoded route params as a `SafeResult` (discriminated on `status`). */
 export declare function safeDecodeParams<R extends AnyRoute>(route: R, source: ParamsSource, options?: DecodeParamsOptions): SafeResult<InferRouteParams<R>>;
-/** Decoded search params as a `SafeResult` (discriminated on `status`, PR12). */
+/** Decoded search params as a `SafeResult` (discriminated on `status`). */
 export declare function safeDecodeSearch<R extends AnyRoute>(route: R, source: SearchSource): SafeResult<SearchOutputOf<R["~search"]>>;

package/dist/safe-decode.js

@@ -2,15 +2,16 @@ import { ParamsDecodeError, SearchDecodeError } from "./errors.js";
 import { decodeParams, } from "./path.js";
 import { decodeSearch, } from "./search.js";
 /**
- * Sync `SafeResult` twins of {@link decodeParams} / {@link decodeSearch}
- * (RL6's stance at the standalone-function layer): the route methods'
- * `safeParse*` surface awaits props, but sync callers — client hooks,
- * middleware, route handlers — already hold a decoded-value-layer source.
- * Same taxonomy as route.ts's `safely`: only a decode failure becomes the
- * `error` arm; source-contract violations, rebranded foreign errors, and
- * async-schema misuse (design-02 D7) stay loud and propagate unchanged.
+ * Sync `SafeResult` twins of {@link decodeParams} / {@link decodeSearch},
+ * carrying the route methods' safe-parse stance down to the
+ * standalone-function layer: `safeParse*` awaits props, but sync callers —
+ * client hooks, middleware, route handlers — already hold a
+ * decoded-value-layer source. Same taxonomy as route.ts's `safely`: only a
+ * decode failure becomes the `error` arm; source-contract violations,
+ * rebranded foreign errors, and async-schema misuse stay loud and propagate
+ * unchanged.
  */
-/** Decoded route params as a `SafeResult` (discriminated on `status`, PR12). */
+/** Decoded route params as a `SafeResult` (discriminated on `status`). */
 export function safeDecodeParams(route, source, options) {
     try {
         return { data: decodeParams(route, source, options), status: "success" };
@@ -21,16 +22,16 @@ export function safeDecodeParams(route, source, options) {
         throw error;
     }
 }
-/** Decoded search params as a `SafeResult` (discriminated on `status`, PR12). */
+/** Decoded search params as a `SafeResult` (discriminated on `status`). */
 export function safeDecodeSearch(route, source) {
     try {
-        // decodeSearch is keyed on SearchOutputOf (design-04 SS6) — the correct
+        // decodeSearch is keyed on SearchOutputOf (SS6) — the correct
         // public type — but AnyRoute erases its SC to `any`, so for a still-
         // generic R the call's value side reduces to `unknown` while the
         // annotation side stays deferred. The cast bridges that inference gap to
         // the SAME (correct) type.
         return {
-            data: decodeSearch(route["~search"], source),
+            data: decodeSearch(route["~search"], source, route.path),
             status: "success",
         };
     }

package/dist/schema.d.ts

@@ -2,9 +2,9 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 /**
  * Runs a Standard Schema synchronously and returns the raw result. Standard
  * Schema permits async validation, but URL parsing must be sync — an async
- * schema is a documented runtime error (design-02 D7). Shared by `p.ts`
- * (which joins `result.issues` into one message string) and the raw-search
- * decode path (which needs structured `Issue[]` with `path`) — each call
- * site maps issues its own way (plan-04 step 1).
+ * schema is a documented runtime error. Shared by `p.ts` (which joins
+ * `result.issues` into one message string) and the raw-search decode path
+ * (which needs structured `Issue[]` with `path`) — each call site maps
+ * issues its own way.
  */
 export declare function runStandardSchemaSync<Out>(schema: StandardSchemaV1<unknown, Out>, value: unknown): StandardSchemaV1.Result<Out>;

package/dist/schema.js

@@ -2,10 +2,10 @@ import { ParamourError } from "./errors.js";
 /**
  * Runs a Standard Schema synchronously and returns the raw result. Standard
  * Schema permits async validation, but URL parsing must be sync — an async
- * schema is a documented runtime error (design-02 D7). Shared by `p.ts`
- * (which joins `result.issues` into one message string) and the raw-search
- * decode path (which needs structured `Issue[]` with `path`) — each call
- * site maps issues its own way (plan-04 step 1).
+ * schema is a documented runtime error. Shared by `p.ts` (which joins
+ * `result.issues` into one message string) and the raw-search decode path
+ * (which needs structured `Issue[]` with `path`) — each call site maps
+ * issues its own way.
  */
 export function runStandardSchemaSync(schema, value) {
     const result = schema["~standard"].validate(value);

package/dist/search.d.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { AnyCodec, OutputOf, PresenceOf } from "./codec.js";
 /**
- * href-input side (design-02 D4): required presence stays required;
+ * href-input side (D4): required presence stays required;
  * optional and defaulted keys may be omitted. Array (arity-"many") keys may
  * also be omitted: absent and [] are the same wire state (S6/P6), so
  * requiring `tags: []` ceremony would be pure noise. Omittable keys also
@@ -17,14 +17,14 @@ export type InferSearchInput<S extends SearchConfig> = {
     [K in OptionalInputKeys<S>]?: OutputOf<S[K]> | undefined;
 };
 /**
- * Parse-output side (design-02 D4): every declared key is PRESENT on the
+ * Parse-output side (D4): every declared key is PRESENT on the
  * object; optional presence contributes `| undefined` to the value type.
  */
 export type InferSearchOutput<S extends SearchConfig> = {
     [K in keyof S]: PresenceOf<S[K]> extends "optional" ? OutputOf<S[K]> | undefined : OutputOf<S[K]>;
 };
 /**
- * The whole-object search escape hatch (design-04 SS1/SS2): wraps a bare
+ * The whole-object search escape hatch (SS1/SS2): wraps a bare
  * Standard Schema in a branded marker so `search:` config discrimination is
  * unambiguous at both the type and runtime level. `~`-prefixed members are
  * reserved (codec convention) — a codec map never carries them at the top
@@ -37,7 +37,7 @@ export interface RawSearch<S extends StandardSchemaV1> {
 /** A search-params schema: key → codec. */
 export type SearchConfig = Record<string, AnyCodec>;
 /**
- * href / encode side of a `search:` config (design-04 SS6): a `RawSearch`
+ * href / encode side of a `search:` config (SS6): a `RawSearch`
  * route accepts the raw wire record (SS5 — the schema never runs on encode,
  * so there's no encode-side type to infer from it); a codec map keeps its
  * existing `InferSearchInput` behavior. Module-exported for route.ts/href.ts,
@@ -45,23 +45,23 @@ export type SearchConfig = Record<string, AnyCodec>;
  */
 export type SearchInputOf<SC> = SC extends RawSearch<StandardSchemaV1> ? Record<string, string | string[]> : SC extends SearchConfig ? InferSearchInput<SC> : never;
 /**
- * Parse-output side of a `search:` config (design-04 SS6): a `RawSearch`
+ * Parse-output side of a `search:` config (SS6): a `RawSearch`
  * route's output is the schema's own inferred output; a codec map keeps its
  * existing `InferSearchOutput` behavior. Module-exported for
  * route.ts/href.ts, not barrel-exported.
  */
 export type SearchOutputOf<SC> = SC extends RawSearch<infer S> ? StandardSchemaV1.InferOutput<S> : SC extends SearchConfig ? InferSearchOutput<SC> : never;
 /**
- * The `search:` config slot's full type (design-04 SS2): a codec map (the
+ * The `search:` config slot's full type (SS2): a codec map (the
  * main road) or a `RawSearch` marker (the escape hatch). Internal — not
  * barrel-exported; `Route`/`RouteConfig`/`HrefArgs` consume it as their `SC`
  * bound.
  */
 export type SearchSlot = RawSearch<StandardSchemaV1> | SearchConfig;
 /**
- * Decoded value-layer sources (wire spec §1): Next's server `searchParams`
- * shape or the client's `URLSearchParams`. Both are already percent-decoded
- * by the platform.
+ * Decoded value-layer sources: Next's server `searchParams` shape or the
+ * client's `URLSearchParams`. Both are already percent-decoded by the
+ * platform.
  */
 export type SearchSource = Record<string, string | string[] | undefined> | URLSearchParams;
 type OptionalInputKeys<S extends SearchConfig> = {
@@ -80,15 +80,19 @@ export declare function buildSearchString(pairs: readonly (readonly [string, str
  * 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 declare function decodeSearch<S extends SearchSlot>(config: S, source: SearchSource): SearchOutputOf<S>;
+export declare function decodeSearch<S extends SearchSlot>(config: S, source: SearchSource, routePath?: string): SearchOutputOf<S>;
 /**
  * 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 declare function encodeComponent(text: string): string;
@@ -98,7 +102,7 @@ export declare function encodeComponent(text: string): string;
  * 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).
@@ -106,13 +110,13 @@ export declare function encodeComponent(text: string): string;
  * 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 declare function encodeSearch<S extends SearchSlot>(config: S, input: SearchInputOf<S>): [string, string][];
 /**
- * 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
@@ -126,22 +130,22 @@ export declare function isRawSearch(config: SearchSlot): config is RawSearch<Sta
  * 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).
  */
 export declare function parseValue(codec: AnyCodec, raw: string): unknown;
 /**
- * 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 declare function rawSearch<S extends StandardSchemaV1>(schema: S): RawSearch<S>;
 /**