@techspokes/typescript-wsdl-client 0.6.3 → 0.7.0

package/dist/openapi/security.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Authentication scheme types supported in the OpenAPI specification
+ *
+ * @property {"none"} string No authentication required
+ * @property {"basic"} string HTTP Basic authentication
+ * @property {"bearer"} string HTTP Bearer token authentication
+ * @property {"apiKey"} string API key authentication
+ * @property {"oauth2"} string OAuth 2.0 authentication
+ */
+export type AuthScheme = "none" | "basic" | "bearer" | "apiKey" | "oauth2";
+/**
+ * Security configuration schema for the OpenAPI generation
+ *
+ * @interface SecurityConfig
+ * @property {Object} [global] - Global security settings applied to all operations by default
+ * @property {AuthScheme} [global.scheme] - Default authentication scheme
+ * @property {Object} [global.apiKey] - API key configuration (when scheme is "apiKey")
+ * @property {Object} [global.bearer] - Bearer token configuration (when scheme is "bearer")
+ * @property {Object} [global.basic] - Basic auth configuration (when scheme is "basic")
+ * @property {Object} [global.oauth2] - OAuth2 configuration (when scheme is "oauth2")
+ * @property {Array<Object>} [global.headers] - Global security headers
+ * @property {Record<string, Object>} [overrides] - Operation-specific security overrides
+ */
+export type SecurityConfig = {
+    global?: {
+        scheme?: AuthScheme;
+        apiKey?: {
+            in: "header" | "query" | "cookie";
+            name: string;
+        };
+        bearer?: {
+            bearerFormat?: string;
+        };
+        basic?: Record<string, never>;
+        oauth2?: {
+            flows: Record<string, any>;
+        };
+        headers?: Array<{
+            name: string;
+            required?: boolean;
+            schema?: any;
+        }>;
+    };
+    overrides?: Record<string, {
+        scheme?: AuthScheme;
+        headers?: Array<{
+            name: string;
+            required?: boolean;
+            schema?: any;
+        }>;
+    }>;
+};
+/**
+ * Built security components for OpenAPI generation
+ *
+ * @interface BuiltSecurity
+ * @property {Record<string, any>} [securitySchemes] - Security schemes defined for the API
+ * @property {Record<string, any>} headerParameters - Header parameters for security
+ * @property {Record<string, any[]>} opSecurity - Operation security requirements
+ * @property {Record<string, string[]>} opHeaderParameters - Operation-specific header parameters
+ */
+export type BuiltSecurity = {
+    securitySchemes?: Record<string, any>;
+    headerParameters: Record<string, any>;
+    opSecurity: Record<string, any[] | undefined>;
+    opHeaderParameters: Record<string, string[]>;
+};
+/**
+ * Load security configuration from a JSON file
+ *
+ * @param {string} [filePath] - Path to the security configuration file
+ * @returns {SecurityConfig|undefined} Parsed security configuration object or undefined if loading failed
+ */
+export declare function loadSecurityConfig(filePath?: string): SecurityConfig | undefined;
+/**
+ * Build security schemes and parameters for OpenAPI generation
+ *
+ * @param {SecurityConfig} [cfg] - Security configuration object
+ * @returns {BuiltSecurity} Object containing built security schemes and parameters
+ */
+export declare function buildSecurity(cfg?: SecurityConfig): BuiltSecurity;
+//# sourceMappingURL=security.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/openapi/security.ts"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE;QACP,MAAM,CAAC,EAAE,UAAU,CAAC;QACpB,MAAM,CAAC,EAAE;YAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7D,MAAM,CAAC,EAAE;YAAE,YAAY,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACnC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC9B,MAAM,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;SAAE,CAAC;QACxC,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,GAAG,CAAA;SAAE,CAAC,CAAC;KACrE,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,MAAM,CAAC,EAAE,UAAU,CAAC;QACpB,OAAO,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,GAAG,CAAA;SAAE,CAAC,CAAA;KACpE,CAAC,CAAC;CACJ,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;IAC9C,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAShF;AAeD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,aAAa,CA+FjE"}

package/dist/openapi/security.js

