WSDL TypeScript Client Generator

Common errors

• TypeError: createClientAsync is not a function

  cause The `soap` package, which provides the `createClientAsync` function at runtime, is not installed as a dependency in the project using the generated client.
  fix Run `npm install soap` or `yarn add soap` in your project's root directory.

• Error: Maximum recursive definition name exceeded. This can lead to very long filenames.

  cause The WSDL contains highly recursive type definitions or many types with very similar names, and `wsdl-tsclient` has reached its limit for creating unique, suffixed names.
  fix Try increasing the limit with the `--maxRecursiveDefinitionName` CLI option (e.g., `wsdl-tsclient ... --maxRecursiveDefinitionName 128`), or consider simplifying the WSDL schema if possible.

• Cannot find module 'soap' or its corresponding type declarations.

  cause TypeScript cannot resolve the `soap` module. This usually means `soap` is not installed, or type declarations for `soap` are missing or not correctly configured in `tsconfig.json`.
  fix Ensure `soap` is installed (`npm i soap`) and, if using TypeScript, that `@types/soap` (if available and needed for an older `soap` version, though `soap` itself often ships types now) is also installed or that `skipLibCheck` is enabled in `tsconfig.json` if type errors persist.

• SyntaxError: Cannot use import statement outside a module

  cause You are trying to run a generated client file (or `wsdl-tsclient` itself) that uses ESM `import` statements in a CommonJS-only Node.js environment without proper configuration (e.g., missing `"type": "module"` in `package.json` for ESM output, or not transpiling to CJS). This is particularly relevant if `--esm` flag was used during generation.
  fix If the generated client is intended for ESM, ensure your `package.json` includes `"type": "module"` or use a bundler/transpiler configured for ESM. If targeting CommonJS, avoid the `--esm` flag during generation or ensure your Node.js environment correctly handles ESM interoperability.

Warnings

• gotcha The `soap` package, which is essential for the runtime functionality of the generated clients, is a peer dependency and must be installed manually alongside `wsdl-tsclient`. Forgetting to install `soap` will lead to runtime errors when attempting to use the generated client.
  Fix: Ensure `npm i soap` or `yarn add soap` is executed in your project where the generated client is consumed.
• breaking Older versions of `soap` (specifically before `^1.0.0`) had tighter constraints, which could cause issues. Version 1.6.0 of `wsdl-tsclient` relaxed these constraints, but it's important to use a compatible version of `soap` (preferably `^1.0.0` or newer) for stability.
  Fix: Upgrade `wsdl-tsclient` to v1.6.0 or newer and ensure your `soap` dependency is `^1.0.0` or a more recent compatible version.
• gotcha When WSDL definitions contain self-recursive or cyclic types, `wsdl-tsclient` might generate `any` types to prevent infinite recursion, potentially losing some type safety in those specific areas. This behavior was introduced to handle complex WSDLs more gracefully.
  Fix: Review generated `any` types for critical data structures and consider manual type refinement if strict type safety is paramount in those specific recursive parts.
• gotcha The `--esm` CLI flag, introduced in v1.7.1, affects how imports are generated in the client code, specifically by adding `.js` suffixes to import paths for better ESM compatibility. Failing to use this flag for projects targeting pure ESM environments might lead to import resolution issues.
  Fix: If targeting ESM-only environments, ensure you use `wsdl-tsclient --esm ...` when generating your client code.
• gotcha WSDL definitions with identical names but different structures can lead to definition collisions. The `--maxRecursiveDefinitionName` option (since v1.2.0) sets a limit on how many times a suffix is added to disambiguate such names. Exceeding this limit will result in an error.
  Fix: Adjust the `--maxRecursiveDefinitionName` CLI option if you encounter errors related to excessive recursive definition names, or refine your WSDL to reduce name collisions.
• gotcha Early versions (before 1.3.1) had issues with generated types missing attributes or having incorrect casing, leading to mismatches with the actual SOAP payload. This could cause runtime failures or incorrect data interpretation.
  Fix: Upgrade `wsdl-tsclient` to version 1.3.1 or later to benefit from improved code generation accuracy for attributes and name casing.

Install

• npm install wsdl-tsclient npm
• yarn add wsdl-tsclient yarn
• pnpm add wsdl-tsclient pnpm

Imports

• generateClient
  wrong:

  const { generateClient } = require('wsdl-tsclient');

  correct:

  import { generateClient } from 'wsdl-tsclient';

  While CommonJS `require` might work in some Node.js environments due to `esModuleInterop` in `tsconfig.json`, explicit ESM `import` is the recommended and modern approach for this TypeScript-first library.
• createClientAsync
  wrong:

  const { createClientAsync } = require('./generated/MyWsdl');

  correct:

  import { createClientAsync } from './generated/MyWsdl';

  This import is for the *generated* client code. If you use the `--esm` CLI flag (available since v1.7.1) for generation, the output imports will include `.js` suffixes. Without it, standard ESM imports are assumed. The `wrong` example shows CommonJS which would fail if the generated code is truly ESM.
• MyServicePort

  import { IMyServicePort } from './generated/MyWsdl/MyServicePort';

  This is an example of importing a generated TypeScript interface for a specific service port, often used for type-checking or mocking. The exact path depends on the WSDL structure and generated file names. The generated files are typically TypeScript and best consumed via `import`.

Quickstart

This example demonstrates how to programmatically generate a TypeScript SOAP client from a WSDL file and then use the generated client to make a call to a (mocked) SOAP service. It includes setup for a dummy WSDL and output directory.

import { generateClient } from 'wsdl-tsclient';
import { createClientAsync } from './generated/MyService'; // This path will vary based on your WSDL
import * as path from 'path';
import * as fs from 'fs';

async function runGenerationAndClient() {
  const wsdlPath = path.resolve(__dirname, 'resources', 'MyService.wsdl');
  const outputPath = path.resolve(__dirname, 'generated');

  // Ensure output directory exists
  if (!fs.existsSync(outputPath)) {
    fs.mkdirSync(outputPath, { recursive: true });
  }

  // Placeholder WSDL content for demonstration
  // In a real scenario, you'd have a physical WSDL file.
  const dummyWsdlContent = `<?xml version="1.0" encoding="UTF-8"?>
<definitions name="MyService" targetNamespace="http://www.example.org/MyService/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
  <types>
    <xsd:schema targetNamespace="http://www.example.org/MyService/">
      <xsd:element name="SayHelloRequest">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="name" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
      <xsd:element name="SayHelloResponse">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="greeting" type="xsd:string"/>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </types>
  <message name="SayHelloRequest">
    <part name="parameters" element="tns:SayHelloRequest"/>
  </message>
  <message name="SayHelloResponse">
    <part name="parameters" element="tns:SayHelloResponse"/>
  </message>
  <portType name="MyService">
    <operation name="SayHello">
      <input message="tns:SayHelloRequest"/>
      <output message="tns:SayHelloResponse"/>
    </operation>
  </portType>
  <binding name="MyServiceSOAP" type="tns:MyService">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="SayHello">
      <soap:operation soapAction="http://www.example.org/MyService/SayHello"/>
      <input>
        <soap:body use="literal"/>
      </input>
      <output>
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>
  <service name="MyService">
    <port name="MyServiceSOAP" binding="tns:MyServiceSOAP">
      <soap:address location="http://localhost:8000/MyService"/>
    </port>
  </service>
</definitions>`;

  // Save dummy WSDL for generation
  const resourcesDir = path.resolve(__dirname, 'resources');
  if (!fs.existsSync(resourcesDir)) {
    fs.mkdirSync(resourcesDir, { recursive: true });
  }
  fs.writeFileSync(wsdlPath, dummyWsdlContent);

  console.log(`Generating client from ${wsdlPath} to ${outputPath}...`);
  await generateClient(wsdlPath, outputPath);
  console.log('Client generated successfully!');

  // Example of using the generated client (requires 'soap' package to be installed)
  // In a real scenario, the 'soap' client would be configured to hit a live endpoint.
  try {
    const client = await createClientAsync(wsdlPath);
    // Assuming the generated client has a 'MyService' service and 'MyServiceSOAP' port
    const result = await client.MyService.MyServiceSOAP.SayHelloAsync({ name: 'World' });
    console.log('SOAP Call Result:', result[0].greeting); // result[0] typically holds the response body
  } catch (error) {
    console.error('Error using generated client (ensure soap is installed and service is running):', error.message);
  }
}

runGenerationAndClient().catch(console.error);