@r0hitsharma/router-kit 0.12.0-rohit-fork-ci.1 → 0.12.0

package/DESIGN.md

@@ -91,6 +91,28 @@ shape — and when they are not, the failure reads as an inscrutable variance er
 at the route definition rather than as a duplicate dependency. A peer makes it
 one install and the question does not arise.
 
+#### Built on `zod/mini`, composable into either entry point
+
+The builders import from `zod/mini`, not from `zod`. Both entry points are thin
+layers over the same `zod/v4/core` schema model, so a mini schema nests in a
+classic `z.object` and the reverse, at runtime and in `z.infer`. What differs is
+bundle cost: a classic schema's constructor attaches the whole method table
+(`.email`, `.toJSONSchema`, and the rest), so constructing even one pulls most
+of classic zod into the app. Measured on a real app's search schemas, minified:
+about 57 kB (17 kB gzip) on classic against 14 kB (5 kB gzip) on mini.
+
+That saving only exists if *every* schema in the bundle is mini, which is why
+the call is made here: an app that moved its own schemas to mini while these
+builders stayed classic would still ship about 49 kB. An app still on classic
+pays about 1 kB for the mini wrappers alongside.
+
+The cost is that the returned schemas carry mini's surface, not classic's:
+`textParam().default(...)` or `.describe(...)` is not available. Wrap them the
+mini way (`z._default(textParam(), ...)`), or build a param of your own on
+`toSearchText` under the rules at the foot of `search-params.ts`.
+
+`zod/mini` has been exported since zod 4.0.0, so the peer floor does not move.
+
 ### `@r0hitsharma/design-system` — not a dependency at all
 
 Not a dependency, not an optional peer. `UrlSyncedTableStateAdapter` is restated

package/README.md

