@stacksjs/bun-router 0.0.16 → 0.0.17

package/src/types/route-inference.ts

@@ -4,16 +4,29 @@
  * Advanced TypeScript utilities for inferring route parameter types from URL patterns
  */
 
-// Base types for route parameter extraction
-export type ExtractRouteParams<T extends string> = 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 } & ExtractRouteParams<Rest>
-    : T extends `${infer _Start}:${infer Param}`
-      ? { [K in Param]: string }
-      : T extends `${infer _Start}*${infer Rest}`
-        ? { '*': string } & ExtractRouteParams<Rest>
-        : Record<string, never>
+/** Strip an inline constraint from a brace parameter: `id:[0-9]+` → `id` */
+type StripInlineConstraint<T extends string> = T extends `${infer Name}:${string}` ? Name : T
+
+// Base types for route parameter extraction.
+//
+// The router's canonical parameter syntax is `{param}` (with `{param?}` for
+// optional and `{param:regex}` for constrained parameters) — that form is
+// handled first. The legacy Express-style `:param` clauses are kept for
+// backward compatibility with code written against the colon syntax.
+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 } & ExtractRouteParams<Rest>
+        : T extends `${infer _Start}:${infer Param}`
+          ? { [K in Param]: string }
+          : T extends `${infer _Start}*${infer Rest}`
+            ? { '*': string } & ExtractRouteParams<Rest>
+            : Record<string, never>
 
 // Advanced parameter extraction with type constraints
 export type ExtractTypedParams<T extends string> = T extends `${infer _Start}:${infer Param}<${infer Type}>${infer Rest}`
@@ -214,11 +227,13 @@ export interface RouteGroup<TPrefix extends string = '', TContext = object> {
   routes: TypedRoute<any, any, any, TContext>[]
 }
 
-// Middleware type (forward declaration - will be defined in middleware types)
+// Middleware type (forward declaration — the canonical definition lives in
+// middleware-types.ts; this one mirrors its narrow defaults so the two
+// can't drift apart silently)
 export interface TypedMiddleware<
-  TRequest = any,
-  TResponse = any,
-  TNext = any,
+  TRequest = Request,
+  TResponse = Response,
+  TNext = () => Promise<TResponse>,
   _TContext = Record<string, never>,
 > {
   (request: TRequest, next: TNext): Promise<TResponse> | TResponse

package/src/types.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,
@@ -807,6 +808,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)
    */
@@ -816,9 +823,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)
    */
@@ -1057,6 +1066,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
 }
 
 /**
@@ -1102,6 +1118,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.
@@ -1273,12 +1305,33 @@ export type MiddlewareWithParams<T extends string = string> =
 export type RouteParam<T extends string> = T extends `{${infer P}}` ? P : never
 
 /**
- * Extract parameters from route path
+ * 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}`
-    ? { [K in Param]: string } & ExtractRouteParams<Rest>
-    : object
+    ? (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
@@ -1735,8 +1788,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
@@ -1933,6 +1986,9 @@ export interface RequestMacroMethods {
   bearerToken: () => string | null
   basicAuth: () => { 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>
+
   // Headers
   hasHeader: (name: string) => boolean
   header: (name: string, defaultValue?: string) => string | null

package/src/url.ts

@@ -100,8 +100,13 @@ export function url(
     }
   }
 
-  // Strip any unfilled optional placeholders (e.g. `/posts/{slug?}` → `/posts/`)
-  resolved = resolved.replace(/\/\{[^}]+\?\}/g, '')
+  // Strip any unfilled optional placeholders and tidy the slashes they
+  // leave behind (`/posts/{slug?}` → `/posts`, `/a/{v?}/b` → `/a/b`)
+  if (resolved.includes('?}')) {
+    resolved = resolved.replace(/\{[^}]+\?\}/g, '').replace(/\/{2,}/g, '/')
+    if (resolved.length > 1 && resolved.endsWith('/'))
+      resolved = resolved.slice(0, -1)
+  }
 
   // Throw on unfilled required placeholders so the caller sees the bug.
   const missing = resolved.match(/\{([^}?]+)\}/g)

package/src/utils.ts

@@ -319,7 +319,7 @@ export async function resolveViewPath(
  * @param template The HTML template string
  * @param data The data to inject into the template
  */
