@bymax-one/nest-core 1.3.2 → 1.4.0

package/dist/openapi/index.mjs

@@ -1,5 +1,5 @@
-import { Logger, VersioningType, VERSION_NEUTRAL } from '@nestjs/common';
-import { ApplicationConfig } from '@nestjs/core';
+import { SetMetadata, Logger, VersioningType, VERSION_NEUTRAL } from '@nestjs/common';
+import { DiscoveryService, Reflector, ApplicationConfig } from '@nestjs/core';
 
 // src/openapi/openapi.bootstrap.ts
 
@@ -15,6 +15,116 @@ function isProductionRuntime(value = process.env["NODE_ENV"]) {
   return !NON_PRODUCTION_ENVIRONMENTS.has(value.trim().toLowerCase());
 }
 
+// src/discovery.ts
+function labelFor(className, token) {
+  return className === "" ? String(token) : className;
+}
+function findMarkedProviders(discovery, reflector, metadataKey) {
+  const marked = [];
+  for (const wrapper of discovery.getProviders()) {
+    const metatype = wrapper.metatype;
+    if (typeof metatype !== "function") {
+      continue;
+    }
+    if (reflector.get(metadataKey, metatype) !== true) {
+      continue;
+    }
+    marked.push({ instance: wrapper.instance, label: labelFor(metatype.name, wrapper.name) });
+  }
+  return marked;
+}
+var BYMAX_OPENAPI_CONTRACT_VERSION = 1;
+var BYMAX_OPENAPI_CONTRIBUTOR_METADATA = "bymax-one:openapi-contributor";
+function BymaxOpenApiContributor() {
+  return SetMetadata(BYMAX_OPENAPI_CONTRIBUTOR_METADATA, true);
+}
+
+// src/openapi/openapi.contribution.ts
+function createHandlerIdMap() {
+  const ids = /* @__PURE__ */ new Map();
+  const versions = /* @__PURE__ */ new Map();
+  return {
+    record: (controllerKey, methodKey, version, id) => {
+      const handlerKey = `${controllerKey}.${methodKey}`;
+      const seen = versions.get(handlerKey) ?? /* @__PURE__ */ new Set();
+      if (seen.has(version)) {
+        throw new Error(
+          `[BymaxCoreModule] two route handlers in this application answer to "${handlerKey}", so an OpenAPI fragment addressing it would apply to both. Handler keys are "<ControllerClassName>.<methodName>"; rename one of the controller classes.`
+        );
+      }
+      seen.add(version);
+      versions.set(handlerKey, seen);
+      ids.set(handlerKey, [...ids.get(handlerKey) ?? [], id]);
+    },
+    idsFor: (handlerKey) => ids.get(handlerKey) ?? [],
+    keys: () => [...ids.keys()]
+  };
+}
+function isContributor(instance) {
+  return typeof instance?.contributeOpenApi === "function";
+}
+function callContributor(contributor, label) {
+  try {
+    return contributor.contributeOpenApi();
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(
+      `[BymaxCoreModule] "${label}" failed to contribute to the OpenAPI document: ${reason}`,
+      {
+        cause
+      }
+    );
+  }
+}
+function assertContractVersion(fragment, label) {
+  if (fragment.contractVersion === BYMAX_OPENAPI_CONTRACT_VERSION) {
+    return;
+  }
+  throw new Error(
+    `[BymaxCoreModule] "${label}" contributed a fragment written against OpenAPI contract version ${String(fragment.contractVersion)}, and this package speaks version ${String(BYMAX_OPENAPI_CONTRACT_VERSION)}. Upgrade whichever of the two is behind; the shapes are not interchangeable.`
+  );
+}
+function resolveOperations(fragment, label, handlers) {
+  const entries = Object.entries(fragment.operations ?? {});
+  const unmatched = entries.filter(([handlerKey]) => handlers.idsFor(handlerKey).length === 0);
+  if (unmatched.length > 0) {
+    const known = handlers.keys();
+    throw new Error(
+      `[BymaxCoreModule] "${label}" contributed fragments for ${unmatched.length} handler(s) this application does not have: ${unmatched.map(([key]) => key).join(", ")}. Keys are "<ControllerClassName>.<methodName>". The application has: ${known.length === 0 ? "(none)" : known.join(", ")}.`
+    );
+  }
+  return Object.fromEntries(
+    entries.flatMap(
+      ([handlerKey, operation]) => handlers.idsFor(handlerKey).map((id) => [id, operation])
+    )
+  );
+}
+function collectContributions(discovery, reflector, handlers) {
+  const marked = [...findMarkedProviders(discovery, reflector, BYMAX_OPENAPI_CONTRIBUTOR_METADATA)];
+  const labels = marked.map(({ label }) => label);
+  const duplicated = labels.filter((label, index) => labels.indexOf(label) !== index);
+  if (duplicated.length > 0) {
+    throw new Error(
+      `[BymaxCoreModule] more than one OpenAPI contributor is named "${[...new Set(duplicated)].join('", "')}", so the order they merge in would depend on the container rather than on anything stated. Rename one of the contributor classes.`
+    );
+  }
+  marked.sort((left, right) => left.label.localeCompare(right.label));
+  return marked.map(({ instance, label }) => {
+    if (!isContributor(instance)) {
+      throw new Error(
+        `[BymaxCoreModule] "${label}" is marked @BymaxOpenApiContributor() but does not implement IOpenApiContributor: it must expose a "contributeOpenApi" method.`
+      );
+    }
+    const fragment = callContributor(instance, label);
+    assertContractVersion(fragment, label);
+    return {
+      label,
+      operations: resolveOperations(fragment, label, handlers),
+      components: fragment.components ?? {}
+    };
+  });
+}
+
 // src/route-defaults.ts
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
@@ -207,7 +317,8 @@ function operationsOf(item) {
 }
 function mergeResponses(existing, additions) {
   const merged = new Map(Object.entries(existing));
-  for (const [status, contributed] of Object.entries(additions)) {
+  for (const [status, value] of Object.entries(additions)) {
+    const contributed = asRecord(value);
     const current = asRecord(merged.get(status));
     if (current["content"] === void 0 && current["$ref"] === void 0) {
       const described = current["description"] === void 0 || current["description"] === "" ? contributed["description"] : current["description"];
@@ -287,11 +398,29 @@ function coreResponses(path, options, routes) {
   }
   return responses;
 }
-function augmentOperation(operation, path, method, options, routes) {
-  const result = { ...operation };
-  if (result["security"] === void 0) {
+function fragmentsFor(operationId, contributions) {
+  return contributions.flatMap(
+    (contribution) => Object.entries(contribution.operations).filter(([id]) => id === operationId).map(([, fragment]) => fragment)
+  );
+}
+function mergeFragment(operation, fragment) {
+  const { responses, ...members } = fragment;
+  const merged = { ...members, ...operation };
+  if (responses !== void 0) {
+    merged["responses"] = mergeResponses(asRecord(operation["responses"]), asRecord(responses));
+  }
+  return merged;
+}
+function augmentOperation(operation, path, method, options, routes, contributions) {
+  const declaredByDocument = operation["security"] !== void 0;
+  let result = { ...operation };
+  for (const fragment of fragmentsFor(result["operationId"], contributions)) {
+    result = { ...mergeFragment(result, fragment) };
+  }
+  if (!declaredByDocument) {
     const override = options.openapi.operationSecurity[operationKey(method, path)];
-    const security = override ?? ownRouteSecurity(path, method, options, routes);
+    const describedByLibrary = result["security"] !== void 0;
+    const security = override ?? (describedByLibrary ? void 0 : ownRouteSecurity(path, method, options, routes));
     if (security !== void 0) {
       result["security"] = security;
     }
@@ -347,24 +476,24 @@ function assertOverridesMatch(paths, openapi) {
     `[BymaxCoreModule] openapi.operationSecurity addresses ${unmatched.length} operation(s) that the document does not contain: ${unmatched.join(", ")}. Keys are "<METHOD> <path>" with the path exactly as documented, including any global prefix. The document contains: ${documented.length === 0 ? "(none)" : documented.join(", ")}.`
   );
 }
-function augmentPaths(paths, options, routes) {
+function augmentPaths(paths, options, routes, contributions) {
   return Object.fromEntries(
     Object.entries(paths).map(([path, item]) => {
       const augmented = operationsOf(item).map(([method, operation]) => [
         method,
-        augmentOperation(asRecord(operation), path, method, options, routes)
+        augmentOperation(asRecord(operation), path, method, options, routes, contributions)
       ]);
       return [path, { ...asRecord(item), ...Object.fromEntries(augmented) }];
     })
   );
 }
-function augmentDocument(document, options, pathPrefixes = [""]) {
+function augmentDocument(document, options, pathPrefixes = [""], contributions = []) {
   const { openapi } = options;
   const components = asRecord(document.components);
-  const merged = { ...components };
+  const merged = new Map(Object.entries(components));
   if (openapi.includeCoreSchemas) {
-    merged["schemas"] = mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS);
-    merged["parameters"] = mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS);
+    merged.set("schemas", mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS));
+    merged.set("parameters", mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS));
   }
   const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
     [METRICS_SCHEME_NAME]: {
@@ -374,20 +503,25 @@ function augmentDocument(document, options, pathPrefixes = [""]) {
     }
   };
   assertScrapeSchemeIsOurs(openapi, components, options.metrics.authToken !== void 0);
-  const schemes = mergeAbsent(asRecord(components["securitySchemes"]), {
+  const declaredSchemes = mergeAbsent(asRecord(components["securitySchemes"]), {
     ...openapi.securitySchemes,
     ...scrapeScheme
   });
-  if (Object.keys(schemes).length > 0) {
-    merged["securitySchemes"] = schemes;
+  if (Object.keys(declaredSchemes).length > 0) {
+    merged.set("securitySchemes", declaredSchemes);
+  }
+  for (const contribution of contributions) {
+    for (const [member, entries] of Object.entries(contribution.components)) {
+      merged.set(member, mergeAbsent(asRecord(merged.get(member)), entries));
+    }
   }
-  assertSchemesDeclared(openapi, schemes);
+  assertSchemesDeclared(openapi, asRecord(merged.get("securitySchemes")));
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
   assertOverridesMatch(served, openapi);
-  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes) };
+  const paths = document.paths === void 0 ? {} : { paths: augmentPaths(served, options, routes, contributions) };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
-  return { ...document, components: merged, ...paths, ...security };
+  return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
 }
 
 // src/optional-peer.ts
@@ -450,6 +584,27 @@ function readPathPrefixes(app) {
   const globalPrefix = config.getGlobalPrefix();
   return versionSegments(config.getVersioning()).map((segment) => `${globalPrefix}/${segment}`);
 }
+function recordingOperationIdFactory(handlers, configured) {
+  return (controllerKey, methodKey, version) => {
+    const id = configured === void 0 ? defaultOperationId(controllerKey, methodKey, version) : configured(controllerKey, methodKey, version);
+    handlers.record(controllerKey, methodKey, version, id);
+    return id;
+  };
+}
+function defaultOperationId(controllerKey, methodKey, version) {
+  return version === void 0 ? `${controllerKey}_${methodKey}` : `${controllerKey}_${methodKey}_${version}`;
+}
+function readContributions(app, handlers) {
+  let discovery;
+  let reflector;
+  try {
+    discovery = app.get(DiscoveryService);
+    reflector = app.get(Reflector);
+  } catch {
+    return [];
+  }
+  return collectContributions(discovery, reflector, handlers);
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -474,10 +629,15 @@ async function applyBymaxOpenApi(app) {
   }
   const swagger = await loadSwagger();
   const config = buildConfig(new swagger.DocumentBuilder(), options);
+  const handlers = createHandlerIdMap();
+  const generated = swagger.SwaggerModule.createDocument(app, config, {
+    operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
+  });
   const document = augmentDocument(
-    swagger.SwaggerModule.createDocument(app, config),
+    generated,
     resolved,
-    readPathPrefixes(app)
+    readPathPrefixes(app),
+    readContributions(app, handlers)
   );
   swagger.SwaggerModule.setup(options.path, app, document, {
     jsonDocumentUrl: options.jsonPath
@@ -486,4 +646,4 @@ async function applyBymaxOpenApi(app) {
   return { mounted: true, path: options.path };
 }
 
-export { applyBymaxOpenApi };
+export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, applyBymaxOpenApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-core",
-  "version": "1.3.2",
+  "version": "1.4.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",
@@ -136,6 +136,7 @@
     "@nestjs/common": "^11.1.20",
     "@nestjs/core": "^11.1.20",
     "@nestjs/platform-express": "^11.1.20",
+    "@nestjs/platform-fastify": "^11.1.29",
     "@nestjs/swagger": "^11.4.6",
     "@nestjs/testing": "^11.1.20",
     "@opentelemetry/api": "^1.9.1",
@@ -155,6 +156,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-security": "^4.0.0",
+    "fastify": "^5.11.3",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "jest": "^30.4.2",