paramour 0.0.0 → 0.2.0

package/dist/standard-schema.js

@@ -0,0 +1,77 @@
+import { SearchSourceError } from "./errors.js";
+import { safeDecodeSearch } from "./safe-decode.js";
+import { isRawSearch, requireSearchConfig, } from "./search.js";
+/**
+ * Exports a route's `search:` config as the URL wire contract in Standard
+ * Schema form (design-08 STD1/STD5), for consumers like tRPC inputs or
+ * TanStack `validateSearch`. Semantics are byte-identical to `decodeSearch`
+ * (STD6): defaults apply, `.catch()` recovers parse failures — invalid API
+ * input silently coerces to the fallback — unknown keys strip (P8), and
+ * duplicate values on a scalar codec reject (P5). No coercion, ever (STD2):
+ * the schema accepts wire strings (`"42"`), not decoded values (`42`).
+ */
+export function standardSearchSchema(route) {
+    const config = route["~search"];
+    // A missing/malformed config is a programming error and stays loud (STD7);
+    // checking eagerly fails at construction, not at first validate().
+    requireSearchConfig(config);
+    // A config's raw/codec-map shape is fixed at construction; hoisted so the
+    // sentinel un-mapping below never touches a codec map's keyed issues.
+    const raw = isRawSearch(config);
+    return {
+        "~standard": {
+            validate: (value) => {
+                try {
+                    const result = safeDecodeSearch(route, value);
+                    if (result.status === "error") {
+                        return {
+                            issues: result.error.issues.map((issue) => toStandardIssue(issue, raw)),
+                        };
+                    }
+                    return { value: result.data };
+                }
+                catch (error) {
+                    // STD7: validate() receives genuinely untrusted input, so the
+                    // source-shape contract the read layer enforces with loud throws
+                    // softens to issues at this one boundary — SearchSourceError exists
+                    // as its own branded class exactly so this catch can't swallow
+                    // config-contract violations or rebranded validator throws.
+                    if (error instanceof SearchSourceError) {
+                        return { issues: [toSourceIssue(error)] };
+                    }
+                    // Async raw schema (design-02 D7), throwing raw validators, and
+                    // throwing .default()/.catch() factories are true programming
+                    // errors: loud (STD7).
+                    throw error;
+                }
+            },
+            vendor: "paramour",
+            version: 1,
+        },
+    };
+}
+/**
+ * Maps a source-shape violation to spec shape (STD7): keyed where the read
+ * layer could attribute it, root-level (absent path) for a malformed source.
+ */
+function toSourceIssue(error) {
+    return error.key === null
+        ? { message: error.message }
+        : { message: error.message, path: [error.key] };
+}
+/**
+ * Maps a decode issue to spec shape. decodeRawSearch collapses a root-level
+ * schema issue to the "<search>" sentinel key (SS3/SS4); a Standard Schema
+ * expresses "root" as an ABSENT path, so the sentinel un-maps here (STD7
+ * "root-level otherwise") — for raw configs only, since a codec map's issues
+ * are always keyed and a param may literally be named "<search>". (A raw
+ * vendor issue whose real path is ["<search>"] still collides with the
+ * sentinel — indistinguishable after the flat-key collapse.) Nested
+ * raw-schema paths were already dot-joined into the key and re-emit as ONE
+ * segment — keys may contain dots, so splitting back would be unsound.
+ */
+function toStandardIssue(issue, raw) {
+    return raw && issue.key === "<search>"
+        ? { message: issue.message }
+        : { message: issue.message, path: [issue.key] };
+}

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "paramour",
-  "version": "0.0.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. Placeholder release — under active development.",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "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",
     "app-router",
@@ -16,11 +27,24 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/JasonPaff/paramour.git"
+    "url": "git+https://github.com/JasonPaff/paramour.git",
+    "directory": "packages/core"
   },
   "homepage": "https://github.com/JasonPaff/paramour#readme",
   "bugs": {
     "url": "https://github.com/JasonPaff/paramour/issues"
   },
-  "files": []
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "arktype": "^2.2.3",
+    "fast-check": "^4.8.0",
+    "valibot": "^1.4.2",
+    "zod": "^4.4.3"
+  }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Jason Paff
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,28 +0,0 @@
-# paramour
-
-> *paramour* — "param" + "amour": a library that loves your params.
-
-A fully type-safe routing companion for the Next.js App Router: validated, typed
-route params and search params, type-checked path building, and a predictable,
-human-readable URL wire format — with your choice of validation library via
-[Standard Schema](https://github.com/standard-schema/standard-schema).
-
-## Status
-
-**This is a name-reservation placeholder.** The library is under active design
-and development — nothing here is usable yet.
-
-- Design document and progress: [github.com/JasonPaff/paramour](https://github.com/JasonPaff/paramour)
-- Companion packages will live under the [`@paramour-js`](https://www.npmjs.com/org/paramour-js) scope.
-
-## Why
-
-Born from lessons learned maintaining and contributing to
-[`next-typesafe-url`](https://www.npmjs.com/package/next-typesafe-url), which is
-effectively unmaintained. Paramour aims to be a documented, tested,
-community-maintained answer to typed routing in Next.js, with a migration path
-from `next-typesafe-url`.
-
-## License
-
-MIT © Jason Paff