@stacksjs/router 0.74.47 → 0.74.48

package/dist/health.js

@@ -1 +1 @@
-export async function runHealthProbes(probes,options={}){const timeoutMs=options.timeoutMs??1500,now=options.now??Date.now,entries=await Promise.all(probes.map(async({name,run})=>{const startedAt=now();let timeout;try{await Promise.race([run(),new Promise((_resolve,reject)=>{timeout=setTimeout(()=>reject(Error("timeout")),timeoutMs)})]);return[name,{ok:!0,ms:Math.max(0,now()-startedAt)}]}catch(error){return[name,{ok:!1,ms:Math.max(0,now()-startedAt),message:error instanceof Error?error.message:String(error)}]}finally{if(timeout)clearTimeout(timeout)}})),checks=Object.fromEntries(entries);return{status:Object.values(checks).every((check)=>check.ok)?"healthy":"degraded",checks,timestamp:now()}}export async function checkApplicationHealth(options={}){return runHealthProbes([{name:"database",async run(){const{db}=await import("@stacksjs/database"),unsafe=db.unsafe;if(typeof unsafe!=="function")throw Error("database driver does not expose a raw health probe");await unsafe.call(db,"SELECT 1")}},{name:"cache",async run(){const{cache}=await import("@stacksjs/cache"),key=`__health__:${Date.now()}`;let stored=!1;try{await cache.set(key,1,5);stored=!0}finally{if(stored)await cache.del(key)}}}],options)}
+export async function runHealthProbes(probes,options={}){const timeoutMs=options.timeoutMs??1500,now=options.now??Date.now,entries=await Promise.all(probes.map(async({name,run})=>{const startedAt=now();let timeout;try{await Promise.race([run(),new Promise((_resolve,reject)=>{timeout=setTimeout(()=>reject(Error("timeout")),timeoutMs)})]);return[name,{ok:!0,ms:Math.max(0,now()-startedAt)}]}catch(error){return[name,{ok:!1,ms:Math.max(0,now()-startedAt),message:error instanceof Error?error.message:String(error)}]}finally{if(timeout)clearTimeout(timeout)}})),checks=Object.fromEntries(entries);return{status:Object.values(checks).every((check)=>check.ok)?"healthy":"degraded",checks,timestamp:now()}}export async function checkApplicationHealth(options={}){return runHealthProbes([{name:"database",async run(){const{db}=await import("@stacksjs/database/runtime"),unsafe=db.unsafe;if(typeof unsafe!=="function")throw Error("database driver does not expose a raw health probe");await unsafe.call(db,"SELECT 1")}},{name:"cache",async run(){const{cache}=await import("@stacksjs/cache"),key=`__health__:${Date.now()}`;let stored=!1;try{await cache.set(key,1,5);stored=!0}finally{if(stored)await cache.del(key)}}}],options)}

package/dist/stacks-router.d.ts

@@ -1,6 +1,9 @@
+import type { Server } from 'bun';
 import './request-augmentation';
-import type { ActionPath, EnhancedRequest, MiddlewareReference, RequestFor, Route } from '@stacksjs/bun-router';
-import type { ActionResult } from '@stacksjs/actions';
+import { response } from '@stacksjs/bun-router';
+import { Router } from '@stacksjs/bun-router';
+import type { ActionHandler, ActionPath, EnhancedRequest, ExtractRouteParams, KnownRouteName, MiddlewareHandler as BunMiddlewareHandler, MiddlewareReference, PathForRouteName, RequestFor, Route, ServerOptions } from '@stacksjs/bun-router';
+import type { ActionResult, ActionValidations, ValidationResult } from '@stacksjs/actions';
 /**
  * Run every registered boot hook, once per process.
  *
@@ -21,9 +24,219 @@ export declare function warnOnMultipleRouterInstances(): boolean;
  * overlapping constrained, domain-scoped, or mixed-parameter route expected.
  */
 export declare function shouldUseNativeRoutesByDefault(routes: readonly Route[]): boolean;
