@stacksjs/router 0.70.37 → 0.70.42

package/dist/action-paths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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/error-handler.d.ts

@@ -0,0 +1,62 @@
+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. 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>;
+/**
+ * Clear tracked queries (e.g., after successful response)
+ */
+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 }, 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

@@ -0,0 +1,35 @@
+export type { MiddlewareConfig, Request } from './middleware';
+// Export route registry types
+export type { RouteDefinition, RouteRegistry } from '../../../../../app/Routes';
+/**
+ * @stacksjs/router - Stacks Router
+ *
+ * A thin wrapper around bun-router that adds Stacks-specific
+ * action/controller resolution for string-based route handlers.
+ *
+ * All routing functionality comes directly from bun-router.
+ */
+// Re-export everything from bun-router (includes response factory)
+export * from '@stacksjs/bun-router';
+// Export Stacks-specific action resolver and URL helper
+export { clearMiddlewareCache, createStacksRouter, installMiddlewareHotReload, route, serve, serverResponse, url } 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 action-level rate limiting helpers
+export { rateLimit, rateLimitStatus, clearRateLimit } from './rate-limit';

package/dist/middleware.d.ts

@@ -0,0 +1,36 @@
+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);
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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-context.d.ts

@@ -0,0 +1,59 @@
+import type { EnhancedRequest } from '@stacksjs/bun-router';
+/**
+ * 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;
+/**
+ * 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
+ * Similar to Laravel's request() helper
+ *
+ * Methods:
+ * - bearerToken() - Get the bearer token from Authorization header
+ * - user() - Get the authenticated user (async)
+ * - userToken() - Get the current access token (async)
+ * - tokenCan(ability) - Check if token has an ability (async)
+ * - tokenCant(ability) - Check if token doesn't have an ability (async)
+ */
+export declare const request: Proxy;

package/dist/route-loader.d.ts

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

package/dist/stacks-router.d.ts

@@ -0,0 +1,113 @@
+import type { Server } from 'bun';
+import { Router } from '@stacksjs/bun-router';
+import type { ActionHandler, EnhancedRequest, Route, ServerOptions } from '@stacksjs/bun-router';
+/**
+ * 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;
+/**
+ * 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>>;
+// Create and export a default router instance
+export declare const route: unknown;
+declare interface StacksRouterConfig {
+  verbose?: boolean
+  apiPrefix?: string
+}
+declare interface GroupOptions {
+  prefix?: string
+  middleware?: string | string[]
+}
+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
+}
+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) => StacksRouterInstance
+  register: (routePath: string, options?: { prefix?: string, middleware?: string | string[] }) => Promise<StacksRouterInstance>
+  serve: (options?: ServerOptions) => Promise<Server<unknown>>
+  handleRequest: (req: Request) => Promise<Response>
+  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';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/router",
   "type": "module",
-  "version": "0.70.37",
+  "version": "0.70.42",
   "description": "The Stacks framework router.",
   "author": "Chris Breuer",
   "contributors": [
@@ -52,15 +52,15 @@
     "@stacksjs/bun-router": "^0.0.13"
   },
   "devDependencies": {
-    "@stacksjs/actions": "0.70.30",
-    "@stacksjs/config": "0.70.30",
+    "@stacksjs/actions": "^0.70.42",
+    "@stacksjs/config": "^0.70.42",
     "better-dx": "^0.2.12",
-    "@stacksjs/error-handling": "0.70.30",
-    "@stacksjs/logging": "0.70.30",
-    "@stacksjs/orm": "0.70.30",
-    "@stacksjs/path": "0.70.30",
-    "@stacksjs/storage": "0.70.30",
-    "@stacksjs/types": "0.70.30",
-    "@stacksjs/validation": "0.70.30"
+    "@stacksjs/error-handling": "^0.70.42",
+    "@stacksjs/logging": "^0.70.42",
+    "@stacksjs/orm": "^0.70.42",
+    "@stacksjs/path": "^0.70.42",
+    "@stacksjs/storage": "^0.70.42",
+    "@stacksjs/types": "^0.70.42",
+    "@stacksjs/validation": "^0.70.42"
   }
 }