@techspokes/typescript-wsdl-client 0.16.1 → 0.17.0

package/dist/util/streamConfig.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Per-operation stream metadata, normalized form. Exported so that the
+ * compiler, emitters, and gateway all consume the same shape.
+ */
+export interface OperationStreamMetadata {
+    mode: "stream";
+    format: "ndjson" | "json-array";
+    mediaType: string;
+    recordPath: string[];
+    recordTypeName: string;
+    shapeCatalogName?: string;
+    sourceOutputTypeName?: string;
+}
+/**
+ * Reference to a companion catalog that supplies record shapes. Exactly one
+ * of `wsdlSource` or `catalogFile` must be set.
+ */
+export interface ShapeCatalogRef {
+    wsdlSource?: string;
+    catalogFile?: string;
+}
+/**
+ * Parsed and normalized stream configuration.
+ */
+export interface StreamConfig {
+    shapeCatalogs: Record<string, ShapeCatalogRef>;
+    operations: Record<string, OperationStreamMetadata>;
+}
+/**
+ * Structured error thrown when a stream configuration cannot be parsed.
+ * The CLI error handler prints `.toUserMessage()` verbatim.
+ */
+export declare class StreamConfigError extends Error {
+    readonly context: {
+        file?: string;
+        pointer?: string;
+        suggestion?: string;
+    };
+    readonly name = "StreamConfigError";
+    constructor(message: string, context?: {
+        file?: string;
+        pointer?: string;
+        suggestion?: string;
+    });
+    toUserMessage(): string;
+}
+/**
+ * Parse a stream configuration from an in-memory JSON value. Used directly
+ * by tests; the file-based variant below wraps this.
+ */
+export declare function parseStreamConfig(raw: unknown, opts?: {
+    file?: string;
+}): StreamConfig;
+/**
+ * Load and parse a stream configuration file. Relative paths are resolved
+ * against the caller's cwd.
+ */
+export declare function loadStreamConfigFile(filePath: string): StreamConfig;
+//# sourceMappingURL=streamConfig.d.ts.map

package/dist/util/streamConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamConfig.d.ts","sourceRoot":"","sources":["../../src/util/streamConfig.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAG1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;CACrD;AAED;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAKxB,OAAO,EAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAC;IAJjF,SAAkB,IAAI,uBAAuB;gBAG3C,OAAO,EAAE,MAAM,EACC,OAAO,GAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAM;IAKtF,aAAa,IAAI,MAAM;CAOxB;AASD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAM,GAAG,YAAY,CAwBxF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAqBnE"}

package/dist/util/streamConfig.js

