@zedtech/zedkit-nest 0.0.0-stage → 0.0.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/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.0.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"
+  }
 }