mark mergeExamples as @internal and add tests

Author: pullfrog[bot]

express-zod-api/src/json-schema-helpers.ts

@@ -79,7 +79,8 @@ export const processPropertyNames = (
   if (!isOptional) requiredKeys.push(...keys);
 };
 
-const mergeExamples = (
+/** @internal */
+export const mergeExamples = (
   flat: FlattenObjectSchema,
   entry: z.core.JSONSchema.BaseSchema,
   isOptional: boolean,

express-zod-api/tests/json-schema-helpers.spec.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import {
   flattenIO,
   isJsonObjectSchema,
+  mergeExamples,
   propsMerger,
   canMerge,
   nestOptional,
@@ -199,6 +200,55 @@ describe("JSON Schema helpers", () => {
     });
   });
 
+  describe("mergeExamples()", () => {
+    test("should do nothing when entry has no examples", () => {
+      const flat = { type: "object" as const, properties: {} };
+      mergeExamples(flat, { type: "string" }, false);
+      expect(flat).toEqual({ type: "object", properties: {} });
+    });
+
+    test("should concatenate examples when optional", () => {
+      const flat = {
+        type: "object" as const,
+        properties: {},
+        examples: [{ a: 1 }],
+      };
+      mergeExamples(flat, { examples: [{ b: 2 }, { c: 3 }] }, true);
+      expect(flat.examples).toEqual([{ a: 1 }, { b: 2 }, { c: 3 }]);
+    });
+
+    test("should initialize examples when optional and flat has none", () => {
+      const flat: { type: "object"; properties: {}; examples?: unknown[] } = {
+        type: "object",
+        properties: {},
+      };
+      mergeExamples(flat, { examples: [{ a: 1 }] }, true);
+      expect(flat.examples).toEqual([{ a: 1 }]);
+    });
+
+    test("should produce combinations when required", () => {
+      const flat = {
+        type: "object" as const,
+        properties: {},
+        examples: [{ a: 1 }],
+      };
+      mergeExamples(flat, { examples: [{ b: 2 }, { b: 3 }] }, false);
+      expect(flat.examples).toEqual([
+        { a: 1, b: 2 },
+        { a: 1, b: 3 },
+      ]);
+    });
+
+    test("should handle required with no prior examples", () => {
+      const flat: { type: "object"; properties: {}; examples?: unknown[] } = {
+        type: "object",
+        properties: {},
+      };
+      mergeExamples(flat, { examples: [{ a: 1 }] }, false);
+      expect(flat.examples).toEqual([{ a: 1 }]);
+    });
+  });
+
   describe("pullRequestExamples()", () => {
     test("should return empty array for empty properties", () => {
       expect(pullRequestExamples({ type: "object", properties: {} })).toEqual(