paramour 0.4.0 → 0.5.1

package/README.md

@@ -0,0 +1,44 @@
+# paramour
+
+Type-safe routing companion for the Next.js App Router: validated, typed
+route and search params, type-checked path building, and a predictable,
+human-readable URL wire format. Validation is bring-your-own via
+[Standard Schema](https://github.com/standard-schema/standard-schema) —
+paramour owns serialization (the part validators can't do), your validator
+owns the rules.
+
+```sh
+pnpm add paramour @paramour-js/next
+```
+
+```ts
+import { defineAppRoute, href, p } from "paramour";
+
+export const productRoute = defineAppRoute("/product/[id]", {
+  params: { id: p.integer() },
+  search: { q: p.string().optional() },
+});
+
+// typed, validated, explicit: "/product/42?q=paramour"
+href(productRoute, { params: { id: 42 }, search: { q: "paramour" } });
+
+// a string into p.integer() fails to compile
+href(productRoute, { params: { id: "42" } });
+```
+
+Routes are plain imported objects — no central registry, nothing to
+tree-shake around. Codecs are bidirectional wire converters with a
+type-state modifier API (`.optional()`, `.default()`, `.catch()`) where
+illegal chains fail to compile, and every codec serializes by a
+[published, numbered spec](https://paramour.dev/docs/reference/wire-format).
+
+## Docs
+
+- [Getting started](https://paramour.dev/docs/getting-started)
+- [Core API reference](https://paramour.dev/docs/reference/core)
+- [Wire-format spec & explorer](https://paramour.dev/docs/reference/wire-format)
+- [Migrating from next-typesafe-url](https://paramour.dev/docs/migrate)
+
+## License
+
+MIT © Jason Paff

package/dist/errors.d.ts

@@ -57,9 +57,10 @@ export declare function describeType(value: unknown): string;
  * Best-effort human-readable message for a foreign (non-paramour) throw:
  * an `Error`'s message, else a {@link showValue}-hardened `String()` — safe
  * even for values whose primitive conversion itself throws (null-prototype
- * objects, `Symbol.toPrimitive` throwers). Public via the barrel so derived
- * tooling that catches user-code throws (the devtools panel's edit preview)
- * shares the hardening instead of re-implementing it minus the guard.
+ * objects, `Symbol.toPrimitive` throwers). Public via `paramour/internal` so
+ * derived tooling that catches user-code throws (the devtools panel's edit
+ * preview) shares the hardening instead of re-implementing it minus the
+ * guard.
  */
 export declare function foreignMessage(error: unknown): string;
 /**

package/dist/errors.js

@@ -110,9 +110,10 @@ export function describeType(value) {
  * Best-effort human-readable message for a foreign (non-paramour) throw:
  * an `Error`'s message, else a {@link showValue}-hardened `String()` — safe
  * even for values whose primitive conversion itself throws (null-prototype
- * objects, `Symbol.toPrimitive` throwers). Public via the barrel so derived
- * tooling that catches user-code throws (the devtools panel's edit preview)
- * shares the hardening instead of re-implementing it minus the guard.
+ * objects, `Symbol.toPrimitive` throwers). Public via `paramour/internal` so
+ * derived tooling that catches user-code throws (the devtools panel's edit
+ * preview) shares the hardening instead of re-implementing it minus the
+ * guard.
  */
 export function foreignMessage(error) {
     return error instanceof Error ? error.message : showValue(error);

package/dist/index.d.ts

@@ -1,10 +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, type CodecFormatStyle, describeCodec, describeRoute, formatCodecDescription, type ParamDescription, type RouteDescription, type SearchDescription, } from "./describe.js";
-export { foreignMessage, type Issue, ParamourError, ParamsDecodeError, ParseError, type RouteDecodeError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.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 { type AnyAppRoute, type AnyPagesRoute, type AnyRoute, type AppRoute, defineAppRoute, definePagesRoute, type InferRouteParams, type PagesContext, type PagesRoute, type ParamourRegister, type ParamsConfig, type ParamsProps, type ParamsPropsInput, type RegisteredAppRoutePaths, type RegisteredPagesRoutePaths, type RegisteredStaticAppRoutePaths, type RegisteredStaticPagesRoutePaths, type RegisteredStaticRoutePaths, type Route, type RouteProps, type RoutePropsInput, type RouterKind, type SafeResult, type SearchProps, type SearchPropsInput, } from "./route.js";
 export { safeDecodeParams, safeDecodeSearch } from "./safe-decode.js";
-export { buildSearchString, decodeSearch, encodeSearch, type InferSearchInput, type InferSearchOutput, isRawSearch, parseValue, rawSearch, type RawSearch, type SearchConfig, type SearchOutputOf, type SearchSource, searchToString, serializeValue, } from "./search.js";
+export { buildSearchString, decodeSearch, encodeSearch, type InferSearchInput, type InferSearchOutput, isRawSearch, rawSearch, type RawSearch, type SearchConfig, type SearchOutputOf, type SearchSource, searchToString, serializeValue, } from "./search.js";
 export { standardSearchSchema, type StandardSearchSchema, } from "./standard-schema.js";

package/dist/index.js

@@ -1,10 +1,10 @@
 export {} from "./codec.js";
 export { describeCodec, describeRoute, formatCodecDescription, } from "./describe.js";
-export { foreignMessage, ParamourError, ParamsDecodeError, ParseError, SearchDecodeError, SearchSourceError, SerializeError, } from "./errors.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, isRawSearch, parseValue, rawSearch, searchToString, serializeValue, } from "./search.js";
+export { buildSearchString, decodeSearch, encodeSearch, isRawSearch, rawSearch, searchToString, serializeValue, } from "./search.js";
 export { standardSearchSchema, } from "./standard-schema.js";

package/dist/internal.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `paramour/internal` entry: unstable helpers for derived tooling
+ * (devtools, adapters), NOT for app authors and NOT covered by the public
+ * API's stability expectations. These live off the main barrel on purpose —
+ * the docs' Reference section documents the app-author surface, and these
+ * two exist solely so reflection-driven consumers (the devtools panel's
+ * catch-attribution probe and edit preview, design-12 DT7) share core's
+ * implementation instead of re-deriving it.
+ */
+export { foreignMessage } from "./errors.js";
+export { parseValue } from "./search.js";

package/dist/internal.js

@@ -0,0 +1,11 @@
+/**
+ * The `paramour/internal` entry: unstable helpers for derived tooling
+ * (devtools, adapters), NOT for app authors and NOT covered by the public
+ * API's stability expectations. These live off the main barrel on purpose —
+ * the docs' Reference section documents the app-author surface, and these
+ * two exist solely so reflection-driven consumers (the devtools panel's
+ * catch-attribution probe and edit preview, design-12 DT7) share core's
+ * implementation instead of re-deriving it.
+ */
+export { foreignMessage } from "./errors.js";
+export { parseValue } from "./search.js";

package/dist/route.d.ts

@@ -27,20 +27,20 @@ export interface AppRoute<Path extends string, PC extends ParamsConfig<Path>, SC
      * FIRST — a params grammar failure means the URL doesn't denote this
      * route at all (morally a 404), so it throws before search is decoded.
      */
-    parse(props: RouteProps): Promise<{
+    parse(props: RoutePropsInput): Promise<{
         params: ParamsOutput<Path, PC>;
         search: SearchOutputOf<SC>;
     }>;
     /** Bare params object (RL6) — layout props are structurally assignable. */
-    parseParams(props: ParamsProps): Promise<ParamsOutput<Path, PC>>;
+    parseParams(props: ParamsPropsInput): Promise<ParamsOutput<Path, PC>>;
     /** Bare search object (RL6) — the search half alone. */
-    parseSearch(props: SearchProps): Promise<SearchOutputOf<SC>>;
-    safeParse(props: RouteProps): Promise<SafeResult<{
+    parseSearch(props: SearchPropsInput): Promise<SearchOutputOf<SC>>;
+    safeParse(props: RoutePropsInput): Promise<SafeResult<{
         params: ParamsOutput<Path, PC>;
         search: SearchOutputOf<SC>;
     }>>;
-    safeParseParams(props: ParamsProps): Promise<SafeResult<ParamsOutput<Path, PC>>>;
-    safeParseSearch(props: SearchProps): Promise<SafeResult<SearchOutputOf<SC>>>;
+    safeParseParams(props: ParamsPropsInput): Promise<SafeResult<ParamsOutput<Path, PC>>>;
+    safeParseSearch(props: SearchPropsInput): Promise<SafeResult<SearchOutputOf<SC>>>;
 }
 /** Names of `[...name]` catch-all segments in the path literal (RL3). */
 export type CatchAllNames<Path extends string> = Segments<Path> extends infer S extends string ? S extends `[...${infer Name}]` ? NonEmptyName<Name> : never : never;
@@ -52,7 +52,15 @@ export type CatchAllNames<Path extends string> = Segments<Path> extends infer S
 export type ConformParams<Path extends string, PC> = PC & Record<Exclude<keyof PC, PathParamNames<Path>>, never>;
 /** Decoded params object type for a route (RL3); see {@link ParamsOutput}. */
 export type InferRouteParams<R extends AnyRoute> = ParamsOutput<R["path"], R["~params"]>;
-/** Accepts Next 15/16's promised props and plain objects alike (RL6). */
+/**
+ * Accepts promised props and plain objects alike (RL6). This width lives on
+ * the parse INPUT surface ({@link RoutePropsInput} and friends), not on the
+ * annotation types: every supported Next (peer `>=15`) delivers page props
+ * as promises, and Next 15.5's generated `.next/types` page check requires
+ * a page's `params` prop to be `Promise<any> | undefined` — a sync arm in
+ * {@link RouteProps} fails `next build` there. Hand-built sync props (tests,
+ * server code calling `parse` directly) stay legal via the input types.
+ */
 export type MaybePromise<T> = Promise<T> | T;
 /**
  * RL3: an empty name (`[]`, `[...]`, `[[...]]`) is not a token — it falls
@@ -145,6 +153,14 @@ export type ParamsOutput<Path extends string, PC> = {
  * global doesn't exist in fresh clones before `next dev` first runs.
  */
 export interface ParamsProps {
+    readonly params?: Promise<ParamsSource>;
+}
+/**
+ * What `parseParams` ACCEPTS (RL6): {@link ParamsProps} plus plain sync
+ * objects — see {@link MaybePromise} for why the annotation type is
+ * promise-only while the parse input stays wide.
+ */
+export interface ParamsPropsInput {
     readonly params?: MaybePromise<ParamsSource>;
 }
 /** Every dynamic segment name in the path literal (RL3). */
@@ -218,9 +234,18 @@ export type RouteConfig<Path extends string, PC extends ParamsConfig<Path>, SC e
     readonly params: ConformParams<Path, PC>;
     readonly search?: SC;
 };
-/** Full page-props contract (RL6): Next's `PageProps` is structurally assignable. */
+/**
+ * Full page-props contract (RL6): the type a page annotates its props with.
+ * Next's `PageProps` is structurally assignable, and both members are
+ * promise-only so the annotation survives Next 15.5's generated page check
+ * (see {@link MaybePromise}). Deliberately NOT Next's generated `PageProps`
+ * global — core stays framework-agnostic.
+ */
 export interface RouteProps extends ParamsProps, SearchProps {
 }
+/** What `parse`/`safeParse` ACCEPT (RL6): {@link RouteProps} plus sync props. */
+export interface RoutePropsInput extends ParamsPropsInput, SearchPropsInput {
+}
 /** Which router a route belongs to (PR3) — the value of the `~router` brand. */
 export type RouterKind = "app" | "pages";
 /**
@@ -241,6 +266,10 @@ export type SafeResult<T> = {
  * shape is the same as the params side's, hence the shared source type.
  */
 export interface SearchProps {
+    readonly searchParams?: Promise<ParamsSource>;
+}
+/** Sync-accepting twin of {@link SearchProps} — see {@link ParamsPropsInput}. */
+export interface SearchPropsInput {
     readonly searchParams?: MaybePromise<ParamsSource>;
 }
 /**

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "paramour",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
     }
   },
+  "engines": {
+    "node": ">=22.13.0"
+  },
   "description": "Type-safe routing companion for the Next.js App Router: validated route params and search params, typed path building, and explicit URL serialization.",
   "keywords": [
     "nextjs",
@@ -26,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"
   },
@@ -49,6 +56,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "check:publish": "publint --strict && attw --pack . --profile esm-only",
     "typecheck": "tsc --noEmit"
   }
 }