Skip to content

migration.md

Latest commit

 

History

History
168 lines (111 loc) · 8.29 KB

migration.md

File metadata and controls

168 lines (111 loc) · 8.29 KB
Raw

Migration Guide

This guide covers upgrade steps between major versions of @techspokes/typescript-wsdl-client.

Versions are listed newest first. Find your current version and follow the steps for each version you need to cross.

General Upgrade Steps

These steps apply to every version upgrade:

  1. Update the package: npm install --save-dev @techspokes/typescript-wsdl-client@latest
  2. Read the migration section for your version jump below
  3. Regenerate all output by running your generation script or pipeline command
  4. Run tsc --noEmit to verify the generated code compiles
  5. Test your application

Version Compatibility

wsdl-tsc Node.js TypeScript soap Fastify saxes
1.0.x >= 24.0 >= 6.0 >= 1.9 >= 5.10 >= 6.0
0.35.x and later >= 24.0 >= 6.0 >= 1.9 >= 5.8 >= 6.0
0.17.x >= 20.0 >= 6.0 >= 1.9 >= 5.8 >= 6.0
0.16.x >= 20.0 >= 6.0 >= 1.9 >= 5.8 N/A
0.15.x >= 20.0 >= 6.0 >= 1.8 >= 5.4 N/A
0.11.x to 0.14.x >= 20.0 >= 5.6 >= 1.3 >= 5.2 N/A
0.10.x >= 20.0 >= 5.6 >= 1.3 >= 5.2 N/A
0.9.x >= 20.0 >= 5.6 >= 1.3 >= 5.2 N/A
0.8.x >= 20.0 >= 5.6 >= 1.3 >= 5.2 N/A
0.7.x >= 20.0 >= 5.6 >= 1.3 N/A N/A

Versions 0.11 through 0.16 are additive and non-breaking. See CHANGELOG.md for per-version detail rather than dedicated upgrade sections here.

Upgrading to 1.0.0 from 0.40.1

Version 1.0.0 stabilizes the public behavior shipped through 0.40.1. It does not intentionally change generated client, OpenAPI, gateway, app, or runtime contracts.

Stable 1.0 Contract

  • Node.js 24 is the supported runtime floor.
  • The package and generated code remain ESM-only.
  • all-optional remains the default xs:choice strategy.
  • Choice union mode remains opt-in through --client-choice-mode union.
  • NDJSON remains the default configured stream format.
  • JSON array streaming remains opt-in per operation.
  • Generated output remains replaceable and should be regenerated from WSDL or catalog inputs.

Accepted 1.0 Limitations

  • Multiple SOAP bindings use deterministic first SOAP binding selection.
  • External PolicyReference documents are not fetched or resolved.
  • Abstract complex types fail with a diagnostic.
  • Substitution groups fail with a diagnostic.
  • MTOM/XOP attachments fail with a diagnostic.

Steps to Upgrade to 1.0.0

  1. Upgrade the development dependency to @techspokes/typescript-wsdl-client@^1.0.0.
  2. Confirm the project runs Node.js 24 or newer.
  3. Keep soap installed as a runtime dependency.
  4. Regenerate every owned client, OpenAPI, gateway, app, and generated-test artifact.
  5. Review the generated diff and run the consumer TypeScript build and tests.

Is 1.0.0 Breaking?

No intentional behavior break is introduced relative to 0.40.1. The major version declares the documented surface stable, so future incompatible changes require a new major release.

Upgrading to 0.17.x from 0.16.x

This upgrade adds opt-in streamable SOAP responses. No breaking changes; generated output is byte-for-byte unchanged when --stream-config is not provided.

What Changed in 0.17.x

The CLI gains a --stream-config <file> flag on compile, client, and pipeline. Operations listed in that file emit a new client method signature returning StreamOperationResponse<RecordType> with records: AsyncIterable<RecordType>, an OpenAPI 200 response typed as application/x-ndjson by default with an x-wsdl-tsc-stream extension, and a Fastify route that streams records with backpressure. Set format: "json-array" for application/json array streaming. The compiler now retains xs:any wildcard particles on compiled types (previously dropped silently), enabling honest stream-candidate detection and companion-catalog shape resolution. saxes ^6.0.0 is now a runtime dependency of the package and is pinned automatically into the generated app scaffold.

