@biorate/nestjs-tools 2.5.0 → 2.6.0

package/README.md

@@ -8,7 +8,7 @@ Production‑grade middleware, guards, interceptors, filters, decorators, and HT
 - **Response time** — Prometheus histogram + `x-response-time` header.
 - **HTTP proxy** — Prometheus‑instrumented `http-proxy-middleware` wrapper.
 - **Tracing** — OpenTelemetry span attributes for incoming requests.
-- **Exception filter** — structured JSON error responses for HTTP, WS, and RPC.
+- **Exception filter** — structured JSON error responses for HTTP and WebSocket transports (RPC is unsupported).
 - **Auth** — `@AuthBasic()` decorator + `AuthGuardProvider`.
 - **Roles** — `@Roles()` decorator + `RolesGuardProvider`.
 - **CORS** — config‑driven origin validation.
@@ -25,14 +25,14 @@ Peer dependencies: `@nestjs/common`, `@nestjs/core`, `@nestjs/swagger`, `class-v
 
 ## Quick start
 
+`main.ts`:
+
 ```ts
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
 import {
   AllExceptionsFilter,
-  BootstrapProvider,
-  RequestCountMiddleware,
-  ResponseTimeMiddleware,
+  RoutesInterceptor,
   TracingInterceptor,
 } from '@biorate/nestjs-tools';
 
@@ -40,17 +40,38 @@ async function bootstrap() {
   const app = await NestFactory.create(AppModule, { bufferLogs: true });
 
   app.useGlobalFilters(new AllExceptionsFilter());
-  app.useGlobalInterceptors(new TracingInterceptor());
-
-  // Middleware
-  app.use(BootstrapProvider.create());
-  app.use(RequestCountMiddleware.create());
-  app.use(ResponseTimeMiddleware.create());
+  app.useGlobalInterceptors(new RoutesInterceptor(), new TracingInterceptor());
 
   await app.listen(3000);
 }
+
+bootstrap();
+```
+
+`app.module.ts`:
+
+```ts
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import {
+  RequestCountMiddleware,
+  ResponseTimeMiddleware,
+} from '@biorate/nestjs-tools';
+
+@Module({ imports: [...] })
+export class AppModule implements NestModule {
+  public configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(RequestCountMiddleware, ResponseTimeMiddleware)
+      .forRoutes('*');
+  }
+}
 ```
 
+> Middleware and interceptor classes use `@inject(Types.Config)` from the global
+> `@biorate/inversion` container — bootstrap the app via the `@biorate/launcher`
+> lifecycle with `Types.Config` bound, otherwise requests will fail with
+> `InversionInjectionIsUndefinedError`.
+
 ## Middlewares
 
 ### `RequestCountMiddleware`
@@ -59,8 +80,6 @@ Prometheus counter `http_server_requests_seconds_count` with labels `method`, `u
 
 ```ts
 consumer.apply(RequestCountMiddleware).forRoutes('*');
-// or via BootstrapProvider
-app.use(RequestCountMiddleware.create());
 ```
 
 Uses `RoutesInterceptor` to resolve the actual route path (e.g. `/api/users/:id` instead of `/api/users/123`).
@@ -72,7 +91,7 @@ Config option: `app.middleware.RequestCountMiddleware.log-base-url` (boolean, de
 Prometheus histogram `http_server_requests_seconds` + `x-response-time` header.
 
 ```ts
-app.use(ResponseTimeMiddleware.create());
+consumer.apply(ResponseTimeMiddleware).forRoutes('*');
 ```
 
 Config options:
@@ -125,7 +144,7 @@ Catches all exceptions and returns a structured JSON response:
 }
 ```
 
-Supports HTTP, WebSocket, and RPC transport types. Maps `meta.status` from `@biorate/errors` to HTTP status codes.
+Supports HTTP and WebSocket transports; RPC is unsupported and throws `UnsupportedProtocolError`. Maps `meta.status` from `@biorate/errors` to HTTP status codes.
 
 ```ts
 app.useGlobalFilters(new AllExceptionsFilter());
@@ -181,7 +200,7 @@ Granular control over which span attributes are written:
 
 Resolves the full route path (controller + handler) and stores it in a `WeakMap<Request, { path }>` for use by `RequestCountMiddleware` and `ResponseTimeMiddleware`.
 
-Applied automatically when using the count/time middlewares.
+Not applied automatically: when using the count/time middlewares, register it globally via `app.useGlobalInterceptors(new RoutesInterceptor())` — otherwise they won't see the resolved route path and metrics fall back to `/`.
 
 ## Providers (Guards)
 
@@ -233,14 +252,6 @@ export class CustomRolesGuard extends RolesGuardProvider {
 }
 ```
 
-### `BootstrapProvider`
-
-Convenience middleware that initializes the `@biorate/inversion` container lifecycle:
-
-```ts
-app.use(BootstrapProvider.create());
-```
-
 ## Decorators
 
 | Decorator      | Composition                                       |
@@ -260,15 +271,18 @@ In non‑debug environments, validates the origin against `ALLOWED_ORIGIN` confi
 
 ## HTTP controllers
 
+> The `MetricsController`, `ProbeController`, and `LocalesController` in `src/http/controllers` are marked `@deprecated`. Their hexagonal replacements live in `src/app/infrastructure/controllers/` and are **not** exported individually at the package top level — `src/app/infrastructure/index.ts` re-exports them only as the `controllers` namespace (`export * as controllers from './controllers'`), so reach them as `import { controllers } from '@biorate/nestjs-tools'` (e.g. `controllers.MetricsController`).
+
 ### `MetricsController`
 
 Exposes `GET /metrics` with Prometheus metrics from the shared registry.
 
 ### `ProbeController`
 
-| Route        | Purpose            |
-| ------------ | ------------------ |
-| `GET /probe` | Liveness/readiness |
+| Route                  | Purpose         |
+| ---------------------- | --------------- |
+| `GET /probe/readiness` | Readiness probe |
+| `GET /probe/healthz`   | Healthz probe   |
 
 ### `LocalesController`
 
@@ -296,14 +310,12 @@ src/app/
 └──────────┬───────────────────────────────────────────┘
            │
 ┌──────────▼───────────────────────────────────────────┐
-│ BootstrapProvider (DI lifecycle init)                 │
+│ RoutesInterceptor (path resolution)                   │
 ├──────────────────────────────────────────────────────┤
 │ RequestCountMiddleware (counter)                      │
 ├──────────────────────────────────────────────────────┤
 │ ResponseTimeMiddleware (histogram + header)           │
 ├──────────────────────────────────────────────────────┤
-│ RoutesInterceptor (path resolution)                   │
-├──────────────────────────────────────────────────────┤
 │ TracingInterceptor (OpenTelemetry span attrs)         │
 ├──────────────────────────────────────────────────────┤
 │ AllExceptionsFilter (structured error JSON)           │

package/dist/cjs/src/filters/all-exception-filter.js

@@ -12,46 +12,44 @@ const common_1 = require("@nestjs/common");
 const errors_1 = require("../errors");
 let AllExceptionsFilter = class AllExceptionsFilter {
     catch(exception, host) {
-        const type = host.getType();
-        const method = `_${type}`;
+        this.type = host.getType();
+        this.exception = exception;
+        this.host = host;
+        const method = `_${this.type}`;
         if (!this[method])
-            throw new errors_1.UnsupportedProtocolError(host.getType());
-        this[method](exception, host);
+            throw new errors_1.UnsupportedProtocolError(this.type);
+        this[method]();
     }
-    _http(exception, host) {
-        const ctx = host.switchToHttp();
+    _http() {
+        const ctx = this.host.switchToHttp();
         const response = ctx.getResponse();
         const request = ctx.getRequest();
-        const meta = exception?.meta;
-        const status = exception instanceof common_1.HttpException
-            ? exception.getStatus()
+        const meta = this.exception?.meta;
+        const status = this.exception instanceof common_1.HttpException
+            ? this.exception.getStatus()
             : meta?.status ?? common_1.HttpStatus.INTERNAL_SERVER_ERROR;
-        this.log(exception);
-        response.status(status).json({
+        this.log(this.exception);
+        response.status(status).json(this.format({
             status,
-            code: this.code(exception),
-            hint: this.hint(exception),
             path: request.url,
             meta: meta?.meta,
-        });
+        }));
     }
-    _ws(exception, host) {
-        const ctx = host.switchToWs();
+    _ws() {
+        const ctx = this.host.switchToWs();
         const socket = ctx.getClient();
-        const meta = exception?.meta;
+        const meta = this.exception?.meta;
         const status = meta?.status ?? common_1.HttpStatus.INTERNAL_SERVER_ERROR;
-        this.log(exception);
+        this.log(this.exception);
         socket.send(JSON.stringify({
             event: 'error',
-            data: {
+            data: this.format({
                 status,
-                code: this.code(exception),
-                hint: this.hint(exception),
                 meta: meta?.meta,
-            },
+            }),
         }));
     }
-    _rpc(exception, host) {
+    _rpc() {
         throw new errors_1.UnsupportedProtocolError('rpc');
     }
     code(exception) {
@@ -60,6 +58,13 @@ let AllExceptionsFilter = class AllExceptionsFilter {
     hint(exception) {
         return (exception?.getResponse?.()?.message ?? exception.message);
     }
+    format(data) {
+        return {
+            code: this.code(this.exception),
+            hint: this.hint(this.exception),
+            ...data,
+        };
+    }
     log(exception) {
         if (exception instanceof axios_1.AxiosError)
             console.error(new errors_1.AxiosRequestError(exception?.response?.data?.statusCode ?? exception.status, exception?.response?.data?.error ?? exception.code, exception?.response?.data?.message ?? exception.message).stack);

package/dist/esm/src/filters/all-exception-filter.js

@@ -9,46 +9,44 @@ import { Catch, HttpException, HttpStatus, } from '@nestjs/common';
 import { AxiosRequestError, UnsupportedProtocolError } from '../errors.js';
 let AllExceptionsFilter = class AllExceptionsFilter {
     catch(exception, host) {
-        const type = host.getType();
-        const method = `_${type}`;
+        this.type = host.getType();
+        this.exception = exception;
+        this.host = host;
+        const method = `_${this.type}`;
         if (!this[method])
-            throw new UnsupportedProtocolError(host.getType());
-        this[method](exception, host);
+            throw new UnsupportedProtocolError(this.type);
+        this[method]();
     }
-    _http(exception, host) {
-        const ctx = host.switchToHttp();
+    _http() {
+        const ctx = this.host.switchToHttp();
         const response = ctx.getResponse();
         const request = ctx.getRequest();
-        const meta = exception?.meta;
-        const status = exception instanceof HttpException
-            ? exception.getStatus()
+        const meta = this.exception?.meta;
+        const status = this.exception instanceof HttpException
+            ? this.exception.getStatus()
             : meta?.status ?? HttpStatus.INTERNAL_SERVER_ERROR;
-        this.log(exception);
-        response.status(status).json({
+        this.log(this.exception);
+        response.status(status).json(this.format({
             status,
-            code: this.code(exception),
-            hint: this.hint(exception),
             path: request.url,
             meta: meta?.meta,
-        });
+        }));
     }
-    _ws(exception, host) {
-        const ctx = host.switchToWs();
+    _ws() {
+        const ctx = this.host.switchToWs();
         const socket = ctx.getClient();
-        const meta = exception?.meta;
+        const meta = this.exception?.meta;
         const status = meta?.status ?? HttpStatus.INTERNAL_SERVER_ERROR;
-        this.log(exception);
+        this.log(this.exception);
         socket.send(JSON.stringify({
             event: 'error',
-            data: {
+            data: this.format({
                 status,
-                code: this.code(exception),
-                hint: this.hint(exception),
                 meta: meta?.meta,
-            },
+            }),
         }));
     }
-    _rpc(exception, host) {
+    _rpc() {
         throw new UnsupportedProtocolError('rpc');
     }
     code(exception) {
@@ -57,6 +55,13 @@ let AllExceptionsFilter = class AllExceptionsFilter {
     hint(exception) {
         return (exception?.getResponse?.()?.message ?? exception.message);
     }
+    format(data) {
+        return {
+            code: this.code(this.exception),
+            hint: this.hint(this.exception),
+            ...data,
+        };
+    }
     log(exception) {
         if (exception instanceof AxiosError)
             console.error(new AxiosRequestError(exception?.response?.data?.statusCode ?? exception.status, exception?.response?.data?.error ?? exception.code, exception?.response?.data?.message ?? exception.message).stack);

package/dist/types/src/filters/all-exception-filter.d.ts

@@ -1,10 +1,17 @@
-import { ExceptionFilter, ArgumentsHost } from '@nestjs/common';
+import { ExceptionFilter, ArgumentsHost, ContextType } from '@nestjs/common';
 export declare class AllExceptionsFilter implements ExceptionFilter {
+    protected type: ContextType;
+    protected exception: Error;
+    protected host: ArgumentsHost;
     catch(exception: Error, host: ArgumentsHost): void;
     private _http;
     private _ws;
     private _rpc;
     private code;
     private hint;
+    protected format(data: Record<string, unknown>): {
+        code: string;
+        hint: string | [string];
+    };
     protected log(exception: Error): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biorate/nestjs-tools",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "NestJS tools",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -45,7 +45,7 @@
   "keywords": [],
   "author": "llevkin",
   "license": "MIT",
-  "gitHead": "8c6857bfe61de7b03025b0d883c478045c14390a",
+  "gitHead": "ba34f02a95796fee72c9dc822e31eaa740e09b4a",
   "peerDependencies": {
     "@nestjs/common": ">=10.4.15",
     "@nestjs/core": ">=10.4.15",
@@ -59,13 +59,13 @@
     "ws": ">=8.18.0"
   },
   "dependencies": {
-    "@biorate/axios": "3.4.0",
-    "@biorate/config": "3.2.3",
+    "@biorate/axios": "3.4.1",
+    "@biorate/config": "3.2.4",
     "@biorate/errors": "3.1.2",
-    "@biorate/inversion": "3.1.3",
-    "@biorate/opentelemetry": "2.4.2",
-    "@biorate/prometheus": "3.1.3",
-    "@biorate/tools": "3.1.2",
+    "@biorate/inversion": "3.1.4",
+    "@biorate/opentelemetry": "2.4.3",
+    "@biorate/prometheus": "3.1.4",
+    "@biorate/tools": "3.1.3",
     "http-proxy": "1.18.1",
     "http-proxy-middleware": "2.0.6",
     "json-stringify-safe": "5.0.1",