@bymax-one/nest-core 1.0.1 → 1.1.0

package/dist/metrics/index.d.cts

@@ -0,0 +1,57 @@
+import { CustomDecorator } from '@nestjs/common';
+import * as PromClient from 'prom-client';
+
+/**
+ * The dedicated registry backing the application's scrape endpoint. Collectors
+ * registered against it appear at `GET /metrics`; nothing else does.
+ */
+type MetricsRegistry = PromClient.Registry;
+/**
+ * A component that publishes its own metrics.
+ *
+ * Implement it on a provider, mark the class, and the module calls it once at
+ * bootstrap with the registry the scrape endpoint serves. Registration failures
+ * — most often a metric name another component already claimed — fail the boot
+ * with the contributor named, rather than surfacing at the first scrape.
+ */
+interface IMetricsContributor {
+    /**
+     * Register this component's collectors against the shared registry.
+     *
+     * Called exactly once, during application bootstrap, and only when the metrics
+     * feature is enabled. Construct collectors with `registers: [registry]` (or
+     * call `registry.registerMetric`); do not create metrics on the global default
+     * registry, which this package never scrapes.
+     *
+     * @param registry - The registry the scrape endpoint serves.
+     */
+    registerMetrics(registry: MetricsRegistry): void;
+}
+/**
+ * Reflect metadata key carrying the contributor marker. Namespaced so it cannot
+ * collide with a consumer's own metadata, and exported so a conformance test can
+ * assert a class is marked without depending on how the decorator is built.
+ */
+declare const BYMAX_METRICS_CONTRIBUTOR_METADATA = "bymax-one:metrics-contributor";
+/**
+ * Mark a provider class as a metrics contributor, so `BymaxCoreModule` calls it
+ * at bootstrap without the application wiring anything.
+ *
+ * The class must implement {@link IMetricsContributor}; a marked provider that
+ * does not fails at bootstrap with a message naming it. Contributors run only
+ * when the metrics feature is enabled — marking a class in an application that
+ * leaves metrics off costs one metadata entry and changes nothing.
+ *
+ * @returns The class decorator carrying the marker.
+ * @example
+ *   \@BymaxMetricsContributor()
+ *   \@Injectable()
+ *   export class QueueMetrics implements IMetricsContributor {
+ *     registerMetrics(registry: MetricsRegistry): void {
+ *       new Gauge({ name: 'bymax_queue_depth', help: 'Jobs waiting', registers: [registry] })
+ *     }
+ *   }
+ */
+declare function BymaxMetricsContributor(): CustomDecorator<string>;
+
+export { BYMAX_METRICS_CONTRIBUTOR_METADATA, BymaxMetricsContributor, type IMetricsContributor, type MetricsRegistry };

package/dist/metrics/index.d.ts

@@ -0,0 +1,57 @@
+import { CustomDecorator } from '@nestjs/common';
+import * as PromClient from 'prom-client';
+
+/**
+ * The dedicated registry backing the application's scrape endpoint. Collectors
+ * registered against it appear at `GET /metrics`; nothing else does.
+ */
+type MetricsRegistry = PromClient.Registry;
+/**
+ * A component that publishes its own metrics.
+ *
+ * Implement it on a provider, mark the class, and the module calls it once at
+ * bootstrap with the registry the scrape endpoint serves. Registration failures
+ * — most often a metric name another component already claimed — fail the boot
+ * with the contributor named, rather than surfacing at the first scrape.
+ */
+interface IMetricsContributor {
+    /**
+     * Register this component's collectors against the shared registry.
+     *
+     * Called exactly once, during application bootstrap, and only when the metrics
+     * feature is enabled. Construct collectors with `registers: [registry]` (or
+     * call `registry.registerMetric`); do not create metrics on the global default
+     * registry, which this package never scrapes.
+     *
+     * @param registry - The registry the scrape endpoint serves.
+     */
+    registerMetrics(registry: MetricsRegistry): void;
+}
+/**
+ * Reflect metadata key carrying the contributor marker. Namespaced so it cannot
+ * collide with a consumer's own metadata, and exported so a conformance test can
+ * assert a class is marked without depending on how the decorator is built.
+ */
+declare const BYMAX_METRICS_CONTRIBUTOR_METADATA = "bymax-one:metrics-contributor";
+/**
+ * Mark a provider class as a metrics contributor, so `BymaxCoreModule` calls it
+ * at bootstrap without the application wiring anything.
+ *
+ * The class must implement {@link IMetricsContributor}; a marked provider that
+ * does not fails at bootstrap with a message naming it. Contributors run only
+ * when the metrics feature is enabled — marking a class in an application that
+ * leaves metrics off costs one metadata entry and changes nothing.
+ *
+ * @returns The class decorator carrying the marker.
+ * @example
+ *   \@BymaxMetricsContributor()
+ *   \@Injectable()
+ *   export class QueueMetrics implements IMetricsContributor {
+ *     registerMetrics(registry: MetricsRegistry): void {
+ *       new Gauge({ name: 'bymax_queue_depth', help: 'Jobs waiting', registers: [registry] })
+ *     }
+ *   }
+ */
+declare function BymaxMetricsContributor(): CustomDecorator<string>;
+
+export { BYMAX_METRICS_CONTRIBUTOR_METADATA, BymaxMetricsContributor, type IMetricsContributor, type MetricsRegistry };

