@techspokes/typescript-wsdl-client 0.25.0 → 0.27.0

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.2.md

@@ -0,0 +1,32 @@
+# TypeScript WSDL Client v0.25.2
+
+## Roadmap And CLI Contract Alignment
+
+This release publishes the 1.0 readiness roadmap and tightens the CLI reference against the implemented command surface.
+
+## What This Improves
+
+The 1.0 roadmap is now split into concrete implementation slices for contract audit, OpenAPI compatibility, choice union mode, JSON array streaming, WSDL coverage, and release gates. The CLI reference also matches the actual public flags, which reduces confusion around OpenAPI versioning, default methods, validation behavior, and pipeline cleanup.
+
+## Highlights
+
+- Adds the 1.0 roadmap breakdown with independent implementation slice plans.
+- Aligns CLI documentation with `--openapi-version-tag`, `--openapi-default-method`, and `--clean`.
+- Adds contract coverage that compares public CLI declarations with the CLI reference.
+- Keeps release dependency maintenance from downgrading newer pins when npm metadata points backward.
+
+## Upgrade Notes
+
+No special upgrade steps.
+
+## 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.2`.

package/docs/releases/v0.26.0.md

@@ -0,0 +1,32 @@
+# TypeScript WSDL Client v0.26.0
+
+## Choice Union Mode
+
+This release completes opt-in `xs:choice` union mode for generated TypeScript clients, OpenAPI schemas, and generated gateway tests.
+
+## What This Improves
+
+Developers can now choose stricter generated models for WSDL choice groups without changing the default output. The default `all-optional` mode remains stable, while `--client-choice-mode union` emits exclusive TypeScript branch unions and OpenAPI constraints that reject invalid branch combinations in generated Fastify gateways.
+
+## Highlights
+
+- Completes opt-in `--client-choice-mode union` support across compiler metadata, TypeScript output, OpenAPI schemas, mocks, and generated tests.
+- Aligns CLI, API, generated-code, production, supported-patterns, and roadmap documentation with the released union-mode behavior.
+- Updates the packaged agent skill guidance so consumer-project agents can discover choice union mode and generated-code examples.
+- Keeps `all-optional` as the default choice strategy for backward compatibility.
+
+## Upgrade Notes
+
+No special upgrade steps. Existing users keep the default `all-optional` choice behavior unless they opt into `--client-choice-mode union`.
+
+## 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.26.0`.