paramour 0.0.0 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { type AnyCodec, type Arity, type Codec, type OutputOf, type ParamCodec, type Presence, type PresenceOf, } from "./codec.js";
+export { type CodecDefaultDescription, type CodecDescription, describeCodec, describeRoute, type ParamDescription, type RouteDescription, type SearchDescription, } from "./describe.js";
+export { type Issue, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+export { href, type Href, type HrefArgs, type InferHrefInput, type StaticHrefOptions, } from "./href.js";
+export { p } from "./p.js";
+export { buildPath, decodeParams, type DecodeParamsOptions, encodeParams, encodeStaticParams, type InferStaticParams, type ParamsSource, } from "./path.js";
+export { type AnyAppRoute, type AnyPagesRoute, type AnyRoute, type AppRoute, defineAppRoute, definePagesRoute, type InferRouteParams, type PagesContext, type PagesRoute, type ParamourRegister, type ParamsConfig, type ParamsProps, type RegisteredAppRoutePaths, type RegisteredPagesRoutePaths, type RegisteredStaticAppRoutePaths, type RegisteredStaticPagesRoutePaths, type RegisteredStaticRoutePaths, type Route, type RouteProps, type RouterKind, type SafeResult, type SearchProps, } from "./route.js";
+export { safeDecodeParams, safeDecodeSearch } from "./safe-decode.js";
+export { buildSearchString, decodeSearch, encodeSearch, type InferSearchInput, type InferSearchOutput, rawSearch, type RawSearch, type SearchConfig, type SearchOutputOf, type SearchSource, searchToString, } from "./search.js";
+export { standardSearchSchema, type StandardSearchSchema, } from "./standard-schema.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export {} from "./codec.js";
+export { describeCodec, describeRoute, } from "./describe.js";
+export { ParamourError, ParamsDecodeError, ParseError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.js";
+export { href, } from "./href.js";
+export { p } from "./p.js";
+export { buildPath, decodeParams, encodeParams, encodeStaticParams, } from "./path.js";
+export { defineAppRoute, definePagesRoute, } from "./route.js";
+export { safeDecodeParams, safeDecodeSearch } from "./safe-decode.js";
+export { buildSearchString, decodeSearch, encodeSearch, rawSearch, searchToString, } from "./search.js";
+export { standardSearchSchema, } from "./standard-schema.js";

package/dist/p.d.ts

@@ -0,0 +1,23 @@
+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.
+ */
+export declare const p: {
+    boolean(): Codec<boolean>;
+    custom<Out>(codec: {
+        /** Reflection name shown by describeCodec/`paramour list` (default "custom"). */
+        label?: string;
+        parse: (raw: string) => Out;
+        serialize: (value: Out) => string;
+    }): Codec<Out>;
+    enum<const M extends readonly [string, ...string[]]>(members: M): Codec<M[number]>;
+    integer<S extends StandardSchemaV1<number, number>>(schema?: S): Codec<S extends undefined ? number : StandardSchemaV1.InferOutput<S>>;
+    isoDate(): Codec<Date>;
+    json<S extends StandardSchemaV1>(schema: S): Codec<StandardSchemaV1.InferOutput<S>>;
+    number<S extends StandardSchemaV1<number, number>>(schema?: S): Codec<S extends undefined ? number : StandardSchemaV1.InferOutput<S>>;
+    string<S extends StandardSchemaV1<string, string>>(schema?: S): Codec<S extends undefined ? string : StandardSchemaV1.InferOutput<S>>;
+    stringArray(): Codec<string[], "required", false, "many">;
+    timestamp(): Codec<Date>;
+};

package/dist/p.js

@@ -0,0 +1,265 @@
+import { createCodec } from "./codec.js";
+import { foreignMessage, ParseError, rebrandForeign, SerializeError, showValue, } from "./errors.js";
+import { runStandardSchemaSync } from "./schema.js";
+// Wire grammars per wire-format spec §4. `Number()` alone is too loose
+// (accepts hex, trims whitespace), hence explicit anchored patterns.
+const INTEGER_RE = /^-?\d+$/;
+const NUMBER_RE = /^-?\d+(\.\d+)?([eE][+-]?\d+)?$/;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+// Canonical emit is Date#toISOString (milliseconds always); parse tolerates
+// missing milliseconds. UTC (`Z`) only — offsets are rejected in v0.1.
+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.
+ */
+function expectSerializableDate(value) {
+    if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+        throw new SerializeError("Expected a valid Date");
+    }
+    const year = value.getUTCFullYear();
+    if (year < 0 || year > 9999) {
+        throw new SerializeError(`Date year ${String(year)} is outside the representable 0000-9999 range`);
+    }
+    return value;
+}
+// Array.from, not .map: the issues array belongs to the validator and may be
+// an Array subclass whose Symbol.species constructor mangles a mapped result
+// (see the note in search.ts's decodeRawSearch).
+function joinIssues(issues) {
+    return Array.from(issues, (issue) => issue.message).join("; ");
+}
+function parseIntegerElement(raw) {
+    if (!INTEGER_RE.test(raw)) {
+        throw new ParseError(`"${raw}" is not an integer`);
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value)) {
+        throw new ParseError(`"${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`);
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new ParseError(`"${raw}" is not a finite number`);
+    }
+    return value;
+}
+function refine(schema, value) {
+    const result = runStandardSchemaSync(schema, value);
+    if (result.issues) {
+        throw new ParseError(`Schema validation failed: ${joinIssues(result.issues)}`);
+    }
+    return result.value;
+}
+/**
+ * Serialize-side twin of {@link refine}: schema-invalid in-memory values must
+ * fail loudly at link-build time, not on the next navigation. The schema's
+ * returned value is what goes on the wire, so normalizing schemas emit
+ * canonical form. Transforming (In≠Out) schemas are parse-only by design —
+ * their output fails input validation here; use `p.custom` for bidirectional
+ * transforms.
+ */
+function refineForSerialize(schema, value) {
+    const result = runStandardSchemaSync(schema, value);
+    if (result.issues) {
+        throw new SerializeError(`Schema validation failed: ${joinIssues(result.issues)}`);
+    }
+    return result.value;
+}
+function serializeFiniteNumber(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new SerializeError(`Expected a finite number, got ${showValue(value)}`);
+    }
+    return String(value);
+}
+/**
+ * JSON.stringify throws raw TypeErrors (circular refs, BigInt) and lets
+ * toJSON() exceptions escape; wrap them so the ParamourError contract holds.
+ */
+function stringifyJson(value) {
+    return rebrandForeign(() => JSON.stringify(value), (error) => new SerializeError("Value is not JSON-serializable", { cause: error }));
+}
+/**
+ * The `p.*` wire-codec builders (DESIGN §5 layer 1, design-02 D9).
+ * Each codec defines how one value crosses the URL boundary, both directions.
+ */
+export const p = {
+    boolean() {
+        return createCodec({
+            kind: "boolean",
+            parseElement: (raw) => {
+                if (raw === "true")
+                    return true;
+                if (raw === "false")
+                    return false;
+                throw new ParseError(`"${raw}" is not "true" or "false"`);
+            },
+            serializeElement: (value) => {
+                if (typeof value !== "boolean") {
+                    throw new SerializeError(`Expected a boolean, got ${showValue(value)}`);
+                }
+                return value ? "true" : "false";
+            },
+        });
+    },
+    custom(codec) {
+        // Paramour's own errors are never downgraded: ANY ParamourError thrown
+        // by user parse/serialize code — config-level failures (async schema,
+        // builder misuse) but also value-level errors from reused paramour
+        // helpers — passes through loud, bypassing .catch() recovery and per-key
+        // aggregation. .catch() recovers foreign parse failures only, which
+        // 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 })),
+            serializeElement: (value) => rebrandForeign(() => codec.serialize(value), (error) => new SerializeError(foreignMessage(error), { cause: error })),
+        });
+    },
+    enum(members) {
+        const set = new Set(members);
+        return createCodec({
+            enumMembers: members,
+            kind: "enum",
+            parseElement: (raw) => {
+                if (!set.has(raw)) {
+                    throw new ParseError(`"${raw}" is not one of: ${members.join(", ")}`);
+                }
+                return raw;
+            },
+            serializeElement: (value) => {
+                if (typeof value !== "string" || !set.has(value)) {
+                    throw new SerializeError(`${showValue(value)} is not one of: ${members.join(", ")}`);
+                }
+                return value;
+            },
+        });
+    },
+    integer(schema) {
+        return createCodec({
+            kind: "integer",
+            parseElement: (raw) => {
+                const value = parseIntegerElement(raw);
+                return schema ? refine(schema, value) : value;
+            },
+            serializeElement: (value) => {
+                const refined = schema ? refineForSerialize(schema, value) : value;
+                const serialized = serializeFiniteNumber(refined);
+                if (!Number.isSafeInteger(refined)) {
+                    throw new SerializeError(`${serialized} is not a safe integer`);
+                }
+                return serialized;
+            },
+        });
+    },
+    isoDate() {
+        return createCodec({
+            kind: "isoDate",
+            parseElement: (raw) => {
+                if (!ISO_DATE_RE.test(raw)) {
+                    throw new ParseError(`"${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
+                // would silently normalize (2026-02-30 → Mar 2).
+                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`);
+                }
+                return date;
+            },
+            serializeElement: (value) => expectSerializableDate(value).toISOString().slice(0, 10),
+        });
+    },
+    json(schema) {
+        return createCodec({
+            kind: "json",
+            parseElement: (raw) => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    throw new ParseError(`"${raw}" is not valid JSON`);
+                }
+                return refine(schema, parsed);
+            },
+            serializeElement: (value) => {
+                const refined = refineForSerialize(schema, value);
+                // lib.d.ts types JSON.stringify as always-string, but it returns
+                // undefined for undefined/function/symbol inputs.
+                const serialized = stringifyJson(refined);
+                if (serialized === undefined) {
+                    throw new SerializeError("Value is not JSON-serializable");
+                }
+                return serialized;
+            },
+        });
+    },
+    number(schema) {
+        return createCodec({
+            kind: "number",
+            parseElement: (raw) => {
+                const value = parseNumberElement(raw);
+                return schema ? refine(schema, value) : value;
+            },
+            serializeElement: (value) => serializeFiniteNumber(schema ? refineForSerialize(schema, value) : value),
+        });
+    },
+    string(schema) {
+        return createCodec({
+            kind: "string",
+            parseElement: (raw) => (schema ? refine(schema, raw) : raw),
+            serializeElement: (value) => {
+                const refined = schema ? refineForSerialize(schema, value) : value;
+                if (typeof refined !== "string") {
+                    throw new SerializeError("Expected a string");
+                }
+                return refined;
+            },
+        });
+    },
+    stringArray() {
+        return createCodec({
+            arity: "many",
+            kind: "string",
+            parseElement: (raw) => raw,
+            serializeElement: (value) => {
+                if (typeof value !== "string") {
+                    throw new SerializeError("Expected an array of strings");
+                }
+                return value;
+            },
+        });
+    },
+    timestamp() {
+        return createCodec({
+            kind: "timestamp",
+            parseElement: (raw) => {
+                if (!TIMESTAMP_RE.test(raw)) {
+                    throw new ParseError(`"${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`);
+                }
+                // 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`);
+                }
+                return date;
+            },
+            serializeElement: (value) => expectSerializableDate(value).toISOString(),
+        });
+    },
+};

package/dist/path.d.ts

@@ -0,0 +1,108 @@
+import type { AnyRoute, CatchAllNames, InferRouteParams, OptionalCatchAllNames, ParamOutput, SingleParamNames } from "./route.js";
+/**
+ * Decode-policy knob for {@link decodeParams} / {@link safeDecodeParams} (R5).
+ * `percentDecode` defaults to `true` — the App-Router reality, where Next
+ * hands the `params` prop / `useParams()` surface percent-ENCODED values
+ * (issues #48058/#64952), so core owns the decode. The pages surfaces are the
+ * exception: `useRouter().query` and `getServerSideProps` `ctx.params`/`query`
+ * have ALREADY been percent-decoded by Node's querystring layer, so those
+ * entry points pass `{ percentDecode: false }` to avoid a double-decode
+ * (`/product/a%2520b` → `"a%20b"` from Node → must survive, not decode again).
+ * Optional-with-default under `exactOptionalPropertyTypes`: absent or a plain
+ * `boolean`, never `undefined`.
+ */
+export interface DecodeParamsOptions {
+    readonly percentDecode?: boolean;
+}
+/**
+ * Encode-input side of a route's params (RL3's 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.
+ */
+export type InferParamsInput<R extends AnyRoute> = {
+    [K in CatchAllNames<R["path"]>]: ParamOutput<R["~params"], K>[];
+} & {
+    [K in OptionalCatchAllNames<R["path"]>]?: ParamOutput<R["~params"], K>[];
+} & {
+    [K in SingleParamNames<R["path"]>]: ParamOutput<R["~params"], K>;
+};
+/**
+ * Return shape of {@link encodeStaticParams}: the per-param wire-value record
+ * Next's static-generation surfaces expect — `[id]` → `string`, `[...slug]` →
+ * `string[]`, `[[...slug]]` → `string[]` with an OPTIONAL key (absent is the
+ * R3 base-path variant). Mapped types carry implicit index signatures, so the
+ * result is assignable to `generateStaticParams`' and `getStaticPaths`'
+ * params shapes without a cast.
+ */
+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`
+ * 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
+ * owns the decode in {@link decodeParams} before applying codec grammars. The
+ * pages surfaces are the exception (already Node-decoded); they opt out via
+ * {@link DecodeParamsOptions}'s `percentDecode: false`.
+ */
+export type ParamsSource = Record<string, string | string[] | undefined>;
+/** One parsed path segment, as produced by {@link tokenizePath}. */
+export type PathSegment = {
+    readonly kind: "catchall" | "optional-catchall" | "single";
+    readonly name: string;
+    readonly raw: string;
+} | {
+    readonly kind: "static";
+    readonly raw: string;
+};
+/**
+ * Builds the path portion of an href (RL5): `/` 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
+ * `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,
+ * or a non-string element are recorded issues, and NOT `.catch()`-recoverable
+ * — a shape mismatch means the props came from a route this definition
+ * doesn't describe. Unknown source keys are never read (P8's spirit; Next
+ * includes parent-layout params).
+ */
+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.
+ */
+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).
+ */
+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.
+ */
+export declare function tokenizePath(path: string): PathSegment[];