@techspokes/typescript-wsdl-client 0.15.0 → 0.15.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +155 -35
- package/dist/gateway/helpers.d.ts +2 -2
- package/docs/README.md +32 -19
- package/docs/migration-playbook.md +237 -0
- package/docs/output-anatomy.md +112 -0
- package/docs/start-here.md +82 -0
- package/docs/supported-patterns.md +62 -0
- package/package.json +7 -3
package/README.md
CHANGED
|
@@ -5,19 +5,32 @@
|
|
|
5
5
|
[](https://www.npmjs.com/package/@techspokes/typescript-wsdl-client)
|
|
6
6
|
[](https://www.npmjs.com/package/@techspokes/typescript-wsdl-client)
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Turn legacy WSDL/SOAP services into typed TypeScript clients and optional REST APIs without hand-maintaining XML mappings.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Created from production integration work at [TechSpokes](https://www.techspokes.com); built for teams modernizing real enterprise SOAP integrations.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
- OpenAPI 3.1 specs that mirror your TypeScript types
|
|
14
|
-
- REST gateway over SOAP with automatic request/response transformation
|
|
15
|
-
- CI-friendly deterministic output for safe regeneration in version control
|
|
16
|
-
- WSDL/XSD documentation propagated into generated comments and OpenAPI descriptions
|
|
12
|
+
## Pick Your Path
|
|
17
13
|
|
|
18
|
-
|
|
14
|
+
| Goal | Command | What you get |
|
|
15
|
+
|------|---------|-------------|
|
|
16
|
+
| Typed SOAP client | `npx wsdl-tsc client` | TypeScript types, typed operations, mockable interface |
|
|
17
|
+
| OpenAPI 3.1 spec | `npx wsdl-tsc openapi` | OpenAPI JSON/YAML generated from WSDL |
|
|
18
|
+
| Full SOAP-to-REST bridge | `npx wsdl-tsc pipeline` | Client + OpenAPI + Fastify gateway + runnable app |
|
|
19
|
+
|
|
20
|
+
See [Start Here](docs/start-here.md) for detailed guidance on choosing a path.
|
|
21
|
+
|
|
22
|
+
## Why Choose This
|
|
23
|
+
|
|
24
|
+
Most tools in this space stop at one layer: a SOAP runtime, type generation, or spec conversion. This package generates the full stack from a single WSDL source.
|
|
19
25
|
|
|
20
|
-
|
|
26
|
+
- Typed client, OpenAPI spec, REST gateway, and runnable app from one command
|
|
27
|
+
- Deterministic output safe for CI regeneration and version control
|
|
28
|
+
- Handles complex inheritance, `xs:attribute`, namespace collisions, nested XSD imports, and choice elements
|
|
29
|
+
- Generated `operations.ts` interface enables testing without importing `soap` or calling a live service
|
|
30
|
+
- OpenAPI is a first-class output, not an afterthought; types, schemas, and descriptions stay aligned
|
|
31
|
+
- MIT licensed; generated code is yours with no attribution required
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
21
34
|
|
|
22
35
|
```bash
|
|
23
36
|
npm install --save-dev @techspokes/typescript-wsdl-client
|
|
@@ -26,25 +39,43 @@ npm install soap
|
|
|
26
39
|
|
|
27
40
|
Requirements: Node.js 20+ and the `soap` package as a runtime dependency.
|
|
28
41
|
|
|
29
|
-
|
|
42
|
+
## Quick Start
|
|
43
|
+
|
|
44
|
+
### Generate a typed client
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npx wsdl-tsc client \
|
|
48
|
+
--wsdl-source examples/minimal/weather.wsdl \
|
|
49
|
+
--client-dir ./generated/client
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
This produces `types.ts`, `client.ts`, `operations.ts`, and `utils.ts` in the output directory.
|
|
53
|
+
|
|
54
|
+
### Generate an OpenAPI spec
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npx wsdl-tsc openapi \
|
|
58
|
+
--wsdl-source examples/minimal/weather.wsdl \
|
|
59
|
+
--openapi-file ./generated/openapi.json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Generate the full stack
|
|
30
63
|
|
|
31
64
|
```bash
|
|
32
65
|
npx wsdl-tsc pipeline \
|
|
33
66
|
--wsdl-source examples/minimal/weather.wsdl \
|
|
34
|
-
--client-dir ./
|
|
35
|
-
--openapi-file ./
|
|
36
|
-
--gateway-dir ./
|
|
67
|
+
--client-dir ./generated/client \
|
|
68
|
+
--openapi-file ./generated/openapi.json \
|
|
69
|
+
--gateway-dir ./generated/gateway \
|
|
37
70
|
--gateway-service-name weather \
|
|
38
71
|
--gateway-version-prefix v1 \
|
|
39
72
|
--init-app
|
|
40
73
|
```
|
|
41
74
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
### Run and Test
|
|
75
|
+
### Run and test
|
|
45
76
|
|
|
46
77
|
```bash
|
|
47
|
-
cd
|
|
78
|
+
cd generated/app && npm install && cp .env.example .env && npm start
|
|
48
79
|
```
|
|
49
80
|
|
|
50
81
|
```bash
|
|
@@ -54,14 +85,75 @@ curl -X POST http://localhost:3000/get-weather-information \
|
|
|
54
85
|
-H "Content-Type: application/json" -d '{}'
|
|
55
86
|
```
|
|
56
87
|
|
|
57
|
-
## What
|
|
88
|
+
## What Gets Generated
|
|
58
89
|
|
|
59
90
|
| Output | Files | Purpose |
|
|
60
91
|
|--------|-------|---------|
|
|
61
|
-
| TypeScript Client | client.ts, types.ts, utils.ts, operations.ts | Typed SOAP operations and mockable
|
|
62
|
-
| OpenAPI 3.1 Spec | openapi.json or .yaml | REST API documentation |
|
|
63
|
-
| Fastify Gateway | plugin.ts, routes/, schemas/ | Production REST handlers |
|
|
64
|
-
| Catalog | catalog.json | Compiled WSDL
|
|
92
|
+
| TypeScript Client | client.ts, types.ts, utils.ts, operations.ts | Typed SOAP operations and mockable interface |
|
|
93
|
+
| OpenAPI 3.1 Spec | openapi.json or .yaml | REST API documentation aligned with TypeScript types |
|
|
94
|
+
| Fastify Gateway | plugin.ts, routes/, schemas/ | Production REST handlers with request/response transform |
|
|
95
|
+
| Catalog | catalog.json | Compiled WSDL metadata, debuggable and cacheable |
|
|
96
|
+
|
|
97
|
+
See [Output Anatomy](docs/output-anatomy.md) for a detailed walkthrough of each file.
|
|
98
|
+
|
|
99
|
+
## When to Use This
|
|
100
|
+
|
|
101
|
+
- You have a WSDL and need typed TypeScript access to its operations
|
|
102
|
+
- You are building a REST API in front of a SOAP backend
|
|
103
|
+
- You want OpenAPI documentation that stays in sync with WSDL changes
|
|
104
|
+
- You need deterministic codegen output safe for CI/CD regeneration
|
|
105
|
+
- You are modernizing a legacy SOAP integration incrementally
|
|
106
|
+
|
|
107
|
+
## When NOT to Use This
|
|
108
|
+
|
|
109
|
+
- You need a generic SOAP server implementation: use `soap` directly
|
|
110
|
+
- You need multi-language SDK generation: use a platform like APIMatic
|
|
111
|
+
- You need API management, rate limiting, or policy enforcement: use an API gateway platform
|
|
112
|
+
- Your SOAP service relies on WS-* standards beyond WS-Security hints (partial support)
|
|
113
|
+
|
|
114
|
+
## Compared to Alternatives
|
|
115
|
+
|
|
116
|
+
### Why not just use soap (node-soap) directly?
|
|
117
|
+
|
|
118
|
+
`soap` is a runtime SOAP client. It gives you dynamic access to WSDL operations but no generated types, no compile-time safety, and no path to REST or OpenAPI. This package generates typed artifacts you can commit, review, and test; then optionally bridges to REST.
|
|
119
|
+
|
|
120
|
+
### Why not use wsdl-tsclient?
|
|
121
|
+
|
|
122
|
+
wsdl-tsclient generates a typed SOAP client. If that is all you need, it is a solid choice. This package goes further: OpenAPI generation, Fastify gateway scaffolding, deterministic CI-friendly output, and a mockable operations interface. Choose wsdl-tsclient for simplicity; choose this package for modernization projects.
|
|
123
|
+
|
|
124
|
+
### Why not use a commercial API gateway?
|
|
125
|
+
|
|
126
|
+
Platform API gateways solve governance, policy, and multi-language SDK generation. This package solves a different problem: developer-owned, code-first modernization of a specific SOAP backend into typed TypeScript and REST. Lower complexity, lower cost, full code ownership.
|
|
127
|
+
|
|
128
|
+
### Comparison matrix
|
|
129
|
+
|
|
130
|
+
| Capability | soap | wsdl-tsclient | wsdl-to-ts | this package |
|
|
131
|
+
|---|---|---|---|---|
|
|
132
|
+
| Actively maintained | yes | stalled | abandoned | yes |
|
|
133
|
+
| Call SOAP from Node | yes | yes | indirect | yes |
|
|
134
|
+
| Generated TypeScript types | limited | yes | yes | yes |
|
|
135
|
+
| Deterministic CI-safe output | no | partial | partial | yes |
|
|
136
|
+
| WSDL to OpenAPI 3.1 | no | no | no | yes |
|
|
137
|
+
| REST gateway generation | no | no | no | yes |
|
|
138
|
+
| Runnable app scaffolding | no | no | no | yes |
|
|
139
|
+
| Mockable operations interface | no | no | no | yes |
|
|
140
|
+
|
|
141
|
+
Data as of April 2026.
|
|
142
|
+
|
|
143
|
+
## Built for Messy WSDLs
|
|
144
|
+
|
|
145
|
+
Real-world WSDL/XSD files are rarely clean. This generator handles patterns that simpler tools skip.
|
|
146
|
+
|
|
147
|
+
- Complex type inheritance with `<xs:extension>` and `<xs:restriction>`, including proper attribute and element merging
|
|
148
|
+
- `xs:attribute` on complex types, flattened into peer properties alongside elements
|
|
149
|
+
- Namespace collisions across multiple XSD imports, resolved deterministically
|
|
150
|
+
- Deep import chains across multiple schema files
|
|
151
|
+
- Configurable strategies for `<xs:choice>` element modeling
|
|
152
|
+
- Correct optionality for nillable fields in both TypeScript and OpenAPI output
|
|
153
|
+
- The `$value` pattern for simple content with attributes, preserving text content alongside attribute properties
|
|
154
|
+
- `ArrayOf*` wrapper types, unwrapped automatically in OpenAPI with runtime bridging
|
|
155
|
+
|
|
156
|
+
See [Core Concepts](docs/concepts.md) and [Supported Patterns](docs/supported-patterns.md) for details.
|
|
65
157
|
|
|
66
158
|
## Testing With Generated Code
|
|
67
159
|
|
|
@@ -75,10 +167,8 @@ const mockClient: WeatherOperations = {
|
|
|
75
167
|
response: { GetCityWeatherByZIPResult: { Success: true, City: "Test" } },
|
|
76
168
|
headers: {},
|
|
77
169
|
}),
|
|
78
|
-
// ... other operations
|
|
79
170
|
};
|
|
80
171
|
|
|
81
|
-
// Use with the gateway plugin
|
|
82
172
|
import Fastify from "fastify";
|
|
83
173
|
import { weatherGateway } from "./generated/gateway/plugin.js";
|
|
84
174
|
|
|
@@ -103,19 +193,48 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
|
|
|
103
193
|
|
|
104
194
|
## Documentation
|
|
105
195
|
|
|
196
|
+
### Evaluate
|
|
197
|
+
|
|
198
|
+
| Guide | Description |
|
|
199
|
+
|-------|-------------|
|
|
200
|
+
| [Start Here](docs/start-here.md) | What this is, who it is for, choose your path |
|
|
201
|
+
| [Supported Patterns](docs/supported-patterns.md) | WSDL/XSD features handled and current limitations |
|
|
202
|
+
| [Output Anatomy](docs/output-anatomy.md) | What gets generated and how to use it |
|
|
203
|
+
|
|
204
|
+
### Adopt
|
|
205
|
+
|
|
206
|
+
| Guide | Description |
|
|
207
|
+
|-------|-------------|
|
|
208
|
+
| [CLI Reference](docs/cli-reference.md) | All commands with flags and examples |
|
|
209
|
+
| [Working With Generated Code](docs/generated-code.md) | Using clients, types, and operations |
|
|
210
|
+
| [Configuration](docs/configuration.md) | Security schemes, tags, operation overrides |
|
|
211
|
+
| [Migration Playbook](docs/migration-playbook.md) | End-to-end SOAP modernization guide |
|
|
212
|
+
|
|
213
|
+
### Operate
|
|
214
|
+
|
|
106
215
|
| Guide | Description |
|
|
107
216
|
|-------|-------------|
|
|
108
|
-
| [CLI Reference](docs/cli-reference.md) | All 6 commands with flags and examples |
|
|
109
|
-
| [Programmatic API](docs/api-reference.md) | TypeScript functions for build tools |
|
|
110
|
-
| [Core Concepts](docs/concepts.md) | Flattening, $value, primitives, determinism |
|
|
111
217
|
| [Gateway Guide](docs/gateway-guide.md) | Fastify integration and error handling |
|
|
112
|
-
| [Configuration](docs/configuration.md) | Security, tags, operations config files |
|
|
113
|
-
| [Production Guide](docs/production.md) | CI/CD, validation, logging, limitations |
|
|
114
218
|
| [Testing Guide](docs/testing.md) | Testing patterns and mock client examples |
|
|
219
|
+
| [Production Guide](docs/production.md) | CI/CD, validation, logging |
|
|
115
220
|
| [Troubleshooting](docs/troubleshooting.md) | Common issues and debugging |
|
|
116
|
-
|
|
221
|
+
|
|
222
|
+
### Extend
|
|
223
|
+
|
|
224
|
+
| Guide | Description |
|
|
225
|
+
|-------|-------------|
|
|
226
|
+
| [Programmatic API](docs/api-reference.md) | TypeScript functions for build tools |
|
|
227
|
+
| [Core Concepts](docs/concepts.md) | Flattening, $value, primitives, determinism |
|
|
117
228
|
| [Architecture](docs/architecture.md) | Internal pipeline for contributors |
|
|
118
|
-
| [Migration
|
|
229
|
+
| [Version Migration](docs/migration.md) | Upgrading between package versions |
|
|
230
|
+
|
|
231
|
+
## Why This Exists
|
|
232
|
+
|
|
233
|
+
This package was created while modernizing production SOAP integrations at [TechSpokes](https://www.techspokes.com). The existing options were: hand-write hundreds of TypeScript DTOs and XML mappings, use untyped runtime SOAP calls, or adopt an enterprise platform we did not need.
|
|
234
|
+
|
|
235
|
+
We built a generator that reads the WSDL contract and produces everything needed to go from legacy SOAP to typed TypeScript and REST, with deterministic output safe for version control and CI.
|
|
236
|
+
|
|
237
|
+
If you are wrapping a vendor SOAP API in a modern service layer, this is the tool we wished existed when we started.
|
|
119
238
|
|
|
120
239
|
## Contributing
|
|
121
240
|
|
|
@@ -128,12 +247,13 @@ MIT. See [LICENSE](LICENSE) for full text. Generated artifacts are fully yours w
|
|
|
128
247
|
## Links
|
|
129
248
|
|
|
130
249
|
- [npm](https://www.npmjs.com/package/@techspokes/typescript-wsdl-client)
|
|
131
|
-
- [Issues](https://github.com/techspokes/typescript-wsdl-client/issues)
|
|
132
|
-
- [Discussions](https://github.com/techspokes/typescript-wsdl-client/discussions)
|
|
133
250
|
- [Changelog](CHANGELOG.md)
|
|
134
251
|
- [Roadmap](ROADMAP.md)
|
|
135
252
|
- [Security](SECURITY.md)
|
|
136
|
-
- [Support](SUPPORT.md)
|
|
137
253
|
- [Sponsor](https://github.com/sponsors/TechSpokes)
|
|
138
254
|
|
|
139
|
-
|
|
255
|
+
Built and maintained by [TechSpokes](https://www.techspokes.com). Created by [Serge Liatko](https://github.com/sergeliatko).
|
|
256
|
+
|
|
257
|
+
- Community help: [GitHub Discussions](https://github.com/techspokes/typescript-wsdl-client/discussions)
|
|
258
|
+
- Bug reports: [GitHub Issues](https://github.com/techspokes/typescript-wsdl-client/issues)
|
|
259
|
+
- Commercial support and integration consulting: [techspokes.com/contact](https://www.techspokes.com/contact/)
|
|
@@ -139,8 +139,8 @@ export declare function buildParamSchemasForOperation(pathItem: any, operation:
|
|
|
139
139
|
* Metadata about the SOAP client for handler generation
|
|
140
140
|
*
|
|
141
141
|
* @interface ClientMeta
|
|
142
|
-
* @property {string} className - Client class name (e.g., "
|
|
143
|
-
* @property {string} decoratorName - Fastify decorator name (e.g., "
|
|
142
|
+
* @property {string} className - Client class name (e.g., "WeatherService")
|
|
143
|
+
* @property {string} decoratorName - Fastify decorator name (e.g., "weatherserviceClient")
|
|
144
144
|
* @property {string} importPath - Import path relative to routes/ directory — for typed route handlers
|
|
145
145
|
* @property {string} typesImportPath - Types import path relative to routes/ directory — for typed route handlers
|
|
146
146
|
* @property {string} pluginImportPath - Import path relative to gateway output directory — used by emitPluginModule()
|
package/docs/README.md
CHANGED
|
@@ -1,20 +1,33 @@
|
|
|
1
1
|
# Documentation
|
|
2
2
|
|
|
3
|
-
Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. The root [README.md](../README.md) Documentation
|
|
4
|
-
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
- [
|
|
8
|
-
- [
|
|
9
|
-
- [
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
- [
|
|
16
|
-
- [
|
|
17
|
-
|
|
3
|
+
Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. The root [README.md](../README.md) Documentation section is the authoritative index with descriptions; the list below is a quick local reference organized by reader intent.
|
|
4
|
+
|
|
5
|
+
## Evaluate
|
|
6
|
+
|
|
7
|
+
- [start-here.md](start-here.md): what this is, who it is for, choose your path
|
|
8
|
+
- [supported-patterns.md](supported-patterns.md): WSDL/XSD features handled and current limitations
|
|
9
|
+
- [output-anatomy.md](output-anatomy.md): what gets generated and how to use it
|
|
10
|
+
|
|
11
|
+
## Adopt
|
|
12
|
+
|
|
13
|
+
- [cli-reference.md](cli-reference.md): all 6 commands with flags and examples
|
|
14
|
+
- [generated-code.md](generated-code.md): using clients, types, and operations
|
|
15
|
+
- [configuration.md](configuration.md): security schemes, tags, operations config files
|
|
16
|
+
- [migration-playbook.md](migration-playbook.md): end-to-end SOAP modernization guide
|
|
17
|
+
|
|
18
|
+
## Operate
|
|
19
|
+
|
|
20
|
+
- [gateway-guide.md](gateway-guide.md): Fastify integration and error handling
|
|
21
|
+
- [testing.md](testing.md): testing patterns and mock client examples
|
|
22
|
+
- [production.md](production.md): CI/CD, validation, logging
|
|
23
|
+
- [troubleshooting.md](troubleshooting.md): common issues and debugging
|
|
24
|
+
|
|
25
|
+
## Extend
|
|
26
|
+
|
|
27
|
+
- [api-reference.md](api-reference.md): programmatic TypeScript API
|
|
28
|
+
- [concepts.md](concepts.md): flattening, `$value`, primitives, determinism
|
|
29
|
+
- [architecture.md](architecture.md): internal pipeline for contributors
|
|
30
|
+
- [migration.md](migration.md): upgrading between package versions
|
|
18
31
|
|
|
19
32
|
## Conventions
|
|
20
33
|
|
|
@@ -25,10 +38,10 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
|
|
|
25
38
|
|
|
26
39
|
## Related
|
|
27
40
|
|
|
28
|
-
- [Root README](../README.md)
|
|
29
|
-
- [CONTRIBUTING.md](../CONTRIBUTING.md)
|
|
30
|
-
- [CHANGELOG.md](../CHANGELOG.md)
|
|
31
|
-
- [examples/](../examples/)
|
|
41
|
+
- [Root README](../README.md): project overview, quick start, and authoritative Documentation section
|
|
42
|
+
- [CONTRIBUTING.md](../CONTRIBUTING.md): development setup and workflow
|
|
43
|
+
- [CHANGELOG.md](../CHANGELOG.md): version history
|
|
44
|
+
- [examples/](../examples/): sample WSDL files and generated output
|
|
32
45
|
|
|
33
46
|
## Not Here
|
|
34
47
|
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
# Migration Playbook
|
|
2
|
+
|
|
3
|
+
A step-by-step guide for modernizing a SOAP API into a typed TypeScript client and REST gateway. This covers the full journey from WSDL to production REST service.
|
|
4
|
+
|
|
5
|
+
For CLI flag details, see [CLI Reference](cli-reference.md). For gateway integration, see [Gateway Guide](gateway-guide.md).
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
The typical migration follows this sequence:
|
|
10
|
+
|
|
11
|
+
1. Generate a typed client and verify operations work
|
|
12
|
+
2. Generate an OpenAPI spec and review the API surface
|
|
13
|
+
3. Generate a REST gateway and test routes
|
|
14
|
+
4. Add authentication, headers, and middleware
|
|
15
|
+
5. Test with typed mocks
|
|
16
|
+
6. Deploy to production
|
|
17
|
+
7. Roll out incrementally
|
|
18
|
+
|
|
19
|
+
You can stop at any step. A typed client alone (step 1) is valuable even if you never build a gateway.
|
|
20
|
+
|
|
21
|
+
## Step 1: Generate and Validate the Client
|
|
22
|
+
|
|
23
|
+
Start by generating a typed client from your WSDL.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx wsdl-tsc client \
|
|
27
|
+
--wsdl-source https://your-service.example.com/service.svc?wsdl \
|
|
28
|
+
--client-dir ./generated/client
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Inspect the generated `types.ts` to confirm that your WSDL types are represented correctly. Check that operation signatures in `operations.ts` match your expectations.
|
|
32
|
+
|
|
33
|
+
Test a single operation to verify connectivity:
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
import { YourService } from "./generated/client/client.js";
|
|
37
|
+
|
|
38
|
+
const client = new YourService({
|
|
39
|
+
source: "https://your-service.example.com/service.svc?wsdl",
|
|
40
|
+
});
|
|
41
|
+
const result = await client.SomeOperation({ /* args */ });
|
|
42
|
+
console.log(result.response);
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
If the WSDL uses authentication, you may need to configure credentials on the underlying `soap` client. See the `soap` package documentation for authentication options.
|
|
46
|
+
|
|
47
|
+
## Step 2: Generate the OpenAPI Spec
|
|
48
|
+
|
|
49
|
+
Once the client types look correct, generate an OpenAPI 3.1 specification.
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npx wsdl-tsc openapi \
|
|
53
|
+
--wsdl-source https://your-service.example.com/service.svc?wsdl \
|
|
54
|
+
--openapi-file ./generated/openapi.json
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Open `openapi.json` and review the paths, request/response schemas, and descriptions. The spec is derived from the same compiled catalog as the TypeScript types, so they stay aligned.
|
|
58
|
+
|
|
59
|
+
Validate the spec with any OpenAPI tool. Built-in validation runs by default; disable with `--openapi-validate false` if you need to inspect an intermediate state.
|
|
60
|
+
|
|
61
|
+
## Step 3: Generate the REST Gateway
|
|
62
|
+
|
|
63
|
+
Generate Fastify route handlers that translate JSON HTTP requests into SOAP calls.
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npx wsdl-tsc gateway \
|
|
67
|
+
--openapi-file ./generated/openapi.json \
|
|
68
|
+
--gateway-dir ./generated/gateway \
|
|
69
|
+
--gateway-service-name your-service \
|
|
70
|
+
--gateway-version-prefix v1
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Or run all stages at once with the `pipeline` command and `--init-app`:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npx wsdl-tsc pipeline \
|
|
77
|
+
--wsdl-source https://your-service.example.com/service.svc?wsdl \
|
|
78
|
+
--client-dir ./generated/client \
|
|
79
|
+
--openapi-file ./generated/openapi.json \
|
|
80
|
+
--gateway-dir ./generated/gateway \
|
|
81
|
+
--gateway-service-name your-service \
|
|
82
|
+
--gateway-version-prefix v1 \
|
|
83
|
+
--init-app
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The generated gateway plugin registers one POST route per WSDL operation. Each route validates the request body, calls the SOAP operation, and returns the response as JSON.
|
|
87
|
+
|
|
88
|
+
## Step 4: Add Authentication and Middleware
|
|
89
|
+
|
|
90
|
+
### Security schemes
|
|
91
|
+
|
|
92
|
+
Create a security configuration file to add authentication to the OpenAPI spec and generated routes.
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"global": {
|
|
97
|
+
"scheme": "bearer",
|
|
98
|
+
"bearer": { "bearerFormat": "JWT" }
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Pass it during generation:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
npx wsdl-tsc pipeline \
|
|
107
|
+
--wsdl-source your-service.wsdl \
|
|
108
|
+
--openapi-security-config-file ./config/security.json \
|
|
109
|
+
...
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
See [Configuration](configuration.md) for all options including per-operation overrides and custom headers.
|
|
113
|
+
|
|
114
|
+
### Custom middleware
|
|
115
|
+
|
|
116
|
+
Add middleware in your application code, not in the generated gateway files. The generated app scaffold (`index.ts`) is the right place for auth verification, logging, CORS, and other cross-cutting concerns.
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
import Fastify from "fastify";
|
|
120
|
+
import { yourServiceGateway } from "./generated/gateway/plugin.js";
|
|
121
|
+
|
|
122
|
+
const app = Fastify({ logger: true });
|
|
123
|
+
|
|
124
|
+
// Add your middleware here
|
|
125
|
+
app.addHook("onRequest", async (request) => {
|
|
126
|
+
// Verify JWT, check API keys, etc.
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
await app.register(yourServiceGateway, { client, prefix: "/v1" });
|
|
130
|
+
await app.listen({ port: 3000 });
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## Step 5: Test With Typed Mocks
|
|
134
|
+
|
|
135
|
+
The generated `operations.ts` interface lets you test gateway routes without a live SOAP connection.
|
|
136
|
+
|
|
137
|
+
```typescript
|
|
138
|
+
import type { YourServiceOperations } from "./generated/client/operations.js";
|
|
139
|
+
|
|
140
|
+
const mockClient: YourServiceOperations = {
|
|
141
|
+
SomeOperation: async (args) => ({
|
|
142
|
+
response: { SomeOperationResult: { Status: "OK" } },
|
|
143
|
+
headers: {},
|
|
144
|
+
}),
|
|
145
|
+
};
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Use this mock client when registering the gateway plugin in tests:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
import Fastify from "fastify";
|
|
152
|
+
import { yourServiceGateway } from "./generated/gateway/plugin.js";
|
|
153
|
+
|
|
154
|
+
const app = Fastify();
|
|
155
|
+
await app.register(yourServiceGateway, { client: mockClient, prefix: "/v1" });
|
|
156
|
+
await app.ready();
|
|
157
|
+
|
|
158
|
+
const response = await app.inject({
|
|
159
|
+
method: "POST",
|
|
160
|
+
url: "/v1/some-operation",
|
|
161
|
+
payload: { /* request body */ },
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
expect(response.statusCode).toBe(200);
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
See [Testing Guide](testing.md) for more patterns including generated test suites.
|
|
168
|
+
|
|
169
|
+
## Step 6: Production Deployment
|
|
170
|
+
|
|
171
|
+
### Environment variables
|
|
172
|
+
|
|
173
|
+
The generated app scaffold uses `.env` for configuration. Copy `.env.example` and set your values:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
WSDL_SOURCE=https://your-service.example.com/service.svc?wsdl
|
|
177
|
+
PORT=3000
|
|
178
|
+
HOST=0.0.0.0
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### SOAP wire logging
|
|
182
|
+
|
|
183
|
+
Enable request/response debugging with the `NODE_DEBUG` environment variable:
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
NODE_DEBUG=soap node app.js
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### CI/CD regeneration
|
|
190
|
+
|
|
191
|
+
Add a regeneration step to your CI pipeline. Because output is deterministic, you can regenerate and check for unexpected diffs:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
npx wsdl-tsc pipeline --wsdl-source $WSDL_URL ...
|
|
195
|
+
git diff --exit-code generated/
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
If the diff is non-empty, the WSDL contract has changed. Review and commit the updated files.
|
|
199
|
+
|
|
200
|
+
See [Production Guide](production.md) for validation, logging, and deployment details.
|
|
201
|
+
|
|
202
|
+
## Step 7: Incremental Rollout
|
|
203
|
+
|
|
204
|
+
You do not have to expose all WSDL operations at once.
|
|
205
|
+
|
|
206
|
+
### Route-by-route migration
|
|
207
|
+
|
|
208
|
+
Use the operations configuration file to control which operations are included in the OpenAPI spec and gateway. Generate only the operations you are ready to expose, then add more over time.
|
|
209
|
+
|
|
210
|
+
See [Configuration](configuration.md) for the operations config file format.
|
|
211
|
+
|
|
212
|
+
### Parallel running
|
|
213
|
+
|
|
214
|
+
Run the REST gateway alongside existing SOAP consumers. The gateway does not modify or proxy the SOAP service; it calls it as a client. Both access patterns can coexist safely.
|
|
215
|
+
|
|
216
|
+
### Monitoring
|
|
217
|
+
|
|
218
|
+
Track gateway health through Fastify's built-in logging and the `/health` endpoint generated in the app scaffold. For SOAP-level debugging, use `NODE_DEBUG=soap` to inspect wire traffic.
|
|
219
|
+
|
|
220
|
+
## Common Migration Patterns
|
|
221
|
+
|
|
222
|
+
### Wrapping a vendor SOAP API
|
|
223
|
+
|
|
224
|
+
When the WSDL comes from a third-party vendor, you cannot change it. Generate the full stack, add authentication and rate limiting in your app layer, and expose the subset of operations your consumers need. The generated gateway becomes your controlled API surface.
|
|
225
|
+
|
|
226
|
+
### Multiple WSDL services behind one gateway
|
|
227
|
+
|
|
228
|
+
Generate each WSDL into its own client and gateway directory. Register multiple gateway plugins in a single Fastify app with different prefixes:
|
|
229
|
+
|
|
230
|
+
```typescript
|
|
231
|
+
await app.register(serviceAGateway, { client: clientA, prefix: "/v1/service-a" });
|
|
232
|
+
await app.register(serviceBGateway, { client: clientB, prefix: "/v1/service-b" });
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### Regenerating after WSDL changes
|
|
236
|
+
|
|
237
|
+
When the vendor updates their WSDL, regenerate with the same command. Review the diff in version control. TypeScript compilation will catch any breaking changes in your consumer code that depend on removed or renamed types.
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Output Anatomy
|
|
2
|
+
|
|
3
|
+
This document describes each file produced by the generator, what it contains, and how to work with it. For CLI flags that control output, see [CLI Reference](cli-reference.md).
|
|
4
|
+
|
|
5
|
+
## Generation Flow
|
|
6
|
+
|
|
7
|
+
The pipeline follows this sequence: WSDL source is parsed and compiled into a catalog, then each emitter reads the catalog and produces its output.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
WSDL/XSD --> compile --> catalog.json --> emit client/
|
|
11
|
+
--> emit openapi.json
|
|
12
|
+
--> emit gateway/
|
|
13
|
+
--> emit app/
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Each stage can run independently. The `pipeline` command runs all stages in sequence.
|
|
17
|
+
|
|
18
|
+
## Client Output
|
|
19
|
+
|
|
20
|
+
Generated into the directory specified by `--client-dir`.
|
|
21
|
+
|
|
22
|
+
| File | Purpose |
|
|
23
|
+
|------|---------|
|
|
24
|
+
| types.ts | All TypeScript interfaces derived from WSDL/XSD types |
|
|
25
|
+
| client.ts | SOAP client class with one typed method per operation |
|
|
26
|
+
| operations.ts | Pure interface matching client methods, for mocking without importing `soap` |
|
|
27
|
+
| utils.ts | Runtime helpers including array unwrapping and type metadata |
|
|
28
|
+
| catalog.json | Compiled WSDL data in JSON format, used by other generation stages |
|
|
29
|
+
|
|
30
|
+
### types.ts
|
|
31
|
+
|
|
32
|
+
Contains one interface per WSDL complex type. Attributes and elements are flattened into peer properties. Inheritance is expressed with TypeScript `extends`. All numeric and date-time types map to `string` by default to prevent precision loss.
|
|
33
|
+
|
|
34
|
+
### client.ts
|
|
35
|
+
|
|
36
|
+
Exports a client class that wraps the `soap` package. Each WSDL operation becomes an async method with typed input and output. The class handles SOAP envelope construction and response parsing internally.
|
|
37
|
+
|
|
38
|
+
### operations.ts
|
|
39
|
+
|
|
40
|
+
Exports a TypeScript interface with the same method signatures as the client class but no implementation. Use this for dependency injection and testing. Your test code can implement this interface with mock data without importing the client or `soap`.
|
|
41
|
+
|
|
42
|
+
### utils.ts
|
|
43
|
+
|
|
44
|
+
Contains runtime metadata and helper functions. Includes `unwrapArrayWrappers()` for bridging between SOAP array wrapper objects and flattened OpenAPI array schemas.
|
|
45
|
+
|
|
46
|
+
## OpenAPI Output
|
|
47
|
+
|
|
48
|
+
Generated at the path specified by `--openapi-file`.
|
|
49
|
+
|
|
50
|
+
| File | Purpose |
|
|
51
|
+
|------|---------|
|
|
52
|
+
| openapi.json (or .yaml) | Complete OpenAPI 3.1 specification |
|
|
53
|
+
|
|
54
|
+
The spec includes one POST path per WSDL operation, request and response schemas in `components/schemas`, and descriptions derived from WSDL documentation annotations. Schemas are generated from the same catalog used for TypeScript types, so the two outputs stay aligned.
|
|
55
|
+
|
|
56
|
+
OpenAPI validation runs by default using `@apidevtools/swagger-parser`. Disable with `--openapi-validate false`.
|
|
57
|
+
|
|
58
|
+
## Gateway Output
|
|
59
|
+
|
|
60
|
+
Generated into the directory specified by `--gateway-dir`.
|
|
61
|
+
|
|
62
|
+
| File | Purpose |
|
|
63
|
+
|------|---------|
|
|
64
|
+
| plugin.ts | Fastify plugin entry point; registers routes and the SOAP client decorator |
|
|
65
|
+
| routes.ts | Route registration file that imports all individual route handlers |
|
|
66
|
+
| routes/*.ts | One file per WSDL operation with request validation, SOAP call, and response transform |
|
|
67
|
+
| schemas.ts | Schema registration file for JSON Schema validation |
|
|
68
|
+
| schemas/models/*.json | JSON Schema files for each type |
|
|
69
|
+
| schemas/operations/*.json | JSON Schema files for each operation request/response |
|
|
70
|
+
| runtime.ts | Runtime helpers for array unwrapping and type bridging |
|
|
71
|
+
| _typecheck.ts | Compile-time verification that types and schemas stay consistent |
|
|
72
|
+
|
|
73
|
+
### Route handler structure
|
|
74
|
+
|
|
75
|
+
Each route file in `routes/` follows the same pattern: validate the JSON request body against the operation schema, call the corresponding SOAP operation via the typed client, transform the SOAP response to JSON, and return it with the appropriate response schema.
|
|
76
|
+
|
|
77
|
+
### Plugin registration
|
|
78
|
+
|
|
79
|
+
The generated plugin exports a Fastify plugin function. Register it with your Fastify app and provide a client instance (real or mock) and a route prefix.
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
import Fastify from "fastify";
|
|
83
|
+
import { myServiceGateway } from "./generated/gateway/plugin.js";
|
|
84
|
+
import { createMyServiceClient } from "./generated/client/client.js";
|
|
85
|
+
|
|
86
|
+
const app = Fastify();
|
|
87
|
+
const client = await createMyServiceClient("https://soap-endpoint.example.com");
|
|
88
|
+
await app.register(myServiceGateway, { client, prefix: "/v1/my-service" });
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## App Output
|
|
92
|
+
|
|
93
|
+
Generated when `--init-app` is passed. Creates a runnable Fastify application in a sibling `app/` directory.
|
|
94
|
+
|
|
95
|
+
| File | Purpose |
|
|
96
|
+
|------|---------|
|
|
97
|
+
| index.ts | Application entry point with server startup |
|
|
98
|
+
| .env.example | Environment variable template for WSDL URL, port, host |
|
|
99
|
+
| package.json | Dependencies and npm scripts |
|
|
100
|
+
| tsconfig.json | TypeScript configuration for the app |
|
|
101
|
+
|
|
102
|
+
App files have overwrite protection: they are written only if they do not already exist. This prevents regeneration from overwriting your customizations. Use `--force-app` to override this behavior.
|
|
103
|
+
|
|
104
|
+
## What to Commit
|
|
105
|
+
|
|
106
|
+
All generated files are deterministic. Committing them to version control is safe and recommended. After WSDL changes, regenerate with the same command and review the diff to see exactly what changed.
|
|
107
|
+
|
|
108
|
+
## What to Customize
|
|
109
|
+
|
|
110
|
+
- App files (`index.ts`, `.env`): these are your entry points; customize freely after first generation
|
|
111
|
+
- Gateway plugin, routes, and schemas: do not edit manually; they are overwritten on regeneration
|
|
112
|
+
- Add custom middleware, auth, logging, and error handling in your app code, not in generated gateway files
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Start Here
|
|
2
|
+
|
|
3
|
+
This page helps you understand what this package does, decide if it fits your needs, and find the fastest path to your first result.
|
|
4
|
+
|
|
5
|
+
## What This Package Does
|
|
6
|
+
|
|
7
|
+
`@techspokes/typescript-wsdl-client` reads a WSDL/XSD definition and generates typed TypeScript code. Depending on the command you run, you get a typed SOAP client, an OpenAPI 3.1 specification, a Fastify REST gateway, or all of the above.
|
|
8
|
+
|
|
9
|
+
The generated output is deterministic: re-running the same command produces identical files, safe for version control and CI regeneration.
|
|
10
|
+
|
|
11
|
+
## Who It Is For
|
|
12
|
+
|
|
13
|
+
- TypeScript teams integrating with SOAP services who want type safety without hand-writing DTOs
|
|
14
|
+
- Teams modernizing legacy SOAP integrations into REST APIs
|
|
15
|
+
- Developers who need OpenAPI documentation derived from WSDL contracts
|
|
16
|
+
- Projects that require deterministic code generation under version control
|
|
17
|
+
|
|
18
|
+
## Choose Your Path
|
|
19
|
+
|
|
20
|
+
### I need a typed SOAP client
|
|
21
|
+
|
|
22
|
+
Run the `client` command. This generates TypeScript interfaces for all WSDL types and a typed client class with one method per SOAP operation.
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npx wsdl-tsc client \
|
|
26
|
+
--wsdl-source your-service.wsdl \
|
|
27
|
+
--client-dir ./generated/client
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
You get `types.ts`, `client.ts`, `operations.ts`, and `utils.ts`. Import the client, call typed methods, and let TypeScript catch contract mismatches at compile time.
|
|
31
|
+
|
|
32
|
+
Next: [Working With Generated Code](generated-code.md)
|
|
33
|
+
|
|
34
|
+
### I need an OpenAPI spec from a WSDL
|
|
35
|
+
|
|
36
|
+
Run the `openapi` command. This generates an OpenAPI 3.1 specification with schemas derived from the same type system used for the TypeScript client.
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx wsdl-tsc openapi \
|
|
40
|
+
--wsdl-source your-service.wsdl \
|
|
41
|
+
--openapi-file ./generated/openapi.json
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The spec includes paths for each SOAP operation, request/response schemas, and descriptions propagated from WSDL documentation annotations.
|
|
45
|
+
|
|
46
|
+
Next: [CLI Reference](cli-reference.md) for OpenAPI-specific flags
|
|
47
|
+
|
|
48
|
+
### I need a REST gateway over SOAP
|
|
49
|
+
|
|
50
|
+
Run the `pipeline` command with `--init-app`. This generates the typed client, OpenAPI spec, Fastify gateway handlers, and a runnable application in one step.
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
npx wsdl-tsc pipeline \
|
|
54
|
+
--wsdl-source your-service.wsdl \
|
|
55
|
+
--client-dir ./generated/client \
|
|
56
|
+
--openapi-file ./generated/openapi.json \
|
|
57
|
+
--gateway-dir ./generated/gateway \
|
|
58
|
+
--gateway-service-name my-service \
|
|
59
|
+
--gateway-version-prefix v1 \
|
|
60
|
+
--init-app
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The gateway transforms JSON HTTP requests into SOAP calls and returns JSON responses. Each WSDL operation becomes a POST endpoint.
|
|
64
|
+
|
|
65
|
+
Next: [Gateway Guide](gateway-guide.md) for integration details, then [Migration Playbook](migration-playbook.md) for the full modernization workflow
|
|
66
|
+
|
|
67
|
+
## What NOT to Expect
|
|
68
|
+
|
|
69
|
+
This package does not replace a full API management platform. It does not provide rate limiting, policy enforcement, or multi-language SDK generation. It generates code; it does not run a proxy or manage deployments.
|
|
70
|
+
|
|
71
|
+
For more on scope boundaries, see the "When NOT to Use This" section of the [README](../README.md).
|
|
72
|
+
|
|
73
|
+
## Next Steps
|
|
74
|
+
|
|
75
|
+
| Goal | Read |
|
|
76
|
+
|------|------|
|
|
77
|
+
| Understand what files are generated | [Output Anatomy](output-anatomy.md) |
|
|
78
|
+
| See which WSDL patterns are supported | [Supported Patterns](supported-patterns.md) |
|
|
79
|
+
| Learn about type modeling decisions | [Core Concepts](concepts.md) |
|
|
80
|
+
| Plan a full SOAP-to-REST migration | [Migration Playbook](migration-playbook.md) |
|
|
81
|
+
| Set up testing for generated code | [Testing Guide](testing.md) |
|
|
82
|
+
| Review all CLI flags | [CLI Reference](cli-reference.md) |
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Supported WSDL/XSD Patterns
|
|
2
|
+
|
|
3
|
+
This document lists the WSDL and XSD features handled by the generator, along with current limitations. For modeling details, see [Core Concepts](concepts.md).
|
|
4
|
+
|
|
5
|
+
## Fully Supported
|
|
6
|
+
|
|
7
|
+
These patterns are handled end-to-end: WSDL parsing, TypeScript type generation, OpenAPI schema output, and gateway code generation.
|
|
8
|
+
|
|
9
|
+
- Complex types with `<xs:sequence>`, `<xs:all>`, and `<xs:choice>` compositors, including recursive nesting
|
|
10
|
+
- Simple content with attributes using the `$value` pattern to preserve text content alongside attribute properties
|
|
11
|
+
- Type inheritance through `<xs:extension>` and `<xs:restriction>` on both simple and complex content
|
|
12
|
+
- Nested XSD imports across multiple schema files with relative and absolute URI resolution
|
|
13
|
+
- Multiple namespaces with deterministic collision resolution via PascalCase uniqueness
|
|
14
|
+
- `<xs:choice>` elements modeled as parallel optional alternatives
|
|
15
|
+
- Optional and nillable fields using `minOccurs`, `maxOccurs`, and `nillable` attributes
|
|
16
|
+
- `ArrayOf*` wrapper types with automatic unwrapping in OpenAPI and runtime bridging in gateway code
|
|
17
|
+
- WSDL/XSD documentation annotations propagated into TypeScript JSDoc comments and OpenAPI descriptions
|
|
18
|
+
- Circular type references detected and broken with minimal stub types
|
|
19
|
+
- Multiple WSDL ports and bindings; the first SOAP binding is selected, all ports are documented in service metadata
|
|
20
|
+
- SOAP 1.1 and SOAP 1.2 binding detection
|
|
21
|
+
|
|
22
|
+
## Partially Supported
|
|
23
|
+
|
|
24
|
+
These patterns work in common cases but have known limitations.
|
|
25
|
+
|
|
26
|
+
### WS-Policy and WS-Security hints
|
|
27
|
+
|
|
28
|
+
The compiler scans inline policies for UsernameToken, TransportBinding, and X509Token patterns and records them in `operation.security[]`. External `PolicyReference` elements pointing to out-of-band policy documents are not resolved.
|
|
29
|
+
|
|
30
|
+
### xs:group and xs:attributeGroup
|
|
31
|
+
|
|
32
|
+
Groups are inlined into the parent type during schema compilation. The group identity is not preserved as a separate named type in the output, but all elements and attributes from the group appear correctly in the containing type.
|
|
33
|
+
|
|
34
|
+
### xs:list
|
|
35
|
+
|
|
36
|
+
List types with an `itemType` attribute are detected and generate array types (`${itemType}[]`). Lists defined with inline simple types are not handled.
|
|
37
|
+
|
|
38
|
+
## Not Yet Supported
|
|
39
|
+
|
|
40
|
+
These features are not currently handled. Contributions are welcome.
|
|
41
|
+
|
|
42
|
+
- `xs:any` and `xs:anyAttribute`: unrecognized elements fall through to an untyped representation
|
|
43
|
+
- `xs:union` types: only union members expressed as restriction enumerations are captured
|
|
44
|
+
- Abstract types: treated as regular concrete types without substitution logic
|
|
45
|
+
- Substitution groups: not resolved during schema compilation
|
|
46
|
+
- MTOM/XOP binary attachments: no support for binary part handling
|
|
47
|
+
- WS-ReliableMessaging, WS-Addressing beyond basic headers
|
|
48
|
+
- Custom serialization hooks for non-standard XML patterns
|
|
49
|
+
|
|
50
|
+
## Known Edge Cases
|
|
51
|
+
|
|
52
|
+
### Response schema complexity limit
|
|
53
|
+
|
|
54
|
+
Gateway generation measures the `$ref` graph depth for each operation response. When the number of unique `$ref` targets exceeds 150, the response serialization schema is skipped and the route falls back to `JSON.stringify`. This avoids a depth limit in `fast-json-stringify`. The threshold is controlled by `REF_COMPLEXITY_LIMIT` in `src/gateway/helpers.ts`.
|
|
55
|
+
|
|
56
|
+
### Circular references
|
|
57
|
+
|
|
58
|
+
Recursive type references are detected during compilation and broken with a minimal stub. The generated TypeScript types are correct for non-recursive paths, but deeply recursive structures may produce simplified types at the recursion boundary.
|
|
59
|
+
|
|
60
|
+
### First binding selection
|
|
61
|
+
|
|
62
|
+
When a WSDL defines multiple bindings, the compiler selects the first SOAP binding encountered. If your WSDL has multiple bindings for different protocols, the non-SOAP bindings are ignored. All ports are still recorded in service-level metadata.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@techspokes/typescript-wsdl-client",
|
|
3
|
-
"version": "0.15.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.15.1",
|
|
4
|
+
"description": "Turn legacy WSDL/SOAP services into typed TypeScript clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways. Built for enterprise SOAP modernization.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"wsdl",
|
|
7
7
|
"soap",
|
|
@@ -14,7 +14,11 @@
|
|
|
14
14
|
"soap-to-rest",
|
|
15
15
|
"api-gateway",
|
|
16
16
|
"code-generator",
|
|
17
|
-
"wsdl-to-typescript"
|
|
17
|
+
"wsdl-to-typescript",
|
|
18
|
+
"soap-modernization",
|
|
19
|
+
"wsdl-parser",
|
|
20
|
+
"soap-to-rest-bridge",
|
|
21
|
+
"legacy-api"
|
|
18
22
|
],
|
|
19
23
|
"homepage": "https://github.com/TechSpokes/typescript-wsdl-client#readme",
|
|
20
24
|
"bugs": {
|