@@ -0,0 +1,230 @@
+/**
+ * Stream-configuration parsing and validation.
+ *
+ * Backs the `--stream-config <file>` CLI flag on every generation command.
+ * The file is a small JSON document that marks selected WSDL operations as
+ * streamable and optionally declares companion catalogs that supply record
+ * shapes not present in the main WSDL. See `docs/decisions/002-streamable-responses.md`.
+ *
+ * This module is parser-only: it reads the JSON, validates it, and returns a
+ * normalized shape. It never loads companion catalogs or compiles WSDLs —
+ * that is the shape-resolver's job in phase-2.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Structured error thrown when a stream configuration cannot be parsed.
+ * The CLI error handler prints `.toUserMessage()` verbatim.
+ */
+export class StreamConfigError extends Error {
+    context;
+    name = "StreamConfigError";
+    constructor(message, context = {}) {
+        super(message);
+        this.context = context;
+    }
+    toUserMessage() {
+        const parts = [this.message];
+        if (this.context.pointer)
+            parts.push(`  At: ${this.context.pointer}`);
+        if (this.context.file)
+            parts.push(`  File: ${this.context.file}`);
+        if (this.context.suggestion)
+            parts.push(`  Suggestion: ${this.context.suggestion}`);
+        return parts.join("\n");
+    }
+}
+const SUPPORTED_FORMATS = new Set(["ndjson", "json-array"]);
+const DEFAULT_MEDIA_TYPE_BY_FORMAT = {
+    "ndjson": "application/x-ndjson",
+    "json-array": "application/json",
+};
+/**
+ * Parse a stream configuration from an in-memory JSON value. Used directly
+ * by tests; the file-based variant below wraps this.
+ */
+export function parseStreamConfig(raw, opts = {}) {
+    const file = opts.file;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new StreamConfigError("Stream config must be a JSON object.", {
+            file,
+            pointer: "$",
+            suggestion: `Expected an object with "shapeCatalogs" and "operations" keys.`,
+        });
+    }
+    const obj = raw;
+    const shapeCatalogs = parseShapeCatalogs(obj["shapeCatalogs"], file);
+    const operations = parseOperations(obj["operations"], shapeCatalogs, file);
+    if (Object.keys(operations).length === 0) {
+        throw new StreamConfigError(`Stream config must declare at least one operation.`, {
+            file,
+            pointer: "$.operations",
+            suggestion: `Add an entry under "operations" keyed by the WSDL operation name.`,
+        });
+    }
+    return { shapeCatalogs, operations };
+}
+/**
+ * Load and parse a stream configuration file. Relative paths are resolved
+ * against the caller's cwd.
+ */
+export function loadStreamConfigFile(filePath) {
+    const abs = path.resolve(filePath);
+    let text;
+    try {
+        text = fs.readFileSync(abs, "utf-8");
+    }
+    catch (err) {
+        throw new StreamConfigError(`Failed to read stream config file: ${err.message}`, { file: abs, suggestion: "Check that --stream-config points to an existing, readable file." });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new StreamConfigError(`Stream config file is not valid JSON: ${err.message}`, { file: abs, suggestion: "Fix the JSON syntax and retry." });
+    }
+    return parseStreamConfig(parsed, { file: abs });
+}
+function parseShapeCatalogs(raw, file) {
+    if (raw === undefined)
+        return {};
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new StreamConfigError(`"shapeCatalogs" must be an object.`, {
+            file,
+            pointer: "$.shapeCatalogs",
+        });
+    }
+    const out = {};
+    for (const [name, entry] of Object.entries(raw)) {
+        if (!name) {
+            throw new StreamConfigError(`"shapeCatalogs" keys must be non-empty strings.`, {
+                file,
+                pointer: `$.shapeCatalogs`,
+            });
+        }
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new StreamConfigError(`Shape catalog "${name}" must be an object.`, {
+                file,
+                pointer: `$.shapeCatalogs.${name}`,
+            });
+        }
+        const e = entry;
+        const wsdlSource = e["wsdlSource"];
+        const catalogFile = e["catalogFile"];
+        if (wsdlSource !== undefined && catalogFile !== undefined) {
+            throw new StreamConfigError(`Shape catalog "${name}" must set exactly one of "wsdlSource" or "catalogFile", not both.`, { file, pointer: `$.shapeCatalogs.${name}` });
+        }
+        if (wsdlSource === undefined && catalogFile === undefined) {
+            throw new StreamConfigError(`Shape catalog "${name}" must set one of "wsdlSource" or "catalogFile".`, { file, pointer: `$.shapeCatalogs.${name}` });
+        }
+        if (wsdlSource !== undefined && (typeof wsdlSource !== "string" || !wsdlSource)) {
+            throw new StreamConfigError(`Shape catalog "${name}".wsdlSource must be a non-empty string.`, { file, pointer: `$.shapeCatalogs.${name}.wsdlSource` });
+        }
+        if (catalogFile !== undefined && (typeof catalogFile !== "string" || !catalogFile)) {
+            throw new StreamConfigError(`Shape catalog "${name}".catalogFile must be a non-empty string.`, { file, pointer: `$.shapeCatalogs.${name}.catalogFile` });
+        }
+        out[name] = {
+            wsdlSource: wsdlSource,
+            catalogFile: catalogFile,
+        };
+    }
+    return out;
+}
+function parseOperations(raw, shapeCatalogs, file) {
+    if (raw === undefined) {
+        throw new StreamConfigError(`"operations" is required.`, {
+            file,
+            pointer: "$.operations",
+        });
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new StreamConfigError(`"operations" must be an object.`, {
+            file,
+            pointer: "$.operations",
+        });
+    }
+    const out = {};
+    for (const [opName, entry] of Object.entries(raw)) {
+        if (!opName) {
+            throw new StreamConfigError(`"operations" keys must be non-empty strings.`, {
+                file,
+                pointer: `$.operations`,
+            });
+        }
+        out[opName] = parseOperationEntry(opName, entry, shapeCatalogs, file);
+    }
+    return out;
+}
+function parseOperationEntry(opName, raw, shapeCatalogs, file) {
+    const pointer = `$.operations.${opName}`;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new StreamConfigError(`Operation "${opName}" must be an object.`, { file, pointer });
+    }
+    const e = raw;
+    // mode
+    const mode = e["mode"];
+    if (mode !== undefined && mode !== "stream") {
+        throw new StreamConfigError(`Operation "${opName}".mode must be "stream" (or omitted).`, { file, pointer: `${pointer}.mode` });
+    }
+    // format
+    const formatRaw = e["format"] ?? "ndjson";
+    if (typeof formatRaw !== "string" || !SUPPORTED_FORMATS.has(formatRaw)) {
+        throw new StreamConfigError(`Operation "${opName}".format must be one of: ${[...SUPPORTED_FORMATS].join(", ")}.`, { file, pointer: `${pointer}.format` });
+    }
+    const format = formatRaw;
+    // mediaType (optional; derived from format when absent)
+    const mediaTypeRaw = e["mediaType"];
+    let mediaType;
+    if (mediaTypeRaw === undefined) {
+        mediaType = DEFAULT_MEDIA_TYPE_BY_FORMAT[format];
+    }
+    else if (typeof mediaTypeRaw !== "string" || !mediaTypeRaw.includes("/")) {
+        throw new StreamConfigError(`Operation "${opName}".mediaType must be a string of the form "type/subtype".`, { file, pointer: `${pointer}.mediaType` });
+    }
+    else {
+        mediaType = mediaTypeRaw;
+    }
+    // recordType
+    const recordTypeRaw = e["recordType"];
+    if (typeof recordTypeRaw !== "string" || !recordTypeRaw) {
+        throw new StreamConfigError(`Operation "${opName}".recordType is required and must be a non-empty string.`, { file, pointer: `${pointer}.recordType` });
+    }
+    const recordTypeName = recordTypeRaw;
+    // recordPath
+    const recordPathRaw = e["recordPath"];
+    if (!Array.isArray(recordPathRaw) || recordPathRaw.length === 0) {
+        throw new StreamConfigError(`Operation "${opName}".recordPath must be a non-empty array of element local names.`, { file, pointer: `${pointer}.recordPath` });
+    }
+    const recordPath = [];
+    recordPathRaw.forEach((seg, i) => {
+        if (typeof seg !== "string" || !seg) {
+            throw new StreamConfigError(`Operation "${opName}".recordPath[${i}] must be a non-empty string.`, { file, pointer: `${pointer}.recordPath[${i}]` });
+        }
+        recordPath.push(seg);
+    });
+    // shapeCatalog (optional reference to shapeCatalogs entry)
+    const shapeCatalogRaw = e["shapeCatalog"];
+    let shapeCatalogName;
+    if (shapeCatalogRaw !== undefined) {
+        if (typeof shapeCatalogRaw !== "string" || !shapeCatalogRaw) {
+            throw new StreamConfigError(`Operation "${opName}".shapeCatalog must be a non-empty string.`, { file, pointer: `${pointer}.shapeCatalog` });
+        }
+        if (!(shapeCatalogRaw in shapeCatalogs)) {
+            throw new StreamConfigError(`Operation "${opName}".shapeCatalog references "${shapeCatalogRaw}" which is not declared under "shapeCatalogs".`, {
+                file,
+                pointer: `${pointer}.shapeCatalog`,
+                suggestion: `Add a "shapeCatalogs.${shapeCatalogRaw}" entry, or remove the reference.`,
+            });
+        }
+        shapeCatalogName = shapeCatalogRaw;
+    }
+    return {
+        mode: "stream",
+        format,
+        mediaType,
+        recordPath,
+        recordTypeName,
+        shapeCatalogName,
+    };
+}

