@stacksjs/router 0.70.86 → 0.70.88

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/router",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.86",
+  "version": "0.70.88",
   "description": "The Stacks framework router.",
   "author": "Chris Breuer",
   "contributors": [
@@ -54,18 +54,18 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/bun-router": "0.0.17"
+    "@stacksjs/bun-router": "^0.0.19"
   },
   "devDependencies": {
-    "@stacksjs/actions": "0.70.86",
-    "@stacksjs/config": "0.70.86",
+    "@stacksjs/actions": "0.70.88",
+    "@stacksjs/config": "0.70.88",
     "better-dx": "^0.2.16",
-    "@stacksjs/error-handling": "0.70.86",
-    "@stacksjs/logging": "0.70.86",
-    "@stacksjs/orm": "0.70.86",
-    "@stacksjs/path": "0.70.86",
-    "@stacksjs/storage": "0.70.86",
-    "@stacksjs/types": "0.70.86",
-    "@stacksjs/validation": "0.70.86"
+    "@stacksjs/error-handling": "0.70.88",
+    "@stacksjs/logging": "0.70.88",
+    "@stacksjs/orm": "0.70.88",
+    "@stacksjs/path": "0.70.88",
+    "@stacksjs/storage": "0.70.88",
+    "@stacksjs/types": "0.70.88",
+    "@stacksjs/validation": "0.70.88"
   }
 }

package/dist/action-paths.d.ts

@@ -1,7 +0,0 @@
-/**
- * Action path types for the Stacks router.
- * This file is auto-generated or manually maintained to provide
- * type-safe string paths for routing to actions and controllers.
- */
-// Base type for all action paths - will be narrowed as actions are added
-export type StacksActionPath = string;

package/dist/api-shape.d.ts

@@ -1,24 +0,0 @@
-/*`,
- * not `application/json`). This predicate fixes that asymmetry by making
- * JSON the default unless the client explicitly opts into HTML.
- */
-export declare function isApiRequest(req: Request | { headers: Headers }): boolean;
-/**
- * "Is this request JSON-shaped?" — the single source of truth used across
- * the framework to decide JSON vs HTML for responses (errors, primitives,
- * empty results) and to widen request-body parsing to every JSON variant.
- *
- * The historical bug was scattered ad-hoc checks: `error-handler` looked at
- * `Accept`, `formatResult` ignored the request entirely, `parseRequestBody`
- * did `contentType.includes('application/json')` so `application/vnd.api+json`
- * went unparsed. Centralizing the decision here means a future tweak (e.g.,
- * treating an `apiResponse: true` route group as always-JSON) lands in one
- * place and every response path picks it up.
- */
-/**
- * Matches `application/json` plus any RFC-6838 structured-suffix subtype:
- * `application/vnd.api+json`, `application/ld+json`, `application/hal+json`,
- * `application/problem+json`, etc. Case-insensitive; tolerates a trailing
- * `;` (for `;charset=utf-8`) or end-of-string.
- */
-export declare const JSON_CONTENT_TYPE: unknown;

package/dist/encrypted-session-store.d.ts

@@ -1,19 +0,0 @@
-import type { SessionData, SessionStore } from '@stacksjs/bun-router';
-export declare interface EncryptedSessionStoreOptions {
-  appKey?: string
-}
-/**
- * Wrap a bun-router `SessionStore<SessionData>` so all writes are
- * encrypted on the way in and decrypted on the way out. Drop-in
- * replacement for any of the built-in stores.
- */
-export declare class EncryptedSessionStore implements SessionStore<SessionData> {
-  constructor(inner: SessionStore<SessionData>, opts?: EncryptedSessionStoreOptions);
-  set(sid: string, session: SessionData, ttl?: number): Promise<void>;
-  touch(sid: string, session: SessionData, ttl?: number): Promise<void>;
-  get(sid: string): Promise<SessionData | null>;
-  destroy(sid: string): Promise<void>;
-  all(): Promise<Record<string, SessionData>>;
-  length(): Promise<number>;
-  clear(): Promise<void>;
-}

package/dist/error-handler.d.ts

@@ -1,68 +0,0 @@
-import type { EnhancedRequest } from '@stacksjs/bun-router';
-/**
- * Add a query to the recent queries list for error context.
- * Uses a circular buffer for O(1) insert instead of array.shift().
- *
- * Also runs N+1 detection: when the same query *shape* (with bound
- * values normalized away) repeats more than `N1_THRESHOLD` times within
- * a single request lifecycle, we warn once via `log.warn`. The signal
- * is highly correlated with missing eager loading.
- */
-export declare function trackQuery(query: string, time?: number, connection?: string): void;
-/**
- * Snapshot of query shape counts for the active request. Useful for
- * tests asserting that an action ran a single query for `posts`
- * instead of one-per-user.
- */
-export declare function getQueryShapeCounts(): ReadonlyMap<string, number>;
-/**
- * Reset query tracking for the active scope.
- *
- * Inside a request, this clears the per-request tracking object — but
- * the object is also auto-collected when the request goes out of scope,
- * so the explicit call is mainly useful for tests that re-use a single
- * request. Outside a request, this clears the process-wide fallback.
- */
-export declare function clearTrackedQueries(): void;
-/**
- * Create an Ignition-style error response for development
- */
-export declare function createErrorResponse(error: Error, request: Request | EnhancedRequest, options?: {
-    status?: number
-    handlerPath?: string
-    routingContext?: {
-      controller?: string
-      routeName?: string
-      middleware?: string[]
-    }
-  }): Promise<Response>;
-/**
- * Create a middleware error response (401, 403, etc.)
- *
- * Reads `statusCode` OR `status` off the error so both shapes are honored:
- * - middleware that throws `Object.assign(new Error('msg'), { statusCode: 401 })`
- * - framework HttpError instances where the field is named `status`
- *
- * Without the `status` fallback, every `HttpError(401, …)` throw from auth or
- * validation middleware leaks out as a 500 with an Ignition error page —
- * which is what we used to ship for `GET /api/me` without a token.
- */
-export declare function createMiddlewareErrorResponse(error: Error & { statusCode?: number, status?: number, headers?: Record<string, string> }, request: Request | EnhancedRequest): Promise<Response>;
-/**
- * Create a validation error response
- */
-export declare function createValidationErrorResponse(errors: Record<string, string[]>, _request: Request | EnhancedRequest): Response;
-/**
- * Create a 404 Not Found response
- */
-export declare function createNotFoundResponse(path: string, request: Request | EnhancedRequest): Promise<Response>;
-/**
- * Standard error response structure used across all JSON error responses.
- */
-export declare interface ErrorResponseBody {
-  error: string
-  message: string
-  status: number
-  timestamp: string
-  details?: Record<string, unknown>
-}

