@techspokes/typescript-wsdl-client 0.11.5 → 0.13.0

package/dist/test/generators.js

@@ -9,7 +9,7 @@
  * via computeRelativeImport() from src/util/imports.ts.
  */
 import { computeRelativeImport } from "../util/imports.js";
-import { generateAllOperationMocks } from "./mockData.js";
+import { detectArrayWrappers, detectChildrenTypes } from "../util/catalogMeta.js";
 /**
  * Emits vitest.config.ts content.
  *
@@ -17,12 +17,13 @@ import { generateAllOperationMocks } from "./mockData.js";
  * config file location, not the working directory.
  */
 export function emitVitestConfig() {
-    return `import { dirname } from "node:path";
+    return `import { defineProject } from "vitest/config";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export default {
+export default defineProject({
   test: {
     root: __dirname,
     include: [
@@ -31,7 +32,7 @@ export default {
     ],
     testTimeout: 30000,
   },
-};
+});
 `;
 }
 /**
@@ -42,12 +43,11 @@ export default {
  * @param importsMode - Import extension mode
  * @param clientMeta - Client metadata
  * @param operations - Resolved operation metadata
- * @param catalog - Compiled catalog for mock data generation
+ * @param mocks - Pre-computed mock data map
  */
-export function emitMockClientHelper(testDir, clientDir, importsMode, clientMeta, operations, catalog) {
+export function emitMockClientHelper(testDir, clientDir, importsMode, clientMeta, operations, mocks) {
     const helpersDir = `${testDir}/helpers`;
     const operationsImport = computeRelativeImport(helpersDir, `${clientDir}/operations`, importsMode);
-    const mocks = generateAllOperationMocks(catalog);
     // Sort operations for deterministic output
     const sortedOps = [...operations].sort((a, b) => a.operationId.localeCompare(b.operationId));
     const methodEntries = sortedOps.map((op) => {
@@ -141,12 +141,12 @@ export async function createTestApp(
  * @param testDir - Absolute path to test output directory
  * @param importsMode - Import extension mode
  * @param operations - Resolved operation metadata
- * @param catalog - Compiled catalog for mock data generation
+ * @param mocks - Pre-computed mock data map
  */
-export function emitRoutesTest(testDir, importsMode, operations, catalog) {
+// noinspection JSUnusedLocalSymbols
+export function emitRoutesTest(testDir, importsMode, operations, mocks) {
     const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
     const testAppImport = `../helpers/test-app${suffix}`;
-    const mocks = generateAllOperationMocks(catalog);
     // Sort operations for deterministic output
     const sortedOps = [...operations].sort((a, b) => a.operationId.localeCompare(b.operationId));
     const testCases = sortedOps.map((op) => {
@@ -191,9 +191,10 @@ ${testCases}
  * @param testDir - Absolute path to test output directory
  * @param importsMode - Import extension mode
  * @param operations - Resolved operation metadata (uses first operation for error tests)
- * @param catalog - Compiled catalog for mock data generation
+ * @param mocks - Pre-computed mock data map
  */
-export function emitErrorsTest(testDir, importsMode, operations, catalog) {
+// noinspection JSUnusedLocalSymbols
+export function emitErrorsTest(testDir, importsMode, operations, mocks) {
     const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
     const testAppImport = `../helpers/test-app${suffix}`;
     const mockClientImport = `../helpers/mock-client${suffix}`;
@@ -202,7 +203,6 @@ export function emitErrorsTest(testDir, importsMode, operations, catalog) {
     const op = sortedOps[0];
     if (!op)
         return "// No operations found\n";
-    const mocks = generateAllOperationMocks(catalog);
     const mockData = mocks.get(op.operationId);
     const requestPayload = JSON.stringify(mockData?.request ?? {}, null, 4).replace(/\n/g, "\n    ");
     return `/**
@@ -325,7 +325,8 @@ describe("gateway routes — error handling", () => {
 /**
  * Emits gateway/envelope.test.ts with SUCCESS/ERROR structure assertions.
  */
-export function emitEnvelopeTest(testDir, importsMode, operations, catalog) {
+// noinspection JSUnusedLocalSymbols
+export function emitEnvelopeTest(testDir, importsMode, operations, mocks) {
     // noinspection DuplicatedCode
     const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
     const testAppImport = `../helpers/test-app${suffix}`;
@@ -334,7 +335,6 @@ export function emitEnvelopeTest(testDir, importsMode, operations, catalog) {
     const op = sortedOps[0];
     if (!op)
         return "// No operations found\n";
-    const mocks = generateAllOperationMocks(catalog);
     const mockData = mocks.get(op.operationId);
     const requestPayload = JSON.stringify(mockData?.request ?? {}, null, 4).replace(/\n/g, "\n    ");
     return `/**
@@ -399,6 +399,7 @@ describe("gateway — envelope structure", () => {
 /**
  * Emits gateway/validation.test.ts with invalid payload tests per route.
  */
+// noinspection JSUnusedLocalSymbols
 export function emitValidationTest(testDir, importsMode, operations) {
     const suffix = importsMode === "bare" ? "" : `.${importsMode}`;
     const testAppImport = `../helpers/test-app${suffix}`;
@@ -572,10 +573,14 @@ describe("buildErrorEnvelope", () => {
  * Returns null if no array wrappers exist in the catalog.
  */
 export function emitUnwrapTest(testDir, gatewayDir, importsMode, catalog) {
-    // Detect array wrappers
-    const wrappers = detectArrayWrappersFromCatalog(catalog);
+    // Detect array wrappers using shared utility with full type definitions
+    const types = catalog.types ?? [];
+    const wrappers = detectArrayWrappers(types);
     if (Object.keys(wrappers).length === 0)
         return null;
+    // Detect children-only types (in CHILDREN_TYPES but NOT in ARRAY_WRAPPERS)
+    const childTypeMap = catalog.meta?.childType ?? {};
+    const childrenOnly = detectChildrenTypes(childTypeMap, wrappers);
     const runtimeDir = `${testDir}/runtime`;
     const runtimeImport = computeRelativeImport(runtimeDir, `${gatewayDir}/runtime`, importsMode);
     const wrapperTests = Object.entries(wrappers).map(([wrapperType, innerKey]) => {
@@ -585,6 +590,24 @@ export function emitUnwrapTest(testDir, gatewayDir, importsMode, catalog) {
     expect(result).toEqual([{ id: 1 }]);
   });`;
     }).join("\n\n");
+    // Generate tests for children-only types that have nested wrappers
+    const childrenTests = [];
+    for (const [typeName, children] of Object.entries(childrenOnly)) {
+        // Find children whose types are array wrappers (these get recursively unwrapped)
+        const wrappedChildren = Object.entries(children).filter(([, childType]) => childType in wrappers);
+        if (wrappedChildren.length === 0)
+            continue;
+        const [childProp, childType] = wrappedChildren[0];
+        const innerKey = wrappers[childType];
+        childrenTests.push(`  it("recursively unwraps nested wrappers in ${typeName}", () => {
+    const input = { ${childProp}: { ${innerKey}: [{ id: 1 }] } };
+    const result = unwrapArrayWrappers(input, "${typeName}");
+    expect(result).toEqual({ ${childProp}: [{ id: 1 }] });
+  });`);
+    }
+    const childrenTestBlock = childrenTests.length > 0
+        ? "\n" + childrenTests.join("\n\n") + "\n"
+        : "";
     return `/**
  * unwrapArrayWrappers() Unit Tests
  *
@@ -597,7 +620,7 @@ import { unwrapArrayWrappers } from "${runtimeImport}";
 
 describe("unwrapArrayWrappers", () => {
 ${wrapperTests}
-
+${childrenTestBlock}
   it("returns empty array when inner key is missing", () => {
     const result = unwrapArrayWrappers({}, "${Object.keys(wrappers)[0]}");
     expect(result).toEqual([]);
@@ -611,22 +634,3 @@ ${wrapperTests}
 });
 `;
 }
-/**
- * Detects ArrayOf* wrapper types from catalog (mirrors the logic in generators.ts).
- */
-function detectArrayWrappersFromCatalog(catalog) {
-    const wrappers = {};
-    const childTypes = catalog.meta?.childType ?? {};
-    const propMeta = catalog.meta?.propMeta ?? {};
-    for (const [typeName, children] of Object.entries(childTypes)) {
-        const childEntries = Object.entries(children);
-        if (childEntries.length !== 1)
-            continue;
-        const [propName] = childEntries[0];
-        const meta = propMeta[typeName]?.[propName];
-        if (meta?.max === "unbounded" || (typeof meta?.max === "number" && meta.max > 1)) {
-            wrappers[typeName] = propName;
-        }
-    }
-    return wrappers;
-}

package/dist/test/mockData.d.ts

@@ -1,12 +1,3 @@
-/**
- * Mock Data Generator
- *
- * Generates realistic mock data trees from compiled catalog type metadata.
- * Used by the test generator to create full default responses per operation
- * so that generated tests pass out of the box.
- *
- * Pure logic — no I/O or side effects.
- */
 /**
  * Options for mock data generation
  */
@@ -18,6 +9,7 @@ export interface MockDataOptions {
  */
 export interface CatalogForMocks {
     meta?: {
+        attrType?: Record<string, Record<string, string>>;
         childType?: Record<string, Record<string, string>>;
         propMeta?: Record<string, Record<string, {
             declaredType?: string;
@@ -31,6 +23,16 @@ export interface CatalogForMocks {
         inputTypeName?: string;
         outputTypeName?: string;
     }>;
+    types?: Array<{
+        name: string;
+        attrs: Array<{
+            name: string;
+        }>;
+        elems: Array<{
+            name: string;
+            max: number | "unbounded";
+        }>;
+    }>;
 }
 /**
  * Generates a mock primitive value based on the TypeScript type and property name.
@@ -52,16 +54,27 @@ export declare function generateMockPrimitive(tsType: string, propName: string):
  * @returns Mock data object matching the type structure
  */
 export declare function generateMockData(typeName: string, catalog: CatalogForMocks, opts?: MockDataOptions, visited?: Set<string>, depth?: number): Record<string, unknown>;
+/**
+ * Options for bulk mock generation
+ */
+export interface GenerateAllMocksOptions {
+    flattenArrayWrappers?: boolean;
+}
 /**
  * Generates mock request and response data for all operations in the catalog.
  *
  * Response data uses the pre-unwrap shape (e.g. { WeatherDescription: [{...}] }
  * not [{...}]) since the generated route handler calls unwrapArrayWrappers() at runtime.
  *
+ * When flattenArrayWrappers is enabled, request payloads are post-processed to
+ * flatten ArrayOf* wrapper objects into plain arrays, matching the OpenAPI schema
+ * shape that AJV validates against.
+ *
  * @param catalog - The compiled catalog with operations and type metadata
+ * @param opts - Optional generation options
  * @returns Map from operation name to { request, response } mock data
  */
-export declare function generateAllOperationMocks(catalog: CatalogForMocks): Map<string, {
+export declare function generateAllOperationMocks(catalog: CatalogForMocks, opts?: GenerateAllMocksOptions): Map<string, {
     request: Record<string, unknown>;
     response: Record<string, unknown>;
 }>;

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

@@ -1 +1 @@
-{"version":3,"file":"mockData.d.ts","sourceRoot":"","sources":["../../src/test/mockData.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE;QACL,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;KACzB,CAAC,CAAC;CACJ;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAiCjG;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,CAoCzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,eAAe,GACvB,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAkBtF"}
+{"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;KACzB,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;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;AAED;;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,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CA+BtF"}

package/dist/test/mockData.js

@@ -7,6 +7,7 @@
  *
  * Pure logic — no I/O or side effects.
  */
+import { detectArrayWrappers, flattenMockPayload } from "../util/catalogMeta.js";
 /**
  * Generates a mock primitive value based on the TypeScript type and property name.
  * Uses contextual defaults based on common property names.
@@ -33,6 +34,13 @@ export function generateMockPrimitive(tsType, propName) {
             return 1013;
         return 0;
     }
+    // String union / enum type — pick the first literal value
+    // e.g. '"Test" | "Production"' → "Test"
+    if (tsType.includes("|") && tsType.includes('"')) {
+        const match = tsType.match(/"([^"]+)"/);
+        if (match)
+            return match[1];
+    }
     // string type — use contextual defaults
     if (lower === "zip" || lower === "zipcode" || lower === "postalcode")
         return "10001";
@@ -84,14 +92,15 @@ export function generateMockData(typeName, catalog, opts, visited, depth) {
         return {};
     }
     const childTypes = catalog.meta?.childType?.[typeName];
-    if (!childTypes || Object.keys(childTypes).length === 0) {
+    const attrTypes = catalog.meta?.attrType?.[typeName];
+    if ((!childTypes || Object.keys(childTypes).length === 0) && !attrTypes) {
         return {};
     }
     const propMeta = catalog.meta?.propMeta?.[typeName] ?? {};
     const newVisited = new Set(currentVisited);
     newVisited.add(typeName);
     const result = {};
-    for (const [propName, propType] of Object.entries(childTypes)) {
+    for (const [propName, propType] of Object.entries(childTypes ?? {})) {
         const meta = propMeta[propName];
         const isArray = meta?.max === "unbounded" || (typeof meta?.max === "number" && meta.max > 1);
         // Check if it's a primitive type
@@ -105,6 +114,21 @@ export function generateMockData(typeName, catalog, opts, visited, depth) {
             result[propName] = isArray ? [childData] : childData;
         }
     }
+    // Include XML attributes (not in childType, stored separately in attrType)
+    if (attrTypes) {
+        for (const [attrName, attrTsType] of Object.entries(attrTypes)) {
+            if (!(attrName in result)) {
+                // Handle array-typed attributes (e.g. "string[]")
+                if (attrTsType.endsWith("[]")) {
+                    const baseType = attrTsType.slice(0, -2);
+                    result[attrName] = [generateMockPrimitive(baseType, attrName)];
+                }
+                else {
+                    result[attrName] = generateMockPrimitive(attrTsType, attrName);
+                }
+            }
+        }
+    }
     return result;
 }
 /**
@@ -113,17 +137,33 @@ export function generateMockData(typeName, catalog, opts, visited, depth) {
  * Response data uses the pre-unwrap shape (e.g. { WeatherDescription: [{...}] }
  * not [{...}]) since the generated route handler calls unwrapArrayWrappers() at runtime.
  *
+ * When flattenArrayWrappers is enabled, request payloads are post-processed to
+ * flatten ArrayOf* wrapper objects into plain arrays, matching the OpenAPI schema
+ * shape that AJV validates against.
+ *
  * @param catalog - The compiled catalog with operations and type metadata
+ * @param opts - Optional generation options
  * @returns Map from operation name to { request, response } mock data
  */
-export function generateAllOperationMocks(catalog) {
+export function generateAllOperationMocks(catalog, opts) {
     const result = new Map();
     if (!catalog.operations)
         return result;
+    // Detect array wrappers once for all operations
+    const arrayWrappers = opts?.flattenArrayWrappers !== false && catalog.types
+        ? detectArrayWrappers(catalog.types)
+        : {};
+    const shouldFlatten = Object.keys(arrayWrappers).length > 0;
+    const childTypeMap = catalog.meta?.childType ?? {};
     for (const op of catalog.operations) {
-        const request = op.inputTypeName
+        let request = op.inputTypeName
             ? generateMockData(op.inputTypeName, catalog)
             : {};
+        // Flatten request payloads when array wrappers are active
+        if (shouldFlatten && op.inputTypeName) {
+            request = flattenMockPayload(request, op.inputTypeName, childTypeMap, arrayWrappers);
+        }
+        // Response stays SOAP-shaped (pre-unwrap) since runtime unwrapArrayWrappers() handles it
         const response = op.outputTypeName
             ? generateMockData(op.outputTypeName, catalog)
             : {};

package/dist/util/catalogMeta.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared catalog analysis utilities.
+ *
+ * Provides canonical array-wrapper and children-type detection used by both
+ * the gateway generator (runtime.ts emission) and the test generator.
+ */
+export interface CatalogTypeDef {
+    name: string;
+    attrs: Array<{
+        name: string;
+    }>;
+    elems: Array<{
+        name: string;
+        max: number | "unbounded";
+    }>;
+}
+/**
+ * Detects ArrayOf* wrapper types: exactly 1 element with max unbounded, no attributes.
+ * Returns Record<wrapperTypeName, innerPropertyName>.
+ */
+export declare function detectArrayWrappers(types: CatalogTypeDef[]): Record<string, string>;
+/**
+ * Builds CHILDREN_TYPES map: all childType entries that are NOT array wrappers.
+ * Used by the runtime unwrapArrayWrappers() for recursive child processing.
+ */
+export declare function detectChildrenTypes(childTypeMap: Record<string, Record<string, string>>, arrayWrappers: Record<string, string>): Record<string, Record<string, string>>;
+/**
+ * Post-processes a mock request payload to flatten array-wrapper fields.
+ * Replaces { InnerProp: [...items] } with [...items] for wrapper types.
+ * Recursion follows the childType map.
+ */
+export declare function flattenMockPayload(data: Record<string, unknown>, typeName: string, childTypeMap: Record<string, Record<string, string>>, arrayWrappers: Record<string, string>): Record<string, unknown>;
+//# sourceMappingURL=catalogMeta.d.ts.map

package/dist/util/catalogMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalogMeta.d.ts","sourceRoot":"","sources":["../../src/util/catalogMeta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/B,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACpD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOxC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACpD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoDzB"}

package/dist/util/catalogMeta.js

@@ -0,0 +1,95 @@
+/**
+ * Shared catalog analysis utilities.
+ *
+ * Provides canonical array-wrapper and children-type detection used by both
+ * the gateway generator (runtime.ts emission) and the test generator.
+ */
+/**
+ * Detects ArrayOf* wrapper types: exactly 1 element with max unbounded, no attributes.
+ * Returns Record<wrapperTypeName, innerPropertyName>.
+ */
+export function detectArrayWrappers(types) {
+    const wrappers = {};
+    for (const t of types) {
+        if (t.attrs && t.attrs.length !== 0)
+            continue;
+        if (!t.elems || t.elems.length !== 1)
+            continue;
+        const e = t.elems[0];
+        if (e.max !== "unbounded" && !(typeof e.max === "number" && e.max > 1))
+            continue;
+        wrappers[t.name] = e.name;
+    }
+    return wrappers;
+}
+/**
+ * Builds CHILDREN_TYPES map: all childType entries that are NOT array wrappers.
+ * Used by the runtime unwrapArrayWrappers() for recursive child processing.
+ */
+export function detectChildrenTypes(childTypeMap, arrayWrappers) {
+    const result = {};
+    for (const [typeName, children] of Object.entries(childTypeMap)) {
+        if (typeName in arrayWrappers)
+            continue;
+        result[typeName] = children;
+    }
+    return result;
+}
+/**
+ * Post-processes a mock request payload to flatten array-wrapper fields.
+ * Replaces { InnerProp: [...items] } with [...items] for wrapper types.
+ * Recursion follows the childType map.
+ */
+export function flattenMockPayload(data, typeName, childTypeMap, arrayWrappers) {
+    const children = childTypeMap[typeName];
+    if (!children)
+        return data;
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const childTypeName = children[key];
+        if (childTypeName && childTypeName in arrayWrappers && value != null && typeof value === "object" && !Array.isArray(value)) {
+            // This field's type is an array wrapper — flatten it
+            const innerKey = arrayWrappers[childTypeName];
+            const innerValue = value[innerKey];
+            // Recurse into each item of the unwrapped array
+            const itemTypeName = childTypeMap[childTypeName]?.[innerKey];
+            if (Array.isArray(innerValue) && itemTypeName) {
+                result[key] = innerValue.map(item => item != null && typeof item === "object" && !Array.isArray(item)
+                    ? flattenMockPayload(item, itemTypeName, childTypeMap, arrayWrappers)
+                    : item);
+            }
+            else {
+                result[key] = innerValue ?? [];
+            }
+        }
+        else if (childTypeName && value != null && typeof value === "object" && !Array.isArray(value)) {
+            // Recurse into complex types
+            result[key] = flattenMockPayload(value, childTypeName, childTypeMap, arrayWrappers);
+        }
+        else if (childTypeName && Array.isArray(value)) {
+            // Array of complex types — flatten each item
+            result[key] = value.map(item => {
+                if (item != null && typeof item === "object" && !Array.isArray(item)) {
+                    if (childTypeName in arrayWrappers) {
+                        const innerKey = arrayWrappers[childTypeName];
+                        const innerValue = item[innerKey];
+                        // Recurse into each item of the unwrapped array
+                        const itemTypeName = childTypeMap[childTypeName]?.[innerKey];
+                        if (Array.isArray(innerValue) && itemTypeName) {
+                            return innerValue.map(subItem => subItem != null && typeof subItem === "object" && !Array.isArray(subItem)
+                                ? flattenMockPayload(subItem, itemTypeName, childTypeMap, arrayWrappers)
+                                : subItem);
+                        }
+                        return innerValue ?? [];
+                    }
+                    return flattenMockPayload(item, childTypeName, childTypeMap, arrayWrappers);
+                }
+                return item;
+            });
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/docs/architecture.md

@@ -83,6 +83,8 @@ CompiledCatalog {
 }
 ```
 
+`CompiledType`, type aliases, and operations may include optional `doc` fields populated from WSDL/XSD documentation nodes. Client emitters consume these values to generate comments in `types.ts`, `operations.ts`, and `client.ts`. OpenAPI emitters consume the same fields for schema, property, and operation `description` values.
+
 Data flow through the pipeline:
 
 1. schemaCompiler produces CompiledCatalog from WSDL XML

package/docs/concepts.md

@@ -67,6 +67,8 @@ cacheable, and reused across client, OpenAPI, and gateway generation.
 Inspect types, operations, and metadata as plain JSON. The catalog is
 automatically placed alongside generated output.
 
+The catalog stores optional human-readable `doc` fields extracted from WSDL/XSD documentation nodes. These fields are additive metadata used by TypeScript and OpenAPI emitters and do not change runtime behavior.
+
 ### Catalog Locations by Command
 
 | Command | Location |

package/docs/generated-code.md

@@ -73,6 +73,34 @@ result.GetCityWeatherByZIPResult.Temperature;
 
 Autocomplete and type checking work across all generated interfaces.
 
+## Documentation Comments
+
+Generated `types.ts`, `operations.ts`, and `client.ts` include source documentation when present in WSDL/XSD.
+
+`wsdl:documentation` on operations is emitted as method comments in `operations.ts` and `client.ts`. `xs:annotation/xs:documentation` on complex types, attributes, and elements is emitted as comments in `types.ts`.
+
+```typescript
+/**
+ * Thing payload.
+ */
+export interface Thing {
+  /**
+   * Display name.
+   *
+   * @xsd {"kind":"element","type":"xs:string","occurs":{"min":1,"max":1,"nillable":false}}
+   */
+  name: string;
+}
+```
+
+The existing `@xsd` metadata annotations are preserved for runtime marshaling and tooling.
+
+OpenAPI generation also propagates these docs into `description` fields:
+
+- Operation descriptions come from `wsdl:documentation` by default
+- `--openapi-ops-file` `description` overrides operation documentation when provided
+- Schema and property descriptions come from `xs:annotation/xs:documentation`
+
 ## Gateway Route Handlers
 
 When generating a Fastify gateway (`--gateway-dir`), each SOAP operation gets a fully typed route handler. The handler imports the request type from the client, uses Fastify's `Body: T` generic for type inference, and wraps the SOAP response in a standard envelope.
@@ -99,9 +127,9 @@ export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: Fas
 
 Key features of the generated handlers:
 
-- **`Body: T` generic** — Fastify infers `request.body` type from the route generic, enabling IDE autocomplete and compile-time checks
-- **JSON Schema validation** — the `schema` import provides Fastify with request/response validation at runtime, before the handler runs
-- **Envelope wrapping** — `buildSuccessEnvelope()` wraps the raw SOAP response in the standard `{ status, message, data, error }` envelope
+- `Body: T` generic: Fastify infers `request.body` type from the route generic, enabling IDE autocomplete and compile-time checks
+- JSON Schema validation: the `schema` import provides Fastify with request/response validation at runtime, before the handler runs
+- Envelope wrapping: `buildSuccessEnvelope()` wraps the raw SOAP response in the standard `{ status, message, data, error }` envelope
 
 See [Gateway Guide](gateway-guide.md) for the full architecture and [CLI Reference](cli-reference.md) for generation flags.
 

package/docs/testing.md

@@ -8,9 +8,9 @@ See [README](../README.md) for quick start and [CONTRIBUTING](../CONTRIBUTING.md
 
 The project uses three layers of testing:
 
-1. **Unit tests** — Pure function tests for utilities, parsers, and type mapping
-2. **Snapshot tests** — Baseline comparisons for all generated pipeline output
-3. **Integration tests** — End-to-end gateway tests using Fastify's `inject()` with mock clients
+1. Unit tests: Pure function tests for utilities, parsers, and type mapping
+2. Snapshot tests: Baseline comparisons for all generated pipeline output
+3. Integration tests: End-to-end gateway tests using Fastify's `inject()` with mock clients
 
 All tests use [Vitest](https://vitest.dev/) and run in under 3 seconds.
 
@@ -34,12 +34,13 @@ npm run ci
 
 Unit tests cover pure functions with no I/O or side effects:
 
-- **`tools.test.ts`** — `pascal()`, `resolveQName()`, `explodePascal()`, `pascalToSnakeCase()`, `normalizeArray()`, `getChildrenWithLocalName()`, `getFirstWithLocalName()`
-- **`casing.test.ts`** — `toPathSegment()` with kebab, asis, and lower styles
-- **`primitives.test.ts`** — `xsdToTsPrimitive()` covering all XSD types (string-like, boolean, integers, decimals, floats, dates, any)
-- **`errors.test.ts`** — `WsdlCompilationError` construction and `toUserMessage()` formatting
-- **`schema-alignment.test.ts`** — Cross-validates TypeScript types, JSON schemas, and catalog.json for consistency
-- **`mock-data.test.ts`** — `generateMockPrimitive()`, `generateMockData()`, `generateAllOperationMocks()` with cycle detection and array wrapping
+- `tools.test.ts`: `pascal()`, `resolveQName()`, `explodePascal()`, `pascalToSnakeCase()`, `normalizeArray()`, `getChildrenWithLocalName()`, `getFirstWithLocalName()`
+- `casing.test.ts`: `toPathSegment()` with kebab, asis, and lower styles
+- `primitives.test.ts`: `xsdToTsPrimitive()` covering all XSD types (string-like, boolean, integers, decimals, floats, dates, any)
+- `errors.test.ts`: `WsdlCompilationError` construction and `toUserMessage()` formatting
+- `schema-alignment.test.ts`: Cross-validates TypeScript types, JSON schemas, and catalog.json for consistency
+- `mock-data.test.ts`: `generateMockPrimitive()`, `generateMockData()`, `generateAllOperationMocks()` with cycle detection and array wrapping
+- `wsdl-documentation.test.ts`: verifies doc flow to catalog, generated TS comments, and OpenAPI descriptions with override precedence
 
 ### Writing Unit Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.11.5",
+  "version": "0.13.0",
   "description": "Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways from WSDL/XSD definitions.",
   "keywords": [
     "wsdl",
@@ -76,20 +76,20 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.2.0",
+    "@types/node": "^25.3.3",
     "@types/yargs": "^17.0.35",
-    "fastify": "^5.7.0",
+    "fastify": "^5.7.4",
     "fastify-plugin": "^5.1.0",
-    "rimraf": "^6.1.0",
+    "rimraf": "^6.1.3",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.0",
+    "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "fast-xml-parser": "^5.3.0",
+    "fast-xml-parser": "^5.4.2",
     "js-yaml": "^4.1.1",
-    "soap": "^1.6.0",
+    "soap": "^1.7.1",
     "yargs": "^18.0.0"
   },
   "funding": {