@zedtech/zedkit-nest 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zedtech-fr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @zedtech/zedkit-nest
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generic NestJS bootstrap factory. Original work by the same author.
+
+`createNestApp({ module, envSchema, docs, ... })` wires only standard
+pieces and returns the app ready to `listen()`:
+
+- Fastify platform (`platform-fastify`) with exact raw bodies
+  (`{ rawBody: true }`, proven by test) and a configurable body cap.
+- Validated env (`@nestjs/config` + a class-validator schema per app;
+  boot fails fast with one readable error).
+- Request-id JSON logs (`nestjs-pino`): honors `x-request-id`,
+  generates a UUID otherwise; one id across logs and error bodies.
+  `Authorization` and cookies are redacted from logs by default.
+- Strict global `ValidationPipe` (whitelist, forbid non-whitelisted,
+  transform; implicit conversion off — see below). Relax per app with
+  `validation: { whitelist: false, forbidNonWhitelisted: false }`.
+- One global error shape: `{ code, message, requestId }` (+ status).
+  4xx carries the safe message; 5xx never leaks internals. Every response
+  echoes `x-request-id` (interceptor on handled routes, filter otherwise).
+  Apps with domain errors pass their own filter via `exceptionFilter`.
+- Optional global throttler (`@nestjs/throttler`, default 100/min;
+  in-memory, single process — set `trustProxy` before running behind a
+  proxy or every client shares one bucket).
+- Generated OpenAPI (`@nestjs/swagger`), served as raw Fastify routes:
+  public by design, guards do not apply. Enabled by default except in
+  production (`NODE_ENV=production`) — opt back in explicitly if you
+  serve docs in prod. `docs.aliases` serves the same JSON from extra
+  absolute paths. Shutdown hooks.
+- Custom body parsers per content type (`bodyParsers`), installed
+  before Nest's defaults so an `application/json` entry replaces the
+  default parser; rawBody capture included.
+
+```ts
+import "reflect-metadata";
+import { createNestApp } from "@zedtech/zedkit-nest";
+
+const app = await createNestApp({
+  module: AppModule,
+  envSchema: AppEnv,
+  docs: { title: "My API", version: "v1" },
+});
+await app.listen(3000);
+```
+
+Framework pieces are peer dependencies (one copy per app — required for
+Nest DI). Install them alongside:
+
+```sh
+pnpm add @zedtech/zedkit-nest @fastify/static @nestjs/common @nestjs/config \
+  @nestjs/core @nestjs/platform-fastify @nestjs/swagger @nestjs/throttler \
+  class-transformer class-validator fastify nestjs-pino pino pino-http \
+  reflect-metadata
+```
+
+Rules (non-negotiable):
+
+- Zero product names or logic.
+- Numbers need explicit `@Type(() => Number)` (env ints, nested
+  DTOs): implicit conversion relies on decorator metadata, which
+  vitest can only emit via SWC — and the day one suite forgets SWC,
+  implicit conversion silently diverges from `tsc`.
+- Tests boot the factory with a product-free fixture domain and hit
+  it over HTTP (supertest, ephemeral ports): validation, exact raw
+  bytes, error shapes, throttling, request ids, docs, env failure.
+
+Vitest transforms via SWC (`swc.vite()`, options inferred from
+tsconfig): esbuild cannot emit decorator metadata, which would
+silently disable the global `ValidationPipe` in tests. Never remove
+it. Agent rules: [AGENTS.md](AGENTS.md)
+
+Find helpers by need in [CATALOG.md](CATALOG.md).
+
+## Install or copy?
+
+Install: this package is framework integration (DI, decorators, peer
+dependencies), not suitable for source-copying.
+
+## Verify
+
+```sh
+pnpm --filter @zedtech/zedkit-nest typecheck && pnpm --filter @zedtech/zedkit-nest lint && pnpm --filter @zedtech/zedkit-nest build && pnpm --filter @zedtech/zedkit-nest test
+```

package/dist/all-exceptions.filter.d.ts

