Node.js SOAP Client and Server

Common errors

• TypeError: soap.createClientAsync is not a function

  cause This error typically indicates an incorrect import statement (e.g., using CommonJS `require` syntax with an ESM module) or incorrect destructuring of the imported module.
  fix Ensure you are using `import { createClientAsync } from 'soap';` in ESM contexts. If your project uses CommonJS, you might need to use `const soap = require('soap');` and then `soap.createClientAsync` or check module compatibility.

• Error: WSDL not found: [your-wsdl-url]

  cause The provided WSDL URL is inaccessible, incorrect, or the network connection to it is failing. This can also occur if the WSDL requires specific authentication headers that were not applied before `createClientAsync` attempts to fetch it.
  fix Verify the WSDL URL is correct and publicly accessible from your Node.js environment. Check network connectivity, proxy settings, and any required HTTP authentication that might be necessary to retrieve the WSDL.

• SOAP Fault: <faultcode>...</faultcode><faultstring>...</faultstring>

  cause This is an application-level error returned by the SOAP web service itself, indicating a problem with the request parameters, business logic, or an internal server-side issue.
  fix Examine the `faultstring` and `faultcode` within the error message for specific details. Review your request arguments against the service's WSDL documentation for expected inputs. Use `client.lastRequest` to inspect the exact XML sent to the server.

• TypeError: client.yourMethodName is not a function

  cause The method name you are attempting to call is either incorrect, case-sensitive, or the WSDL was not fully parsed, meaning the client object does not recognize that method.
  fix Verify the method name against the WSDL (use `client.describe()` to programmatically see available services, ports, and methods). Ensure the client was successfully created and the WSDL fully loaded before attempting to call methods.

Warnings

• breaking The package now officially requires Node.js version 20.19.0 or higher. Running on older Node.js versions may lead to unexpected errors, build failures, or compatibility issues.
  Fix: Upgrade your Node.js environment to version 20.19.0 or later to ensure compatibility and stability.
• gotcha The internal URL parsing mechanism was updated in v1.9.0 to use the modern WHATWG URL API, replacing the deprecated `url.parse`. While this generally improves compliance with web standards, it might introduce subtle behavioral differences for malformed or non-standard WSDL/endpoint URLs that previously worked under `url.parse`'s more lenient parsing.
  Fix: Ensure that all WSDL and SOAP endpoint URLs are well-formed and adhere to WHATWG URL standards. Thoroughly test existing integrations after upgrading.
• gotcha Several transitive dependencies, including `glob`, `js-yaml`, `qs`, and `body-parser`, have received security updates across various minor versions. While `node-soap` addresses these promptly, users should regularly update their `node-soap` package to mitigate potential supply chain vulnerabilities from these underlying libraries.
  Fix: Keep `node-soap` updated to the latest minor or patch version using `npm update soap` to ensure you benefit from the most recent security fixes.
• gotcha The `lodash` dependency was entirely removed in version 1.7.0 to reduce the package's footprint. If your project indirectly relied on `lodash` through `node-soap`'s transitive dependencies for other functionalities, you might now encounter runtime errors.
  Fix: Review your project's direct and indirect `lodash` usage. If necessary, add `lodash` as a direct dependency to your project: `npm install lodash`.

Install

• npm install soap npm
• yarn add soap yarn
• pnpm add soap pnpm

Imports

• createClientAsync
  wrong:

  const { createClientAsync } = require('soap');

  correct:

  import { createClientAsync } from 'soap';

  Preferred for modern async/await patterns to create a SOAP client. The callback-based `createClient` is also available.
• listen
  wrong:

  const { listen } = require('soap');

  correct:

  import { listen } from 'soap';

  Used to create a new SOAP server instance on an existing Node.js HTTP(S) server.
• WSSecurity
  wrong:

  const { WSSecurity } = require('soap');

  correct:

  import { WSSecurity } from 'soap';

  One of several security classes (e.g., BasicAuthSecurity, NTLMSecurity) for configuring SOAP message security.
• Client

  import type { Client } from 'soap';

  Type import for the SOAP client instance, useful for TypeScript projects.

Quickstart

Demonstrates asynchronous SOAP client creation, calling a service method (Add), and basic error handling with security options.

import { createClientAsync, BasicAuthSecurity, Client } from 'soap';

async function consumeWebService() {
  const wsdlUrl = 'http://www.dneonline.com/calculator.asmx?WSDL'; // Public test WSDL
  let client: Client | undefined;
  try {
    client = await createClientAsync(wsdlUrl);
    console.log('SOAP client initialized successfully.');

    // Optional: Add security headers if required by the service
    // client.setSecurity(new BasicAuthSecurity('username', 'password'));

    // You can inspect available methods and types:
    // console.log(client.describe());

    // Call a method, e.g., 'Add' from the Calculator service
    const args = { intA: 10, intB: 5 };
    console.log(`Calling 'Add' method with arguments: ${JSON.stringify(args)}`);
    const result = await client.AddAsync(args);

    console.log('Result from SOAP service (Add):', result[0].AddResult);
  } catch (error) {
    console.error('Error consuming SOAP web service:', error instanceof Error ? error.message : error);
    // For detailed debugging, inspect the last request/response
    if (client) {
      console.error('Last Request (XML):', client.lastRequest);
      console.error('Last Response (XML):', client.lastResponse);
    }
  }
}

consumeWebService();