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

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	Typed SOAP operations
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).