@bb-labs/next-router 0.0.1

package/README.md

@@ -0,0 +1,291 @@
+## Introduction
+
+Type-safe route and search params for Next.js App Router with Zod validation.
+
+- 🔒 **Type-safe** — Full TypeScript inference from your Zod schemas
+- ✅ **Validated** — Params are validated at runtime with Zod
+- 🎯 **Flexible** — Use promises or pre-awaited values, your choice
+- 🪝 **Hooks included** — First-class support for client components
+- 📦 **Zero dependencies** — Only requires Zod
+- 🛡️ **Error handling** — Built-in error handling with customizable callbacks
+
+## Installation
+
+```bash
+npm install @bb-labs/next-router
+# or
+yarn add @bb-labs/next-router
+# or
+bun add @bb-labs/next-router
+```
+
+## Server Components
+
+### `zPage`
+
+A unified function for creating page components with type-safe params. Use the `resolve` parameter to control how params are handled.
+
+#### Resolved Params (Default)
+
+When `resolve: true` (or omitted), params are **pre-awaited** with built-in Suspense.
+
+```tsx
+import { zPage } from "@bb-labs/next-router";
+import { z } from "zod";
+
+export default zPage({
+  params: {
+    searchParams: z.object({
+      email: z.string().email(),
+    }),
+  },
+  handler: ({ searchParams }) => {
+    // Already awaited — use directly
+    return <div>Email: {searchParams.email}</div>;
+  },
+});
+```
+
+**Options for resolved mode:**
+
+- `onError?: (error: z.ZodError) => void` — Custom error handler (defaults to redirecting to "/404")
+- `loadingHandler?: React.ReactNode` — Custom Suspense fallback (defaults to `null`)
+
+#### Promise Params
+
+When `resolve: false`, params are passed as **promises** — you control when to await.
+
+```tsx
+import { zPage, resolveParams } from "@bb-labs/next-router";
+import { z } from "zod";
+
+export default zPage({
+  params: {
+    routeParams: z.object({ id: z.string() }),
+    searchParams: z.object({ page: z.coerce.number().optional() }),
+  },
+  resolve: false,
+  handler: async (paramsPromise) => {
+    const { routeParams, searchParams } = await resolveParams(paramsPromise);
+    return (
+      <div>
+        Product {routeParams.id}, Page {searchParams.page}
+      </div>
+    );
+  },
+});
+```
+
+**Note:** `onError` and `loadingHandler` are not available when `resolve: false`.
+
+### `resolveParams`
+
+Helper function to await and validate params from promise-based handlers. Optionally accepts an `onError` callback.
+
+```tsx
+import { zPage, resolveParams } from "@bb-labs/next-router";
+import { redirect } from "next/navigation";
+import { z } from "zod";
+
+export default zPage({
+  params: {
+    searchParams: z.object({
+      email: z.string().email(),
+    }),
+  },
+  resolve: false,
+  handler: async (paramsPromise) => {
+    const { searchParams } = await resolveParams(paramsPromise, {
+      onError: (error) => {
+        console.error("Validation failed:", error);
+        redirect("/custom-error");
+      },
+    });
+    return <div>{searchParams.email}</div>;
+  },
+});
+```
+
+### Flexible Params Configuration
+
+You can provide both, only `routeParams`, or only `searchParams` — but never neither:
+
+```tsx
+// ✅ Both
+{ params: { routeParams: z.object({...}), searchParams: z.object({...}) } }
+
+// ✅ Only routeParams
+{ params: { routeParams: z.object({...}) } }
+
+// ✅ Only searchParams
+{ params: { searchParams: z.object({...}) } }
+
+// ❌ Neither — TypeScript error
+{ params: {} }
+```
+
+---
+
+## Client Components
+
+### `useRouteParams` / `useSearchParams`
+
+Hooks for accessing validated params in client components with `onSuccess` and `onError` callbacks.
+
+```tsx
+"use client";
+
+import { useSearchParams } from "@bb-labs/next-router/client";
+import { z } from "zod";
+
+const searchParamsSchema = z.object({
+  email: z.string().email(),
+});
+
+export function MyComponent() {
+  const { data } = useSearchParams(searchParamsSchema, {
+    onSuccess: (data) => {
+      console.log("Valid params:", data.email);
+    },
+    onError: (error) => {
+      console.error("Validation failed:", error);
+      // Custom error handling (defaults to redirecting to "/404")
+    },
+  });
+
+  if (!data) return <div>Loading...</div>;
+
+  return <div>Email: {data.email}</div>;
+}
+```
+
+### Hook API
+
+```tsx
+const { data } = useRouteParams(schema, options?);
+const { data } = useSearchParams(schema, options?);
+```
+
+**Options:**
+
+- `onSuccess?: (data: T) => void` — Called when params are successfully validated
+- `onError?: (error: Error) => void` — Called when validation fails (defaults to redirecting to "/404")
+
+**Returns:**
+
+- `data` — The validated params, or `null` if validation failed
+
+---
+
+## Schema Types
+
+**Important:** URL params are always strings. Use Zod's coercion methods for non-string types:
+
+```tsx
+// ✅ Correct — use coercion for non-string types
+z.object({
+  id: z.string(), // strings work directly
+  page: z.coerce.number(), // coerce string → number
+  active: z.coerce.boolean(), // coerce string → boolean
+  count: z.coerce.number().optional(), // optional coerced number
+  tags: z.array(z.string()), // array of strings (for ?tags=a&tags=b)
+});
+
+// ❌ Wrong — will fail because raw input is always a string
+z.object({
+  page: z.number(), // Error: expected number, received string
+  active: z.boolean(), // Error: expected boolean, received string
+});
+```
+
+You can also use transforms for custom parsing:
+
+```tsx
+z.object({
+  date: z.string().transform((s) => new Date(s)),
+  ids: z.string().transform((s) => s.split(",")),
+});
+```
+
+### JSON-Encoded Objects
+
+For complex objects, encode them as JSON in the URL (URL-escaped). Use `.transform()` with `JSON.parse()` and `.pipe()` to validate:
+
+```tsx
+// URL: ?filter={"category":"books","price":{"min":10,"max":50},"inStock":true}
+// (URL-encoded: ?filter=%7B%22category%22%3A%22books%22...%7D)
+
+z.object({
+  filter: z
+    .string()
+    .transform((s) => JSON.parse(s))
+    .pipe(
+      z.object({
+        category: z.string(),
+        price: z.object({ min: z.number(), max: z.number() }),
+        tags: z.array(z.string()).optional(),
+        inStock: z.boolean(),
+      })
+    ),
+});
+```
+
+**How it works:**
+
+1. The raw URL param is a JSON string: `'{"category":"books",...}'`
+2. `.transform((s) => JSON.parse(s))` parses it into a JS object
+3. `.pipe(z.object({...}))` validates the parsed object's structure
+
+**Example usage:**
+
+```tsx
+export default zPage({
+  params: {
+    searchParams: z.object({
+      filter: z
+        .string()
+        .transform((s) => JSON.parse(s))
+        .pipe(
+          z.object({
+            category: z.string(),
+            price: z.object({ min: z.number(), max: z.number() }),
+          })
+        ),
+    }),
+  },
+  handler: ({ searchParams }) => {
+    // searchParams.filter is fully typed!
+    return (
+      <div>
+        Category: {searchParams.filter.category}
+        Price: ${searchParams.filter.price.min} - ${searchParams.filter.price.max}
+      </div>
+    );
+  },
+});
+```
+
+**Client-side encoding:**
+
+```tsx
+const filter = { category: "books", price: { min: 10, max: 50 } };
+const url = `/products?filter=${encodeURIComponent(JSON.stringify(filter))}`;
+```
+
+---
+
+## Error Handling
+
+By default, validation errors redirect to "/404":
+
+- **Server components**: `zPage` and `resolveParams` with `resolve: true` redirects on validation failure
+- **Client components**: `useRouteParams` and `useSearchParams` redirect on validation failure
+
+You can customize error handling:
+
+- **Server**: Provide an `onError` callback to `zPage` (only available when `resolve: true`)
+- **Client**: Provide an `onError` callback to the hooks
+
+## License
+
+MIT

