@stacksjs/bun-router 0.0.27 → 0.1.1

package/dist/typed/client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A client that knows what every endpoint takes and returns, with no
+ * generation step between changing a route and seeing the type change.
+ *
+ * Reads the route map straight out of `createTypedRouter()`'s type, so editing
+ * a handler's return shape or its `validations` is a compile error at every
+ * call site that disagrees - immediately, with no CLI run and no generated
+ * file that could still be holding yesterday's answer.
+ *
+ * ```ts
+ * import type { AppRoutes } from './routes'
+ * import { createTypedClient } from '@stacksjs/bun-router'
+ *
+ * const client = createTypedClient<AppRoutes>({ baseUrl: 'https://api.example.com' })
+ *
+ * const projects = await client.get('/v1/projects')
+ * const one = await client.get('/v1/projects/{id}', { params: { id: '42' } })
+ * const created = await client.post('/v1/projects', { name: 'apollo', budget: 1200 })
+ * ```
+ *
+ * A path the API does not serve is a compile error. A body that does not match
+ * the handler's declared input is a compile error. The awaited result is the
+ * handler's own return type.
+ *
+ * ## What it does not promise
+ *
+ * The output type is the handler's return type as TypeScript sees it, not a
+ * model of what JSON does to it - a `Date` in a response body arrives as a
+ * string, and the type will still say `Date`. A handler that returns a
+ * `Response` or a stream has taken over the wire format itself and is typed
+ * `unknown`, which is the honest answer.
+ *
+ * It speaks HTTP and nothing else: no router import, no server code, nothing
+ * that stops it being bundled for a browser.
+ */
+import type { PathsForMethod, RouteMapOf, TypedRouteMap } from './contract';
+/** A response the server refused. Carries the parsed body when there was one. */
+export declare class TypedClientError extends Error {
+    readonly status: number;
+    readonly response: Response;
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+export interface TypedClientOptions {
+    /** Where the API lives. A trailing slash is fine. */
+    baseUrl: string;
+    /**
+     * Headers on every request. A function is called per request, so an auth
+     * token that rotates does not have to be a new client.
+     */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    /** Swap the fetch implementation - a test double, or one that retries. */
+    fetch?: typeof globalThis.fetch;
+    credentials?: RequestInit['credentials'];
+    /**
+     * Called instead of throwing when the server answers 4xx/5xx. Return a value
+     * to have it become the call's result; throw to keep the default behaviour.
+     */
+    onError?: (error: TypedClientError) => unknown;
+}
+/** Per-call options. `params` is required when the path has any. */
+export interface TypedRequestOptions<TParams extends Record<string, string>> {
+    params?: TParams;
+    query?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+type Route<T, M extends string, P extends string> = RouteMapOf<T> extends infer R ? (R extends TypedRouteMap ? (`${M} ${P}` extends keyof R ? R[`${M} ${P}`] : never) : never) : never;
+type Input<T, M extends string, P extends string> = Route<T, M, P>['input'];
+type Output<T, M extends string, P extends string> = Route<T, M, P>['output'];
+type Params<T, M extends string, P extends string> = Route<T, M, P>['params'];
+type Paths<T, M extends string> = RouteMapOf<T> extends infer R ? (R extends TypedRouteMap ? PathsForMethod<R, M> : never) : never;
+export interface TypedClient<T> {
+    get: <P extends Paths<T, 'GET'>>(path: P, options?: TypedRequestOptions<Params<T, 'GET', P>>) => Promise<Output<T, 'GET', P>>;
+    post: <P extends Paths<T, 'POST'>>(path: P, body: Input<T, 'POST', P>, options?: TypedRequestOptions<Params<T, 'POST', P>>) => Promise<Output<T, 'POST', P>>;
+    put: <P extends Paths<T, 'PUT'>>(path: P, body: Input<T, 'PUT', P>, options?: TypedRequestOptions<Params<T, 'PUT', P>>) => Promise<Output<T, 'PUT', P>>;
+    patch: <P extends Paths<T, 'PATCH'>>(path: P, body: Input<T, 'PATCH', P>, options?: TypedRequestOptions<Params<T, 'PATCH', P>>) => Promise<Output<T, 'PATCH', P>>;
+    delete: <P extends Paths<T, 'DELETE'>>(path: P, options?: TypedRequestOptions<Params<T, 'DELETE', P>>) => Promise<Output<T, 'DELETE', P>>;
+    /**
+     * The untyped escape hatch, for when you need the `Response` itself -
+     * a redirect to follow by hand, a header to read, a body to stream.
+     */
+    raw: (method: string, path: string, init?: RequestInit & {
+        params?: Record<string, string>;
+        query?: Record<string, unknown>;
+    }) => Promise<Response>;
+}
+export declare function createTypedClient<T>(options: TypedClientOptions): TypedClient<T>;
+export {};

package/dist/typed/contract.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The contract between a typed router and a typed client.
+ *
+ * One route map, keyed `"METHOD /path"`, describing what each endpoint takes,
+ * what it answers with, and what its path needs. `createTypedRouter()`
+ * accumulates one of these into its own type as routes are registered;
+ * `createTypedClient()` reads it back. Nothing else needs to know it exists.
+ *
+ * It lives in its own module, with no imports, because both halves depend on
+ * it and neither should have to depend on the other.
+ */
+/** One route: what a client sends, what it gets back, what the path needs. */
+export interface TypedRoute {
+    input: unknown;
+    output: unknown;
+    params: Record<string, string>;
+}
+/** A whole API, keyed `"METHOD /path"` (e.g. `"GET /v1/projects"`). */
+export type TypedRouteMap = Record<string, TypedRoute>;
+/**
+ * The route map behind a typed router, or the map itself.
+ *
+ * `createTypedRouter()` accumulates its map into a phantom `__routes`
+ * property, so `typeof api` carries it and this reads it back out. Passing a
+ * map type directly works too, which is what an application that would rather
+ * name its API explicitly will export.
+ */
+export type RouteMapOf<T> = T extends {
+    __routes?: infer R;
+} ? ([R] extends [TypedRouteMap | undefined] ? NonNullable<R> : never) : (T extends TypedRouteMap ? T : never);
+/** The paths one method serves, as a union of path literals. */
+export type PathsForMethod<R extends TypedRouteMap, M extends string> = Extract<keyof R, `${M} ${string}`> extends `${M} ${infer P}` ? P : never;
+/** The HTTP methods a typed router registers. */
+export type TypedMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

package/dist/typed/endpoint.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Reading a handler's input and output types.
+ *
+ * A typed route map is only as good as what can be inferred about the handler
+ * behind it, and handlers come in more than one shape. Three are understood
+ * here, in order:
+ *
+ *   1. A plain function. Its return type is the output; the input is unknown,
+ *      because a function that reads `req.body` says nothing about what it
+ *      expects to find there.
+ *   2. An object with `handle()`. Same output inference, and if it also
+ *      carries a `validations` map, the input comes from that - the same
+ *      object the validator runs, so the two cannot drift.
+ *   3. Anything declaring an explicit `__input` phantom, which wins over
+ *      `validations`. The escape hatch for a handler that validates somewhere
+ *      this cannot see.
+ *
+ * Shape 2 is why a framework built on this router does not need its own
+ * builder: an "action" with `handle` and `validations` is structurally exactly
+ * what this reads.
+ */
+/** A validation rule, as `validations` maps are written. */
+export interface TypedRule<T = unknown> {
+    /**
+     * Names the value the rule accepts. Matches the `Validator<T>` shape that
+     * ts-validation (and anything else with a `test(value: T)` predicate) uses,
+     * which is how the input type is read without depending on a validator
+     * library.
+     */
+    test?: (value: T) => boolean;
+    validate: (value: any) => any;
+}
+/** A `validations:` map: one rule per field, optionally with a message. */
+export type TypedValidations = Record<string, {
+    rule: TypedRule<any>;
+    message?: unknown;
+}>;
+/** What a single rule accepts. */
+type RuleInput<R> = R extends {
+    test: (value: infer T) => boolean;
+} ? T : unknown;
+/** The body shape a `validations` map describes. */
+export type InputOfValidations<V> = V extends TypedValidations ? {
+    [K in keyof V]: RuleInput<V[K]['rule']>;
+} : Record<string, unknown>;
+/**
+ * What a client has to send to reach this handler.
+ *
+ * An explicit `__input` wins; otherwise `validations`; otherwise unknown-ish,
+ * which is the honest answer rather than a guess.
+ */
+export type InputOf<H> = H extends {
+    __input?: infer I;
+} ? ([I] extends [undefined] ? InputOfHandlerValidations<H> : NonNullable<I>) : InputOfHandlerValidations<H>;
+type InputOfHandlerValidations<H> = H extends {
+    validations: infer V;
+} ? InputOfValidations<V> : Record<string, unknown>;
+/**
+ * What a client gets back.
+ *
+ * A handler that returns a `Response` or a stream has taken over the wire
+ * format itself, so its shape is genuinely unknown here - saying so is more
+ * useful than pretending the client knows.
+ */
+export type OutputOf<H> = H extends {
+    handle: (..._args: any[]) => infer R;
+} ? NormalizeOutput<Awaited<R>> : (H extends (..._args: any[]) => infer R ? NormalizeOutput<Awaited<R>> : unknown);
+type NormalizeOutput<R> = [R] extends [Response | ReadableStream] ? unknown : R;
+/** Anything this module can read types out of. */
+export type TypedHandlerLike = ((..._args: any[]) => any) | {
+    handle: (..._args: any[]) => any;
+};
+/**
+ * Declare a handler's input and output explicitly.
+ *
+ * For the case shape 1 cannot cover: a plain function that validates its own
+ * body, where the router has no `validations` map to read. The returned value
+ * is the same function with an `__input` phantom attached, so it registers
+ * exactly as it would have.
+ *
+ * @example
+ * const createUser = defineEndpoint<{ name: string }, { id: number }>(async (req) => {
+ *   const body = await req.json()
+ *   return { id: 1 }
+ * })
+ */
+export declare function defineEndpoint<TInput, TOutput>(handle: (..._args: any[]) => TOutput | Promise<TOutput>): ((..._args: any[]) => TOutput | Promise<TOutput>) & {
+    __input?: TInput;
+};
+export {};

package/dist/typed/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Typed routes and the client that reads them.
+ *
+ * Three modules, deliberately separate: the contract both halves agree on, the
+ * builder that produces it, and the client that consumes it. The client
+ * imports only the contract, so it stays bundleable for a browser.
+ */
+export type { PathsForMethod, RouteMapOf, TypedMethod, TypedRoute, TypedRouteMap } from './contract';
+export { createTypedClient, TypedClientError } from './client';
+export type { TypedClient, TypedClientOptions, TypedRequestOptions } from './client';
+export { defineEndpoint } from './endpoint';
+export type { InputOf, InputOfValidations, OutputOf, TypedHandlerLike, TypedRule, TypedValidations } from './endpoint';
+export { createTypedRouter } from './router';
+export type { RoutesOf, TypedRouteParams, TypedRegistrar, TypedRouteOptions, TypedRouter } from './router';

package/dist/typed/router.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Routes a TypeScript consumer can see the shape of, with no generation step.
+ *
+ * ## What this is for
+ *
+ * `router.get('/v1/projects', handler)` tells the compiler nothing a client
+ * could use. The path is a string, the handler returns a `Response`, and the
+ * only route-aware client you could offer was one generated from an OpenAPI
+ * document by running a CLI command - which has to be re-run, and whose output
+ * goes stale the moment a route changes.
+ *
+ * This builder registers through the router it is given, exactly as you would
+ * by hand, while accumulating a route map into its own type as you chain:
+ *
+ * ```ts
+ * export const api = createTypedRouter(router)
+ *   .get('/v1/projects', listProjects)
+ *   .post('/v1/projects', createProject)
+ *
+ * export type AppRoutes = typeof api
+ * ```
+ *
+ * ```ts
+ * // any TypeScript consumer, same repo or a package away
+ * import { createTypedClient } from '@stacksjs/bun-router'
+ *
+ * const client = createTypedClient<AppRoutes>({ baseUrl: 'https://api.example.com' })
+ * const projects = await client.get('/v1/projects')   // typed, no CLI step
+ * ```
+ *
+ * Registration goes through the ordinary router, so there is exactly one
+ * runtime dispatch path and the difference from a hand-written route is
+ * entirely at compile time.
+ *
+ * ## What it reads
+ *
+ * See `./endpoint.ts`. A plain function gives its return type; an object with
+ * `handle()` gives the same, plus its input from a `validations` map when it
+ * has one. That second shape is deliberate: a framework built on this router
+ * whose "actions" are `{ handle, validations }` objects gets typed routes from
+ * this builder without needing one of its own.
+ *
+ * ## What it is not
+ *
+ * Not a replacement for `router.get(...)`, which stays exactly as it is for
+ * every route that would rather be lazy than inferable, and not a replacement
+ * for OpenAPI, which remains the answer for consumers that are not TypeScript
+ * in this repo.
+ *
+ * ## Groups
+ *
+ * There is deliberately no `.group()`. A prefix applied only at runtime makes
+ * every accumulated path type wrong, and one applied only in the type is a
+ * second place for the URL to be written down. Write the full path; it is what
+ * the client will show you anyway.
+ */
+import type { ExtractRouteParams } from '../types';
+import type { TypedRouteMap } from './contract';
+import type { InputOf, OutputOf, TypedHandlerLike } from './endpoint';
+/**
+ * A path's params, normalized.
+ *
+ * `ExtractRouteParams` answers `object` for a path with no parameters, which
+ * would let a client pass anything. An empty record says what is meant.
+ */
+export type TypedRouteParams<P extends string> = keyof ExtractRouteParams<P> extends never ? Record<string, never> : ExtractRouteParams<P>;
+type Entry<P extends string, H> = {
+    input: InputOf<H>;
+    output: OutputOf<H>;
+    params: TypedRouteParams<P>;
+};
+/**
+ * Per-route settings.
+ *
+ * An argument rather than a chained call, because chaining `.middleware()`
+ * would return the route and lose the accumulated map. Applied by calling the
+ * matching method on whatever the registrar returned, so a router whose
+ * `get()` returns a chainable route supports all of them; see
+ * {@link TypedRegistrar}.
+ */
+export interface TypedRouteOptions {
+    middleware?: string | readonly string[];
+    name?: string;
+    skipCsrf?: boolean;
+    requireCsrf?: boolean;
+    rateLimit?: {
+        max: number;
+        window?: 'second' | 'minute' | 'hour' | 'day' | number;
+    };
+}
+/**
+ * Anything that can register a route.
+ *
+ * `Router` satisfies this, and so does any wrapper around it. The return value
+ * is whatever that router hands back: when it is a chainable route,
+ * {@link TypedRouteOptions} are applied to it.
+ */
+export interface TypedRegistrar {
+    get: (path: string, handler: any) => unknown;
+    post: (path: string, handler: any) => unknown;
+    put: (path: string, handler: any) => unknown;
+    patch: (path: string, handler: any) => unknown;
+    delete: (path: string, handler: any) => unknown;
+}
+/**
+ * The builder. Each method returns the same object at runtime and a wider type
+ * at compile time, which is what puts the route map in `typeof api` without
+ * anything being written down twice.
+ */
+export interface TypedRouter<R extends TypedRouteMap = {}> {
+    /**
+     * Phantom. Never set at runtime; it is where `RouteMapOf` reads the
+     * accumulated map from.
+     */
+    readonly __routes?: R;
+    get: <P extends string, H extends TypedHandlerLike>(path: P, handler: H, options?: TypedRouteOptions) => TypedRouter<R & {
+        [K in `GET ${P}`]: Entry<P, H>;
+    }>;
+    post: <P extends string, H extends TypedHandlerLike>(path: P, handler: H, options?: TypedRouteOptions) => TypedRouter<R & {
+        [K in `POST ${P}`]: Entry<P, H>;
+    }>;
+    put: <P extends string, H extends TypedHandlerLike>(path: P, handler: H, options?: TypedRouteOptions) => TypedRouter<R & {
+        [K in `PUT ${P}`]: Entry<P, H>;
+    }>;
+    patch: <P extends string, H extends TypedHandlerLike>(path: P, handler: H, options?: TypedRouteOptions) => TypedRouter<R & {
+        [K in `PATCH ${P}`]: Entry<P, H>;
+    }>;
+    delete: <P extends string, H extends TypedHandlerLike>(path: P, handler: H, options?: TypedRouteOptions) => TypedRouter<R & {
+        [K in `DELETE ${P}`]: Entry<P, H>;
+    }>;
+}
+/** The accumulated route map, pulled back out of a builder's type. */
+export type RoutesOf<T> = T extends TypedRouter<infer R> ? R : never;
+/**
+ * Build a typed route group on top of a router.
+ *
+ * Routes land in that router's table exactly as if they had been registered by
+ * hand; the only difference is that the builder's own type remembers them.
+ */
+export declare function createTypedRouter(router: TypedRegistrar): TypedRouter;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/bun-router",
   "type": "module",
-  "version": "0.0.27",
+  "version": "0.1.1",
   "description": "A fast, type-safe router for Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",

package/dist/chunk-1ahs68ys.js

@@ -1,18 +0,0 @@
-// @bun
-var __defProp = Object.defineProperty;
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: __exportSetter.bind(all, name)
-    });
-};
-var __require = import.meta.require;
-
-export { __export, __require };