@@ -0,0 +1,17 @@
+import { ArgumentsHost, ExceptionFilter } from "@nestjs/common";
+/**
+ * Global error shape for every Nest app from this bootstrap:
+ * `{ code, message, requestId }` with the matching HTTP status.
+ * 4xx responses carry the safe client-facing message; 5xx responses never
+ * leak internals (the full error goes to the logger only).
+ */
+export interface ErrorBody {
+    code: string;
+    message: string;
+    requestId: string;
+}
+export declare class AllExceptionsFilter implements ExceptionFilter {
+    private readonly logger;
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
+//# sourceMappingURL=all-exceptions.filter.d.ts.map

package/dist/all-exceptions.filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"all-exceptions.filter.d.ts","sourceRoot":"","sources":["../src/all-exceptions.filter.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EAEb,eAAe,EAGhB,MAAM,gBAAgB,CAAC;AAIxB;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAwCD,qBACa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAE/D,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;CAuCrD"}

package/dist/all-exceptions.filter.js

@@ -0,0 +1,97 @@
+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 AllExceptionsFilter_1;
+// Original work by the same author.
+import { Catch, HttpException, Logger, } from "@nestjs/common";
+import { REQUEST_ID_HEADER } from "./request-id.js";
+const STATUS_CODES = {
+    400: "invalid_input",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    409: "conflict",
+    413: "payload_too_large",
+    415: "unsupported_media_type",
+    429: "rate_limited",
+    500: "internal",
+    503: "unavailable",
+};
+/** Safe public messages for mapped 5xx; everything else stays "internal error". */
+const STATUS_5XX_MESSAGES = {
+    503: "service unavailable",
+};
+function fastifyBodyErrorStatus(exception) {
+    if (typeof exception !== "object" || exception === null)
+        return null;
+    if (!("code" in exception) || typeof exception.code !== "string")
+        return null;
+    if (exception.code === "FST_ERR_CTP_BODY_TOO_LARGE")
+        return 413;
+    if (exception.code === "FST_ERR_CTP_INVALID_MEDIA_TYPE")
+        return 415;
+    if (exception.code.startsWith("FST_ERR_CTP_"))
+        return 400;
+    return null;
+}
+function httpMessage(exception) {
+    const response = exception.getResponse();
+    if (typeof response === "string")
+        return response;
+    if (typeof response === "object" && response !== null && "message" in response) {
+        const message = response.message;
+        if (typeof message === "string")
+            return message;
+        if (Array.isArray(message))
+            return message.map(String).join("; ");
+    }
+    return exception.message;
+}
+let AllExceptionsFilter = AllExceptionsFilter_1 = class AllExceptionsFilter {
+    logger = new Logger(AllExceptionsFilter_1.name);
+    catch(exception, host) {
+        const ctx = host.switchToHttp();
+        const req = ctx.getRequest();
+        const reply = ctx.getResponse();
+        const requestId = typeof req.id === "string" ? req.id : "unknown";
+        let status;
+        let message;
+        if (exception instanceof HttpException) {
+            status = exception.getStatus();
+            message =
+                status >= 500
+                    ? (STATUS_5XX_MESSAGES[status] ?? "internal error")
+                    : httpMessage(exception);
+        }
+        else {
+            const bodyStatus = fastifyBodyErrorStatus(exception);
+            status = bodyStatus ?? 500;
+            message =
+                status === 413
+                    ? "body exceeds the configured limit"
+                    : status === 415
+                        ? "unsupported media type"
+                        : status === 400
+                            ? "invalid request body"
+                            : "internal error";
+        }
+        if (status >= 500) {
+            this.logger.error(`Unhandled error on ${req.method} ${req.url}: ${String(exception)}`, exception instanceof Error ? exception.stack : undefined);
+        }
+        // A streaming handler that throws after the first flush already sent
+        // the reply: sending again would raise inside the filter itself.
+        if (reply.sent)
+            return;
+        const code = STATUS_CODES[status] ?? `http_${status}`;
+        reply.header(REQUEST_ID_HEADER, requestId);
+        reply.status(status).send({ code, message, requestId });
+    }
+};
+AllExceptionsFilter = AllExceptionsFilter_1 = __decorate([
+    Catch()
+], AllExceptionsFilter);
+export { AllExceptionsFilter };
+//# sourceMappingURL=all-exceptions.filter.js.map

package/dist/all-exceptions.filter.js.map

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

package/dist/factory.d.ts

@@ -0,0 +1,121 @@
+import "reflect-metadata";
+import { type INestApplication, type Type } from "@nestjs/common";
+import { type NestFastifyApplication } from "@nestjs/platform-fastify";
+import { type ThrottlerStorage } from "@nestjs/throttler";
+import type { FastifyBodyParser, FastifyServerOptions } from "fastify";
+import type { DestinationStream } from "pino";
+/** Whatever `app.enableCors()` accepts (`true` allows any origin). */
+type CorsSetting = Parameters<INestApplication["enableCors"]>[0];
+export interface ThrottleOptions {
+    ttlMs: number;
+    limit: number;
+    /**
+     * Custom hit counter (e.g. shared across replicas). Defaults to the
+     * in-memory store: correct for a single process only.
+     */
+    storage?: ThrottlerStorage | undefined;
+}
+export interface DocsOptions {
+    title: string;
+    version: string;
+    description?: string | undefined;
+    /** Serve path for the UI and `<path>-json`. Defaults to `docs`. */
+    path?: string | undefined;
+    /**
+     * Extra absolute paths serving the same JSON document (stable
+     * contract URLs beyond the swagger-default `<path>-json`). Served
+     * raw (no guards), like the default JSON route.
+     */
+    aliases?: string[] | undefined;
+}
+/**
+ * Request-logging options. The logger is process-wide: when several apps
+ * boot in one process (tests), the first app's logger options win.
+ */
+export interface LoggerOptions {
+    level?: string | undefined;
+    /**
+     * pino redact paths. Defaults to the Authorization header and cookies:
+     * request logs must never carry credentials.
+     */
+    redact?: string[] | undefined;
+    /** Log destination (pino passthrough). Defaults to stdout. */
+    stream?: DestinationStream | undefined;
+}
+export interface ValidationOptions {
+    /** Strip properties with no decorators. Defaults to true. */
+    whitelist?: boolean | undefined;
+    /** Reject (400) unknown properties instead of stripping. Defaults to true. */
+    forbidNonWhitelisted?: boolean | undefined;
+}
+export interface NestBootstrapOptions {
+    /** Root application module of the product app. */
+    module: Type<object>;
+    /**
+     * class-validator decorated env schema. Validated at boot; boot fails
+     * fast with a readable error when a declared variable is invalid.
+     * Numbers need an explicit `@Type(() => Number)`: implicit conversion
+     * relies on decorator metadata, which vitest/esbuild cannot emit.
+     */
+    envSchema?: Type<object> | undefined;
+    /**
+     * `.env` file lookup (ConfigModule passthrough). Defaults to `[".env"]`
+     * (plus `process.env`, which always wins). Missing files are ignored.
+     */
+    envFilePath?: string[] | undefined;
+    /**
+     * Generated OpenAPI. Enabled by default except when
+     * `NODE_ENV=production` (a public endpoint inventory is a gift to
+     * attackers — opt back in explicitly if you serve docs in prod). Pass
+     * `false` for apps without HTTP (workers).
+     */
+    docs?: DocsOptions | false | undefined;
+    /**
+     * Global IP-based coarse guard. Enabled by default at 100 req/min;
+     * product apps add their own credential-scoped limits on top.
+     */
+    throttle?: ThrottleOptions | false | undefined;
+    /** Populate `request.rawBody` with the exact bytes. Defaults to true. */
+    rawBody?: boolean | undefined;
+    /** Fastify body cap in bytes. Defaults to 1 MiB. */
+    bodyLimit?: number | undefined;
+    /**
+     * Trust proxy headers (Fastify passthrough). Set this before running
+     * behind a proxy or every client shares one throttle bucket.
+     */
+    trustProxy?: FastifyServerOptions["trustProxy"] | undefined;
+    /**
+     * `true` allows any origin; pass an object to restrict it. Note: a
+     * plain string origin is echoed unconditionally — use an array or
+     * function to actually restrict.
+     */
+    cors?: CorsSetting | undefined;
+    logger?: LoggerOptions | undefined;
+    /** Global ValidationPipe shape. Defaults to strict (strip + forbid). */
+    validation?: ValidationOptions | undefined;
+    /**
+     * Global error filter. Defaults to AllExceptionsFilter; apps with
+     * domain errors pass their own filter class here.
+     */
+    exceptionFilter?: Type<object> | undefined;
+    /**
+     * Custom body parsers by content type, installed through the
+     * adapter's standard `useBodyParser` (rawBody capture included)
+     * before Nest registers its defaults — so a custom
+     * `application/json` parser replaces the default instead of
+     * conflicting with it. Receives the raw buffer; `done(null, value)`
+     * sets `@Body()`, `done(error)` with `statusCode` rejects.
+     */
+    bodyParsers?: Record<string, FastifyBodyParser<Buffer>> | undefined;
+}
+/**
+ * Generic Nest bootstrap shared by every app. Wires only standard pieces:
+ * Fastify platform, validated env (`@nestjs/config`), request-id JSON logs
+ * (`nestjs-pino`), strict global `ValidationPipe`, a global error-shape
+ * filter, an optional global throttler, generated OpenAPI, and graceful
+ * shutdown hooks. Returns the app ready to `listen()`; tests use it with
+ * supertest without ever touching product code.
+ */
+export declare function createNestApp(options: NestBootstrapOptions): Promise<NestFastifyApplication>;
+export {};
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

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

package/dist/factory.js

@@ -0,0 +1,176 @@
+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;
+};
+// Original work by the same author. Design notes:
+// - `envFilePath` option (default `[".env"]`) instead of a hardcoded
+//   monorepo-relative lookup.
+// - `trustProxy` passthrough so the documented proxy guidance works.
+import "reflect-metadata";
+import { Module, ValidationPipe, } from "@nestjs/common";
+import { ConfigModule } from "@nestjs/config";
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE, NestFactory } from "@nestjs/core";
+import { FastifyAdapter, } from "@nestjs/platform-fastify";
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import { ThrottlerGuard, ThrottlerModule, } from "@nestjs/throttler";
+import { Logger as PinoLogger, LoggerModule } from "nestjs-pino";
+import { randomUUID } from "node:crypto";
+import { AllExceptionsFilter } from "./all-exceptions.filter.js";
+import { REQUEST_ID_HEADER } from "./request-id.js";
+import { RequestIdInterceptor } from "./request-id.interceptor.js";
+import { validateEnv } from "./validate-env.js";
+const DEFAULT_THROTTLE = { ttlMs: 60_000, limit: 100 };
+const DEFAULT_LOG_REDACT = ["req.headers.authorization", "req.headers.cookie"];
+const DEFAULT_BODY_LIMIT = 1024 * 1024;
+const DEFAULT_DOCS = {
+    title: "API",
+    version: "0.0.0",
+    path: "docs",
+};
+function requestIdOf(req) {
+    const header = req.headers[REQUEST_ID_HEADER];
+    // Node joins repeated HTTP/1 headers with ", "; HTTP/2 may deliver an
+    // array. Either way the first value wins.
+    const first = Array.isArray(header)
+        ? header[0]?.trim()
+        : header?.split(",")[0]?.trim();
+    if (first)
+        return first;
+    return randomUUID();
+}
+/**
+ * Fastify assigns `request.id` (via its own `genReqId`) before pino-http
+ * runs, so pino reuses it: logs, error bodies, and the wire id are one
+ * value. Generating a second UUID here would split them apart.
+ */
+function pinoReqId(req) {
+    const existing = req.id;
+    if (typeof existing === "string" && existing.length > 0)
+        return existing;
+    return requestIdOf(req);
+}
+/**
+ * Generic Nest bootstrap shared by every app. Wires only standard pieces:
+ * Fastify platform, validated env (`@nestjs/config`), request-id JSON logs
+ * (`nestjs-pino`), strict global `ValidationPipe`, a global error-shape
+ * filter, an optional global throttler, generated OpenAPI, and graceful
+ * shutdown hooks. Returns the app ready to `listen()`; tests use it with
+ * supertest without ever touching product code.
+ */
+export async function createNestApp(options) {
+    const throttle = options.throttle === undefined ? DEFAULT_THROTTLE : options.throttle;
+    const schema = options.envSchema;
+    let BootstrapRootModule = class BootstrapRootModule {
+    };
+    BootstrapRootModule = __decorate([
+        Module({
+            imports: [
+                ConfigModule.forRoot({
+                    isGlobal: true,
+                    cache: true,
+                    envFilePath: options.envFilePath ?? [".env"],
+                    ...(schema
+                        ? { validate: (config) => validateEnv(schema, config) }
+                        : {}),
+                }),
+                LoggerModule.forRoot({
+                    // nestjs-pino takes the destination as a tuple, not an option key.
+                    pinoHttp: options.logger?.stream === undefined
+                        ? {
+                            level: options.logger?.level ?? "info",
+                            genReqId: (req) => pinoReqId(req),
+                            redact: options.logger?.redact ?? DEFAULT_LOG_REDACT,
+                        }
+                        : [
+                            {
+                                level: options.logger.level ?? "info",
+                                genReqId: (req) => pinoReqId(req),
+                                redact: options.logger.redact ?? DEFAULT_LOG_REDACT,
+                            },
+                            options.logger.stream,
+                        ],
+                }),
+                ...(throttle
+                    ? [
+                        ThrottlerModule.forRoot(throttle.storage
+                            ? {
+                                storage: throttle.storage,
+                                throttlers: [{ ttl: throttle.ttlMs, limit: throttle.limit }],
+                            }
+                            : [{ ttl: throttle.ttlMs, limit: throttle.limit }]),
+                    ]
+                    : []),
+                options.module,
+            ],
+            providers: [
+                {
+                    provide: APP_PIPE,
+                    useValue: new ValidationPipe({
+                        whitelist: options.validation?.whitelist ?? true,
+                        forbidNonWhitelisted: options.validation?.forbidNonWhitelisted ?? true,
+                        transform: true,
+                    }),
+                },
+                { provide: APP_FILTER, useClass: options.exceptionFilter ?? AllExceptionsFilter },
+                { provide: APP_INTERCEPTOR, useClass: RequestIdInterceptor },
+                ...(throttle ? [{ provide: APP_GUARD, useClass: ThrottlerGuard }] : []),
+            ],
+        })
+    ], BootstrapRootModule);
+    const bodyLimit = options.bodyLimit ?? DEFAULT_BODY_LIMIT;
+    const adapter = new FastifyAdapter({
+        bodyLimit,
+        genReqId: (req) => requestIdOf(req),
+        // exactOptionalPropertyTypes: only pass the key when set.
+        ...(options.trustProxy === undefined ? {} : { trustProxy: options.trustProxy }),
+    });
+    for (const [contentType, parser] of Object.entries(options.bodyParsers ?? {})) {
+        adapter.useBodyParser(contentType, options.rawBody ?? true, { bodyLimit }, parser);
+    }
+    const app = await NestFactory.create(BootstrapRootModule, adapter, {
+        rawBody: options.rawBody ?? true,
+        bufferLogs: true,
+        // Surface boot errors (e.g. invalid env) as rejections instead of
+        // `process.abort()`: callers and tests can handle them, and an
+        // unhandled rejection still crashes with the error printed.
+        abortOnError: false,
+    });
+    app.useLogger(app.get(PinoLogger));
+    app.enableShutdownHooks();
+    if (options.cors) {
+        app.enableCors(options.cors === true ? undefined : options.cors);
+    }
+    const docs = options.docs === undefined
+        ? process.env.NODE_ENV === "production"
+            ? false
+            : DEFAULT_DOCS
+        : options.docs;
+    if (docs) {
+        const builder = new DocumentBuilder()
+            .setTitle(docs.title)
+            .setVersion(docs.version);
+        if (docs.description) {
+            builder.setDescription(docs.description);
+        }
+        // Tolerate "docs/" or "/docs": the JSON route is derived by suffix.
+        // Manual trim (no regex): the path is deployer-controlled input.
+        const rawDocsPath = docs.path ?? "docs";
+        let docsStart = 0;
+        let docsEnd = rawDocsPath.length;
+        while (docsStart < docsEnd && rawDocsPath[docsStart] === "/")
+            docsStart += 1;
+        while (docsEnd > docsStart && rawDocsPath[docsEnd - 1] === "/")
+            docsEnd -= 1;
+        const docsPath = rawDocsPath.slice(docsStart, docsEnd) || "docs";
+        const document = SwaggerModule.createDocument(app, builder.build());
+        SwaggerModule.setup(docsPath, app, document);
+        const fastify = app.getHttpAdapter().getInstance();
+        for (const alias of docs.aliases ?? []) {
+            fastify.get(alias, (_req, reply) => reply.send(document));
+        }
+    }
+    return app;
+}
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { AllExceptionsFilter, type ErrorBody } from "./all-exceptions.filter.js";
+export { createNestApp, type DocsOptions, type LoggerOptions, type NestBootstrapOptions, type ThrottleOptions, type ValidationOptions, } from "./factory.js";
+export { REQUEST_ID_HEADER } from "./request-id.js";
+export { RequestIdInterceptor } from "./request-id.interceptor.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EACL,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { AllExceptionsFilter } from "./all-exceptions.filter.js";
+export { createNestApp, } from "./factory.js";
+export { REQUEST_ID_HEADER } from "./request-id.js";
+export { RequestIdInterceptor } from "./request-id.interceptor.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAkB,MAAM,4BAA4B,CAAC;AACjF,OAAO,EACL,aAAa,GAMd,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/request-id.d.ts

