@bymax-one/nest-core 1.6.0 → 1.6.2

package/dist/openapi/index.mjs

@@ -132,6 +132,82 @@ function collectContributions(discovery, reflector, handlers) {
   });
 }
 
+// src/openapi/openapi.shape.ts
+var OPERATION_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "head",
+  "options",
+  "trace"
+];
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+function operationsOf(item) {
+  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
+}
+function operationKey(method, path) {
+  return `${method.toUpperCase()} ${path}`;
+}
+
+// src/openapi/openapi.components.ts
+function isEmptyRequired(key, value) {
+  return key === "required" && Array.isArray(value) && value.length === 0;
+}
+var IGNORABLE_KEYS = /* @__PURE__ */ new Set(["type", "properties", "description"]);
+function describesNoShape(entry) {
+  const type = entry["type"];
+  if (type !== void 0 && type !== "object") {
+    return false;
+  }
+  const properties = entry["properties"];
+  if (!Object.hasOwn(entry, "properties") || asRecord(properties) !== properties) {
+    return false;
+  }
+  if (Object.keys(asRecord(properties)).length > 0) {
+    return false;
+  }
+  return Object.entries(entry).every(
+    ([key, value]) => IGNORABLE_KEYS.has(key) || isEmptyRequired(key, value)
+  );
+}
+function placeComponentEntries(existing, member, offered, onKept) {
+  const next = new Map(Object.entries(asRecord(existing)));
+  for (const [name, contributed] of Object.entries(asRecord(offered))) {
+    const declared = next.get(name);
+    const held = asRecord(declared);
+    const replaceable = member === "schemas" && describesNoShape(held);
+    if (declared !== void 0 && !replaceable) {
+      onKept(name);
+      continue;
+    }
+    const described = held["description"];
+    next.set(
+      name,
+      described === void 0 || described === "" ? contributed : { ...asRecord(contributed), description: described }
+    );
+  }
+  return Object.fromEntries(next);
+}
+function mergeContributedComponents(merged, contributions) {
+  const discarded = [];
+  for (const contribution of contributions) {
+    for (const [member, entries] of Object.entries(contribution.components)) {
+      const placed = placeComponentEntries(merged.get(member), member, entries, (name) => {
+        discarded.push({ contributor: contribution.label, member, name });
+      });
+      merged.set(member, placed);
+    }
+  }
+  return discarded;
+}
+
 // src/route-defaults.ts
 var DEFAULT_HEALTH_PATH = "health";
 var DEFAULT_METRICS_PATH = "metrics";
@@ -324,30 +400,6 @@ var CORE_PARAMETERS = {
   }
 };
 
-// src/openapi/openapi.shape.ts
-var OPERATION_METHODS = [
-  "get",
-  "post",
-  "put",
-  "patch",
-  "delete",
-  "head",
-  "options",
-  "trace"
-];
-function asRecord(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return {};
-  }
-  return value;
-}
-function operationsOf(item) {
-  return Object.entries(asRecord(item)).filter(([key]) => OPERATION_METHODS.includes(key));
-}
-function operationKey(method, path) {
-  return `${method.toUpperCase()} ${path}`;
-}
-
 // src/openapi/openapi.document.ts
 var METRICS_SCHEME_NAME = "BymaxMetricsAuth";
 var ERROR_ENVELOPE_SCHEMA = "BymaxErrorEnvelope";
@@ -539,8 +591,14 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   const components = asRecord(document.components);
   const merged = new Map(Object.entries(components));
   if (openapi.includeCoreSchemas) {
-    merged.set("schemas", mergeAbsent(asRecord(components["schemas"]), CORE_SCHEMAS));
-    merged.set("parameters", mergeAbsent(asRecord(components["parameters"]), CORE_PARAMETERS));
+    const keep = () => void 0;
+    const catalogue = [
+      ["schemas", CORE_SCHEMAS],
+      ["parameters", CORE_PARAMETERS]
+    ];
+    for (const [member, entries] of catalogue) {
+      merged.set(member, placeComponentEntries(merged.get(member), member, entries, keep));
+    }
   }
   const scrapeScheme = options.metrics.authToken === void 0 ? {} : {
     [METRICS_SCHEME_NAME]: {
@@ -557,11 +615,7 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
   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));
-    }
-  }
+  const discarded = mergeContributedComponents(merged, contributions);
   assertSchemesDeclared(openapi, asRecord(merged.get("securitySchemes")));
   const routes = indexOwnRoutes(options, pathPrefixes);
   const served = withoutDisabledRoutes(asRecord(document.paths), options, routes);
@@ -576,7 +630,10 @@ function augmentDocument(document, options, pathPrefixes = [""], contributions =
     )
   };
   const security = openapi.security.length > 0 && document.security === void 0 ? { security: openapi.security } : {};
-  return { ...document, components: Object.fromEntries(merged), ...paths, ...security };
+  return {
+    document: { ...document, components: Object.fromEntries(merged), ...paths, ...security },
+    discarded
+  };
 }
 
 // src/optional-peer.ts
@@ -671,6 +728,16 @@ function warnUnsecuredOperations(logger, keys) {
     `a client generated from the OpenAPI document will send no credentials to ${keys.length} operation(s): ${listed}${elided > 0 ? `, and ${elided} more` : ""}. They state no security requirement, the document declares no default, and other operations in it do state one \u2014 so this is more often a missing openapi.security default than a public API. Set openapi.security, or state the intent per operation with an explicit [] in openapi.operationSecurity.`
   );
 }
+function warnDiscardedComponents(logger, discarded) {
+  if (discarded.length === 0) {
+    return;
+  }
+  const elided = discarded.length - MAX_WARNED_OPERATIONS;
+  const listed = discarded.slice(0, MAX_WARNED_OPERATIONS).map(({ contributor, member, name }) => `${contributor} -> ${member}.${name}`).join(", ");
+  logger.warn(
+    `the served OpenAPI document already defines ${discarded.length} component entry(ies) a library also contributes: ${listed}${elided > 0 ? `, and ${elided} more` : ""}. The contributed version is not served, so a client generated from this document will not match that library's own types. What holds the name may be the application's own declaration, a core schema under openapi.includeCoreSchemas, or a contributor that sorted earlier \u2014 read the document before deciding what to remove.`
+  );
+}
 function buildConfig(builder, options) {
   builder.setTitle(options.title).setDescription(options.description).setVersion(options.version);
   for (const server of options.servers) {
@@ -700,13 +767,19 @@ async function applyBymaxOpenApi(app) {
     operationIdFactory: recordingOperationIdFactory(handlers, options.operationIdFactory)
   });
   const prefixes = readPathPrefixes(app);
-  const document = augmentDocument(generated, resolved, prefixes, readContributions(app, handlers));
+  const { document, discarded } = augmentDocument(
+    generated,
+    resolved,
+    prefixes,
+    readContributions(app, handlers)
+  );
   warnUnsecuredOperations(logger, unsecuredOperations(document, resolved, prefixes));
+  warnDiscardedComponents(logger, discarded);
   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 };
+  return { mounted: true, path: options.path, discarded };
 }
 
 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.6.0",
+  "version": "1.6.2",
   "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,7 +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/platform-fastify": "^11.2.4",
     "@nestjs/swagger": "^11.4.6",
     "@nestjs/testing": "^11.1.20",
     "@opentelemetry/api": "^1.9.1",
@@ -156,7 +156,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-security": "^4.0.0",
-    "fastify": "^5.11.3",
+    "fastify": "^5.12.5",
     "globals": "^17.6.0",
     "husky": "^9.1.7",
     "jest": "^30.4.2",