FEAT: add limit property to the combinations fn itself to avoid dragging maxCombinations through the call chain.

RobinTail · RobinTail · commit 47a02c291e43 · 2026-05-04T09:47:00.000+02:00
diff --git a/express-zod-api/src/common-helpers.ts b/express-zod-api/src/common-helpers.ts
@@ -110,22 +110,25 @@ export const isSchema = <T extends z.core.$ZodType = z.core.$ZodType>(
   (type ? R.path(["_zod", "def", "type"], subject) === type : true);
 
 /** Configurable replacement for R.xprod(), but it also handles empty arrays */
-export const combinations = <T>(
-  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 combinations = Object.assign(
+  <T>(
+    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 = combinations.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;
+  },
+  { limit: Infinity as number | undefined },
+);
 
 export const ucFirst = (subject: string) =>
   subject.charAt(0).toUpperCase() + subject.slice(1).toLowerCase();
diff --git a/express-zod-api/src/diagnostics.ts b/express-zod-api/src/diagnostics.ts
@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { responseVariants } from "./api-response";
-import { FlatObject, getRoutePathParams } from "./common-helpers";
+import { combinations, FlatObject, getRoutePathParams } from "./common-helpers";
 import { contentTypes } from "./content-type";
 import { findJsonIncompatible } from "./deep-checks";
 import { AbstractEndpoint } from "./endpoint";
@@ -46,8 +46,9 @@ export class Diagnostics {
         );
       }
     }
+    combinations.limit = 0; // no examples
     for (const variant of responseVariants) {
-      const responses = endpoint.getResponses(variant, { maxCombinations: 0 }); // no examples
+      const responses = endpoint.getResponses(variant);
       for (const { mimeTypes, schema } of responses) {
         if (!mimeTypes?.includes(contentTypes.json)) continue;
         const reason = findJsonIncompatible(schema, "output");
@@ -71,12 +72,12 @@ export class Diagnostics {
     if (ref.paths.has(path)) return;
     const params = getRoutePathParams(path);
     if (params.length === 0) return; // next statement can be expensive
+    combinations.limit = 0; // not required for this check
     ref.flat ??= flattenIO(
       z.toJSONSchema(endpoint.inputSchema, {
         unrepresentable: "any",
         io: "input",
       }),
-      { maxCombinations: 0 }, // not required for this check
     );
     for (const param of params) {
       if (param in ref.flat.properties) continue;
diff --git a/express-zod-api/src/documentation-helpers.ts b/express-zod-api/src/documentation-helpers.ts
@@ -55,7 +55,6 @@ interface ReqResCommons {
   ) => ReferenceObject;
   path: string;
   method: ClientMethod;
-  maxCombinations?: number;
 }
 
 export interface OpenAPIContext extends ReqResCommons {
@@ -127,9 +126,9 @@ export const depictUnion: Depicter = ({ zodSchema, jsonSchema }) => {
 };
 
 export const depictIntersection = R.tryCatch<Depicter>(
-  ({ jsonSchema }, { maxCombinations }) => {
+  ({ jsonSchema }) => {
     if (!jsonSchema.allOf) throw "no allOf";
-    return flattenIO(jsonSchema, { isStrict: true, maxCombinations });
+    return flattenIO(jsonSchema, { isStrict: true });
   },
   (_err, { jsonSchema }) => jsonSchema,
 );
@@ -283,7 +282,6 @@ export const depictRequestParams = ({
   composition,
   isHeader,
   securityHeaders,
-  maxCombinations,
   description = `${method.toUpperCase()} ${path} Parameter`,
 }: ReqResCommons & {
   composition: "inline" | "components";
@@ -293,7 +291,7 @@ export const depictRequestParams = ({
   isHeader?: IsHeader;
   securityHeaders?: Set<string>;
 }) => {
-  const flat = flattenIO(request, { maxCombinations });
+  const flat = flattenIO(request);
   const pathParams = getRoutePathParams(path);
   const isQueryEnabled = inputSources.includes("query");
   const areParamsEnabled = inputSources.includes("params");
@@ -456,7 +454,6 @@ export const depictResponse = ({
   hasMultipleStatusCodes,
   statusCode,
   brandHandling,
-  maxCombinations,
   description = `${method.toUpperCase()} ${path} ${ucFirst(variant)} response ${
     hasMultipleStatusCodes ? statusCode : ""
   }`.trim(),
@@ -474,7 +471,7 @@ export const depictResponse = ({
   const response = asOAS(
     depict(schema, {
       rules: { ...brandHandling, ...depicters },
-      ctx: { isResponse: true, makeRef, path, method, maxCombinations },
+      ctx: { isResponse: true, makeRef, path, method },
     }),
   );
   const examples = [];
@@ -590,14 +587,13 @@ export const depictRequest = ({
   makeRef,
   path,
   method,
-  maxCombinations,
 }: ReqResCommons & {
   schema: IOSchema;
   brandHandling?: BrandHandling;
 }) =>
   depict(schema, {
     rules: { ...brandHandling, ...depicters },
-    ctx: { isResponse: false, makeRef, path, method, maxCombinations },
+    ctx: { isResponse: false, makeRef, path, method },
   });
 
 export const depictBody = ({
@@ -609,7 +605,6 @@ export const depictBody = ({
   makeRef,
   composition,
   paramNames,
-  maxCombinations,
   description = `${method.toUpperCase()} ${path} Request body`,
 }: ReqResCommons & {
   schema: IOSchema;
@@ -636,7 +631,7 @@ export const depictBody = ({
     examples: enumerateExamples(
       examples.length
         ? examples
-        : flattenIO(request, { maxCombinations })
+        : flattenIO(request)
             .examples?.filter(
               (one): one is FlatObject => isObject(one) && !Array.isArray(one),
             )
diff --git a/express-zod-api/src/documentation.ts b/express-zod-api/src/documentation.ts
@@ -11,7 +11,7 @@ import * as R from "ramda";
 import { responseVariants } from "./api-response";
 import { contentTypes } from "./content-type";
 import { DocumentationError } from "./errors";
-import { getInputSources, makeCleanId } from "./common-helpers";
+import { getInputSources, combinations, makeCleanId } from "./common-helpers";
 import { CommonConfig } from "./config-type";
 import { getSecurityHeaders } from "./security";
 import { processContainers } from "./logical-container";
@@ -173,6 +173,7 @@ export class Documentation extends OpenApiBuilder {
     composition = "inline",
   }: DocumentationParams) {
     super();
+    combinations.limit = maxCombinations;
     this.addInfo({ title, version });
     for (const url of typeof serverUrl === "string" ? [serverUrl] : serverUrl)
       this.addServer({ url });
@@ -183,7 +184,6 @@ export class Documentation extends OpenApiBuilder {
         endpoint,
         composition,
         brandHandling,
-        maxCombinations,
         makeRef: this.#makeRef.bind(this),
       };
       const { description, shortDescription, scopes, inputSchema } = endpoint;
@@ -216,9 +216,7 @@ export class Documentation extends OpenApiBuilder {
 
       const responses: ResponsesObject = {};
       for (const variant of responseVariants) {
-        const apiResponses = endpoint.getResponses(variant, {
-          maxCombinations,
-        });
+        const apiResponses = endpoint.getResponses(variant);
         for (const { mimeTypes, schema, statusCodes } of apiResponses) {
           for (const statusCode of statusCodes) {
             responses[statusCode] = depictResponse({
@@ -256,10 +254,7 @@ export class Documentation extends OpenApiBuilder {
         : undefined;
 
       const securityRefs = depictSecurityRefs(
-        depictSecurity(
-          processContainers(endpoint.security, maxCombinations),
-          inputSources,
-        ),
+        depictSecurity(processContainers(endpoint.security), inputSources),
         scopes,
         (securitySchema) => {
           const name = this.#ensureUniqSecuritySchemaName(securitySchema);
diff --git a/express-zod-api/src/endpoint.ts b/express-zod-api/src/endpoint.ts
@@ -57,7 +57,6 @@ export abstract class AbstractEndpoint {
   /** @internal */
   public abstract getResponses(
     variant: ResponseVariant,
-    params: { maxCombinations?: number },
   ): ReadonlyArray<NormalizedResponse>;
   /** @internal */
   public abstract getOperationId(method: ClientMethod): string | undefined;
@@ -91,10 +90,10 @@ export class Endpoint<
   readonly #def: ConstructorParameters<typeof Endpoint<IN, OUT, CTX>>[0];
 
   /** considered expensive operation, only required for generators */
-  #ensureOutputExamples(limit?: number) {
+  #ensureOutputExamples() {
     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, limit);
+    const examples = pullResponseExamples(this.#def.outputSchema);
     if (!examples.length) return;
     const current = this.#def.outputSchema.meta();
     globalRegistry
@@ -173,11 +172,8 @@ export class Endpoint<
   }
 
   /** @internal */
-  public override getResponses(
-    variant: ResponseVariant,
-    { maxCombinations }: { maxCombinations?: number },
-  ) {
-    if (variant === "positive") this.#ensureOutputExamples(maxCombinations);
+  public override getResponses(variant: ResponseVariant) {
+    if (variant === "positive") this.#ensureOutputExamples();
     return Object.freeze(
       variant === "negative"
         ? this.#def.resultHandler.getNegativeResponse()
diff --git a/express-zod-api/src/integration.ts b/express-zod-api/src/integration.ts
@@ -3,7 +3,7 @@ import type ts from "typescript";
 import { z } from "zod";
 import { ResponseVariant, responseVariants } from "./api-response";
 import { IntegrationBase } from "./integration-base";
-import { shouldHaveContent, makeCleanId } from "./common-helpers";
+import { combinations, shouldHaveContent, makeCleanId } from "./common-helpers";
 import { loadPeer } from "./peer-helpers";
 import { Routing } from "./routing";
 import { OnEndpoint, walkRouting, withHead } from "./routing-walker";
@@ -92,6 +92,7 @@ export class Integration extends IntegrationBase {
     hasHeadMethod = true,
   }: IntegrationParams) {
     super(typescript, serverUrl);
+    combinations.limit = 0; // not using examples yet
     const commons = { makeAlias: this.#makeAlias.bind(this), api: this.api };
     const ctxIn = { brandHandling, ctx: { ...commons, isResponse: false } };
     const ctxOut = { brandHandling, ctx: { ...commons, isResponse: true } };
@@ -107,9 +108,7 @@ export class Integration extends IntegrationBase {
       this.#program.push(input);
       const dictionaries = responseVariants.reduce(
         (agg, responseVariant) => {
-          const responses = endpoint.getResponses(responseVariant, {
-            maxCombinations: 0, // not using examples yet
-          });
+          const responses = endpoint.getResponses(responseVariant);
           const props = R.chain(([idx, { schema, mimeTypes, statusCodes }]) => {
             const hasContent = shouldHaveContent(method, mimeTypes);
             const variantType = this.api.makeType(
diff --git a/express-zod-api/src/json-schema-helpers.ts b/express-zod-api/src/json-schema-helpers.ts
@@ -84,10 +84,7 @@ export const processPropertyNames = (
 export const mergeExamples = (
   target: FlattenObjectSchema,
   entry: z.core.JSONSchema.BaseSchema,
-  {
-    isOptional,
-    maxCombinations,
-  }: { isOptional: boolean; maxCombinations?: number },
+  { isOptional }: { isOptional: boolean },
 ) => {
   if (!entry.examples?.length) return;
   if (isOptional) {
@@ -97,7 +94,6 @@ export const mergeExamples = (
       target.examples?.filter(isObject) || [],
       entry.examples.filter(isObject),
       R.mergeDeepRight,
-      maxCombinations,
     );
   }
 };
@@ -106,11 +102,9 @@ export const flattenIO = (
   jsonSchema: z.core.JSONSchema.BaseSchema,
   {
     isStrict = false,
-    maxCombinations,
   }: {
     /** @default false */
     isStrict?: boolean;
-    maxCombinations?: number;
   } = {},
 ) => {
   const stack: Stack = [R.pair(false, jsonSchema)]; // [isOptional, JSON Schema]
@@ -121,12 +115,9 @@ export const flattenIO = (
     if (entry.description) flat.description ??= entry.description;
     stack.push(...processAllOf(entry, { isStrict, isOptional }));
     stack.push(...processVariants(entry));
-    mergeExamples(flat, entry, { isOptional, maxCombinations });
+    mergeExamples(flat, entry, { isOptional });
     if (!isJsonObjectSchema(entry)) continue;
-    stack.push([
-      isOptional,
-      { examples: pullRequestExamples(entry, maxCombinations) },
-    ]);
+    stack.push([isOptional, { examples: pullRequestExamples(entry) }]);
     if (entry.properties) {
       flat.properties = (isStrict ? propsMerger : R.mergeDeepRight)(
         flat.properties,
@@ -141,14 +132,11 @@ export const flattenIO = (
 };
 
 /** @see pullResponseExamples */
-export const pullRequestExamples = (
-  subject: z.core.JSONSchema.ObjectSchema,
-  limit?: number,
-) =>
+export const pullRequestExamples = (subject: z.core.JSONSchema.ObjectSchema) =>
   Object.entries(subject.properties || {}).reduce<FlatObject[]>(
     (acc, [key, prop]) => {
       const { examples = [] } = isObject(prop) ? prop : {};
-      return combinations(acc, examples.map(R.objOf(key)), R.mergeRight, limit);
+      return combinations(acc, examples.map(R.objOf(key)), R.mergeRight);
     },
     [],
   );
diff --git a/express-zod-api/src/logical-container.ts b/express-zod-api/src/logical-container.ts
@@ -27,7 +27,6 @@ export type Alternatives<T> = Array<Combination<T>>;
 
 export const processContainers = <T>(
   containers: LogicalContainer<T>[],
-  maxCombinations?: number,
 ): Alternatives<T> => {
   const simples = R.filter(isSimple, containers);
   const ands = R.chain(R.prop("and"), R.filter(isLogicalAnd, containers));
@@ -41,7 +40,6 @@ export const processContainers = <T>(
         acc,
         R.map((opt) => (isSimple(opt) ? [opt] : opt.and), entry),
         R.concat,
-        maxCombinations,
       ),
     R.reject(R.isEmpty, [persistent]),
   );
diff --git a/express-zod-api/src/result-helpers.ts b/express-zod-api/src/result-helpers.ts
@@ -88,14 +88,11 @@ export const getPublicErrorMessage = (error: HttpError): string =>
     : error.message;
 
 /** @see pullRequestExamples */
-export const pullResponseExamples = <T extends z.core.$ZodObject>(
-  subject: T,
-  limit?: number,
-) =>
+export const pullResponseExamples = <T extends z.core.$ZodObject>(subject: T) =>
   Object.entries(subject._zod.def.shape).reduce<FlatObject[]>(
     (acc, [key, schema]) => {
       const { examples = [] } = globalRegistry.get(schema) || {};
-      return combinations(acc, examples.map(R.objOf(key)), R.mergeRight, limit);
+      return combinations(acc, examples.map(R.objOf(key)), R.mergeRight);
     },
     [],
   );
diff --git a/express-zod-api/tests/common-helpers.spec.ts b/express-zod-api/tests/common-helpers.spec.ts
@@ -291,6 +291,11 @@ describe("Common Helpers", () => {
       expect(combinations([1, 2], [4, 5, 6], (a, b) => a + b, 4)).toEqual([
         5, 6, 7, 6,
       ]);
+      combinations.limit = 3;
+      expect(combinations([1, 2], [4, 5, 6], (a, b) => a + b)).toEqual([
+        5, 6, 7,
+      ]);
+      combinations.limit = Infinity;
     });
 
     test.each([0, -1, NaN])("should return empty for limit=%s", (limit) => {
diff --git a/express-zod-api/tests/endpoint.spec.ts b/express-zod-api/tests/endpoint.spec.ts
@@ -282,9 +282,7 @@ describe("Endpoint", () => {
           output: z.object({ something: z.number() }),
           handler: vi.fn(),
         });
-        const responses = endpoint.getResponses(variant, {
-          maxCombinations: 0,
-        });
+        const responses = endpoint.getResponses(variant);
         expect(responses).toMatchSnapshot();
         expect(() => (responses as any[]).push()).toThrowError(/read only/);
       },
diff --git a/express-zod-api/tests/json-schema-helpers.spec.ts b/express-zod-api/tests/json-schema-helpers.spec.ts
diff --git a/express-zod-api/tests/logical-container.spec.ts b/express-zod-api/tests/logical-container.spec.ts
diff --git a/express-zod-api/tests/result-helpers.spec.ts b/express-zod-api/tests/result-helpers.spec.ts