package/docs/README.md

@@ -27,6 +27,7 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [api-reference.md](api-reference.md): programmatic TypeScript API
 - [concepts.md](concepts.md): flattening, `$value`, primitives, determinism
 - [architecture.md](architecture.md): internal pipeline for contributors
+- [decisions/002-streamable-responses.md](decisions/002-streamable-responses.md): opt-in streaming design (client `AsyncIterable`, gateway NDJSON, `x-wsdl-tsc-stream` OpenAPI extension); shipped in 0.17.0
 - [migration.md](migration.md): upgrading between package versions
 
 ## Conventions

package/docs/api-reference.md

@@ -37,9 +37,13 @@ function compileWsdlToProject(input: {
   wsdl: string;
   outDir: string;
   options?: Partial<CompilerOptions>;
+  streamConfigFile?: string;
+  streamConfig?: StreamConfig;
 }): Promise<void>;
 ```
 
+`streamConfigFile` points at a JSON file parsed by `loadStreamConfigFile`. `streamConfig` accepts an already-parsed value; `streamConfigFile` takes precedence when both are set. Buffered generation is unchanged when both are omitted. See [Stream Configuration](configuration.md#stream-configuration) for the file format and [ADR-002](decisions/002-streamable-responses.md) for rationale.
+
 ### CompilerOptions
 
 ```typescript
@@ -219,5 +223,147 @@ interface PipelineOptions {
   gateway?: Omit<GenerateGatewayOptions, "openapiFile" | "openapiDocument"> & {
     outDir?: string;
   };
+  streamConfigFile?: string;
+  streamConfig?: StreamConfig;
+}
+```
+
+`streamConfigFile` and `streamConfig` are threaded through the compile step and into every downstream emitter via `catalog.json`. Relative paths in `shapeCatalogs` resolve against the stream-config file's directory when `streamConfigFile` is used, otherwise against the WSDL's directory.
+
+## Stream Configuration Helpers
+
+These exports back the `--stream-config` CLI flag and are also usable directly in programmatic flows.
+
+### loadStreamConfigFile
+
+Read a stream-config JSON file from disk and return a parsed, validated `StreamConfig`. Throws `StreamConfigError` on missing files, invalid JSON, or schema violations.
+
+```typescript
+import { loadStreamConfigFile } from "@techspokes/typescript-wsdl-client";
+
+const streamConfig = loadStreamConfigFile("./stream.config.json");
+```
+
+### parseStreamConfig
+
+Parse and validate a stream configuration from an in-memory value. Useful when the config originates from a build tool or a remote source rather than a file.
+
+```typescript
+import { parseStreamConfig } from "@techspokes/typescript-wsdl-client";
+
+const streamConfig = parseStreamConfig({
+  operations: {
+    MyStreamOp: {
+      recordType: "MyRecordType",
+      recordPath: ["MyStreamOpResponse", "Records", "Record"],
+    },
+  },
+});
+```
+
+### StreamConfigError
+
+Thrown by `loadStreamConfigFile` and `parseStreamConfig` when the configuration is invalid. Use `.toUserMessage()` to render a multi-line, human-readable error suitable for CLI output.
+
+```typescript
+import { StreamConfigError } from "@techspokes/typescript-wsdl-client";
+
+try {
+  loadStreamConfigFile("./stream.config.json");
+} catch (err) {
+  if (err instanceof StreamConfigError) {
+    console.error(err.toUserMessage());
+    process.exit(1);
+  }
+  throw err;
+}
+```
+
+### applyShapeCatalogs
+
+Resolve companion catalogs against a compiled catalog, copying reachable record-type graphs into place. `runGenerationPipeline` and `compileWsdlToProject` call this automatically when a stream config is present; it is exported for custom pipelines.
+
+```typescript
+import {
+  applyShapeCatalogs,
+  loadStreamConfigFile,
+} from "@techspokes/typescript-wsdl-client";
+import path from "node:path";
+
+const streamConfig = loadStreamConfigFile("./stream.config.json");
+await applyShapeCatalogs(compiled, streamConfig, {
+  baseDir: path.dirname(path.resolve("./stream.config.json")),
+});
+```
+
+### ApplyShapeCatalogsOptions
+
+```typescript
+interface ApplyShapeCatalogsOptions {
+  baseDir?: string;
 }
 ```
+
+`baseDir` is the directory against which relative `catalogFile` and `wsdlSource` paths are resolved. Defaults to `process.cwd()`.
+
+### StreamConfig
+
+```typescript
+interface StreamConfig {
+  shapeCatalogs: Record<string, ShapeCatalogRef>;
+  operations: Record<string, OperationStreamMetadata>;
+}
+
+interface ShapeCatalogRef {
+  wsdlSource?: string;
+  catalogFile?: string;
+}
+
+interface OperationStreamMetadata {
+  mode: "stream";
+  format: "ndjson" | "json-array";
+  mediaType: string;
+  recordPath: string[];
+  recordTypeName: string;
+  shapeCatalogName?: string;
+  sourceOutputTypeName?: string;
+}
+```
+
+Exactly one of `wsdlSource` or `catalogFile` must be set on each `ShapeCatalogRef`. `OperationStreamMetadata` is produced by the parser; `sourceOutputTypeName` is populated by the compiler when it binds the operation to the main WSDL.
+
+## End-to-End Example
+
+Compile with a stream config, verify the catalog carries the expected metadata, and run the full pipeline:
+
+```typescript
+import {
+  loadStreamConfigFile,
+  runGenerationPipeline,
+} from "@techspokes/typescript-wsdl-client";
+
+const streamConfig = loadStreamConfigFile("./stream.config.json");
+
+const { compiled, openapiDoc } = await runGenerationPipeline({
+  wsdl: "./wsdl/Service.wsdl",
+  catalogOut: "./build/service-catalog.json",
+  clientOutDir: "./src/services/service",
+  compiler: { imports: "js" },
+  openapi: {
+    outFile: "./docs/service-api.json",
+    format: "json",
+    servers: ["https://api.example.com/v1"],
+  },
+  gateway: {
+    outDir: "./src/gateway/service",
+    versionSlug: "v1",
+    serviceSlug: "service",
+  },
+  streamConfig,
+});
+
+const streamOp = compiled.operations.find((op) => op.stream);
+console.log(streamOp?.stream?.mediaType); // "application/x-ndjson"
+```
+
+The generated client exports a `StreamOperationResponse<RecordType>` type; each stream-configured operation returns `Promise<StreamOperationResponse<RecordType>>` with `records: AsyncIterable<RecordType>`.

package/docs/architecture.md

@@ -7,9 +7,9 @@ See [CONTRIBUTING](../CONTRIBUTING.md) for development setup and [README](../REA
 ## Pipeline Overview
 
 ```text