-export function processHtmlTemplate(template: string, data: Record<string, any>): string {
+export function processHtmlTemplate(template: string, data: Record<string, unknown>): string {
   // Process general variables {{ varName }}
   let result = template.replace(/\{\{([^}]+)\}\}/g, (match, key) => {
     const trimmedKey = key.trim()
@@ -339,7 +339,7 @@ export function processHtmlTemplate(template: string, data: Record<string, any>)
 /**
  * Process conditional statements in templates
  */
-function processConditionals(template: string, data: Record<string, any>): string {
+function processConditionals(template: string, data: Record<string, unknown>): string {
   // Match {{#if condition}} content {{/if}} or {{#if condition}} content {{else}} alternative {{/if}}
   return template.replace(
     /\{\{#if ([^}]+)\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}/g,
@@ -355,7 +355,7 @@ function processConditionals(template: string, data: Record<string, any>): strin
 /**
  * Process loop statements in templates
  */
-function processLoops(template: string, data: Record<string, any>): string {
+function processLoops(template: string, data: Record<string, unknown>): string {
   // Match {{#each items}} content {{/each}}
   return template.replace(
     /\{\{#each ([^}]+)\}\}([\s\S]*?)\{\{\/each\}\}/g,
@@ -385,8 +385,11 @@ function processLoops(template: string, data: Record<string, any>): string {
  * @param obj The object to extract value from
  * @param path The path to the value (e.g., 'user.profile.name')
  */
-function getNestedValue(obj: Record<string, any>, path: string): any {
-  return path.split('.').reduce((prev, curr) => {
-    return prev && prev[curr] !== undefined ? prev[curr] : undefined
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  return path.split('.').reduce<unknown>((prev, curr) => {
+    if (prev && typeof prev === 'object' && curr in prev) {
+      return (prev as Record<string, unknown>)[curr]
+    }
+    return undefined
   }, obj)
 }

package/src/validation/validator.ts

@@ -7,6 +7,12 @@
 import type { EnhancedRequest, NextFunction } from '../types'
 import { ValidationException } from '../errors/exceptions'
 
+// Hoisted email check. Pragmatic RFC 5322 approximation: requires one `@`,
+// a non-empty local part without surrounding/consecutive dots, and a domain
+// with at least one label dot and a 2+ char TLD. The previous regex
+// accepted addresses like `a@.com` and consecutive dots.
+const EMAIL_REGEX = /^[A-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?(?:\.[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?)*\.[A-Z]{2,}$/i
+
 export interface ValidationRule {
   name: string
   validate: (value: any, parameters: string[], field: string, data: Record<string, any>) => Promise<boolean> | boolean
@@ -74,10 +80,7 @@ export const BuiltInRules: Record<string, ValidationRule> = {
 
   email: {
     name: 'email',
-    validate: (value) => {
-      const emailRegex = /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/
-      return typeof value === 'string' && emailRegex.test(value)
-    },
+    validate: value => typeof value === 'string' && EMAIL_REGEX.test(value),
     message: 'The :field field must be a valid email address.',
   },
 

package/src/websocket/clustering.ts

@@ -539,8 +539,13 @@ export class WebSocketCluster {
         break
 
       case 'stats':
-        // Handle stats updates from other workers
+        // Handle stats updates from other workers. Bounded: with worker
+        // churn the per-worker entries would otherwise accumulate forever.
         if (message.data && message.workerId) {
+          const workerIds = Object.keys(this.stats.workerStats)
+          if (workerIds.length >= 1000 && !(message.workerId in this.stats.workerStats)) {
+            delete this.stats.workerStats[workerIds[0]]
+          }
           this.stats.workerStats[message.workerId] = message.data
         }
         break
@@ -623,6 +628,8 @@ export class WebSocketCluster {
         timestamp: now,
       })
     }, this.config.heartbeatInterval)
+    // The heartbeat must not keep the process alive on shutdown
+    this.heartbeatTimer.unref?.()
   }
 
   /**

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 {};