@stacksjs/bun-router 0.1.2 → 0.1.3

package/dist/request/cookie-accessor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One `request.cookies`, built one way.
+ *
+ * There were three constructions of this object - one in the router, one in
+ * `testing/test-request`, one in `testing/auth-testing` - and the server built
+ * a fourth, different one through a macro accessor. Only the macro's was the
+ * real shape: callable, carrying the name→value entries directly, AND holding
+ * `get`/`set`/`delete`/`getAll`. The other three were plain method bags, so a
+ * handler written against a real request (`req.cookies()`, `req.cookies.session`)
+ * broke the moment it met a test request, and the declared type described none
+ * of them completely.
+ *
+ * This is the one builder. The differences that are real - where a read comes
+ * from, where a write goes - are parameters.
+ */
+import type { CookieAccessor, CookieOptions } from '../types';
+export interface CookieAccessorSinks {
+    /** The current cookie map. Called on every read, so it can stay lazy. */
+    read: () => Record<string, string>;
+    /** Where a `set` goes. Omitted, `set` is a no-op. */
+    write?: (name: string, value: string, options: CookieOptions) => void;
+    /** Where a `delete` goes. Omitted, `delete` is a no-op. */
+    remove?: (name: string, options: CookieOptions) => void;
+}
+export declare function createCookieAccessor(sinks: CookieAccessorSinks): CookieAccessor;
+/**
+ * A cookie accessor backed by a mutable in-memory map.
+ *
+ * What a test request wants: `set` and `delete` take effect immediately and are
+ * visible to the next read, rather than being queued onto a response that does
+ * not exist.
+ */
+export declare function createInMemoryCookieAccessor(initial?: Record<string, string>): CookieAccessor;

package/dist/router/middleware-groups.d.ts

@@ -1,4 +1,4 @@
-import type { MiddlewareHandler } from '../types';
+import type { MiddlewareHandler, MiddlewareReference } from '../types';
 /**
  * Middleware Group Registry
  *
@@ -20,19 +20,19 @@ export declare class MiddlewareGroupRegistry {
     /**
      * Define a middleware group
      */
-    define(name: string, middleware: (string | MiddlewareHandler)[]): this;
+    define(name: string, middleware: (MiddlewareReference | MiddlewareHandler)[]): this;
     /**
      * Extend an existing group with additional middleware
      */
-    extend(name: string, middleware: (string | MiddlewareHandler)[]): this;
+    extend(name: string, middleware: (MiddlewareReference | MiddlewareHandler)[]): this;
     /**
      * Prepend middleware to an existing group
      */
-    prepend(name: string, middleware: (string | MiddlewareHandler)[]): this;
+    prepend(name: string, middleware: (MiddlewareReference | MiddlewareHandler)[]): this;
     /**
      * Get middleware for a group
      */
-    get(name: string): (string | MiddlewareHandler)[];
+    get(name: string): (MiddlewareReference | MiddlewareHandler)[];
     /**
      * Check if a group exists
      */
