@stacksjs/bun-router 0.0.16 → 0.0.18

package/dist/testing/websocket-testing.d.ts

@@ -172,7 +172,7 @@ export declare const wsAssertions: {
     /**
      * Assert message type
      */
-    messageType: (tester: WebSocketTester, index: number, expectedType: "text" | "binary") => void;
+    messageType: (tester: WebSocketTester, index: number, expectedType: 'text' | 'binary') => void;
     /**
      * Assert ready state
      */

package/dist/types/middleware-types.d.ts

@@ -4,7 +4,7 @@
  * Advanced TypeScript utilities for type-safe middleware with generic constraints
  */
 import type { RouteHandler, TypedRequest } from './route-inference';
-export interface TypedMiddleware<TInput = any, TOutput = TInput, _TContext = object, TNext = any> {
+export interface TypedMiddleware<TInput = Request, TOutput = Response, _TContext = object, TNext = () => Promise<TOutput>> {
     (request: TInput, next: TNext): Promise<TOutput> | TOutput;
 }
 export type AugmentContext<TBase, TAddition> = TBase & TAddition;

package/dist/types/route-inference.d.ts

@@ -3,7 +3,13 @@
  *
  * Advanced TypeScript utilities for inferring route parameter types from URL patterns
  */
-export type ExtractRouteParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+/** Strip an inline constraint from a brace parameter: `id:[0-9]+` → `id` */
+type StripInlineConstraint<T extends string> = T extends `${infer Name}:${string}` ? Name : T;
+export type ExtractRouteParams<T extends string> = T extends `${string}{${infer Param}}${infer Rest}` ? (Param extends `${infer Inner}?` ? {
+    [K in StripInlineConstraint<Inner>]?: string;
+} : {
+    [K in StripInlineConstraint<Param>]: string;
+}) & ExtractRouteParams<Rest> : T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
     [K in Param]: string;
 } & ExtractRouteParams<`/${Rest}`> : T extends `${infer _Start}:${infer Param}?${infer Rest}` ? {
     [K in Param]?: string;
@@ -100,7 +106,7 @@ export interface RouteGroup<TPrefix extends string = '', TContext = object> {
     middleware?: TypedMiddleware<any, any, any, TContext>[];
     routes: TypedRoute<any, any, any, TContext>[];
 }
-export interface TypedMiddleware<TRequest = any, TResponse = any, TNext = any, _TContext = Record<string, never>> {
+export interface TypedMiddleware<TRequest = Request, TResponse = Response, TNext = () => Promise<TResponse>, _TContext = Record<string, never>> {
     (request: TRequest, next: TNext): Promise<TResponse> | TResponse;
 }
 export interface RouteBuilder<TContext = object> {
@@ -166,3 +172,4 @@ export interface GenerateOpenAPISchema<T extends TypedRoute<any, any, any, any>>
 export type AssertEqual<T, U> = T extends U ? U extends T ? true : false : false;
 export type AssertExtends<T, U> = T extends U ? true : false;
 export type AssertNotEqual<T, U> = AssertEqual<T, U> extends true ? false : true;
+export {};

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Server } from 'bun';
 import type { Router } from './router/router';
+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';
 export type { QueryPreservationConfig } from './utils/query-preservation';
@@ -702,6 +703,12 @@ export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip'
      * Parsed JSON body (if Content-Type is application/json)
      */
     jsonBody?: Record<string, unknown>;
+    /**
+     * Raw unparsed request body cache, populated on first `rawBody()` read (or up
+     * front by a framework body parser). Kept so webhook signature checks get the
+     * exact bytes the client sent.
+     */
+    _rawBody?: string;
     /**
      * Form body data (if Content-Type is multipart/form-data or application/x-www-form-urlencoded)
      */
@@ -711,9 +718,11 @@ export interface EnhancedRequest extends Request, Omit<RequestMacroMethods, 'ip'
      */
     files?: UploadedFile[];
     /**
-     * Session data (if session middleware is used)
+     * Session for the current request. The built-in session middleware
+     * attaches a `SessionManager` (with `get`/`set`/`flash`/… methods);
+     * testing utilities may attach plain `SessionData`.
      */
-    session?: SessionData;
+    session?: SessionManager | SessionData;
     /**
      * User data (if authentication middleware is used)
      */
@@ -936,6 +945,13 @@ export interface Route {
     pattern?: {
         exec: (url: URL) => PatternMatchResult | null;
     };
+    /**
+     * Set to `false` (via `router.withoutNativeDispatch()`) to keep this
+     * route on the fetch-handler matcher even when the server runs with
+     * `nativeRoutes: true` — e.g. when it must respect registration-order
+     * precedence against an overlapping pattern.
+     */
+    nativeDispatch?: boolean;
 }
 /**
  * WebSocket handler configuration
@@ -967,6 +983,22 @@ export interface ServerOptions<T extends WebSocketData = WebSocketData> extends
      * These bypass the fetch handler entirely for zero-allocation serving (~15% faster).
      */
     static?: Record<string, Response>;
+    /**
+     * Opt-in: register compatible routes with `Bun.serve`'s native router
+     * (`routes`), skipping the fetch handler's URL parsing and route
+     * matching for them. Compatible means: standard HTTP method, no
+     * domain scoping, no `where()`/inline constraints, no optional
+     * params, and `{param}`s spanning whole segments. Everything else —
+     * incompatible routes, 404/405 handling, HEAD fallback, the generic
+     * OPTIONS preflight — still flows through the fetch handler with
+     * identical semantics.
+     *
+     * Caveat: Bun matches by specificity (exact > param > wildcard).
+     * Apps that rely on registration order between same-shape overlapping
+     * patterns should leave this off. Routes registered after `serve()`
+     * only join the native table after `reload()`.
+     */
+    nativeRoutes?: boolean;
     /**
      * Development mode options for Bun's dev server.
      * When true, enables HMR and development features.
@@ -1085,11 +1117,30 @@ export type MiddlewareWithParams<T extends string = string> = T | `${T}:${string
  */
 export type RouteParam<T extends string> = T extends `{${infer P}}` ? P : never;
 /**
- * Extract parameters from route path
- */
-export type ExtractRouteParams<T extends string> = T extends `${string}{${infer Param}}${infer Rest}` ? {
-    [K in Param]: string;
-} & ExtractRouteParams<Rest> : object;
+ * Strip an inline constraint from a parameter token:
+ * `id:[0-9]+` → `id`, `slug` → `slug`
+ */
+export type ExtractParamName<T extends string> = T extends `${infer Name}:${string}` ? Name : T;
+/**
+ * Extract parameters from a route path into a narrowly-typed object.
+ *
+ * Handles the full parameter grammar:
+ * - `{id}` → `{ id: string }`
+ * - `{id?}` (optional) → `{ id?: string }`
+ * - `{id:[0-9]+}` (inline constraint) → `{ id: string }`
+ * - trailing `*` wildcard → `{ wildcard: string }`
+ *
+ * @example
+ * type P = ExtractRouteParams<'/users/{userId}/posts/{slug?}'>
+ * //   ^? { userId: string } & { slug?: string }
+ */
+export type ExtractRouteParams<T extends string> = T extends `${string}{${infer Param}}${infer Rest}` ? (Param extends `${infer Inner}?` ? {
+    [K in ExtractParamName<Inner>]?: string;
+} : {
+    [K in ExtractParamName<Param>]: string;
+}) & ExtractRouteParams<Rest> : T extends `${string}*${string}` ? {
+    wildcard: string;
+} : object;
 /**
  * Route method constraints
  */
@@ -1520,8 +1571,8 @@ export interface StreamingOptions {
 /**
  * SSE (Server-Sent Events) data structure
  */
-export interface SSEData {
-    data: any;
+export interface SSEData<T = unknown> {
+    data: T;
     event?: string;
     id?: string;
     retry?: number;
@@ -1701,6 +1752,8 @@ export interface RequestMacroMethods {
         username: string;
         password: string;
     } | null;
+    /** Raw unparsed request body as a string (cached). Needed for webhook signature verification (Stripe/GitHub/Slack), where a re-serialized jsonBody won't match the HMAC. */
+    rawBody: () => Promise<string>;
     hasHeader: (name: string) => boolean;
     header: (name: string, defaultValue?: string) => string | null;
     allHeaders: () => Record<string, string>;

package/dist/utils.d.ts

@@ -66,4 +66,4 @@ export declare function resolveViewPath(viewName: string, viewsPath: string, ext
  * @param template The HTML template string
  * @param data The data to inject into the template
  */
-export declare function processHtmlTemplate(template: string, data: Record<string, any>): string;
+export declare function processHtmlTemplate(template: string, data: Record<string, unknown>): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/bun-router",
   "type": "module",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "A fast, type-safe router for Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -28,6 +28,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./container": {
+      "bun": "./dist/container/index.js",
+      "types": "./dist/container/index.d.ts",
+      "import": "./dist/container/index.js"
+    },
     "./*": {
       "bun": "./dist/*",
       "import": "./dist/*"
@@ -40,6 +45,11 @@
         "types": "./dist/index.d.ts",
         "import": "./dist/index.js"
       },
+      "./container": {
+        "bun": "./dist/container/index.js",
+        "types": "./dist/container/index.d.ts",
+        "import": "./dist/container/index.js"
+      },
       "./*": {
         "bun": "./dist/*",
         "import": "./dist/*"
@@ -54,8 +64,7 @@
   },
   "files": [
     "README.md",
-    "dist",
-    "src"
+    "dist"
   ],
   "scripts": {
     "build": "bun --bun build.ts && bun run compile",

package/dist/router/fluent-router.d.ts

@@ -1,315 +0,0 @@
-/**
- * Fluent Routing Extensions
- *
- * Implements fluent routing patterns with full TypeScript support
- */
-import type { EnhancedRequest, MiddlewareHandler, Route, RouteHandler } from '../types';
-import type { Router } from './router';
-/**
- * Controller class interface
- */
-export interface ControllerClass {
-    new (): Controller;
-}
-/**
- * Base controller interface
- */
-export interface Controller {
-    [key: string]: RouteHandler | unknown;
-}
-/**
- * Resource controller methods
- */
-export type ResourceMethod = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
-/**
- * API resource methods (no create/edit views)
- */
-export type ApiResourceMethod = 'index' | 'store' | 'show' | 'update' | 'destroy';
-/**
- * Singleton resource methods
- */
-export type SingletonMethod = 'show' | 'edit' | 'update';
-/**
- * Resource configuration
- */
-export interface ResourceOptions {
-    only?: ResourceMethod[];
-    except?: ResourceMethod[];
-    middleware?: (string | MiddlewareHandler)[];
-    names?: Partial<Record<ResourceMethod, string>>;
-    parameters?: Record<string, string>;
-    shallow?: boolean;
-}
-/**
- * Route builder for fluent API
- */
-export interface FluentRoute {
-    name: (name: string) => FluentRoute;
-    middleware: (...middleware: (string | MiddlewareHandler)[]) => FluentRoute;
-    withoutMiddleware: (...middleware: string[]) => FluentRoute;
-    where: (param: string, pattern: string | RegExp) => FluentRoute;
-    whereNumber: (param: string) => FluentRoute;
-    whereAlpha: (param: string) => FluentRoute;
-    whereAlphaNumeric: (param: string) => FluentRoute;
-    whereUuid: (param: string) => FluentRoute;
-    whereSlug: (param: string) => FluentRoute;
-    can: (ability: string, model?: string) => FluentRoute;
-    missing: (handler: (req: EnhancedRequest) => Response) => FluentRoute;
-    withTrashed: () => FluentRoute;
-    scopeBindings: () => FluentRoute;
-}
-/**
- * Group builder for fluent API
- */
-export interface GroupBuilder {
-    prefix: (prefix: string) => GroupBuilder;
-    name: (name: string) => GroupBuilder;
-    middleware: (...middleware: (string | MiddlewareHandler)[]) => GroupBuilder;
-    domain: (domain: string) => GroupBuilder;
-    controller: (controller: ControllerClass) => GroupBuilder;
-    routes: (callback: (router: FluentRouter) => void) => void;
-}
-/**
- * Fluent router with chainable API
- */
-export declare class FluentRouter {
-    private router;
-    private currentPrefix;
-    private currentNamePrefix;
-    private currentMiddleware;
-    private currentDomain;
-    private currentController;
-    private excludedMiddleware;
-    constructor(router: Router);
-    /**
-     * Register a GET route
-     */
-    get(path: string, handler: RouteHandler | string | Response): FluentRouteBuilder;
-    /**
-     * Register a POST route
-     */
-    post(path: string, handler: RouteHandler | string): FluentRouteBuilder;
-    /**
-     * Register a PUT route
-     */
-    put(path: string, handler: RouteHandler | string): FluentRouteBuilder;
-    /**
-     * Register a PATCH route
-     */
-    patch(path: string, handler: RouteHandler | string): FluentRouteBuilder;
-    /**
-     * Register a DELETE route
-     */
-    delete(path: string, handler: RouteHandler | string): FluentRouteBuilder;
-    /**
-     * Register an OPTIONS route
-     */
-    options(path: string, handler: RouteHandler | string): FluentRouteBuilder;
-    /**
-     * Register a route for any HTTP method
-     */
-    any(path: string, handler: RouteHandler | string): FluentRouteBuilder;
-    /**
-     * Register a route for multiple HTTP methods
-     */
-    match(methods: string[], path: string, handler: RouteHandler | string): FluentRouteBuilder;
-    /**
-     * Register a resource controller
-     */
-    resource(name: string, Controller: ControllerClass, options?: ResourceOptions): this;
-    /**
-     * Register an API resource controller (no create/edit views)
-     */
-    apiResource(name: string, controller: ControllerClass, options?: ResourceOptions): this;
-    /**
-     * Register a singleton resource (no index, create, store, destroy)
-     */
-    singleton(name: string, Controller: ControllerClass, options?: ResourceOptions): this;
-    /**
-     * Create a route group with prefix
-     */
-    prefix(prefix: string): GroupBuilderImpl;
-    /**
-     * Create a route group with name prefix
-     */
-    name(namePrefix: string): GroupBuilderImpl;
-    /**
-     * Create a route group with middleware
-     */
-    middleware(...middleware: (string | MiddlewareHandler)[]): GroupBuilderImpl;
-    /**
-     * Create a route group for a domain
-     */
-    domain(domain: string): GroupBuilderImpl;
-    /**
-     * Create a route group with a controller
-     */
-    controller(controller: ControllerClass): GroupBuilderImpl;
-    /**
-     * Create a route group
-     */
-    group(options: GroupOptions, callback: (router: FluentRouter) => void): this;
-    /**
-     * Check if a named route exists
-     */
-    has(name: string): boolean;
-    /**
-     * Get the current route (from request context)
-     */
-    current(): Route | null;
-    /**
-     * Get the current route name
-     */
-    currentRouteName(): string | null;
-    /**
-     * Get URL for a named route
-     */
-    route(name: string, params?: Record<string, string | number>): string;
-    /**
-     * Register a fallback route
-     */
-    fallback(handler: RouteHandler): this;
-    private addRoute;
-    /**
-     * Create a pattern object for route matching
-     */
-    private createPattern;
-    private buildPath;
-    private buildMiddleware;
-    private resolveHandler;
-    private resolveMiddleware;
-    private getResourceMethods;
-    private getResourceRoute;
-    private getSingletonRoute;
-}
-/**
- * Fluent route builder for chaining route configuration
- */
-export declare class FluentRouteBuilder implements FluentRoute {
-    private router;
-    private path;
-    private method;
-    private routeName;
-    private routeMiddleware;
-    private excludedMiddleware;
-    private constraints;
-    private missingHandler;
-    private includeTrashed;
-    private scopeBindingsEnabled;
-    private ability;
-    private abilityModel;
-    constructor(router: Router, path: string, method: string);
-    /**
-     * Set the route name
-     */
-    name(name: string): this;
-    /**
-     * Add middleware to the route
-     */
-    middleware(...middleware: (string | MiddlewareHandler)[]): this;
-    /**
-     * Exclude middleware from the route
-     */
-    withoutMiddleware(...middleware: string[]): this;
-    /**
-     * Add a parameter constraint
-     */
-    where(param: string, pattern: string | RegExp): this;
-    /**
-     * Constrain parameter to numbers
-     */
-    whereNumber(param: string): this;
-    /**
-     * Constrain parameter to letters
-     */
-    whereAlpha(param: string): this;
-    /**
-     * Constrain parameter to alphanumeric
-     */
-    whereAlphaNumeric(param: string): this;
-    /**
-     * Constrain parameter to UUID
-     */
-    whereUuid(param: string): this;
-    /**
-     * Constrain parameter to slug format
-     */
-    whereSlug(param: string): this;
-    /**
-     * Add authorization check
-     */
-    can(ability: string, model?: string): this;
-    /**
-     * Handle missing model binding
-     */
-    missing(handler: (req: EnhancedRequest) => Response): this;
-    /**
-     * Include soft-deleted models
-     */
-    withTrashed(): this;
-    /**
-     * Enable scoped bindings
-     */
-    scopeBindings(): this;
-    private findRoute;
-}
-interface GroupOptions {
-    prefix?: string;
-    as?: string;
-    middleware?: (string | MiddlewareHandler)[];
-    domain?: string;
-    controller?: ControllerClass;
-}
-declare class GroupBuilderImpl implements GroupBuilder {
-    private fluentRouter;
-    private options;
-    constructor(router: FluentRouter);
-    prefix(prefix: string): this;
-    name(name: string): this;
-    middleware(...middleware: (string | MiddlewareHandler)[]): this;
-    domain(domain: string): this;
-    controller(controller: ControllerClass): this;
-    routes(callback: (router: FluentRouter) => void): void;
-}
-/**
- * Extend Router with fluent routing methods
- */
-export declare function registerFluentRouting(RouterClass: typeof import('./router').Router): void;
-declare module './router' {
-    interface Router {
-        /**
-         * Get fluent router instance
-         */
-        fluent: () => FluentRouter;
-        /**
-         * Register a controller-based resource
-         * Note: Use `resourceController` to avoid conflict with existing `resource` method
-         */
-        resourceController: (name: string, controller: ControllerClass, options?: ResourceOptions) => Router;
-        /**
-         * Register an API resource controller (no create/edit views)
-         */
-        apiResourceController: (name: string, controller: ControllerClass, options?: ResourceOptions) => Router;
-        /**
-         * Register a singleton resource
-         */
-        singletonResource: (name: string, controller: ControllerClass, options?: ResourceOptions) => Router;
-        /**
-         * Check if a named route exists
-         */
-        hasRoute: (name: string) => boolean;
-        /**
-         * Get the current route
-         */
-        currentRoute: () => Route | null;
-        /**
-         * Get the current route name
-         */
-        currentRouteName: () => string | null;
-        /**
-         * Get URL for a named route
-         */
-        routeUrl: (name: string, params?: Record<string, string | number>) => string;
-    }
-}
-export {};