@techspokes/typescript-wsdl-client 0.6.3 → 0.7.1

package/dist/openapi/buildPaths.js

@@ -0,0 +1,66 @@
+import { toPathSegment } from "./casing.js";
+export function buildPaths(compiled, opts) {
+    const paths = {};
+    const base = normalizeBase(opts.basePath || "/");
+    for (const op of compiled.operations) {
+        const seg = toPathSegment(op.name, opts.pathStyle);
+        const fullPath = (base.endsWith("/") ? base.slice(0, -1) : base) + "/" + seg;
+        const override = opts.overrides?.[op.name] || {};
+        const method = (override.method || opts.defaultMethod || "post").toLowerCase();
+        const tag = opts.tagsMap?.[op.name] || opts.defaultTag;
+        const inputRef = op.inputElement?.local ? { $ref: `#/components/schemas/${op.inputElement.local}` } : { type: "object" };
+        const outputRef = op.outputElement?.local ? { $ref: `#/components/schemas/${op.outputElement.local}` } : { type: "object" };
+        const parameters = [];
+        // Header parameters from security builder
+        const headerParamNames = opts.opHeaderParameters[op.name] || [];
+        for (const pName of headerParamNames) {
+            parameters.push({ $ref: `#/components/parameters/${pName}` });
+        }
+        const operationObject = {
+            operationId: op.name,
+            tags: [tag],
+            requestBody: {
+                required: true,
+                content: {
+                    "application/json": { schema: inputRef }
+                }
+            },
+            responses: {
+                "200": {
+                    description: "Successful SOAP operation response",
+                    content: {
+                        "application/json": { schema: outputRef }
+                    }
+                },
+                default: {
+                    description: "Error response",
+                    content: {
+                        "application/json": { schema: { $ref: "#/components/schemas/ErrorEnvelope" } }
+                    }
+                }
+            },
+        };
+        if (override.summary)
+            operationObject.summary = override.summary;
+        if (override.description)
+            operationObject.description = override.description;
+        if (override.deprecated)
+            operationObject.deprecated = true;
+        if (parameters.length)
+            operationObject.parameters = parameters;
+        const opSec = opts.opSecurity[op.name];
+        if (opSec)
+            operationObject.security = opSec;
+        if (!paths[fullPath])
+            paths[fullPath] = {};
+        paths[fullPath][method] = operationObject;
+    }
+    return paths;
+}
+function normalizeBase(base) {
+    if (!base.startsWith("/"))
+        base = "/" + base;
+    if (base.endsWith("/"))
+        return base;
+    return base;
+}

package/dist/openapi/buildSchemas.d.ts

@@ -0,0 +1,44 @@
+/**
+ * OpenAPI Schema Component Builder
+ *
+ * This module transforms the compiled TypeScript types from the WSDL catalog
+ * into OpenAPI 3.1 schema components. It handles the conversion of complex types,
+ * type aliases, arrays, and primitive types to their JSON Schema equivalents.
+ *
+ * Key features:
+ * - Converts TypeScript interfaces to JSON Schema objects
+ * - Handles type aliases and enumerations
+ * - Supports array types with appropriate item definitions
+ * - Manages property requirements based on XML schema constraints
+ * - Optionally enforces closed schemas with additionalProperties:false
+ * - Can prune schemas that aren't referenced by any operation
+ */
+import type { CompiledCatalog } from "../compiler/schemaCompiler.js";
+/**
+ * Options for building OpenAPI schema components
+ *
+ * @interface BuildSchemasOptions
+ * @property {boolean} [closedSchemas] - Whether to add additionalProperties:false to object schemas
+ * @property {boolean} [pruneUnusedSchemas] - Whether to exclude schemas not referenced by operations
+ */
+export interface BuildSchemasOptions {
+    closedSchemas?: boolean;
+    pruneUnusedSchemas?: boolean;
+}
+export type ComponentsSchemas = Record<string, any>;
+/**
+ * Transforms the compiled WSDL catalog into OpenAPI schema components
+ *
+ * @function buildSchemas
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing types, aliases, and operations
+ * @param {BuildSchemasOptions} opts - Options for schema generation
+ * @returns {ComponentsSchemas} - A record of schema component names to their JSON Schema definitions
+ *
+ * @throws Will throw an error if there are unknown referenced types or bases while building schemas
+ *
+ * @example
+ * // Example usage: building schemas with closed schemas enforcement and unused schema pruning
+ * const schemas = buildSchemas(compiledCatalog, { closedSchemas: true, pruneUnusedSchemas: true });
+ */
+export declare function buildSchemas(compiled: CompiledCatalog, opts: BuildSchemasOptions): ComponentsSchemas;
+//# sourceMappingURL=buildSchemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildSchemas.d.ts","sourceRoot":"","sources":["../../src/openapi/buildSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAgB,eAAe,EAAe,MAAM,+BAA+B,CAAC;AAEhG;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAmIpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,mBAAmB,GAAG,iBAAiB,CA8CpG"}

