{"id":15236,"library":"soap","title":"Node.js SOAP Client and Server","description":"Node-SOAP is a robust and minimal JavaScript library designed for interacting with SOAP web services, offering both client-side and server-side functionalities. Currently at stable version 1.9.1, the project maintains a regular release cadence focused on dependency updates, security patches, and minor enhancements, typically releasing new versions every few weeks or months. Its key differentiators include comprehensive support for various SOAP security mechanisms such as BasicAuth, WS-Security, and NTLM, and a flexible API that supports both callback-based and modern promise-based interactions with WSDL-defined services. The library ships with TypeScript types, making it well-suited for contemporary Node.js applications. It targets Node.js versions 20.19.0 and higher.","status":"active","version":"1.9.1","language":"javascript","source_language":"en","source_url":"https://github.com/vpulim/node-soap","tags":["javascript","soap","typescript"],"install":[{"cmd":"npm install soap","lang":"bash","label":"npm"},{"cmd":"yarn add soap","lang":"bash","label":"yarn"},{"cmd":"pnpm add soap","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for making HTTP/HTTPS requests to SOAP endpoints.","package":"axios","optional":false},{"reason":"Lightweight XML parser used for handling SOAP envelopes.","package":"sax","optional":false},{"reason":"Required for running the SOAP server functionality.","package":"express","optional":true},{"reason":"Used by the SOAP server to parse incoming request bodies.","package":"body-parser","optional":true}],"imports":[{"note":"Preferred for modern async/await patterns to create a SOAP client. The callback-based `createClient` is also available.","wrong":"const { createClientAsync } = require('soap');","symbol":"createClientAsync","correct":"import { createClientAsync } from 'soap';"},{"note":"Used to create a new SOAP server instance on an existing Node.js HTTP(S) server.","wrong":"const { listen } = require('soap');","symbol":"listen","correct":"import { listen } from 'soap';"},{"note":"One of several security classes (e.g., BasicAuthSecurity, NTLMSecurity) for configuring SOAP message security.","wrong":"const { WSSecurity } = require('soap');","symbol":"WSSecurity","correct":"import { WSSecurity } from 'soap';"},{"note":"Type import for the SOAP client instance, useful for TypeScript projects.","symbol":"Client","correct":"import type { Client } from 'soap';"}],"quickstart":{"code":"import { createClientAsync, BasicAuthSecurity, Client } from 'soap';\n\nasync function consumeWebService() {\n  const wsdlUrl = 'http://www.dneonline.com/calculator.asmx?WSDL'; // Public test WSDL\n  let client: Client | undefined;\n  try {\n    client = await createClientAsync(wsdlUrl);\n    console.log('SOAP client initialized successfully.');\n\n    // Optional: Add security headers if required by the service\n    // client.setSecurity(new BasicAuthSecurity('username', 'password'));\n\n    // You can inspect available methods and types:\n    // console.log(client.describe());\n\n    // Call a method, e.g., 'Add' from the Calculator service\n    const args = { intA: 10, intB: 5 };\n    console.log(`Calling 'Add' method with arguments: ${JSON.stringify(args)}`);\n    const result = await client.AddAsync(args);\n\n    console.log('Result from SOAP service (Add):', result[0].AddResult);\n  } catch (error) {\n    console.error('Error consuming SOAP web service:', error instanceof Error ? error.message : error);\n    // For detailed debugging, inspect the last request/response\n    if (client) {\n      console.error('Last Request (XML):', client.lastRequest);\n      console.error('Last Response (XML):', client.lastResponse);\n    }\n  }\n}\n\nconsumeWebService();","lang":"typescript","description":"Demonstrates asynchronous SOAP client creation, calling a service method (Add), and basic error handling with security options."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.19.0 or later to ensure compatibility and stability.","message":"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.","severity":"breaking","affected_versions":">=1.9.0"},{"fix":"Ensure that all WSDL and SOAP endpoint URLs are well-formed and adhere to WHATWG URL standards. Thoroughly test existing integrations after upgrading.","message":"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.","severity":"gotcha","affected_versions":">=1.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.6.1"},{"fix":"Review your project's direct and indirect `lodash` usage. If necessary, add `lodash` as a direct dependency to your project: `npm install lodash`.","message":"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.","severity":"gotcha","affected_versions":">=1.7.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: soap.createClientAsync is not a function"},{"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.","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.","error":"Error: WSDL not found: [your-wsdl-url]"},{"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.","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.","error":"SOAP Fault: <faultcode>...</faultcode><faultstring>...</faultstring>"},{"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.","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.","error":"TypeError: client.yourMethodName is not a function"}],"ecosystem":"npm"}