@techspokes/typescript-wsdl-client 0.24.0 → 0.26.0

package/dist/gateway/generators.js

@@ -418,6 +418,10 @@ const ARRAY_WRAPPERS: Record<string, string> = ${JSON.stringify(arrayWrappers, n
  */
 const CHILDREN_TYPES: Record<string, Record<string, string>> = ${JSON.stringify(childTypes, null, 2)};
 
+function isSafeObjectKey(key: string): boolean {
+  return key !== "__proto__" && key !== "constructor" && key !== "prototype";
+}
+
 /**
  * Recursively unwraps ArrayOf* wrapper objects in a SOAP response so the
  * data matches the flattened OpenAPI array schemas.
@@ -447,14 +451,14 @@ export function unwrapArrayWrappers(data: unknown, typeName: string): unknown {
   // Recurse into children whose types may contain wrappers
   if (typeName in CHILDREN_TYPES) {
     const children = CHILDREN_TYPES[typeName];
+    const record = data as Record<string, unknown>;
     for (const [propName, propType] of Object.entries(children)) {
-      const val = (data as Record<string, unknown>)[propName];
-      if (val !== undefined) {
-        if (Array.isArray(val)) {
-          (data as Record<string, unknown>)[propName] = val.map(item => unwrapArrayWrappers(item, propType));
-        } else {
-          (data as Record<string, unknown>)[propName] = unwrapArrayWrappers(val, propType);
-        }
+      if (!isSafeObjectKey(propName) || !Object.hasOwn(record, propName)) continue;
+      const val = record[propName];
+      if (Array.isArray(val)) {
+        record[propName] = val.map(item => unwrapArrayWrappers(item, propType));
+      } else {
+        record[propName] = unwrapArrayWrappers(val, propType);
       }
     }
   }

package/dist/openapi/generateSchemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateSchemas.d.ts","sourceRoot":"","sources":["../../src/openapi/generateSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAgB,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAwKpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CAoD1G"}
+{"version":3,"file":"generateSchemas.d.ts","sourceRoot":"","sources":["../../src/openapi/generateSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAgB,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAkNpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,sBAAsB,GAAG,iBAAiB,CA2D1G"}

package/dist/openapi/generateSchemas.js

@@ -67,7 +67,7 @@ function isSyntheticAliasSelfWrapper(t, aliasNames) {
     const e = t.elems[0];
     return e.name === "$value" && e.tsType === t.name;
 }
-function buildComplexSchema(t, closed, knownTypeNames, aliasNames, flattenWrappers) {
+function buildComplexSchema(t, closed, knownTypeNames, aliasNames, flattenWrappers, choiceUnionMode) {
     // Use knownTypeNames/aliasNames to validate $ref targets so we surface
     // compiler issues early instead of emitting dangling references in OpenAPI output.
     function refOrPrimitive(ts) {
@@ -108,6 +108,8 @@ function buildComplexSchema(t, closed, knownTypeNames, aliasNames, flattenWrappe
     }
     const properties = {};
     const required = [];
+    const choiceGroups = choiceUnionMode ? (t.choiceGroups ?? []) : [];
+    const choiceElementNames = new Set(choiceGroups.flatMap((group) => group.branches.map((branch) => branch.name)));
     // attributes
     for (const a of t.attrs) {
         const propSchema = refOrPrimitive(a.tsType);
@@ -135,7 +137,7 @@ function buildComplexSchema(t, closed, knownTypeNames, aliasNames, flattenWrappe
         if (e.name === "$value") {
             // never required
         }
-        else if (e.min >= 1) {
+        else if (e.min >= 1 && !choiceElementNames.has(e.name)) {
             required.push(e.name);
         }
     }
@@ -147,6 +149,40 @@ function buildComplexSchema(t, closed, knownTypeNames, aliasNames, flattenWrappe
         obj.required = Array.from(new Set(required));
     if (closed)
         obj.additionalProperties = false;
+    const choiceConstraints = choiceGroups
+        .map((group) => {
+        const branchNames = group.branches.map((branch) => branch.name);
+        const presenceSchema = (names) => {
+            if (names.length === 0)
+                return undefined;
+            if (names.length === 1)
+                return { required: [names[0]] };
+            return { anyOf: names.map((name) => ({ required: [name] })) };
+        };
+        const oneOf = group.branches.map((branch) => {
+            const peers = branchNames.filter((name) => name !== branch.name);
+            const schema = { required: [branch.name] };
+            const forbiddenPeers = presenceSchema(peers);
+            if (forbiddenPeers) {
+                schema.not = forbiddenPeers;
+            }
+            return schema;
+        });
+        if (group.min === 0) {
+            const anyBranch = presenceSchema(branchNames);
+            if (anyBranch) {
+                oneOf.push({ not: anyBranch });
+            }
+        }
+        return oneOf.length > 0 ? { oneOf } : undefined;
+    })
+        .filter((schema) => !!schema);
+    if (choiceConstraints.length === 1) {
+        obj.oneOf = choiceConstraints[0].oneOf;
+    }
+    else if (choiceConstraints.length > 1) {
+        obj.allOf = choiceConstraints;
+    }
     // inheritance via base => allOf
     if (t.base) {
         const baseName = t.base;
@@ -194,7 +230,7 @@ export function generateSchemas(compiled, opts) {
         if (isSyntheticAliasSelfWrapper(t, aliasNames)) {
             continue;
         }
-        schemas[t.name] = buildComplexSchema(t, closed, typeNames, aliasNames, flattenWrappers);
+        schemas[t.name] = buildComplexSchema(t, closed, typeNames, aliasNames, flattenWrappers, compiled.options.choice === "union");
     }
     if (opts.pruneUnusedSchemas) {
         // Root references: operation type names when available, falling back to element local names.

package/dist/test/generateTests.js

@@ -127,7 +127,7 @@ export async function generateTests(opts) {
     // Emit gateway/envelope.test.ts
     writeTestFile(path.join(testDir, "gateway", "envelope.test.ts"), emitEnvelopeTest(testDir, importsMode, operations, mocks), force);
     // Emit gateway/validation.test.ts
-    writeTestFile(path.join(testDir, "gateway", "validation.test.ts"), emitValidationTest(testDir, importsMode, operations), force);
+    writeTestFile(path.join(testDir, "gateway", "validation.test.ts"), emitValidationTest(testDir, importsMode, operations, mocks, catalog), force);
     // Emit runtime/classify-error.test.ts
     writeTestFile(path.join(testDir, "runtime", "classify-error.test.ts"), emitClassifyErrorTest(testDir, gatewayDir, importsMode), force);
     // Emit runtime/envelope-builders.test.ts

package/dist/test/generators.d.ts

@@ -1,5 +1,5 @@
 import type { ClientMeta, ResolvedOperationMeta } from "../gateway/helpers.js";
-import type { CatalogForMocks } from "./mockData.js";
+import { type CatalogForMocks } from "./mockData.js";
 /** Pre-computed mock data map passed from the orchestrator to all emitters. */
 export type OperationMocksMap = Map<string, {
     request: unknown;
@@ -57,7 +57,7 @@ export declare function emitEnvelopeTest(testDir: string, importsMode: "js" | "t
 /**
  * Emits gateway/validation.test.ts with invalid payload tests per route.
  */
-export declare function emitValidationTest(testDir: string, importsMode: "js" | "ts" | "bare", operations: ResolvedOperationMeta[]): string;
+export declare function emitValidationTest(testDir: string, importsMode: "js" | "ts" | "bare", operations: ResolvedOperationMeta[], mocks?: OperationMocksMap, catalog?: CatalogForMocks): string;
 /**
  * Emits runtime/classify-error.test.ts with direct classifyError() unit tests.
  */

package/dist/test/generators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/test/generators.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,eAAe,CAAC;AAGnD,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAerF;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAkBzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAgFR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,GACrB,MAAM,CAsCR;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAuER;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAiIR;AAED;;GAEG;AAEH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAuER;AAED;;GAEG;AAEH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,GAClC,MAAM,CAoCR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgFR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgDR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,OAAO,EAAE,eAAe,GACvB,MAAM,GAAG,IAAI,CAkEf"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/test/generators.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EAA0C,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAG5F,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AA6FrF;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAkBzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAgFR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,GACrB,MAAM,CAsCR;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAuER;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAiIR;AAED;;GAEG;AAEH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAuER;AAED;;GAEG;AAEH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,CAAC,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,MAAM,CAwDR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgFR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgDR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,OAAO,EAAE,eAAe,GACvB,MAAM,GAAG,IAAI,CAkEf"}

package/dist/test/generators.js

@@ -9,6 +9,7 @@
  * via computeRelativeImport() from src/util/imports.ts.
  */
 import { computeRelativeImport } from "../util/imports.js";
+import { generateMockData, generateMockPrimitive } from "./mockData.js";
 import { detectArrayWrappers, detectChildrenTypes } from "../util/catalogMeta.js";
 function formatOperationHint(summary, description) {
     const source = summary || description;
@@ -22,6 +23,66 @@ function formatOperationHint(summary, description) {
         .trim();
     return normalized || undefined;
 }
+function isRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function cloneRecord(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function mockChoiceBranchValue(branch, catalog) {
+    const isArray = branch.max === "unbounded" || (typeof branch.max === "number" && branch.max > 1);
+    const value = branch.tsType === "string" || branch.tsType === "number" || branch.tsType === "boolean"
+        ? generateMockPrimitive(branch.tsType, branch.name)
+        : generateMockData(branch.tsType, catalog);
+    return isArray ? [value] : value;
+}
+function buildInvalidChoicePayloads(op, mocks, catalog) {
+    if (catalog?.options?.choice !== "union" || !op.requestTypeName) {
+        return [];
+    }
+    const typeMeta = catalog.types?.find((type) => type.name === op.requestTypeName);
+    const groups = typeMeta?.choiceGroups ?? [];
+    if (groups.length === 0) {
+        return [];
+    }
+    const basePayload = mocks?.get(op.operationId)?.request;
+    if (!isRecord(basePayload)) {
+        return [];
+    }
+    const invalidPayloads = [];
+    for (const group of groups) {
+        if (group.branches.length < 2) {
+            continue;
+        }
+        const selectedBranch = group.branches.find((branch) => Object.hasOwn(basePayload, branch.name)) ?? group.branches[0];
+        const peerBranch = group.branches.find((branch) => branch.name !== selectedBranch.name);
+        if (!peerBranch) {
+            continue;
+        }
+        const payload = cloneRecord(basePayload);
+        if (!Object.hasOwn(payload, selectedBranch.name)) {
+            payload[selectedBranch.name] = mockChoiceBranchValue(selectedBranch, catalog);
+        }
+        payload[peerBranch.name] = mockChoiceBranchValue(peerBranch, catalog);
+        invalidPayloads.push({
+            kind: "invalid",
+            typeName: op.requestTypeName,
+            payload,
+        });
+        if (group.min >= 1) {
+            const missingPayload = cloneRecord(basePayload);
+            for (const branch of group.branches) {
+                delete missingPayload[branch.name];
+            }
+            invalidPayloads.push({
+                kind: "missing",
+                typeName: op.requestTypeName,
+                payload: missingPayload,
+            });
+        }
+    }
+    return invalidPayloads;
+}
 /**
  * Emits vitest.config.ts content.
  *
@@ -467,11 +528,11 @@ describe("gateway — envelope structure", () => {
  * Emits gateway/validation.test.ts with invalid payload tests per route.
  */
 // noinspection JSUnusedLocalSymbols
-export function emitValidationTest(testDir, importsMode, operations) {
+export function emitValidationTest(testDir, importsMode, operations, mocks, catalog) {
     const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
     const testAppImport = `../helpers/test-app${suffix}`;
     const sortedOps = [...operations].sort((a, b) => a.operationId.localeCompare(b.operationId));
-    const testCases = sortedOps.map((op) => {
+    const arrayBodyCases = sortedOps.map((op) => {
         return `  it("${op.method.toUpperCase()} ${op.path} rejects array body", async () => {
     const app = await createTestApp();
     try {
@@ -485,7 +546,27 @@ export function emitValidationTest(testDir, importsMode, operations) {
       await app.close();
     }
   });`;
-    }).join("\n\n");
+    });
+    const choiceCases = sortedOps.flatMap((op) => {
+        return buildInvalidChoicePayloads(op, mocks, catalog).map((invalid) => {
+            const payload = JSON.stringify(invalid.payload, null, 4).replace(/\n/g, "\n    ");
+            const title = `${invalid.kind} ${invalid.typeName} choice payload`;
+            return `  it("${op.method.toUpperCase()} ${op.path} rejects ${title}", async () => {
+    const app = await createTestApp();
+    try {
+      const res = await app.inject({
+        method: "${op.method.toUpperCase()}",
+        url: "${op.path}",
+        payload: ${payload},
+      });
+      expect(res.statusCode).toBe(400);
+    } finally {
+      await app.close();
+    }
+  });`;
+        });
+    });
+    const testCases = [...arrayBodyCases, ...choiceCases].join("\n\n");
     return `/**
  * Gateway Validation Tests
  *

package/dist/test/mockData.d.ts

@@ -8,6 +8,9 @@ export interface MockDataOptions {
  * Compiled catalog structure (minimal interface for mock data generation)
  */
 export interface CatalogForMocks {
+    options?: {
+        choice?: "all-optional" | "union";
+    };
     meta?: {
         attrType?: Record<string, Record<string, string>>;
         childType?: Record<string, Record<string, string>>;
@@ -38,6 +41,22 @@ export interface CatalogForMocks {
             name: string;
             max: number | "unbounded";
         }>;
+        choiceGroups?: Array<{
+            name: string;
+            min: number;
+            max: number | "unbounded";
+            sourceOrder: number;
+            branches: Array<{
+                name: string;
+                tsType: string;
+                min: number;
+                max: number | "unbounded";
+                nillable?: boolean;
+                declaredType: string;
+                doc?: string;
+                sourceOrder: number;
+            }>;
+        }>;
     }>;
     aliases?: Array<{
         name: string;

package/dist/test/mockData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mockData.d.ts","sourceRoot":"","sources":["../../src/test/mockData.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAClD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACnD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;YACvC,YAAY,CAAC,EAAE,MAAM,CAAC;YACtB,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;YAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;SACpB,CAAC,CAAC,CAAC;KACL,CAAC;IACF,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE;YACP,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC;YAChC,SAAS,EAAE,MAAM,CAAC;YAClB,cAAc,EAAE,MAAM,CAAC;YACvB,UAAU,EAAE,MAAM,EAAE,CAAC;SACtB,CAAC;KACH,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC/B,KAAK,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;SAAE,CAAC,CAAC;KAC3D,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;CACJ;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAwCjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE,eAAe,EACtB,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EACrB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoDzB;AAWD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE,uBAAuB,GAC7B,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CA+BtD"}
+{"version":3,"file":"mockData.d.ts","sourceRoot":"","sources":["../../src/test/mockData.ts"],"names":[],"mappings":"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"}

package/dist/test/mockData.js

@@ -100,7 +100,16 @@ export function generateMockData(typeName, catalog, opts, visited, depth) {
     const newVisited = new Set(currentVisited);
     newVisited.add(typeName);
     const result = {};
+    const typeMeta = catalog.types?.find((t) => t.name === typeName);
+    const choiceGroups = catalog.options?.choice === "union" ? (typeMeta?.choiceGroups ?? []) : [];
+    const choiceBranchNames = new Set(choiceGroups.flatMap((group) => group.branches.map((branch) => branch.name)));
+    const selectedChoiceBranchNames = new Set(choiceGroups
+        .map((group) => group.branches[0]?.name)
+        .filter((name) => !!name));
     for (const [propName, propType] of Object.entries(childTypes ?? {})) {
+        if (choiceBranchNames.has(propName) && !selectedChoiceBranchNames.has(propName)) {
+            continue;
+        }
         const meta = propMeta[propName];
         const isArray = meta?.max === "unbounded" || (typeof meta?.max === "number" && meta.max > 1);
         // Check if it's a primitive type

package/docs/README.md

@@ -29,6 +29,7 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [concepts.md](concepts.md): flattening, `$value`, primitives, determinism
 - [architecture.md](architecture.md): internal pipeline for contributors
 - [agent-skill.md](agent-skill.md): release ZIP for consumer-project AI agents
+- [roadmap/README.md](roadmap/README.md): implementation slices and release gates for 1.0
 - [decisions/002-streamable-responses.md](decisions/002-streamable-responses.md): opt-in streaming design (client `AsyncIterable`, gateway NDJSON, `x-wsdl-tsc-stream` OpenAPI extension); shipped in 0.17.0
 - [migration.md](migration.md): upgrading between package versions
 

package/docs/api-reference.md

@@ -68,6 +68,8 @@ interface PrimitiveOptions {
 }
 ```
 
+`CompilerOptions.choice` defaults to `all-optional`. Set `choice: "union"` to model `xs:choice` groups as exclusive branch unions in generated client types and catalog-backed OpenAPI schemas.
+
 ## generateOpenAPI
 
 Generate an OpenAPI 3.1 specification from WSDL or catalog.
@@ -204,6 +206,25 @@ const { compiled, openapiDoc } = await runGenerationPipeline({
 });
 ```
 
+Programmatic callers opt into choice union mode by passing `compiler: { choice: "union" }` to `runGenerationPipeline`:
+
+```typescript
+await runGenerationPipeline({
+  wsdl: "./service.wsdl",
+  catalogOut: "./generated/catalog.json",
+  clientOutDir: "./generated/client",
+  openapi: {
+    outFile: "./generated/openapi.json"
+  },
+  gateway: {
+    outDir: "./generated/gateway",
+    serviceSlug: "service",
+    versionSlug: "v1"
+  },
+  compiler: { choice: "union" }
+});
+```
+
 ### Type Signature
 
 ```typescript

package/docs/cli-reference.md

@@ -54,6 +54,7 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--client-dir` | Generate TypeScript client in this directory |
 | `--openapi-file` | Generate OpenAPI spec at this path |
 | `--gateway-dir` | Generate Fastify gateway in this directory |
+| `--clean` | Remove existing client output directory contents before generation |
 
 ### Client Flags
 
@@ -66,36 +67,37 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--client-bigint-as` | `string` | Map arbitrary-size integers |
 | `--client-decimal-as` | `string` | Map xs:decimal |
 | `--client-date-as` | `string` | Map date/time types |
-| `--client-choice-mode` | `all-optional` | Choice element strategy |
+| `--client-choice-mode` | `all-optional` | Controls `xs:choice` modeling |
 | `--client-fail-on-unresolved` | `false` | Fail on unresolved references |
 | `--client-nillable-as-optional` | `false` | Treat nillable as optional |
 
+`--client-choice-mode` accepts `all-optional` and `union`. The default `all-optional` mode emits parallel optional choice fields. The `union` mode emits exclusive generated client type branches and catalog-backed OpenAPI schema constraints.
+
 ### OpenAPI Flags
 
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--openapi-format` | `json` | Output format: json, yaml, or both |
 | `--openapi-title` | (derived) | API title |
-| `--openapi-version` | `0.0.0` | API version |
-| `--openapi-description` | (empty) | API description |
+| `--openapi-version-tag` | `0.0.0` | API version for `info.version` |
 | `--openapi-servers` | `/` | Comma-separated server URLs (see note below) |
-
-> When `--init-app` is used and `--openapi-servers` is not provided, servers default to `http://localhost:3000`. The app scaffold also rewrites the servers array in its local `openapi.json` copy to match the configured port and prefix.
-
 | `--openapi-base-path` | (empty) | Base path prefix |
 | `--openapi-path-style` | `kebab` | Path transform: kebab, asis, or lower |
-| `--openapi-method` | `post` | Default HTTP method |
+| `--openapi-default-method` | `post` | Default HTTP method |
 | `--openapi-tag-style` | `default` | Tag inference: default, service, or first |
 | `--openapi-closed-schemas` | `false` | Add additionalProperties: false |
 | `--openapi-flatten-array-wrappers` | `true` | Flatten ArrayOf* wrappers to plain arrays; emit runtime unwrap in gateway |
 | `--openapi-prune-unused-schemas` | `false` | Emit only referenced schemas |
 | `--openapi-envelope-namespace` | `ResponseEnvelope` | Envelope component name suffix |
 | `--openapi-error-namespace` | `ErrorObject` | Error object name suffix |
-| `--openapi-validate` | `true` | Validate spec with swagger-parser |
 | `--openapi-security-config-file` | | Path to security.json; `--openapi-security-file` is accepted as an alias |
 | `--openapi-tags-file` | | Path to tags.json |
 | `--openapi-ops-file` | | Path to ops.json |
 
+CLI OpenAPI generation always validates the generated spec with `@apidevtools/swagger-parser`.
+
+When `--init-app` is used and `--openapi-servers` is not provided, servers default to `http://localhost:3000`. The app scaffold also rewrites the servers array in its local `openapi.json` copy to match the configured port and prefix.
+
 ### Gateway Flags
 
 | Flag | Default | Description |
@@ -201,6 +203,19 @@ npx wsdl-tsc pipeline \
   --init-app
 ```
 
+With union-mode choice modeling:
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source ./service.wsdl \
+  --client-dir ./generated/client \
+  --openapi-file ./generated/openapi.json \
+  --gateway-dir ./generated/gateway \
+  --gateway-service-name service \
+  --gateway-version-prefix v1 \
+  --client-choice-mode union
+```
+
 With generated test suite:
 
 ```bash
@@ -257,6 +272,12 @@ Provide either `--wsdl-source` (compile from WSDL) or `--catalog-file` (use pre-
 
 All flags from the compile command apply, plus the client-specific flags listed in the pipeline section.
 
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--client-choice-mode` | `all-optional` | Controls `xs:choice` modeling |
+
+`--client-choice-mode` accepts `all-optional` and `union`. The `client` command stores the selected mode in `catalog.json` when it compiles from WSDL and uses that catalog metadata when emitting generated TypeScript.
+
 ### Key Modeling Rules
 
 - Attributes and elements become peer properties (flattened)
@@ -537,6 +558,14 @@ npx wsdl-tsc compile --wsdl-source <file|url> --catalog-file <path> [options]
 | `--wsdl-source` | Path or URL to WSDL file |
 | `--catalog-file` | Output path for catalog.json |
 
+### Compiler Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--client-choice-mode` | `all-optional` | Controls `xs:choice` modeling |
+
+`--client-choice-mode` accepts `all-optional` and `union`. The `compile` command writes the selected mode to `catalog.json` so later catalog-backed generation stages can use the same choice strategy.
+
 ### Catalog Co-location
 
 Default behavior varies by command:

package/docs/concepts.md

@@ -253,8 +253,7 @@ produces `WeatherResponse_ResponseEnvelope`.
 
 ## Choice Element Handling
 
-The current strategy is all-optional. All choice branches are emitted as
-optional properties on a single interface.
+The default strategy is `all-optional`. Choice branches are emitted on a single interface using the occurrence metadata compiled from the WSDL.
 
 ```typescript
 // WSDL: <xs:choice>
@@ -264,6 +263,22 @@ interface MyType {
 }
 ```
 
+`--client-choice-mode union` is opt-in. It emits a base object for non-choice fields and an exclusive generated branch union for choice fields. Peer branch properties use `?: never`, so TypeScript rejects payloads that include more than one branch.
+
+```typescript
+type MyType = MyTypeChoiceBase & MyTypeChoice1;
+
+interface MyTypeChoiceBase {
+  id: string;
+}
+
+type MyTypeChoice1 =
+  | { optionA: string; optionB?: never }
+  | { optionB: number; optionA?: never };
+```
+
+OpenAPI generation also consumes the same choice metadata in union mode. It keeps choice member properties on the containing object and adds `oneOf` branch constraints with peer `not` checks so generated request schemas reject payloads that send multiple branches.
+
 ## Array Wrapper Flattening
 
 A complex type whose only child is a single repeated element with no attributes
@@ -339,8 +354,7 @@ OpenAPI output is validated with `@apidevtools/swagger-parser`. The validator
 checks schema structure, resolves all `$ref` references, catches missing
 schemas, and detects circular dependencies.
 
-Disable with `--openapi-validate false` or `validate: false` in the
-programmatic API.
+CLI OpenAPI generation always validates the generated spec. Programmatic callers can set `skipValidate: true` when they need to inspect an intermediate state.
 
 ## Streaming vs Buffered Responses
 

package/docs/generated-code.md

@@ -83,6 +83,24 @@ interface ForecastReturn {
 }
 ```
 
+## Working With Choice Unions
+
+`--client-choice-mode union` changes generated `xs:choice` types from parallel optional fields into a base object plus an exclusive branch union. The default mode remains `all-optional`.
+
+```typescript
+export type SearchRequest = SearchRequestChoiceBase & SearchRequestChoice1;
+
+export interface SearchRequestChoiceBase {
+  tenantId: string;
+}
+
+export type SearchRequestChoice1 =
+  | { email: string; phone?: never }
+  | { phone: number; email?: never };
+```
+
+Generated gateway test suites use one valid branch in union-mode mocks. They also include validation cases that reject payloads with multiple choice branches and payloads that omit a required choice branch.
+
 ## Type Safety
 
 All operations and types are fully typed:

package/docs/migration-playbook.md

@@ -56,7 +56,7 @@ npx wsdl-tsc openapi \
 
 Open `openapi.json` and review the paths, request/response schemas, and descriptions. The spec is derived from the same compiled catalog as the TypeScript types, so they stay aligned.
 
-Validate the spec with any OpenAPI tool. Built-in validation runs by default; disable with `--openapi-validate false` if you need to inspect an intermediate state.
+Validate the spec with any OpenAPI tool. Built-in CLI validation always runs; programmatic callers can set `skipValidate: true` when they need to inspect an intermediate state.
 
 ## Step 2b (Optional): Opt Into Streaming for Large Responses
 

package/docs/migration.md

@@ -108,7 +108,7 @@ All CLI flags changed from camelCase to kebab-case. The URN format changed to a
 
 | Old Flag (0.7.x) | New Flag (0.8.x) |
 |-------------------|-------------------|
-| `--versionTag` | `--openapi-version` |
+| `--versionTag` | `--openapi-version-tag` |
 | `--basePath` | `--openapi-base-path` |
 | `--pathStyle` | `--openapi-path-style` |
 | `--closedSchemas` | `--openapi-closed-schemas` |

package/docs/output-anatomy.md

@@ -71,7 +71,7 @@ Generated at the path specified by `--openapi-file`.
 
 The spec includes one POST path per WSDL operation, request and response schemas in `components/schemas`, and descriptions derived from WSDL documentation annotations. Schemas are generated from the same catalog used for TypeScript types, so the two outputs stay aligned.
 
-OpenAPI validation runs by default using `@apidevtools/swagger-parser`. Disable with `--openapi-validate false`.
+CLI OpenAPI generation always validates the generated spec using `@apidevtools/swagger-parser`.
 
 ### Stream Schema Extension
 

package/docs/production.md

@@ -20,7 +20,7 @@ Regenerate safely in CI/CD without spurious diffs.
 
 ### OpenAPI Validation
 
-Enabled by default using @apidevtools/swagger-parser. Validates schema structure, resolves all $ref references, catches missing schemas and circular dependencies. Disable with `--openapi-validate false`.
+CLI OpenAPI generation always validates with `@apidevtools/swagger-parser`. It checks schema structure, resolves `$ref` references, and catches missing schemas and circular dependencies.
 
 ### Gateway Contract Validation
 
@@ -89,11 +89,11 @@ Errors raised before the first record use the normal gateway error envelope (cli
 
 ### Choice Elements
 
-Current strategy: all-optional (all branches optional). Discriminated union support is planned.
+Default strategy: `all-optional`. The opt-in `--client-choice-mode union` mode emits TypeScript branch unions for generated client types and OpenAPI choice constraints for generated schemas.
 
 ### Union Types
 
-Experimental --client-choice-mode union available. May require manual refinement for complex patterns.
+`--client-choice-mode union` is supported as an opt-in strategy. Future WSDL coverage matrix work will broaden fixture evidence for edge cases, but the released union mode is test-backed for compiler metadata, TypeScript output, OpenAPI constraints, generated mocks, and generated validation tests.
 
 ### WS-Policy
 

package/docs/releases/v0.25.0.md

@@ -0,0 +1,31 @@
+# TypeScript WSDL Client v0.25.0
+
+## Security Scan Hardening
+
+This release resolves GitHub CodeQL findings that were reported after `v0.24.0` shipped.
+
+## What This Improves
+
+Generated gateway runtimes now avoid assigning through prototype-sensitive property names while recursively unwrapping SOAP array wrappers. Release preflight changelog parsing also avoids dynamic regular expression construction for version headers, so GitHub security scanning can validate the release tooling without sanitizer warnings.
+
+## Highlights
+
+- Hardens generated gateway runtime unwrapping against `__proto__`, `constructor`, and `prototype` child keys.
+- Replaces release preflight's dynamic changelog header regex with literal version matching.
+- Adds regression coverage for both GitHub CodeQL findings.
+
+## Upgrade Notes
+
+No runtime upgrade steps. Regenerate gateway output to receive the hardened `runtime.ts` code in generated projects.
+
+## Validation
+
+- CI passed.
+- NPM package contents were validated.
+- Documentation links and TypeScript fenced snippets were validated.
+- Agent skill artifact was validated and packaged.
+- Release preflight passed against the target tag.
+
+## Notes
+
+Release tag: `v0.25.0`.