package/dist/index.d.ts

@@ -1,81 +0,0 @@
-import './request-augmentation';
-// Re-export the augmentation types so userland can refer to the marker
-// surface explicitly when needed.
-export type { StacksRequestExtensions, StacksRequestMacros, StacksRequestMarkers } from './request-augmentation';
-export type { MiddlewareConfig, Request } from './middleware';
-// Export route registry types — owned here rather than in app/Routes.ts
-// so the path doesn't depend on a 5-level relative reach across the
-// framework defaults tree (stacksjs/stacks#1863, T-10).
-export type { RouteDefinition, RouteRegistry } from './route-types';
-export type { PathParamRejection, SanitizePathParamOptions } from './path-sanitize';
-export type { StreamOptions } from './stacks-router';
-export type { SignedUrlOptions, SignedUrlVerifyResult } from './signed-url';
-export type { EncryptedSessionStoreOptions } from './encrypted-session-store';
-export type {
-  RedisClient,
-  SessionConfig,
-  SessionData,
-  SessionStore,
-  StacksSessionConfig,
-} from './session-factory';
-// Re-export everything from bun-router (includes response factory)
-export * from '@stacksjs/bun-router';
-// Export Stacks-specific action resolver and URL helper
-export { assertRouteMiddlewareResolvable, clearMiddlewareCache, createStacksRouter, findUnresolvableRouteMiddleware, installMiddlewareHotReload, route, serve, serverResponse, url, warnOnMultipleRouterInstances } from './stacks-router';
-// Export request context helpers
-export { cacheRequestQuery, getCurrentRequest, getTraceId, request, runWithRequest, setCurrentRequest, withTraceId } from './request-context';
-// Export Middleware class for defining route middleware
-export { Middleware } from './middleware';
-// Export route loader
-export { loadRoutes } from './route-loader';
-// Export error handler utilities
-export {
-  clearTrackedQueries,
-  createErrorResponse,
-  createMiddlewareErrorResponse,
-  createNotFoundResponse,
-  createValidationErrorResponse,
-  getQueryShapeCounts,
-  trackQuery,
-} from './error-handler';
-// Export route introspection helpers
-export { listRegisteredRoutes, routeParams } from './stacks-router';
-// Export JSON-vs-HTML negotiation predicate so userland can short-circuit
-// the same decision the framework makes in formatResult / error-handler.
-export { isApiRequest, JSON_CONTENT_TYPE } from './api-shape';
-// Export action-level rate limiting helpers
-export { rateLimit, rateLimitStatus, clearRateLimit } from './rate-limit';
-// Export path-param sanitization helper (stacksjs/stacks#1870 R-12).
-// Defense-in-depth for actions that interpolate route params into
-// filesystem paths; the helper enforces no-traversal / no-absolute /
-// no-null-byte / length ceiling at a single chokepoint.
-export { PathParamError, safePathParam, sanitizePathParam } from './path-sanitize';
-// Export the streaming-response helper for SSE / NDJSON / chunked
-// binary returns (stacksjs/stacks#1870 R-4). Actions can return
-// `stream(asyncGen, { type: 'sse' })` and the router pipes it back
-// with the right Content-Type + no-cache headers.
-export { stream } from './stacks-router';
-// Signed-URL helpers — HMAC over the URL + optional expiry so single-
-// use links (email verify, password reset, unsubscribe) can be handed
-// out without long-lived bearer tokens. Pair `signedUrl(...)` with the
-// `signed` middleware (or call `verifySignedUrl(req.url)` directly).
-// See stacksjs/stacks#1870 R-7.
-export { signedUrl, signUrl, verifySignedUrl, verifySignedUrlMiddleware } from './signed-url';
-// Encryption-at-rest wrapper for any bun-router SessionStore
-// (stacksjs/stacks#1878 Se-4). Opt-in: wrap your existing store
-// instance so session payloads are AES-GCM encrypted via APP_KEY
-// before being persisted.
-export { EncryptedSessionStore } from './encrypted-session-store';
-// Session driver factory (stacksjs/stacks#1889, F-2 from #1874).
-// Builds a SessionStore from the Stacks config — picks the right
-// driver from `config.session.driver`, optionally wraps with
-// EncryptedSessionStore. Re-exports all four bun-router store
-// classes so callers can assemble custom stacks manually too.
-export {
-  createSessionStore,
-  createStacksSessionStore,
-  DatabaseSessionStore,
-  FileSessionStore,
-  MemorySessionStore,
-  RedisSessionStore,
-} from './session-factory';

package/dist/index.js