package/dist/metrics/index.mjs

@@ -0,0 +1,9 @@
+import { SetMetadata } from '@nestjs/common';
+
+// src/metrics/metrics.contract.ts
+var BYMAX_METRICS_CONTRIBUTOR_METADATA = "bymax-one:metrics-contributor";
+function BymaxMetricsContributor() {
+  return SetMetadata(BYMAX_METRICS_CONTRIBUTOR_METADATA, true);
+}
+
+export { BYMAX_METRICS_CONTRIBUTOR_METADATA, BymaxMetricsContributor };

package/dist/openapi/index.cjs

@@ -0,0 +1,268 @@
+'use strict';
+
+var common = require('@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 common.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 };
+}
+
+exports.applyBymaxOpenApi = applyBymaxOpenApi;

package/dist/openapi/index.d.cts

@@ -0,0 +1,44 @@
+import { INestApplication } from '@nestjs/common';
+
+/** Why the document was not mounted. */
+type OpenApiSkipReason = 
+/** The consumer never enabled the feature. */
+'disabled'
+/** The runtime is production, where the document is never served. */
+ | 'production';
+/** What {@link applyBymaxOpenApi} did, so a caller can assert on it. */
+interface OpenApiMountOutcome {
+    /** Whether the document and its UI were mounted. */
+    mounted: boolean;
+    /** Present only when `mounted` is `false`. */
+    reason?: OpenApiSkipReason;
+    /** The route the UI was mounted at. Present only when `mounted` is `true`. */
+    path?: string;
+}
+/**
+ * Build and mount the OpenAPI document and its interactive UI, when the
+ * configuration and the runtime both allow it.
+ *
+ * Call it once, after `NestFactory.create` and BEFORE the application starts
+ * listening. The ordering is not a style preference: mounting the document
+ * re-registers routes on the HTTP adapter, and on Express 5 doing that against
+ * an already-initialized application replaces the router — every route the
+ * application had, including its own controllers and this package's health
+ * endpoints, stops resolving. `app.listen()` performs that initialization, so
+ * "before listening" is the whole rule.
+ *
+ * It is safe to call unconditionally: with the feature disabled, or in
+ * production, it mounts nothing, loads no optional peer, and returns why.
+ *
+ * @param app - The created Nest application, not yet listening.
+ * @returns What happened: mounted, or skipped with a reason.
+ * @throws Error When `BymaxCoreModule` is not registered, or when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed.
+ * @example
+ *   const app = await NestFactory.create(AppModule)
+ *   await applyBymaxOpenApi(app)
+ *   await app.listen(3000)
+ */
+declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+
+export { type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };

package/dist/openapi/index.d.ts

@@ -0,0 +1,44 @@
+import { INestApplication } from '@nestjs/common';
+
+/** Why the document was not mounted. */
+type OpenApiSkipReason = 
+/** The consumer never enabled the feature. */
+'disabled'
+/** The runtime is production, where the document is never served. */
+ | 'production';
+/** What {@link applyBymaxOpenApi} did, so a caller can assert on it. */
+interface OpenApiMountOutcome {
+    /** Whether the document and its UI were mounted. */
+    mounted: boolean;
+    /** Present only when `mounted` is `false`. */
+    reason?: OpenApiSkipReason;
+    /** The route the UI was mounted at. Present only when `mounted` is `true`. */
+    path?: string;
+}
+/**
+ * Build and mount the OpenAPI document and its interactive UI, when the
+ * configuration and the runtime both allow it.
+ *
+ * Call it once, after `NestFactory.create` and BEFORE the application starts
+ * listening. The ordering is not a style preference: mounting the document
+ * re-registers routes on the HTTP adapter, and on Express 5 doing that against
+ * an already-initialized application replaces the router — every route the
+ * application had, including its own controllers and this package's health
+ * endpoints, stops resolving. `app.listen()` performs that initialization, so
+ * "before listening" is the whole rule.
+ *
+ * It is safe to call unconditionally: with the feature disabled, or in
+ * production, it mounts nothing, loads no optional peer, and returns why.
+ *
+ * @param app - The created Nest application, not yet listening.
+ * @returns What happened: mounted, or skipped with a reason.
+ * @throws Error When `BymaxCoreModule` is not registered, or when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed.
+ * @example
+ *   const app = await NestFactory.create(AppModule)
+ *   await applyBymaxOpenApi(app)
+ *   await app.listen(3000)
+ */
+declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+
+export { type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };