paramour 0.5.1 → 0.7.0

package/dist/p.d.ts

@@ -1,12 +1,12 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
 import { type Codec } from "./codec.js";
 /**
- * The `p.*` wire-codec builders (DESIGN §5 layer 1, design-02 D9).
- * Each codec defines how one value crosses the URL boundary, both directions.
+ * The `p.*` wire-codec builders. Each codec defines how one value
+ * crosses the URL boundary, in both directions.
  */
 export declare const p: {
     /**
-     * A repeated-key list (`?tags=a&tags=b`, design-13 PP1): arity "many", so
+     * A repeated-key list (`?tags=a&tags=b`, PP1): arity "many", so
      * presence modifiers are unavailable — absent and `[]` are the same wire
      * state (S6/P6) — unlike `p.csv`'s one-key packing (CV7). Elements are
      * strings unless an element codec is given.
@@ -14,7 +14,7 @@ export declare const p: {
     array<E = string>(element?: Codec<E>): Codec<E[], "required", false, "many">;
     boolean(): Codec<boolean>;
     /**
-     * A comma-separated scalar list in ONE wire value (design-11 CV1): arity
+     * A comma-separated scalar list in ONE wire value (CV1): arity
      * "single", so the full modifier set applies — unlike `p.array`'s
      * repeated-key format (CV7: both are first-class; csv is the one-key
      * packing). Elements are strings unless an element codec is given.
@@ -29,13 +29,14 @@ export declare const p: {
     enum<const M extends readonly [string, ...string[]]>(members: M): Codec<M[number]>;
     /**
      * A 1-based-on-wire / 0-based-in-memory integer for pagination-style
-     * params (`?page=1` ↔ index 0, design-13 PP5). Deliberately stricter than
-     * nuqs's `parseAsIndex`, whose below-floor behavior is unspecified: wire
-     * values below 1 are a ParseError (recoverable via `.catch()`, like any
-     * other malformed input), and a negative in-memory index — which cannot
+     * params (`?page=1` ↔ index 0, PP5). Deliberately stricter than nuqs's
+     * `parseAsIndex`, whose below-floor behavior is unspecified: wire values
+     * below 1 are a ParseError (recoverable via `.catch()`, like any other
+     * malformed input), and a negative in-memory index — which cannot
      * round-trip through the 1-based wire floor — is a SerializeError at
-     * link-build time (the RL1 ethos). The optional schema validates the
-     * in-memory (0-based) value on both sides.
+     * link-build time, failing where the link is written rather than on the
+     * next navigation. The optional schema validates the in-memory (0-based)
+     * value on both sides.
      */
     index<S extends StandardSchemaV1<number, number>>(schema?: S): Codec<S extends undefined ? number : StandardSchemaV1.InferOutput<S>>;
     integer<S extends StandardSchemaV1<number, number>>(schema?: S): Codec<S extends undefined ? number : StandardSchemaV1.InferOutput<S>>;

package/dist/p.js

@@ -1,7 +1,7 @@
 import { createCodec } from "./codec.js";
-import { foreignMessage, ParamourError, ParseError, rebrandForeign, SerializeError, showValue, } from "./errors.js";
+import { foreignMessage, grammarParseError, ParamourError, ParseError, rebrandForeign, SerializeError, showValue, } from "./errors.js";
 import { runStandardSchemaSync } from "./schema.js";
-// Wire grammars per wire-format spec §4. `Number()` alone is too loose
+// Wire grammars for the scalar kinds. `Number()` alone is too loose
 // (accepts hex, trims whitespace), hence explicit anchored patterns.
 const INTEGER_RE = /^-?\d+$/;
 const NUMBER_RE = /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/;
@@ -12,8 +12,8 @@ const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
 /**
  * Serialize-side Date guard. Years outside 0000–9999 are rejected:
  * toISOString switches to the expanded ±6-digit-year form there, which the
- * wire grammars (§4) cannot represent — better a loud SerializeError than a
- * URL that can never round-trip.
+ * wire grammars cannot represent — better a loud SerializeError than a URL
+ * that can never round-trip.
  */
 function expectSerializableDate(value) {
     if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
@@ -33,27 +33,30 @@ function joinIssues(issues) {
 }
 function parseIntegerElement(raw) {
     if (!INTEGER_RE.test(raw)) {
-        throw new ParseError(`"${raw}" is not an integer`);
+        throw grammarParseError(`"${raw}" is not an integer`);
     }
     const value = Number(raw);
     if (!Number.isSafeInteger(value)) {
-        throw new ParseError(`"${raw}" is outside the safe integer range`);
+        throw grammarParseError(`"${raw}" is outside the safe integer range`);
     }
     return value;
 }
 function parseNumberElement(raw) {
     if (!NUMBER_RE.test(raw)) {
-        throw new ParseError(`"${raw}" is not a number`);
+        throw grammarParseError(`"${raw}" is not a number`);
     }
     const value = Number(raw);
     if (!Number.isFinite(value)) {
-        throw new ParseError(`"${raw}" is not a finite number`);
+        throw grammarParseError(`"${raw}" is not a finite number`);
     }
     return value;
 }
 function refine(schema, value) {
     const result = runStandardSchemaSync(schema, value);
     if (result.issues) {
+        // Plain ParseError, NOT grammarParseError: the joined issue prose comes
+        // from the user's validator and is not guaranteed to quote the value or
+        // name the grammar, so renderers must add that context themselves.
         throw new ParseError(`Schema validation failed: ${joinIssues(result.issues)}`);
     }
     return result.value;
@@ -76,9 +79,10 @@ function refineForSerialize(schema, value) {
 /**
  * Shared element admission for `p.array`/`p.csv` (PP1/CV2): resolves the
  * no-arg default and mirrors the type-state exclusions — presence, catch,
- * and arity-many inners — for JS consumers (the RL1 ethos). Only the
- * element's parse/serialize functions are captured by the list builders, so
- * an accepted modifier would be silently dropped, not applied; one guard
+ * and arity-many inners — for JS consumers, who get the same fail-fast
+ * rejection at definition time that the type layer gives TS callers. Only
+ * the element's parse/serialize functions are captured by the list builders,
+ * so an accepted modifier would be silently dropped, not applied; one guard
  * keeps that runtime mirror of the type-state in a single place.
  */
 function resolveListElement(element, builder) {
@@ -127,12 +131,12 @@ function stringifyJson(value) {
  */
 let defaultListElement;
 /**
- * The `p.*` wire-codec builders (DESIGN §5 layer 1, design-02 D9).
- * Each codec defines how one value crosses the URL boundary, both directions.
+ * The `p.*` wire-codec builders. Each codec defines how one value
+ * crosses the URL boundary, in both directions.
  */
 export const p = {
     /**
-     * A repeated-key list (`?tags=a&tags=b`, design-13 PP1): arity "many", so
+     * A repeated-key list (`?tags=a&tags=b`, PP1): arity "many", so
      * presence modifiers are unavailable — absent and `[]` are the same wire
      * state (S6/P6) — unlike `p.csv`'s one-key packing (CV7). Elements are
      * strings unless an element codec is given.
@@ -166,7 +170,7 @@ export const p = {
                     return true;
                 if (raw === "false")
                     return false;
-                throw new ParseError(`"${raw}" is not "true" or "false"`);
+                throw grammarParseError(`"${raw}" is not "true" or "false"`);
             },
             serializeElement: (value) => {
                 if (typeof value !== "boolean") {
@@ -177,19 +181,18 @@ export const p = {
         });
     },
     /**
-     * A comma-separated scalar list in ONE wire value (design-11 CV1): arity
+     * A comma-separated scalar list in ONE wire value (CV1): arity
      * "single", so the full modifier set applies — unlike `p.array`'s
      * repeated-key format (CV7: both are first-class; csv is the one-key
      * packing). Elements are strings unless an element codec is given.
      */
     csv(element) {
         // CV2: presence, catch, and arity-many inners are excluded by the
-        // parameter type (the D3 philosophy); resolveListElement mirrors that
-        // type-state for JS consumers (the RL1 ethos). Nesting is detected
+        // parameter type (the same type-state philosophy); resolveListElement
+        // mirrors that type-state for JS consumers. Nesting is detected
         // structurally via ~element (never via ~kind, which is reflection-only
-        // and free-form for p.custom labels). Comma-emitting p.custom inners
-        // are undetectable here and are caught by the CV4 serialize guard
-        // instead.
+        // and free-form for p.custom labels). Comma-emitting p.custom inners are
+        // undetectable here and are caught by the CV4 serialize guard instead.
         const inner = resolveListElement(element, "p.csv");
         // The shared guard ran first: p.array also carries ~element (PP1), and
         // the arity guard owns the "array codecs" wording — the ~element guard
@@ -213,7 +216,7 @@ export const p = {
                     // CV3: strict grammar — "a,,b", trailing "a,", and a lone "," are
                     // ParseErrors, recoverable via the LIST's .catch() (D2).
                     if (segment === "") {
-                        throw new ParseError(`"${raw}" contains an empty list element`);
+                        throw grammarParseError(`"${raw}" contains an empty list element`);
                     }
                     // CV3: the first element failure aborts the list parse — the
                     // element codec's own ParseError propagates unwrapped.
@@ -262,7 +265,11 @@ export const p = {
         // rebrandForeign normalizes to ParseError so recovery sees them.
         return createCodec({
             ...(codec.label === undefined ? {} : { kind: codec.label }),
-            parseElement: (raw) => rebrandForeign(() => codec.parse(raw), (error) => new ParseError(foreignMessage(error), { cause: error })),
+            parseElement: (raw) => rebrandForeign(() => codec.parse(raw), 
+            // Not grammarParseError: foreign prose may name neither the value
+            // nor the grammar, so decode issues classify it "validate" and
+            // renderers append the expected shape themselves.
+            (error) => new ParseError(foreignMessage(error), { cause: error })),
             serializeElement: (value) => rebrandForeign(() => codec.serialize(value), (error) => new SerializeError(foreignMessage(error), { cause: error })),
         });
     },
@@ -273,7 +280,7 @@ export const p = {
             kind: "enum",
             parseElement: (raw) => {
                 if (!set.has(raw)) {
-                    throw new ParseError(`"${raw}" is not one of: ${members.join(", ")}`);
+                    throw grammarParseError(`"${raw}" is not one of: ${members.join(", ")}`);
                 }
                 return raw;
             },
@@ -287,13 +294,14 @@ export const p = {
     },
     /**
      * A 1-based-on-wire / 0-based-in-memory integer for pagination-style
-     * params (`?page=1` ↔ index 0, design-13 PP5). Deliberately stricter than
-     * nuqs's `parseAsIndex`, whose below-floor behavior is unspecified: wire
-     * values below 1 are a ParseError (recoverable via `.catch()`, like any
-     * other malformed input), and a negative in-memory index — which cannot
+     * params (`?page=1` ↔ index 0, PP5). Deliberately stricter than nuqs's
+     * `parseAsIndex`, whose below-floor behavior is unspecified: wire values
+     * below 1 are a ParseError (recoverable via `.catch()`, like any other
+     * malformed input), and a negative in-memory index — which cannot
      * round-trip through the 1-based wire floor — is a SerializeError at
-     * link-build time (the RL1 ethos). The optional schema validates the
-     * in-memory (0-based) value on both sides.
+     * link-build time, failing where the link is written rather than on the
+     * next navigation. The optional schema validates the in-memory (0-based)
+     * value on both sides.
      */
     index(schema) {
         return createCodec({
@@ -301,7 +309,7 @@ export const p = {
             parseElement: (raw) => {
                 const wire = parseIntegerElement(raw);
                 if (wire < 1) {
-                    throw new ParseError(`"${raw}" is below the 1-based wire floor of 1`);
+                    throw grammarParseError(`"${raw}" is below the 1-based wire floor of 1`);
                 }
                 const value = wire - 1;
                 return schema ? refine(schema, value) : value;
@@ -334,7 +342,7 @@ export const p = {
             kind: "isoDate",
             parseElement: (raw) => {
                 if (!ISO_DATE_RE.test(raw)) {
-                    throw new ParseError(`"${raw}" is not a YYYY-MM-DD date`);
+                    throw grammarParseError(`"${raw}" is not a YYYY-MM-DD date`);
                 }
                 // ISO-string construction, not Date.UTC: the latter maps years 0-99
                 // to 1900+year. The round-trip comparison rejects days the engine
@@ -342,7 +350,7 @@ export const p = {
                 const date = new Date(`${raw}T00:00:00.000Z`);
                 if (Number.isNaN(date.getTime()) ||
                     date.toISOString().slice(0, 10) !== raw) {
-                    throw new ParseError(`"${raw}" is not a real calendar date`);
+                    throw grammarParseError(`"${raw}" is not a real calendar date`);
                 }
                 return date;
             },
@@ -358,7 +366,7 @@ export const p = {
                     parsed = JSON.parse(raw);
                 }
                 catch {
-                    throw new ParseError(`"${raw}" is not valid JSON`);
+                    throw grammarParseError(`"${raw}" is not valid JSON`);
                 }
                 return refine(schema, parsed);
             },
@@ -402,18 +410,18 @@ export const p = {
             kind: "timestamp",
             parseElement: (raw) => {
                 if (!TIMESTAMP_RE.test(raw)) {
-                    throw new ParseError(`"${raw}" is not an ISO 8601 UTC timestamp`);
+                    throw grammarParseError(`"${raw}" is not an ISO 8601 UTC timestamp`);
                 }
                 const date = new Date(raw);
                 if (Number.isNaN(date.getTime())) {
-                    throw new ParseError(`"${raw}" is not a real instant`);
+                    throw grammarParseError(`"${raw}" is not a real instant`);
                 }
                 // The engine silently normalizes impossible fields (Feb 30 → Mar 1,
                 // 24:00 → next day). Pad the input to canonical millisecond form and
                 // require an exact round-trip instead.
                 const canonical = raw.replace(/(?:\.(\d{1,3}))?Z$/, (_match, ms) => `.${(ms ?? "").padEnd(3, "0")}Z`);
                 if (date.toISOString() !== canonical) {
-                    throw new ParseError(`"${raw}" is not a real instant`);
+                    throw grammarParseError(`"${raw}" is not a real instant`);
                 }
                 return date;
             },

package/dist/path.d.ts

@@ -15,11 +15,11 @@ export interface DecodeParamsOptions {
     readonly percentDecode?: boolean;
 }
 /**
- * Encode-input side of a route's params (RL3's href-input column): `[id]` →
+ * Encode-input side of a route's params (the href-input column): `[id]` →
  * `Out` (required), `[...slug]` → `Out[]` (required — `[]` is an R3
- * serialization error), `[[...slug]]` → `Out[]` with an OPTIONAL key, per
- * the spike-01 follow-up under exactOptionalPropertyTypes. Module-level
- * export only; Block 3's `InferHrefInput` builds on it.
+ * serialization error), `[[...slug]]` → `Out[]` with an OPTIONAL key under
+ * exactOptionalPropertyTypes. Module-level export only; `InferHrefInput`
+ * builds on it.
  */
 export type InferParamsInput<R extends AnyRoute> = {
     [K in CatchAllNames<R["path"]>]: ParamOutput<R["~params"], K>[];
@@ -38,7 +38,7 @@ export type InferParamsInput<R extends AnyRoute> = {
  */
 export type InferStaticParams<R extends AnyRoute> = Partial<Record<OptionalCatchAllNames<R["path"]>, string[]>> & Record<CatchAllNames<R["path"]>, string[]> & Record<SingleParamNames<R["path"]>, string>;
 /**
- * Value-layer params source (wire spec §1, R5): the shape of Next's `params`
+ * Value-layer params source (R5): the shape of Next's `params`
  * prop and `useParams()` return. Contrary to the byte-layer's usual "platform
  * already decoded it" stance, Next hands the App-Router surfaces percent-ENCODED
  * values (Next issues #48058/#64952 — only route.ts handlers decode), so core
@@ -57,14 +57,14 @@ export type PathSegment = {
     readonly raw: string;
 };
 /**
- * Builds the path portion of an href (RL5): `/` plus the encoded segments
+ * Builds the path portion of an href: `/` plus the encoded segments
  * joined with `/`. R2's element joining falls out of the same join as
  * everything else; a fully-elided path (an optional catch-all at the root)
  * yields "/".
  */
 export declare function buildPath<R extends AnyRoute>(route: R, params: InferParamsInput<R>): string;
 /**
- * Decodes a params source against a route's codecs (RL7), the sync twin of
+ * Decodes a params source against a route's codecs, the sync twin of
  * `route.parseParams` — mirrors decodeSearch: per-key {@link Issue}
  * aggregation into {@link ParamsDecodeError}. Shape validation is strict:
  * `[id]` given an array, a catch-all given a string, a missing required key,
@@ -76,33 +76,33 @@ export declare function buildPath<R extends AnyRoute>(route: R, params: InferPar
 export declare function decodeParams<R extends AnyRoute>(route: R, source: ParamsSource, options?: DecodeParamsOptions): InferRouteParams<R>;
 /**
  * Encodes a params input into ordered, already-percent-encoded URL segment
- * strings (RL5) — ONE entry per emitted URL segment: a static segment is
- * emitted verbatim, a single param contributes one entry (R1), a catch-all
- * one per element (R2), an elided optional catch-all none (R3). Codec
- * serialize errors and schema-refinement failures (N9) propagate unchanged,
- * already branded at their own chokepoints.
+ * strings — ONE entry per emitted URL segment: a static segment is emitted
+ * verbatim, a single param contributes one entry (R1), a catch-all one per
+ * element (R2), an elided optional catch-all none (R3). Codec serialize
+ * errors and schema-refinement failures propagate unchanged, already branded
+ * at their own chokepoints.
  */
 export declare function encodeParams<R extends AnyRoute>(route: R, params: InferParamsInput<R>): string[];
 /**
  * Encodes a params input into the per-param wire-value record the static
  * generation surfaces expect: App Router `generateStaticParams` entries and
- * Pages Router `getStaticPaths` `{ params }` objects (PR10's static story).
- * Same codec serialization and R1–R4 validation as {@link encodeParams},
- * with two deliberate differences: static segments are skipped (Next wants
- * only the dynamic params, keyed by name), and values are NOT percent-encoded
- * — Next percent-encodes static-params values itself when it materializes
- * the concrete URLs, so pre-encoding here would double-encode (the
- * encode-side mirror of R5's decode asymmetry). That also means the S7
- * lone-surrogate brand stays an encodeParams concern: strings are handed to
- * Next verbatim. An elided optional catch-all (R3) OMITS its key — an absent
- * key is the base-path variant on both routers (Pages also accepts
- * undefined/[]; omission is the one spelling valid on both).
+ * Pages Router `getStaticPaths` `{ params }` objects. Same codec
+ * serialization and R1–R4 validation as {@link encodeParams}, with two
+ * deliberate differences: static segments are skipped (Next wants only the
+ * dynamic params, keyed by name), and values are NOT percent-encoded — Next
+ * percent-encodes static-params values itself when it materializes the
+ * concrete URLs, so pre-encoding here would double-encode (the encode-side
+ * mirror of R5's decode asymmetry). That also means the S7 lone-surrogate
+ * brand stays an encodeParams concern: strings are handed to Next verbatim.
+ * An elided optional catch-all (R3) OMITS its key — an absent key is the
+ * base-path variant on both routers (Pages also accepts undefined/[];
+ * omission is the one spelling valid on both).
  */
 export declare function encodeStaticParams<R extends AnyRoute>(route: R, params: InferParamsInput<R>): InferStaticParams<R>;
 /**
  * Tokenizes a path literal into segments, throwing ParamourError on every
- * RL1 rejection. Shared by the route constructors (define-time validation)
- * and the R-rule runtime here, so encode/decode never re-derive segment
- * kinds.
+ * rejected literal. Shared by the route constructors (define-time
+ * validation) and the R-rule runtime here, so encode/decode never re-derive
+ * segment kinds.
  */
 export declare function tokenizePath(path: string): PathSegment[];