@stacksjs/bun-router 0.0.16 → 0.0.17

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.17",
   "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/*"

package/src/auth.ts

@@ -1,4 +1,5 @@
-import type { EnhancedRequest, JwtPayload } from './types'
+import type { EnhancedRequest, JwtHeader, JwtPayload } from './types'
+import { timingSafeEqual } from 'node:crypto'
 
 // Types
 export interface JwtVerifyOptions {
@@ -22,10 +23,25 @@ export interface JwtSignOptions {
   keyid?: string
   jwtid?: string
   noTimestamp?: boolean
-  header?: Record<string, any>
+  header?: Partial<JwtHeader>
   encoding?: string
 }
 
+/**
+ * Token endpoint response for the OAuth2 authorization-code flow
+ * (RFC 6749 §5.1). Providers may include extra fields — they're preserved
+ * under the index signature.
+ */
+export interface OAuth2TokenResponse {
+  access_token: string
+  token_type: string
+  expires_in?: number
+  refresh_token?: string
+  scope?: string
+  id_token?: string
+  [key: string]: string | number | undefined
+}
+
 export interface ApiKeyOptions {
   source?: 'header' | 'query' | 'cookie'
   keyName?: string
@@ -74,7 +90,7 @@ export class JWT {
   /**
    * Sign payload into a JWT token
    */
-  sign(payload: Record<string, any>, options: JwtSignOptions = {}): string {
+  sign(payload: JwtPayload, options: JwtSignOptions = {}): string {
     // Default header
     const header = {
       alg: options.algorithm || 'HS256',
@@ -132,7 +148,7 @@ export class JWT {
   /**
    * Verify a JWT token and return the decoded payload
    */
-  verify(token: string, options: JwtVerifyOptions = {}): Record<string, any> | null {
+  verify(token: string, options: JwtVerifyOptions = {}): JwtPayload | null {
     try {
       const parts = token.split('.')
 
@@ -143,8 +159,8 @@ export class JWT {
       const [encodedHeader, encodedPayload, signature] = parts
 
       // Decode header and payload
-      const header = JSON.parse(base64UrlDecode(encodedHeader))
-      const payload = JSON.parse(base64UrlDecode(encodedPayload))
+      const header = JSON.parse(base64UrlDecode(encodedHeader)) as JwtHeader
+      const payload = JSON.parse(base64UrlDecode(encodedPayload)) as JwtPayload
 
       // Verify algorithm if specified
       if (options.algorithms && !options.algorithms.includes(header.alg)) {
@@ -156,7 +172,11 @@ export class JWT {
       const data = `${encodedHeader}.${encodedPayload}`
       const expectedSignature = this.createSignature(data, this.secret, header.alg)
 
-      if (signature !== expectedSignature) {
+      // Constant-time comparison — `!==` leaks how much of the signature
+      // matched through response timing
+      const sigBuf = Buffer.from(signature)
+      const expectedBuf = Buffer.from(expectedSignature)
+      if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) {
         throw new Error('Invalid signature')
       }
 
@@ -200,7 +220,7 @@ export class JWT {
   /**
    * Decode a JWT token without verifying the signature
    */
-  decode(token: string): { header: Record<string, any>, payload: Record<string, any> } | null {
+  decode(token: string): { header: JwtHeader, payload: JwtPayload } | null {
     try {
       const parts = token.split('.')
 
@@ -402,7 +422,7 @@ export class OAuth2Helper {
   /**
    * Exchange authorization code for access token
    */
-  async exchangeCodeForToken(code: string): Promise<Record<string, any>> {
+  async exchangeCodeForToken(code: string): Promise<OAuth2TokenResponse> {
     const params = new URLSearchParams({
       grant_type: 'authorization_code',
       code,
@@ -423,13 +443,13 @@ export class OAuth2Helper {
       throw new Error(`OAuth token exchange failed: ${response.status} ${response.statusText}`)
     }
 
-    return await response.json() as Record<string, any>
+    return await response.json() as OAuth2TokenResponse
   }
 
   /**
    * Refresh an access token using a refresh token
    */
-  async refreshToken(refreshToken: string): Promise<Record<string, any>> {
+  async refreshToken(refreshToken: string): Promise<OAuth2TokenResponse> {
     const params = new URLSearchParams({
       grant_type: 'refresh_token',
       refresh_token: refreshToken,
@@ -449,7 +469,7 @@ export class OAuth2Helper {
       throw new Error(`OAuth token refresh failed: ${response.status} ${response.statusText}`)
     }
 
-    return await response.json() as Record<string, any>
+    return await response.json() as OAuth2TokenResponse
   }
 }
 

package/src/container/container.ts

@@ -86,6 +86,9 @@ export interface InjectMetadata {
  */
 export class Container {
   private bindings = new Map<Token, Binding>()
+  // Tag → tokens index, maintained on register/unbind so tagged lookups
+  // are O(matches) instead of scanning every binding
+  private tagIndex = new Map<string, Set<Token>>()
   private instances = new Map<Token, any>()
   private scopedInstances = new Map<string, Map<Token, any>>()
   private interceptors = new Map<Token, ((..._args: any[]) => any)[]>()
@@ -115,7 +118,26 @@ export class Container {
    * Register a binding
    */
   register<T>(binding: Binding<T>): this {
+    // Re-registering a token replaces its tag index entries
+    const existing = this.bindings.get(binding.token)
+    if (existing?.metadata?.tags) {
+      for (const tag of existing.metadata.tags) {
+        this.tagIndex.get(tag)?.delete(binding.token)
+      }
+    }
+
     this.bindings.set(binding.token, binding)
+
+    if (binding.metadata?.tags) {
+      for (const tag of binding.metadata.tags) {
+        let tokens = this.tagIndex.get(tag)
+        if (!tokens) {
+          tokens = new Set()
+          this.tagIndex.set(tag, tokens)
+        }
+        tokens.add(binding.token)
+      }
+    }
     return this
   }
 
@@ -177,31 +199,48 @@ export class Container {
    * Resolve all instances of a token (useful for arrays of services)
    */
   resolveAll<T>(token: Token): T[] {
-    const bindings = Array.from(this.bindings.values()).filter(
-      binding => binding.token === token || this.hasTag(binding, token as string),
-    )
+    // Direct binding plus anything tagged with the token (when it's a
+    // string), deduplicated by token
+    const tokens = new Set<Token>()
+    if (this.bindings.has(token)) {
+      tokens.add(token)
+    }
+    if (typeof token === 'string') {
+      for (const tagged of this.tagIndex.get(token) ?? []) {
+        tokens.add(tagged)
+      }
+    }
 
-    return bindings.map(binding => this.resolve<T>(binding.token))
+    return Array.from(tokens, t => this.resolve<T>(t))
   }
 
   /**
    * Resolve with tags
    */
   resolveTagged<T>(tag: string): T[] {
-    const bindings = Array.from(this.bindings.values()).filter(
-      binding => this.hasTag(binding, tag),
-    )
-
-    return bindings.map(binding => this.resolve<T>(binding.token))
+    const tokens = this.tagIndex.get(tag)
+    if (!tokens || tokens.size === 0) {
+      return []
+    }
+    return Array.from(tokens, token => this.resolve<T>(token))
   }
 
   /**
    * Get all bindings with a specific tag
    */
   getTaggedBindings<T>(tag: string): Binding<T>[] {
-    return Array.from(this.bindings.values()).filter(
-      (binding): binding is Binding<T> => binding.metadata?.tags?.includes(tag) ?? false,
-    )
+    const tokens = this.tagIndex.get(tag)
+    if (!tokens || tokens.size === 0) {
+      return []
+    }
+    const bindings: Binding<T>[] = []
+    for (const token of tokens) {
+      const binding = this.bindings.get(token)
+      if (binding) {
+        bindings.push(binding as Binding<T>)
+      }
+    }
+    return bindings
   }
 
   /**
@@ -241,6 +280,12 @@ export class Container {
    * Unbind a token
    */
   unbind(token: Token): this {
+    const binding = this.bindings.get(token)
+    if (binding?.metadata?.tags) {
+      for (const tag of binding.metadata.tags) {
+        this.tagIndex.get(tag)?.delete(token)
+      }
+    }
     this.bindings.delete(token)
     this.instances.delete(token)
     return this
@@ -277,6 +322,7 @@ export class Container {
    */
   clear(): this {
     this.bindings.clear()
+    this.tagIndex.clear()
     this.instances.clear()
     this.scopedInstances.clear()
     return this

package/src/container/contextual-binding.ts

@@ -600,4 +600,7 @@ export class BindingConditions {
   }
 }
 
-export { ContextualContainer as DIContainer }
+// NOTE: this module used to also alias `ContextualContainer` as
+// `DIContainer`, colliding with container.ts's `Container as DIContainer`
+// alias — two different classes under one public name. The base
+// container keeps the alias; use `ContextualContainer` explicitly here.

package/src/container/decorators.ts

@@ -4,13 +4,22 @@
  */
 
 import type { ResolutionContext } from './container'
-import { Container } from './container'
-
-// Metadata keys with explicit types
-export const INJECTABLE_METADATA_KEY: unique symbol = Symbol('injectable')
-export const INJECT_METADATA_KEY: unique symbol = Symbol('inject')
-export const OPTIONAL_METADATA_KEY: unique symbol = Symbol('optional')
-export const TAGGED_METADATA_KEY: unique symbol = Symbol('tagged')
+import {
+  Container,
+  INJECT_METADATA_KEY,
+  INJECTABLE_METADATA_KEY,
+  OPTIONAL_METADATA_KEY,
+  TAGGED_METADATA_KEY,
+} from './container'
+
+// The injection metadata keys MUST be the container's own symbols — this
+// module previously declared its own `Symbol('inject')` etc., so metadata
+// written by `@Inject` was invisible to `Container.getConstructorDependencies`
+// (which reads with the container's symbols) and constructor injection
+// silently resolved nothing. Re-exported for backward compatibility.
+export { INJECT_METADATA_KEY, INJECTABLE_METADATA_KEY, OPTIONAL_METADATA_KEY, TAGGED_METADATA_KEY }
+
+// Decorator-specific metadata keys
 export const CONTROLLER_METADATA_KEY: unique symbol = Symbol('controller')
 export const ROUTE_METADATA_KEY: unique symbol = Symbol('route')
 export const MIDDLEWARE_METADATA_KEY: unique symbol = Symbol('middleware')

package/src/container/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Dependency-injection container — public entry point.
+ *
+ * ```ts
+ * import { Container, createContainer, Inject, Injectable } from '@stacksjs/bun-router/container'
+ * ```
+ *
+ * The core `Container` (and a few companions) are also re-exported from the
+ * package root; the decorators live only here because their names (`Get`,
+ * `Post`, `Controller`, …) would collide with the router's exports.
+ */
+
+export * from './container'
+
+// Decorators. The duplicate `InjectableMetadata`/`InjectMetadata` interface
+// declarations stay out of the barrel — the canonical ones come from
+// `./container` above.
+export {
+  Body,
+  Controller,
+  CONTROLLER_METADATA_KEY,
+  Cookie,
+  decoratorContainer,
+  DecoratorContainer,
+  Delete,
+  Get,
+  Head,
+  Header,
+  Inject,
+  Injectable,
+  InjectParam,
+  MetadataReader,
+  MIDDLEWARE_METADATA_KEY,
+  Optional,
+  Options,
+  Param,
+  PARAM_METADATA_KEY,
+  Patch,
+  Post,
+  Put,
+  Query,
+  ROUTE_METADATA_KEY,
+  Tagged,
+  UseMiddleware,
+} from './decorators'
+export type { ControllerMetadata, ParamMetadata, RouteMetadata } from './decorators'
+
+export * from './contextual-binding'
+export * from './service-provider'

package/src/errors/circuit-breaker.ts

@@ -87,8 +87,9 @@ export class CircuitBreaker {
       consecutiveSuccesses: 0,
     }
 
-    // Clean up old requests periodically
-    setInterval(() => this.cleanupOldRequests(), this.config.monitoringPeriod / 4)
+    // Clean up old requests periodically (unref'd so the timer never
+    // keeps the process alive)
+    setInterval(() => this.cleanupOldRequests(), this.config.monitoringPeriod / 4).unref?.()
   }
 
   /**

package/src/errors/graceful-degradation.ts

@@ -119,6 +119,8 @@ export class ServiceHealthMonitor {
         () => this.performHealthCheck(serviceName, healthConfig),
         healthConfig.interval,
       )
+      // Health checks must not keep the process alive on shutdown
+      interval.unref?.()
       this.healthCheckIntervals.set(serviceName, interval)
     }
   }