+// False positive: this is an overload signature, which has no body for its
+// parameters to be used in. The implementation below uses them.
+// eslint-disable-next-line unused-imports/no-unused-vars
+export declare function url<TName extends KnownRouteName>(routeName: TName, ...params: RequiresUrlParams<TName> extends true ? [params: UrlParams<TName>] : [params?: UrlParams<TName>]): 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[];
+/**
+ * Every named route, as `name → path`.
+ *
+ * `listRegisteredRoutes()` reports a name by searching the named registry for a
+ * matching path, which answers "what is this route called" and cannot answer
+ * "what routes are there names for" - two routes on one path give the first
+ * name found, and a name whose route was never registered is invisible.
+ *
+ * The type generator needs the second question: it writes this map into the
+ * router's type registry so `url('users.shwo')` stops compiling. Reading the
+ * registry directly is the only way to get every name.
+ */
+export declare function listNamedRoutes(): Record<string, string>;
+/**
+ * Snapshot of the registered routes — `{ method, path, name?, handler? }` per
+ * route. Used by `buddy route:list`, the dev-server startup banner, and the
+ * OpenAPI generator.
+ *
+ * `handler` is the string a route was registered with (`'Actions/…'`), and it
+ * is absent for an inline function, which has no file to read anything out of.
+ * The OpenAPI generator needs it to find the action's `validations`: it used to
+ * guess the path by title-casing the route *name* (`posts.store` →
+ * `Actions/PostsStoreAction`), which found a schema for the handful of routes
+ * following that convention and silently described every other endpoint as
+ * taking no input at all. The registry has known the real answer the whole
+ * time; it was simply not being reported.
+ */
+export declare function listRegisteredRoutes(): Array<{ method: string, path: string, name?: string, handler?: string, action?: RouterAction, middleware?: string[] }>;
+/**
+ * The merged middleware alias map: the framework defaults, with the
+ * application's own map on top.
+ *
+ * Exported for diagnostics and tests. A copy, so a caller cannot edit the
+ * cached map out from under the router.
+ */
+export declare function middlewareAliases(): Promise<Record<string, string>>;
+/*.ts` as the single middleware registry instead of asking
+ * the application to define a second set of anonymous page-only functions.
+ */
+export declare function loadMiddlewareHandlers(): Promise<Record<string, MiddlewareHandler>>;
+/**
+ * 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;
+/**
+ * Drop every registered route-state mapping.
+ *
+ * The registry is module-scoped and lives for the life of the process, which
+ * is what `listRegisteredRoutes()` and the boot-time validators read. That is
+ * correct at runtime — routes are registered once at boot — but it means a
+ * test that registers a route keeps it visible to every later caller in the
+ * same process, including `assertRouteMiddlewareResolvable()`. A suite that
+ * deliberately registers an unresolvable alias therefore made an unrelated
+ * file's `serverResponse()` throw on routes it never declared.
+ *
+ * `clearMiddlewareCache()` deliberately does NOT do this: it flushes resolved
+ * middleware so a hot-reloaded file is re-read, while the routes themselves
+ * must survive. Clearing the route table is a separate, coarser action.
+ */
+export declare function clearRouteMiddlewareRegistry(): 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>;
+/**
+ * Whether this request is asking "would this be accepted?" rather than
+ * "do this" (stacksjs/stacks#2226).
+ *
+ * An Action's `validations:` block was a server-only artifact: nothing could
+ * read it from a template or a client script, so every form in every app
+ * retyped the rules in the browser and the two copies drifted. The framework's
+ * own defaults demonstrated it — the browser refused a 7-character password
+ * that `POST /register` would have accepted.
+ *
+ * Rather than serialise the rules (a `schema.*` chain is a live object with
+ * no faithful JSON projection), the client asks the real endpoint to run the
+ * real rules and stops short of the side effect. Same shape as Laravel
+ * Precognition, and deliberately header-compatible with it.
+ *
+ * `?_validate=1` is accepted too: a header cannot be set on a plain form
+ * submission or a `<script client>` block using a bare fetch shorthand, and
+ * requiring one would have put this out of reach of the simplest caller.
+ */
+export declare function precognitionRequest(req: EnhancedRequest, knownHeader?: string | null): { only: string[] } | null;
+/**
+ * The "nothing to report" answer to a precognition request. 204 rather than an
+ * empty 200 so a client cannot mistake it for the action's real result.
+ *
+ * `Vary` because the same URL and method now has two different answers
+ * depending on a request header — without it a shared cache is entitled to
+ * serve this 204 to a caller that meant to submit.
+ */
+export declare function precognitionSuccess(): Response;
+/** Whether a route handler is an action rather than a plain function. */
+export declare function isRouterAction(handler: unknown): handler is RouterAction;
+/**
+ * Turn a resolved action into the function the route actually runs.
+ *
+ * Split out of the string-resolution path so registering an action by import
+ * (`createTypedRouter().get('/x', ShowAction)`) and registering it by name
+ * (`route.get('/x', 'Actions/ShowAction')`) share one runtime path. The two
+ * forms differ only in when the module is loaded and in what the compiler can
+ * see; everything below - validation, precognition, `authorize`, `before`,
+ * result formatting, error reporting - is the same code for both.
+ *
+ * `handlerKey` identifies the action for the CSRF skip cache and for error
+ * labels. It is the handler string when there is one, and the route key
+ * otherwise.
+ */
+export declare function wrapAction(action: RouterAction, handlerKey: string): RouteHandlerFn;
+declare function createValidationFieldLabel(field: string): { label: string, decorate: (message: string) => string };
+export declare function validateActionInput(req: EnhancedRequest, validations: ActionValidations): Promise<ValidationResult>;
+export declare function stream(source: ReadableStream | AsyncIterable<string | Uint8Array>, options?: StreamOptions): Response;
+/** Test / hot-reload seam: forget the resolved module. */
+export declare function clearCsrfModuleCache(): void;
+export declare function enhanceRequest(req: EnhancedRequest, initializeRequestId?: boolean): EnhancedRequest;
+/**
+ * Create a Stacks-enhanced router
+ */
+export declare function createStacksRouter(config?: StacksRouterConfig): StacksRouterInstance;
+/**
+ * Tell the file-based view renderer where this application keeps its templates.
+ *
+ * Two different programs render `.stx` in a Stacks app and they were not
+ * agreeing. `buddy dev` and the production server go through
+ * `bun-plugin-stx`'s own `serve()`, which is handed the components, layouts and
+ * partials directories explicitly. `route.serve()` goes through bun-router's
+ * file routing, which was handed nothing - so its components directory fell
+ * back to `<viewsDir>/components`, and `resources/components`, where every
+ * Stacks app actually keeps them, was never looked in.
+ *
+ * The failure is silent in the direction that hides bugs. The page still
+ * answers 200; the component is replaced inline with
+ * `[Error loading component: ENOENT ...]`. So a test that boots the router and
+ * asserts on rendered HTML cannot see any component at all, and reads as though
+ * the feature under test were missing rather than the harness.
+ *
+ * Only fills in what has not been set: an application that called
+ * `route.bunRouter.views(...)` itself has said something more specific, and
+ * this must not overwrite it.
+ *
+ * **It deliberately does not set `viewsPath`.** Naming one switches on
+ * file-based route discovery, which walks the whole views tree - so an
+ * application that never asked for file routing would start doing it because a
+ * directory happened to exist. Where the views are is already decided
+ * elsewhere; the only thing missing was where the *components* are.
+ */
+export declare function configureViewDirectories(bunRouter: Router): void;
+/*.ts` works.
+ *
+ * The two functions are coupled and the coupling is bun-router's, not ours:
+ * `serve()` calls {@link configureViewDirectories} after this, and that only
+ * backs off because `disableFileRouting()` happens to leave a non-empty
+ * `_fileRoutingConfig` behind. Were that flag ever to move to a field of its
+ * own, `configureViewDirectories` would overwrite the config and re-mount every
+ * template. `api-view-routing.test.ts` drives both, in that order, so the
+ * upgrade that changes it fails a test rather than quietly restoring the site
+ * to the API port.
+ *
+ * @returns whether file routing was switched off by this call.
+ */
+export declare function disableViewRouting(bunRouter: Router): boolean;
+/**
+ * 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>>;
 declare const CSRF_DEFAULT: 0;
 declare const CSRF_SKIPPED: 1;
 declare const CSRF_REQUIRED: 2;
+export declare const route: StacksRouterInstance;
 /**
  * Warn (once per process) when more than one @stacksjs/router module has loaded
  * (stacksjs/stacks#1975 / #1982). Routing still works — the route table and
@@ -70,6 +283,11 @@ export declare interface StacksRouterConfig {
   csrf?: boolean
   requestContext?: boolean
 }
+declare interface GroupOptions {
+  prefix?: string
+  middleware?: MiddlewareReference | MiddlewareReference[]
+  apiResponse?: boolean
+}
 /** The file-name half each CRUD action is composed from. */
 declare interface ResourceKindOf {
   index: 'Index'
@@ -88,6 +306,118 @@ export declare interface ChainableRoute {
   requireCsrf: () => ChainableRoute
   rateLimit: (max: number, window: 'second' | 'minute' | 'hour' | 'day' | number) => ChainableRoute
 }
+/** Represents a middleware module with a handle method */
+declare interface MiddlewareHandler {
+  handle: (req: EnhancedRequest) => Promise<void> | void
+  priority?: number
+}
+/**
+ * Anything the router is willing to treat as an action.
+ *
+ * Structural rather than `instanceof Action`, because an action can also be a
+ * plain object with a `handle()` - the framework's own defaults include both
+ * shapes - and because a duplicated install would make an `instanceof` check
+ * reject a perfectly good action from the other copy of the package.
+ */
+export declare interface RouterAction {
+  handle: (req: any) => unknown
+  validations?: ActionValidations
+  authorize?: (req: any) => unknown
+  before?: (req: any) => unknown
+  skipCsrf?: boolean
+  csrf?: boolean
+  apiResponse?: boolean
+  model?: unknown
+  modelDefinition?: unknown
+  name?: string
+  responses?: unknown
+  responseHeaders?: unknown
+  requestHeaders?: unknown
+}
+/**
+ * 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: {
+    <TPath extends string>(path: TPath, handler: TypedInlineRouteHandler<TPath>): ChainableRoute
+    (path: string, handler: StacksHandler): ChainableRoute
+  }
+  post: {
+    <TPath extends string>(path: TPath, handler: TypedInlineRouteHandler<TPath>): ChainableRoute
+    (path: string, handler: StacksHandler): ChainableRoute
+  }
+  put: {
+    <TPath extends string>(path: TPath, handler: TypedInlineRouteHandler<TPath>): ChainableRoute
+    (path: string, handler: StacksHandler): ChainableRoute
+  }
+  patch: {
+    <TPath extends string>(path: TPath, handler: TypedInlineRouteHandler<TPath>): ChainableRoute
+    (path: string, handler: StacksHandler): ChainableRoute
+  }
+  delete: {
+    <TPath extends string>(path: TPath, handler: TypedInlineRouteHandler<TPath>): ChainableRoute
+    (path: string, handler: StacksHandler): ChainableRoute
+  }
+  options: {
+    <TPath extends string>(path: TPath, handler: TypedInlineRouteHandler<TPath>): ChainableRoute
+    (path: string, handler: StacksHandler): ChainableRoute
+  }
+  group: (options: GroupOptions, callback: () => void | Promise<void>) => StacksRouterInstance | Promise<StacksRouterInstance>
+  resource: <TBase extends string, TOnly extends ResourceAction = never, TExcept extends ResourceAction = never>(
+    name: string,
+    handler: TBase & ResourceBaseCheck<TBase, ActiveResourceActions<TOnly, TExcept>>,
+    options?: {
+      only?: readonly TOnly[]
+      except?: readonly TExcept[]
+      middleware?: MiddlewareReference | MiddlewareReference[]
+    },
+  ) => StacksRouterInstance
+  match: {
+    <TPath extends string>(methods: string[], path: TPath, handler: TypedInlineRouteHandler<TPath>): ChainableRoute
+    (methods: string[], path: string, handler: StacksHandler): ChainableRoute
+  }
+  health: () => StacksRouterInstance
+  use: (middleware: ActionHandler | BunMiddlewareHandler) => StacksRouterInstance
+  register: (routePath: string, options?: { prefix?: string, middleware?: MiddlewareReference | MiddlewareReference[] }) => Promise<StacksRouterInstance>
+  booting: (name: string, run: () => void | Promise<void>) => 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 AsyncRouteHandlerFn = (
   req: EnhancedRequest,
@@ -155,3 +485,101 @@ declare type ResourceBaseCheck<TBase extends string, TActive extends ResourceAct
     ? unknown
     : { 'these actions do not exist': MissingResourceActions<TBase, TActive> }
 declare type RouteCsrfMode = typeof CSRF_DEFAULT | typeof CSRF_SKIPPED | typeof CSRF_REQUIRED;
+declare type CorsHeaderApplier = (req: Request, res: Response, cfg?: unknown) => Response;
+declare type CompressionApplier = (req: Request, res: Response, bodySizeUpperBound?: number) => Promise<Response>;
+/**
+ * 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
+ * ```
+ */
+/**
+ * The params a named route needs, plus anything else that becomes query string.
+ *
+ * The required half comes from the path the name resolves to, so
+ * `url('user.post', { id: 42 })` against `/users/{id}/posts/{postId}` stops
+ * compiling instead of throwing at call time. Extra keys stay allowed: the
+ * implementation appends whatever it did not consume as a query string, which
+ * is what `url('email.unsubscribe', { token })` relies on.
+ */
+export type UrlParams<TName extends string> = { [K in keyof ExtractRouteParams<PathForRouteName<TName>>]: string | number }
+    & Record<string, string | number>;
+/** The keys of `T` that are not optional. */
+declare type RequiredParamKeys<T> = { [K in keyof T]-?: object extends Pick<T, K> ? never : K }[keyof T];
+/**
+ * Whether `url()` must be given a second argument.
+ *
+ * Keyed on REQUIRED params: a path whose only placeholder is optional is
+ * reachable with nothing at all, and demanding an empty object for it would be
+ * the type getting in the way of the truth.
+ */
+declare type RequiresUrlParams<TName extends string> = [RequiredParamKeys<ExtractRouteParams<PathForRouteName<TName>>>] extends [never] ? false : true;
+/**
+ * Run an action's declarative `validations:` against the request.
+ *
+ * The action path uses this synchronous core because input collection and the
+ * validator contract are synchronous. The exported wrapper below stays
+ * Promise-based for compatibility with callers that chain or await it.
+ */
+declare type ActionRuleTest = (value: unknown) => boolean;
+declare type ActionValidationEntry = [string, ActionValidations[string], ActionRuleTest[]?, ReturnType<typeof createValidationFieldLabel>?];
+/**
+ * Per-request read-routing context.
+ *
+ * The database package tracks writes per async context so that a request
+ * which reads back what it just wrote is never served from a read replica
+ * (replication is asynchronous, so the row may not be there yet). That
+ * tracking only works if something establishes the context at the request
+ * boundary — without this, `contextHasWritten()` has no store to consult,
+ * always reports false, and every read routes to a replica including the
+ * one immediately following a write. The safety rule would be dead code.
+ *
+ * Loaded lazily rather than imported: `@stacksjs/database` already depends
+ * on `@stacksjs/router`, so a static import here would close a package
+ * cycle. The dynamic import is resolved once and cached, and the fallback
+ * is a plain pass-through so a build without the database package (or an
+ * older one) still serves requests.
+ */
+declare type ContextDispatcher = <T, A>(fn: (arg: A) => T, arg: A) => T;
+declare type ContextRunner = <T>(fn: () => T) => T;
+declare type NativeRouteHandler = (request: Request) => Response | Promise<Response>;
+declare type NativeRouteTable = Record<string, Record<string, NativeRouteHandler>>;
+declare type NativeResponseFinalizer = (response: Response, request: Request) => Response | Promise<Response>;
+/**
+ * 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;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/router",
   "type": "module",
   "sideEffects": false,
-  "version": "0.74.47",
+  "version": "0.74.48",
   "description": "The Stacks framework router.",
   "author": "Chris Breuer",
   "contributors": [
@@ -67,27 +67,27 @@
   },
   "dependencies": {
     "@stacksjs/bun-router": "^0.1.18",
-    "@stacksjs/cache": "0.74.47",
-    "@stacksjs/collections": "0.74.47",
-    "@stacksjs/config": "0.74.47",
-    "@stacksjs/error-handling": "0.74.47",
-    "@stacksjs/logging": "0.74.47",
-    "@stacksjs/pagination": "0.74.47",
-    "@stacksjs/path": "0.74.47",
-    "@stacksjs/security": "0.74.47",
-    "@stacksjs/storage": "0.74.47",
+    "@stacksjs/cache": "0.74.48",
+    "@stacksjs/collections": "0.74.48",
+    "@stacksjs/config": "0.74.48",
+    "@stacksjs/error-handling": "0.74.48",
+    "@stacksjs/logging": "0.74.48",
+    "@stacksjs/pagination": "0.74.48",
+    "@stacksjs/path": "0.74.48",
+    "@stacksjs/security": "0.74.48",
+    "@stacksjs/storage": "0.74.48",
     "ts-rate-limiter": "^0.4.10"
   },
   "devDependencies": {
-    "@stacksjs/actions": "0.74.47",
-    "@stacksjs/types": "0.74.47",
+    "@stacksjs/actions": "0.74.48",
+    "@stacksjs/types": "0.74.48",
     "better-dx": "^0.2.24"
   },
   "peerDependencies": {
-    "@stacksjs/api": "0.74.47",
-    "@stacksjs/auth": "0.74.47",
-    "@stacksjs/database": "0.74.47",
-    "@stacksjs/validation": "0.74.47"
+    "@stacksjs/api": "0.74.48",
+    "@stacksjs/auth": "0.74.48",
+    "@stacksjs/database": "0.74.48",
+    "@stacksjs/validation": "0.74.48"
   },
   "peerDependenciesMeta": {
     "@stacksjs/api": {