-WSDL Source
-    |
-    v
+WSDL Source       Stream Config (optional)
+    |                    |
+    v                    v
 Loader (fetch.ts, wsdlLoader.ts)
     Fetches WSDL from URL or file
     Returns parsed XML document
@@ -17,9 +17,16 @@ Loader (fetch.ts, wsdlLoader.ts)
     v
 Compiler (schemaCompiler.ts)
     Walks XSD types, resolves references
+    Retains xs:any wildcard particles
     Produces CompiledCatalog
     |
     v
+Shape Resolver (shapeResolver.ts, optional)
+    Loads companion catalogs
+    Copies reachable record-type graphs
+    Fails on structural name collisions
+    |
+    v
 Catalog Emitter (generateCatalog.ts)
     Serializes to catalog.json
     |
@@ -38,7 +45,7 @@ fetch.ts handles HTTP/HTTPS/file fetching. wsdlLoader.ts handles XML parsing and
 
 ### compiler/
 
-schemaCompiler.ts is the core compiler. It walks XSD complex/simple types, resolves inheritance, handles choices, and builds the type graph. generateCatalog.ts serializes compiled types to catalog.json.
+schemaCompiler.ts is the core compiler. It walks XSD complex/simple types, resolves inheritance, handles choices, retains xs:any wildcard particles as catalog metadata, and builds the type graph. generateCatalog.ts serializes compiled types to catalog.json. shapeResolver.ts resolves companion catalogs: it loads each referenced `shapeCatalog` once, copies the reachable record-type graph into the current compilation, and enforces structural-equality collision checks. It mutates the compiled catalog in place and is invoked after schemaCompiler.ts whenever a stream config is present.
 
 ### client/
 
@@ -62,7 +69,11 @@ pipeline.ts orchestrates the full pipeline from compile through app generation.
 
 ### util/
 
-tools.ts provides string helpers (pascal, kebab, QName resolution). cli.ts provides console output helpers and error handling. builder.ts provides shared Yargs option builders.
+tools.ts provides string helpers (pascal, kebab, QName resolution). cli.ts provides console output helpers and error handling. builder.ts provides shared Yargs option builders. streamConfig.ts parses and validates `--stream-config` input into a normalized `StreamConfig` shape; it is parser-only and never touches the filesystem beyond reading the config file itself. runtimeSource.ts reads template strings for the client stream transport.
+
+### runtime/
+
+Template sources embedded into generated clients and gateways. streamXml.ts implements a SAX-driven `parseRecords(stream, spec)` that tracks the configured `recordPath` positionally (duplicate local names allowed) and yields records as their closing tags arrive. ndjson.ts wraps an async iterable of records in a `Readable` that emits NDJSON lines with honored backpressure. clientStreamMethods.tpl.txt and operationsStreamHelper.tpl.txt are text templates emitted into the generated `client.ts` and `operations.ts` when stream operations are present; they encode the `callStream()` transport and the `StreamOperationResponse<T>` type.
 
 ### xsd/
 
