@spinajs/http 2.0.486 → 2.0.487

package/README.md

@@ -1,11 +1,376 @@
-# `http`
+# @spinajs/http
 
-> TODO: description
+HTTP server & controller framework for SpinaJS, built on top of Express.
 
-## Usage
+- Class-based controllers with decorator routing (`@Get`, `@Post`, …)
+- Declarative route arguments (`@Query`, `@Body`, `@Param`, `@File`, …) with validation & hydration
+- Policies (authorization) and route middlewares
+- Pluggable controller discovery (`ControllerSource`) — filesystem scan, DI registry, or your own
+- Typed response classes (`Ok`, `Created`, `NotFound`, …) with content negotiation (JSON / HTML / XML)
+- Controller metadata cache with ahead-of-time CLI build (fast cold starts in docker)
+- Fail-fast startup: broken controllers throw typed exceptions instead of half-starting
 
+## Installation
+
+```bash
+npm install @spinajs/http
+```
+
+## Quick start
+
+```ts
+// src/controllers/UsersController.ts
+import { BaseController, BasePath, Get, Post, Ok, Created, NotFound, Query, Param, Body } from '@spinajs/http';
+
+@BasePath('users')
+export class UsersController extends BaseController {
+  /**
+   * GET /users?page=1
+   */
+  @Get('/')
+  public async list(@Query() page?: number) {
+    return new Ok([{ id: 1, name: 'John' }]);
+  }
+
+  /**
+   * GET /users/42
+   */
+  @Get(':id')
+  public async get(@Param() id: number) {
+    if (id !== 42) {
+      return new NotFound({ message: 'no such user' });
+    }
+    return new Ok({ id, name: 'John' });
+  }
+
+  /**
+   * POST /users  { "name": "Alice" }
+   */
+  @Post('/')
+  public async create(@Body() user: UserDto) {
+    return new Created(user);
+  }
+}
+```
+
+```ts
+// src/index.ts — application bootstrap
+import { DI } from '@spinajs/di';
+import { Configuration } from '@spinajs/configuration';
+import { fsService } from '@spinajs/fs';
+import { Controllers, HttpServer } from '@spinajs/http';
+
+await DI.resolve(Configuration);
+await DI.resolve(fsService);
+await DI.resolve(Controllers);   // discovers & mounts all controllers
+
+const server = await DI.resolve(HttpServer);
+server.start();                  // listens on http.port ( default 1337 )
+```
+
+Controllers are auto-discovered from directories configured at `system.dirs.controllers`.
+
+## Configuration
+
+All settings live under the `http` config key ( see `src/config/http.ts` for full defaults ):
+
+```ts
+// config/http.ts ( app override )
+import config from './config.js';
+
+export default {
+  system: {
+    dirs: {
+      // where controller classes are scanned from
+      controllers: ['/app/dist/controllers'],
+    },
+  },
+  http: {
+    port: 3000,
+
+    // global prefix added to EVERY controller route, eg. api/v1 -> /api/v1/users
+    controllers: {
+      route: { prefix: 'api/v1' },
+    },
+
+    // raw express middlewares, executed before routing
+    middlewares: [ /* helmet(), express.json(), ... */ ],
+
+    // signed cookie secret — ALWAYS override in production
+    cookie: {
+      secret: 'change-me',
+      options: { maxAge: 900000, httpOnly: true },
+    },
+
+    // static content: GET /_static/* served from Path
+    Static: [{ Route: '/_static', Path: '/app/public' }],
+
+    ssl: { key: '', cert: '' },
+  },
+};
+```
+
+## Routing
+
+Route decorators: `@Get`, `@Post`, `@Put`, `@Patch`, `@Del`, `@Head` — all take optional path and schema.
+
+Path resolution rules:
+
+| Declaration | Resulting path |
+| --- | --- |
+| `@BasePath('user')` + `@Get()` on `refresh()` | `/user/refresh` ( method name fallback ) |
+| `@BasePath('user')` + `@Get('/')` | `/user` |
+| `@BasePath('user')` + `@Get('grants/:id')` | `/user/grants/:id` |
+| no `@BasePath` | controller class name lowercased |
+| config `http.controllers.route.prefix = 'api/v1'` | `/api/v1/...` prepended to all of the above |
+
+## Route arguments
+
+Declared per-parameter with decorators; extracted, validated and hydrated before the action runs:
+
+```ts
+import {
+  Get, Post, Query, Body, Param, Header, Cookie, Form, File, CsvFile, JsonFile,
+  FromXml, RawBody, Req, Res, Ip, RequestId, UserAgent, Referer, FromDI, PKey, Uuid,
+} from '@spinajs/http';
+
+class ExamplesController extends BaseController {
+  @Get(':id')
+  public async byId(@PKey() id: number) { /* primary key helper */ }
+
+  @Get('search')
+  public async search(@Query() q: string, @Header('x-api-key') key: string) { }
+
+  @Post('upload')
+  public async upload(@File({ maxFileSize: 1024 * 1024 }) file: IUploadedFile) { }
+
+  @Post('import')
+  public async import(@CsvFile() rows: unknown[]) { }
+
+  @Post('webhook')
+  public async webhook(@RawBody() raw: Buffer, @Header('x-signature') sig: string) {
+    // raw = exact received bytes, for signature verification
+  }
+
+  @Get('whoami')
+  public async whoami(@Ip() ip: string, @UserAgent() ua: string, @RequestId() rid: string) { }
+
+  @Get('svc')
+  public async svc(@FromDI() service: SomeService) { /* resolved from DI per request */ }
+}
+```
+
+Selected argument decorators:
+
+| Decorator | Source |
+| --- | --- |
+| `@Query(schema?)` | query string parameter |
+| `@Body(options?)` | JSON body ( whole body or single field ) |
+| `@Param(schema?)` | URL parameter ( `:id` ) |
+| `@Header(name?)` | request header |
+| `@Cookie(secure?)` | cookie ( optionally signed ) |
+| `@Form` / `@FormField` | multipart form data |
+| `@File` / `@Files` | uploaded file(s), with size limits & upload middlewares |
+| `@CsvFile` / `@JsonFile` | uploaded file parsed to data |
+| `@FromXml` | XML request body, parsed |
+| `@RawBody` | raw request bytes ( webhook signatures ) |
+| `@Req` / `@Res` | express request / response |
+| `@Ip`, `@RequestId`, `@UserAgent`, `@Referer` | request metadata |
+| `@FromDI` | DI-resolved service |
+| `@PKey`, `@Uuid` | validated identifier helpers |
+| `@Model(Type)` | ORM model lookup ( with `@spinajs/orm-http` ) |
+
+Custom types passed to `@Body` / `@Query` are hydrated: class instances are constructed and (optionally) validated against JSON schema attached via `@Schema` from `@spinajs/validation`. Custom hydration via `@Hydrator(MyHydrator)` on the DTO class.
+
+## Responses
+
+Actions return response objects ( content negotiation JSON / HTML / XML happens automatically based on `Accept` header ):
+
+```ts
+import { Ok, Created, NoContent, BadRequestResponse, Unauthorized, ForbiddenResponse,
+         NotFound, Conflict, ValidationError, ServerError, Json, Xml,
+         FileResponse, ZipResponse, JsonFileResponse, TemplateResponse, Redirect } from '@spinajs/http';
+
+@Get('download')
+public async download() {
+  return new FileResponse({ path: '/data/report.pdf', filename: 'report.pdf' });
+}
+
+@Get('page')
+public async page() {
+  // renders pug template ( with @spinajs/templates-pug )
+  return new TemplateResponse('page.pug', { title: 'Hello' });
+}
+
+@Get('legacy')
+public async legacy() {
+  return new Redirect('/new-location');
+}
+```
+
+## Policies ( authorization )
+
+Policies gate route execution. When several policies are attached, **one success is enough** — this allows alternative access paths ( e.g. session cookie OR api token ):
+
+```ts
+import { BasePolicy, Policy, IRoute, IController } from '@spinajs/http';
+
+export class ApiKeyPolicy extends BasePolicy {
+  public isEnabled(_route: IRoute, _controller: IController): boolean {
+    return true;
+  }
+
+  public async execute(req: express.Request): Promise<void> {
+    if (req.headers['x-api-key'] !== process.env.API_KEY) {
+      throw new Forbidden('invalid api key');
+    }
+    // resolving = access granted
+  }
+}
+
+@BasePath('admin')
+@Policy(ApiKeyPolicy)               // controller-wide
+export class AdminController extends BaseController {
+  @Get()
+  @Policy(SessionPolicy)            // route-level, OR-ed with ApiKeyPolicy
+  public async dashboard() { ... }
+}
 ```
-const http = require('http');
 
-// TODO: DEMONSTRATE API
+Policies can also be referenced **by configuration key** — the key must resolve to a registered policy type name:
+
+```ts
+@Policy('rbac.session.policy')      // read from configuration at startup
+```
+
+A config key that does not resolve to a registered `BasePolicy` throws `RouteRegistrationException` at startup — a silently dropped policy would leave the route unprotected.
+
+## Route middlewares
+
+Run before / after actions and can inspect the produced response:
+
+```ts
+import { RouteMiddleware, Middleware } from '@spinajs/http';
+
+export class AuditMiddleware extends RouteMiddleware {
+  public isEnabled(route: IRoute, controller: IController): boolean { return true; }
+  public async onBefore(req, res, route, controller): Promise<void> { /* before action */ }
+  public async onResponse(response, route, controller): Promise<void> { /* inspect response object */ }
+  public async onAfter(req, res, route, controller): Promise<void> { /* after action */ }
+}
+
+@Middleware(AuditMiddleware)        // controller-wide or per-route
+export class OrdersController extends BaseController { ... }
 ```
+
+Server-level middlewares ( whole express stack, not per-route ) ship in `src/middlewares/`: `AccessLog`, `Cors`, `Compression`, `RequestId` ( w3c traceparent + `x-request-id` ), `ResponseTime`, `RealIp`, `ServerTiming`, `PerfRollup`, `SlowRequestWarning`, `NotFound`, `ErrorHandler`.
+
+## Controller discovery ( ControllerSource )
+
+Discovery is pluggable. Built-in sources:
+
+- `FilesystemControllerSource` — scans `system.dirs.controllers` directories
+- `DiRegistryControllerSource` — picks up types registered in DI **before** `Controllers` resolves:
+
+```ts
+// package bootstrapper — conditional controller registration
+@Injectable(Bootstrapper)
+export class MyPackageBootstrapper extends Bootstrapper {
+  public bootstrap(): void {
+    if (someFeatureFlag) {
+      DI.register(MyFeatureController).as(BaseController);
+    }
+  }
+}
+```
+
+Custom source — implement and register, the loader picks it up automatically:
+
+```ts
+import { ControllerSource, BaseController } from '@spinajs/http';
+import { ClassInfo, Injectable } from '@spinajs/di';
+
+@Injectable(ControllerSource)
+export class PluginManifestSource extends ControllerSource {
+  public async getControllers(): Promise<Array<ClassInfo<BaseController>>> {
+    // read your plugin manifest, return ClassInfo entries ( name, type, file )
+    return [];
+  }
+}
+```
+
+### Overriding a package controller
+
+Register the subclass as an override — only the subclass mounts:
+
+```ts
+DI.register(MyUserController).as(PackageUserController);
+```
+
+Subclassing a scanned controller **without** registering the override mounts BOTH and logs a warning ( express route order decides which answers ).
+
+### Dynamic registration at runtime
+
+```ts
+const controllers = await DI.resolve(Controllers);
+await controllers.add(LateBoundController);   // idempotent, mounts immediately
+```
+
+## Startup error handling
+
+Registration is fail-fast — the app refuses to start instead of silently skipping broken pieces:
+
+| Condition | Exception |
+| --- | --- |
+| controller instance could not be resolved | `ControllerRegistrationException` |
+| controller has descriptor but no router ( `super.resolve()` not called ) | `ControllerRegistrationException` |
+| route declared for a member that does not exist | `RouteRegistrationException` |
+| unknown route type ( broken decorator ) | `RouteRegistrationException` |
+| string policy config key not resolvable | `RouteRegistrationException` |
+
+Routes inherited from a base class declared in another file are fine — parameter names fall back to runtime extraction.
+
+## Controller cache & CLI
+
+Route parameter names and JSDoc documentation ( used by `@spinajs/http-swagger` ) are extracted from `.d.ts` files with the TypeScript compiler and cached under `__cache__/__controllers__` ( configurable via the `__fs_controller_cache__` fs provider ). Entries are keyed by source file content hash — changed files regenerate automatically.
+
+First app start pays the parsing cost. To avoid that ( e.g. docker images ), pre-build the cache at image build time:
+
+```bash
+# generate missing cache entries
+spinajs http:controllers:cache
+
+# force regeneration even if entries exist
+spinajs http:controllers:cache --rebuild
+```
+
+```dockerfile
+FROM node:22 AS build
+WORKDIR /app
+COPY . .
+RUN npm ci && npm run build
+# pre-build controllers cache AFTER tsc — cache keys are content hashes of compiled .d.ts
+RUN node node_modules/.bin/spinajs http:controllers:cache --rebuild
+
+FROM node:22-slim
+WORKDIR /app
+COPY --from=build /app .
+CMD ["node", "dist/index.js"]
+```
+
+The command exits non-zero when any controller fails to parse, failing the image build loudly.
+
+## Exceptions
+
+| Exception | Purpose |
+| --- | --- |
+| `ControllerRegistrationException` | controller-level startup failure |
+| `RouteRegistrationException` | route-level startup failure |
+| `EntityTooLargeException` | uploaded file exceeds limits ( maps to HTTP 413 ) |
+
+## Related packages
+
+- `@spinajs/http-swagger` — OpenAPI document generation from controller JSDoc
+- `@spinajs/orm-http` — `@Model()` route arg, ORM-aware responses
+- `@spinajs/rbac-http` — session / role policies
+- `@spinajs/templates-pug` — HTML rendering for `TemplateResponse` and error pages

package/lib/cjs/base-controller.d.ts

@@ -0,0 +1,35 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import Express from 'express';
+import { AsyncService, IContainer } from '@spinajs/di';
+import { Log } from '@spinajs/log';
+import { DataValidator } from '@spinajs/validation';
+import { Configuration } from '@spinajs/configuration';
+import { IController, IControllerDescriptor, IActionLocalStoregeContext } from './interfaces.js';
+export declare abstract class BaseController extends AsyncService implements IController {
+    /**
+     * Array index getter
+     */
+    [action: string]: any;
+    protected _router: Express.Router;
+    protected _container: IContainer;
+    protected _validator: DataValidator;
+    protected _log: Log;
+    protected _actionLocalStorage: AsyncLocalStorage<IActionLocalStoregeContext>;
+    protected _cfg: Configuration;
+    /**
+     * Express router with middleware stack
+     */
+    get Router(): Express.Router;
+    /**
+     * Controller descriptor
+     */
+    get Descriptor(): IControllerDescriptor;
+    /**
+     * Base path for all controller routes eg. my/custom/path/
+     *
+     * It can be defined via `@BasePath` decorator, defaults to controller name without `Controller` part.
+     */
+    get BasePath(): string;
+    resolve(): Promise<void>;
+}
+//# sourceMappingURL=base-controller.d.ts.map

package/lib/cjs/base-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-controller.d.ts","sourceRoot":"","sources":["../../src/base-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAyB,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAU,GAAG,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAOjG,8BAAsB,cAAe,SAAQ,YAAa,YAAW,WAAW;IAC9E;;OAEG;IACH,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC;IAEtB,SAAS,CAAC,OAAO,EAAG,OAAO,CAAC,MAAM,CAAC;IAGnC,SAAS,CAAC,UAAU,EAAG,UAAU,CAAC;IAGlC,SAAS,CAAC,UAAU,EAAG,aAAa,CAAC;IAGrC,SAAS,CAAC,IAAI,EAAG,GAAG,CAAC;IAGrB,SAAS,CAAC,mBAAmB,EAAG,iBAAiB,CAAC,0BAA0B,CAAC,CAAC;IAG9E,SAAS,CAAC,IAAI,EAAG,aAAa,CAAC;IAE/B;;OAEG;IACH,IAAW,MAAM,IAAI,OAAO,CAAC,MAAM,CAElC;IAED;;OAEG;IACH,IAAW,UAAU,IAAI,qBAAqB,CAE7C;IAED;;;;OAIG;IACH,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAEY,OAAO;CAsCrB"}

package/lib/cjs/base-controller.js

@@ -0,0 +1,100 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseController = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+const express_1 = __importDefault(require("express"));
+const di_1 = require("@spinajs/di");
+const log_1 = require("@spinajs/log");
+const validation_1 = require("@spinajs/validation");
+const configuration_1 = require("@spinajs/configuration");
+const decorators_js_1 = require("./decorators.js");
+const exceptions_js_1 = require("./exceptions.js");
+const response_js_1 = require("./response.js");
+const error_js_1 = require("./error.js");
+const route_builder_js_1 = require("./route-builder.js");
+class BaseController extends di_1.AsyncService {
+    /**
+     * Express router with middleware stack
+     */
+    get Router() {
+        return this._router;
+    }
+    /**
+     * Controller descriptor
+     */
+    get Descriptor() {
+        return Reflect.getMetadata(decorators_js_1.CONTROLLED_DESCRIPTOR_SYMBOL, this);
+    }
+    /**
+     * Base path for all controller routes eg. my/custom/path/
+     *
+     * It can be defined via `@BasePath` decorator, defaults to controller name without `Controller` part.
+     */
+    get BasePath() {
+        return this.Descriptor.BasePath ? this.Descriptor.BasePath : this.constructor.name.toLowerCase();
+    }
+    async resolve() {
+        await super.resolve();
+        if (!this.Descriptor) {
+            this._log.warn(`Controller ${this.constructor.name} does not have descriptor. If its abstract or base class ignore this message.`);
+            return;
+        }
+        this._router = express_1.default.Router();
+        for (const [, route] of this.Descriptor.Routes) {
+            // Fail fast: an unknown route type means the route decorator never set a
+            // valid express method — mounting the rest of the controller while
+            // silently dropping this route would hide the bug.
+            if (route.InternalType === 'unknown') {
+                throw new exceptions_js_1.RouteRegistrationException(`Unknown route type for ${this.constructor.name}::${String(route.Method)}`);
+            }
+            const path = (0, route_builder_js_1.buildRoutePath)(this.BasePath, route, this._cfg.get('http.controllers.route.prefix'));
+            const middlewares = await (0, route_builder_js_1.resolveRouteMiddlewares)(this.Descriptor, route, this._container);
+            const policies = await (0, route_builder_js_1.resolveRoutePolicies)(this.Descriptor, route, this._container, this._cfg, this._log, this.constructor.name, path);
+            const enabledMiddlewares = middlewares.filter((m) => m.isEnabled(route, this));
+            this._log.trace(`Registering route ${route.Type.toUpperCase()} ${this.constructor.name}::${String(route.Method)} at ${path}`);
+            const handlers = [
+                (0, route_builder_js_1.createPolicyGate)(policies, route, this, this._log),
+                ...enabledMiddlewares.map((m) => (0, route_builder_js_1.wrapMiddlewareAction)(m, m.onBefore.bind(m), route, this)),
+                (0, route_builder_js_1.createActionHandler)(this, route, enabledMiddlewares, this._actionLocalStorage),
+                ...enabledMiddlewares.map((m) => (0, route_builder_js_1.wrapMiddlewareAction)(m, m.onAfter.bind(m), route, this)),
+                (0, response_js_1.__handle_response__)(),
+                (0, error_js_1.__handle_error__)(),
+            ];
+            this._router[route.InternalType](path, handlers);
+        }
+    }
+}
+exports.BaseController = BaseController;
+__decorate([
+    (0, di_1.Autoinject)(di_1.Container),
+    __metadata("design:type", Object)
+], BaseController.prototype, "_container", void 0);
+__decorate([
+    (0, di_1.Autoinject)(),
+    __metadata("design:type", validation_1.DataValidator)
+], BaseController.prototype, "_validator", void 0);
+__decorate([
+    (0, log_1.Logger)('http'),
+    __metadata("design:type", log_1.Log)
+], BaseController.prototype, "_log", void 0);
+__decorate([
+    (0, di_1.Autoinject)(),
+    __metadata("design:type", node_async_hooks_1.AsyncLocalStorage)
+], BaseController.prototype, "_actionLocalStorage", void 0);
+__decorate([
+    (0, di_1.Autoinject)(configuration_1.Configuration),
+    __metadata("design:type", configuration_1.Configuration)
+], BaseController.prototype, "_cfg", void 0);
+//# sourceMappingURL=base-controller.js.map

package/lib/cjs/base-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-controller.js","sourceRoot":"","sources":["../../src/base-controller.ts"],"names":[],"mappings":"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"}

package/lib/cjs/cache.d.ts

@@ -1,7 +1,7 @@
 import ts from 'typescript';
 import { AsyncService, ClassInfo } from '@spinajs/di';
 import { fs as fFs, FileHasher } from '@spinajs/fs';
-import type { BaseController } from './controllers.js';
+import type { BaseController } from './base-controller.js';
 import { Log } from '@spinajs/log';
 export interface IParamDoc {
     name: string;
@@ -83,8 +83,18 @@ export declare class DefaultControllerCache extends AsyncService {
     protected CacheFS: fFs;
     protected Hasher: FileHasher;
     resolve(): Promise<void>;
-    /** Returns parameter-name map used for route argument binding. */
-    getCache(controller: ClassInfo<BaseController>): Promise<Record<string, string[]>>;
+    /**
+     * Returns parameter-name map used for route argument binding.
+     *
+     * Cache entries are keyed by source-file content hash, so a changed file
+     * naturally gets a fresh entry. `options.rebuild` forces regeneration and
+     * overwrite even when entries for the current hash already exist — used by
+     * the `http:controllers:cache` CLI command to refresh a pre-built cache
+     * (e.g. inside a docker image build).
+     */
+    getCache(controller: ClassInfo<BaseController>, options?: {
+        rebuild?: boolean;
+    }): Promise<Record<string, string[]>>;
     /** Whether `file` points at a real on-disk source we can parse. */
     private isResolvableSource;
     /**
@@ -160,4 +170,16 @@ export declare class DefaultControllerCache extends AsyncService {
      */
     private schemaFromNamedType;
 }
+/**
+ * Whether a ClassInfo `file` points at a real on-disk source. Bracketed
+ * sentinels (e.g. `<di>`, `<dynamic>`) are used by Controllers for entries
+ * that were never loaded from a file.
+ */
+export declare function isOnDiskSource(file: string | undefined): boolean;
+/**
+ * Pull parameter names from `Function.prototype.toString()` output. Modern V8
+ * preserves the literal signature so we can regex out `(a, b = 1, ...rest)`.
+ * Stripped of default values and TypeScript type annotations.
+ */
+export declare function parseFnParamNames(fn: Function): string[];
 //# sourceMappingURL=cache.d.ts.map

package/lib/cjs/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"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"}

package/lib/cjs/cache.js

@@ -13,6 +13,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultControllerCache = void 0;
+exports.isOnDiskSource = isOnDiskSource;
+exports.parseFnParamNames = parseFnParamNames;
 const typescript_1 = __importDefault(require("typescript"));
 const path_1 = require("path");
 const fs_1 = require("fs");
@@ -57,8 +59,16 @@ let DefaultControllerCache = class DefaultControllerCache extends di_1.AsyncServ
         await super.resolve();
         this.Log.info(`Controller cache dir is: ${this.CacheFS.resolvePath('')}`);
     }
-    /** Returns parameter-name map used for route argument binding. */
-    async getCache(controller) {
+    /**
+     * Returns parameter-name map used for route argument binding.
+     *
+     * Cache entries are keyed by source-file content hash, so a changed file
+     * naturally gets a fresh entry. `options.rebuild` forces regeneration and
+     * overwrite even when entries for the current hash already exist — used by
+     * the `http:controllers:cache` CLI command to refresh a pre-built cache
+     * (e.g. inside a docker image build).
+     */
+    async getCache(controller, options) {
         // Sentinel values like `<di>` are set by Controllers.resolve() / add() for
         // controllers registered through DI rather than a file scan. There's no
         // on-disk source to parse, so fall back to a runtime extraction of
@@ -69,8 +79,9 @@ let DefaultControllerCache = class DefaultControllerCache extends di_1.AsyncServ
         const file = (0, path_1.resolve)(controller.file.replace('.js', '.d.ts'));
         const hash = await this.Hasher.hash(file);
         const docHash = `doc_${hash}`;
-        const paramExists = await this.CacheFS.exists(hash);
-        const docExists = await this.CacheFS.exists(docHash);
+        const rebuild = options?.rebuild === true;
+        const paramExists = !rebuild && (await this.CacheFS.exists(hash));
+        const docExists = !rebuild && (await this.CacheFS.exists(docHash));
         if (!paramExists || !docExists) {
             this.Log.info(`Generating controller cache for ${controller.name}`);
             const { parameters, documentation } = this.extractAll(file, controller.name);
@@ -84,11 +95,7 @@ let DefaultControllerCache = class DefaultControllerCache extends di_1.AsyncServ
     }
     /** Whether `file` points at a real on-disk source we can parse. */
     isResolvableSource(file) {
-        if (!file)
-            return false;
-        // Bracketed sentinels (e.g. `<di>`, `<dynamic>`) are used by Controllers
-        // for entries that were never loaded from a file.
-        return !(file.startsWith('<') && file.endsWith('>'));
+        return isOnDiskSource(file);
     }
     /**
      * Fallback: derive route method parameter names by parsing each method's
@@ -543,6 +550,16 @@ __decorate([
 exports.DefaultControllerCache = DefaultControllerCache = __decorate([
     (0, di_1.Singleton)()
 ], DefaultControllerCache);
+/**
+ * Whether a ClassInfo `file` points at a real on-disk source. Bracketed
+ * sentinels (e.g. `<di>`, `<dynamic>`) are used by Controllers for entries
+ * that were never loaded from a file.
+ */
+function isOnDiskSource(file) {
+    if (!file)
+        return false;
+    return !(file.startsWith('<') && file.endsWith('>'));
+}
 /** Rightmost identifier of an entity name. */
 function entityNameRight(name) {
     return typescript_1.default.isIdentifier(name) ? name.text : name.right.text;