package/dist/client/index.d.ts

@@ -0,0 +1 @@
+export * from "./z-page";

package/dist/client/index.js

@@ -0,0 +1 @@
+export * from "./z-page";

package/dist/client/z-page/index.d.ts

@@ -0,0 +1,21 @@
+import { z, type ZodRawShape } from "zod";
+type ZodObject = z.ZodObject<ZodRawShape>;
+type HookOptions<T> = {
+    onSuccess?: (data: T) => void;
+    onError?: (error: Error) => void;
+};
+export declare function useRouteParams<T extends ZodObject>(schema: T, options?: HookOptions<z.output<T>>): {
+    data: z.output<T>;
+    error: null;
+} | {
+    data: null;
+    error: z.ZodError<z.core.output<T>>;
+};
+export declare function useSearchParams<T extends ZodObject>(schema: T, options?: HookOptions<z.output<T>>): {
+    data: z.output<T>;
+    error: null;
+} | {
+    data: null;
+    error: z.ZodError<z.core.output<T>>;
+};
+export {};

package/dist/client/z-page/index.js

@@ -0,0 +1,52 @@
+"use client";
+import { useEffect, useRef, useMemo } from "react";
+import { useParams, useSearchParams as useNextSearchParams, useRouter } from "next/navigation";
+export function useRouteParams(schema, options) {
+    const rawParams = useParams();
+    const router = useRouter();
+    const calledRef = useRef(false);
+    const result = useMemo(() => {
+        const parsed = schema.safeParse(rawParams);
+        return parsed.success ? { data: parsed.data, error: null } : { data: null, error: parsed.error };
+    }, [rawParams, schema]);
+    useEffect(() => {
+        if (calledRef.current)
+            return;
+        calledRef.current = true;
+        if (result.error) {
+            console.log(result.error);
+            options?.onError ? options.onError(result.error) : router.push("/404");
+        }
+        else if (result.data) {
+            options?.onSuccess?.(result.data);
+        }
+    }, [result, options, router]);
+    return result;
+}
+export function useSearchParams(schema, options) {
+    const nextSearchParams = useNextSearchParams();
+    const router = useRouter();
+    const calledRef = useRef(false);
+    const result = useMemo(() => {
+        const raw = {};
+        nextSearchParams.forEach((v, k) => {
+            const existing = raw[k];
+            raw[k] = existing ? (Array.isArray(existing) ? [...existing, v] : [existing, v]) : v;
+        });
+        const parsed = schema.safeParse(raw);
+        return parsed.success ? { data: parsed.data, error: null } : { data: null, error: parsed.error };
+    }, [nextSearchParams, schema]);
+    useEffect(() => {
+        if (calledRef.current)
+            return;
+        calledRef.current = true;
+        if (result.error) {
+            console.log(result.error);
+            options?.onError ? options.onError(result.error) : router.push("/404");
+        }
+        else if (result.data) {
+            options?.onSuccess?.(result.data);
+        }
+    }, [result, options, router]);
+    return result;
+}

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export * from "./z-page";

