Add Standard Schema support (#67)

fenok · web-flow · commit 2c124d7aa1c9 · 2025-06-30T21:16:54.000+02:00
* Add support for Standard Schema

* Add deferred version

* Update CHANGELOG.md

* Add exports for standard-schema

* Fix import

* Ignore built standard-schema

* Exclude standard-schema directory

* Update README.md

* Rename standard schema spec file

* Update README.md

* Fix import
diff --git a/.eslintignore b/.eslintignore
@@ -1,4 +1,5 @@
 lib/*
+standard-schema/*
 zod/*
 yup/*
 src/**/*.cts
diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,7 @@
 
 # Compiled code
 lib/*
+standard-schema/*
 zod/*
 yup/*
 src/**/*.cts
diff --git a/.idea/react-router-typesafe-routes.iml b/.idea/react-router-typesafe-routes.iml
diff --git a/.pnp.cjs b/.pnp.cjs
diff --git a/.prettierignore b/.prettierignore
@@ -1,6 +1,7 @@
 .yarn/*
 .pnp.*
 lib/*
+standard-schema/*
 zod/*
 yup/*
 src/**/*.cts
diff --git a/.yarn/cache/zod-npm-3.20.6-d9ed055758-804b1934b8.zip b/.yarn/cache/zod-npm-3.20.6-d9ed055758-804b1934b8.zip
diff --git a/.yarn/cache/zod-npm-3.25.67-5734ab93c5-56ab904d33.zip b/.yarn/cache/zod-npm-3.25.67-5734ab93c5-56ab904d33.zip
diff --git a/.yarn/versions/f47e780a.yml b/.yarn/versions/f47e780a.yml
@@ -1,2 +1,2 @@
 releases:
-  react-router-typesafe-routes: patch
+  react-router-typesafe-routes: minor
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Add support for [Standard Schema](https://github.com/standard-schema/standard-schema).
+
 ## [2.0.0] - 2024-11-23
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,7 +7,7 @@
 
 All code changes have to be done via pull requests to `dev` branch.
 
-Every pull request have to specify a deferred version bump via [yarn version](https://yarnpkg.com/cli/version) like this:
+Every pull request has to specify a deferred version bump via [yarn version](https://yarnpkg.com/cli/version) like this:
 
 ```bash
 yarn version patch --deferred
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ Enhanced type safety via validation for all route params in React Router v7.
 
 The library provides type safety for all route params (pathname params, search params (including multiple keys), state, and hash) on building and parsing/validating URL parts and state. There are no unsafe type casts whatsoever.
 
-If you want, you can use a validation library. There is first-party support for [Zod](https://github.com/colinhacks/zod) and [Yup](https://github.com/jquense/yup), and other libraries can be integrated with ease. Otherwise, you can use other built-in types and fine-tune their validation instead.
+If you want, you can use a validation library. There is first-party support for [Standard Schema](https://github.com/standard-schema/standard-schema), [Zod (v3)](https://github.com/colinhacks/zod), and [Yup](https://github.com/jquense/yup), and other libraries can be integrated with ease. Otherwise, you can use other built-in types and fine-tune their validation instead.
 
 In built-in types, parsing and validation errors are caught and replaced with `undefined`. You can also return a default value or throw an error in case of an absent or invalid param. All these adjustments reflect in types, too!
 
@@ -25,7 +25,8 @@ Note that `react-router` and `react` are peer dependencies.
 
 There are optional entry points for types based on third-party validation libraries:
 
-- `react-router-typesafe-routes/zod` exports `zod` type, `zod` is a peer dependency;
+- `react-router-typesafe-routes/standard-schema` exports `schema` type that accepts any Standard Schema;
+- `react-router-typesafe-routes/zod` exports `zod` type (for Zod v3 only), `zod` is a peer dependency;
 - `react-router-typesafe-routes/yup` exports `yup` type, `yup` is a peer dependency;
 
 The library is targeting ES6 (ES2015).
@@ -395,7 +396,30 @@ const myRoute = route({
 
 </details>
 
-### Use Zod
+### Use Standard Schema
+
+<details>
+  <summary>Click to expand</summary>
+
+```tsx
+import { route, parser } from "react-router-typesafe-routes";
+import { schema } from "react-router-typesafe-routes/standard-schema";
+import { z } from "zod/v4"; // Zod v4 implements Standard Schema
+
+const myRoute = route({
+  path: ":id",
+  // There is no way to get the type hint from a Standard Schema in runtime, so we need to specify it explicitly.
+  // For the built-in parser, this is only necessary for strings and dates. It's also type-safe!
+  // It's needed for omitting wrapping quotes in serialized values.
+  params: { id: schema(z.string().uuid(), parser("string")) },
+});
+```
+
+> ❗Zod doesn't do coercion by default, but you may need it for complex values returned from `JSON.parse` (for instance, a date wrapped in an object).
+
+</details>
+
+### Use Zod v3
 
 <details>
   <summary>Click to expand</summary>
@@ -767,7 +791,7 @@ There is also somewhat specific `union()` helper that accepts an enum (or an enu
 
 ##### Third-party validation libraries
 
-If you can, you should use a validation library for all types. You can use Zod and Yup out of the box via the `zod()` and `yup()` helpers, and you should be able to integrate any third-party validation library via the `type()` helper. See [Advanced examples](#advanced-examples).
+If you can, you should use a validation library for all types. You can use Standard Schema, Zod v3, and Yup out of the box via the `schema()`, `zod()`, and `yup()` helpers, and you should be able to integrate any third-party validation library via the `type()` helper. See [Advanced examples](#advanced-examples).
 
 #### Type objects
 
@@ -992,7 +1016,8 @@ There are built-in helpers for common types:
 
 There are also built-in helpers for third-party validation libraries:
 
-- `zod()` - a wrapper around `type()` for creating type objects based on Zod Types. Uses a separate entry point: `react-router-typesafe-routes/zod`.
+- `schema()` - a wrapper around `type()` for creating type objects based on Standard Schemas. Uses a separate entry point: `react-router-typesafe-routes/standard-schema`.
+- `zod()` - a wrapper around `type()` for creating type objects based on Zod v3 Types. Uses a separate entry point: `react-router-typesafe-routes/zod`.
 - `yup()` - a wrapper around `type()` for creating type objects based on Yup Schemas. Uses a separate entry point: `react-router-typesafe-routes/yup`.
 
 All of them use the built-in parser with auto-detected hint by default, and all of them allow to supply a custom parser.
diff --git a/package.json b/package.json
@@ -24,6 +24,10 @@
       "import": "./lib/index.mjs",
       "default": "./lib/index.js"
     },
+    "./standard-schema": {
+      "import": "./standard-schema/index.mjs",
+      "default": "./standard-schema/index.js"
+    },
     "./zod": {
       "import": "./zod/index.mjs",
       "default": "./zod/index.js"
@@ -74,13 +78,13 @@
     "ts-jest": "^29.1.1",
     "typescript": "^5.2.2",
     "yup": "^1.0.0",
-    "zod": "^3.0.0"
+    "zod": "^3.25.67"
   },
   "peerDependencies": {
     "react": ">=18",
     "react-router": "^7.0.1",
     "yup": "^1.0.0",
-    "zod": "^3.0.0"
+    "zod": ">=3.0.0"
   },
   "peerDependenciesMeta": {
     "yup": {
diff --git a/src/lib/route.test.ts b/src/lib/route.test.ts
@@ -16,12 +16,15 @@ import {
   Parser,
   ParserHint,
   ParserType,
+  parser,
 } from "./index.js";
 import { assert, IsExact } from "conditional-type-checks";
 import { zod, configure as configureZod } from "../zod/index.js";
 import { z } from "zod";
 import { yup, configure as configureYup } from "../yup/index.js";
 import * as y from "yup";
+import { schema } from "../standard-schema/index.js";
+import { z as z4 } from "zod/v4";
 
 it("provides absolute path", () => {
   const GRANDCHILD = route({
@@ -1745,6 +1748,71 @@ it("ensures that arrays don't accept undefined items if a custom type allows und
   >(true);
 });
 
+it("allows to use standard schema v1", () => {
+  const TEST_ROUTE = route({
+    path: "",
+
+    searchParams: {
+      a: schema(z4.string().optional(), parser("string")),
+      b: schema(z4.number(), parser("number")),
+      c: schema(z4.boolean(), parser("boolean")),
+      d: schema(z4.date(), parser("date")),
+      e: schema(z4.string().nullable()),
+      f: schema(z4.string().nullable()),
+      g: schema(z4.object({ d: z4.coerce.date() })), // We have to coerce the result of JSON.parse
+    },
+  });
+
+  assert<
+    IsExact<
+      ReturnType<typeof TEST_ROUTE.$deserializeSearchParams>,
+      {
+        a?: string;
+        b?: number;
+        c?: boolean;
+        d?: Date;
+        e?: string | null;
+        f?: string | null;
+        g?: { d: Date };
+      }
+    >
+  >(true);
+
+  const testDate = new Date();
+
+  const plainSearchParams = TEST_ROUTE.$serializeSearchParams({
+    searchParams: {
+      a: "test",
+      b: 0,
+      c: false,
+      d: testDate,
+      e: "null",
+      f: null,
+      g: { d: testDate },
+    },
+  });
+
+  expect(urlSearchParamsToRecord(plainSearchParams)).toStrictEqual({
+    a: "test",
+    b: "0",
+    c: "false",
+    d: testDate.toISOString(),
+    e: '"null"',
+    f: "null",
+    g: JSON.stringify({ d: testDate }),
+  });
+
+  expect(TEST_ROUTE.$deserializeSearchParams(plainSearchParams)).toStrictEqual({
+    a: "test",
+    b: 0,
+    c: false,
+    d: testDate,
+    e: "null",
+    f: null,
+    g: { d: testDate },
+  });
+});
+
 it("allows to use zod", () => {
   const TEST_ROUTE = route({
     path: "",
diff --git a/src/standard-schema/index.ts b/src/standard-schema/index.ts
@@ -0,0 +1 @@
+export * from "./standard-schema.js";
diff --git a/src/standard-schema/standard-schema-spec.ts b/src/standard-schema/standard-schema-spec.ts
@@ -0,0 +1,67 @@
+/** @see https://github.com/standard-schema/standard-schema */
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
diff --git a/src/standard-schema/standard-schema.ts b/src/standard-schema/standard-schema.ts
@@ -0,0 +1,32 @@
+import { type, Type, ParserHint, parser, Parser } from "../lib/index.js";
+import type { StandardSchemaV1 } from "./standard-schema-spec.js";
+
+interface ConfigureOptions {
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  parserFactory: (hint?: ParserHint) => Parser<any, ParserHint>;
+}
+
+function configure({ parserFactory }: ConfigureOptions) {
+  function schema<T>(schema: StandardSchemaV1<unknown, T | undefined>, parser?: Parser<T>): Type<T> {
+    return type(
+      (value: unknown) => {
+        const result = schema["~standard"].validate(value);
+
+        if (result instanceof Promise) throw new Error("Async validation is not supported");
+
+        if (result.issues) {
+          throw new Error(JSON.stringify(result.issues, null, 2));
+        }
+
+        return result.value;
+      },
+      parser ?? parserFactory("unknown"),
+    );
+  }
+
+  return { schema };
+}
+
+const { schema } = configure({ parserFactory: parser });
+
+export { configure, schema };
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`lib/*`
	`2`	`+standard-schema/*`
`2`	`3`	`zod/*`
`3`	`4`	`yup/*`
`4`	`5`	`src/*/.cts`
-Original file line number
+Diff line change
@@ @@ -1,6 +1,7 @@ @@
 .yarn/*
 .pnp.*
 lib/*
 +standard-schema/*
 zod/*
 yup/*
 src/**/*.cts
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`releases:`
`2`		`- react-router-typesafe-routes: patch`
	`2`	`+ react-router-typesafe-routes: minor`