@techspokes/typescript-wsdl-client 0.27.0 → 0.29.0

package/docs/roadmap/v1.0-openapi-fastify-compatibility.md

@@ -1,45 +1,47 @@
 # Version 1.0 OpenAPI Fastify Compatibility
 
-Plan for proving schema choices against Fastify before changing choice union output or JSON array streaming output.
+Status: compatibility baseline completed for `0.26.0` choice union mode and `0.28.0` JSON array streaming.
+
+Plan for preserving Fastify compatibility as schema output evolves toward `1.0.0`.
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
 
 ## Goal
 
-This slice confirms which OpenAPI 3.1 and JSON Schema constructs are safe for generated Fastify gateways. The result should constrain choice union mode, JSON array streaming, and any future schema complexity work.
+This slice confirms which OpenAPI 3.1 and JSON Schema constructs are safe for generated Fastify gateways. The completed findings constrain released choice union mode, released JSON array streaming, and any future schema complexity work.
 
-## Why This Slice Comes Before Implementation
+## Why This Slice Remains Active
 
 Fastify compatibility is part of the generated gateway contract. A TypeScript type shape can be correct while the generated OpenAPI schema is unusable for Fastify request validation or response serialization.
 
 ## Scope
 
-- Test `oneOf`, `anyOf`, and `allOf` request schemas through Fastify validation.
-- Test generated response schemas through Fastify serialization where applicable.
-- Test route schemas that omit response serialization for streamed responses.
-- Verify how schema complexity interacts with the existing response-depth safety limit.
+- Maintain probes for `oneOf`, `anyOf`, and `allOf` request schemas through Fastify validation.
+- Maintain probes for generated response schemas through Fastify serialization where applicable.
+- Maintain probes for streamed routes that omit response serialization schemas.
+- Keep the response-depth safety limit aware of schema composition.
 - Document the allowed schema strategy for choice union mode.
 - Document the allowed schema strategy for JSON array streaming.
 
 ## Out Of Scope
 
-- Do not implement choice union mode in this slice.
-- Do not implement JSON array streaming in this slice.
+- Do not change shipped choice union behavior without new compatibility evidence.
+- Do not change shipped JSON array streaming behavior without new compatibility evidence.
 - Do not change public WSDL feature coverage in this slice.
 
 ## Research Questions
 
 ### Choice Request Validation
 
-The research must determine whether `oneOf` with mutually exclusive object branches behaves correctly for request bodies. It must also determine whether additional branch exclusion properties are needed to reject payloads that send more than one choice branch.
+The research determined that `oneOf` with mutually exclusive object branches needs peer exclusion constraints for request bodies. Additional branch exclusion properties are needed to reject payloads that send more than one choice branch.
 
 ### Choice Response Serialization
 
-The research must determine whether generated response schemas should use union constructs or stay envelope-based with permissive payload branches. If Fastify serialization becomes fragile, generated route response schemas must stay conservative.
+The research determined that generated response schemas should stay conservative unless a future slice proves a stricter strategy. If Fastify serialization becomes fragile, generated route response schemas must stay conservative.
 
 ### JSON Array Streaming Schema
 
-The research must determine how to advertise an incrementally streamed JSON array in OpenAPI while keeping generated Fastify route schemas valid. Stream routes already omit normal response serialization because the response is not a single buffered object.
+The research determined how to advertise an incrementally streamed JSON array in OpenAPI while keeping generated Fastify route schemas valid. Stream routes omit normal response serialization because the response is not a single buffered object.
 
 ## Local Fastify Findings
 
@@ -94,4 +96,4 @@ Use small synthetic schemas for compatibility probes. Do not require WSDL fixtur
 
 ## Release Implications
 
-This slice may ship without user-facing generator changes if it only adds tests and docs. If it changes schema generation defaults, it must be paired with snapshot updates and migration notes.
+This slice shipped its released findings through the choice union and JSON array streaming work. Future schema-generation changes must be paired with compatibility probes, snapshot updates, and migration notes when behavior changes.

package/docs/roadmap/v1.0-release-candidate-gates.md

@@ -1,5 +1,7 @@
 # Version 1.0 Release Candidate Gates
 
+Status: remaining final release preparation for `1.0.0`.
+
 Plan for validating that `1.0.0` is repeatable, documented, test-backed, and ready to publish.
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.

package/docs/roadmap/v1.0-wsdl-coverage-matrix.md

@@ -1,12 +1,14 @@
 # Version 1.0 WSDL Coverage Matrix
 
-Plan for turning WSDL and XSD support claims into automated, fixture-backed evidence before 1.0.
+Status: remaining before `1.0.0`.
+
+Plan for turning WSDL and XSD support claims into automated, fixture-backed evidence before 1.0. This is the first domain under the [Capability Conformance Framework](v1.0-capability-conformance-framework.md).
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
 
 ## Goal
 
-The project should have an automated feature matrix that proves which WSDL and XSD patterns are supported, partially supported, or rejected with diagnostics. The matrix should feed `docs/supported-patterns.md` and protect 1.0 from silent miscompilation.
+The project should have an automated WSDL and XSD feature matrix that proves which patterns are supported, partially supported, or rejected with diagnostics. The matrix should feed the conformance registry, align with `docs/supported-patterns.md`, and protect 1.0 from silent miscompilation.
 
 ## Design Direction
 
@@ -28,17 +30,17 @@ Each matrix row should have a minimal fixture, an expected support status, and a
 
 ## Priority Feature Rows
 
-| Feature | Expected 1.0 Status | Notes |
-|---------|---------------------|-------|
-| `xs:choice` union mode | supported | Implemented in `0.26.0` |
-| `xs:union` | supported or diagnostic | Decide after fixture work |
-| Abstract types | diagnostic | Avoid silent concrete treatment |
-| Substitution groups | diagnostic | Avoid silent omission |
-| Multi-binding WSDLs | documented behavior | First binding or explicit selection |
-| External `PolicyReference` | partial or diagnostic | Inline policy already exists |
-| Deep composition | supported | Prove current recursion behavior |
-| `xs:anyAttribute` | diagnostic | Current support is not full |
-| MTOM/XOP attachments | unsupported diagnostic | Keep out of 1.0 scope unless required |
+| Feature                    | Expected 1.0 Status     | Notes                                 |
+|----------------------------|-------------------------|---------------------------------------|
+| `xs:choice` union mode     | supported               | Implemented in `0.26.0`               |
+| `xs:union`                 | supported or diagnostic | Decide after fixture work             |
+| Abstract types             | diagnostic              | Avoid silent concrete treatment       |
+| Substitution groups        | diagnostic              | Avoid silent omission                 |
+| Multi-binding WSDLs        | documented behavior     | First binding or explicit selection   |
+| External `PolicyReference` | partial or diagnostic   | Inline policy already exists          |
+| Deep composition           | supported               | Prove current recursion behavior      |
+| `xs:anyAttribute`          | diagnostic              | Current support is not full           |
+| MTOM/XOP attachments       | unsupported diagnostic  | Keep out of 1.0 scope unless required |
 
 ## Manifest Shape
 

package/docs/start-here.md

@@ -92,7 +92,9 @@ Minimal `stream.config.json`:
 }
 ```
 
-Stream operations return `StreamOperationResponse<RecordType>` on the client (`records: AsyncIterable<RecordType>`), emit `application/x-ndjson` on the gateway, and advertise the record schema in OpenAPI via the `x-wsdl-tsc-stream` extension.
+Stream operations return `StreamOperationResponse<RecordType>` on the client (`records: AsyncIterable<RecordType>`), emit `application/x-ndjson` by default on the gateway, and advertise the record schema in OpenAPI via the `x-wsdl-tsc-stream` extension.
+
+Set `"format": "json-array"` in the stream config when downstream clients need one `application/json` array document instead of NDJSON lines.
 
 Next: [ADR-002: Streamable Responses](decisions/002-streamable-responses.md) for rationale and terminal-error policy, then [Stream Configuration](configuration.md#stream-configuration) for the full file reference.
 
@@ -118,5 +120,5 @@ For more on scope boundaries, see the "When NOT to Use This" section of the [REA
 | Plan a full SOAP-to-REST migration | [Migration Playbook](migration-playbook.md) |
 | Set up testing for generated code | [Testing Guide](testing.md) |
 | Review all CLI flags | [CLI Reference](cli-reference.md) |
-| Opt specific operations into NDJSON streaming | [ADR-002](decisions/002-streamable-responses.md) and [Stream Configuration](configuration.md#stream-configuration) |
+| Opt specific operations into response streaming | [ADR-002](decisions/002-streamable-responses.md) and [Stream Configuration](configuration.md#stream-configuration) |
 | Install package-specific agent guidance | [Agent Skill Artifact](agent-skill.md) |

package/docs/supported-patterns.md

@@ -20,7 +20,7 @@ These patterns are handled end-to-end: WSDL parsing, TypeScript type generation,
 - Circular type references detected and broken with minimal stub types
 - Multiple WSDL ports and bindings; the first SOAP binding is selected, all ports are documented in service metadata
 - SOAP 1.1 and SOAP 1.2 binding detection
-- Streamable SOAP responses, opt-in per operation via `--stream-config` (ADR-002): client exposes `AsyncIterable<RecordType>`, gateway emits NDJSON with backpressure, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`
+- Streamable SOAP responses, opt-in per operation via `--stream-config` (ADR-002): client exposes `AsyncIterable<RecordType>`, gateway emits NDJSON or JSON array streams with backpressure, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`
 - `xs:any` wildcard particles retained on compiled types (they used to be dropped silently) — enables honest stream-candidate detection and companion-catalog shape resolution
 
 ### Named simple types and same-name elements

package/docs/testing.md

@@ -246,7 +246,7 @@ const client = createMockClient({
 
 Mock responses use the pre-unwrap SOAP wrapper shape. The generated `unwrapArrayWrappers()` function handles conversion at runtime.
 
-For operations opted in via `--stream-config`, the mock returns `records: AsyncIterable<RecordType>` (via a small `asyncIterableOf` helper) and the generated happy-path test asserts on the NDJSON content-type and parseable record lines. Override a stream op with a multi-record iterable to exercise downstream backpressure:
+For operations opted in via `--stream-config`, the mock returns `records: AsyncIterable<RecordType>` via a small `asyncIterableOf` helper. Generated happy-path tests assert on the configured content type; NDJSON tests parse record lines, and JSON array tests parse the response body once as an array. Override a stream op with a multi-record iterable to exercise downstream backpressure:
 
 ```typescript
 const client = createMockClient({

package/docs/troubleshooting.md

@@ -20,7 +20,7 @@ See [README](../README.md) for quick start and [CLI Reference](cli-reference.md)
 | Stream config references unknown operation | Operation name must match the WSDL exactly; check spelling and casing |
 | Stream record type not found | `recordType` must exist in the main catalog or a companion `shapeCatalog` must supply it; confirm the companion WSDL compiles cleanly in isolation |
 | Structural collision between main and companion catalog | Two types share a name but differ structurally; rename in the companion source or point `recordType` at a distinct subtree |
-| NDJSON response ends abruptly | Mid-stream upstream error per the terminal-error policy; check gateway logs for the classified error |
+| Stream response ends abruptly or JSON array parse fails | Mid-stream upstream error per the terminal-error policy; check gateway logs for the classified error |
 | Stream recordPath does not match | SAX matching is positional and case-sensitive; verify duplicate local-name segments are spelled exactly |
 | Stream client throws "stream request failed" | The upstream SOAP endpoint rejected the hand-built envelope; check `requestRaw` on the response and verify SOAP action and namespaces match the WSDL binding |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "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.",
   "keywords": [
     "wsdl",
@@ -90,18 +90,18 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.3",
     "@types/yargs": "^17.0.35",
     "fastify": "^5.8.5",
-    "fastify-plugin": "^5.1.0",
+    "fastify-plugin": "^6.0.0",
     "rimraf": "^6.1.3",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.9"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "fast-xml-parser": "^5.8.0",
+    "fast-xml-parser": "^5.9.0",
     "js-yaml": "^4.2.0",
     "saxes": "^6.0.0",
     "soap": "^1.9.3",

package/src/runtime/jsonArray.ts

@@ -0,0 +1,55 @@
+/**
+ * JSON array adapter for record iterables.
+ *
+ * Given an `AsyncIterable<T>` (typically the output of `parseRecords`), produce
+ * a Node `Readable` that emits a single JSON array document without buffering
+ * the full record set.
+ *
+ * Terminal-error policy: the first record is prefetched before any bytes are
+ * pushed. A source error before the first record reaches Fastify before the
+ * response starts, so the gateway can return the standard JSON error envelope.
+ * Errors after the first record abort the stream and leave a truncated JSON
+ * document for clients to treat as a failed stream.
+ */
+import {Readable} from "node:stream";
+
+/**
+ * Wrap an async iterable of records in a Node `Readable` stream that emits a
+ * JSON array. Downstream backpressure is honored via `Readable.from`'s default
+ * behavior: the iterator's `next()` is not called until the internal buffer has
+ * room.
+ *
+ * Source errors are forwarded to the returned stream's `error` event.
+ */
+export function toJsonArray<T>(records: AsyncIterable<T>): Readable {
+  return Readable.from(encode(records), {objectMode: false, encoding: "utf-8"});
+}
+
+async function* encode<T>(records: AsyncIterable<T>): AsyncIterable<string> {
+  const iterator = records[Symbol.asyncIterator]();
+  let complete = false;
+  try {
+    const first = await iterator.next();
+    if (first.done) {
+      complete = true;
+      yield "[]";
+      return;
+    }
+
+    yield "[" + JSON.stringify(first.value);
+
+    while (true) {
+      const next = await iterator.next();
+      if (next.done) {
+        complete = true;
+        yield "]";
+        return;
+      }
+      yield "," + JSON.stringify(next.value);
+    }
+  } finally {
+    if (!complete && typeof iterator.return === "function") {
+      await iterator.return();
+    }
+  }
+}