@jointly/gen-ts-from-wsdl

A powerful command-line tool and Node.js library to generate TypeScript interfaces and types from WSDL (Web Services Description Language) files for SOAP services.

Features

• 🔄 WSDL Parsing: Parse WSDL files from local paths or URLs
• 📝 TypeScript Generation: Generate clean, typed TypeScript interfaces
• 🏗️ Complex Types Support: Handle complex XML Schema types and nested structures
• 🎯 Simple Types Support: Convert XML Schema simple types with restrictions
• 📨 Message Types: Generate types for SOAP messages
• ⚙️ Operation Interfaces: Optional generation of service operation interfaces
• 📦 Namespace Support: Organize generated types with custom namespaces
• 🔧 CLI & Programmatic: Use as a command-line tool or Node.js library

Installation

Global Installation (CLI)

npm install -g @jointly/gen-ts-from-wsdl

Local Installation (Project Dependency)

npm install @jointly/gen-ts-from-wsdl

yarn add @jointly/gen-ts-from-wsdl

Usage

Command Line Interface

Using npx (No Installation Required)

You can run the tool directly without installing it globally using npx:

npx @jointly/gen-ts-from-wsdl <wsdl-file-or-url> [options]

npx Examples

# Generate types from a local WSDL file
npx @jointly/gen-ts-from-wsdl ./service.wsdl

# Generate types from a URL with custom output
npx @jointly/gen-ts-from-wsdl https://example.com/service.wsdl -o ./types/soap-api.ts

# Generate with namespace and operations
npx @jointly/gen-ts-from-wsdl ./service.wsdl -n ApiTypes --include-operations

# Generate with strict mode for optional properties
npx @jointly/gen-ts-from-wsdl ./service.wsdl --strict

Basic Usage (Global Installation)

gen-ts-from-wsdl <wsdl-file-or-url> [options]

Examples

# Generate types from a local WSDL file
gen-ts-from-wsdl ./service.wsdl

# Generate types from a URL
gen-ts-from-wsdl https://example.com/service.wsdl

# Specify custom output file
gen-ts-from-wsdl ./service.wsdl -o ./generated/soap-types.ts

# Add namespace and include operations
gen-ts-from-wsdl ./service.wsdl -n MyService --include-operations

# Enable strict mode for optional properties
gen-ts-from-wsdl ./service.wsdl --strict

# Disable code prettification
gen-ts-from-wsdl ./service.wsdl --no-prettify

CLI Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --output | -o | Output file path | ./types.ts | | --namespace | -n | Namespace for generated types | (none) | | --include-operations | | Include operation interfaces | false | | --strict | | Enable strict mode for optional properties | false | | --no-prettify | | Disable code prettification | false |

Programmatic Usage

import { WSDLParser, TypeScriptGenerator, GeneratorOptions } from '@jointly/gen-ts-from-wsdl';

async function generateTypes() {
  const parser = new WSDLParser();
  const generator = new TypeScriptGenerator();

  // Parse WSDL
  const parsedWSDL = await parser.parseWSDL('./service.wsdl');

  // Configure generation options
  const options: GeneratorOptions = {
    outputPath: './generated-types.ts',
    namespace: 'MyServiceTypes',
    includeOperations: true,
    prettify: true,
  };

  // Generate TypeScript types
  await generator.writeTypesToFile(parsedWSDL, './generated-types.ts', options);
}

generateTypes().catch(console.error);

Generated Output

The tool generates TypeScript interfaces based on the WSDL schema definitions:

Complex Types

export interface UserInfo {
  id: number;
  name: string;
  email?: string;
  roles: string[];
}

Simple Types with Restrictions

export type UserStatus = 'active' | 'inactive' | 'pending';

export type UserId = string; // Pattern: /^[A-Z]{2}\d{6}$/

Message Types

export interface GetUserRequest {
  userId: string;
}

export interface GetUserResponse {
  user: UserInfo;
  success: boolean;
}

Operation Interfaces (Optional)

export interface UserServiceOperations {
  GetUser(request: GetUserRequest): Promise<GetUserResponse>;
  UpdateUser(request: UpdateUserRequest): Promise<UpdateUserResponse>;
}

Configuration

Generator Options

interface GeneratorOptions {
  outputPath: string;           // Output file path
  namespace?: string;           // Optional namespace wrapper
  includeOperations?: boolean;  // Include operation interfaces
  strict?: boolean;            // Enable strict mode for optional properties
  prettify?: boolean;          // Format generated code
}

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/JointlyTech/gen-ts-from-wsdl.git
cd gen-ts-from-wsdl

# Install dependencies
npm install

# Build the project
npm run build

# Execute the CLI
npm run start

# Or build and start
npm run dev

Scripts

• npm run build - Compile TypeScript to JavaScript

• npm run start - Run the compiled CLI tool

• npm run dev - Compile and run the CLI

• npm run release:patch|minor|major - Release new version

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Contributors

• Pellegrino Durante - @PellegrinoDurante
• Luigi Colombi - @Gigiz

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [email protected]

Made with ❤️ by Jointly