@bymax-one/nest-core 1.6.0 → 1.6.2

package/dist/openapi/index.cjs

@@ -134,6 +134,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";
@@ -326,30 +402,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";
@@ -541,8 +593,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]: {
@@ -559,11 +617,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);
@@ -578,7 +632,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
@@ -673,6 +730,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) {
@@ -702,13 +769,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 };
 }
 
 exports.BYMAX_OPENAPI_CONTRACT_VERSION = BYMAX_OPENAPI_CONTRACT_VERSION;

package/dist/openapi/index.d.cts

@@ -1,55 +1,4 @@
-import { INestApplication, CustomDecorator } 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.
- *
- * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
- * dynamic `import()`, which is what keeps the peer optional for everyone who
- * never enables the document — and Jest's module registry cannot service a
- * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
- * only the *enabled* path fails, with `dynamic import callback invoked without
- * --experimental-vm-modules`; the disabled and production paths never reach the
- * loader and pass either way, which is what makes the omission confusing.
- *
- * @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, when the feature is
- *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
- *   `openapi.operationSecurity` addresses an operation the generated document
- *   does not contain.
- * @example
- *   const app = await NestFactory.create(AppModule)
- *   await applyBymaxOpenApi(app)
- *   await app.listen(3000)
- */
-declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+import { CustomDecorator, INestApplication } from '@nestjs/common';
 
 /**
  * Addresses one route handler, as `'<ControllerClassName>.<methodName>'`.
@@ -196,4 +145,99 @@ declare const BYMAX_OPENAPI_CONTRIBUTOR_METADATA = "bymax-one:openapi-contributo
  */
 declare function BymaxOpenApiContributor(): CustomDecorator<string>;
 
-export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };
+/**
+ * @fileoverview Placing offered entries — this package's catalogue and every
+ * library contribution — into a document's `components`, and reporting what a
+ * contributor could not place.
+ *
+ * A module of its own because the rule here is not the document's rule: everywhere else the merge is "the existing side wins", and this is the
+ * one place that asks whether the existing side says anything at all. Keeping
+ * the question and its narrow carve-out together makes the exception legible as
+ * an exception.
+ * @layer internal
+ */
+
+/**
+ * One component entry a contributor offered and the document already declared.
+ *
+ * Carries the contributor's label because a collision is only actionable if you
+ * know who lost it: an application with several contributing libraries would
+ * otherwise be told a name was dropped without being told whose it was.
+ */
+interface DiscardedComponent {
+    /** The contributing class, as {@link ResolvedContribution.label} names it. */
+    readonly contributor: string;
+    /** The component member, such as `schemas` or `parameters`. */
+    readonly member: string;
+    /** The entry's name within that member. */
+    readonly name: string;
+}
+
+/** 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;
+    /**
+     * Component entries a contributor offered that the served document already
+     * defined with a shape of its own. Present only when `mounted` is `true`;
+     * empty when every contribution was placed.
+     *
+     * The merge prefers whatever holds the name already, so a collision is not an
+     * error and does not stop the boot. The holder is usually the application's
+     * own declaration, but it may be a core schema this package contributes under
+     * `openapi.includeCoreSchemas` or an earlier contributor's entry — the report
+     * names what was dropped and by whom, not who owns the winning definition.
+     *
+     * It is reported because it is otherwise unobservable from either side: the
+     * contributing library cannot tell its entry was dropped, and the application
+     * cannot tell one was offered.
+     */
+    discarded?: readonly DiscardedComponent[];
+}
+/**
+ * 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.
+ *
+ * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
+ * dynamic `import()`, which is what keeps the peer optional for everyone who
+ * never enables the document — and Jest's module registry cannot service a
+ * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
+ * only the *enabled* path fails, with `dynamic import callback invoked without
+ * --experimental-vm-modules`; the disabled and production paths never reach the
+ * loader and pass either way, which is what makes the omission confusing.
+ *
+ * @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, when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
+ *   `openapi.operationSecurity` addresses an operation the generated document
+ *   does not contain.
+ * @example
+ *   const app = await NestFactory.create(AppModule)
+ *   await applyBymaxOpenApi(app)
+ *   await app.listen(3000)
+ */
+declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+
+export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type DiscardedComponent, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };

package/dist/openapi/index.d.ts