package/dist/openapi/buildSchemas.js

@@ -0,0 +1,196 @@
+function isLiteralUnion(ts) {
+    // very naive: split by | and ensure each trimmed starts and ends with quotes
+    const parts = ts.split("|").map(p => p.trim()).filter(Boolean);
+    if (!parts.length)
+        return null;
+    if (parts.every(p => /^".*"$/.test(p))) {
+        return parts.map(p => p.slice(1, -1));
+    }
+    return null;
+}
+function primitiveSchema(ts) {
+    switch (ts) {
+        case "string":
+            return { type: "string" };
+        case "number":
+            return { type: "number" };
+        case "boolean":
+            return { type: "boolean" };
+        case "any":
+            return {};
+        default:
+            if (ts.endsWith("[]")) {
+                return { type: "array", items: primitiveSchema(ts.slice(0, -2)) };
+            }
+            return { $ref: `#/components/schemas/${ts}` };
+    }
+}
+function buildAliasSchema(a) {
+    const lit = isLiteralUnion(a.tsType);
+    if (lit) {
+        return { type: "string", enum: lit };
+    }
+    // If alias wraps primitive
+    if (["string", "number", "boolean", "any"].includes(a.tsType) || a.tsType.endsWith("[]")) {
+        return primitiveSchema(a.tsType);
+    }
+    // alias of another complex/alias type -> allOf wrapper preserves name
+    return { allOf: [{ $ref: `#/components/schemas/${a.tsType}` }] };
+}
+function isArrayWrapper(t) {
+    if (t.attrs.length !== 0)
+        return null;
+    if (t.elems.length !== 1)
+        return null;
+    const e = t.elems[0];
+    if (e.max !== "unbounded" && !(e.max > 1))
+        return null;
+    return { itemType: e.tsType };
+}
+function buildComplexSchema(t, closed, knownTypeNames, aliasNames) {
+    // Use knownTypeNames/aliasNames to validate $ref targets so we surface
+    // compiler issues early instead of emitting dangling references in OpenAPI output.
+    function refOrPrimitive(ts) {
+        switch (ts) {
+            case "string":
+                return { type: "string" };
+            case "number":
+                return { type: "number" };
+            case "boolean":
+                return { type: "boolean" };
+            case "any":
+                return {}; // intentionally permissive
+            default:
+                if (ts.endsWith("[]")) {
+                    const inner = ts.slice(0, -2);
+                    return { type: "array", items: refOrPrimitive(inner) };
+                }
+                if (!knownTypeNames.has(ts) && !aliasNames.has(ts)) {
+                    // Fail fast: this indicates a mismatch between schemaCompiler output and OpenAPI builder expectations.
+                    throw new Error(`[openapi] unknown referenced type '${ts}' while building schema '${t.name}'`);
+                }
+                return { $ref: `#/components/schemas/${ts}` };
+        }
+    }
+    const arrayWrap = isArrayWrapper(t);
+    if (arrayWrap) {
+        const item = refOrPrimitive(String(arrayWrap.itemType));
+        return { type: "array", items: item };
+    }
+    const properties = {};
+    const required = [];
+    // attributes
+    for (const a of t.attrs) {
+        properties[a.name] = refOrPrimitive(a.tsType);
+        if (a.use === "required")
+            required.push(a.name);
+    }
+    // elements
+    for (const e of t.elems) {
+        const baseSchema = refOrPrimitive(e.tsType);
+        const isArray = e.max === "unbounded" || (e.max > 1);
+        let schema = baseSchema;
+        if (isArray)
+            schema = { type: "array", items: baseSchema };
+        if (e.nillable) {
+            schema = { anyOf: [schema, { type: "null" }] };
+        }
+        properties[e.name] = schema;
+        if (e.name === "$value") {
+            // never required
+        }
+        else if (e.min >= 1) {
+            required.push(e.name);
+        }
+    }
+    const obj = {
+        type: "object",
+        properties,
+    };
+    if (required.length)
+        obj.required = Array.from(new Set(required));
+    if (closed)
+        obj.additionalProperties = false;
+    // inheritance via base => allOf
+    if (t.base) {
+        const baseName = t.base;
+        // Validate base reference explicitly (using helper ensures error if unknown)
+        if (!knownTypeNames.has(baseName) && !aliasNames.has(baseName)) {
+            throw new Error(`[openapi] unknown base type '${baseName}' while building schema '${t.name}'`);
+        }
+        obj.allOf = [{ $ref: `#/components/schemas/${baseName}` }, { ...obj }];
+        delete obj.type; // inner object part handled in allOf
+        delete obj.properties;
+        if (!required.length)
+            delete obj.required;
+        if (!closed)
+            delete obj.additionalProperties; // put closed only on leaf part
+    }
+    return obj;
+}
+/**
+ * Transforms the compiled WSDL catalog into OpenAPI schema components
+ *
+ * @function buildSchemas
+ * @param {CompiledCatalog} compiled - The compiled WSDL catalog containing types, aliases, and operations
+ * @param {BuildSchemasOptions} opts - Options for schema generation
+ * @returns {ComponentsSchemas} - A record of schema component names to their JSON Schema definitions
+ *
+ * @throws Will throw an error if there are unknown referenced types or bases while building schemas
+ *
+ * @example
+ * // Example usage: building schemas with closed schemas enforcement and unused schema pruning
+ * const schemas = buildSchemas(compiledCatalog, { closedSchemas: true, pruneUnusedSchemas: true });
+ */
+export function buildSchemas(compiled, opts) {
+    const closed = !!opts.closedSchemas;
+    const schemas = {};
+    const typeNames = new Set(compiled.types.map(t => t.name));
+    const aliasNames = new Set(compiled.aliases.map(a => a.name));
+    // Build alias schemas first so complex types can reference them
+    for (const a of compiled.aliases) {
+        schemas[a.name] = buildAliasSchema(a);
+    }
+    for (const t of compiled.types) {
+        schemas[t.name] = buildComplexSchema(t, closed, typeNames, aliasNames);
+    }
+    if (opts.pruneUnusedSchemas) {
+        // Root references: each operation's inputElement.local, outputElement.local
+        const roots = new Set();
+        for (const op of compiled.operations) {
+            if (op.inputElement?.local)
+                roots.add(op.inputElement.local);
+            if (op.outputElement?.local)
+                roots.add(op.outputElement.local);
+        }
+        // BFS through $ref graph
+        const reachable = new Set();
+        const queue = Array.from(roots);
+        while (queue.length) {
+            const cur = queue.shift();
+            if (reachable.has(cur))
+                continue;
+            if (!schemas[cur])
+                continue; // unknown
+            reachable.add(cur);
+            const scan = (node) => {
+                if (!node || typeof node !== "object")
+                    return;
+                if (node.$ref) {
+                    const name = node.$ref.split("/").pop();
+                    if (name && !reachable.has(name))
+                        queue.push(name);
+                }
+                for (const v of Object.values(node))
+                    scan(v);
+            };
+            scan(schemas[cur]);
+        }
+        // prune
+        for (const k of Object.keys(schemas)) {
+            if (!reachable.has(k))
+                delete schemas[k];
+        }
+    }
+    return schemas;
+}