package/dist/server/index.js

@@ -0,0 +1 @@
+export * from "./z-page";

package/dist/server/z-page/fns/z-page.d.ts

@@ -0,0 +1,81 @@
+import React from "react";
+import { z } from "zod";
+import { type ZodObject, type OnError } from "../utils/helper";
+import type { NextPageProps } from "../types";
+/** Return type for zPage */
+type ZPageReturn = (props: NextPageProps) => React.ReactNode | Promise<React.ReactNode>;
+export declare function zPage<RP extends ZodObject, SP extends ZodObject>(cfg: {
+    params: {
+        routeParams: RP;
+        searchParams: SP;
+    };
+    resolve?: true;
+    onError?: OnError;
+    loadingHandler?: React.ReactNode;
+    handler: (input: {
+        routeParams: z.output<RP>;
+        searchParams: z.output<SP>;
+    }) => React.ReactNode | Promise<React.ReactNode>;
+}): ZPageReturn;
+export declare function zPage<RP extends ZodObject>(cfg: {
+    params: {
+        routeParams: RP;
+        searchParams?: undefined;
+    };
+    resolve?: true;
+    onError?: OnError;
+    loadingHandler?: React.ReactNode;
+    handler: (input: {
+        routeParams: z.output<RP>;
+    }) => React.ReactNode | Promise<React.ReactNode>;
+}): ZPageReturn;
+export declare function zPage<SP extends ZodObject>(cfg: {
+    params: {
+        routeParams?: undefined;
+        searchParams: SP;
+    };
+    resolve?: true;
+    onError?: OnError;
+    loadingHandler?: React.ReactNode;
+    handler: (input: {
+        searchParams: z.output<SP>;
+    }) => React.ReactNode | Promise<React.ReactNode>;
+}): ZPageReturn;
+export declare function zPage<RP extends ZodObject, SP extends ZodObject>(cfg: {
+    params: {
+        routeParams: RP;
+        searchParams: SP;
+    };
+    resolve: false;
+    onError?: never;
+    loadingHandler?: never;
+    handler: (input: {
+        routeParams: Promise<z.output<RP>>;
+        searchParams: Promise<z.output<SP>>;
+    }) => React.ReactNode | Promise<React.ReactNode>;
+}): ZPageReturn;
+export declare function zPage<RP extends ZodObject>(cfg: {
+    params: {
+        routeParams: RP;
+        searchParams?: undefined;
+    };
+    resolve: false;
+    onError?: never;
+    loadingHandler?: never;
+    handler: (input: {
+        routeParams: Promise<z.output<RP>>;
+    }) => React.ReactNode | Promise<React.ReactNode>;
+}): ZPageReturn;
+export declare function zPage<SP extends ZodObject>(cfg: {
+    params: {
+        routeParams?: undefined;
+        searchParams: SP;
+    };
+    resolve: false;
+    onError?: never;
+    loadingHandler?: never;
+    handler: (input: {
+        searchParams: Promise<z.output<SP>>;
+    }) => React.ReactNode | Promise<React.ReactNode>;
+}): ZPageReturn;
+export {};

package/dist/server/z-page/fns/z-page.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense } from "react";
+import { setup } from "../utils/helper";
+// ------------- IMPLEMENTATION -------------
+export function zPage(cfg) {
+    const shouldResolve = cfg.resolve !== false;
+    const { createValidatedPromises, resolveParams } = setup(cfg.params, shouldResolve ? cfg.onError : undefined);
+    if (!shouldResolve) {
+        return async (props) => cfg.handler(createValidatedPromises(props));
+    }
+    async function Inner({ promises }) {
+        const input = await resolveParams(promises);
+        if (!Object.keys(input).length)
+            return null;
+        return cfg.handler(input);
+    }
+    return (props) => (_jsx(Suspense, { fallback: cfg.loadingHandler ?? null, children: _jsx(Inner, { promises: createValidatedPromises(props) }) }));
+}

package/dist/server/z-page/helpers/infer-props.d.ts

@@ -0,0 +1,12 @@
+import { z, type ZodObject, type ZodRawShape } from "zod";
+type InferParamsPromises<T> = ("routeParams" extends keyof T ? (T["routeParams"] extends ZodObject<ZodRawShape> ? {
+    routeParams: Promise<z.output<T["routeParams"]>>;
+} : {}) : {}) & ("searchParams" extends keyof T ? (T["searchParams"] extends ZodObject<ZodRawShape> ? {
+    searchParams: Promise<z.output<T["searchParams"]>>;
+} : {}) : {});
+type InferParams<T> = ("routeParams" extends keyof T ? (T["routeParams"] extends ZodObject<ZodRawShape> ? {
+    routeParams: z.output<T["routeParams"]>;
+} : {}) : {}) & ("searchParams" extends keyof T ? (T["searchParams"] extends ZodObject<ZodRawShape> ? {
+    searchParams: z.output<T["searchParams"]>;
+} : {}) : {});
+export type { InferParamsPromises, InferParams };

package/dist/server/z-page/helpers/infer-props.js

@@ -0,0 +1 @@
+export {};

package/dist/server/z-page/helpers/resolve-params.d.ts

@@ -0,0 +1,14 @@
+import { type OnError } from "../utils/helper";
+type ResolveParamsInput<RP, SP> = {
+    routeParams?: Promise<RP>;
+    searchParams?: Promise<SP>;
+};
+type ResolveParamsResult<RP, SP> = {
+    routeParams: RP;
+    searchParams: SP;
+};
+type ResolveParamsOptions = {
+    onError?: OnError;
+};
+export declare function resolveParams<RP, SP>(paramsPromise: ResolveParamsInput<RP, SP>, options?: ResolveParamsOptions): Promise<ResolveParamsResult<RP, SP>>;
+export {};

package/dist/server/z-page/helpers/resolve-params.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { defaultOnError } from "../utils/helper";
+export async function resolveParams(paramsPromise, options = {}) {
+    const result = {};
+    const onError = options.onError ?? defaultOnError;
+    if (paramsPromise.routeParams) {
+        try {
+            result.routeParams = await paramsPromise.routeParams;
+        }
+        catch (e) {
+            if (e instanceof z.ZodError) {
+                onError(e);
+                return result;
+            }
+            throw e;
+        }
+    }
+    if (paramsPromise.searchParams) {
+        try {
+            result.searchParams = await paramsPromise.searchParams;
+        }
+        catch (e) {
+            if (e instanceof z.ZodError) {
+                onError(e);
+                return result;
+            }
+            throw e;
+        }
+    }
+    return result;
+}

package/dist/server/z-page/index.d.ts

@@ -0,0 +1,3 @@
+export { zPage } from "./fns/z-page";
+export { resolveParams } from "./helpers/resolve-params";
+export type { InferParamsPromises, InferParams } from "./helpers/infer-props";

package/dist/server/z-page/index.js

@@ -0,0 +1,2 @@
+export { zPage } from "./fns/z-page";
+export { resolveParams } from "./helpers/resolve-params";

package/dist/server/z-page/types.d.ts

@@ -0,0 +1,10 @@
+import { z, type ZodRawShape } from "zod";
+/** Next.js page props type */
+export type NextPageProps = {
+    params: Promise<Record<string, string | string[]>>;
+    searchParams: Promise<Record<string, string | string[] | undefined>>;
+};
+/** Enforces that routeParams/searchParams must be z.object(...) */
+export type ZodObject = z.ZodObject<ZodRawShape>;
+/** Error handler type */
+export type OnError = (error: z.ZodError) => never | void;

package/dist/server/z-page/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/z-page/utils/helper.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { NextPageProps, ZodObject, OnError } from "../types";
+export type { ZodObject, OnError };
+export declare const defaultOnError: OnError;
+export declare function setup<RP extends ZodObject, SP extends ZodObject>(params: {
+    routeParams?: RP;
+    searchParams?: SP;
+}, onError?: OnError): {
+    createValidatedPromises: (props: NextPageProps) => {
+        routeParams: Promise<z.core.output<RP>> | undefined;
+        searchParams: Promise<z.core.output<SP>> | undefined;
+    };
+    resolveParams: (promises: {
+        routeParams: Promise<z.core.output<RP>> | undefined;
+        searchParams: Promise<z.core.output<SP>> | undefined;
+    }) => Promise<Record<string, unknown>>;
+};

package/dist/server/z-page/utils/helper.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { redirect } from "next/navigation";
+export const defaultOnError = (e) => {
+    console.log(e);
+    redirect("/404");
+};
+export function setup(params, onError = defaultOnError) {
+    const rpSchema = params.routeParams;
+    const spSchema = params.searchParams;
+    /** Creates validated promises from Next.js page props */
+    function createValidatedPromises(props) {
+        return {
+            routeParams: rpSchema ? props.params.then((raw) => rpSchema.parse(raw)) : undefined,
+            searchParams: spSchema ? props.searchParams.then((raw) => spSchema.parse(raw)) : undefined,
+        };
+    }
+    /** Awaits all params in parallel, handling errors */
+    async function resolveParams(promises) {
+        const result = {};
+        try {
+            const [rp, sp] = await Promise.all([promises.routeParams, promises.searchParams]);
+            if (rpSchema)
+                result.routeParams = rp;
+            if (spSchema)
+                result.searchParams = sp;
+        }
+        catch (e) {
+            if (e instanceof z.ZodError)
+                return onError(e), {};
+            throw e;
+        }
+        return result;
+    }
+    return { createValidatedPromises, resolveParams };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@bb-labs/next-router",
+  "version": "0.0.1",
+  "author": "Beepbop",
+  "homepage": "https://github.com/beepbop-labs/next-router",
+  "keywords": [
+    "next-router",
+    "router",
+    "next",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beepbop-labs/next-router.git"
+  },
+  "description": "A library for routing in Next.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./dist/server/index.js",
+    "./client": "./dist/client/index.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "pack": "npm run build && npm pack --pack-destination ./archive/"
+  },
+  "dependencies": {
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.7"
+  },
+  "peerDependencies": {
+    "typescript": "^5",
+    "react": "^19",
+    "next": "^16.0.4"
+  }
+}