@@ -1,55 +1,4 @@
-import { INestApplication, CustomDecorator } 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.
- *
- * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
- * dynamic `import()`, which is what keeps the peer optional for everyone who
- * never enables the document — and Jest's module registry cannot service a
- * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
- * only the *enabled* path fails, with `dynamic import callback invoked without
- * --experimental-vm-modules`; the disabled and production paths never reach the
- * loader and pass either way, which is what makes the omission confusing.
- *
- * @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, when the feature is
- *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
- *   `openapi.operationSecurity` addresses an operation the generated document
- *   does not contain.
- * @example
- *   const app = await NestFactory.create(AppModule)
- *   await applyBymaxOpenApi(app)
- *   await app.listen(3000)
- */
-declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+import { CustomDecorator, INestApplication } from '@nestjs/common';
 
 /**
  * Addresses one route handler, as `'<ControllerClassName>.<methodName>'`.
@@ -196,4 +145,99 @@ declare const BYMAX_OPENAPI_CONTRIBUTOR_METADATA = "bymax-one:openapi-contributo
  */
 declare function BymaxOpenApiContributor(): CustomDecorator<string>;
 
-export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };
+/**
+ * @fileoverview Placing offered entries — this package's catalogue and every
+ * library contribution — into a document's `components`, and reporting what a
+ * contributor could not place.
+ *
+ * A module of its own because the rule here is not the document's rule: everywhere else the merge is "the existing side wins", and this is the
+ * one place that asks whether the existing side says anything at all. Keeping
+ * the question and its narrow carve-out together makes the exception legible as
+ * an exception.
+ * @layer internal
+ */
+
+/**
+ * One component entry a contributor offered and the document already declared.
+ *
+ * Carries the contributor's label because a collision is only actionable if you
+ * know who lost it: an application with several contributing libraries would
+ * otherwise be told a name was dropped without being told whose it was.
+ */
+interface DiscardedComponent {
+    /** The contributing class, as {@link ResolvedContribution.label} names it. */
+    readonly contributor: string;
+    /** The component member, such as `schemas` or `parameters`. */
+    readonly member: string;
+    /** The entry's name within that member. */
+    readonly name: string;
+}
+
+/** 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;
+    /**
+     * Component entries a contributor offered that the served document already
+     * defined with a shape of its own. Present only when `mounted` is `true`;
+     * empty when every contribution was placed.
+     *
+     * The merge prefers whatever holds the name already, so a collision is not an
+     * error and does not stop the boot. The holder is usually the application's
+     * own declaration, but it may be a core schema this package contributes under
+     * `openapi.includeCoreSchemas` or an earlier contributor's entry — the report
+     * names what was dropped and by whom, not who owns the winning definition.
+     *
+     * It is reported because it is otherwise unobservable from either side: the
+     * contributing library cannot tell its entry was dropped, and the application
+     * cannot tell one was offered.
+     */
+    discarded?: readonly DiscardedComponent[];
+}
+/**
+ * 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.
+ *
+ * Testing this under Jest needs one flag. `@nestjs/swagger` is loaded through a
+ * dynamic `import()`, which is what keeps the peer optional for everyone who
+ * never enables the document — and Jest's module registry cannot service a
+ * dynamic import without `NODE_OPTIONS=--experimental-vm-modules`. Without it,
+ * only the *enabled* path fails, with `dynamic import callback invoked without
+ * --experimental-vm-modules`; the disabled and production paths never reach the
+ * loader and pass either way, which is what makes the omission confusing.
+ *
+ * @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, when the feature is
+ *   enabled and the optional peer `@nestjs/swagger` is not installed, or when
+ *   `openapi.operationSecurity` addresses an operation the generated document
+ *   does not contain.
+ * @example
+ *   const app = await NestFactory.create(AppModule)
+ *   await applyBymaxOpenApi(app)
+ *   await app.listen(3000)
+ */
+declare function applyBymaxOpenApi(app: INestApplication): Promise<OpenApiMountOutcome>;
+
+export { BYMAX_OPENAPI_CONTRACT_VERSION, BYMAX_OPENAPI_CONTRIBUTOR_METADATA, BymaxOpenApiContributor, type DiscardedComponent, type IOpenApiContributor, type OpenApiFragment, type OpenApiFragmentObject, type OpenApiHandlerKey, type OpenApiMountOutcome, type OpenApiSkipReason, applyBymaxOpenApi };