@@ -115,3 +126,14 @@ Data flow through the pipeline:
 1. Add mapping in src/xsd/primitives.ts
 2. Handle in src/compiler/schemaCompiler.ts if needed
 3. Update src/openapi/generateSchemas.ts for JSON Schema output
+
+### Adding a Stream-Capable Operation Output
+
+1. Add a `stream-config` JSON entry for the operation with `recordType` and `recordPath`
+2. Declare a `shapeCatalog` entry when the record type lives in a companion WSDL
+3. Run the compile command and verify `catalog.operations[].stream` carries normalized metadata
+4. The client, OpenAPI, and gateway emitters consume that metadata automatically; no per-emitter code changes are required
+
+## Client Stream Transport
+
+Phase-0 research (see ADR-002) established that `node-soap` buffers the full response before invoking its operation callback. Stream operations cannot use that transport, so the generated client emits a parallel `callStream()` method that POSTs a hand-built SOAP envelope via global `fetch`, captures HTTP headers before the first record, and pipes the response body through `parseRecords`. Buffered operations continue to use `node-soap` unchanged. The two transports coexist on the same client class.

package/docs/cli-reference.md

@@ -129,6 +129,36 @@ The catalog is auto-placed alongside the first available output directory: `{cli
 | `--test-dir` | (none) | Generate Vitest test suite in this directory (requires client, gateway) |
 | `--force-test` | `false` | Overwrite existing test files when using --test-dir |
 
+### Stream Configuration Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--stream-config` | (none) | Path to a JSON stream-configuration file (ADR-002). Marks selected operations as streaming: client emits `AsyncIterable<RecordType>`, gateway serves NDJSON, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`. Buffered output is unchanged when the flag is omitted. |
+
+`--stream-config` is accepted on the `compile`, `client`, and `pipeline` commands. It is not accepted on `openapi`, `gateway`, or `app` because those consume a pre-compiled `catalog.json` that already carries the normalized stream metadata.
+
+Stream-config file shape (see `docs/decisions/002-streamable-responses.md`):
+
+```json
+{
+  "shapeCatalogs": {
+    "main": { "wsdlSource": "https://api.example.com/Main.svc?singleWsdl" }
+  },
+  "operations": {
+    "UnitDescriptiveInfoStream": {
+      "recordType": "UnitDescriptiveContentType",
+      "recordPath": [
+        "UnitDescriptiveInfoStream",
+        "EVRN_UnitDescriptiveInfoRS",
+        "UnitDescriptiveContents",
+        "UnitDescriptiveContent"
+      ],
+      "shapeCatalog": "main"
+    }
+  }
+}
+```
+
 ### Pipeline Workflow
 
 Steps execute in order:

package/docs/concepts.md

@@ -230,6 +230,10 @@ details:
 }
 ```
 
+### Streaming Bypass
+
+Operations opted into streaming with `--stream-config` bypass the success envelope on the `200` response path. The OpenAPI response content is declared as the configured stream media type (default `application/x-ndjson`) and the gateway writes raw NDJSON lines straight to the response body. Error responses (400, 502, and the rest) still use the normal envelope so clients always see structured failures before the first record. See [ADR-002](decisions/002-streamable-responses.md) for the full rationale.
+
 ### Envelope Naming
 
 The base envelope is named `${serviceName}ResponseEnvelope`. Override with
@@ -337,3 +341,50 @@ schemas, and detects circular dependencies.
 
 Disable with `--openapi-validate false` or `validate: false` in the
 programmatic API.