@@ -0,0 +1,3 @@
+/** Incoming request-id header honored by the logger and error bodies. */
+export declare const REQUEST_ID_HEADER = "x-request-id";
+//# sourceMappingURL=request-id.d.ts.map

package/dist/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../src/request-id.ts"],"names":[],"mappings":"AACA,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,iBAAiB,CAAC"}

package/dist/request-id.interceptor.d.ts

@@ -0,0 +1,11 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from "@nestjs/common";
+/**
+ * Echoes the request id as a response header on every handled route.
+ * Set before the handler runs, so it survives handler errors; errors
+ * thrown earlier (guards, parsers, unknown routes) get the same
+ * header from the error filter instead.
+ */
+export declare class RequestIdInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): ReturnType<CallHandler["handle"]>;
+}
+//# sourceMappingURL=request-id.interceptor.d.ts.map

package/dist/request-id.interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.interceptor.d.ts","sourceRoot":"","sources":["../src/request-id.interceptor.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI3G;;;;;GAKG;AACH,qBACa,oBAAqB,YAAW,eAAe;IAC1D,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;CAS3F"}

package/dist/request-id.interceptor.js

@@ -0,0 +1,31 @@
+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;
+};
+// Original work by the same author.
+import { Injectable } from "@nestjs/common";
+import { REQUEST_ID_HEADER } from "./request-id.js";
+/**
+ * Echoes the request id as a response header on every handled route.
+ * Set before the handler runs, so it survives handler errors; errors
+ * thrown earlier (guards, parsers, unknown routes) get the same
+ * header from the error filter instead.
+ */
+let RequestIdInterceptor = class RequestIdInterceptor {
+    intercept(context, next) {
+        const ctx = context.switchToHttp();
+        const req = ctx.getRequest();
+        const reply = ctx.getResponse();
+        if (typeof req.id === "string" && req.id.length > 0) {
+            reply.header(REQUEST_ID_HEADER, req.id);
+        }
+        return next.handle();
+    }
+};
+RequestIdInterceptor = __decorate([
+    Injectable()
+], RequestIdInterceptor);
+export { RequestIdInterceptor };
+//# sourceMappingURL=request-id.interceptor.js.map