@@ -85,6 +85,10 @@ export const sharedSearchSchema = z.object({
 value only if it is in the set — pass the set `as const` so the inferred type is
 the literal union rather than `string`.
 
+The builders are built on `zod/mini` and compose into an object from either
+`zod` or `zod/mini`. If nothing else in your app builds a classic schema,
+classic zod drops out of the bundle; see [DESIGN.md](./DESIGN.md).
+
 Every builder here is **total** and **idempotent**:
 
 - **Total** — no input fails, so `validateSearch` never rejects a URL. A

package/dist/search-params.d.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from 'zod/mini';
 /**
  * Collapses a raw URL search value to the text a param means, or `undefined`
  * when it means nothing.
@@ -59,7 +59,7 @@ export declare function toSearchOption<T extends string>(value: unknown, allowed
  * Schema shape returned by {@link textParam}. Named so the built `.d.ts` states
  * the param's output type instead of inlining zod's internal generics.
  */
-export type SearchTextParam = z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+export type SearchTextParam = z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniUnknown, z.ZodMiniTransform<string | undefined, unknown>>>;
 /**
  * A free-text search param: trimmed, with empty and unusable values degrading
  * to absent. Use for identifiers, query strings, and timestamps — anything
@@ -73,7 +73,7 @@ export declare function textParam(): SearchTextParam;
  * Schema shape returned by {@link oneOfParam}, carrying the closed option set
  * through to the inferred search type.
  */
-export type SearchOptionParam<T extends string> = z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<T | undefined, unknown>>>;
+export type SearchOptionParam<T extends string> = z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniUnknown, z.ZodMiniTransform<T | undefined, unknown>>>;
 /**
  * A closed-set param: one of `allowed`, or absent. Use for tabs, modes, sort
  * directions, and flags whose spellings are fixed — a hand-edited or stale

package/dist/search-params.js

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from 'zod/mini';
 /**
  * Collapses a raw URL search value to the text a param means, or `undefined`
  * when it means nothing.
@@ -85,7 +85,7 @@ export function toSearchOption(value, allowed) {
  * builders below.
  */
 export function textParam() {
-    return z.optional(z.unknown().transform(toSearchText));
+    return z.optional(z.pipe(z.unknown(), z.transform(toSearchText)));
 }
 /**
  * A closed-set param: one of `allowed`, or absent. Use for tabs, modes, sort
@@ -97,7 +97,7 @@ export function textParam() {
  * search type is the literal union rather than `string`.
  */
 export function oneOfParam(allowed) {
-    return z.optional(z.unknown().transform((value) => toSearchOption(value, allowed)));
+    return z.optional(z.pipe(z.unknown(), z.transform((value) => toSearchOption(value, allowed))));
 }
 /*
  * ## Writing a param of your own

package/package.json

@@ -42,12 +42,12 @@
     "@r0hitsharma/oxlint-config": "*",
     "@r0hitsharma/tsconfig": "*",
     "@tanstack/react-router": "1.170.33",
-    "oxfmt": "0.67.0",
-    "oxlint": "1.82.0",
+    "oxfmt": "0.68.0",
+    "oxlint": "1.83.0",
     "vitest": "^4.1.9",
     "zod": "4.5.4"
   },
-  "version": "0.12.0-rohit-fork-ci.1",
+  "version": "0.12.0",
   "repository": {
     "url": "https://github.com/r0hitsharma/uikit"
   }

package/src/search-params.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it } from 'vitest';
+import { z as classic } from 'zod';
+import { z as mini } from 'zod/mini';
 
 import {
   oneOfParam,
@@ -7,6 +9,7 @@ import {
   toSearchText,
 } from './search-params.js';
 import {
+  createMiniRouter,
   jsonParseSearch,
   jsonStringifySearch,
   parseSearch,
@@ -14,6 +17,7 @@ import {
   stringifySearch,
   TABS,
 } from './test-fixtures.js';
+import { settleEntryUrl } from './testing.js';
 
 /**
  * Renders a normalized value into a query string and decodes it back through
@@ -173,3 +177,28 @@ describe('oneOfParam', () => {
     expect(oneOfParam(TABS).parse('overview')).toBe('overview');
   });
 });
+
+describe('composing into either zod entry point', () => {
+  // The builders are built on `zod/mini` so an app on mini does not pull the
+  // classic API back in, and an app on classic `zod` still composes them into
+  // its own `z.object`. Both share `zod/v4/core`, so it is one schema model.
+  const shape = { q: textParam(), tab: oneOfParam(TABS) };
+  const raw = { q: '  hello ', tab: 'archive', stray: 1 };
+
+  it('applies the same rule under a classic and a mini object', () => {
+    const expected = { q: 'hello', tab: undefined };
+
+    expect(classic.object(shape).parse(raw)).toEqual(expected);
+    expect(mini.object(shape).parse(raw)).toEqual(expected);
+  });
+
+  it('settles an entry URL through a route whose schema is a mini object', async () => {
+    const settled = await settleEntryUrl(
+      createMiniRouter().options,
+      '/plain?q=%20hi%20&tab=archive',
+    );
+
+    expect(settled.url).toBe('/plain?q=hi');
+    expect(settled.result.search).toEqual({ q: 'hi' });
+  });
+});

package/src/search-params.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from 'zod/mini';
 
 /**
  * Collapses a raw URL search value to the text a param means, or `undefined`
@@ -90,8 +90,11 @@ export function toSearchOption<T extends string>(
  * Schema shape returned by {@link textParam}. Named so the built `.d.ts` states
  * the param's output type instead of inlining zod's internal generics.
  */
-export type SearchTextParam = z.ZodOptional<
-  z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>
+export type SearchTextParam = z.ZodMiniOptional<
+  z.ZodMiniPipe<
+    z.ZodMiniUnknown,
+    z.ZodMiniTransform<string | undefined, unknown>
+  >
 >;
 
 /**
@@ -103,15 +106,15 @@ export type SearchTextParam = z.ZodOptional<
  * builders below.
  */
 export function textParam(): SearchTextParam {
-  return z.optional(z.unknown().transform(toSearchText));
+  return z.optional(z.pipe(z.unknown(), z.transform(toSearchText)));
 }
 
 /**
  * Schema shape returned by {@link oneOfParam}, carrying the closed option set
  * through to the inferred search type.
  */
-export type SearchOptionParam<T extends string> = z.ZodOptional<
-  z.ZodPipe<z.ZodUnknown, z.ZodTransform<T | undefined, unknown>>
+export type SearchOptionParam<T extends string> = z.ZodMiniOptional<
+  z.ZodMiniPipe<z.ZodMiniUnknown, z.ZodMiniTransform<T | undefined, unknown>>
 >;
 
 /**
@@ -127,7 +130,10 @@ export function oneOfParam<T extends string>(
   allowed: readonly T[],
 ): SearchOptionParam<T> {
   return z.optional(
-    z.unknown().transform((value) => toSearchOption(value, allowed)),
+    z.pipe(
+      z.unknown(),
+      z.transform((value) => toSearchOption(value, allowed)),
+    ),
   );
 }
 

package/src/search-params.types.test.ts

@@ -1,5 +1,6 @@
 import { describe, expectTypeOf, it } from 'vitest';
 import { z } from 'zod';
+import { z as mini } from 'zod/mini';
 
 import { oneOfParam, textParam, toSearchOption } from './search-params.js';
 
@@ -57,4 +58,20 @@ export function typeAssertions(): void {
   expectTypeOf(toSearchOption('detail', mutableSet)).toEqualTypeOf<
     string | undefined
   >();
+
+  // The same inference through a mini object: an app on `zod/mini` gets the
+  // literal union and the absent case too, not a widened `unknown`.
+  const miniSchema = mini.object({ q: textParam(), tab: oneOfParam(TABS) });
+  type MiniSearch = mini.infer<typeof miniSchema>;
+  expectTypeOf<MiniSearch>().toEqualTypeOf<Search>();
+
+  // A classic object with a classic transform on top — the shape an app's
+  // shared schema usually takes — still infers through the mini children.
+  const transformed = z
+    .object({ q: textParam() })
+    .transform(({ q }) => ({ q, hasQuery: q !== undefined }));
+  expectTypeOf<z.infer<typeof transformed>>().toEqualTypeOf<{
+    q: string | undefined;
+    hasQuery: boolean;
+  }>();
 }

package/src/test-fixtures.ts

@@ -7,6 +7,7 @@ import {
   stringifySearchWith,
 } from '@tanstack/react-router';
 import { z } from 'zod';
+import { z as mini } from 'zod/mini';
 
 import { oneOfParam, textParam } from './search-params.js';
 import {
@@ -81,6 +82,27 @@ export function createToyRouter() {
   });
 }
 
+/**
+ * The toy router's cleanup with the root schema built from `zod/mini` instead
+ * of classic `zod` — the shape an app on mini writes. The router takes it as a
+ * Standard Schema, so nothing else about the tree changes.
+ */
+export function createMiniRouter() {
+  const rootRoute = createRootRoute({
+    validateSearch: mini.object({ q: textParam(), tab: oneOfParam(TABS) }),
+    beforeLoad: createValidatedSearchRedirect({ stringifySearch }),
+  });
+
+  return createRouter({
+    routeTree: rootRoute.addChildren([
+      createRoute({ getParentRoute: () => rootRoute, path: '/plain' }),
+    ]),
+    trailingSlash: 'never',
+    parseSearch,
+    stringifySearch,
+  });
+}
+
 /**
  * The same tree as {@link createToyRouter}, plus an allowlist for the two keys
  * an OAuth provider appends on the way back. Neither is declared by any schema