@techspokes/typescript-wsdl-client 0.15.2 → 0.17.0

package/docs/migration-playbook.md

@@ -58,6 +58,39 @@ Open `openapi.json` and review the paths, request/response schemas, and descript
 
 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.
 
+## Step 2b (Optional): Opt Into Streaming for Large Responses
+
+Skip this step unless a specific SOAP operation returns payloads too large or too slow to buffer in memory. Good candidates are batch-style operations with repeated record elements, responses that use `xs:any` wildcards to point at concrete records in a companion WSDL, and any operation where first-byte latency matters more than total duration.
+
+Author a stream config naming those operations:
+
+```json
+{
+  "operations": {
+    "MyBatchOp": {
+      "recordType": "MyRecordType",
+      "recordPath": ["MyBatchOpResponse", "Records", "Record"]
+    }
+  }
+}
+```
+
+Regenerate with `--stream-config`:
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source your-service.wsdl \
+  --client-dir ./generated/client \
+  --openapi-file ./generated/openapi.json \
+  --gateway-dir ./generated/gateway \
+  --gateway-service-name your-service \
+  --gateway-version-prefix v1 \
+  --stream-config ./stream.config.json \
+  --init-app
+```
+
+The opted-in operations now return `StreamOperationResponse<RecordType>` on the client, serve `application/x-ndjson` on the gateway, and advertise the record schema in OpenAPI via `x-wsdl-tsc-stream`. Operations not listed in the config are unchanged. See [Stream Configuration](configuration.md#stream-configuration) for the full file reference and [ADR-002](decisions/002-streamable-responses.md) for the terminal-error policy.
+
 ## Step 3: Generate the REST Gateway
 
 Generate Fastify route handlers that translate JSON HTTP requests into SOAP calls.

package/docs/migration.md

@@ -16,12 +16,37 @@ These steps apply to every version upgrade:
 
 ## Version Compatibility
 
-| wsdl-tsc | Node.js | TypeScript | soap | Fastify |
-|----------|---------|------------|------|---------|
-| 0.10.x | >= 20.0 | >= 5.6 | >= 1.3 | >= 5.2 |
-| 0.9.x | >= 20.0 | >= 5.6 | >= 1.3 | >= 5.2 |
-| 0.8.x | >= 20.0 | >= 5.6 | >= 1.3 | >= 5.2 |
-| 0.7.x | >= 20.0 | >= 5.6 | >= 1.3 | N/A |
+| wsdl-tsc | Node.js | TypeScript | soap | Fastify | saxes |
+|----------|---------|------------|------|---------|-------|
+| 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 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` with an `x-wsdl-tsc-stream` extension, and a Fastify route that streams NDJSON with backpressure. 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](configuration.md#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
 

package/docs/output-anatomy.md

@@ -43,6 +43,24 @@ Exports a TypeScript interface with the same method signatures as the client cla
 
 Contains runtime metadata and helper functions. Includes `unwrapArrayWrappers()` for bridging between SOAP array wrapper objects and flattened OpenAPI array schemas.
 
+### Stream Operations
+
+When `--stream-config` opts an operation into streaming (see [ADR-002](decisions/002-streamable-responses.md)), the client emits additional surfaces alongside the buffered ones. Buffered operations in the same client are unaffected.
+
+`operations.ts` gains a `StreamOperationResponse<RecordType>` type that stream methods return instead of the buffered `{ response, headers, responseRaw, requestRaw }` shape:
+
+```typescript
+export type StreamOperationResponse<RecordType, HeadersType = Record<string, unknown>> = {
+  records: AsyncIterable<RecordType>;
+  headers: HeadersType;
+  requestRaw?: string;
+};
+```
+
+`client.ts` gains a protected `callStream()` transport. Stream methods bypass `node-soap` (which buffers the full response before invoking its callback, as confirmed in phase-0 research) and instead POST a hand-built SOAP envelope via global `fetch`, piping the response body through a SAX-driven record parser. `node-soap` remains the transport for buffered operations.
+
+Generated imports required at runtime: `saxes` for SAX parsing. The generated app scaffold pins `saxes ^6.0.0` automatically; manual consumers must install it explicitly.
+
 ## OpenAPI Output
 
 Generated at the path specified by `--openapi-file`.
@@ -55,6 +73,29 @@ The spec includes one POST path per WSDL operation, request and response schemas
 
 OpenAPI validation runs by default using `@apidevtools/swagger-parser`. Disable with `--openapi-validate false`.
 
+### Stream Schema Extension
+
+Stream operations do not use the standard success envelope for `200` responses. The response content declares the configured stream media type (default `application/x-ndjson`) with `schema: { "type": "string" }` and an `x-wsdl-tsc-stream` extension that carries the record schema reference:
+
+```json
+{
+  "200": {
+    "description": "Successful streamed SOAP operation response",
+    "content": {
+      "application/x-ndjson": {
+        "schema": { "type": "string" },
+        "x-wsdl-tsc-stream": {
+          "format": "ndjson",
+          "itemSchema": { "$ref": "#/components/schemas/UnitDescriptiveContentType" }
+        }
+      }
+    }
+  }
+}
+```
+
+OpenAPI 3.1 cannot fully describe an NDJSON sequence as a standard JSON Schema document, so the extension makes the item schema explicit for generated gateways, documentation tools, and future SDK generators. Error responses (400, 502, and the rest) still use the normal envelope.
+
 ## Gateway Output
 
 Generated into the directory specified by `--gateway-dir`.
@@ -74,6 +115,14 @@ Generated into the directory specified by `--gateway-dir`.
 
 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.
 
+### Stream Routes
+
+Stream-configured operations generate a different route shape. The Fastify response serialization schema is omitted because Fastify cannot serialize an unbounded stream with a normal JSON response schema. The handler sets `reply.type("application/x-ndjson")` and returns `reply.send(toNdjson(result.records))`. `runtime.ts` gains a `toNdjson<T>(records: AsyncIterable<T>): Readable` helper that wraps the async iterable in a backpressure-aware Node `Readable`. See the [Gateway Guide](gateway-guide.md#streaming-handlers) for the full handler example and terminal-error policy.
+
+### Generated Test Surface
+
+When `--test-dir` is combined with `--stream-config`, the generated happy-path tests for stream operations assert on the `application/x-ndjson` content-type and parse each line as a separate JSON record. Mock clients use async-generator overrides that yield records to drive those tests; see the [Testing Guide](testing.md) for the pattern.
+
 ### Plugin registration
 
 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.

package/docs/production.md

@@ -61,6 +61,30 @@ npx wsdl-tsc openapi --catalog-file ./build/catalog.json --openapi-file ./docs/a
 }
 ```
 
+## Streaming Operations
+
+Operations opted into streaming with `--stream-config` change the production profile of the gateway. Plan for these characteristics before rolling out.
+
+### Backpressure
+
+Records flow through `Readable.from` in the generated `runtime.ts`. The iterator's `next()` is not called until the internal buffer has room, so a slow HTTP client propagates backpressure all the way to the upstream SOAP server. A client that opens a connection and stops reading will eventually stall the upstream SOAP socket; set idle timeouts on both the gateway and the SOAP endpoint accordingly.
+
+### Connection Timeouts
+
+Stream responses can stay open for the full duration of the upstream SOAP call. The Fastify `keepAliveTimeout`, `requestTimeout`, and any reverse proxy (nginx, ALB, CloudFront) must allow the maximum expected upstream duration. Default Fastify timeouts are shorter than typical long-running SOAP batch responses.
+
+### Memory Profile
+
+Memory stays bounded regardless of payload size because records are parsed and emitted one at a time. The SAX parser buffers only within the current record element. This is the primary reason to opt into streaming: buffered operations load the full response into memory before yielding.
+
+### Observability
+
+Log the time to first record, not just the time to response completion. First-record time is the most useful SLO signal because it measures the combined latency of upstream connect, first-byte, and parser spin-up. Track it separately from total stream duration.
+
+### Terminal-Error Policy
+
+Errors raised before the first record use the normal gateway error envelope (client sees a standard JSON error). Errors raised mid-stream truncate the chunked response without a terminating zero-chunk. Consumers detect this as an incomplete HTTP response. Document this behavior for downstream API consumers so they distinguish truncation from a legitimate empty stream.
+
 ## Known Limitations
 
 ### Choice Elements
@@ -78,3 +102,11 @@ Security hints extracted from policies. Custom policies may require manual secur
 ### Array Wrapper Flattening
 
 Single-child sequences with maxOccurs>1 become array schemas. Sequences with multiple children preserve wrapper.
+
+### Stream Format Coverage
+
+Only `ndjson` is emitted today. `json-array` is reserved in the config schema but not yet implemented; opting in with `format: "json-array"` parses successfully but generates no routes for that operation.
+
+### Stream Transport Bypasses node-soap
+
+Stream operations bypass `node-soap` entirely and POST a hand-built SOAP envelope via `fetch`. Any `node-soap` middleware, interceptors, or custom security handlers that your buffered operations rely on will not apply to stream operations. Authentication headers, proxies, and TLS options must be configured on the stream transport path separately.

package/docs/start-here.md

@@ -64,6 +64,38 @@ The gateway transforms JSON HTTP requests into SOAP calls and returns JSON respo
 
 Next: [Gateway Guide](gateway-guide.md) for integration details, then [Migration Playbook](migration-playbook.md) for the full modernization workflow
 
+### I need to stream large SOAP responses
+
+Some SOAP services return payloads that are too large or too slow to buffer in memory. Opt selected operations into streaming with a small JSON config and the `--stream-config` flag. Operations not listed keep their buffered behavior, so existing output stays byte-for-byte unchanged.
+
+```bash
+npx wsdl-tsc pipeline \
+  --wsdl-source your-service.wsdl \
+  --client-dir ./generated/client \
+  --openapi-file ./generated/openapi.json \
+  --gateway-dir ./generated/gateway \
+  --gateway-service-name my-service \
+  --gateway-version-prefix v1 \
+  --stream-config ./stream.config.json
+```
+
+Minimal `stream.config.json`:
+
+```json
+{
+  "operations": {
+    "MyStreamOp": {
+      "recordType": "MyRecordType",
+      "recordPath": ["MyStreamOpResponse", "Records", "Record"]
+    }
+  }
+}
+```
+
+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.
+
+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.
+
 ## What NOT to Expect
 
 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.
@@ -80,3 +112,4 @@ 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) |

package/docs/supported-patterns.md

@@ -8,6 +8,7 @@ These patterns are handled end-to-end: WSDL parsing, TypeScript type generation,
 
 - Complex types with `<xs:sequence>`, `<xs:all>`, and `<xs:choice>` compositors, including recursive nesting
 - Simple content with attributes using the `$value` pattern to preserve text content alongside attribute properties
+- Named simple type restrictions and enumerations emitted as TypeScript aliases and OpenAPI scalar schemas
 - Type inheritance through `<xs:extension>` and `<xs:restriction>` on both simple and complex content
 - Nested XSD imports across multiple schema files with relative and absolute URI resolution
 - Multiple namespaces with deterministic collision resolution via PascalCase uniqueness
@@ -18,6 +19,34 @@ 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`
+- `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
+
+Named `xs:simpleType` declarations compile to TypeScript type aliases. Restriction enumerations compile to string literal unions in TypeScript and `enum` scalar schemas in OpenAPI.
+
+When a global `xs:element` has the same local name as a referenced named simple type, the generator reuses the simple type alias. It does not emit a second wrapper interface with the same TypeScript name.
+
+```xml
+<xs:simpleType name="MyEnum">
+  <xs:restriction base="xs:string">
+    <xs:enumeration value="Red"/>
+    <xs:enumeration value="Green"/>
+  </xs:restriction>
+</xs:simpleType>
+<xs:element name="MyEnum" nillable="true" type="tns:MyEnum"/>
+```
+
+The generated TypeScript type is a scalar alias:
+
+```typescript
+export type MyEnum = "Red" | "Green";
+```
+
+If a message part uses `tns:MyEnum` as the operation root element, the generated client method uses `MyEnum` directly for the request or response payload type.
+
+The compiler records this reuse as an informational catalog diagnostic. CLI commands print it as a `Note:` line, not as a warning.
 
 ## Partially Supported
 

package/docs/testing.md

@@ -246,6 +246,20 @@ 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:
+
+```typescript
+const client = createMockClient({
+  UnitDescriptiveInfoStream: async () => ({
+    records: (async function* () {
+      yield { Id: "1", Name: "Villa A" };
+      yield { Id: "2", Name: "Villa B" };
+    })(),
+    headers: {},
+  }),
+});
+```
+
 ## For Consumer Projects
 
 If you're using wsdl-tsc as a dependency and want to test your integration:

package/docs/troubleshooting.md

@@ -17,6 +17,12 @@ See [README](../README.md) for quick start and [CLI Reference](cli-reference.md)
 | TypeScript compilation errors | Check --import-extensions matches your tsconfig moduleResolution |
 | Gateway validation failures | Ensure OpenAPI has valid $ref paths and all schemas in components.schemas |
 | Catalog file not found | Catalog defaults to output directory; use --catalog-file to specify |
+| 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 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 |
 
 ## SOAP Wire Logging
 
@@ -68,3 +74,15 @@ Or inspect catalog from client generation:
 ```bash
 cat ./src/services/hotel/catalog.json | jq '.types'
 ```
+
+## Streaming Debug
+
+Inspect stream metadata on the compiled catalog to confirm the config was parsed and applied:
+
+```bash
+cat ./src/services/hotel/catalog.json | jq '.operations[] | select(.stream) | {name, stream}'
+```
+
+Each entry shows the normalized `OperationStreamMetadata` (mode, format, mediaType, recordPath, recordTypeName, and any `shapeCatalogName`). If an expected operation is missing, the config either did not match the WSDL operation name or was not passed to the generation command.
+
+For record-path and chunk-boundary issues, the reference integration test pattern lives in `test/integration/stream-end-to-end.test.ts` and the SAX record matcher is exercised by `test/unit/stream-xml.test.ts`. Running them against a local fixture isolates whether the issue is in the config, the parser, or the upstream SOAP server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.15.2",
+  "version": "0.17.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",
@@ -53,7 +53,9 @@
     "docs",
     "README.md",
     "LICENSE",
-    "llms.txt"
+    "llms.txt",
+    "src/runtime/*.ts",
+    "src/runtime/*.tpl.txt"
   ],
   "scripts": {
     "dev": "tsx src/cli.ts",
@@ -82,18 +84,19 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.6.0",
     "@types/yargs": "^17.0.35",
-    "fastify": "^5.8.4",
+    "fastify": "^5.8.5",
     "fastify-plugin": "^5.1.0",
     "rimraf": "^6.1.3",
     "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.0"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "fast-xml-parser": "^5.5.8",
+    "fast-xml-parser": "^5.7.1",
     "js-yaml": "^4.1.1",
-    "soap": "^1.8.0",
+    "saxes": "^6.0.0",
+    "soap": "^1.9.1",
     "yargs": "^18.0.0"
   },
   "funding": {

package/src/runtime/clientStreamMethods.tpl.txt

@@ -0,0 +1,183 @@
+
+  /**
+   * Streaming transport for operations flagged with a stream configuration.
+   *
+   * node-soap buffers the full response before invoking the operation callback
+   * (verified empirically in ADR-002 / phase-0 research), so this method
+   * bypasses node-soap and POSTs a hand-built SOAP envelope directly, then
+   * pipes the response body through the SAX-driven record parser.
+   */
+  protected async callStream<RequestType, RecordType, HeadersType>(
+    args: RequestType,
+    operation: string,
+    requestType: string | undefined,
+    recordTypeName: string,
+    inputElementLocal: string,
+    inputElementNs: string,
+    soapAction: string,
+    recordPath: string[]
+  ): Promise<StreamOperationResponse<RecordType, HeadersType>> {
+    const client = await this.soapClient();
+    const endpoint = this.resolveStreamEndpoint(client);
+    const envelope = this.buildSoapEnvelope(args, operation, requestType, inputElementLocal, inputElementNs);
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "text/xml; charset=utf-8",
+        "soapaction": '"' + soapAction + '"',
+      },
+      body: envelope,
+    });
+    if (!res.ok) {
+      throw new Error(
+        operation + " stream request failed: " + res.status + " " + res.statusText
+      );
+    }
+    if (!res.body) {
+      throw new Error(operation + " stream request returned an empty response body");
+    }
+    const headers: Record<string, string> = {};
+    res.headers.forEach((value, key) => { headers[key] = value; });
+    const spec: RecordParseSpec = {
+      recordPath,
+      recordTypeName,
+      attributesKey: this.attributesKeyOut,
+      childType: this.dataTypes?.ChildrenTypes,
+    };
+    const records = parseRecords<RecordType>(
+      this.webStreamToAsyncIterable(res.body),
+      spec
+    );
+    return {
+      records,
+      headers: headers as unknown as HeadersType,
+      requestRaw: envelope,
+    };
+  }
+
+  /**
+   * Walk the node-soap WSDL descriptor to locate the first service port's
+   * SOAP address. Falls back to the \`source\` URL when the descriptor is
+   * unavailable (e.g., \`source\` was given as a direct endpoint URL).
+   */
+  protected resolveStreamEndpoint(client: soap.Client): string {
+    const services = (client as any)?.wsdl?.definitions?.services ?? {};
+    for (const svc of Object.values(services)) {
+      const ports = (svc as any)?.ports ?? {};
+      for (const port of Object.values(ports)) {
+        const location = (port as any)?.location;
+        if (typeof location === "string" && location) return location;
+      }
+    }
+    return this.source;
+  }
+
+  /**
+   * Build a SOAP 1.1 envelope around the operation's input element. Uses the
+   * existing attributes / children metadata so attribute bags render as XML
+   * attributes and child properties render as nested elements.
+   */
+  protected buildSoapEnvelope(
+    args: unknown,
+    operation: string,
+    requestType: string | undefined,
+    inputElementLocal: string,
+    inputElementNs: string
+  ): string {
+    const body = this.toXmlElement(args, requestType, inputElementLocal, inputElementNs);
+    return '<?xml version="1.0" encoding="utf-8"?>' +
+      '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' +
+      '<soap:Body>' + body + '</soap:Body>' +
+      '</soap:Envelope>';
+  }
+
+  /**
+   * Serialize a value as a single XML element. The element namespace is only
+   * emitted when \`namespace\` is provided (i.e., the envelope's top-level body
+   * element). Nested elements inherit the namespace via XML scoping.
+   */
+  protected toXmlElement(
+    value: unknown,
+    typeName: string | undefined,
+    elementName: string,
+    namespace?: string
+  ): string {
+    const nsAttr = namespace ? ' xmlns="' + this.escapeXml(namespace) + '"' : "";
+    if (value === null || value === undefined) {
+      return '<' + elementName + nsAttr +
+        ' xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>';
+    }
+    if (typeof value !== "object") {
+      return '<' + elementName + nsAttr + '>' + this.escapeXml(String(value)) + '</' + elementName + '>';
+    }
+    if (Array.isArray(value)) {
+      return value.map((v) => this.toXmlElement(v, typeName, elementName, namespace)).join("");
+    }
+    const obj = value as Record<string, unknown>;
+    const attributesList = (typeName && this.dataTypes?.Attributes?.[typeName]) || [];
+    const childrenTypes = (typeName && this.dataTypes?.ChildrenTypes?.[typeName]) || {};
+    const attrPairs: Array<[string, string]> = [];
+    const bagIn = (obj as any)[this.attributesKeyIn] ?? (obj as any)["attributes"];
+    if (bagIn && typeof bagIn === "object") {
+      for (const [k, v] of Object.entries(bagIn)) attrPairs.push([k, this.normalizeAttr(v)]);
+    }
+    const childParts: string[] = [];
+    let textContent: string | undefined;
+    if ("$value" in obj) textContent = String(obj.$value ?? "");
+    for (const [k, v] of Object.entries(obj)) {
+      if (k === "$value" || k === this.attributesKeyIn || k === "attributes") continue;
+      if ((attributesList as readonly string[]).includes(k)) {
+        attrPairs.push([k, this.normalizeAttr(v)]);
+        continue;
+      }
+      const childTypeRaw = (childrenTypes as Record<string, string>)[k];
+      const childType = childTypeRaw?.endsWith("[]") ? childTypeRaw.slice(0, -2) : childTypeRaw;
+      if (Array.isArray(v)) {
+        for (const item of v) childParts.push(this.toXmlElement(item, childType, k));
+      } else {
+        childParts.push(this.toXmlElement(v, childType, k));
+      }
+    }
+    const attrStr = attrPairs.map(([k, val]) => ' ' + k + '="' + this.escapeXml(val) + '"').join("");
+    if (childParts.length === 0 && textContent === undefined) {
+      return '<' + elementName + nsAttr + attrStr + '/>';
+    }
+    const inner = childParts.join("") + (textContent !== undefined ? this.escapeXml(textContent) : "");
+    return '<' + elementName + nsAttr + attrStr + '>' + inner + '</' + elementName + '>';
+  }
+
+  protected normalizeAttr(v: unknown): string {
+    if (v === null || v === undefined) return "";
+    if (typeof v === "boolean") return v ? "true" : "false";
+    if (typeof v === "number") return Number.isFinite(v) ? String(v) : "";
+    return String(v);
+  }
+
+  protected escapeXml(s: string): string {
+    return s
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&apos;");
+  }
+
+  /**
+   * Iterate an uploaded web ReadableStream as Uint8Array chunks. Node 20+
+   * ReadableStream implements Symbol.asyncIterator natively; this helper
+   * normalizes the types so TypeScript can drive it through \`for await\`.
+   */
+  protected async *webStreamToAsyncIterable(
+    body: ReadableStream<Uint8Array>
+  ): AsyncIterable<Uint8Array> {
+    const reader = body.getReader();
+    try {
+      while (true) {
+        const {value, done} = await reader.read();
+        if (done) return;
+        if (value) yield value;
+      }
+    } finally {
+      try { reader.releaseLock(); } catch { /* noop */ }
+    }
+  }

package/src/runtime/ndjson.ts

@@ -0,0 +1,32 @@
+/**
+ * NDJSON adapter for record iterables.
+ *
+ * Phase 3 of ADR-002. Given an `AsyncIterable<T>` (typically the output of
+ * `parseRecords`), produce a Node `Readable` that emits one JSON-encoded line
+ * per record and respects downstream backpressure.
+ *
+ * Terminal-error policy (Q3 resolved): the stream aborts on source errors.
+ * Before-first-byte errors surface as the stream's `error` event before any
+ * bytes are pushed, so Fastify can translate them into a normal JSON error
+ * envelope. Errors after the first byte propagate as `error` events too, but
+ * callers should treat them as a truncated response.
+ */
+import {Readable} from "node:stream";
+
+/**
+ * Wrap an async iterable of records in a Node `Readable` stream that emits
+ * NDJSON (one JSON document per line, LF-terminated). 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 toNdjson<T>(records: AsyncIterable<T>): Readable {
+  return Readable.from(encode(records), {objectMode: false, encoding: "utf-8"});
+}
+
+async function* encode<T>(records: AsyncIterable<T>): AsyncIterable<string> {
+  for await (const record of records) {
+    yield JSON.stringify(record) + "\n";
+  }
+}

package/src/runtime/operationsStreamHelper.tpl.txt

@@ -0,0 +1,13 @@
+/**
+ * Response shape for streaming __CLIENT_NAME__ operations. `records` is a
+ * single-pass async iterable of parsed record objects; iteration pulls bytes
+ * from the upstream SOAP response on demand. `headers` is the HTTP response
+ * header map captured before the first record is parsed. `requestRaw`, when
+ * populated, contains the serialized SOAP envelope that was sent upstream.
+ */
+export type StreamOperationResponse<RecordType, HeadersType = Record<string, unknown>> = {
+  records: AsyncIterable<RecordType>;
+  headers: HeadersType;
+  requestRaw?: string;
+};
+