@techspokes/typescript-wsdl-client 0.10.2 → 0.11.0

package/docs/gateway-guide.md

@@ -63,17 +63,18 @@ Route handlers call the SOAP client automatically:
 
 ```typescript
 import type { FastifyInstance } from "fastify";
+import type { GetCityForecastByZIP } from "../../client/types.js";
 import schema from "../schemas/operations/getcityforecastbyzip.json" with { type: "json" };
 import { buildSuccessEnvelope } from "../runtime.js";
 
 export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: FastifyInstance) {
-  fastify.route({
+  fastify.route<{ Body: GetCityForecastByZIP }>({
     method: "POST",
     url: "/get-city-forecast-by-zip",
     schema,
     handler: async (request) => {
       const client = fastify.weatherClient;
-      const result = await client.GetCityForecastByZIP(request.body);
+      const result = await client.GetCityForecastByZIP(request.body as GetCityForecastByZIP);
       return buildSuccessEnvelope(result.response);
     },
   });
@@ -117,6 +118,39 @@ All generated JSON Schemas use deterministic URN identifiers:
 
 Example: `urn:services:weather:v1:schemas:models:getcityweatherbyzipresponse`
 
+## Multi-Service Setup
+
+When integrating multiple SOAP services, each service gets its own client, gateway, and OpenAPI spec. Register each in its own Fastify encapsulation scope to prevent decorator collisions:
+
+```typescript
+import Fastify from "fastify";
+import weatherPlugin from "./generated/weather/gateway/plugin.js";
+import inventoryPlugin from "./generated/inventory/gateway/plugin.js";
+import { Weather } from "./generated/weather/client/client.js";
+import { Inventory } from "./generated/inventory/client/client.js";
+
+const app = Fastify({ logger: true });
+
+// Each plugin gets its own scope to isolate decorators
+await app.register(async (scope) => {
+  await scope.register(weatherPlugin, {
+    client: new Weather({ source: "https://example.com/weather?wsdl" }),
+    prefix: "/api/weather",
+  });
+});
+
+await app.register(async (scope) => {
+  await scope.register(inventoryPlugin, {
+    client: new Inventory({ source: "https://example.com/inventory?wsdl" }),
+    prefix: "/api/inventory",
+  });
+});
+
+await app.listen({ port: 3000 });
+```
+
+See [`examples/fastify-gateway/`](../examples/fastify-gateway/) for a complete example.
+
 ## Contract Assumptions
 
 - All request/response bodies must use $ref to components.schemas

package/docs/generated-code.md

@@ -72,3 +72,59 @@ result.GetCityWeatherByZIPResult.Temperature;
 ```
 
 Autocomplete and type checking work across all generated interfaces.
+
+## Gateway Route Handlers
+
+When generating a Fastify gateway (`--gateway-dir`), each SOAP operation gets a fully typed route handler. The handler imports the request type from the client, uses Fastify's `Body: T` generic for type inference, and wraps the SOAP response in a standard envelope.
+
+```typescript
+import type { FastifyInstance } from "fastify";
+import type { GetCityForecastByZIP } from "../../client/types.js";
+import schema from "../schemas/operations/getcityforecastbyzip.json" with { type: "json" };
+import { buildSuccessEnvelope } from "../runtime.js";
+
+export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: FastifyInstance) {
+  fastify.route<{ Body: GetCityForecastByZIP }>({
+    method: "POST",
+    url: "/get-city-forecast-by-zip",
+    schema,
+    handler: async (request) => {
+      const client = fastify.weatherClient;
+      const result = await client.GetCityForecastByZIP(request.body as GetCityForecastByZIP);
+      return buildSuccessEnvelope(result.response);
+    },
+  });
+}
+```
+
+Key features of the generated handlers:
+
+- **`Body: T` generic** — Fastify infers `request.body` type from the route generic, enabling IDE autocomplete and compile-time checks
+- **JSON Schema validation** — the `schema` import provides Fastify with request/response validation at runtime, before the handler runs
+- **Envelope wrapping** — `buildSuccessEnvelope()` wraps the raw SOAP response in the standard `{ status, message, data, error }` envelope
+
+See [Gateway Guide](gateway-guide.md) for the full architecture and [CLI Reference](cli-reference.md) for generation flags.
+
+## Operations Interface
+
+The generated `operations.ts` exports a typed interface (`{ServiceName}Operations`) that mirrors the concrete client class methods. Use it for dependency injection and testing:
+
+```typescript
+import type { WeatherOperations } from "./client/operations.js";
+
+const mock: WeatherOperations = {
+  GetCityWeatherByZIP: async (args) => ({
+    response: { GetCityWeatherByZIPResult: { Success: true } },
+    headers: {},
+  }),
+  // ...other operations
+};
+```
+
+The gateway plugin accepts any `WeatherOperations` implementation, so you can pass the mock directly:
+
+```typescript
+app.register(weatherGateway, { client: mock });
+```
+
+See [Testing Guide](testing.md) for full integration test patterns.

package/docs/testing.md

@@ -0,0 +1,193 @@
+# Testing Guide
+
+Guide to running and writing tests for wsdl-tsc development and for testing generated code in consumer projects.
+
+See [README](../README.md) for quick start and [CONTRIBUTING](../CONTRIBUTING.md) for development setup.
+
+## Test Architecture
+
+The project uses three layers of testing:
+
+1. **Unit tests** — Pure function tests for utilities, parsers, and type mapping
+2. **Snapshot tests** — Baseline comparisons for all generated pipeline output
+3. **Integration tests** — End-to-end gateway tests using Fastify's `inject()` with mock clients
+
+All tests use [Vitest](https://vitest.dev/) and run in under 3 seconds.
+
+## Running Tests
+
+```bash
+npm test              # All Vitest tests
+npm run test:unit     # Unit tests only
+npm run test:snap     # Snapshot tests only
+npm run test:integration  # Integration tests only
+npm run test:watch    # Watch mode for development
+```
+
+For the full CI pipeline including smoke tests:
+
+```bash
+npm run ci
+```
+
+## Unit Tests
+
+Unit tests cover pure functions with no I/O or side effects:
+
+- **`tools.test.ts`** — `pascal()`, `resolveQName()`, `explodePascal()`, `pascalToSnakeCase()`, `normalizeArray()`, `getChildrenWithLocalName()`, `getFirstWithLocalName()`
+- **`casing.test.ts`** — `toPathSegment()` with kebab, asis, and lower styles
+- **`primitives.test.ts`** — `xsdToTsPrimitive()` covering all XSD types (string-like, boolean, integers, decimals, floats, dates, any)
+- **`errors.test.ts`** — `WsdlCompilationError` construction and `toUserMessage()` formatting
+- **`schema-alignment.test.ts`** — Cross-validates TypeScript types, JSON schemas, and catalog.json for consistency
+
+### Writing Unit Tests
+
+```typescript
+import { describe, it, expect } from "vitest";
+import { pascal } from "../../src/util/tools.js";
+
+describe("pascal", () => {
+  it("converts kebab-case", () => {
+    expect(pascal("get-weather")).toBe("GetWeather");
+  });
+});
+```
+
+## Snapshot Tests
+
+Snapshot tests capture the complete output of the pipeline as baselines. When a generator change intentionally alters output, the snapshot diff shows exactly what changed.
+
+### How It Works
+
+1. The pipeline runs against `examples/minimal/weather.wsdl` into a temp directory
+2. Each generated file is read and compared against the stored snapshot
+3. A file inventory snapshot detects added or removed files
+
+### Updating Snapshots
+
+```bash
+npx vitest run test/snapshot -u
+```
+
+Always review the diff before committing updated snapshots.
+
+### What's Covered
+
+- Client output: `client.ts`, `types.ts`, `utils.ts`, `operations.ts`, `catalog.json`
+- OpenAPI: `openapi.json`
+- Gateway core: `plugin.ts`, `routes.ts`, `schemas.ts`, `runtime.ts`, `_typecheck.ts`
+- Gateway routes: one handler per WSDL operation
+- Gateway schemas: all model and operation JSON schema files
+- File inventory: complete listing of generated files
+
+## Integration Tests
+
+Integration tests verify the generated gateway works end-to-end by:
+
+1. Running the pipeline in `beforeAll` to generate gateway code
+2. Dynamically importing the generated plugin
+3. Creating a Fastify instance with the plugin and a mock client
+4. Using `fastify.inject()` to send HTTP requests and verify responses
+
+### Mock Client Pattern
+
+The generated `operations.ts` provides a typed interface for creating test doubles:
+
+```typescript
+import type { WeatherOperations } from "../client/operations.js";
+
+function createMockClient(): WeatherOperations {
+  return {
+    GetCityWeatherByZIP: async (args) => ({
+      response: {
+        GetCityWeatherByZIPResult: {
+          Success: true,
+          ResponseText: "City Found",
+          State: "NY",
+          City: "New York",
+          Temperature: "72",
+        },
+      },
+      headers: {},
+    }),
+    GetCityForecastByZIP: async (args) => ({
+      response: {
+        GetCityForecastByZIPResult: {
+          Success: true,
+          ResponseText: "Forecast Found",
+          // Use SOAP wrapper shape — unwrapArrayWrappers() handles conversion
+          ForecastResult: { Forecast: [] },
+        },
+      },
+      headers: {},
+    }),
+    GetWeatherInformation: async (args) => ({
+      response: {
+        // Use SOAP wrapper shape — unwrapArrayWrappers() handles conversion
+        GetWeatherInformationResult: { WeatherDescription: [] },
+      },
+      headers: {},
+    }),
+  };
+}
+```
+
+Each method returns the same `{ response, headers }` shape as the real SOAP client. Use the wrapper object structure matching TypeScript types — the generated `unwrapArrayWrappers()` function handles conversion to the flat array shape expected by JSON schemas.
+
+### Using the Mock with Fastify
+
+```typescript
+import Fastify from "fastify";
+
+const app = Fastify();
+await app.register(weatherGateway, {
+  client: createMockClient(),
+  prefix: "/v1/weather",
+});
+await app.ready();
+
+const res = await app.inject({
+  method: "POST",
+  url: "/v1/weather/get-city-weather-by-zip",
+  payload: { ZIP: "10001" },
+});
+
+expect(res.statusCode).toBe(200);
+expect(res.json().status).toBe("SUCCESS");
+```
+
+### Dynamic Import of Generated Code
+
+Integration tests dynamically import generated `.ts` files from temp directories. This works because Vitest's Vite module resolution handles TypeScript imports, JSON import attributes, and bare specifiers from the project's `node_modules`:
+
+```typescript
+import { pathToFileURL } from "node:url";
+
+const pluginModule = await import(pathToFileURL(join(outDir, "gateway", "plugin.ts")).href);
+```
+
+## Known Issues
+
+### ArrayOf* Schema-Type Mismatch (Resolved)
+
+JSON schemas flatten SOAP `ArrayOf*` wrapper types to plain `type: "array"` (when `--openapi-flatten-array-wrappers` is `true`, the default), while TypeScript types preserve the wrapper structure (e.g., `ArrayOfForecast = { Forecast?: Forecast[] }`).
+
+This mismatch is resolved by the generated `unwrapArrayWrappers()` function in `runtime.ts`. Route handlers call it automatically to strip wrapper objects before Fastify serialization. Mock clients should return the real SOAP wrapper structure — the unwrap function handles the conversion.
+
+When `--openapi-flatten-array-wrappers false` is used, ArrayOf* types are emitted as `type: "object"` and no unwrap function is generated. In this mode, mock data should use the wrapper object shape matching both the TypeScript types and the JSON schemas.
+
+### Error Details Serialization
+
+The `classifyError()` function puts `err.message` (a string) in the `details` field for connection and timeout errors, but the error JSON schema defines `details` as `object | null`. This causes Fastify serialization failures for 503/504 error responses. Test error classification directly via `classifyError()` rather than through Fastify's `inject()` for these error types.
+
+## For Consumer Projects
+
+If you're using wsdl-tsc as a dependency and want to test your integration:
+
+1. Generate code with `npx wsdl-tsc pipeline`
+2. Import the operations interface from `operations.ts`
+3. Create a mock client implementing the interface
+4. Register the generated gateway plugin with your mock client
+5. Use Fastify's `inject()` to test routes without a running server
+
+The operations interface is the recommended seam for dependency injection and testing. It's a pure TypeScript interface with no runtime dependencies on the `soap` package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Generate type-safe TypeScript SOAP clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways from WSDL/XSD definitions.",
   "keywords": [
     "wsdl",
@@ -58,32 +58,38 @@
     "clean:tmp": "rimraf tmp",
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && npm run smoke:pipeline",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:snap": "vitest run test/snapshot",
+    "test:integration": "vitest run test/integration",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run clean && npm run build",
     "smoke:reset": "npm run clean:tmp",
     "smoke:compile": "npm run smoke:reset && tsx src/cli.ts compile --wsdl-source examples/minimal/weather.wsdl --catalog-file tmp/catalog.json",
     "smoke:client": "npm run smoke:reset && tsx src/cli.ts client --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client && tsc -p tsconfig.smoke.json",
     "smoke:openapi": "npm run smoke:reset && tsx src/cli.ts openapi --wsdl-source examples/minimal/weather.wsdl --openapi-file tmp/openapi.json --openapi-format json && tsc -p tsconfig.smoke.json",
     "smoke:gateway": "npm run smoke:reset && tsx src/cli.ts client --wsdl-source examples/minimal/weather.wsdl --client-dir tmp/client && tsx src/cli.ts openapi --catalog-file tmp/client/catalog.json --openapi-file tmp/openapi.json --openapi-format json && tsx src/cli.ts gateway --openapi-file tmp/openapi.json --client-dir tmp/client --gateway-dir tmp/gateway --gateway-service-name weather --gateway-version-prefix v1 && tsc -p tsconfig.smoke.json",
-    "smoke:pipeline": "npm run smoke:reset && tsx src/cli.ts 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 --openapi-format json --openapi-servers https://example.com/api --generate-app && tsc -p tsconfig.smoke.json",
-    "smoke:app": "npm run smoke:reset && tsx src/cli.ts 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 --openapi-format json --openapi-servers https://example.com/api && tsx src/cli.ts app --client-dir tmp/client --gateway-dir tmp/gateway --openapi-file tmp/openapi.json --app-dir tmp/app && tsc -p tsconfig.smoke.json",
-    "ci": "npm run clean && npm run build && npm run typecheck && npm run smoke:pipeline"
+    "smoke:pipeline": "npm run smoke:reset && tsx src/cli.ts 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 --openapi-format json --init-app && tsc -p tsconfig.smoke.json",
+    "smoke:app": "npm run smoke:reset && tsx src/cli.ts 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 --openapi-format json --openapi-servers https://example.com/api && tsx src/cli.ts app --client-dir tmp/client --gateway-dir tmp/gateway --openapi-file tmp/openapi.json --app-dir tmp/app --port 8080 && tsc -p tsconfig.smoke.json",
+    "ci": "npm run clean && npm run build && npm run typecheck && vitest run && npm run smoke:pipeline",
+    "examples:regenerate": "tsx src/cli.ts pipeline --wsdl-source examples/minimal/weather.wsdl --client-dir examples/generated-output/client --openapi-file examples/generated-output/openapi.json --gateway-dir examples/generated-output/gateway --gateway-service-name weather --gateway-version-prefix v1 --openapi-format json"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.0.2",
-    "@types/yargs": "^17.0.33",
-    "fastify": "^5.2.0",
+    "@types/node": "^25.2.0",
+    "@types/yargs": "^17.0.35",
+    "fastify": "^5.7.0",
     "fastify-plugin": "^5.1.0",
-    "rimraf": "^6.0.0",
-    "tsx": "^4.20.0",
-    "typescript": "^5.6.3"
+    "rimraf": "^6.1.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.18"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "fast-xml-parser": "^5.2.5",
+    "fast-xml-parser": "^5.3.0",
     "js-yaml": "^4.1.1",
-    "soap": "^1.3.0",
+    "soap": "^1.6.0",
     "yargs": "^18.0.0"
   },
   "funding": {