@techspokes/typescript-wsdl-client 0.6.2 → 0.7.0

package/dist/emit/typesEmitter.d.ts

@@ -1,11 +1,22 @@
 import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
 /**
- * Emit TypeScript types from a compiled XSD catalog.
+ * Emits TypeScript interfaces and type aliases from a compiled WSDL catalog
  *
- * - Text node is modeled as "$value" (not "value") to avoid collisions with real elements.
- * - xs:complexType + xs:simpleContent/extension is flattened to `extends <BaseType>`.
- * - All properties (attributes and elements) include @xsd JSDoc.
- * - If a "$value" element is present, it is emitted last.
+ * This function generates a TypeScript file containing all the types required to
+ * work with the SOAP service, including:
+ *
+ * - Type aliases for simple types (enums, restrictions, etc.)
+ * - Interfaces for complex types with proper inheritance
+ * - JSDoc annotations with XML metadata for runtime marshalling
+ *
+ * Key design decisions:
+ * - Text node is modeled as "$value" (not "value") to avoid collisions with real elements
+ * - xs:complexType + xs:simpleContent/extension is flattened to `extends <BaseType>`
+ * - All properties (attributes and elements) include @xsd JSDoc
+ * - If a "$value" element is present, it is emitted last
+ *
+ * @param {string} outFile - Path to the output TypeScript file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog
  */
 export declare function emitTypes(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=typesEmitter.d.ts.map

package/dist/emit/typesEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typesEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/typesEmitter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEjF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAgJnE"}
+{"version":3,"file":"typesEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/typesEmitter.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEjF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAgJnE"}

package/dist/emit/typesEmitter.js

@@ -1,11 +1,36 @@
+/**
+ * TypeScript Types Emitter
+ *
+ * This module is responsible for transforming the compiled WSDL catalog into TypeScript
+ * type definitions. It generates interfaces for complex types and type aliases for
+ * simple types, handling features such as:
+ *
+ * - XML attribute flattening (attributes and elements as peer properties)
+ * - Text content as "$value" property
+ * - Type inheritance (extends) for complexContent extensions
+ * - Proper JSDoc annotations for XML metadata
+ * - Consistent property ordering and interface structuring
+ * - Optional/required markers based on XML schema requirements
+ */
 import fs from "node:fs";
 /**
- * Emit TypeScript types from a compiled XSD catalog.
+ * Emits TypeScript interfaces and type aliases from a compiled WSDL catalog
+ *
+ * This function generates a TypeScript file containing all the types required to
+ * work with the SOAP service, including:
+ *
+ * - Type aliases for simple types (enums, restrictions, etc.)
+ * - Interfaces for complex types with proper inheritance
+ * - JSDoc annotations with XML metadata for runtime marshalling
+ *
+ * Key design decisions:
+ * - Text node is modeled as "$value" (not "value") to avoid collisions with real elements
+ * - xs:complexType + xs:simpleContent/extension is flattened to `extends <BaseType>`
+ * - All properties (attributes and elements) include @xsd JSDoc
+ * - If a "$value" element is present, it is emitted last
  *
- * - Text node is modeled as "$value" (not "value") to avoid collisions with real elements.
- * - xs:complexType + xs:simpleContent/extension is flattened to `extends <BaseType>`.
- * - All properties (attributes and elements) include @xsd JSDoc.
- * - If a "$value" element is present, it is emitted last.
+ * @param {string} outFile - Path to the output TypeScript file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog
  */
 export function emitTypes(outFile, compiled) {
     const lines = [];

package/dist/emit/utilsEmitter.d.ts

@@ -1,3 +1,21 @@
 import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
+/**
+ * Emits utility types and constants for XML serialization/deserialization
+ *
+ * This function generates a TypeScript file containing metadata mappings that help
+ * the SOAP client distinguish between XML attributes and child elements during
+ * the conversion process. It exports:
+ *
+ * 1. A DataTypes interface defining the structure of the metadata
+ * 2. A constant containing the actual mappings extracted from the compiled catalog
+ *
+ * The metadata is critical for proper XML marshalling and unmarshalling, as it enables
+ * the client to correctly handle XML attributes vs. child elements, maintain type information
+ * during recursive processing, and ensure that the XML structure matches the WSDL specification.
+ *
+ * @param {string} outFile - Path to the output TypeScript file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing metadata
+ * @throws {Error} If metadata is missing or has an invalid structure
+ */
 export declare function emitUtils(outFile: string, compiled: CompiledCatalog): void;
 //# sourceMappingURL=utilsEmitter.d.ts.map

package/dist/emit/utilsEmitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilsEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/utilsEmitter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAGnE,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAiCnE"}
+{"version":3,"file":"utilsEmitter.d.ts","sourceRoot":"","sources":["../../src/emit/utilsEmitter.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAGnE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,QAiCnE"}

package/dist/emit/utilsEmitter.js

@@ -1,5 +1,35 @@
+/**
+ * TypeScript SOAP Client Utilities Emitter
+ *
+ * This module generates utility types and constants needed for the TypeScript SOAP client
+ * to properly handle XML serialization and deserialization. It creates metadata mappings
+ * that enable the client to distinguish between XML attributes and child elements during
+ * the conversion process between TypeScript objects and XML.
+ *
+ * The generated utilities include:
+ * - A DataTypes interface defining the structure of the metadata
+ * - A constant containing the actual metadata mappings extracted from the compiled catalog
+ */
 import fs from "node:fs";
 import { deriveClientName, pascalToSnakeCase } from "../util/tools.js";
+/**
+ * Emits utility types and constants for XML serialization/deserialization
+ *
+ * This function generates a TypeScript file containing metadata mappings that help
+ * the SOAP client distinguish between XML attributes and child elements during
+ * the conversion process. It exports:
+ *
+ * 1. A DataTypes interface defining the structure of the metadata
+ * 2. A constant containing the actual mappings extracted from the compiled catalog
+ *
+ * The metadata is critical for proper XML marshalling and unmarshalling, as it enables
+ * the client to correctly handle XML attributes vs. child elements, maintain type information
+ * during recursive processing, and ensure that the XML structure matches the WSDL specification.
+ *
+ * @param {string} outFile - Path to the output TypeScript file
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing metadata
+ * @throws {Error} If metadata is missing or has an invalid structure
+ */
 export function emitUtils(outFile, compiled) {
     const clientName = deriveClientName(compiled);
     const clientConstant = pascalToSnakeCase(clientName).toUpperCase();

package/dist/index.d.ts

@@ -1,4 +1,26 @@
 import type { CompilerOptions } from "./config.js";
+export { generateOpenAPI } from "./openapi/generateOpenAPI.js";
+export { runGenerationPipeline } from "./pipeline.js";
+/**
+ * Compiles a WSDL file to TypeScript client code
+ *
+ * This function is the main programmatic entry point for generating TypeScript
+ * client code from a WSDL file. It performs the full compilation process:
+ *
+ * 1. Loading and parsing the WSDL document
+ * 2. Compiling the WSDL into a structured catalog
+ * 3. Generating TypeScript artifacts (client, types, utilities)
+ * 4. Optionally emitting a JSON catalog for introspection
+ *
+ * The function ensures the output directory exists and handles errors properly.
+ *
+ * @param {Object} input - Input configuration
+ * @param {string} input.wsdl - Path or URL to the WSDL file
+ * @param {string} input.outDir - Output directory for generated code
+ * @param {CompilerOptions} [input.options] - Optional compiler configuration
+ * @returns {Promise<void>}
+ * @throws {Error} If no schemas or operations are found, or if compilation fails
+ */
 export declare function compileWsdlToProject(input: {
     wsdl: string;
     outDir: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AAUjD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,eAAe,CAAA;CAAE,iBAsDnE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,aAAa,CAAC;AASjD,OAAO,EAAC,eAAe,EAAC,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAC,qBAAqB,EAAC,MAAM,eAAe,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,eAAe,CAAA;CAAE,GACjE,OAAO,CAAC,IAAI,CAAC,CAqDf"}

package/dist/index.js

@@ -1,13 +1,48 @@
+/**
+ * TypeScript WSDL Client Generator - API Entry Point
+ *
+ * This module exports the public API for programmatic usage of the TypeScript WSDL client
+ * generator. It provides functions for:
+ *
+ * 1. Compiling WSDL to TypeScript client code (compileWsdlToProject)
+ * 2. Generating OpenAPI specifications from WSDL (generateOpenAPI)
+ * 3. Running the full generation pipeline (runGenerationPipeline)
+ *
+ * These functions provide a way to integrate the generator into other tools and workflows
+ * without relying on the command-line interface.
+ */
 import fs from "node:fs";
 import path from "node:path";
+import { TYPESCRIPT_WSDL_CLIENT_DEFAULT_COMPLIER_OPTIONS } from "./config.js";
 import { loadWsdl } from "./loader/wsdlLoader.js";
 import { compileCatalog } from "./compiler/schemaCompiler.js";
 import { emitTypes } from "./emit/typesEmitter.js";
 import { emitUtils } from "./emit/utilsEmitter.js";
 import { emitCatalog } from "./emit/catalogEmitter.js";
 import { emitClient } from "./emit/clientEmitter.js";
-import { TYPESCRIPT_WSDL_CLIENT_DEFAULT_COMPLIER_OPTIONS } from "./config.js";
+export { generateOpenAPI } from "./openapi/generateOpenAPI.js";
+export { runGenerationPipeline } from "./pipeline.js";
 // noinspection JSUnusedGlobalSymbols
+/**
+ * Compiles a WSDL file to TypeScript client code
+ *
+ * This function is the main programmatic entry point for generating TypeScript
+ * client code from a WSDL file. It performs the full compilation process:
+ *
+ * 1. Loading and parsing the WSDL document
+ * 2. Compiling the WSDL into a structured catalog
+ * 3. Generating TypeScript artifacts (client, types, utilities)
+ * 4. Optionally emitting a JSON catalog for introspection
+ *
+ * The function ensures the output directory exists and handles errors properly.
+ *
+ * @param {Object} input - Input configuration
+ * @param {string} input.wsdl - Path or URL to the WSDL file
+ * @param {string} input.outDir - Output directory for generated code
+ * @param {CompilerOptions} [input.options] - Optional compiler configuration
+ * @returns {Promise<void>}
+ * @throws {Error} If no schemas or operations are found, or if compilation fails
+ */
 export async function compileWsdlToProject(input) {
     // Merge defaults with overrides, always set wsdl+out
     const finalOptions = {

package/dist/loader/fetch.d.ts

@@ -1,3 +1,34 @@
+/**
+ * WSDL Document Fetcher
+ *
+ * This module provides utilities for fetching WSDL and XSD documents from either
+ * HTTP/HTTPS URLs or local file paths. It handles relative paths intelligently by
+ * resolving them against a base directory, which is crucial for processing XSD
+ * imports and includes with relative paths.
+ *
+ * The fetcher supports:
+ * - HTTP/HTTPS URLs (using the global fetch API)
+ * - Absolute file paths
+ * - Relative file paths (resolved against an optional base path)
+ */
+/**
+ * Fetches text content from a URL or file path
+ *
+ * This function retrieves the content of a WSDL or XSD document from either
+ * a remote URL or a local file path. It handles:
+ *
+ * - HTTP/HTTPS URLs (using the global fetch API with appropriate XML headers)
+ * - Absolute local file paths
+ * - Relative paths (resolved against the provided base path)
+ *
+ * This is a key component for resolving schema imports and includes, which may
+ * use relative paths to reference other schema documents.
+ *
+ * @param {string} urlOrPath - URL or file path to fetch
+ * @param {string} [base] - Optional base directory/URL for resolving relative paths
+ * @returns {Promise<{uri: string, text: string}>} - Object containing resolved URI and text content
+ * @throws {Error} - If HTTP request fails or file cannot be read
+ */
 export declare function fetchText(urlOrPath: string, base?: string): Promise<{
     uri: string;
     text: string;

package/dist/loader/fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/loader/fetch.ts"],"names":[],"mappings":"AAGA,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAcxG"}
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/loader/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAcxG"}

package/dist/loader/fetch.js

@@ -1,5 +1,36 @@
+/**
+ * WSDL Document Fetcher
+ *
+ * This module provides utilities for fetching WSDL and XSD documents from either
+ * HTTP/HTTPS URLs or local file paths. It handles relative paths intelligently by
+ * resolving them against a base directory, which is crucial for processing XSD
+ * imports and includes with relative paths.
+ *
+ * The fetcher supports:
+ * - HTTP/HTTPS URLs (using the global fetch API)
+ * - Absolute file paths
+ * - Relative file paths (resolved against an optional base path)
+ */
 import fs from "node:fs";
 import path from "node:path";
+/**
+ * Fetches text content from a URL or file path
+ *
+ * This function retrieves the content of a WSDL or XSD document from either
+ * a remote URL or a local file path. It handles:
+ *
+ * - HTTP/HTTPS URLs (using the global fetch API with appropriate XML headers)
+ * - Absolute local file paths
+ * - Relative paths (resolved against the provided base path)
+ *
+ * This is a key component for resolving schema imports and includes, which may
+ * use relative paths to reference other schema documents.
+ *
+ * @param {string} urlOrPath - URL or file path to fetch
+ * @param {string} [base] - Optional base directory/URL for resolving relative paths
+ * @returns {Promise<{uri: string, text: string}>} - Object containing resolved URI and text content
+ * @throws {Error} - If HTTP request fails or file cannot be read
+ */
 export async function fetchText(urlOrPath, base) {
     let uri = urlOrPath;
     if (base && !/^https?:/i.test(urlOrPath) && !path.isAbsolute(urlOrPath)) {

package/dist/loader/wsdlLoader.d.ts

@@ -1,14 +1,46 @@
+/**
+ * Represents a single XSD schema document with its associated context
+ *
+ * @interface SchemaDoc
+ * @property {string} uri - Base directory or URL path of the schema document
+ * @property {any} xml - Parsed XML structure of the schema node
+ * @property {string} targetNS - Target namespace of the schema
+ * @property {Record<string, string>} prefixes - Namespace prefix-to-URI mapping for this schema
+ */
 export type SchemaDoc = {
     uri: string;
     xml: any;
     targetNS: string;
     prefixes: Record<string, string>;
 };
+/**
+ * Complete catalog of WSDL and all associated schemas
+ *
+ * @interface WsdlCatalog
+ * @property {string} wsdlUri - URI/path of the source WSDL document
+ * @property {any} wsdlXml - Parsed XML structure of the entire WSDL
+ * @property {SchemaDoc[]} schemas - Array of all schema documents (from WSDL and imports)
+ * @property {Record<string, string>} prefixMap - Global namespace prefix-to-URI mapping
+ */
 export type WsdlCatalog = {
     wsdlUri: string;
     wsdlXml: any;
     schemas: SchemaDoc[];
     prefixMap: Record<string, string>;
 };
+/**
+ * Loads a WSDL document from a URL or file path and resolves all associated schemas
+ *
+ * This function:
+ * 1. Fetches and parses the WSDL document
+ * 2. Extracts namespace information and target namespace
+ * 3. Locates schema definitions in the WSDL types section
+ * 4. Recursively resolves all schema imports and includes
+ * 5. Returns a complete catalog of all schemas for compilation
+ *
+ * @param {string} wsdlUrlOrPath - URL or file path to the WSDL document
+ * @returns {Promise<WsdlCatalog>} - Complete catalog of WSDL and schemas
+ * @throws {Error} - If the document is not a valid WSDL 1.1 file
+ */
 export declare function loadWsdl(wsdlUrlOrPath: string): Promise<WsdlCatalog>;
 //# sourceMappingURL=wsdlLoader.d.ts.map

package/dist/loader/wsdlLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wsdlLoader.d.ts","sourceRoot":"","sources":["../../src/loader/wsdlLoader.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,SAAS,GAAG;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,CAAC;AAIF,wBAAsB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA6B1E"}
+{"version":3,"file":"wsdlLoader.d.ts","sourceRoot":"","sources":["../../src/loader/wsdlLoader.ts"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC,CAAC;AAKF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAqC1E"}

package/dist/loader/wsdlLoader.js

@@ -1,22 +1,53 @@
+/**
+ * WSDL Document Loader and Schema Resolver
+ *
+ * This module handles the loading, parsing, and resolution of WSDL documents and their
+ * associated XSD schemas. It supports both local file paths and remote URLs, recursively
+ * resolving schema includes and imports to build a complete catalog of all schemas
+ * referenced by the WSDL.
+ *
+ * The loader uses fast-xml-parser for XML parsing and handles namespace prefixes,
+ * target namespaces, and schema relationships to prepare a comprehensive representation
+ * for the compiler stage.
+ */
 import { XMLParser } from "fast-xml-parser";
 import { fetchText } from "./fetch.js";
 import path from "node:path";
 // noinspection ES6UnusedImports
 import { getChildrenWithLocalName, normalizeArray } from "../util/tools.js";
+// Configure XML parser to preserve attributes with @_ prefix
 const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
+/**
+ * Loads a WSDL document from a URL or file path and resolves all associated schemas
+ *
+ * This function:
+ * 1. Fetches and parses the WSDL document
+ * 2. Extracts namespace information and target namespace
+ * 3. Locates schema definitions in the WSDL types section
+ * 4. Recursively resolves all schema imports and includes
+ * 5. Returns a complete catalog of all schemas for compilation
+ *
+ * @param {string} wsdlUrlOrPath - URL or file path to the WSDL document
+ * @returns {Promise<WsdlCatalog>} - Complete catalog of WSDL and schemas
+ * @throws {Error} - If the document is not a valid WSDL 1.1 file
+ */
 export async function loadWsdl(wsdlUrlOrPath) {
+    // Fetch and parse the WSDL document
     const { uri: wsdlUri, text } = await fetchText(wsdlUrlOrPath);
     const wsdlXml = parser.parse(text);
+    // Extract the WSDL definitions node (with or without namespace prefix)
     const defs = wsdlXml["wsdl:definitions"] || wsdlXml["definitions"];
     if (!defs)
         throw new Error("Not a WSDL 1.1 file: missing wsdl:definitions");
-    // WSDL-level prefixes
+    // Extract namespace prefixes declared at the WSDL level
     const prefixMap = {};
     for (const [k, v] of Object.entries(defs)) {
         if (k.startsWith("@_xmlns:"))
             prefixMap[k.slice(8)] = String(v);
     }
+    // Extract target namespace from the WSDL
     const tns = defs["@_targetNamespace"] || "";
+    // Locate the types section which contains schema definitions
     const types = defs["wsdl:types"] || defs["types"];
     const schemas = [];
     const visited = new Set(); // de-dupe fetched schema docs by absolute URL/path
@@ -24,6 +55,7 @@ export async function loadWsdl(wsdlUrlOrPath) {
         // Find any <xsd:schema> (prefix-agnostic) directly under wsdl:types
         const rawSchemas = getChildrenWithLocalName(types, "schema");
         const baseDir = path.dirname(wsdlUri);
+        // Process each schema node, resolving imports and includes
         for (const s of rawSchemas) {
             const discovered = await resolveSchema(s, baseDir, visited);
             schemas.push(...discovered);
@@ -32,17 +64,29 @@ export async function loadWsdl(wsdlUrlOrPath) {
     console.log(`[wsdl] types->schemas: ${schemas.length}`);
     return { wsdlUri, wsdlXml, schemas, prefixMap: { ...prefixMap, tns } };
 }
+/**
+ * Recursively resolves a schema node and all its imports and includes
+ *
+ * This function processes a schema node, extracts its namespace information,
+ * and recursively fetches and resolves any imported or included schemas.
+ *
+ * @param {any} schemaNode - The XML schema node to process
+ * @param {string} baseDir - Base directory/URL for resolving relative paths
+ * @param {Set<string>} visited - Set of already processed schema URIs to prevent cycles
+ * @returns {Promise<SchemaDoc[]>} - Array of resolved schema documents
+ */
 async function resolveSchema(schemaNode, baseDir, visited) {
     const out = [];
+    // Extract target namespace and prefix declarations
     const targetNS = schemaNode["@_targetNamespace"] || "";
     const prefixes = {};
     for (const [k, v] of Object.entries(schemaNode)) {
         if (k.startsWith("@_xmlns:"))
             prefixes[k.slice(8)] = String(v);
     }
-    // Record the inlined schema from the WSDL (no own URI; inherit baseDir)
+    // Add this schema to the output collection
     out.push({ uri: baseDir, xml: schemaNode, targetNS, prefixes });
-    // includes/imports (prefix-agnostic)
+    // Process <include> elements (schemas from same namespace)
     for (const inc of getChildrenWithLocalName(schemaNode, "include")) {
         const loc = inc?.["@_schemaLocation"];
         if (!loc)
@@ -50,6 +94,7 @@ async function resolveSchema(schemaNode, baseDir, visited) {
         const more = await fetchAndResolveSchemaDoc(loc, baseDir, visited);
         out.push(...more);
     }
+    // Process <import> elements (schemas from different namespaces)
     for (const imp of getChildrenWithLocalName(schemaNode, "import")) {
         const loc = imp?.["@_schemaLocation"];
         if (!loc)
@@ -59,30 +104,56 @@ async function resolveSchema(schemaNode, baseDir, visited) {
     }
     return out;
 }
+/**
+ * Fetches and resolves an external schema document
+ *
+ * This function fetches an external schema document from a URL or file path,
+ * parses it, and recursively resolves any imports or includes it contains.
+ *
+ * @param {string} schemaLocation - URL or file path to the schema document
+ * @param {string} baseDir - Base directory/URL for resolving relative paths
+ * @param {Set<string>} visited - Set of already processed schema URIs to prevent cycles
+ * @returns {Promise<SchemaDoc[]>} - Array of resolved schema documents
+ */
 async function fetchAndResolveSchemaDoc(schemaLocation, baseDir, visited) {
+    // Fetch and parse the schema document
     const { uri, text } = await fetchText(schemaLocation, baseDir);
     const docKey = uri;
+    // Skip if already processed to prevent infinite recursion
     if (visited.has(docKey))
         return [];
     visited.add(docKey);
     const sx = parser.parse(text);
-    // The fetched document may contain one or more <schema> nodes at the root (prefix-agnostic).
+    // The fetched document may contain one or more <schema> nodes at the root (prefix-agnostic)
     const roots = getChildrenWithLocalName(sx, "schema");
     const docs = [];
+    // Process each schema node in the document
     for (const sn of roots) {
+        // Extract target namespace and prefix declarations
         const tns = sn["@_targetNamespace"] || "";
         const prefixes = {};
         for (const [k, v] of Object.entries(sn)) {
             if (k.startsWith("@_xmlns:"))
                 prefixes[k.slice(8)] = String(v);
         }
+        // Add this schema to the output collection
         const thisDir = path.dirname(uri);
         docs.push({ uri: thisDir, xml: sn, targetNS: tns, prefixes });
-        // Recurse into nested includes/imports of this external schema
-        const nested = await resolveSchema(sn, thisDir, visited);
-        // resolveSchema already pushed the 'sn'; but here we’ve just pushed it ourselves.
-        // Merge only the *children* discovered by resolveSchema to avoid duplicate heads.
-        docs.push(...nested.slice(1));
+        // Recursively process any imports and includes
+        for (const inc of getChildrenWithLocalName(sn, "include")) {
+            const loc = inc?.["@_schemaLocation"];
+            if (!loc)
+                continue;
+            const more = await fetchAndResolveSchemaDoc(loc, thisDir, visited);
+            docs.push(...more);
+        }
+        for (const imp of getChildrenWithLocalName(sn, "import")) {
+            const loc = imp?.["@_schemaLocation"];
+            if (!loc)
+                continue;
+            const more = await fetchAndResolveSchemaDoc(loc, thisDir, visited);
+            docs.push(...more);
+        }
     }
     return docs;
 }

package/dist/openapi/buildPaths.d.ts

@@ -0,0 +1,74 @@
+/**
+ * OpenAPI Paths Builder
+ *
+ * This module transforms WSDL operations into OpenAPI 3.1 paths and operations.
+ * It bridges the gap between SOAP's operation-centric model and REST's resource-oriented
+ * approach by mapping each SOAP operation to a corresponding REST endpoint.
+ *
+ * Key features:
+ * - Converts WSDL operations to RESTful paths with configurable styles
+ * - Supports operation-specific overrides for methods, descriptions, etc.
+ * - Handles security requirements and header parameters
+ * - Organizes operations into tags for better API documentation
+ * - Properly links request/response schemas to the components section
+ */
+import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
+import type { PathStyle } from "./casing.js";
+/**
+ * Schema for operation overrides file
+ *
+ * This interface defines the structure of the optional JSON file that can
+ * provide operation-specific overrides for method, deprecation status,
+ * and documentation.
+ *
+ * @interface OpsOverridesFile
+ * @property {string} [method] - HTTP method to use (post, get, put, patch, delete)
+ * @property {boolean} [deprecated] - Whether to mark the operation as deprecated
+ * @property {string} [summary] - Short summary for the operation
+ * @property {string} [description] - Detailed description for the operation
+ */
+export interface OpsOverridesFile {
+    [opName: string]: {
+        method?: string;
+        deprecated?: boolean;
+        summary?: string;
+        description?: string;
+    };
+}
+/**
+ * Schema for operation to tag mapping file
+ *
+ * This interface defines the structure of the optional JSON file that maps
+ * operation names to tags for better organization in the OpenAPI specification.
+ *
+ * @interface TagsMappingFile
+ * @property {string} string Tag name to assign to the operation
+ */
+export interface TagsMappingFile {
+    [opName: string]: string;
+}
+/**
+ * Options for building OpenAPI paths
+ *
+ * @interface BuildPathsOptions
+ * @property {string} [basePath] - Base path prefix for all operations (e.g., /v1/soap)
+ * @property {PathStyle} pathStyle - Style for converting operation names to path segments
+ * @property {string} defaultMethod - Default HTTP method for operations
+ * @property {TagsMappingFile} [tagsMap] - Mapping of operation names to tags
+ * @property {OpsOverridesFile} [overrides] - Operation-specific overrides
+ * @property {string} defaultTag - Default tag for operations without explicit tags
+ * @property {Record<string, any[]>} opSecurity - Operation-specific security requirements
+ * @property {Record<string, string[]>} opHeaderParameters - Operation-specific header parameters
+ */
+export interface BuildPathsOptions {
+    basePath?: string;
+    pathStyle: PathStyle;
+    defaultMethod: string;
+    tagsMap?: TagsMappingFile;
+    overrides?: OpsOverridesFile;
+    defaultTag: string;
+    opSecurity: Record<string, any[] | undefined>;
+    opHeaderParameters: Record<string, string[]>;
+}
+export declare function buildPaths(compiled: CompiledCatalog, opts: BuildPathsOptions): Record<string, any>;
+//# sourceMappingURL=buildPaths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildPaths.d.ts","sourceRoot":"","sources":["../../src/openapi/buildPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAG3C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,MAAM,EAAE,MAAM,GAAG;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAE9B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;IAC9C,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9C;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,iBAAiB,uBAyD5E"}