package/dist/request-id.interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.interceptor.js","sourceRoot":"","sources":["../src/request-id.interceptor.ts"],"names":[],"mappings":";;;;;;AAAA,oCAAoC;AACpC,OAAO,EAAE,UAAU,EAAiE,MAAM,gBAAgB,CAAC;AAE3G,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;GAKG;AAEI,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IAC/B,SAAS,CAAC,OAAyB,EAAE,IAAiB;QACpD,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,GAAG,CAAC,UAAU,EAAkB,CAAC;QAC7C,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAgB,CAAC;QAC9C,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,GAAG,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpD,KAAK,CAAC,MAAM,CAAC,iBAAiB,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;IACvB,CAAC;CACF,CAAA;AAVY,oBAAoB;IADhC,UAAU,EAAE;GACA,oBAAoB,CAUhC"}

package/dist/request-id.js

@@ -0,0 +1,4 @@
+// Original work by the same author.
+/** Incoming request-id header honored by the logger and error bodies. */
+export const REQUEST_ID_HEADER = "x-request-id";
+//# sourceMappingURL=request-id.js.map

package/dist/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.js","sourceRoot":"","sources":["../src/request-id.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC"}

package/dist/validate-env.d.ts

@@ -0,0 +1,11 @@
+import type { Type } from "@nestjs/common";
+/**
+ * `ConfigModule` validate hook (documented Nest recipe): instantiate the
+ * schema class so field defaults and `@Type()` coercions apply, then fail
+ * fast with one readable error when a declared variable is invalid.
+ * Undeclared variables pass through untouched, so unrelated env (PATH,
+ * CI flags, other tools) never breaks boot. Returns the instance, so
+ * `ConfigService` serves defaults and coerced numbers.
+ */
+export declare function validateEnv(schema: Type<object>, config: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=validate-env.d.ts.map

package/dist/validate-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-env.d.ts","sourceRoot":"","sources":["../src/validate-env.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAkB3C;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/dist/validate-env.js

@@ -0,0 +1,31 @@
+import { plainToInstance } from "class-transformer";
+import { validateSync } from "class-validator";
+function flattenErrors(errors, prefix = "") {
+    return errors.flatMap((error) => {
+        const path = prefix ? `${prefix}.${error.property}` : error.property;
+        const reasons = Object.values(error.constraints ?? {}).join(", ");
+        const self = reasons ? [`${path}: ${reasons}`] : [];
+        // Unreachable via flat process env today (nested objects never arrive
+        // from env files), but the walk keeps the message readable if a nested
+        // schema ever validates nested input.
+        const children = error.children?.length ? flattenErrors(error.children, path) : [];
+        return [...self, ...children];
+    });
+}
+/**
+ * `ConfigModule` validate hook (documented Nest recipe): instantiate the
+ * schema class so field defaults and `@Type()` coercions apply, then fail
+ * fast with one readable error when a declared variable is invalid.
+ * Undeclared variables pass through untouched, so unrelated env (PATH,
+ * CI flags, other tools) never breaks boot. Returns the instance, so
+ * `ConfigService` serves defaults and coerced numbers.
+ */
+export function validateEnv(schema, config) {
+    const instance = plainToInstance(schema, config);
+    const errors = validateSync(instance);
+    if (errors.length > 0) {
+        throw new Error(`Invalid environment: ${flattenErrors(errors).join("; ")}`);
+    }
+    return instance;
+}
+//# sourceMappingURL=validate-env.js.map

package/dist/validate-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-env.js","sourceRoot":"","sources":["../src/validate-env.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AAErE,SAAS,aAAa,CAAC,MAAyB,EAAE,MAAM,GAAG,EAAE;IAC3D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;QACrE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,sEAAsE;QACtE,uEAAuE;QACvE,sCAAsC;QACtC,MAAM,QAAQ,GACZ,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,MAAoB,EACpB,MAA+B;IAE/B,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACtC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,wBAAwB,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAA8C,CAAC;AACxD,CAAC"}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@zedtech/zedkit-nest",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Generic NestJS bootstrap factory: platform, config, logging, validation, errors, throttling, docs, shutdown. Original work by the same author.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zedtech-fr/zedkit",
+    "directory": "packages/nest"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@fastify/static": "^10.1.7",
+    "@nestjs/common": "^12.2.0",
+    "@nestjs/config": "^12.0.1",
+    "@nestjs/core": "^12.2.0",
+    "@nestjs/platform-fastify": "^12.2.0",
+    "@nestjs/swagger": "^12.0.4",
+    "@nestjs/throttler": "^6.7.1",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "fastify": "^5.12.7",
+    "nestjs-pino": "^5.3.1",
+    "pino": "^10.4.0",
+    "pino-http": "^11.0.0",
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@fastify/static": "10.1.7",
+    "@nestjs/common": "12.2.0",
+    "@nestjs/config": "12.0.1",
+    "@nestjs/core": "12.2.0",
+    "@nestjs/platform-fastify": "12.2.0",
+    "@nestjs/swagger": "12.0.4",
+    "@nestjs/throttler": "6.7.1",
+    "@swc/core": "1.16.20",
+    "@types/node": "22.20.5",
+    "@types/supertest": "7.2.1",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.15.1",
+    "fastify": "5.12.7",
+    "nestjs-pino": "5.3.1",
+    "pino": "10.4.0",
+    "pino-http": "11.0.0",
+    "reflect-metadata": "0.2.2",
+    "supertest": "7.3.1",
+    "typescript": "5.9.3",
+    "unplugin-swc": "2.0.0",
+    "vitest": "2.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src tests"
+  }
 }