TypeScript WSDL Client

Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways from WSDL/XSD definitions.

Use This If You Need

• TypeScript-first SOAP clients with full type safety
• OpenAPI 3.1 specs that mirror your TypeScript types
• REST gateway over SOAP with automatic request/response transformation
• CI-friendly deterministic output for safe regeneration in version control
• WSDL/XSD documentation propagated into generated comments and OpenAPI descriptions

Quick Start

Installation

npm install --save-dev @techspokes/typescript-wsdl-client
npm install soap

Requirements: Node.js 20+ and the soap package as a runtime dependency.

Generate a Complete Stack

npx wsdl-tsc pipeline \
  --wsdl-source examples/minimal/weather.wsdl \
  --client-dir ./tmp/client \
  --openapi-file ./tmp/openapi.json \
  --gateway-dir ./tmp/gateway \
  --gateway-service-name weather \
  --gateway-version-prefix v1 \
  --init-app

This parses the WSDL, generates a typed SOAP client, creates an OpenAPI 3.1 spec, builds Fastify gateway handlers, and creates a runnable application.

Run and Test

cd tmp/app && npm install && cp .env.example .env && npm start

curl http://localhost:3000/health
curl http://localhost:3000/openapi.json | jq .
curl -X POST http://localhost:3000/get-weather-information \
  -H "Content-Type: application/json" -d '{}'

What You Get

| Output | Files | Purpose | |--------|-------|---------| | TypeScript Client | client.ts, types.ts, utils.ts, operations.ts | Typed SOAP operations and mockable operations interface | | OpenAPI 3.1 Spec | openapi.json or .yaml | REST API documentation | | Fastify Gateway | plugin.ts, routes/, schemas/ | Production REST handlers | | Catalog | catalog.json | Compiled WSDL (debuggable, cacheable) |

Testing With Generated Code

The generated operations.ts provides a typed interface for mocking the SOAP client without importing the concrete class or the soap package:

import type { WeatherOperations } from "./generated/client/operations.js";

const mockClient: WeatherOperations = {
  GetCityWeatherByZIP: async (args) => ({
    response: { GetCityWeatherByZIPResult: { Success: true, City: "Test" } },
    headers: {},
  }),
  // ... other operations
};

// Use with the gateway plugin
import Fastify from "fastify";
import { weatherGateway } from "./generated/gateway/plugin.js";

const app = Fastify();
await app.register(weatherGateway, { client: mockClient, prefix: "/v1/weather" });

See Testing Guide for integration test patterns and mock examples.

Commands

| Command | Purpose | |---------|---------| | pipeline | Full stack generation (recommended) | | client | TypeScript SOAP client only | | openapi | OpenAPI 3.1 spec only | | gateway | Fastify REST gateway from OpenAPI | | app | Runnable Fastify application | | compile | Parse WSDL to catalog.json (advanced) |

See CLI Reference for all flags and examples.

Documentation

| Guide | Description | |-------|-------------| | CLI Reference | All 6 commands with flags and examples | | Programmatic API | TypeScript functions for build tools | | Core Concepts | Flattening, $value, primitives, determinism | | Gateway Guide | Fastify integration and error handling | | Configuration | Security, tags, operations config files | | Production Guide | CI/CD, validation, logging, limitations | | Testing Guide | Testing patterns and mock client examples | | Troubleshooting | Common issues and debugging | | Working With Generated Code | Using clients and types | | Architecture | Internal pipeline for contributors | | Migration Guide | Upgrading between versions |

Contributing

See CONTRIBUTING.md for development setup, project structure, and guidelines.

License

MIT. See LICENSE for full text. Generated artifacts are fully yours with no restrictions or attribution required.

Links

• npm
• Issues
• Discussions
• Changelog
• Roadmap
• Security
• Support
• Sponsor

Vendor: TechSpokes. Maintainer: Serge Liatko (@sergeliatko).