package/dist/openapi/casing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Path Segment Styling for OpenAPI Generation
+ *
+ * This module provides utilities for converting operation names to appropriately styled
+ * path segments in the OpenAPI specification. It supports multiple styling options to
+ * accommodate different API design preferences:
+ *
+ * - kebab-case: Transforms "GetUserDetails" to "get-user-details"
+ * - as-is: Preserves the original operation name without modification
+ * - lowercase: Converts to lowercase and removes all non-alphanumeric characters
+ *
+ * These transformations ensure that the generated API paths follow consistent conventions
+ * and are properly formatted for RESTful API design.
+ */
+/**
+ * Path segment styling options for OpenAPI generation
+ *
+ * @property {"kebab"} string Convert to kebab-case (e.g., "get-user-details")
+ * @property {"asis"} string Keep the original operation name unchanged
+ * @property {"lower"} string Convert to lowercase and remove non-alphanumeric characters
+ */
+export type PathStyle = "kebab" | "asis" | "lower";
+/**
+ * Converts an operation name to a path segment according to the specified style
+ *
+ * This function transforms operation names like "GetUserDetails" or "createNewOrder"
+ * into appropriately styled path segments based on the selected style:
+ *
+ * - kebab: "GetUserDetails" → "get-user-details"
+ * - asis: "GetUserDetails" → "GetUserDetails"
+ * - lower: "GetUserDetails" → "getuserdetails"
+ *
+ * @param {string} name - Operation name to convert
+ * @param {PathStyle} style - Path segment style to apply
+ * @returns {string} - Formatted path segment
+ */
+export declare function toPathSegment(name: string, style: PathStyle): string;
+//# sourceMappingURL=casing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"casing.d.ts","sourceRoot":"","sources":["../../src/openapi/casing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAQnD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAepE"}

package/dist/openapi/casing.js

@@ -0,0 +1,49 @@
+/**
+ * Path Segment Styling for OpenAPI Generation
+ *
+ * This module provides utilities for converting operation names to appropriately styled
+ * path segments in the OpenAPI specification. It supports multiple styling options to
+ * accommodate different API design preferences:
+ *
+ * - kebab-case: Transforms "GetUserDetails" to "get-user-details"
+ * - as-is: Preserves the original operation name without modification
+ * - lowercase: Converts to lowercase and removes all non-alphanumeric characters
+ *
+ * These transformations ensure that the generated API paths follow consistent conventions
+ * and are properly formatted for RESTful API design.
+ */
+/**
+ * Regular expression for detecting boundaries between words in camelCase
+ * Matches transitions from lowercase/digit to uppercase letter
+ */
+const CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/g;
+/**
+ * Converts an operation name to a path segment according to the specified style
+ *
+ * This function transforms operation names like "GetUserDetails" or "createNewOrder"
+ * into appropriately styled path segments based on the selected style:
+ *
+ * - kebab: "GetUserDetails" → "get-user-details"
+ * - asis: "GetUserDetails" → "GetUserDetails"
+ * - lower: "GetUserDetails" → "getuserdetails"
+ *
+ * @param {string} name - Operation name to convert
+ * @param {PathStyle} style - Path segment style to apply
+ * @returns {string} - Formatted path segment
+ */
+export function toPathSegment(name, style) {
+    switch (style) {
+        case "asis":
+            return name;
+        case "lower":
+            return name.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
+        case "kebab":
+        default:
+            // insert hyphen between camelCase boundaries then sanitize
+            return name
+                .replace(CAMEL_BOUNDARY, "$1-$2")
+                .replace(/[^A-Za-z0-9]+/g, "-")
+                .replace(/^-+|-+$/g, "")
+                .toLowerCase();
+    }
+}

package/dist/openapi/generateOpenAPI.d.ts

@@ -0,0 +1,61 @@
+import { type CompiledCatalog } from "../compiler/schemaCompiler.js";
+import type { PathStyle } from "./casing.js";
+/**
+ * Options for OpenAPI generation from WSDL
+ *
+ * @interface GenerateOpenAPIOptions
+ * @property {string} [wsdl] - Path or URL to WSDL file (exclusive with catalogFile and compiledCatalog)
+ * @property {string} [catalogFile] - Path to existing compiled catalog.json (exclusive with wsdl and compiledCatalog)
+ * @property {CompiledCatalog} [compiledCatalog] - Pre-compiled catalog in memory (exclusive with wsdl and catalogFile)
+ * @property {string} [outFile] - Output path for generated OpenAPI specification
+ * @property {string} [title] - API title (defaults to derived service name)
+ * @property {string} [version] - API version for info.version (default 0.0.0)
+ * @property {string} [description] - API description
+ * @property {string[]} [servers] - List of server URLs
+ * @property {string} [basePath] - Base path prefix (e.g., /v1/soap)
+ * @property {PathStyle} [pathStyle] - Path segment style: kebab, asis, or lower
+ * @property {string} [defaultMethod] - Default HTTP method: post, get, put, patch, delete
+ * @property {string} [securityConfigFile] - Path to security.json configuration
+ * @property {string} [tagsFile] - Path to tags.json mapping operation names to tags
+ * @property {string} [opsFile] - Path to ops.json with per-operation overrides
+ * @property {boolean} [closedSchemas] - Whether to emit additionalProperties:false
+ * @property {boolean} [pruneUnusedSchemas] - Whether to exclude schemas not referenced by operations
+ * @property {boolean} [asYaml] - Force YAML output regardless of extension (deprecated)
+ * @property {boolean} [validate] - Whether to validate using swagger-parser
+ * @property {"default"|"first"|"service"} [tagStyle] - Heuristic for deriving tags
+ * @property {"json"|"yaml"|"both"} [format] - Output format (default: json)
+ * @property {boolean} [skipValidate] - Skip validation (default: false)
+ * @property {string} [envelopeNamespace] - Namespace segment for envelope (default ResponseEnvelope)
+ * @property {string} [errorNamespace] - Namespace segment for error object (default ErrorObject)
+ */
+export interface GenerateOpenAPIOptions {
+    wsdl?: string;
+    catalogFile?: string;
+    outFile?: string;
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: string[];
+    basePath?: string;
+    pathStyle?: PathStyle;
+    defaultMethod?: string;
+    securityConfigFile?: string;
+    tagsFile?: string;
+    opsFile?: string;
+    closedSchemas?: boolean;
+    pruneUnusedSchemas?: boolean;
+    asYaml?: boolean;
+    validate?: boolean;
+    tagStyle?: "default" | "first" | "service";
+    compiledCatalog?: CompiledCatalog;
+    format?: "json" | "yaml" | "both";
+    skipValidate?: boolean;
+    envelopeNamespace?: string;
+    errorNamespace?: string;
+}
+export declare function generateOpenAPI(opts: GenerateOpenAPIOptions): Promise<{
+    doc: any;
+    jsonPath?: string;
+    yamlPath?: string;
+}>;
+//# sourceMappingURL=generateOpenAPI.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAInF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAyRD"}