+
+## Streaming vs Buffered Responses
+
+The generator produces two response execution models. Buffered is the default and only path for operations not listed in a stream config. Streaming is opt-in and operation-scoped; it changes the emitted client method signature, the OpenAPI response description, and the Fastify route shape for that operation only.
+
+### Execution Model Contrast
+
+Buffered operations call `node-soap`, wait for the full response to materialize, and return `{ response, headers, responseRaw, requestRaw }`. Streaming operations bypass `node-soap`, POST a hand-built SOAP envelope via `fetch`, and return `StreamOperationResponse<RecordType>` with `records: AsyncIterable<RecordType>`. The SAX parser in `runtime/streamXml.ts` walks the configured `recordPath` and yields each record as its closing tag arrives.
+
+The catalog is the source of truth for stream metadata. Each opted-in operation carries an `OperationStreamMetadata` entry, and downstream emitters (client, OpenAPI, gateway, tests) all read from the catalog. OpenAPI carries a derived view via the `x-wsdl-tsc-stream` extension.
+
+### Terminal-Error Policy
+
+Errors before the first record use the normal gateway error envelope because the response headers and status have not been committed yet. Errors mid-stream truncate the chunked response without a terminating zero-chunk; consumers detect this as an incomplete HTTP response and must treat it as a failure. NDJSON has no native error frame, and emitting a fake one would conflict with the item schema. This behavior is documented for operators in the [Production Guide](production.md#terminal-error-policy).
+
+## Companion Catalogs and Shape Resolution
+
+Some vendor WSDLs split their types across multiple services. The stream wrapper operation lives in one WSDL while the concrete record type lives in a companion WSDL. The stream config's `shapeCatalogs` section names additional WSDL or catalog inputs used only to resolve record shapes.
+
+### How Resolution Works
+
+When an operation names a `shapeCatalog`, the compiler loads the companion catalog once, copies the reachable record-type graph into the current compilation, and fails loudly on structural name collisions. Structurally identical types dedupe silently, so two catalogs that share a common base type do not conflict.
+
+```json
+{
+  "shapeCatalogs": {
+    "main": { "wsdlSource": "https://api.example.com/Main.svc?singleWsdl" }
+  },
+  "operations": {
+    "StreamOp": {
+      "recordType": "ConcreteRecordType",
+      "recordPath": ["StreamOpResponse", "Records", "Record"],
+      "shapeCatalog": "main"
+    }
+  }
+}
+```
+
+### Collision Handling
+
+A structural collision means two types share a name but differ in fields. The build fails with a diagnostic naming both source catalogs. Rename in the companion source or point `recordType` at a distinct subtree. Silent renames are intentionally disallowed because they would produce ambiguous public APIs.
+
+## xs:any Wildcard Retention
+
+XSD wildcards (`<xs:any>`) were silently dropped by earlier compiler versions. Since 0.17.0 the compiler retains them on the compiled type alongside any concrete children. This enables two downstream behaviors: honest stream-candidate detection (a wrapper that contains a wildcard is a likely streaming target) and accurate companion-catalog resolution (the compiler knows which elements are open for record types to slot into).
+
+The retained wildcard is metadata only. It does not emit TypeScript `any` or loosen the generated types; concrete fields remain strictly typed.

package/docs/configuration.md

@@ -65,6 +65,46 @@ Per-operation overrides for method, summary, description, and deprecation.
 }
 ```
 
+## Stream Configuration
+
+The `--stream-config <file>` flag (available on `compile`, `client`, `pipeline`)
+opts selected WSDL operations into streaming. Buffered output is unchanged for
+operations not listed in the file.
+
+```json
+{
+  "shapeCatalogs": {
+    "main": { "wsdlSource": "https://api.example.com/Main.svc?singleWsdl" }
+  },
+  "operations": {
+    "UnitDescriptiveInfoStream": {
+      "format": "ndjson",
+      "mediaType": "application/x-ndjson",
+      "recordType": "UnitDescriptiveContentType",
+      "recordPath": [
+        "UnitDescriptiveInfoStream",
+        "EVRN_UnitDescriptiveInfoRS",
+        "UnitDescriptiveContents",
+        "UnitDescriptiveContent"
+      ],
+      "shapeCatalog": "main"
+    }
+  }
+}
+```
+
+- `recordType` and `recordPath` are required; `format` defaults to `ndjson` and
+  `mediaType` to `application/x-ndjson`.
+- `shapeCatalog` references a `shapeCatalogs` entry and is only needed when
+  the record type lives in a different WSDL than the one driving generation.
+- Shape catalogs accept either `wsdlSource` (fetched and compiled on the fly)
+  or `catalogFile` (path to a pre-compiled `catalog.json`).
+- Structural name collisions across catalogs fail the build; structurally
+  identical types dedupe silently.
+
+See [ADR-002](decisions/002-streamable-responses.md) for rationale and the
+terminal-error policy.
+
 ## Example Files
 
 Example configuration files are available in the `examples/openapi/` directory: