@bymax-one/nest-core 1.0.0 → 1.1.0

package/dist/openapi/index.mjs

@@ -0,0 +1,266 @@
+import { Logger } from '@nestjs/common';
+
+// src/openapi/openapi.bootstrap.ts
+
+// src/core.tokens.ts
+var BYMAX_CORE_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_CORE_OPTIONS");
+
+// src/runtime.environment.ts
+var NON_PRODUCTION_ENVIRONMENTS = /* @__PURE__ */ new Set(["development", "test"]);
+function isProductionRuntime(value = process.env["NODE_ENV"]) {
+  if (value === void 0) {
+    return true;
+  }
+  return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
+}
+
+// src/envelope/error-codes.ts
+var BYMAX_BAD_REQUEST = "BYMAX_BAD_REQUEST";
+var BYMAX_VALIDATION_FAILED = "BYMAX_VALIDATION_FAILED";
+var BYMAX_UNAUTHORIZED = "BYMAX_UNAUTHORIZED";
+var BYMAX_FORBIDDEN = "BYMAX_FORBIDDEN";
+var BYMAX_NOT_FOUND = "BYMAX_NOT_FOUND";
+var BYMAX_CONFLICT = "BYMAX_CONFLICT";
+var BYMAX_PAYLOAD_TOO_LARGE = "BYMAX_PAYLOAD_TOO_LARGE";
+var BYMAX_UNSUPPORTED_MEDIA_TYPE = "BYMAX_UNSUPPORTED_MEDIA_TYPE";
+var BYMAX_UNPROCESSABLE_ENTITY = "BYMAX_UNPROCESSABLE_ENTITY";
+var BYMAX_TOO_MANY_REQUESTS = "BYMAX_TOO_MANY_REQUESTS";
+var BYMAX_CLIENT_ERROR = "BYMAX_CLIENT_ERROR";
+var BYMAX_INTERNAL_ERROR = "BYMAX_INTERNAL_ERROR";
+var BYMAX_NOT_IMPLEMENTED = "BYMAX_NOT_IMPLEMENTED";
+var BYMAX_BAD_GATEWAY = "BYMAX_BAD_GATEWAY";
+var BYMAX_SERVICE_UNAVAILABLE = "BYMAX_SERVICE_UNAVAILABLE";
+var BYMAX_GATEWAY_TIMEOUT = "BYMAX_GATEWAY_TIMEOUT";
+
+// src/openapi/openapi.schemas.ts
+var ERROR_CODES = [
+  BYMAX_BAD_REQUEST,
+  BYMAX_VALIDATION_FAILED,
+  BYMAX_UNAUTHORIZED,
+  BYMAX_FORBIDDEN,
+  BYMAX_NOT_FOUND,
+  BYMAX_CONFLICT,
+  BYMAX_PAYLOAD_TOO_LARGE,
+  BYMAX_UNSUPPORTED_MEDIA_TYPE,
+  BYMAX_UNPROCESSABLE_ENTITY,
+  BYMAX_TOO_MANY_REQUESTS,
+  BYMAX_CLIENT_ERROR,
+  BYMAX_INTERNAL_ERROR,
+  BYMAX_NOT_IMPLEMENTED,
+  BYMAX_BAD_GATEWAY,
+  BYMAX_SERVICE_UNAVAILABLE,
+  BYMAX_GATEWAY_TIMEOUT
+];
+var CORE_SCHEMAS = {
+  BymaxErrorCode: {
+    type: "string",
+    enum: ERROR_CODES,
+    description: "Stable machine-readable error codes emitted by this package. A domain error may pass through its own code, so a response is not restricted to this catalogue."
+  },
+  BymaxErrorDetails: {
+    description: "Structured error context. The array form carries one entry per validation violation; the object form carries the development-only internals dump.",
+    oneOf: [
+      { type: "array", items: {} },
+      { type: "object", additionalProperties: true }
+    ]
+  },
+  BymaxErrorEnvelope: {
+    type: "object",
+    description: "The shape of every error response served by this application.",
+    required: ["statusCode", "code", "message", "timestamp", "path"],
+    properties: {
+      statusCode: { type: "integer", example: 404 },
+      code: {
+        type: "string",
+        example: BYMAX_NOT_FOUND,
+        description: "A code from BymaxErrorCode, or a domain code passed through unchanged."
+      },
+      message: { type: "string", description: "Human-readable and safe to show end users." },
+      details: { $ref: "#/components/schemas/BymaxErrorDetails" },
+      correlationId: {
+        type: "string",
+        description: "Present only when a correlation provider resolves an id."
+      },
+      timestamp: { type: "string", format: "date-time" },
+      path: { type: "string", example: "/invoices/42" }
+    }
+  },
+  BymaxHealthCheckEntry: {
+    type: "object",
+    description: "One indicator's result within a readiness response.",
+    required: ["name", "status"],
+    properties: {
+      name: { type: "string", example: "redis" },
+      status: { type: "string", enum: ["up", "down"] },
+      details: {
+        type: "object",
+        additionalProperties: true,
+        description: "Safe diagnostic context. Never carries secrets or connection strings."
+      }
+    }
+  },
+  BymaxHealthResponse: {
+    type: "object",
+    description: "The body served by the liveness and readiness endpoints.",
+    required: ["status", "checks"],
+    properties: {
+      status: {
+        type: "string",
+        enum: ["ok", "error"],
+        description: "'ok' only when every check is up. Liveness is always 'ok'."
+      },
+      checks: {
+        type: "array",
+        items: { $ref: "#/components/schemas/BymaxHealthCheckEntry" },
+        description: "Empty for the liveness endpoint."
+      }
+    }
+  },
+  BymaxPageMeta: {
+    type: "object",
+    description: "Offset-pagination metadata.",
+    required: ["page", "limit", "totalItems", "totalPages"],
+    properties: {
+      page: { type: "integer", minimum: 1, example: 1 },
+      limit: { type: "integer", minimum: 1, example: 20 },
+      totalItems: { type: "integer", minimum: 0, example: 137 },
+      totalPages: { type: "integer", minimum: 0, example: 7 }
+    }
+  },
+  BymaxPageResult: {
+    type: "object",
+    description: "An offset-paginated page. Compose it with a concrete item schema by overriding `items`.",
+    required: ["items", "meta"],
+    properties: {
+      items: { type: "array", items: {} },
+      meta: { $ref: "#/components/schemas/BymaxPageMeta" }
+    }
+  },
+  BymaxCursorResult: {
+    type: "object",
+    description: "A cursor-paginated page. Compose it with a concrete item schema by overriding `items`.",
+    required: ["items", "nextCursor"],
+    properties: {
+      items: { type: "array", items: {} },
+      nextCursor: {
+        type: "string",
+        nullable: true,
+        description: "Opaque cursor for the next page, or null when the last page was reached."
+      }
+    }
+  }
+};
+var CORE_PARAMETERS = {
+  BymaxPageQueryPage: {
+    name: "page",
+    in: "query",
+    required: false,
+    description: "1-based page number. Out-of-range and non-numeric input is clamped.",
+    schema: { type: "integer", minimum: 1, default: 1 }
+  },
+  BymaxPageQueryLimit: {
+    name: "limit",
+    in: "query",
+    required: false,
+    description: "Items per page. Clamped to the range this application configures.",
+    schema: { type: "integer", minimum: 1, default: 20 }
+  },
+  BymaxCursorQueryCursor: {
+    name: "cursor",
+    in: "query",
+    required: false,
+    description: "Opaque cursor from a previous response. Omit to request the first page.",
+    schema: { type: "string" }
+  }
+};
+
+// src/openapi/openapi.document.ts
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+function mergeAbsent(existing, additions) {
+  return { ...additions, ...existing };
+}
+function augmentDocument(document, options) {
+  const components = asRecord(document.components);
+  const merged = { ...components };
+  if (options.includeCoreSchemas) {
+    merged["schemas"] = mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS);
+    merged["parameters"] = mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS);
+  }
+  const securitySchemeNames = Object.keys(options.securitySchemes);
+  if (securitySchemeNames.length > 0) {
+    merged["securitySchemes"] = mergeAbsent(
+      asRecord(components["securitySchemes"]),
+      options.securitySchemes
+    );
+  }
+  return { ...document, components: merged };
+}
+
+// src/optional-peer.ts
+function isMissingModuleError(cause) {
+  const code = cause.code;
+  return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
+}
+function missingPeerMessage(option, peer) {
+  return `${option} is true but the optional peer ${peer} is not installed. Run: pnpm add ${peer}`;
+}
+
+// src/openapi/openapi.loader.ts
+var MISSING_PEER_MESSAGE = missingPeerMessage("openapi.enabled", "@nestjs/swagger");
+async function loadSwagger() {
+  try {
+    return await import('@nestjs/swagger');
+  } catch (cause) {
+    if (isMissingModuleError(cause)) {
+      throw new Error(MISSING_PEER_MESSAGE, { cause });
+    }
+    throw cause;
+  }
+}
+
+// src/openapi/openapi.bootstrap.ts
+var OPTIONS_UNRESOLVED_MESSAGE = "[BymaxCoreModule] applyBymaxOpenApi could not resolve BYMAX_CORE_OPTIONS from the application. Register BymaxCoreModule (forRoot or forRootAsync) before calling it, and keep the module global or import it into the module you bootstrap.";
+function resolveCoreOptions(app) {
+  try {
+    return app.get(BYMAX_CORE_OPTIONS);
+  } catch (cause) {
+    throw new Error(OPTIONS_UNRESOLVED_MESSAGE, { cause });
+  }
+}
+function buildConfig(builder, options) {
+  builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
+  for (const server of options.servers) {
+    builder.addServer(server.url, server.description);
+  }
+  return builder.build();
+}
+async function applyBymaxOpenApi(app) {
+  const logger = new Logger("BymaxCoreModule");
+  const options = resolveCoreOptions(app).openapi;
+  if (isProductionRuntime()) {
+    if (options.suppressedInProduction || options.enabled) {
+      logger.warn(
+        'openapi.enabled was requested but the OpenAPI document is never served in production. Set NODE_ENV to "development" or "test" to serve it.'
+      );
+    }
+    return { mounted: false, reason: "production" };
+  }
+  if (!options.enabled) {
+    return { mounted: false, reason: "disabled" };
+  }
+  const swagger = await loadSwagger();
+  const config = buildConfig(new swagger.DocumentBuilder(), options);
+  const document = augmentDocument(swagger.SwaggerModule.createDocument(app, config), options);
+  swagger.SwaggerModule.setup(options.path, app, document, {
+    jsonDocumentUrl: options.jsonPath
+  });
+  logger.log(`OpenAPI document served at "/${options.path}" (JSON at "/${options.jsonPath}")`);
+  return { mounted: true, path: options.path };
+}
+
+export { applyBymaxOpenApi };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.0.0",
-  "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints, and an optional Prometheus metrics endpoint.",
+  "version": "1.1.0",
+  "description": "Zero-dependency NestJS 11 application foundation kit: error-envelope exception filter, request-timing interceptor, pagination helpers, health endpoints with indicator discovery, an optional Prometheus metrics endpoint with a contribution contract, OpenAPI documents in development, and OpenTelemetry trace correlation.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
   "homepage": "https://github.com/bymaxone/nest-core#readme",
@@ -53,8 +53,51 @@
         "default": "./dist/health/index.cjs"
       }
     },
+    "./metrics": {
+      "import": {
+        "types": "./dist/metrics/index.d.ts",
+        "default": "./dist/metrics/index.mjs"
+      },
+      "require": {
+        "types": "./dist/metrics/index.d.cts",
+        "default": "./dist/metrics/index.cjs"
+      }
+    },
+    "./openapi": {
+      "import": {
+        "types": "./dist/openapi/index.d.ts",
+        "default": "./dist/openapi/index.mjs"
+      },
+      "require": {
+        "types": "./dist/openapi/index.d.cts",
+        "default": "./dist/openapi/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "build": "pnpm clean && tsup",
+    "check:exports": "attw --pack . --profile strict",
+    "check:published": "node scripts/check-published-surface.mjs",
+    "check:runtime": "node scripts/check-consumer-runtime.mjs",
+    "clean": "node -e \"const fs=require('node:fs');for(const d of ['dist','coverage'])fs.rmSync(d,{recursive:true,force:true})\"",
+    "dogfood": "node scripts/dogfood-smoke-test.mjs",
+    "lint": "eslint --no-error-on-unmatched-pattern src scripts test",
+    "lint:fix": "eslint --no-error-on-unmatched-pattern src scripts test --fix",
+    "mutation": "stryker run",
+    "mutation:dry-run": "stryker run --dryRunOnly",
+    "mutation:incremental": "stryker run --incremental",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
+    "release": "npm publish --provenance --access public",
+    "size": "node scripts/check-size.mjs",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
+    "test:e2e": "jest --config jest.e2e.config.ts",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit"
+  },
   "lint-staged": {
     "*.{ts,tsx,js,mjs,cjs}": [
       "eslint --fix",
@@ -64,15 +107,22 @@
       "prettier --write"
     ]
   },
-  "dependencies": {},
   "peerDependencies": {
     "@nestjs/common": "^11.0.16",
     "@nestjs/core": "^11.1.18",
+    "@nestjs/swagger": "^11.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "prom-client": "^15.0.0",
     "reflect-metadata": "^0.2.0",
-    "rxjs": "^7.0.0",
-    "prom-client": "^15.0.0"
+    "rxjs": "^7.0.0"
   },
   "peerDependenciesMeta": {
+    "@nestjs/swagger": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "prom-client": {
       "optional": true
     }
@@ -85,7 +135,10 @@
     "@nestjs/common": "^11.1.20",
     "@nestjs/core": "^11.1.20",
     "@nestjs/platform-express": "^11.1.20",
+    "@nestjs/swagger": "^11.4.6",
     "@nestjs/testing": "^11.1.20",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
     "@stryker-mutator/core": "^9",
     "@stryker-mutator/jest-runner": "^9",
     "@stryker-mutator/typescript-checker": "^9",
@@ -124,8 +177,13 @@
     "health-check",
     "prometheus",
     "metrics",
+    "openapi",
+    "swagger",
+    "opentelemetry",
+    "tracing",
     "typescript"
   ],
+  "packageManager": "pnpm@11.20.0",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -142,28 +200,13 @@
       ],
       "health": [
         "./dist/health/index.d.cts"
+      ],
+      "openapi": [
+        "./dist/openapi/index.d.cts"
+      ],
+      "metrics": [
+        "./dist/metrics/index.d.cts"
       ]
     }
-  },
-  "scripts": {
-    "build": "pnpm clean && tsup",
-    "check:exports": "attw --pack . --profile strict",
-    "check:published": "node scripts/check-published-surface.mjs",
-    "check:runtime": "node scripts/check-consumer-runtime.mjs",
-    "clean": "node -e \"const fs=require('node:fs');for(const d of ['dist','coverage'])fs.rmSync(d,{recursive:true,force:true})\"",
-    "dogfood": "node scripts/dogfood-smoke-test.mjs",
-    "lint": "eslint --no-error-on-unmatched-pattern src scripts test",
-    "lint:fix": "eslint --no-error-on-unmatched-pattern src scripts test --fix",
-    "mutation": "stryker run",
-    "mutation:dry-run": "stryker run --dryRunOnly",
-    "mutation:incremental": "stryker run --incremental",
-    "release": "npm publish --provenance --access public",
-    "size": "node scripts/check-size.mjs",
-    "test": "jest",
-    "test:cov": "jest --coverage",
-    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
-    "test:e2e": "jest --config jest.e2e.config.ts",
-    "test:watch": "jest --watch",
-    "typecheck": "tsc --noEmit"
   }
-}
+}