@@ -42,21 +42,26 @@ export declare class MiddlewareGroupRegistry {
      */
     remove(name: string): this;
     /**
-     * Resolve a middleware reference, expanding group names into their middleware
+     * Resolve a middleware reference, expanding group names into their middleware.
+     *
+     * A group name is a middleware reference as far as a caller is concerned -
+     * you write `.middleware('web')` and get the group - so an application that
+     * declares its aliases in `RouterTypeRegistry` lists its group names there
+     * too.
      */
-    resolve(middleware: string | MiddlewareHandler): (string | MiddlewareHandler)[];
+    resolve(middleware: MiddlewareReference | MiddlewareHandler): (MiddlewareReference | MiddlewareHandler)[];
     /**
      * Resolve multiple middleware references, expanding groups
      */
-    resolveAll(middleware: (string | MiddlewareHandler)[]): (string | MiddlewareHandler)[];
+    resolveAll(middleware: (MiddlewareReference | MiddlewareHandler)[]): (MiddlewareReference | MiddlewareHandler)[];
     /**
      * Add middleware to the global stack (runs on every request)
      */
-    pushGlobal(...middleware: (string | MiddlewareHandler)[]): this;
+    pushGlobal(...middleware: (MiddlewareReference | MiddlewareHandler)[]): this;
     /**
      * Prepend middleware to the global stack
      */
-    prependGlobal(...middleware: (string | MiddlewareHandler)[]): this;
+    prependGlobal(...middleware: (MiddlewareReference | MiddlewareHandler)[]): this;
     /**
      * Remove middleware from the global stack
      */
@@ -64,7 +69,7 @@ export declare class MiddlewareGroupRegistry {
     /**
      * Get the global middleware stack
      */
-    getGlobal(): (string | MiddlewareHandler)[];
+    getGlobal(): (MiddlewareReference | MiddlewareHandler)[];
     /**
      * Set execution priority for a middleware (lower = runs first)
      */
@@ -72,17 +77,17 @@ export declare class MiddlewareGroupRegistry {
     /**
      * Sort middleware by priority
      */
-    sortByPriority(middleware: (string | MiddlewareHandler)[]): (string | MiddlewareHandler)[];
+    sortByPriority(middleware: (MiddlewareReference | MiddlewareHandler)[]): (MiddlewareReference | MiddlewareHandler)[];
     /**
      * Filter middleware by applying except/only rules.
      *
      * @param middleware - Full middleware list
      * @param options - except or only filter
      */
-    filter(middleware: (string | MiddlewareHandler)[], options: {
+    filter(middleware: (MiddlewareReference | MiddlewareHandler)[], options: {
         except?: string[];
         only?: string[];
-    }): (string | MiddlewareHandler)[];
+    }): (MiddlewareReference | MiddlewareHandler)[];
     /**
      * Clear all groups and global middleware
      */

package/dist/router/router.d.ts

@@ -1,6 +1,6 @@
 import type { Server } from 'bun';
 import type { MiddlewareDependency, MiddlewarePipeline, MiddlewarePipelineStats, MiddlewareSkipCondition } from '../middleware/pipeline';
-import type { ActionHandler, CookieOptions, EnhancedRequest, MiddlewareHandler, Route, RouteGroup, RouteHandler, RouterConfig, WebSocketConfig, WebSocketData } from '../types';
+import type { ActionHandler, CookieOptions, EnhancedRequest, MiddlewareHandler, MiddlewareReference, Route, RouteGroup, RouteHandler, RouterConfig, TypedRouteHandler, WebSocketConfig, WebSocketData } from '../types';
 /**
  * Route compiler interface for pattern matching
  */
@@ -95,7 +95,7 @@ export declare class Router {
      * Internal method to add a route with full HTTP method support
      * This is the core route registration method used by get/post/put/patch/delete
      */
-    registerRoute(method: string, path: string, handler: ActionHandler, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    registerRoute(method: string, path: string, handler: ActionHandler, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * Resolve middleware from string or handler (synchronous)
      */
@@ -118,43 +118,51 @@ export declare class Router {
      * keep working — `ActionHandler<TPath>` is a union that accepts them.
      * See stacksjs/stacks#1851 for the broader typed-request work.
      */
-    get<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    get<TPath extends string>(path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    get<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * HTTP POST method. See {@link get} for `TPath`-driven param
      * narrowing on inline handlers.
      */
-    post<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    post<TPath extends string>(path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    post<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * HTTP PUT method. See {@link get} for `TPath`-driven param
      * narrowing on inline handlers.
      */
-    put<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    put<TPath extends string>(path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    put<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * HTTP PATCH method. See {@link get} for `TPath`-driven param
      * narrowing on inline handlers.
      */
-    patch<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    patch<TPath extends string>(path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    patch<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * HTTP DELETE method. See {@link get} for `TPath`-driven param
      * narrowing on inline handlers.
      */
-    delete<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    delete<TPath extends string>(path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    delete<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * HTTP OPTIONS method. See {@link get} for `TPath`-driven param
      * narrowing on inline handlers.
      */
-    options<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    options<TPath extends string>(path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    options<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * Register the same handler against multiple HTTP methods. The
      * handler is type-narrowed via {@link ActionHandler}'s `TPath`
      * generic, same as the single-method overloads.
      */
-    match<TPath extends string>(methods: string[], path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    match<TPath extends string>(methods: string[], path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    match<TPath extends string>(methods: string[], path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * Register the handler against every HTTP method. See {@link get}
      * for `TPath`-driven param narrowing on inline handlers.
      */
-    any<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (string | MiddlewareHandler)[]): Router;
+    any<TPath extends string>(path: TPath, handler: TypedRouteHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
+    any<TPath extends string>(path: TPath, handler: ActionHandler<TPath>, type?: 'api' | 'web', name?: string, middleware?: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * Register redirect route
      */
@@ -197,7 +205,7 @@ export declare class Router {
     /**
      * Add middleware to the router
      */
-    use(...middleware: (string | MiddlewareHandler)[]): Router;
+    use(...middleware: (MiddlewareReference | MiddlewareHandler)[]): Router;
     /**
      * Create a route group with prefix and middleware.
      *
@@ -208,11 +216,11 @@ export declare class Router {
      */
     group(options: {
         prefix?: string;
-        middleware?: (string | MiddlewareHandler)[];
+        middleware?: (MiddlewareReference | MiddlewareHandler)[];
     }, callback: () => Promise<void>): Promise<Router>;
     group(options: {
         prefix?: string;
-        middleware?: (string | MiddlewareHandler)[];
+        middleware?: (MiddlewareReference | MiddlewareHandler)[];
     }, callback: () => void): Router;
     /**
      * Add route to the router

package/dist/types/registry.d.ts

@@ -0,0 +1,93 @@
+import type { BuiltInMiddleware } from '../types';
+/**
+ * What an application tells the router about itself.
+ *
+ * A router deals in strings that are really identifiers: `'Actions/CreateUser'`
+ * names a file, `'auth'` names a middleware, `'users.show'` names a route. The
+ * compiler has no idea which of them exist, so a typo in any of the three is a
+ * runtime error at best — a silently unprotected endpoint at worst, when the
+ * typo is in a middleware alias.
+ *
+ * The router cannot know them either. The application can, so it says so, by
+ * augmenting this interface:
+ *
+ * ```ts
+ * // types/router.d.ts
+ * declare module '@stacksjs/bun-router' {
+ *   interface RouterTypeRegistry {
+ *     actions: 'Actions/CreateUser' | 'Actions/ListUsers'
+ *     middleware: 'auth' | 'throttle' | 'signed'
+ *     routes: {
+ *       'users.index': '/users'
+ *       'users.show': '/users/{id}'
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * From then on, `router.post('/users', 'Actions/CreateUsr')` is a compile
+ * error, so is `.middleware('atuh')`, and `url('users.show')` demands an `id`
+ * because the path says it has one.
+ *
+ * ## Nothing is required
+ *
+ * Every key is independent, and every one falls back to exactly the type it had
+ * before this existed when it is absent. An application that declares none of
+ * them sees no change at all. That is the point: this cannot be a breaking
+ * change, and it cannot be a thing you must do before the router is usable.
+ *
+ * ## Generating it
+ *
+ * The three unions are facts a build step already knows. A framework on top of
+ * this router that scans `app/Actions/` or a middleware alias map can emit the
+ * augmentation into a `.d.ts` and the whole surface types itself with nothing
+ * hand-written. Writing it by hand works just as well for a smaller app.
+ */
+export interface RouterTypeRegistry {
+}
+/**
+ * Read a key out of the registry, or fall back.
+ *
+ * `K extends keyof RouterTypeRegistry` is `never extends never` — false — while
+ * the interface is empty, which is what makes every fallback the default. The
+ * second check keeps a malformed augmentation (say, `actions: number`) from
+ * poisoning the type: it falls back rather than producing something unusable.
+ */
+export type FromRegistry<TKey extends string, TFallback> = TKey extends keyof RouterTypeRegistry ? (RouterTypeRegistry[TKey] extends TFallback ? RouterTypeRegistry[TKey] : TFallback) : TFallback;
+/**
+ * The action paths this application has, or the shape of one when it has not
+ * said.
+ *
+ * The fallback is the pattern that was here before: anything under `Actions/`
+ * ending in `Action`, or a `Controller@method` reference. It catches a shape
+ * mistake and nothing else, which is why declaring the real set is worth doing.
+ */
+export type KnownActionPath = FromRegistry<'actions', `Actions/${string}Action` | `actions/${string}Action` | `${string}Controller@${string}`>;
+/**
+ * The middleware aliases this application registers, or any string.
+ *
+ * Middleware group names belong here too: a group name is a middleware
+ * reference as far as a call site is concerned - `.middleware('web')` expands
+ * to the group - so the union has to contain both or the group form stops
+ * type-checking the moment anything is declared.
+ */
+export type KnownMiddlewareName = FromRegistry<'middleware', string>;
+/**
+ * A middleware reference: an alias, or an alias with parameters.
+ *
+ * `'throttle:60,1'` and `'can:view,post'` are how parameters are passed, so a
+ * declared alias has to keep accepting its parameterised form.
+ *
+ * The built-ins are always allowed alongside whatever the application declares.
+ * An app listing its own aliases is saying "these are mine", not "the ones this
+ * package ships no longer exist" - and the router's own default middleware
+ * groups are built from them, so narrowing them away would make the package
+ * fail to describe itself.
+ */
+export type MiddlewareReference = BuiltInMiddleware | `${BuiltInMiddleware}:${string}` | KnownMiddlewareName | `${KnownMiddlewareName}:${string}`;
+/** The named routes this application registers, as `name → path`. */
+export type KnownRoutes = FromRegistry<'routes', Record<string, string>>;
+/** The names of those routes, or any string when none are declared. */
+export type KnownRouteName = keyof KnownRoutes extends never ? string : Extract<keyof KnownRoutes, string>;
+/** The path a declared route name resolves to, or any path when it is not declared. */
+export type PathForRouteName<TName extends string> = TName extends keyof KnownRoutes ? Extract<KnownRoutes[TName], string> : string;

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Server } from 'bun';
 import type { Router } from './router/router';
+import type { KnownActionPath, MiddlewareReference } from './types/registry';
 import type { SessionManager } from './session/index';
 import type { QueryPreservationConfig } from './utils/query-preservation';
 import type { AuthContext, AuthenticatedUser, BoundModels, CacheAdapter, CacheStats, CookieToDelete, CookieToSet, ErrorMetadata, FallbackError, FileInfo, FlashMessages, FormBody, InputValidationSchemas, InputValue, JsonBodyData, JwtHeader, JwtPayload, MetricEntry, MiddlewareParams, OAuth2Flows, OAuth2Profile, RequestContext, RequestInput, RouteMetadata, SanitizationOptions, SanitizationRule, SessionData, SessionSerializer, SessionStore, SSEConnection, StaticResponseBody, TemplateHelper, TemplateHelpers, TraceAttributes, TraceSpan, TypedServerWebSocket, User, ValidatedBody, ValidatedData, ValidationSchema, WebSocketData } from './types/core';
@@ -629,8 +630,8 @@ export interface RouterConfig {
      */
     controllersPath?: string;
     defaultMiddleware?: {
-        api?: (string | MiddlewareHandler)[];
-        web?: (string | MiddlewareHandler)[];
+        api?: (MiddlewareReference | MiddlewareHandler)[];
+        web?: (MiddlewareReference | MiddlewareHandler)[];
     };
     /**
      * View engine configuration
@@ -678,13 +679,26 @@ export interface CookieOptions {
 /**
  * Cookie accessor interface with utility methods
  */
+/**
+ * `request.cookies`, in all three of the shapes it actually has.
+ *
+ * The server installs a hybrid: a function returning the parsed map, carrying
+ * the name→value entries as own properties, with `get`/`set`/`delete`/`getAll`
+ * on top. The declaration described only the last of those, so `req.cookies()`
+ * and `req.cookies.session` were both type errors against a runtime that
+ * supports them, and userland reached for `as any` to get at either.
+ */
 export interface CookieAccessor {
+    /** The whole parsed cookie map. */
+    (): Record<string, string>;
+    /** Direct access by name: `req.cookies.session`. */
+    [name: string]: unknown;
     get: (name: string) => string | undefined;
     set: (name: string, value: string, options?: CookieOptions) => void;
     delete: (name: string, options?: CookieOptions) => void;
     getAll: () => Record<string, string>;
 }
-export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip' | 'cookies' | 'route'> {
+export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'cookies' | 'route'> {
     /**
      * Route parameters extracted from the URL
      */
@@ -761,13 +775,10 @@ export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip'
      */
     requestId?: string;
     /**
-     * IP address of the client (string property, not function from RequestMacroMethods)
-     */
-    ip?: string;
-    /**
-     * Cookies parsed from the request with utility methods
+     * Cookies parsed from the request. Callable, indexable, and carrying
+     * get/set/delete/getAll - see {@link CookieAccessor}.
      */
-    cookies?: CookieAccessor;
+    cookies: CookieAccessor;
     /**
      * Flash messages (temporary messages for the next request)
      */
@@ -833,11 +844,23 @@ export interface ActionHandlerClass {
     handle: (request: EnhancedRequest) => Promise<Response>;
 }
 /**
- * Action handler path with strict pattern validation
+ * Action handler path.
+ *
+ * The real set of actions when the application declares one through
+ * {@link RouterTypeRegistry}, and the shape of an action path otherwise — which
+ * catches `'Acton/CreateUser'` and nothing else. See `./types/registry.ts`.
  */
-export type ActionPath = `Actions/${string}Action` | `actions/${string}Action` | `${string}Controller@${string}`;
+export type ActionPath = KnownActionPath;
 /**
- * Strongly typed action handler with better type safety
+ * Strongly typed action handler: every form a route will accept.
+ *
+ * Note that the route-registering methods do NOT take this as a single
+ * parameter. A parameter typed as a union containing two call signatures gives
+ * TypeScript nothing to contextually type an inline arrow with, so
+ * `router.get('/users/{id}', req => …)` left `req` implicitly `any` - the exact
+ * opposite of what the path generic exists for. They declare
+ * {@link TypedRouteHandler} as a first overload and this as the fallback, which
+ * types the inline case and keeps every other form working.
  */
 export type ActionHandler<TPath extends string = string> = ActionPath | TypedRouteHandler<TPath> | RouteHandler | (new () => ActionHandlerClass) | Response;
 /**
@@ -935,7 +958,7 @@ export interface AuthMiddlewareConfig {
 }
 export interface RouteGroup {
     prefix?: string;
-    middleware?: (string | MiddlewareHandler)[];
+    middleware?: (MiddlewareReference | MiddlewareHandler)[];
 }
 export interface Route {
     path: string;
@@ -1112,7 +1135,21 @@ export type SecurityHeader = 'Content-Security-Policy' | 'X-Frame-Options' | 'X-
 /**
  * Built-in middleware names - extremely narrow
  */
-export type BuiltInMiddleware = 'auth' | 'cors' | 'csrf' | 'helmet' | 'json' | 'compress' | 'static' | 'session' | 'rateLimiter' | 'requestId' | 'logger' | 'throttle';
+/**
+ * The middleware this package ships, by the name it is actually registered
+ * under.
+ *
+ * This list used to be a guess and disagreed with the package in several
+ * places: it offered `json`, `rateLimiter`, `requestId`, `compress`, `static`
+ * and `logger`, none of which exist, while the real `json_body`, `rate_limit`,
+ * `request_id`, `security` and `ddos_protection` - the ones the default
+ * middleware groups in `config.ts` are built from - were missing. Anything
+ * typed against it was being checked against fiction.
+ *
+ * Every name here is a module under `src/middleware/`, plus the three aliases
+ * `Router` registers itself.
+ */
+export type BuiltInMiddleware = 'auth' | 'content_security_policy' | 'cors' | 'csrf' | 'ddos_protection' | 'file_security' | 'file_upload' | 'helmet' | 'input_validation' | 'json_body' | 'performance_alerting' | 'performance_dashboard' | 'performance_monitor' | 'rate_limit' | 'request_id' | 'request_signing' | 'request_tracer' | 'response_cache' | 'security' | 'security_suite' | 'session' | 'throttle';
 /**
  * Middleware with parameters
  */
@@ -1175,10 +1212,19 @@ export type ContentType = 'application/json' | 'application/xml' | 'text/html' |
 /**
  * Strongly typed route method signatures
  */
+/**
+ * A request whose `params` are exactly the ones its path declares.
+ *
+ * `Omit` first, because `EnhancedRequest.params` is `Record<string, string>`
+ * and an intersection with it widens the narrowed keyset straight back:
+ * `req.params.slugTypo` type-checked happily and returned `undefined` at
+ * runtime, which is the failure a typed router exists to prevent.
+ */
+export type RequestFor<TPath extends string> = Omit<EnhancedRequest, 'params'> & {
+    params: ExtractRouteParams<TPath>;
+};
 export interface TypedRouteHandler<TPath extends string> {
-    (req: EnhancedRequest & {
-        params: ExtractRouteParams<TPath>;
-    }): Response | Promise<Response>;
+    (req: RequestFor<TPath>): Response | Promise<Response>;
 }
 /**
  * Strongly typed route definition for specific HTTP methods
@@ -1860,3 +1906,4 @@ export interface EnhancedLaravelModelBindingMethods {
      */
     scopedBindings: <Parent extends string, Child extends string>(bindings: Record<Child, Parent>) => MiddlewareHandler;
 }
+export type { FromRegistry, KnownActionPath, KnownMiddlewareName, KnownRouteName, KnownRoutes, MiddlewareReference, PathForRouteName, RouterTypeRegistry, } from './types/registry';

package/dist/url.d.ts

@@ -6,6 +6,8 @@
  * resolves a registered name into a URL with path parameters substituted
  * and unmatched params appended as a query string.
  */
+import type { ExtractRouteParams } from './types';
+import type { KnownRouteName, PathForRouteName } from './types/registry';
 /**
  * Register a named-route path. Called by Router/FluentRouter when a route
  * gets a `.name()`.
@@ -25,6 +27,36 @@ export declare function getNamedRoutes(): ReadonlyMap<string, string>;
  * Clear the registry. Provided for tests; production code should not need it.
  */
 export declare function clearNamedRoutes(): void;
+/**
+ * The params a named route needs, plus anything else you want in the query.
+ *
+ * The required half comes from the path the name resolves to, so
+ * `url('users.show')` with no `id` is a compile error once the application has
+ * declared its routes. Extra keys stay allowed on purpose: the implementation
+ * appends whatever it did not consume as a query string, which is a real
+ * feature and not a mistake to be typed away.
+ */
+export type UrlParams<TName extends string> = ParamValues<ExtractRouteParams<PathForRouteName<TName>>> & Record<string, string | number | boolean>;
+/**
+ * Path params are strings on the wire, but `url()` stringifies whatever it is
+ * given - so `url('users.show', { id: 42 })` is correct and should type as
+ * correct. Homomorphic, so an optional `{slug?}` stays optional.
+ */
+type ParamValues<TParams> = {
+    [K in keyof TParams]: string | number | boolean;
+};
+/** The keys of `T` that are not optional. */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: object extends Pick<T, K> ? never : K;
+}[keyof T];
+/**
+ * `url()` takes no second argument when the route needs no parameters.
+ *
+ * Keyed on REQUIRED params, not all of them: a path whose only parameter is
+ * optional (`/posts/{slug?}`) is reachable with nothing at all, and demanding
+ * an empty object for it would be the type getting in the way of the truth.
+ */
+type RequiresParams<TName extends string> = [RequiredKeys<ExtractRouteParams<PathForRouteName<TName>>>] extends [never] ? false : true;
 export interface UrlOptions {
     /**
      * Return a fully-qualified URL using `process.env.APP_URL` (falling back to
@@ -53,4 +85,5 @@ export interface UrlOptions {
  * // → 'https://app.example/users/42'  (when APP_URL=https://app.example)
  * ```
  */
-export declare function url(name: string, params?: Record<string, string | number | boolean>, options?: UrlOptions): string;
+export declare function url<TName extends KnownRouteName>(name: TName, ...rest: RequiresParams<TName> extends true ? [params: UrlParams<TName>, options?: UrlOptions] : [params?: UrlParams<TName>, options?: UrlOptions]): string;
+export {};

package/package.json

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