@@ -1,14 +0,0 @@
-// @bun
-var{defineProperty:K,getOwnPropertyNames:R,getOwnPropertyDescriptor:k}=Object,g=Object.prototype.hasOwnProperty;function h($){return this[$]}var E=($)=>{var F=(Y??=new WeakMap).get($),W;if(F)return F;if(F=K({},"__esModule",{value:!0}),$&&typeof $==="object"||typeof $==="function"){for(var V of R($))if(!g.call(F,V))K(F,V,{get:h.bind($,V),enumerable:!(W=k($,V))||W.enumerable})}return Y.set($,F),F},Y;var l=($)=>$;function q($,F){this[$]=l.bind(null,F)}var d=($,F)=>{for(var W in F)K($,W,{get:F[W],enumerable:!0,configurable:!0,set:q.bind(F,W)})};var f=($,F)=>()=>($&&(F=$($=0)),F);var D=import.meta.require;function z($){let F=$.headers,W=F.get("content-type")||"";if(i.test(W))return!0;if(F.get("sec-fetch-dest")==="document")return!1;if((F.get("accept")||"").includes("text/html"))return!1;return!0}var i;var b=f(()=>{i=/^application\/(?:json|.+\+json)(?:;|$)/i});import c from"process";import{AsyncLocalStorage as U}from"async_hooks";import{log as v0}from"@stacksjs/logging";function I(){return n.getStore()}var p,n,u,w0,x0;var H=f(()=>{p=Symbol.for("stacks.router.requestStorage"),n=globalThis[p]??=new U,u=Symbol.for("stacks.router.traceStorage"),w0=globalThis[u]??=new U;x0=new Proxy({},{get($,F){let W=I();if(!W){if(c.env.NODE_ENV!=="production")console.warn(`[RequestContext] Accessing request.${String(F)} outside of request context`);if(F==="bearerToken")return()=>null;if(F==="user"||F==="userToken")return async()=>{return};if(F==="tokenCan"||F==="tokenCant")return async()=>!1;if(F==="headers")return new Headers;if(F==="url")return"";if(F==="method")return"GET";return}let V=W[F];if(typeof V==="function")return V.bind(W);return V}})});var Q={};d(Q,{trackQuery:()=>e,getQueryShapeCounts:()=>$0,createValidationErrorResponse:()=>O0,createNotFoundResponse:()=>L0,createMiddlewareErrorResponse:()=>N0,createErrorResponse:()=>J,clearTrackedQueries:()=>F0});import N from"process";import{log as o}from"@stacksjs/logging";import{createErrorHandler as a,renderProductionErrorPage as A}from"@stacksjs/error-handling";function P($){let F={error:$.error,message:$.message,status:$.status,timestamp:new Date().toISOString()};if($.details)F.details=$.details;return JSON.stringify(F)}function M(){let $=(N.env.APP_ENV??"").toLowerCase();if($==="development")return!0;if(!$&&N.env.NODE_ENV==="development")return!0;return!1}function O(){return{"Content-Type":"application/json"}}function s(){return O()}function v(){return{buffer:Array(X).fill(null),writeIndex:0,count:0,shapeCounts:new Map,n1Warned:new Set}}function m(){let $=I();if(!$)return S;let F=$[w];if(!F)F=v(),$[w]=F;return F}function r($){return $.replace(/'(?:[^']|'')*'/g,"?").replace(/"(?:[^"]|"")*"/g,"?").replace(/\b\d+(?:\.\d+)?\b/g,"?").replace(/IN\s*\([^)]*\)/gi,"IN (?)").replace(/\s+/g," ").trim().toUpperCase()}function e($,F,W){let V=m();if(V.buffer[V.writeIndex]={query:$,time:F,connection:W},V.writeIndex=(V.writeIndex+1)%X,V.count<X)V.count++;if(!M())return;let G=r($);if(G.startsWith("INSERT INTO QUERY_LOGS")||G.startsWith("EXPLAIN"))return;let Z=(V.shapeCounts.get(G)??0)+1;if(V.shapeCounts.set(G,Z),Z===t+1&&!V.n1Warned.has(G))V.n1Warned.add(G),import("@stacksjs/logging").then(({log:B})=>{B.warn(`[orm] Possible N+1 \u2014 query shape ran ${Z}\xD7 in this request:
-  ${G}
-  Hint: load related rows with .with('relation') or eager-load via includes() before iterating.`)}).catch(()=>{})}function C(){let $=m();if($.count===0)return[];let F=[],W=$.count<X?0:$.writeIndex;for(let V=0;V<$.count;V++){let G=$.buffer[(W+V)%X];if(G)F.push(G)}return F}function $0(){return new Map(m().shapeCounts)}function F0(){let $=I();if($&&$[w]){$[w]=v();return}S=v()}function V0(){return{appName:"Stacks",theme:"auto",showEnvironment:!0,showQueries:!0,showRequest:!0,enableCopyMarkdown:!0,snippetLines:8,basePaths:[N.cwd()]}}function x($,F=0,W=new WeakSet){if(!$||typeof $!=="object"||F>=Z0)return $;if(W.has($))return G0;if(W.add($),Array.isArray($))return $.map((G)=>x(G,F+1,W));let V={};for(let[G,Z]of Object.entries($)){let B=G.toLowerCase();if(W0.some((L)=>B.includes(L)))V[G]="********";else if(typeof Z==="object"&&Z!==null)V[G]=x(Z,F+1,W);else V[G]=Z}return V}function B0($){let F=$;if(F.jsonBody)return x(F.jsonBody);if(F.formBody)return x(F.formBody);return}async function j0($){let W=$._authenticatedUser;if(W)return{id:W.id,email:W.email,name:W.name||W.username};return}async function J($,F,W){let V=W?.status||500;if(o.debug(`[error] ${V} ${$.message}`),!M()){if(z(F)){let Z=V>=400&&V<500,B=$.details;return new Response(P({error:Z?$.name||"Client Error":"Internal Server Error",message:Z?$.message:"An unexpected error occurred.",status:V,details:Z&&B&&typeof B==="object"?B:void 0}),{status:V,headers:O()})}return new Response(A(V),{status:V,headers:{"Content-Type":"text/html; charset=utf-8"}})}try{let Z=a(V0());Z.setFramework("Stacks","0.70.0");let B=B0(F);if(B){let j=new URL(F.url);Z.setRequest({method:F.method,url:F.url,headers:Object.fromEntries(F.headers.entries()),queryParams:Object.fromEntries(j.searchParams.entries()),body:B})}else Z.setRequest(F);let L=await j0(F);if(L)Z.setUser(L);if(W?.routingContext)Z.setRouting(W.routingContext);else if(W?.handlerPath)Z.setRouting({controller:W.handlerPath});for(let j of C())Z.addQuery(j.query,j.time,j.connection);if(z(F)){let j={handler:W?.handlerPath};if(M())j.stack=$.stack?.split(`
-`).slice(0,10),j.queries=C().slice(-10);return new Response(P({error:$.name||"Error",message:$.message,status:V,details:j}),{status:V,headers:s()})}let T=N.env.APP_URL?N.env.APP_URL.startsWith("http")?N.env.APP_URL:`https://${N.env.APP_URL}`:M()?"*":F.headers.get("origin")??"null",y=await Z.render($,V);return new Response(y,{status:V,headers:{"Content-Type":"text/html; charset=utf-8","Access-Control-Allow-Origin":T}})}catch(Z){console.error("[Error Handler] Failed to render error page:",Z);let B=(L)=>L.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;");return new Response(`
-      <html>
-        <head><title>Error</title></head>
-        <body>
-          <h1>Error</h1>
-          <p>${B($.message)}</p>
-          <pre>${B($.stack||"")}</pre>
-        </body>
-      </html>
-    `,{status:V,headers:{"Content-Type":"text/html; charset=utf-8"}})}}async function N0($,F){let W=$.statusCode??$.status??500,V=M();if(W>=400&&W<500){let G=$.headers?{...$.headers,...O()}:O();return new Response(P({error:$.name||"ClientError",message:$.message,status:W}),{status:W,headers:G})}if(V)return await J($,F,{status:W});return new Response(P({error:"Internal Server Error",message:"An unexpected error occurred.",status:W}),{status:W,headers:O()})}function O0($,F){return new Response(P({error:"ValidationError",message:"Validation failed",status:422,details:{errors:$}}),{status:422,headers:O()})}async function L0($,F){if(M()){let V=Error(`Route not found: ${$}`);return V.name="NotFoundError",await J(V,F,{status:404})}if(z(F))return new Response(P({error:"NotFound",message:`Route not found: ${$}`,status:404}),{status:404,headers:O()});return new Response(A(404),{status:404,headers:{"Content-Type":"text/html; charset=utf-8"}})}var X=50,t=5,w,S,W0,Z0=10,G0="[Circular]";var _=f(()=>{b();H();w=Symbol.for("stacks.queryTracking"),S=v();W0=["password","secret","token","api_key","apikey","access_key","accesskey","private_key","privatekey","credit_card","creditcard","card_number","cardnumber","cvv","ssn","authorization","credential","aws_secret","aws_access","database_password","db_password","encryption_key","signing_key","bearer","session_id","sessionid","cookie"]});export*from"@stacksjs/bun-router";import("@stacksjs/database").then(({setQueryTracker:$})=>{if(typeof $==="function"){let{trackQuery:F}=(_(),E(Q));$(F)}}).catch(()=>{});export{p0 as withTraceId,g0 as warnOnMultipleRouterInstances,D1 as verifySignedUrlMiddleware,Y1 as verifySignedUrl,k0 as url,W1 as trackQuery,K1 as stream,m1 as signedUrl,J1 as signUrl,c0 as setCurrentRequest,R0 as serverResponse,y0 as serve,w1 as sanitizePathParam,v1 as safePathParam,i0 as runWithRequest,B1 as routeParams,T0 as route,d0 as request,P1 as rateLimitStatus,M1 as rateLimit,a0 as loadRoutes,G1 as listRegisteredRoutes,N1 as isApiRequest,_0 as installMiddlewareHotReload,q0 as getTraceId,V1 as getQueryShapeCounts,l0 as getCurrentRequest,Q0 as findUnresolvableRouteMiddleware,F1 as createValidationErrorResponse,A1 as createStacksSessionStore,S0 as createStacksRouter,C1 as createSessionStore,$1 as createNotFoundResponse,e0 as createMiddlewareErrorResponse,r0 as createErrorResponse,t0 as clearTrackedQueries,X1 as clearRateLimit,A0 as clearMiddlewareCache,E0 as cacheRequestQuery,C0 as assertRouteMiddlewareResolvable,T1 as RedisSessionStore,I1 as PathParamError,u0 as Middleware,_1 as MemorySessionStore,O1 as JSON_CONTENT_TYPE,Q1 as FileSessionStore,U1 as EncryptedSessionStore,S1 as DatabaseSessionStore};

package/dist/middleware.d.ts

@@ -1,37 +0,0 @@
-import type { EnhancedRequest } from '@stacksjs/bun-router';
-export declare interface MiddlewareConfig {
-  name: string
-  priority?: number
-  handle: (request: EnhancedRequest) => void | Promise<void>
-}
-/**
- * Middleware class for defining route middleware
- *
- * Provides a simple, structured way to define middleware handlers
- * that can be attached to routes and route groups.
- *
- * The request object is an EnhancedRequest with helper methods like
- * `bearerToken()`, `get()`, `input()`, `has()`, etc.
- *
- * @example
- * ```ts
- * import { Middleware } from '@stacksjs/router'
- *
- * export default new Middleware({
- *   name: 'Auth',
- *   priority: 1,
- *   async handle(request) {
- *     const token = request.bearerToken()
- *     if (!token) throw new HttpError(401, 'Unauthorized')
- *   },
- * })
- * ```
- */
-export type Request = EnhancedRequest;
-export declare class Middleware {
-  readonly name: string;
-  readonly priority: number;
-  readonly handle: (request: EnhancedRequest) => void | Promise<void>;
-  constructor(config: MiddlewareConfig);
-  toRouterHandler(): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
-}

package/dist/path-sanitize.d.ts

@@ -1,64 +0,0 @@
-/**
- * Validate and return a path parameter, throwing if it's unsafe to use
- * in filesystem interpolation.
- *
- * The default contract is single-segment: no `/`, no `\`, no `..`, no
- * absolute path, no null bytes, no control characters, length ≤ 255.
- * Pass `allowSlashes: true` for a multi-segment path (still rejects
- * the rest).
- *
- * @throws {PathParamError} when the value fails any check.
- */
-export declare function sanitizePathParam(value: unknown, options?: SanitizePathParamOptions): string;
-/**
- * Non-throwing variant. Returns the sanitized value or `null` if any
- * check failed. Use when you want a fast yes/no in a conditional
- * without a try/catch around the throw site.
- */
-export declare function safePathParam(value: unknown, options?: SanitizePathParamOptions): string | null;
-export declare interface SanitizePathParamOptions {
-  context?: string
-  maxLength?: number
-  allowSlashes?: boolean
-}
-/**
- * Path-parameter sanitization helpers.
- *
- * Route params arrive from the URL as untyped strings and are merged
- * directly into `req.params`. Actions that interpolate those values
- * into filesystem paths or shell commands without first scrubbing
- * them are vulnerable to `..`-traversal, absolute-path takeovers, and
- * null-byte truncation attacks.
- *
- * The router itself can't auto-sanitize every param (some are
- * deliberately path-shaped — file servers, asset proxies, etc.). What
- * we ship instead is a single canonical helper that callers reach for
- * at the boundary where the param meets the filesystem.
- *
- * See stacksjs/stacks#1870 R-12.
- *
- * @example
- * ```ts
- * import { sanitizePathParam } from '@stacksjs/router'
- *
- * const filename = sanitizePathParam(req.params.filename, {
- *   context: 'avatar download',
- * })
- * return new Response(Bun.file(path.appPath(`avatars/${filename}`)))
- * ```
- */
-/**
- * Reasons {@link sanitizePathParam} rejects a value. Surfaced via the
- * thrown error so callers can log or branch.
- */
-export type PathParamRejection = | 'empty'
-  | 'not-string'
-  | 'absolute-path'
-  | 'traversal'
-  | 'null-byte'
-  | 'control-char'
-  | 'too-long';
-export declare class PathParamError extends Error {
-  readonly reason: PathParamRejection;
-  constructor(reason: PathParamRejection, value: unknown, context?: string);
-}

package/dist/rate-limit.d.ts

@@ -1,35 +0,0 @@
-/**
- * Check + consume a rate-limit slot for the current scope.
- *
- * @example
- * ```ts
- * await rateLimit('create-post', 10).per('hour')
- * await rateLimit('login-attempts', 5, { identity: email }).per('minute')
- * await rateLimit('expensive-job', 3).over(900) // custom 15-minute ttl
- * ```
- */
-export declare function rateLimit(key: string, max: number, options?: { identity?: string }): {
-    /** Run with a string period name (`'minute'`, `'hour'`, …). */
-    per: (period: Period) => Promise<void>
-    /** Run with a numeric ttl in seconds. */
-    over: (ttlSeconds: number) => Promise<void>
-  };
-/**
- * Read the current bucket state without consuming a slot. Useful for
- * "you have N attempts remaining" hints in dashboards and pre-flight
- * checks. Returns `null` if the limiter's storage doesn't expose
- * `getCount` (the default memory storage does; redis storage may not).
- */
-export declare function rateLimitStatus(key: string, max: number, windowSeconds: number, options?: { identity?: string }): Promise<{ count: number, limit: number, remaining: number } | null>;
-/**
- * Drop the bucket for the given key (e.g. after a successful login,
- * the failed-attempt counter should reset).
- */
-export declare function clearRateLimit(key: string, max: number, windowSeconds: number, options?: { identity?: string }): Promise<void>;
-declare const PERIOD_SECONDS: {
-  second: 1;
-  minute: 60;
-  hour: 3600;
-  day: unknown
-};
-declare type Period = keyof typeof PERIOD_SECONDS;

package/dist/request-augmentation.d.ts

@@ -1,71 +0,0 @@
-import type { FileInfo } from '@stacksjs/bun-router';
-/**
- * Stacks-specific marker fields attached to the request by the
- * router itself and the framework's default middleware.
- *
- * Markers are deliberately prefixed with `_` so they can't collide
- * with userland keys on the request, and their lifetimes are bounded
- * by the request's lifetime — they're never persisted.
- */
-export declare interface StacksRequestMarkers {
-  _corsConfig?: unknown
-  _forceJson?: boolean
-  _skipCsrf?: boolean
-  _compress?: boolean
-  _middlewareParams?: Record<string, string>
-  _requestId?: string
-  _startNs?: bigint
-  _authenticatedUser?: unknown
-  _currentAccessToken?: unknown
-  _bodyParsed?: boolean
-}
-/**
- * Laravel-style request-input macros that Stacks attaches in
- * `enhanceRequest` (router/src/stacks-router.ts). These shadow some
- * of bun-router's `RequestMacroMethods` with Stacks-specific
- * implementations (more permissive `T = any` generics so action
- * callers don't have to specify the return type for every read).
- *
- * Listed here as part of the augmentation so call sites like
- * `request.input(key)` type-check without `as any`.
- */
-export declare interface StacksRequestMacros {
-  input?: <T = unknown>(key: string, defaultValue?: T) => T
-  get?: <T = unknown>(key: string, defaultValue?: T) => T
-  all?: () => Record<string, unknown>
-  only?: <T extends Record<string, unknown>>(keys: string[]) => T
-  except?: <T extends Record<string, unknown>>(keys: string[]) => T
-  has?: (key: string | string[]) => boolean
-  hasAny?: (keys: string[]) => boolean
-  missing?: (key: string) => boolean
-  filled?: (key: string) => boolean
-  integer?: (key: string, defaultValue?: number) => number
-  float?: (key: string, defaultValue?: number) => number
-  boolean?: (key: string, defaultValue?: boolean) => boolean
-  string?: (key: string, defaultValue?: string) => string
-  array?: <T = unknown>(key: string, defaultValue?: T[]) => T[]
-  file?: (key: string) => FileInfo | null
-  files?: (key: string) => FileInfo[]
-  hasFile?: (key: string) => boolean
-  allFiles?: () => Record<string, FileInfo | FileInfo[]>
-  getFiles?: () => Record<string, FileInfo | FileInfo[]>
-  user?: () => Promise<unknown>
-  userToken?: () => Promise<unknown>
-  tokenCan?: (ability: string) => Promise<boolean>
-  tokenCant?: (ability: string) => Promise<boolean>
-  can?: (ability: string, ...args: unknown[]) => Promise<boolean>
-  cannot?: (ability: string, ...args: unknown[]) => Promise<boolean>
-  authorize?: (ability: string, ...args: unknown[]) => Promise<void>
-}
-/**
- * Union of Stacks markers + macros — useful as a single type alias for
- * places that previously cast to `any`.
- */
-export type StacksRequestExtensions = StacksRequestMarkers & StacksRequestMacros;
-declare module '@stacksjs/bun-router' {
-  interface EnhancedRequestextends StacksRequestMarkers  {
-  allFiles?: StacksRequestMacros['allFiles']
-  tokenCan?: StacksRequestMacros['tokenCan']
-  can?: StacksRequestMacros['can']
-}
-}

package/dist/request-context.d.ts

@@ -1,82 +0,0 @@
-import type { EnhancedRequest } from '@stacksjs/bun-router';
-import type { RequestInstance } from '@stacksjs/types';
-/**
- * Read the active trace id, or `undefined` outside any traced scope.
- *
- * Falls back to the request's `_requestId` if no explicit trace was
- * set so the helper is always useful from an HTTP handler — the router
- * sets `_requestId` per request, and that value is the implicit trace
- * for downstream calls until something more specific is configured.
- */
-export declare function getTraceId(): string | undefined;
-/**
- * Run `fn` under a fresh trace scope. Used by queue workers and cron
- * triggers to associate background work with the originating request
- * (or a synthetic id when there's no parent).
- *
- * @example
- * ```ts
- * await withTraceId(genId(), async () => {
- *   await job.handle()
- * })
- * ```
- */
-export declare function withTraceId<T>(id: string, fn: () => T): T;
-/**
- * Run `fetcher()` once per `key` per request. Subsequent callers within
- * the same request lifecycle await the cached Promise.
- *
- * @example
- * ```ts
- * const user = await cacheRequestQuery(`User.find:${id}`, () => User.find(id))
- * ```
- */
-export declare function cacheRequestQuery<T>(key: string, fetcher: () => T | Promise<T>): Promise<T>;
-/**
- * Set the current request context
- * Called by middleware/router when handling a request
- */
-export declare function setCurrentRequest(req: EnhancedRequest): void;
-/**
- * Clear the current request context.
- *
- * `setCurrentRequest` uses `AsyncLocalStorage.enterWith`, which mutates the
- * caller's async scope and never restores it. Call this in test teardown
- * (`afterEach`) whenever a test body calls `setCurrentRequest`, so the leaked
- * frame doesn't poison subsequently-collected test files (bun's runner
- * mis-registers tests when collected on a foreign async frame).
- */
-export declare function clearCurrentRequest(): void;
-/**
- * Run a function with a request context
- * All code executed within the callback will have access to the request
- */
-export declare function runWithRequest<T>(req: EnhancedRequest, fn: () => T): T;
-/**
- * Get the current request from context
- */
-export declare function getCurrentRequest(): EnhancedRequest | undefined;
-/**
- * Request proxy that provides access to the current request
- * (Laravel's `request()` helper, but typed).
- *
- * The proxy is statically typed as {@link RequestInstance} —
- * the canonical Stacks-side action-request surface
- * (stacksjs/stacks#1851 Phase 1). All the macros action handlers
- * reach for (`all`, `get`, `input`, `cookies`, `param`, `validate`,
- * `user`, `bearerToken`, …) resolve to their declared types instead
- * of `any`, eliminating most `(request as any)` casts in action code.
- *
- * Runtime is unchanged — the proxy still delegates to whichever
- * `EnhancedRequest` is in the AsyncLocalStorage slot. The type swap
- * is API-compatible: every method action code uses on `request`
- * existed on either type already, but only `RequestInstance` carries
- * the model-aware / path-aware narrowing.
- *
- * Methods worth knowing about:
- * - `bearerToken()` — Authorization header
- * - `user()` — authenticated user (async)
- * - `userToken()` — current access token (async)
- * - `tokenCan(ability)` / `tokenCant(ability)` — async ability checks
- */
-export declare const request: RequestInstance;

package/dist/route-loader.d.ts

@@ -1,5 +0,0 @@
-import type { RouteRegistry } from './route-types';
-/**
- * Load all routes from the registry
- */
-export declare function loadRoutes(registry: RouteRegistry): Promise<void>;

package/dist/route-types.d.ts

@@ -1,12 +0,0 @@
-/**
- * Route registry types — owned by `@stacksjs/router` because the router
- * consumes them. `app/Routes.ts` (the project-level route map) imports
- * these via the public package name rather than a relative reach into
- * the framework defaults tree (stacksjs/stacks#1863, T-10).
- */
-export declare interface RouteDefinition {
-  path: string
-  prefix?: string
-  middleware?: string | string[]
-}
-export type RouteRegistry = Record<string, string | RouteDefinition>;

package/dist/security-headers.d.ts

@@ -1,20 +0,0 @@
-/**
- * Apply the default security headers to a Headers instance in-place.
- *
- * Headers applied unconditionally (cheap, no compat risk):
- * - `X-Content-Type-Options: nosniff` — blocks MIME-sniff XSS
- * - `X-Frame-Options: SAMEORIGIN` — clickjacking protection (CSP
- *   `frame-ancestors` is the modern equivalent but XFO still ships)
- * - `Referrer-Policy: strict-origin-when-cross-origin` — modern default
- *
- * Production-only:
- * - `Strict-Transport-Security: max-age=31536000; includeSubDomains` —
- *   tells browsers to commit to HTTPS for a year. Omits `preload` since
- *   that's an irreversible commitment to the browser preload list.
- *
- * Skips overwriting any header that's already set — explicit userland
- * config wins. Skips entirely when `STACKS_SECURITY_HEADERS_DISABLE=true`.
- */
-export declare function applySecurityHeaders(headers: Headers): void;
-/** Test helper — reset the cached env-derived flags. */
-export declare function __resetSecurityHeadersCache(): void;

package/dist/session-factory.d.ts

@@ -1,57 +0,0 @@
-import { createSessionStore } from '@stacksjs/bun-router';
-import type { RedisClient, SessionConfig, SessionData, SessionStore } from '@stacksjs/bun-router';
-// Re-export bun-router's session types so app code only has to
-// import from `@stacksjs/router` (one less package boundary to
-// learn). Drivers stay accessible by name for callers that want
-// to assemble a custom store manually.
-export type {
-  RedisClient,
-  SessionConfig,
-  SessionData,
-  SessionStore,
-};
-/**
- * Build a session store from the Stacks config. Mirrors what
- * `mail` / `Jobs` do for their driver registries — call once at
- * boot, pass the result into the session middleware.
- *
- * @example
- * ```ts
- * // config/session.ts (typical)
- * export const session = {
- *   driver: 'redis',
- *   ttl: 60 * 60 * 24,         // 24h
- *   cookie: { name: 'sid', httpOnly: true, sameSite: 'lax' },
- *   redis: { client: useRedis() },
- * } satisfies StacksSessionConfig
- *
- * // Then at boot:
- * const store = createStacksSessionStore(session)
- * app.use(sessionMiddleware({ store }))
- * ```
- */
-export declare function createStacksSessionStore(config: StacksSessionConfig): SessionStore<SessionData>;
-/**
- * Stacks-level session configuration. Extends bun-router's
- * {@link SessionConfig} with:
- *
- *   - `encrypt`: opt-in/out of {@link EncryptedSessionStore}
- *     wrapping (default: `'auto'` — on in production, off in
- *     dev/test where readability matters more than encryption-
- *     at-rest)
- *   - `appKey`: override key for the encryption (defaults to
- *     `process.env.APP_KEY`)
- *
- * All other fields pass through to bun-router unchanged.
- */
-export declare interface StacksSessionConfig extends SessionConfig {
-  encrypt?: boolean | 'auto'
-  appKey?: string
-}
-export {
-  DatabaseSessionStore,
-  FileSessionStore,
-  MemorySessionStore,
-  RedisSessionStore,
-  createSessionStore,
-} from '@stacksjs/bun-router';

package/dist/signed-url.d.ts

@@ -1,50 +0,0 @@
-import type { EnhancedRequest } from '@stacksjs/bun-router';
-/**
- * Sign an existing URL (full or path-only). Returns a new URL string
- * with `expires` (optional) and `signature` query params appended.
- *
- * Path-only inputs (`/api/email/verify?user=42`) inherit `APP_URL` as
- * the origin — same convention as {@link buildUrl}.
- */
-export declare function signUrl(input: string, options?: SignedUrlOptions): string;
-/**
- * Convenience wrapper that resolves a named route to a URL via {@link buildUrl}
- * and then signs it. Mirrors Laravel's `URL::signedRoute()`.
- *
- * @example
- * ```ts
- * route.get('/api/email/verify', VerifyEmailAction).name('email.verify')
- * const link = signedUrl('email.verify', { user: 42 }, { ttl: 60 * 60 * 24 })
- * // → https://app.example.com/api/email/verify?user=42&expires=1716470400&signature=…
- * ```
- */
-export declare function signedUrl(routeName: string, params?: Record<string, string | number>, options?: SignedUrlOptions): string;
-/**
- * Verify the `signature` (and optional `expires`) on an incoming URL.
- * Returns a discriminated result so callers can pick their own status
- * code per failure mode.
- */
-export declare function verifySignedUrl(input: string | URL): SignedUrlVerifyResult;
-/**
- * Middleware shape for `route.middleware('signed')`. Verifies the
- * incoming URL's signature and throws a `Response` (the router's
- * short-circuit contract) when it fails. Drop in as a route-level
- * middleware on any URL minted by {@link signedUrl}.
- *
- * @example
- * ```ts
- * route.get('/email/verify', 'Actions/VerifyEmail').middleware('signed')
- * ```
- */
-export declare function verifySignedUrlMiddleware(req: EnhancedRequest): Promise<void>;
-export declare interface SignedUrlOptions {
-  expiresAt?: number
-  ttl?: number
-}
-/**
- * Result of {@link verifySignedUrl}. The `reason` only fires when `valid`
- * is `false` — gives callers (and middleware) enough to decide whether
- * to log, return 401, or return 410 (expired vs. tampered).
- */
-export type SignedUrlVerifyResult = | { valid: true }
-  | { valid: false, reason: 'missing-signature' | 'expired' | 'invalid-signature' }

package/dist/stacks-router.d.ts

@@ -1,213 +0,0 @@
-import type { Server } from 'bun';
-import './request-augmentation';
-import { Router } from '@stacksjs/bun-router';
-import type { ActionHandler, EnhancedRequest, Route, ServerOptions } from '@stacksjs/bun-router';
-import type { ActionValidations, ValidationResult } from '@stacksjs/actions';
-/**
- * Warn (once per process) when more than one @stacksjs/router module has loaded
- * (stacksjs/stacks#1975 / #1982). Routing still works — the route table and
- * request context are process-global singletons — but a duplicated install is
- * worth surfacing. Called at serve() boot. Returns whether a split was detected
- * so callers/tests can assert on it without capturing logs.
- */
-export declare function warnOnMultipleRouterInstances(): boolean;
-/**
- * Generate a full URL for a named route, like Laravel's route() helper.
- *
- * Validates path parameters at call time so a typo'd argument
- * (`url('user.post', { userId: 1 })` against `/users/{id}`) throws
- * immediately with a list of expected names instead of silently
- * producing a URL with `{id}` left literal in the path.
- *
- * @example
- * ```typescript
- * // Define a named route
- * route.get('/api/email/unsubscribe', 'Actions/UnsubscribeAction').name('email.unsubscribe')
- *
- * // Generate URL
- * url('email.unsubscribe', { token: 'abc-123' })
- * // → https://stacksjs.com/api/email/unsubscribe?token=abc-123
- *
- * // With path parameters
- * route.get('/users/{id}/posts/{postId}', handler).name('user.post')
- * url('user.post', { id: 42, postId: 7 })
- * // → https://stacksjs.com/users/42/posts/7
- * ```
- */
-export declare function url(routeName: string, params?: Record<string, string | number>): string;
-/**
- * List the placeholder names a named route expects — handy for
- * codegen/test cases and for detecting typos before runtime.
- */
-export declare function routeParams(routeName: string): string[];
-/**
- * Snapshot of the registered routes — `{ method, path, name? }` per
- * route. Used by `buddy route:list` and the dev-server startup banner.
- */
-export declare function listRegisteredRoutes(): Array<{ method: string, path: string, name?: string }>;
-/**
- * Clear the middleware cache (useful for hot-reload in development).
- *
- * `installMiddlewareHotReload()` will wire this up automatically when
- * called from the dev server — production should never invoke it.
- */
-export declare function clearMiddlewareCache(): void;
-/**
- * Watch `app/Middleware/` and `app/Middleware.ts` and invalidate the
- * cached middleware modules whenever a file changes. Intended for the
- * dev server only — calling this in production is a no-op (the
- * watcher handle is created but never fires anything user code cares
- * about). Returns a `disposer()` to stop watching.
- *
- * Without this hook, editing a middleware file in dev requires a
- * full server restart to see the change — the import map caches the
- * old version forever.
- */
-export declare function installMiddlewareHotReload(): () => void;
-/**
- * Resolve every middleware alias referenced by a registered route and
- * report the ones that don't load. `csrf` is always checked too — it's
- * auto-injected on unsafe methods even when no route lists it.
- *
- * Resolution is inherently lazy (`.middleware(name)` is a sync chainable
- * that just records a string; the alias map and middleware modules load
- * via async dynamic import), so a throw at literal registration time is
- * impossible. Calling this after all routes are registered — the end of
- * `importRoutes()` and the compiled-binary boot in core/server — IS
- * effectively registration-time validation. See stacksjs/stacks#1957.
- */
-export declare function findUnresolvableRouteMiddleware(): Promise<Array<{ alias: string, routes: string[] }>>;
-/**
- * Throw when any registered route references a middleware alias that
- * cannot be resolved. Fail-closed boot validation: a typo'd `auth` alias
- * must abort startup loudly, not serve the route unprotected (the
- * request-time guard in createMiddlewareHandler 500s as a backstop).
- */
-export declare function assertRouteMiddlewareResolvable(): Promise<void>;
-/**
- * Run an action's declarative `validations:` against the request.
- *
- * @internal Exported for regression coverage of path-param coercion
- * (stacksjs/stacks#1865). Production callers should rely on the
- * router's action-resolution path, which invokes this for you.
- */
-export declare function validateActionInput(req: EnhancedRequest, validations: ActionValidations): Promise<ValidationResult>;
-export declare function stream(source: ReadableStream | AsyncIterable<string | Uint8Array>, options?: StreamOptions): Response;
-// Decorate the incoming request with the helpers the framework's middleware
-// and actions assume are always available. Names follow Laravel's convention
-// because that's the API surface Stacks userland expects.
-export declare function enhanceRequest(req: EnhancedRequest): EnhancedRequest;
-/**
- * Create a Stacks-enhanced router
- */
-export declare function createStacksRouter(config?: StacksRouterConfig): StacksRouterInstance;
-/**
- * Handle a server request through the router
- * This is the main entry point for the Stacks server
- */
-export declare function serverResponse(request: Request, _body?: string): Promise<Response>;
-// Export serve function that uses the default router
-export declare function serve(options?: ServerOptions): Promise<Server<unknown>>;
-export declare const route: StacksRouterInstance;
-declare interface StacksRouterConfig {
-  verbose?: boolean
-  apiPrefix?: string
-}
-declare interface GroupOptions {
-  prefix?: string
-  middleware?: string | string[]
-  apiResponse?: boolean
-}
-declare interface ResourceRouteOptions {
-  only?: ResourceAction[]
-  except?: ResourceAction[]
-  middleware?: string | string[]
-}
-/**
- * Chainable route interface for middleware and naming support
- */
-declare interface ChainableRoute {
-  middleware: (name: string) => ChainableRoute
-  name: (routeName: string) => ChainableRoute
-  skipCsrf: () => ChainableRoute
-  requireCsrf: () => ChainableRoute
-  rateLimit: (max: number, window: 'second' | 'minute' | 'hour' | 'day' | number) => ChainableRoute
-}
-/**
- * Helper for streaming responses — wraps a `ReadableStream` or async
- * generator with the right headers for the chosen content type.
- *
- * Common shapes:
- *
- *   ```ts
- *   // Server-Sent Events
- *   return stream(async function* () {
- *     for await (const evt of source) yield `data: ${JSON.stringify(evt)}\n\n`
- *   }, { type: 'sse' })
- *
- *   // Chunked JSON (NDJSON) — one JSON object per line
- *   return stream(async function* () {
- *     for await (const row of rows) yield `${JSON.stringify(row)}\n`
- *   }, { type: 'ndjson' })
- *
- *   // Raw bytes — caller supplies a ReadableStream of Uint8Array chunks
- *   return stream(myReadable, { contentType: 'application/octet-stream' })
- *   ```
- *
- * The wrapper sets `Cache-Control: no-cache` and `Connection: keep-alive`
- * for SSE — the two headers a sane proxy / browser pair won't ignore — and
- * leaves backpressure / cancellation to the underlying stream.
- *
- * See stacksjs/stacks#1870 R-4.
- */
-export declare interface StreamOptions {
-  type?: 'sse' | 'ndjson'
-  contentType?: string
-  headers?: HeadersInit
-  status?: number
-}
-export declare interface StacksRouterInstance {
-  bunRouter: Router
-  routes: Route[]
-  get: (path: string, handler: StacksHandler) => ChainableRoute
-  post: (path: string, handler: StacksHandler) => ChainableRoute
-  put: (path: string, handler: StacksHandler) => ChainableRoute
-  patch: (path: string, handler: StacksHandler) => ChainableRoute
-  delete: (path: string, handler: StacksHandler) => ChainableRoute
-  options: (path: string, handler: StacksHandler) => ChainableRoute
-  group: (options: GroupOptions, callback: () => void | Promise<void>) => StacksRouterInstance | Promise<StacksRouterInstance>
-  resource: (name: string, handler: string, options?: ResourceRouteOptions) => StacksRouterInstance
-  match: (methods: string[], path: string, handler: StacksHandler) => ChainableRoute
-  health: () => StacksRouterInstance
-  use: (middleware: ActionHandler | ((req: EnhancedRequest, next: () => Promise<Response>) => Response | Promise<Response>)) => StacksRouterInstance
-  register: (routePath: string, options?: { prefix?: string, middleware?: string | string[] }) => Promise<StacksRouterInstance>
-  serve: (options?: ServerOptions) => Promise<Server<unknown>>
-  handleRequest: (req: Request) => Promise<Response>
-  getAllowedMethods: (pathname: string, domain?: string) => string[]
-  importRoutes: () => Promise<void>
-  loadDiscoveredRoutes: () => Promise<void>
-}
-declare type RouteHandlerFn = (_req: EnhancedRequest) => Response | Promise<Response>;
-declare type StacksHandler = string | RouteHandlerFn;
-declare type ResourceAction = 'index' | 'store' | 'show' | 'update' | 'destroy';
-/**
- * FIFO-bounded Map. Wraps `Map` with a hard size cap; on overflow,
- * the oldest entry (Map insertion order) is evicted. Used for the
- * router's small framework-internal caches whose size is normally
- * bounded by action count, but which had no upper limit before —
- * tests that instantiate many short-lived routers would leak entries
- * across `createStacksRouter()` calls (stacksjs/stacks#1863 T-8).
- *
- * Insertion-order LRU is appropriate here because the access pattern
- * is "set once at action-load time, then many reads" — refreshing on
- * get would buy nothing since reads dominate.
- */
-declare class BoundedMap<K, V> {
-  constructor(max: number);
-  get(key: K): V | undefined;
-  has(key: K): boolean;
-  set(key: K, value: V): this;
-  delete(key: K): boolean;
-  clear(): void;
-  get size(): number;
-}