@@ -0,0 +1,145 @@
+/**
+ * OpenAPI Security Configuration
+ *
+ * This module handles security scheme generation for the OpenAPI specification.
+ * It provides functionality to define authentication and authorization requirements
+ * for the API, including:
+ *
+ * - Basic authentication
+ * - Bearer token authentication
+ * - API key authentication
+ * - OAuth2 flows
+ * - Custom security headers
+ *
+ * The module supports both global security requirements and operation-specific
+ * security overrides through an external JSON configuration file.
+ */
+import fs from "node:fs";
+/**
+ * Load security configuration from a JSON file
+ *
+ * @param {string} [filePath] - Path to the security configuration file
+ * @returns {SecurityConfig|undefined} Parsed security configuration object or undefined if loading failed
+ */
+export function loadSecurityConfig(filePath) {
+    if (!filePath)
+        return undefined;
+    try {
+        const raw = fs.readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        console.warn(`⚠️ Failed to read security config '${filePath}': ${e instanceof Error ? e.message : String(e)}`);
+        return undefined;
+    }
+}
+/**
+ * Generate a canonical parameter component name from a header name
+ *
+ * @param {string} headerName - Original header name
+ * @returns {string} Canonicalized component name
+ */
+function makeParamComponentName(headerName) {
+    return headerName
+        .replace(/[^A-Za-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        || "X_Header";
+}
+/**
+ * Build security schemes and parameters for OpenAPI generation
+ *
+ * @param {SecurityConfig} [cfg] - Security configuration object
+ * @returns {BuiltSecurity} Object containing built security schemes and parameters
+ */
+export function buildSecurity(cfg) {
+    const securitySchemes = {};
+    const headerParameters = {};
+    const opSecurity = {};
+    const opHeaderParameters = {};
+    if (!cfg || !cfg.global) {
+        return { securitySchemes: undefined, headerParameters, opSecurity, opHeaderParameters };
+    }
+    const global = cfg.global;
+    const schemeName = "defaultAuth";
+    const scheme = global.scheme || "none";
+    const hasGlobal = scheme !== "none";
+    if (scheme !== "none") {
+        switch (scheme) {
+            case "basic":
+                securitySchemes[schemeName] = { type: "http", scheme: "basic" };
+                break;
+            case "bearer":
+                securitySchemes[schemeName] = { type: "http", scheme: "bearer", ...(global.bearer || {}) };
+                break;
+            case "apiKey":
+                securitySchemes[schemeName] = { type: "apiKey", ...(global.apiKey || { in: "header", name: "X-API-Key" }) };
+                break;
+            case "oauth2":
+                securitySchemes[schemeName] = { type: "oauth2", ...(global.oauth2 || { flows: {} }) };
+                break;
+        }
+    }
+    // Global headers
+    for (const h of global.headers || []) {
+        const compName = makeParamComponentName(h.name);
+        headerParameters[compName] = {
+            name: h.name,
+            in: "header",
+            required: !!h.required,
+            schema: h.schema || { type: "string" },
+        };
+    }
+    // Default op security (inherit global scheme)
+    // (If scheme is none we omit entirely)
+    // Overrides can set scheme to none to remove security
+    for (const [opName, override] of Object.entries(cfg.overrides || {})) {
+        const oScheme = override.scheme ?? scheme;
+        if (oScheme === "none") {
+            opSecurity[opName] = undefined;
+        }
+        else if (oScheme === scheme) {
+            opSecurity[opName] = hasGlobal ? [{ [schemeName]: [] }] : undefined;
+        }
+        else {
+            // Different scheme per operation -> create ad-hoc component name
+            const altName = `${schemeName}_${oScheme}`;
+            if (!securitySchemes[altName]) {
+                switch (oScheme) {
+                    case "basic":
+                        securitySchemes[altName] = { type: "http", scheme: "basic" };
+                        break;
+                    case "bearer":
+                        securitySchemes[altName] = { type: "http", scheme: "bearer" };
+                        break;
+                    case "apiKey":
+                        securitySchemes[altName] = { type: "apiKey", ...(global.apiKey || { in: "header", name: "X-API-Key" }) };
+                        break;
+                    case "oauth2":
+                        securitySchemes[altName] = { type: "oauth2", ...(global.oauth2 || { flows: {} }) };
+                        break;
+                }
+            }
+            opSecurity[opName] = [{ [altName]: [] }];
+        }
+        // Per-op headers merge global + override specific headers
+        const headers = [...(global.headers || []), ...(override.headers || [])];
+        opHeaderParameters[opName] = headers.map(h => makeParamComponentName(h.name));
+        for (const h of override.headers || []) {
+            const compName = makeParamComponentName(h.name);
+            if (!headerParameters[compName]) {
+                headerParameters[compName] = {
+                    name: h.name,
+                    in: "header",
+                    required: !!h.required,
+                    schema: h.schema || { type: "string" },
+                };
+            }
+        }
+    }
+    return {
+        securitySchemes: Object.keys(securitySchemes).length ? securitySchemes : undefined,
+        headerParameters,
+        opSecurity,
+        opHeaderParameters
+    };
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,37 @@
+import { type GenerateOpenAPIOptions } from "./openapi/generateOpenAPI.js";
+import type { CompilerOptions } from "./config.js";
+/**
+ * Configuration options for the generation pipeline
+ *
+ * @interface PipelineOptions
+ * @property {string} wsdl - Path or URL to the WSDL file to process
+ * @property {string} outDir - Output directory for generated TypeScript artifacts
+ * @property {Partial<CompilerOptions>} [compiler] - Compiler options for type generation
+ * @property {object} [openapi] - OpenAPI generation configuration (optional)
+ * @property {string} [openapi.outFile] - Optional output path for OpenAPI specification
+ */
+export interface PipelineOptions {
+    wsdl: string;
+    outDir: string;
+    compiler?: Partial<CompilerOptions>;
+    openapi?: Omit<GenerateOpenAPIOptions, "wsdl" | "catalogFile" | "compiledCatalog"> & {
+        outFile?: string;
+    };
+}
+/**
+ * Runs the complete generation pipeline from WSDL to TypeScript artifacts and optionally OpenAPI
+ *
+ * This function orchestrates the entire process:
+ * 1. Loads and parses the WSDL from file or URL
+ * 2. Compiles the WSDL into an internal catalog representation
+ * 3. Emits TypeScript client code, types, and utilities
+ * 4. Optionally emits a JSON catalog for introspection
+ * 5. Optionally generates an OpenAPI 3.1 specification
+ *
+ * @param {PipelineOptions} opts - Configuration options for the pipeline
+ * @returns {Promise<{compiled: any}>} - The compiled catalog for potential further processing
+ */
+export declare function runGenerationPipeline(opts: PipelineOptions): Promise<{
+    compiled: import("./compiler/schemaCompiler.js").CompiledCatalog;
+}>;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAkB,KAAK,sBAAsB,EAAC,MAAM,8BAA8B,CAAC;AAC1F,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAGjD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,aAAa,GAAG,iBAAiB,CAAC,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,eAAe;;GAgDhE"}

package/dist/pipeline.js

@@ -0,0 +1,72 @@
+/**
+ * TypeScript WSDL Client Generation Pipeline
+ *
+ * This file implements the high-level generation pipeline that orchestrates the entire
+ * process of converting a WSDL file into TypeScript client code and optionally an OpenAPI
+ * specification. It serves as an integration layer between the various stages of the generation
+ * process.
+ */
+import path from "node:path";
+import fs from "node:fs";
+import { loadWsdl } from "./loader/wsdlLoader.js";
+import { compileCatalog } from "./compiler/schemaCompiler.js";
+import { emitClient } from "./emit/clientEmitter.js";
+import { emitTypes } from "./emit/typesEmitter.js";
+import { emitUtils } from "./emit/utilsEmitter.js";
+import { emitCatalog } from "./emit/catalogEmitter.js";
+import { generateOpenAPI } from "./openapi/generateOpenAPI.js";
+import { TYPESCRIPT_WSDL_CLIENT_DEFAULT_COMPLIER_OPTIONS } from "./config.js";
+/**
+ * Runs the complete generation pipeline from WSDL to TypeScript artifacts and optionally OpenAPI
+ *
+ * This function orchestrates the entire process:
+ * 1. Loads and parses the WSDL from file or URL
+ * 2. Compiles the WSDL into an internal catalog representation
+ * 3. Emits TypeScript client code, types, and utilities
+ * 4. Optionally emits a JSON catalog for introspection
+ * 5. Optionally generates an OpenAPI 3.1 specification
+ *
+ * @param {PipelineOptions} opts - Configuration options for the pipeline
+ * @returns {Promise<{compiled: any}>} - The compiled catalog for potential further processing
+ */
+export async function runGenerationPipeline(opts) {
+    // Merge provided compiler options with defaults, ensuring required fields are set
+    const finalCompiler = {
+        ...TYPESCRIPT_WSDL_CLIENT_DEFAULT_COMPLIER_OPTIONS,
+        catalog: opts.compiler?.catalog ?? true, // default to emitting catalog in pipeline mode
+        ...(opts.compiler || {}),
+        wsdl: opts.wsdl,
+        out: opts.outDir,
+    };
+    // Step 1: Load and parse the WSDL document
+    const wsdlCatalog = await loadWsdl(opts.wsdl);
+    // Step 2: Compile the WSDL into a structured catalog
+    const compiled = compileCatalog(wsdlCatalog, finalCompiler);
+    // Step 3: Ensure the output directory exists
+    fs.mkdirSync(opts.outDir, { recursive: true });
+    // Step 4: Emit TypeScript artifacts
+    emitClient(path.join(opts.outDir, "client.ts"), compiled);
+    emitTypes(path.join(opts.outDir, "types.ts"), compiled);
+    emitUtils(path.join(opts.outDir, "utils.ts"), compiled);
+    // Step 5: Optionally emit the JSON catalog for introspection
+    if (finalCompiler.catalog) {
+        emitCatalog(path.join(opts.outDir, "catalog.json"), compiled);
+    }
+    // Step 6: Optionally generate OpenAPI specification
+    if (opts.openapi) {
+        // Determine output path for OpenAPI specification
+        let resolvedOut = opts.openapi.outFile;
+        if (!resolvedOut) {
+            const yamlPreferred = !!opts.openapi.asYaml;
+            resolvedOut = path.join(opts.outDir, yamlPreferred ? "openapi.yaml" : "openapi.json");
+        }
+        // Generate the OpenAPI specification using the compiled catalog
+        await generateOpenAPI({
+            ...opts.openapi,
+            compiledCatalog: compiled,
+            outFile: resolvedOut,
+        });
+    }
+    // Return the compiled catalog for potential further processing
+    return { compiled };
+}

package/dist/util/tools.d.ts

@@ -1,20 +1,113 @@
+/**
+ * Utility Functions for TypeScript WSDL Client Generator
+ *
+ * This module provides a collection of helper functions used throughout the codebase
+ * for common tasks such as:
+ *
+ * - XML node processing and traversal
+ * - Name formatting and conversion between different cases
+ * - QName (qualified name) resolution with namespace handling
+ * - Array normalization and manipulation
+ * - Client name derivation from various sources
+ *
+ * These utilities create a consistent approach to handling common operations across
+ * the different modules of the generator.
+ */
 import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
-/** Normalize a possibly-single value into an array. */
+/**
+ * Normalizes a possibly-single value into an array
+ *
+ * XML parsers often return single items directly and multiple items as arrays.
+ * This function ensures consistent array treatment regardless of the input.
+ *
+ * @template T - Type of the array elements
+ * @param {T|T[]|undefined|null} x - Value to normalize
+ * @returns {T[]} - Array containing the value(s) or empty array if null/undefined
+ */
 export declare function normalizeArray<T>(x: T | T[] | undefined | null): T[];
-/** Collect direct children whose LOCAL name matches (prefix-agnostic). */
+/**
+ * Collects direct children whose local name matches (prefix-agnostic)
+ *
+ * XML namespaces can cause the same element to appear with different prefixes.
+ * This function finds elements by their local name, ignoring namespace prefixes.
+ *
+ * @param {any} node - Parent XML node to search within
+ * @param {string} local - Local name to match (without namespace prefix)
+ * @returns {any[]} - Array of matching child nodes
+ */
 export declare function getChildrenWithLocalName(node: any, local: string): any[];
-/** Return the first direct child whose LOCAL name matches (prefix-agnostic). */
+/**
+ * Returns the first direct child whose local name matches (prefix-agnostic)
+ *
+ * Similar to getChildrenWithLocalName but returns only the first matching node.
+ * Useful for elements that should appear only once in a valid document.
+ *
+ * @param {any} node - Parent XML node to search within
+ * @param {string} local - Local name to match (without namespace prefix)
+ * @returns {any|undefined} - First matching child node or undefined if none found
+ */
 export declare function getFirstWithLocalName(node: any, local: string): any | undefined;
-/** Simple PascalCase helper used across emitters/parsers. */
+/**
+ * Converts a string to PascalCase format for TypeScript type names
+ *
+ * This function handles various input formats and produces valid TypeScript identifiers:
+ * - Converts separators (spaces, dashes, dots, etc.) to camelCase boundaries
+ * - Preserves underscores as literal characters
+ * - Removes invalid identifier characters
+ * - Ensures the result is a valid TypeScript identifier (not starting with numbers)
+ * - Avoids collision with TypeScript reserved keywords
+ *
+ * @param {string} s - Input string to convert to PascalCase
+ * @returns {string} - Valid TypeScript identifier in PascalCase
+ */
 export declare function pascal(s: string): string;
+/**
+ * Resolves a qualified name (QName) to its namespace and local parts
+ *
+ * XML uses qualified names (prefix:localName) to reference elements in namespaces.
+ * This function resolves the prefix to its full namespace URI using the provided prefixes map.
+ *
+ * @param {string} qname - Qualified name (e.g., "xs:string" or "myPrefix:elementName")
+ * @param {string} defaultNS - Default namespace to use if no prefix is present
+ * @param {Record<string, string>} prefixes - Map of namespace prefixes to full URIs
+ * @returns {{ns: string, local: string}} - Object containing namespace URI and local name
+ */
 export declare function resolveQName(qname: string, defaultNS: string, prefixes: Record<string, string>): {
     ns: string;
     local: string;
 };
-/** Derive a SOAP client class name from CompilerOptions and compiled catalog. */
+/**
+ * Derives a SOAP client class name from various sources
+ *
+ * This function uses a hierarchy of sources to determine an appropriate class name:
+ * 1. Explicit override from compiler options (highest priority)
+ * 2. Service name from the WSDL document
+ * 3. WSDL filename without extension
+ * 4. Default fallback name ("GeneratedSOAPClient")
+ *
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ * @returns {string} - Appropriate class name for the generated SOAP client
+ */
 export declare function deriveClientName(compiled: CompiledCatalog): string;
-/** Explode a PascalCase string into its constituent segments. */
+/**
+ * Explodes a PascalCase string into its constituent segments
+ *
+ * This function breaks a PascalCase identifier into individual words
+ * by inserting underscores at camelCase transitions and then splitting.
+ *
+ * @param {string} s - PascalCase string to explode
+ * @returns {string[]} - Array of individual segments
+ */
 export declare function explodePascal(s: string): string[];
-/** Convert a PascalCase string to snake_case (lowercase + underscores). */
+/**
+ * Convert a PascalCase string to snake_case (lowercase + underscores).
+ *
+ * This function takes a PascalCase string, explodes it into its component segments,
+ * converts each segment to lowercase, and joins them with underscores to form a
+ * snake_case string.
+ *
+ * @param {string} s - PascalCase string to convert
+ * @returns {string} - snake_case version of the input string
+ */
 export declare function pascalToSnakeCase(s: string): string;
 //# sourceMappingURL=tools.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/util/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAErE,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,EAAE,CAGpE;AAED,0EAA0E;AAC1E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,CASxE;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAK/E;AAED,6DAA6D;AAC7D,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA6BxC;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAS/B;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,GACxB,MAAM,CAWR;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAMjD;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAInD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/util/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAEnE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,EAAE,CAGpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,CASxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAK/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CA6BxC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAS/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,GACxB,MAAM,CAWR;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAMjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAInD"}

package/dist/util/tools.js

@@ -1,10 +1,28 @@
-/** Normalize a possibly-single value into an array. */
+/**
+ * Normalizes a possibly-single value into an array
+ *
+ * XML parsers often return single items directly and multiple items as arrays.
+ * This function ensures consistent array treatment regardless of the input.
+ *
+ * @template T - Type of the array elements
+ * @param {T|T[]|undefined|null} x - Value to normalize
+ * @returns {T[]} - Array containing the value(s) or empty array if null/undefined
+ */
 export function normalizeArray(x) {
     if (x == null)
         return [];
     return Array.isArray(x) ? x : [x];
 }
-/** Collect direct children whose LOCAL name matches (prefix-agnostic). */
+/**
+ * Collects direct children whose local name matches (prefix-agnostic)
+ *
+ * XML namespaces can cause the same element to appear with different prefixes.
+ * This function finds elements by their local name, ignoring namespace prefixes.
+ *
+ * @param {any} node - Parent XML node to search within
+ * @param {string} local - Local name to match (without namespace prefix)
+ * @returns {any[]} - Array of matching child nodes
+ */
 export function getChildrenWithLocalName(node, local) {
     const out = [];
     for (const [k, v] of Object.entries(node || {})) {
@@ -15,7 +33,16 @@ export function getChildrenWithLocalName(node, local) {
     }
     return out;
 }
-/** Return the first direct child whose LOCAL name matches (prefix-agnostic). */
+/**
+ * Returns the first direct child whose local name matches (prefix-agnostic)
+ *
+ * Similar to getChildrenWithLocalName but returns only the first matching node.
+ * Useful for elements that should appear only once in a valid document.
+ *
+ * @param {any} node - Parent XML node to search within
+ * @param {string} local - Local name to match (without namespace prefix)
+ * @returns {any|undefined} - First matching child node or undefined if none found
+ */
 export function getFirstWithLocalName(node, local) {
     for (const [k, v] of Object.entries(node || {})) {
         if (k === local || k.endsWith(`:${local}`))
@@ -23,7 +50,19 @@ export function getFirstWithLocalName(node, local) {
     }
     return undefined;
 }
-/** Simple PascalCase helper used across emitters/parsers. */
+/**
+ * Converts a string to PascalCase format for TypeScript type names
+ *
+ * This function handles various input formats and produces valid TypeScript identifiers:
+ * - Converts separators (spaces, dashes, dots, etc.) to camelCase boundaries
+ * - Preserves underscores as literal characters
+ * - Removes invalid identifier characters
+ * - Ensures the result is a valid TypeScript identifier (not starting with numbers)
+ * - Avoids collision with TypeScript reserved keywords
+ *
+ * @param {string} s - Input string to convert to PascalCase
+ * @returns {string} - Valid TypeScript identifier in PascalCase
+ */
 export function pascal(s) {
     const raw = String(s ?? "");
     // Split on underscores to preserve them literally
@@ -55,6 +94,17 @@ export function pascal(s) {
     }
     return out;
 }
+/**
+ * Resolves a qualified name (QName) to its namespace and local parts
+ *
+ * XML uses qualified names (prefix:localName) to reference elements in namespaces.
+ * This function resolves the prefix to its full namespace URI using the provided prefixes map.
+ *
+ * @param {string} qname - Qualified name (e.g., "xs:string" or "myPrefix:elementName")
+ * @param {string} defaultNS - Default namespace to use if no prefix is present
+ * @param {Record<string, string>} prefixes - Map of namespace prefixes to full URIs
+ * @returns {{ns: string, local: string}} - Object containing namespace URI and local name
+ */
 export function resolveQName(qname, defaultNS, prefixes) {
     if (!qname)
         return { ns: defaultNS, local: "" };
@@ -66,7 +116,18 @@ export function resolveQName(qname, defaultNS, prefixes) {
     }
     return { ns: defaultNS, local: qname };
 }
-/** Derive a SOAP client class name from CompilerOptions and compiled catalog. */
+/**
+ * Derives a SOAP client class name from various sources
+ *
+ * This function uses a hierarchy of sources to determine an appropriate class name:
+ * 1. Explicit override from compiler options (highest priority)
+ * 2. Service name from the WSDL document
+ * 3. WSDL filename without extension
+ * 4. Default fallback name ("GeneratedSOAPClient")
+ *
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog
+ * @returns {string} - Appropriate class name for the generated SOAP client
+ */
 export function deriveClientName(compiled) {
     const overrideName = (compiled.options.clientName || "").trim();
     const svcName = compiled.serviceName ? pascal(compiled.serviceName) : "";
@@ -79,7 +140,15 @@ export function deriveClientName(compiled) {
     return overrideName
         || ((svcName || fileBase) ? `${svcName || fileBase}` : "GeneratedSOAPClient");
 }
-/** Explode a PascalCase string into its constituent segments. */
+/**
+ * Explodes a PascalCase string into its constituent segments
+ *
+ * This function breaks a PascalCase identifier into individual words
+ * by inserting underscores at camelCase transitions and then splitting.
+ *
+ * @param {string} s - PascalCase string to explode
+ * @returns {string[]} - Array of individual segments
+ */
 export function explodePascal(s) {
     // insert underscores between camel‐transitions
     const withUnderscores = String(s)
@@ -87,7 +156,16 @@ export function explodePascal(s) {
         .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2');
     return withUnderscores.split('_').filter(Boolean);
 }
-/** Convert a PascalCase string to snake_case (lowercase + underscores). */
+/**
+ * Convert a PascalCase string to snake_case (lowercase + underscores).
+ *
+ * This function takes a PascalCase string, explodes it into its component segments,
+ * converts each segment to lowercase, and joins them with underscores to form a
+ * snake_case string.
+ *
+ * @param {string} s - PascalCase string to convert
+ * @returns {string} - snake_case version of the input string
+ */
 export function pascalToSnakeCase(s) {
     return explodePascal(s)
         .map(seg => seg.toLowerCase())

package/dist/xsd/primitives.d.ts

@@ -1,8 +1,41 @@
+/**
+ * XSD to TypeScript Primitive Type Mapping
+ *
+ * This module defines how XML Schema (XSD) primitive types are mapped to TypeScript types.
+ * It provides a configurable mapping system with safe defaults that prioritizes
+ * data integrity over convenience:
+ *
+ * Key design decisions:
+ * - 64-bit integers (long/unsignedLong) default to string to prevent overflow in JavaScript number
+ * - Arbitrary-precision decimal types default to string to prevent loss of precision
+ * - Date/time types default to string (no automatic Date parsing/conversion)
+ * - Configurable options allow users to override defaults when appropriate for their use case
+ */
+/**
+ * Configuration options for XSD primitive type mapping
+ *
+ * @interface PrimitiveOptions
+ * @property {string} [int64As] - How to map xs:long/xs:unsignedLong (default: "string")
+ * @property {string} [bigIntegerAs] - How to map xs:integer family (default: "string")
+ * @property {string} [decimalAs] - How to map xs:decimal (default: "string")
+ * @property {string} [dateAs] - How to map xs:date/xs:time family (default: "string")
+ */
 export type PrimitiveOptions = {
     int64As?: "string" | "number" | "bigint";
     bigIntegerAs?: "string" | "number";
     decimalAs?: "string" | "number";
     dateAs?: "string" | "Date";
 };
+/**
+ * Maps an XSD QName to the corresponding TypeScript primitive type
+ *
+ * This function is the main entry point for determining the TypeScript type
+ * corresponding to an XSD primitive type. It uses the local part of the QName
+ * and the configured mapping options to return the correct TypeScript type.
+ *
+ * @param {string} xsdQName - The XSD QName to map (e.g., "xs:int")
+ * @param {PrimitiveOptions} [options] - Optional custom mapping options
+ * @returns {string} - The corresponding TypeScript primitive type
+ */
 export declare function xsdToTsPrimitive(xsdQName: string, options?: PrimitiveOptions): string;
 //# sourceMappingURL=primitives.d.ts.map

package/dist/xsd/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/xsd/primitives.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,gBAAgB,GAAG;IAC3B,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACzC,YAAY,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC9B,CAAC;AA+EF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAwCrF"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/xsd/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACzC,YAAY,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAChC,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC5B,CAAC;AAgHF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAyCrF"}