paramour 0.3.0 → 0.4.0

package/dist/codec.d.ts

@@ -66,8 +66,8 @@ export interface Codec<Out, P extends Presence = "required", C extends boolean =
     /** Stored as a thunk regardless of the form passed to `.default()`. */
     readonly "~defaultValue": (() => Out) | undefined;
     /**
-     * Element codec of a composite list codec (currently `p.csv`) — the
-     * per-segment scalar; undefined for every non-composite kind (CV6).
+     * Element codec of a composite list codec (`p.csv`, `p.array`) — the
+     * per-segment/per-key scalar; undefined for every non-composite kind (CV6).
      */
     readonly "~element": AnyCodec | undefined;
     /** Members of a `p.enum` codec; undefined for every other kind. */

package/dist/describe.d.ts

@@ -24,7 +24,7 @@ export interface CodecDescription {
     readonly defaultValue?: CodecDefaultDescription;
     /**
      * Nested description of a composite list codec's element scalar (CV6;
-     * currently `p.csv`).
+     * `p.csv` and `p.array`).
      */
     readonly element?: CodecDescription;
     readonly enumMembers?: readonly string[];

package/dist/describe.js

@@ -10,8 +10,9 @@ export function describeCodec(codec) {
         arity: codec["~arity"],
         caught: codec["~caught"],
         ...(defaultValue === undefined ? {} : { defaultValue }),
-        // Recursion terminates: nested csv is rejected at construction (CV2),
-        // and element codecs are unmodified scalars with no element of their own.
+        // Recursion terminates: composite nesting is bounded at construction —
+        // csv rejects nested csv (CV2) and array rejects arity-many inners
+        // (PP1), so the deepest legal chain is array<csv<scalar>>.
         ...(element === undefined ? {} : { element: describeCodec(element) }),
         ...(enumMembers === undefined ? {} : { enumMembers }),
         kind: codec["~kind"],
@@ -63,11 +64,22 @@ export function formatCodecDescription(description, style) {
     const kindLabel = (part) => part.enumMembers === undefined
         ? part.kind
         : `enum(${part.enumMembers.join(memberSeparator)})`;
-    let label = description.element === undefined
-        ? kindLabel(description)
-        : `${description.kind}<${kindLabel(description.element)}>`;
-    if (description.arity === "many")
-        label += "[]";
+    // Composite labels: a one-key list wraps its element (`csv<integer>`); a
+    // repeated-key list IS its element, pluralized (`integer[]`) — the
+    // "array" kind never appears in a label, the `[]` carries it. The elision
+    // keys on the kind, NOT arity: consumers force arity "many" onto
+    // non-array descriptions (render.ts's catch-all params), where a csv
+    // wrapper must survive as `csv<integer>[]`. Recursive so `array<csv<E>>`
+    // renders `csv<E>[]`.
+    const shapeLabel = (part) => {
+        const base = part.element === undefined
+            ? kindLabel(part)
+            : part.kind === "array"
+                ? shapeLabel(part.element)
+                : `${part.kind}<${shapeLabel(part.element)}>`;
+        return part.arity === "many" ? `${base}[]` : base;
+    };
+    let label = shapeLabel(description);
     if (style === "compact") {
         if (description.presence === "optional")
             label += "?";

package/dist/p.d.ts

@@ -5,10 +5,17 @@ import { type Codec } from "./codec.js";
  * Each codec defines how one value crosses the URL boundary, both directions.
  */
 export declare const p: {
+    /**
+     * A repeated-key list (`?tags=a&tags=b`, design-13 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.
+     */
+    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
-     * "single", so the full modifier set applies — unlike `p.stringArray`'s
+     * "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.
      */
@@ -20,11 +27,21 @@ export declare const p: {
         serialize: (value: Out) => string;
     }): Codec<Out>;
     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
+     * 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.
+     */
+    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>>;
     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

@@ -73,12 +73,46 @@ function refineForSerialize(schema, value) {
     }
     return result.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
+ * keeps that runtime mirror of the type-state in a single place.
+ */
+function resolveListElement(element, builder) {
+    const inner = element ?? (defaultListElement ??= p.string());
+    if (inner["~arity"] === "many" ||
+        inner["~caught"] ||
+        inner["~presence"] !== "required") {
+        throw new ParamourError(`${builder}() elements cannot carry modifiers (.optional()/.default()/.catch()) or be array codecs`);
+    }
+    return inner;
+}
 function serializeFiniteNumber(value) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
         throw new SerializeError(`Expected a finite number, got ${showValue(value)}`);
     }
     return String(value);
 }
+/**
+ * Serialize-side twin of {@link parseIntegerElement}, shared by `p.integer`
+ * and `p.index`: schema refinement plus the finite and safe-integer guards.
+ * Returns the refined NUMBER — `p.integer` stringifies it as-is, `p.index`
+ * shifts it into the 1-based wire form first — so the happy path pays no
+ * throwaway stringification.
+ */
+function serializeIntegerElement(schema, value) {
+    const refined = schema ? refineForSerialize(schema, value) : value;
+    if (typeof refined !== "number" || !Number.isFinite(refined)) {
+        throw new SerializeError(`Expected a finite number, got ${showValue(refined)}`);
+    }
+    if (!Number.isSafeInteger(refined)) {
+        throw new SerializeError(`${String(refined)} is not a safe integer`);
+    }
+    return refined;
+}
 /**
  * JSON.stringify throws raw TypeErrors (circular refs, BigInt) and lets
  * toJSON() exceptions escape; wrap them so the ParamourError contract holds.
@@ -87,16 +121,43 @@ function stringifyJson(value) {
     return rebrandForeign(() => JSON.stringify(value), (error) => new SerializeError("Value is not JSON-serializable", { cause: error }));
 }
 /**
- * Shared element for no-arg `p.csv()` — codecs are immutable, so one
- * schemaless string codec serves every list. Lazily built: `p` does not
+ * Shared element for no-arg `p.csv()`/`p.array()` — codecs are immutable, so
+ * one schemaless string codec serves every list. Lazily built: `p` does not
  * exist yet while the module initializes.
  */
-let defaultCsvElement;
+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.
  */
 export const p = {
+    /**
+     * A repeated-key list (`?tags=a&tags=b`, design-13 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.
+     */
+    array(element) {
+        // PP1: same element-by-composition shape as p.csv (CV2) — presence,
+        // catch, and arity-many inners are excluded by the parameter type;
+        // resolveListElement mirrors that type-state for JS consumers. Unlike
+        // csv there is no nested-composite special case: a csv element is a
+        // legal whole-value scalar per repeated key (?m=a,b&m=c,d), and
+        // repeated-key values have no separator for element serializations to
+        // collide with, so no CV4 twin is needed either.
+        const inner = resolveListElement(element, "p.array");
+        // The element functions already have the arity-"many" per-element
+        // contract (one wire value per array item), so they pass through as-is;
+        // the string-return contract on custom serializers is enforced at the
+        // search.ts/path.ts call sites, same as using the element directly.
+        return createCodec({
+            arity: "many",
+            element: inner,
+            kind: "array",
+            parseElement: inner["~parseElement"],
+            serializeElement: inner["~serializeElement"],
+        });
+    },
     boolean() {
         return createCodec({
             kind: "boolean",
@@ -117,28 +178,26 @@ export const p = {
     },
     /**
      * A comma-separated scalar list in ONE wire value (design-11 CV1): arity
-     * "single", so the full modifier set applies — unlike `p.stringArray`'s
+     * "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); these guards mirror that
-        // type-state for JS consumers (the RL1 ethos) — only the element
-        // functions are captured below, so an accepted modifier would be
-        // silently dropped, not applied. 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.
-        const inner = element ?? (defaultCsvElement ??= p.string());
+        // parameter type (the D3 philosophy); resolveListElement mirrors that
+        // type-state for JS consumers (the RL1 ethos). 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.
+        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
+        // here is then specifically the nested-csv (arity-"single" composite)
+        // case.
         if (inner["~element"] !== undefined) {
             throw new ParamourError("p.csv() elements cannot themselves be csv lists");
         }
-        if (inner["~arity"] === "many" ||
-            inner["~caught"] ||
-            inner["~presence"] !== "required") {
-            throw new ParamourError("p.csv() elements cannot carry modifiers (.optional()/.default()/.catch()) or be array codecs");
-        }
         const parseInner = inner["~parseElement"];
         const serializeInner = inner["~serializeElement"];
         return createCodec({
@@ -226,21 +285,48 @@ export const p = {
             },
         });
     },
-    integer(schema) {
+    /**
+     * 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
+     * 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.
+     */
+    index(schema) {
         return createCodec({
-            kind: "integer",
+            kind: "index",
             parseElement: (raw) => {
-                const value = parseIntegerElement(raw);
+                const wire = parseIntegerElement(raw);
+                if (wire < 1) {
+                    throw new ParseError(`"${raw}" is below the 1-based wire floor of 1`);
+                }
+                const value = wire - 1;
                 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`);
+                const index = serializeIntegerElement(schema, value);
+                if (index < 0) {
+                    throw new SerializeError(`${String(index)} is negative and cannot round-trip through the 1-based wire form`);
                 }
-                return serialized;
+                const wire = index + 1;
+                if (!Number.isSafeInteger(wire)) {
+                    throw new SerializeError(`${String(index)} is outside the 1-based wire form's safe integer range`);
+                }
+                return String(wire);
+            },
+        });
+    },
+    integer(schema) {
+        return createCodec({
+            kind: "integer",
+            parseElement: (raw) => {
+                const value = parseIntegerElement(raw);
+                return schema ? refine(schema, value) : value;
             },
+            serializeElement: (value) => String(serializeIntegerElement(schema, value)),
         });
     },
     isoDate() {
@@ -311,19 +397,6 @@ export const p = {
             },
         });
     },
-    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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paramour",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {