rouzer 0.0.0 → 1.0.0-beta.10

package/dist/client/index.d.ts

@@ -0,0 +1,36 @@
+import type { Promisable, RouteRequest } from '../types.js';
+export declare function createClient(config: {
+    /**
+     * Base URL to use for all requests.
+     */
+    baseURL: string;
+    /**
+     * Default headers to send with every request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Custom handler for non-200 response to a `.json()` request. By default, the
+     * response is always parsed as JSON, regardless of the HTTP status code.
+     */
+    onJsonError?: (response: Response) => Promisable<Response>;
+}): {
+    config: {
+        /**
+         * Base URL to use for all requests.
+         */
+        baseURL: string;
+        /**
+         * Default headers to send with every request.
+         */
+        headers?: Record<string, string> | undefined;
+        /**
+         * Custom handler for non-200 response to a `.json()` request. By default, the
+         * response is always parsed as JSON, regardless of the HTTP status code.
+         */
+        onJsonError?: ((response: Response) => Promisable<Response>) | undefined;
+    };
+    request<T extends RouteRequest>({ path: pathBuilder, method, args: { path, query, body, headers }, route, }: T): Promise<Response & {
+        json(): Promise<T["$result"]>;
+    }>;
+    json<T extends RouteRequest>(request: T): Promise<T["$result"]>;
+};

package/dist/client/index.js

@@ -0,0 +1,55 @@
+import { shake } from '../common.js';
+export function createClient(config) {
+    const baseURL = config.baseURL.replace(/\/$/, '');
+    return {
+        config,
+        request({ path: pathBuilder, method, args: { path, query, body, headers }, route, }) {
+            if (route.path) {
+                path = route.path.parse(path);
+            }
+            let url;
+            const href = pathBuilder.href(path);
+            if (href[0] === '/') {
+                url = new URL(baseURL);
+                url.pathname += pathBuilder.href(path);
+            }
+            else {
+                url = new URL(href);
+            }
+            if (route.query) {
+                query = route.query.parse(query ?? {});
+                url.search = new URLSearchParams(query).toString();
+            }
+            else if (query) {
+                throw new Error('Unexpected query parameters');
+            }
+            if (route.body) {
+                body = route.body.parse(body !== undefined ? body : {});
+            }
+            else if (body !== undefined) {
+                throw new Error('Unexpected body');
+            }
+            if (config.headers || headers) {
+                headers = {
+                    ...config.headers,
+                    ...(headers && shake(headers)),
+                };
+            }
+            if (route.headers) {
+                headers = route.headers.parse(headers);
+            }
+            return fetch(url, {
+                method,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                headers: headers,
+            });
+        },
+        async json(request) {
+            const response = await this.request(request);
+            if (!response.ok && config.onJsonError) {
+                return config.onJsonError(response);
+            }
+            return response.json();
+        },
+    };
+}

package/dist/common.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Map over all the keys to create a new object.
+ *
+ * @see https://radashi.js.org/reference/object/mapEntries
+ * @example
+ * ```ts
+ * const a = { a: 1, b: 2, c: 3 }
+ * mapEntries(a, (key, value) => [value, key])
+ * // => { 1: 'a', 2: 'b', 3: 'c' }
+ * ```
+ * @version 12.1.0
+ */
+export declare function mapEntries<TKey extends string | number | symbol, TValue, TNewKey extends string | number | symbol, TNewValue>(obj: Record<TKey, TValue>, toEntry: (key: TKey, value: TValue) => [TNewKey, TNewValue]): Record<TNewKey, TNewValue>;
+/**
+ * Removes (shakes out) undefined entries from an object. Optional
+ * second argument shakes out values by custom evaluation.
+ *
+ * Note that non-enumerable keys are never shaken out.
+ *
+ * @see https://radashi.js.org/reference/object/shake
+ * @example
+ * ```ts
+ * const a = { a: 1, b: undefined, c: 3 }
+ * shake(a)
+ * // => { a: 1, c: 3 }
+ * ```
+ * @version 12.1.0
+ */
+export declare function shake<T extends object>(obj: T): {
+    [K in keyof T]: Exclude<T[K], undefined>;
+};
+export declare function shake<T extends object>(obj: T, filter: ((value: unknown) => boolean) | undefined): T;
+/**
+ * Map over all the keys to create a new object.
+ *
+ * @see https://radashi.js.org/reference/object/mapValues
+ * @example
+ * ```ts
+ * const a = { a: 1, b: 2, c: 3 }
+ * mapValues(a, (value, key) => value * 2)
+ * // => { a: 2, b: 4, c: 6 }
+ * ```
+ * @version 12.1.0
+ */
+export declare function mapValues<T extends object, U>(obj: T, mapFunc: (value: Required<T>[keyof T], key: keyof T) => U): {
+    [K in keyof T]: U;
+};

package/dist/common.js

@@ -0,0 +1,51 @@
+/**
+ * Map over all the keys to create a new object.
+ *
+ * @see https://radashi.js.org/reference/object/mapEntries
+ * @example
+ * ```ts
+ * const a = { a: 1, b: 2, c: 3 }
+ * mapEntries(a, (key, value) => [value, key])
+ * // => { 1: 'a', 2: 'b', 3: 'c' }
+ * ```
+ * @version 12.1.0
+ */
+export function mapEntries(obj, toEntry) {
+    if (!obj) {
+        return {};
+    }
+    return Object.entries(obj).reduce((acc, [key, value]) => {
+        const [newKey, newValue] = toEntry(key, value);
+        acc[newKey] = newValue;
+        return acc;
+    }, {});
+}
+export function shake(obj, filter = value => value === undefined) {
+    if (!obj) {
+        return {};
+    }
+    return Object.keys(obj).reduce((acc, key) => {
+        if (!filter(obj[key])) {
+            acc[key] = obj[key];
+        }
+        return acc;
+    }, {});
+}
+/**
+ * Map over all the keys to create a new object.
+ *
+ * @see https://radashi.js.org/reference/object/mapValues
+ * @example
+ * ```ts
+ * const a = { a: 1, b: 2, c: 3 }
+ * mapValues(a, (value, key) => value * 2)
+ * // => { a: 2, b: 4, c: 6 }
+ * ```
+ * @version 12.1.0
+ */
+export function mapValues(obj, mapFunc) {
+    return Object.keys(obj).reduce((acc, key) => {
+        acc[key] = mapFunc(obj[key], key);
+        return acc;
+    }, {});
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './route.js';
+export * from './server/router.js';
+export * from './client/index.js';
+export type * from './types.js';
+export * from 'alien-middleware';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './route.js';
+export * from './server/router.js';
+export * from './client/index.js';
+export * from 'alien-middleware';

package/dist/route.d.ts

@@ -0,0 +1,7 @@
+import { RoutePattern } from '@remix-run/route-pattern';
+import type { MutationMethod, QueryMethod, RouteFunction, RouteMethods, Unchecked } from './types.js';
+export declare function $type<T>(): Unchecked<T>;
+export declare function route<P extends string, T extends RouteMethods>(pattern: P, methods: T): {
+    path: RoutePattern<P>;
+    methods: T;
+} & { [K in keyof T]: RouteFunction<Extract<T[K], MutationMethod | QueryMethod>>; };

package/dist/route.js

@@ -0,0 +1,18 @@
+import { RoutePattern } from '@remix-run/route-pattern';
+import { mapEntries } from './common.js';
+export function $type() {
+    return null;
+}
+export function route(pattern, methods) {
+    const path = new RoutePattern(pattern);
+    const createFetch = (method, route) => (args) => {
+        return {
+            route,
+            path,
+            method,
+            args,
+            $result: undefined,
+        };
+    };
+    return Object.assign({ path, methods }, mapEntries(methods, (method, route) => [method, createFetch(method, route)]));
+}

package/dist/server/router.d.ts

@@ -0,0 +1,111 @@
+import type { AdapterRequestContext } from '@hattip/core';
+import { type Params } from '@remix-run/route-pattern';
+import { chain, MiddlewareChain, type MiddlewareContext } from 'alien-middleware';
+import * as z from 'zod/mini';
+import type { InferRouteResponse, MutationMethod, Promisable, QueryMethod, Routes } from '../types.js';
+export { chain };
+type EmptyMiddlewareChain<TPlatform = unknown> = MiddlewareChain<{
+    initial: {
+        env: {};
+        properties: {};
+    };
+    current: {
+        env: {};
+        properties: {};
+    };
+    platform: TPlatform;
+}>;
+export type RouterConfig = {
+    /**
+     * Base path to prepend to all routes.
+     * @example
+     * ```ts
+     * basePath: 'api/',
+     * ```
+     */
+    basePath?: string;
+    /**
+     * Routes to match.
+     * @example
+     * ```ts
+     * // This namespace contains your `route()` declarations.
+     * // Pass it to the `createRouter` function.
+     * import * as routes from './routes'
+     *
+     * createRouter({ routes })({
+     *   // your route handlers...
+     * })
+     * ```
+     */
+    routes: Routes;
+    /**
+     * Middleware to apply to all routes.
+     * @see https://github.com/alien-rpc/alien-middleware#quick-start
+     * @example
+     * ```ts
+     * middlewares: chain().use(ctx => {
+     *   return {
+     *     db: postgres(ctx.env('POSTGRES_URL')),
+     *   }
+     * }),
+     * ```
+     */
+    middlewares?: MiddlewareChain;
+    /**
+     * Enable debugging features.
+     * - When a handler throws an error, include its message in the response body.
+     * - Throw an error if a handler is not found for a route.
+     * @example
+     * ```ts
+     * debug: process.env.NODE_ENV !== 'production',
+     * ```
+     */
+    debug?: boolean;
+    /**
+     * CORS configuration.
+     */
+    cors?: {
+        /**
+         * If defined, requests must have an `Origin` header that is in this list.
+         *
+         * Origins may contain wildcards for protocol and subdomain. The protocol is
+         * optional and defaults to `https`.
+         *
+         * @example
+         * ```ts
+         * allowOrigins: ['example.net', 'https://*.example.com', '*://localhost:3000']
+         * ```
+         */
+        allowOrigins?: string[];
+    };
+};
+interface CreateRouterConfig<TRoutes extends Routes, TMiddleware extends MiddlewareChain> extends RouterConfig {
+    routes: TRoutes;
+    middlewares?: TMiddleware;
+}
+export declare function createRouter<TRoutes extends Routes, TMiddleware extends MiddlewareChain = EmptyMiddlewareChain>(config: CreateRouterConfig<TRoutes, TMiddleware>): (handlers: { [K in keyof TRoutes]: { [M in keyof TRoutes[K]["methods"]]: TRoutes[K]["methods"][M] extends infer T ? T extends TRoutes[K]["methods"][M] ? T extends QueryMethod ? (context: MiddlewareContext<TMiddleware> & {
+    path: T extends {
+        path: any;
+    } ? z.infer<T["path"]> : Params<TRoutes[K]["path"]["source"]>;
+    query: z.infer<T["query"]>;
+    headers: z.infer<T["headers"]>;
+}) => Promisable<Response | InferRouteResponse<T>> : T extends MutationMethod ? (context: MiddlewareContext<TMiddleware> & {
+    path: T extends {
+        path: any;
+    } ? z.infer<T["path"]> : Params<TRoutes[K]["path"]["source"]>;
+    body: z.infer<T["body"]>;
+    headers: z.infer<T["headers"]>;
+}) => Promisable<Response | InferRouteResponse<T>> : never : never : never; }; }) => import("alien-middleware").ApplyMiddleware<TMiddleware, (context: AdapterRequestContext<TMiddleware extends MiddlewareChain<infer T extends {
+    initial: {
+        env: object;
+        properties: object;
+    };
+    current: {
+        env: object;
+        properties: object;
+    };
+    platform: unknown;
+}> ? T["platform"] : never> & {
+    url?: URL | undefined;
+    path?: {} | undefined;
+}) => Promise<Response | undefined>>;

package/dist/server/router.js

@@ -0,0 +1,175 @@
+import { RoutePattern } from '@remix-run/route-pattern';
+import { chain, } from 'alien-middleware';
+import { mapValues } from '../common.js';
+import * as z from 'zod/mini';
+export { chain };
+export function createRouter(config) {
+    const keys = Object.keys(config.routes);
+    const middlewares = config.middlewares ?? chain();
+    const basePath = config.basePath?.replace(/\/?$/, '/');
+    const patterns = mapValues(config.routes, ({ path }) => basePath ? new RoutePattern(path.source.replace(/^\/?/, basePath)) : path);
+    const allowOrigins = config.cors?.allowOrigins?.map(origin => {
+        if (!origin.includes('//')) {
+            origin = `https://${origin}`;
+        }
+        if (origin.includes('*')) {
+            return new RegExp(`^${origin
+                .replace(/\./g, '\\.')
+                .replace(/\*:/g, '[^:]+:') // Wildcard protocol
+                .replace(/\*\./g, '([^/.]+\\.)?') // Wildcard subdomain
+            }$`);
+        }
+        return new ExactPattern(origin);
+    });
+    return (handlers) => middlewares.use(async function (context) {
+        const request = context.request;
+        const url = (context.url ??= new URL(request.url));
+        let method = request.method.toUpperCase();
+        let isPreflight = false;
+        if (method === 'OPTIONS') {
+            method = request.headers.get('Access-Control-Request-Method') ?? 'GET';
+            isPreflight = true;
+        }
+        for (let i = 0; i < keys.length; i++) {
+            const route = config.routes[keys[i]].methods[method];
+            if (!route) {
+                continue;
+            }
+            const match = patterns[keys[i]].match(url);
+            if (!match) {
+                continue;
+            }
+            const handler = handlers[keys[i]][method];
+            if (!handler) {
+                if (config.debug) {
+                    throw new Error(`Handler not found for route: ${keys[i]} ${method}`);
+                }
+                continue;
+            }
+            if (isPreflight) {
+                const origin = request.headers.get('Origin');
+                if (allowOrigins &&
+                    !(origin && allowOrigins.some(pattern => pattern.test(origin)))) {
+                    return new Response(null, { status: 403 });
+                }
+                return new Response(null, {
+                    headers: {
+                        'Access-Control-Allow-Origin': origin ?? '*',
+                        'Access-Control-Allow-Methods': method,
+                        'Access-Control-Allow-Headers': request.headers.get('Access-Control-Request-Headers') ?? '',
+                    },
+                });
+            }
+            if (route.path) {
+                const error = parsePathParams(context, enableStringParsing(route.path), match.params);
+                if (error) {
+                    return httpClientError(error, 'Invalid path parameter', config);
+                }
+            }
+            else {
+                context.path = match.params;
+            }
+            if (route.headers) {
+                const error = parseHeaders(context, enableStringParsing(route.headers));
+                if (error) {
+                    return httpClientError(error, 'Invalid request headers', config);
+                }
+            }
+            if (route.query) {
+                const error = parseQueryString(context, enableStringParsing(route.query));
+                if (error) {
+                    return httpClientError(error, 'Invalid query string', config);
+                }
+            }
+            if (route.body) {
+                const error = await parseRequestBody(context, route.body);
+                if (error) {
+                    return httpClientError(error, 'Invalid request body', config);
+                }
+            }
+            const result = await handler(context);
+            if (result instanceof Response) {
+                return result;
+            }
+            return Response.json(result);
+        }
+    });
+}
+function httpClientError(error, message, config) {
+    return Response.json({
+        ...error,
+        message: config.debug ? `${message}: ${error.message}` : message,
+    }, { status: 400 });
+}
+function parsePathParams(context, schema, params) {
+    const result = schema.safeParse(params);
+    if (!result.success) {
+        return result.error;
+    }
+    context.path = result.data;
+    return null;
+}
+function parseHeaders(context, schema) {
+    const headers = Object.fromEntries(context.request.headers);
+    const result = schema.safeParse(headers);
+    if (!result.success) {
+        return result.error;
+    }
+    context.headers = result.data;
+    return null;
+}
+function parseQueryString(context, schema) {
+    const result = schema.safeParse(Object.fromEntries(context.url.searchParams));
+    if (!result.success) {
+        return result.error;
+    }
+    context.query = result.data;
+    return null;
+}
+async function parseRequestBody(context, schema) {
+    const result = await context.request.json().then(body => schema.safeParse(body), error => ({ success: false, error }));
+    if (!result.success) {
+        return result.error;
+    }
+    context.body = result.data;
+    return null;
+}
+const seen = new WeakMap();
+/**
+ * Traverse object and array schemas, finding schemas that expect a number or
+ * boolean, and replace those schemas with a new schema that parses the input
+ * value as a number or boolean.
+ */
+function enableStringParsing(schema) {
+    if (schema.type === 'number') {
+        return z.pipe(z.transform(Number), schema);
+    }
+    if (schema.type === 'boolean') {
+        return z.pipe(z.transform(toBooleanStrict), schema);
+    }
+    if (schema.type === 'object') {
+        const cached = seen.get(schema);
+        if (cached) {
+            return cached;
+        }
+        const modified = z.object(mapValues(schema.def.shape, enableStringParsing));
+        seen.set(schema, modified);
+        return modified;
+    }
+    if (schema.type === 'array') {
+        return z.array(enableStringParsing(schema.def.element));
+    }
+    return schema;
+}
+function toBooleanStrict(value) {
+    return value === 'true' || (value === 'false' ? false : value);
+}
+class ExactPattern {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    test(input) {
+        return input === this.value;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,85 @@
+import { Params, RoutePattern } from '@remix-run/route-pattern';
+import * as z from 'zod/mini';
+export type Promisable<T> = T | Promise<T>;
+export type Unchecked<T> = {
+    __unchecked__: T;
+};
+export type QueryMethod = {
+    path?: z.ZodMiniObject<any>;
+    query?: z.ZodMiniObject<any>;
+    body?: never;
+    headers?: z.ZodMiniObject<any>;
+    response: Unchecked<any>;
+};
+export type MutationMethod = {
+    path?: z.ZodMiniObject<any>;
+    query?: never;
+    body: z.ZodMiniType<any, any>;
+    headers?: z.ZodMiniObject<any>;
+    response?: Unchecked<any>;
+};
+export type RouteMethods = {
+    GET?: QueryMethod;
+    POST?: MutationMethod;
+    PUT?: MutationMethod;
+    PATCH?: MutationMethod;
+    DELETE?: MutationMethod;
+};
+export type Routes = {
+    [key: string]: {
+        path: RoutePattern;
+        methods: RouteMethods;
+    };
+};
+declare class Any {
+    private isAny;
+}
+type PathArgs<T> = T extends {
+    path: infer TPath extends string;
+} ? Params<TPath> extends infer TParams ? {} extends TParams ? {
+    path?: TParams;
+} : {
+    path: TParams;
+} : unknown : unknown;
+type QueryArgs<T> = T extends QueryMethod & {
+    query: infer TQuery;
+} ? {} extends z.infer<TQuery> ? {
+    query?: z.infer<TQuery>;
+} : {
+    query: z.infer<TQuery>;
+} : unknown;
+type MutationArgs<T> = T extends MutationMethod & {
+    body: infer TBody;
+} ? {} extends z.infer<TBody> ? {
+    body?: z.infer<TBody>;
+} : {
+    body: z.infer<TBody>;
+} : unknown;
+export type RouteArgs<T extends QueryMethod | MutationMethod = any> = ([
+    T
+] extends [Any] ? {
+    query?: any;
+    body?: any;
+    path?: any;
+} : QueryArgs<T> & MutationArgs<T> & PathArgs<T>) & Omit<RequestInit, 'method' | 'body' | 'headers'> & {
+    headers?: Record<string, string | undefined>;
+};
+export type RouteRequest<TResult = any> = {
+    route: QueryMethod | MutationMethod;
+    path: RoutePattern;
+    method: string;
+    args: RouteArgs;
+    $result: TResult;
+};
+export type RouteResponse<TResult = any> = Response & {
+    json(): Promise<TResult>;
+};
+export type InferRouteResponse<T extends QueryMethod | MutationMethod> = T extends {
+    response: Unchecked<infer TResponse>;
+} ? TResponse : void;
+export type RouteFunction<T extends QueryMethod | MutationMethod> = {
+    (args: RouteArgs<T>): RouteRequest<InferRouteResponse<T>>;
+    $args: RouteArgs<T>;
+    $response: InferRouteResponse<T>;
+};
+export {};

package/dist/types.js

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

package/package.json

@@ -1,9 +1,40 @@
 {
   "name": "rouzer",
-  "version": "0.0.0",
+  "version": "1.0.0-beta.10",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": ">=4"
+  },
   "devDependencies": {
     "@alloc/prettier-config": "^1.0.0",
     "@typescript/native-preview": "7.0.0-dev.20251208.1",
-    "prettier": "^3.7.4"
+    "prettier": "^3.7.4",
+    "tsc-lint": "^0.1.9",
+    "typescript": "^5.9.3",
+    "zod": "^4.1.13"
+  },
+  "dependencies": {
+    "@hattip/core": "^0.0.49",
+    "@remix-run/route-pattern": "^0.15.3",
+    "alien-middleware": "^0.10.2"
+  },
+  "prettier": "@alloc/prettier-config",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alloc/rouzer.git"
+  },
+  "files": [
+    "dist",
+    "!*.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsgo -b tsconfig.json"
   }
-}
+}

package/readme.md

@@ -0,0 +1,93 @@
+# rouzer
+
+Type-safe routes shared by your server and client, powered by `zod/mini` (input validation + transforms), `@remix-run/route-pattern` (URL matching), and `alien-middleware` (typed middleware chaining). The router output is intended to be used with `@hattip/core` adapters.
+
+## Install
+
+```sh
+pnpm add rouzer zod
+```
+
+Everything is imported directly from `rouzer`.
+
+## Define routes (shared)
+
+```ts
+// routes.ts
+import * as z from 'zod/mini'
+import { $type, route } from 'rouzer'
+
+export const helloRoute = route('hello/:name', {
+  GET: {
+    query: z.object({
+      excited: z.optional(z.boolean()),
+    }),
+    // The response is only type-checked at compile time.
+    response: $type<{ message: string }>(),
+  },
+})
+
+export const routes = { helloRoute }
+```
+
+The following request parts can be validated with Zod:
+
+- `path`
+- `query`
+- `body`
+- `headers`
+
+Zod validation happens on both the server and client.
+
+## Server router
+
+```ts
+import { chain, createRouter } from 'rouzer'
+import { routes } from './routes'
+
+const middlewares = chain().use(ctx => {
+  // An example middleware. For more info, see https://github.com/alien-rpc/alien-middleware#readme
+  return {
+    db: postgres(ctx.env('POSTGRES_URL')),
+  }
+})
+
+export const handler = createRouter({
+  routes,
+  middlewares,
+  debug: process.env.NODE_ENV === 'development',
+})({
+  helloRoute: {
+    GET(ctx) {
+      const message = `Hello, ${ctx.path.name}${ctx.query.excited ? '!' : '.'}`
+      return { message }
+    },
+  },
+})
+```
+
+## Client wrapper
+
+```ts
+import { createClient } from 'rouzer'
+import { helloRoute } from './routes'
+
+const client = createClient({ baseURL: '/api/' })
+
+const { message } = await client.json(
+  helloRoute.GET({ path: { name: 'world' }, query: { excited: true } })
+)
+
+// If you want the Response object, use `client.request` instead.
+const response = await client.request(
+  helloRoute.GET({ path: { name: 'world' } })
+)
+
+const { message } = await response.json()
+```
+
+## Add an endpoint
+
+1. Declare it in `routes.ts` with `route(...)` and `zod/mini` schemas.
+2. Implement the handler in your router assembly with `createRouter(…)({ ... })`.
+3. Call it from the client with the generated helper via `client.json` or `client.request`.