feat: Ability to limit combinations

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Version 27
 
+### v27.4.0
+
+- Introduced `maxCombinations` setting for Documentation generator:
+  - Limits cartesian product when generating examples by combining each property's own examples;
+  - Set to `0` to disable product but keep concatenations;
+  - Default is `Infinity`, but may change to reasonable number in v28 to avoid too many combinations;
+  - Example: 6 props with 2 examples each → cartesian product makes 2^6 = 64 request examples:
+
+```ts
+const schema = z.object({
+  id: z.number().example(1).example(2),
+  name: z.string().example("john").example("jane"),
+  age: z.number().example(18).example(21),
+  role: z.enum(["user", "admin"]).example("user").example("admin"),
+  active: z.boolean().example(true).example(false),
+  tags: z.array(z.string()).example(["vip"]).example(["new", "promo"]),
+});
+// First 5:
+// { id: 1, name: "john", age: 18, role: "user", active: true, tags: ["vip"] },
+// { id: 1, name: "john", age: 18, role: "user", active: true, tags: ["new", "promo"] },
+// { id: 1, name: "john", age: 18, role: "user", active: false, tags: ["vip"] },
+// { id: 1, name: "john", age: 18, role: "user", active: false, tags: ["new", "promo"] },
+// { id: 1, name: "john", age: 18, role: "admin", active: true, tags: ["vip"] },
+// ...and 59 more
+```
+
 ### v27.3.0
 
 - Supporting Node 26.

express-zod-api/src/common-helpers.ts

@@ -109,11 +109,23 @@ export const isSchema = <T extends z.core.$ZodType = z.core.$ZodType>(
   "_zod" in subject &&
   (type ? R.path(["_zod", "def", "type"], subject) === type : true);
 
+/** Configurable replacement for R.xprod(), but it also handles empty arrays */
 export const combinations = <T>(
-  a: T[],
-  b: T[],
-  merge: (pair: [T, T]) => T,
-): T[] => (a.length && b.length ? R.xprod(a, b).map(merge) : a.concat(b));
+  left: T[],
+  right: T[],
+  /** @desc The function that combines elements */
+  merge: (a: T, b: T) => T,
+  /** @desc Maximum number of combinations (only applies to Cartesian product of non-empty arrays) */
+  limit = Infinity,
+): T[] => {
+  if (!left.length || !right.length) return left.concat(right);
+  const result: T[] = [];
+  for (let idxL = 0; idxL < left.length && result.length < limit; idxL++) {
+    for (let idxR = 0; idxR < right.length && result.length < limit; idxR++)
+      result.push(merge(left[idxL], right[idxR]));
+  }
+  return result;
+};
 
 export const ucFirst = (subject: string) =>
   subject.charAt(0).toUpperCase() + subject.slice(1).toLowerCase();

express-zod-api/src/diagnostics.ts

@@ -47,7 +47,8 @@ export class Diagnostics {
       }
     }
     for (const variant of responseVariants) {
-      for (const { mimeTypes, schema } of endpoint.getResponses(variant)) {
+      const responses = endpoint.getResponses(variant, { maxCombinations: 0 }); // no examples
+      for (const { mimeTypes, schema } of responses) {
         if (!mimeTypes?.includes(contentTypes.json)) continue;
         const reason = findJsonIncompatible(schema, "output");
         if (reason) {
@@ -75,6 +76,7 @@ export class Diagnostics {
         unrepresentable: "any",
         io: "input",
       }),
+      { maxCombinations: 0 }, // not required for this check
     );
     for (const param of params) {
       if (param in ref.flat.properties) continue;

express-zod-api/src/documentation-helpers.ts

@@ -55,6 +55,7 @@ interface ReqResCommons {
   ) => ReferenceObject;
   path: string;
   method: ClientMethod;
+  maxCombinations?: number;
 }
 
 export interface OpenAPIContext extends ReqResCommons {
@@ -126,9 +127,9 @@ export const depictUnion: Depicter = ({ zodSchema, jsonSchema }) => {
 };
 
 export const depictIntersection = R.tryCatch<Depicter>(
-  ({ jsonSchema }) => {
+  ({ jsonSchema }, { maxCombinations }) => {
     if (!jsonSchema.allOf) throw "no allOf";
-    return flattenIO(jsonSchema, "throw");
+    return flattenIO(jsonSchema, { isStrict: true, maxCombinations });
   },
   (_err, { jsonSchema }) => jsonSchema,
 );
@@ -267,9 +268,9 @@ const enumerateExamples = (examples: unknown[]): ExamplesObject | undefined =>
 
 export const defaultIsHeader = (
   name: string,
-  familiar?: string[],
+  familiar?: Set<string>,
 ): name is `x-${string}` =>
-  familiar?.includes(name) ||
+  familiar?.has(name) ||
   name.startsWith("x-") ||
   getWellKnownHeaders().has(name);
 
@@ -281,25 +282,22 @@ export const depictRequestParams = ({
   makeRef,
   composition,
   isHeader,
-  security,
+  securityHeaders,
+  maxCombinations,
   description = `${method.toUpperCase()} ${path} Parameter`,
 }: ReqResCommons & {
   composition: "inline" | "components";
   description?: string;
   request: z.core.JSONSchema.BaseSchema;
   inputSources: InputSource[];
   isHeader?: IsHeader;
-  security?: Alternatives<Security>;
+  securityHeaders?: Set<string>;
 }) => {
-  const flat = flattenIO(request);
+  const flat = flattenIO(request, { maxCombinations });
   const pathParams = getRoutePathParams(path);
   const isQueryEnabled = inputSources.includes("query");
   const areParamsEnabled = inputSources.includes("params");
   const areHeadersEnabled = inputSources.includes("headers");
-  const securityHeaders = R.chain(
-    R.filter((entry: Security) => entry.type === "header"),
-    security ?? [],
-  ).map(({ name }) => name);
 
   const getLocation = (name: string) => {
     if (areParamsEnabled && pathParams.includes(name)) return "path";
@@ -458,6 +456,7 @@ export const depictResponse = ({
   hasMultipleStatusCodes,
   statusCode,
   brandHandling,
+  maxCombinations,
   description = `${method.toUpperCase()} ${path} ${ucFirst(variant)} response ${
     hasMultipleStatusCodes ? statusCode : ""
   }`.trim(),
@@ -475,7 +474,7 @@ export const depictResponse = ({
   const response = asOAS(
     depict(schema, {
       rules: { ...brandHandling, ...depicters },
-      ctx: { isResponse: true, makeRef, path, method },
+      ctx: { isResponse: true, makeRef, path, method, maxCombinations },
     }),
   );
   const examples = [];
@@ -591,13 +590,14 @@ export const depictRequest = ({
   makeRef,
   path,
   method,
+  maxCombinations,
 }: ReqResCommons & {
   schema: IOSchema;
   brandHandling?: BrandHandling;
 }) =>
   depict(schema, {
     rules: { ...brandHandling, ...depicters },
-    ctx: { isResponse: false, makeRef, path, method },
+    ctx: { isResponse: false, makeRef, path, method, maxCombinations },
   });
 
 export const depictBody = ({
@@ -609,6 +609,7 @@ export const depictBody = ({
   makeRef,
   composition,
   paramNames,
+  maxCombinations,
   description = `${method.toUpperCase()} ${path} Request body`,
 }: ReqResCommons & {
   schema: IOSchema;
@@ -635,7 +636,7 @@ export const depictBody = ({
     examples: enumerateExamples(
       examples.length
         ? examples
-        : flattenIO(request)
+        : flattenIO(request, { maxCombinations })
             .examples?.filter(
               (one): one is FlatObject => isObject(one) && !Array.isArray(one),
             )

express-zod-api/src/documentation.ts

@@ -13,6 +13,7 @@ import { contentTypes } from "./content-type";
 import { DocumentationError } from "./errors";
 import { getInputSources, makeCleanId } from "./common-helpers";
 import { CommonConfig } from "./config-type";
+import { getSecurityHeaders } from "./security";
 import { processContainers } from "./logical-container";
 import { ClientMethod } from "./method";
 import {
@@ -86,6 +87,14 @@ interface DocumentationParams {
    * @example { users: "About users", files: { description: "About files", url: "https://example.com" } }
    * */
   tags?: Parameters<typeof depictTags>[0];
+  /**
+   * @desc Limits cartesian product when generating examples by combining each property's own examples.
+   * @desc Applies to: request/response examples, security scheme alternatives.
+   * @example 0 — disables product combinations, keeps concatenations
+   * @default Infinity
+   * @todo set to 10 or 20 in v28 to avoid too many combinations
+   * */
+  maxCombinations?: number;
 }
 
 export class Documentation extends OpenApiBuilder {
@@ -158,6 +167,7 @@ export class Documentation extends OpenApiBuilder {
     brandHandling,
     tags,
     isHeader,
+    maxCombinations,
     hasSummaryFromDescription = true,
     hasHeadMethod = true,
     composition = "inline",
@@ -173,6 +183,7 @@ export class Documentation extends OpenApiBuilder {
         endpoint,
         composition,
         brandHandling,
+        maxCombinations,
         makeRef: this.#makeRef.bind(this),
       };
       const { description, shortDescription, scopes, inputSchema } = endpoint;
@@ -189,12 +200,12 @@ export class Documentation extends OpenApiBuilder {
       );
 
       const request = depictRequest({ ...commons, schema: inputSchema });
-      const security = processContainers(endpoint.security);
+      const securityHeaders = getSecurityHeaders(endpoint.security);
       const depictedParams = depictRequestParams({
         ...commons,
         inputSources,
         isHeader,
-        security,
+        securityHeaders,
         request,
         description: descriptions?.requestParameter?.call(null, {
           method,
@@ -205,7 +216,9 @@ export class Documentation extends OpenApiBuilder {
 
       const responses: ResponsesObject = {};
       for (const variant of responseVariants) {
-        const apiResponses = endpoint.getResponses(variant);
+        const apiResponses = endpoint.getResponses(variant, {
+          maxCombinations,
+        });
         for (const { mimeTypes, schema, statusCodes } of apiResponses) {
           for (const statusCode of statusCodes) {
             responses[statusCode] = depictResponse({
@@ -243,7 +256,10 @@ export class Documentation extends OpenApiBuilder {
         : undefined;
 
       const securityRefs = depictSecurityRefs(
-        depictSecurity(security, inputSources),
+        depictSecurity(
+          processContainers(endpoint.security, maxCombinations),
+          inputSources,
+        ),
         scopes,
         (securitySchema) => {
           const name = this.#ensureUniqSecuritySchemaName(securitySchema);

express-zod-api/src/endpoint.ts

@@ -57,6 +57,7 @@ export abstract class AbstractEndpoint {
   /** @internal */
   public abstract getResponses(
     variant: ResponseVariant,
+    params: { maxCombinations?: number },
   ): ReadonlyArray<NormalizedResponse>;
   /** @internal */
   public abstract getOperationId(method: ClientMethod): string | undefined;
@@ -90,16 +91,16 @@ export class Endpoint<
   readonly #def: ConstructorParameters<typeof Endpoint<IN, OUT, CTX>>[0];
 
   /** considered expensive operation, only required for generators */
-  #ensureOutputExamples = R.once(() => {
+  #ensureOutputExamples(limit?: number) {
     if (globalRegistry.get(this.#def.outputSchema)?.examples?.length) return; // examples on output schema, or pull up:
     if (!isSchema<z.core.$ZodObject>(this.#def.outputSchema, "object")) return;
-    const examples = pullResponseExamples(this.#def.outputSchema);
+    const examples = pullResponseExamples(this.#def.outputSchema, limit);
     if (!examples.length) return;
     const current = this.#def.outputSchema.meta();
     globalRegistry
       .remove(this.#def.outputSchema) // reassign to avoid cloning
       .add(this.#def.outputSchema, { ...current, examples });
-  });
+  }
 
   constructor(def: {
     deprecated?: boolean;
@@ -172,8 +173,11 @@ export class Endpoint<
   }
 
   /** @internal */
-  public override getResponses(variant: ResponseVariant) {
-    if (variant === "positive") this.#ensureOutputExamples();
+  public override getResponses(
+    variant: ResponseVariant,
+    { maxCombinations }: { maxCombinations?: number },
+  ) {
+    if (variant === "positive") this.#ensureOutputExamples(maxCombinations);
     return Object.freeze(
       variant === "negative"
         ? this.#def.resultHandler.getNegativeResponse()

express-zod-api/src/integration.ts

@@ -107,7 +107,9 @@ export class Integration extends IntegrationBase {
       this.#program.push(input);
       const dictionaries = responseVariants.reduce(
         (agg, responseVariant) => {
-          const responses = endpoint.getResponses(responseVariant);
+          const responses = endpoint.getResponses(responseVariant, {
+            maxCombinations: 0, // not using examples yet
+          });
           const props = R.chain(([idx, { schema, mimeTypes, statusCodes }]) => {
             const hasContent = shouldHaveContent(method, mimeTypes);
             const variantType = this.api.makeType(