Steps to Upgrade to 0.17.x

  1. Update the package and regenerate; no flag or code changes are required for buffered operations
  2. If consumers integrate the generated client directly (not via the app scaffold), install saxes ^6.0.0 as a runtime dependency before using any stream operation
  3. To opt into streaming for specific operations, author a stream-config file (see Stream Configuration) and pass it via --stream-config
  4. Review the new generated client method signatures for any opted-in operation; consumers must use for await (const record of result.records) instead of awaiting the full response

Is 0.17.x Breaking?

No. Without --stream-config, generated output is byte-for-byte unchanged. Consumers only see new surfaces when they opt in.

Upgrading to 0.10.x from 0.9.x

This upgrade changes generated gateway code only. No CLI flags changed.

What Changed in 0.10.x

The gateway plugin now uses the concrete client class type instead of a generic index signature. Route handlers are fully typed with Body: T generics. A new _typecheck.ts fixture is generated to catch plugin-client type divergence at build time.

Steps to Upgrade to 0.10.x

  1. Regenerate all gateway code: npx wsdl-tsc pipeline ...
  2. Remove any @ts-expect-error comments you added for client type mismatches
  3. Add _typecheck.ts to your TypeScript includes if you use a custom tsconfig

Is 0.10.x Breaking?

No. These are generated code improvements only. Regenerating your output is sufficient.

Upgrading to 0.9.x from 0.8.x

This upgrade changes how the gateway command generates route handlers.

What Changed in 0.9.x

The gateway command now generates full handler implementations that call the SOAP client and return envelope responses. Previous versions generated stub handlers. New files runtime.ts and plugin.ts are generated. A new app command creates runnable Fastify applications.

Steps to Upgrade to 0.9.x

  1. Regenerate gateway code: npx wsdl-tsc pipeline ...
  2. If you wrote custom handlers over the old stubs, use --gateway-stub-handlers to keep stub behavior
  3. Alternatively, migrate custom logic into the gateway plugin lifecycle hooks
  4. The new plugin.ts is the recommended entry point and replaces manual Fastify wiring

New CLI Flags in 0.9.x

Flag Purpose
--gateway-stub-handlers Generate stub handlers instead of full implementations
--gateway-client-class-name Override the client class name used in handlers
--gateway-decorator-name Override the Fastify decorator name
--gateway-skip-plugin Skip plugin.ts generation
--gateway-skip-runtime Skip runtime.ts generation
--catalog-file Specify catalog location for gateway command

Is 0.9.x Breaking?

Soft breaking. Regeneration changes the output, but the --gateway-stub-handlers flag preserves the old behavior.

Upgrading to 0.8.x from 0.7.x

This upgrade changes CLI flag names, URN format, and adds required arguments. It is a breaking change.

What Changed in 0.8.x

All CLI flags changed from camelCase to kebab-case. The URN format changed to a service-first structure. The --gateway-version-prefix and --gateway-service-name flags became required for gateway and pipeline commands. Catalog files now co-locate with their output directory by default.

CLI Flag Renames in 0.8.x

Old Flag (0.7.x) New Flag (0.8.x)
--versionTag --openapi-version-tag
--basePath --openapi-base-path
--pathStyle --openapi-path-style
--closedSchemas --openapi-closed-schemas
--pruneUnusedSchemas --openapi-prune-unused-schemas

Steps to Upgrade to 0.8.x

  1. Update all CLI commands in scripts and CI to use the new kebab-case flag names
  2. Add --gateway-service-name and --gateway-version-prefix to all gateway and pipeline commands
  3. Regenerate all output because the URN format in JSON schemas changed
  4. Update any code that parses URN identifiers to use the new service-first format

URN Format Change in 0.8.x

The old format was urn:schema:{version}:services:{service}:{models|operations}:{slug}.

The new format is urn:services:{service}:{version}:schemas:{models|operations}:{slug}.

Is 0.8.x Breaking?

Yes. CLI flags, URN format, and required arguments all changed.