![\"@bymax-one/nest-core\"](\"https://img.shields.io/badge/%40bymax--one-nest--core-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E\"){kind=icon}
\n\n
\n Zero-dependency application foundation kit for NestJS
\n Error Envelope · Request Timing · Offset & Cursor Pagination · Health Probes · Prometheus Metrics · Zero Runtime Dependencies\n
\n ![\"npm](\"https://img.shields.io/npm/v/@bymax-one/nest-core?style=flat-square&colorA=000000&colorB=000000\")
![\"npm](\"https://img.shields.io/npm/dm/@bymax-one/nest-core?style=flat-square&colorA=000000&colorB=000000\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/bymaxone/nest-core/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI\")
![\"coverage\"](\"https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"mutation](\"https://img.shields.io/badge/mutation-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
\n
![\"license\"](\"https://img.shields.io/github/license/bymaxone/nest-core?style=flat-square&colorA=000000&colorB=000000\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}
\n GitHub ·\n Issues ·\n Quick Start ·\n API Reference ·\n Example App\n
\n\n---\n\n## ✨ Overview\n\n`@bymax-one/nest-core` is the layer every service in a fleet ends up writing for itself: one\nerror shape, one timing sample, one pagination contract, one health probe, one metrics\nendpoint. Writing it per service is how five services end up answering the same failure five\ndifferent ways, and how a client integration breaks because one of them changed its error\nbody.\n\nIt ships `\"dependencies\": {}`. Everything it touches — NestJS, `rxjs`, `reflect-metadata`, and\nthe three optional peers behind the features that need them (`prom-client`, `@nestjs/swagger`,\n`@opentelemetry/api`) — is a peer whose version you already control. A feature you leave off\nnever loads its peer, which the release gate asserts against the packed tarball.\n\n### Why nest-core?\n\n- **One error shape, fleet-wide.** A versioned code catalog and a fixed envelope, so a client\n writes one error handler instead of one per service — and an unknown failure becomes a\n generic 500 rather than whatever the framework happened to serialize.\n- **Features register only when enabled.** Turning metrics off does not leave a disabled\n provider in the container; it leaves no provider, and `prom-client` is never imported. That\n is what lets it stay an optional peer.\n- **Pagination without a provider.** `./pagination` is pure functions on their own subpath —\n no module to import, nothing to inject, usable from a script or a test.\n- **Health that cannot hang.** An indicator that rejects becomes a `down` entry from its\n top-level message alone, truncated; a slow one is converted by the aggregator rather than\n holding the probe open.\n\n---\n\n## 🔥 Features\n\n### 🚨 Errors\n\n- ✅ **Stable envelope** — one JSON shape for every error an application returns:\n `statusCode`, `code`, `message`, `details`, `correlationId`, `timestamp`, `path`\n- ✅ **Versioned code catalog** — `BYMAX_NOT_FOUND`, `BYMAX_CONFLICT`, `BYMAX_BAD_GATEWAY`\n and the rest, exported as constants so a client maps a `code` rather than a message string\n- ✅ **Internals stay internal** — an unknown error becomes a generic 500; its message and\n stack are captured for your logger, and reach the body only under `exposeInternals`\n- ✅ **Correlation id** — resolved through `BYMAX_CORRELATION_PROVIDER`, so the id comes from\n wherever your request context already keeps it\n\n### ⏱️ Observability\n\n- ✅ **Request timing** — one sample per closed request, rejections included, handed to the sink you register;\n the library stores nothing itself\n- ✅ **Slow-request flag** — samples above `slowRequestThresholdMs` are marked, so a sink can\n branch without re-deriving the threshold\n- ✅ **Prometheus endpoint** — opt-in scrape route over `BYMAX_METRICS_REGISTRY`;\n `prom-client` is imported only when it is enabled\n- ✅ **Contributed metrics** — a provider marked `@BymaxMetricsContributor()` publishes its\n own collectors on that same registry, so an imported library's metrics land in your scrape\n- ✅ **Trace correlation** — reads the active OpenTelemetry span, so timing samples (and,\n when you opt in, error envelopes) carry the trace id; never creates a span or an SDK\n- ✅ **OpenAPI document, development only** — one bootstrap call publishes an interactive\n UI carrying the schemas this package owns; in production it is never served, guarded twice\n\n### 📄 Pagination & Health\n\n- ✅ **Offset and cursor** — `normalizePageQuery` / `buildPageResult` and\n `normalizeCursorQuery` / `buildCursorResult`, pure functions with no NestJS involvement\n- ✅ **Opaque cursors** — `encodeCursor` / `decodeCursor` round-trip a token a client carries\n back, treated as untrusted input on the way in\n- ✅ **Liveness and readiness** — separate endpoints, so a slow dependency fails readiness\n without restarting the pod\n- ✅ **Pluggable indicators** — implement `IHealthIndicator` against a client you already own\n and register it under the `BYMAX_HEALTH_INDICATORS` multi-token\n- ✅ **Discovered indicators** — opt in, and any provider marked\n `@BymaxHealthIndicator()` joins readiness: a library you import brings its own check\n\n### 🧩 Developer Experience\n\n- ✅ **Zero runtime dependencies** — `@nestjs/*`, `rxjs` and `reflect-metadata` arrive as\n peers, so you pin the versions\n- ✅ **Five subpaths** — the module, plus `./pagination`, `./health`, `./metrics` and\n `./openapi` that a package can import without pulling the module in\n- ✅ **Dual-format output** — ESM + CJS with declarations for each format, verified against\n the packed tarball on every run\n- ✅ **Independent features** — each is enabled on its own; the providers for the rest are\n never registered\n- ✅ **Typed end to end** — TypeScript `strict` with `exactOptionalPropertyTypes` and\n `noUncheckedIndexedAccess`; zero `any`\n\n---\n\n## 📦 Subpath Exports\n\n| Subpath | Contents |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `.` | `BymaxCoreModule`, the error envelope and its code catalog, the request-timing middleware, the DI tokens, and every option type |\n| `./pagination` | `normalizePageQuery`, `buildPageResult`, `normalizeCursorQuery`, `buildCursorResult`, `encodeCursor`, `decodeCursor` and their types — pure functions, no NestJS provider involved |\n| `./health` | `IHealthIndicator`, `HealthResponse`, the indicator contracts and the `@BymaxHealthIndicator()` marker, so a package that only implements an indicator does not import the module |\n| `./metrics` | `IMetricsContributor` and the `@BymaxMetricsContributor()` marker, so a package that only publishes metrics imports neither the module nor its DI tokens. The one subpath whose types name `prom-client`, which anyone implementing the contract already depends on |\n| `./openapi` | `applyBymaxOpenApi`, the one bootstrap call that builds and mounts the OpenAPI document — separate so an application that never documents its API never loads the code that does |\n\nEach subpath ships ESM and CommonJS with its own `.d.ts` and `.d.cts`, so\n`require()` and `import` both resolve the declarations meant for them.\n\n### Install\n\n```bash\npnpm add @bymax-one/nest-core @nestjs/common @nestjs/core reflect-metadata rxjs\n```\n\nAdd `prom-client` if you enable the metrics feature, `@nestjs/swagger` if you\nenable the OpenAPI feature, and `@opentelemetry/api` if you enable trace\ncorrelation. All three are optional peer dependencies: none is required, or ever\nloaded, unless you turn its feature on.\n\n```bash\npnpm add prom-client\npnpm add @opentelemetry/api\npnpm add -D @nestjs/swagger\n```\n\n`@nestjs/swagger` belongs in `devDependencies`: the document is never served in\nproduction, so a production install has no reason to carry it.\n\n## 🚀 Quick Start\n\n```typescript\nimport { Module } from '@nestjs/common'\nimport { BymaxCoreModule } from '@bymax-one/nest-core'\n\n@Module({\n imports: [BymaxCoreModule.forRoot()]\n})\nexport class AppModule {}\n```\n\nWith no options, `forRoot()` enables the error envelope, request timing, and\nhealth endpoints, and leaves metrics off. Every documented default is listed\nin the [configuration reference](#-configuration) below.\n\n## 🏭 Production Wiring with `forRootAsync`\n\nThe standard pattern in real applications: resolve options from your own\nconfiguration service, so behavior can vary by environment without a second\ncode path.\n\n```typescript\nimport { Module } from '@nestjs/common'\nimport { BymaxCoreModule } from '@bymax-one/nest-core'\n\n@Module({\n imports: [\n BymaxCoreModule.forRootAsync({\n inject: [AppConfigService],\n useFactory: (config: AppConfigService) => ({\n envelope: { exposeInternals: config.env === 'development' },\n timing: { slowRequestThresholdMs: 1_000 },\n metrics: { enabled: config.env === 'production' }\n })\n })\n ]\n})\nexport class AppModule {}\n```\n\n`isGlobal` is a module extra, not part of the options object, defaulting to\n`true`:\n\n```typescript\nBymaxCoreModule.forRoot({ isGlobal: false })\n```\n\n## ⚙️ Configuration\n\nEvery block is optional; an omitted block, or an omitted field within it,\nfalls back to the documented default. Pass only what you want to change.\n\n### `environment`\n\nThe one top-level option rather than a block, because it describes the\ndeployment rather than a feature.\n\n| Option | Type | Default | Description |\n| ------------- | -------- | ------- | ------------------------------------------------------------------------------------- |\n| `environment` | `string` | unset | The environment this deployment runs in, read only where `NODE_ENV` declares nothing. |\n\nSet it when your application validates its own environment variable and does not\nalso set `NODE_ENV`. `NODE_ENV` wins whenever it says anything, so this can never\nserve the OpenAPI document in a runtime that named itself production. Full rules\nand the classification table: [Production is a closed door](#production-is-a-closed-door).\n\n### `envelope`\n\n| Option | Type | Default | Description |\n| ----------------- | --------- | ------- | ---------------------------------------------------------------------------------------------- |\n| `enabled` | `boolean` | `true` | Registers the global exception filter. |\n| `exposeInternals` | `boolean` | `false` | Includes the original message and stack of unknown errors. Development only, never production. |\n\n### `timing`\n\n| Option | Type | Default | Description |\n| ------------------------ | --------- | ------- | ------------------------------------------------------------------------------ |\n| `enabled` | `boolean` | `true` | Applies the request-timing middleware to every route. |\n| `slowRequestThresholdMs` | `number` | unset | Samples above this duration are flagged `slow: true`. Absent means never slow. |\n\n### `health`\n\n| Option | Type | Default | Description |\n| ----------------------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `enabled` | `boolean` | `true` | Registers the health controller. |\n| `path` | `string` | `'health'` | Route prefix: `GET /