@stacksjs/router/dist/request-context.d.ts

The Stacks framework router.

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;