@techspokes/typescript-wsdl-client 0.27.0 → 0.29.0

package/README.md

@@ -28,7 +28,7 @@ Most tools in this space stop at one layer: a SOAP runtime, type generation, or
 - Handles complex inheritance, `xs:attribute`, namespace collisions, nested XSD imports, and configurable `xs:choice` modeling
 - Generated `operations.ts` interface enables testing without importing `soap` or calling a live service
 - OpenAPI is a first-class output, not an afterthought; types, schemas, and descriptions stay aligned
-- Opt-in NDJSON streaming for large SOAP responses: client emits `AsyncIterable<RecordType>`, gateway flushes records incrementally, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`
+- Opt-in streaming for large SOAP responses: client emits `AsyncIterable<RecordType>`, gateway flushes NDJSON or JSON array records incrementally, OpenAPI advertises the record schema via `x-wsdl-tsc-stream`
 - Optional agent skill ZIP for consumer-project AI agents that need package-specific generation guidance
 - MIT licensed; generated code is yours with no attribution required
 
@@ -140,7 +140,7 @@ Platform API gateways solve governance, policy, and multi-language SDK generatio
 | REST gateway generation | no | no | no | yes |
 | Runnable app scaffolding | no | no | no | yes |
 | Mockable operations interface | no | no | no | yes |
-| Streaming large responses (NDJSON) | no | no | no | yes |
+| Streaming large responses (NDJSON or JSON array) | no | no | no | yes |
 
 Data as of April 2026.
 
@@ -233,8 +233,8 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [Core Concepts](docs/concepts.md) | Flattening, $value, primitives, determinism |
 | [Architecture](docs/architecture.md) | Internal pipeline for contributors |
 | [Agent Skill Artifact](docs/agent-skill.md) | Release ZIP for consumer-project AI agents |
-| [Version 1.0 Roadmap Plan](docs/roadmap/README.md) | Implementation slices and release gates for 1.0 |
-| [Streamable Responses (ADR-002)](docs/decisions/002-streamable-responses.md) | Opt-in streaming: client `AsyncIterable`, gateway NDJSON, `x-wsdl-tsc-stream` |
+| [Version 1.0 Roadmap Plan](docs/roadmap/README.md) | Conformance framework, implementation slices, and release gates for 1.0 |
+| [Streamable Responses (ADR-002)](docs/decisions/002-streamable-responses.md) | Opt-in streaming: client `AsyncIterable`, gateway NDJSON or JSON array, `x-wsdl-tsc-stream` |
 | [Version Migration](docs/migration.md) | Upgrading between package versions |
 
 ## Why This Exists

package/dist/app/generateApp.js

@@ -510,12 +510,12 @@ function generatePackageJson(appDir, force) {
         },
         dependencies: {
             fastify: "^5.8.5",
-            "fastify-plugin": "^5.1.0",
+            "fastify-plugin": "^6.0.0",
             saxes: "^6.0.0",
             soap: "^1.9.3",
         },
         devDependencies: {
-            "@types/node": "^25.9.1",
+            "@types/node": "^25.9.3",
             tsx: "^4.22.4",
             typescript: "^6.0.3",
         },

package/dist/gateway/generators.d.ts

@@ -42,8 +42,9 @@ export interface OperationMetadata {
     skipResponseSchema?: boolean;
     /**
      * Stream metadata populated from the OpenAPI `x-wsdl-tsc-stream` extension.
-     * When present, the route handler pipes `result.records` through the NDJSON
-     * helper instead of envelope-wrapping a single response object.
+     * When present, the route handler pipes `result.records` through the helper
+     * matching the configured stream format instead of envelope-wrapping a single
+     * response object.
      */
     stream?: {
         mediaType: string;

package/dist/gateway/generators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/gateway/generators.ts"],"names":[],"mappings":"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"}

package/dist/gateway/generators.js

@@ -230,8 +230,8 @@ export function emitOperationSchemas(doc, opsDir, versionSlug, serviceSlug, sche
                 path: p,
                 summary: normalizeDocCommentText(typeof operation.summary === "string" ? operation.summary : undefined),
                 description: normalizeDocCommentText(typeof operation.description === "string" ? operation.description : undefined),
-                // Stream ops always skip response schema because NDJSON is not a single
-                // JSON document and fast-json-stringify can't serialize it.
+                // Stream ops always skip response schema because the handler sends a
+                // Readable directly instead of a value for fast-json-stringify.
                 skipResponseSchema: skipResponseSchema || !!streamEntry,
                 ...(streamEntry ? { stream: streamEntry } : {}),
             });
@@ -646,10 +646,10 @@ export function createGatewayErrorHandler_${vSlug}_${sSlug}() {
 /**
  * Returns the streaming helpers block for runtime.ts.
  *
- * The emitted `toNdjson` mirrors the reference implementation in
- * src/runtime/ndjson.ts but is inlined here to avoid a cross-package import
- * from the generated gateway (which would require wsdl-tsc to be a runtime
- * dependency of the consumer's project).
+ * The emitted helpers mirror the reference implementations in src/runtime but
+ * are inlined here to avoid a cross-package import from the generated gateway
+ * (which would require wsdl-tsc to be a runtime dependency of the consumer's
+ * project).
  */
 function buildStreamRuntimeSection() {
     return `
@@ -676,6 +676,45 @@ async function* encodeNdjson<T>(records: AsyncIterable<T>): AsyncIterable<string
     yield JSON.stringify(record) + "\\n";
   }
 }
+
+/**
+ * Wrap an async iterable of records in a Node Readable stream that emits a JSON
+ * array without buffering the full record set. The first record is prefetched
+ * before the opening bracket is pushed, so before-first-record source errors
+ * can still be translated into the standard JSON error envelope.
+ */
+export function toJsonArray<T>(records: AsyncIterable<T>): Readable {
+  return Readable.from(encodeJsonArray(records), { objectMode: false, encoding: "utf-8" });
+}
+
+async function* encodeJsonArray<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();
+    }
+  }
+}
 `;
 }
 /**
@@ -872,8 +911,11 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
             ? `request.body as ${reqTypeName}`
             : "request.body";
         // Build the runtime import and return expression based on unwrap availability
+        const streamHelperName = op.stream?.format === "json-array"
+            ? "toJsonArray"
+            : "toNdjson";
         const runtimeImport = op.stream
-            ? `import { toNdjson } from "../runtime${suffix}";`
+            ? `import { ${streamHelperName} } from "../runtime${suffix}";`
             : hasUnwrap
                 ? `import { buildSuccessEnvelope, unwrapArrayWrappers } from "../runtime${suffix}";`
                 : `import { buildSuccessEnvelope } from "../runtime${suffix}";`;
@@ -883,7 +925,7 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
         // Note: op.path comes from OpenAPI and already includes any base path
         const schemaBinding = op.skipResponseSchema
             ? `\n// Response schema omitted: ${op.stream
-                ? "stream operations emit NDJSON, not a single JSON object"
+                ? "stream operations send a Readable directly"
                 : "$ref graph exceeds fast-json-stringify depth limit"}\nconst { response: _response, ...routeSchema } = schema as Record<string, unknown>;\n`
             : "";
         const schemaLine = op.skipResponseSchema
@@ -895,7 +937,7 @@ export function emitRouteFilesWithHandlers(outDir, routesDir, versionSlug, servi
       const client = fastify.${clientMeta.decoratorName};
       const result = await client.${clientMethod}(${bodyArg});
       reply.type(${JSON.stringify(op.stream.mediaType)});
-      return reply.send(toNdjson(result.records));
+      return reply.send(${streamHelperName}(result.records));
     },`
             : `    handler: async (request) => {
       const client = fastify.${clientMeta.decoratorName};

package/dist/openapi/generateOpenAPI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAyTD"}
+{"version":3,"file":"generateOpenAPI.d.ts","sourceRoot":"","sources":["../../src/openapi/generateOpenAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,EAAiB,KAAK,eAAe,EAAC,MAAM,+BAA+B,CAAC;AAKnF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CA4TD"}

package/dist/openapi/generateOpenAPI.js

@@ -191,12 +191,15 @@ export async function generateOpenAPI(opts) {
                 // Errors raised before the first byte still use the standard envelope.
                 const recordType = op.stream.recordTypeName;
                 const itemRef = { $ref: `#/components/schemas/${recordType}` };
+                const streamSchema = op.stream.format === "json-array"
+                    ? { type: "array", items: itemRef }
+                    : { type: "string" };
                 if (methodObj.responses?.["200"]) {
                     methodObj.responses["200"] = {
                         description: "Successful streamed SOAP operation response",
                         content: {
                             [op.stream.mediaType]: {
-                                schema: { type: "string" },
+                                schema: streamSchema,
                                 "x-wsdl-tsc-stream": {
                                     format: op.stream.format,
                                     itemSchema: itemRef,

package/dist/runtime/jsonArray.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare function toJsonArray<T>(records: AsyncIterable<T>): Readable;
+//# sourceMappingURL=jsonArray.d.ts.map

package/dist/runtime/jsonArray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonArray.d.ts","sourceRoot":"","sources":["../../src/runtime/jsonArray.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AAErC;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAElE"}

package/dist/runtime/jsonArray.js

@@ -0,0 +1,52 @@
+/**
+ * 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(records) {
+    return Readable.from(encode(records), { objectMode: false, encoding: "utf-8" });
+}
+async function* encode(records) {
+    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();
+        }
+    }
+}

package/dist/test/generators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/test/generators.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EAA0C,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAG5F,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AA6FrF;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAkBzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAgFR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,GACrB,MAAM,CAsCR;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAuER;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAiIR;AAED;;GAEG;AAEH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAuER;AAED;;GAEG;AAEH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,CAAC,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,MAAM,CAwDR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgFR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgDR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,OAAO,EAAE,eAAe,GACvB,MAAM,GAAG,IAAI,CAkEf"}
+{"version":3,"file":"generators.d.ts","sourceRoot":"","sources":["../../src/test/generators.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EAA0C,KAAK,eAAe,EAAC,MAAM,eAAe,CAAC;AAG5F,+EAA+E;AAC/E,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AA6FrF;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAkBzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAgFR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,UAAU,GACrB,MAAM,CAsCR;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CA8FR;AAED;;;;;;;GAOG;AAEH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAiIR;AAED;;GAEG;AAEH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,iBAAiB,GACvB,MAAM,CAuER;AAED;;GAEG;AAEH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,CAAC,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,MAAM,CAwDR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgFR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAChC,MAAM,CAgDR;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,EACjC,OAAO,EAAE,eAAe,GACvB,MAAM,GAAG,IAAI,CAkEf"}

package/dist/test/generators.js

@@ -256,10 +256,32 @@ export function emitRoutesTest(testDir, importsMode, operations, mocks) {
         const requestPayload = JSON.stringify(mockData?.request ?? {}, null, 4).replace(/\n/g, "\n    ");
         const hint = formatOperationHint(op.summary, op.description);
         const hintComment = hint ? `  // ${hint}\n` : "";
+        if (op.stream?.format === "json-array") {
+            // JSON array streams return one JSON document containing streamed records.
+            return `${hintComment}  it("${op.method.toUpperCase()} ${op.path} streams json-array records", async () => {
+    const app = await createTestApp();
+    try {
+      const res = await app.inject({
+        method: "${op.method.toUpperCase()}",
+        url: "${op.path}",
+        payload: ${requestPayload},
+      });
+      expect(res.statusCode).toBe(200);
+      expect(String(res.headers["content-type"] ?? "")).toContain(${JSON.stringify(op.stream.mediaType)});
+      const records = JSON.parse(res.body);
+      expect(Array.isArray(records)).toBe(true);
+      expect(records.length).toBeGreaterThan(0);
+      for (const record of records) {
+        expect(record).toBeDefined();
+      }
+    } finally {
+      await app.close();
+    }
+  });`;
+        }
         if (op.stream) {
-            // Stream routes return NDJSON lines, not a single JSON envelope. Assert
-            // on content-type and at least one parseable record per line.
-            return `${hintComment}  it("${op.method.toUpperCase()} ${op.path} streams ${op.stream.format} records", async () => {
+            // NDJSON streams return one parseable JSON document per line.
+            return `${hintComment}  it("${op.method.toUpperCase()} ${op.path} streams ndjson records", async () => {
     const app = await createTestApp();
     try {
       const res = await app.inject({

package/docs/README.md

@@ -29,8 +29,8 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [concepts.md](concepts.md): flattening, `$value`, primitives, determinism
 - [architecture.md](architecture.md): internal pipeline for contributors
 - [agent-skill.md](agent-skill.md): release ZIP for consumer-project AI agents
-- [roadmap/README.md](roadmap/README.md): implementation slices and release gates for 1.0
-- [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
+- [roadmap/README.md](roadmap/README.md): conformance framework, implementation slices, and release gates for 1.0
+- [decisions/002-streamable-responses.md](decisions/002-streamable-responses.md): opt-in streaming design (client `AsyncIterable`, gateway NDJSON or JSON array, `x-wsdl-tsc-stream` OpenAPI extension); shipped in 0.17.0 and extended in 0.28.0
 - [migration.md](migration.md): upgrading between package versions
 
 ## Conventions

package/docs/api-reference.md

@@ -357,6 +357,8 @@ interface OperationStreamMetadata {
 
 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.
 
+`format` selects the gateway wire format. `ndjson` emits one JSON document per line with the default `application/x-ndjson` media type, and `json-array` emits one JSON array document with the default `application/json` media type.
+
 ## Security Configuration Helpers
 
 Parse and build the shared security configuration used by OpenAPI generation and
@@ -408,7 +410,7 @@ const { compiled, openapiDoc } = await runGenerationPipeline({
 });
 
 const streamOp = compiled.operations.find((op) => op.stream);
-console.log(streamOp?.stream?.mediaType); // "application/x-ndjson"
+console.log(streamOp?.stream?.mediaType); // "application/x-ndjson" by default
 ```
 
 The generated client exports a `StreamOperationResponse<RecordType>` type; each stream-configured operation returns `Promise<StreamOperationResponse<RecordType>>` with `records: AsyncIterable<RecordType>`.

package/docs/architecture.md

@@ -73,7 +73,7 @@ tools.ts provides string helpers (pascal, kebab, QName resolution). cli.ts provi
 
 ### 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.
+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. jsonArray.ts wraps the same record iterable as one streamed JSON array document. 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/
 

package/docs/cli-reference.md

@@ -135,7 +135,7 @@ When `--init-app` is used and `--openapi-servers` is not provided, servers defau
 
 | 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` | (none) | Path to a JSON stream-configuration file (ADR-002). Marks selected operations as streaming: client emits `AsyncIterable<RecordType>`, gateway serves NDJSON or JSON array output, 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.
 

package/docs/concepts.md

@@ -232,7 +232,7 @@ 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.
+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, and the gateway writes raw NDJSON lines or one streamed JSON array 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
 
@@ -368,7 +368,7 @@ The catalog is the source of truth for stream metadata. Each opted-in operation
 
 ### 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).
+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 response; NDJSON consumers detect this as an incomplete HTTP response, and JSON array consumers see an incomplete or invalid JSON document. Both cases must be treated as failed streams. This behavior is documented for operators in the [Production Guide](production.md#terminal-error-policy).
 
 ## Companion Catalogs and Shape Resolution
 

package/docs/configuration.md

@@ -125,6 +125,7 @@ operations not listed in the file.
 
 - `recordType` and `recordPath` are required; `format` defaults to `ndjson` and
   `mediaType` to `application/x-ndjson`.
+- `format` accepts `ndjson` and `json-array`; JSON array streams default `mediaType` to `application/json` and emit one valid JSON array document.
 - `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)

package/docs/decisions/002-streamable-responses.md

@@ -101,7 +101,7 @@ Add a stream configuration file passed with `--stream-config`. The same option s
 
 `recordType` is the TypeScript and schema model to emit for each streamed record.
 
-`format` should support `ndjson` first. `json-array` can be added later for clients that require a single JSON array response.
+`format` supports `ndjson` and `json-array`. `ndjson` remains the default; `json-array` is available for clients that require a single JSON array response.
 
 ## CLI and Programmatic API
 
@@ -197,7 +197,7 @@ The converter must reuse catalog metadata for:
 - Text content and `$value`
 - Primitive mapping
 
-The converter should collect SOAP faults, response errors, and warnings when they appear before the first record. After streaming starts, terminal errors cannot be represented as a normal JSON error envelope for NDJSON. The runtime should either emit a final error record with a documented extension shape or abort the stream and log the classified error.
+The converter should collect SOAP faults, response errors, and warnings when they appear before the first record. After streaming starts, terminal errors cannot be represented as a normal JSON error envelope. The shipped behavior aborts the stream; NDJSON clients see an incomplete HTTP response, and JSON array clients see an incomplete or invalid JSON document.
 
 ## OpenAPI Output
 
@@ -222,25 +222,47 @@ Stream operations should not use the standard success envelope for `200` respons
 
 OpenAPI 3.1 cannot fully describe an NDJSON sequence as a standard JSON Schema document. The `x-wsdl-tsc-stream` extension makes the item schema explicit for generated gateways, documentation tools, and future SDK generators.
 
+For `format: "json-array"`, OpenAPI uses an array schema under the configured media type while keeping the same extension:
+
+```json
+{
+  "description": "Successful streamed SOAP operation response",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/UnitDescriptiveContentType"
+        }
+      },
+      "x-wsdl-tsc-stream": {
+        "format": "json-array",
+        "itemSchema": {
+          "$ref": "#/components/schemas/UnitDescriptiveContentType"
+        }
+      }
+    }
+  }
+}
+```
+
 ## Gateway Output
 
 Generated stream routes should call the stream operation and send a Node stream through Fastify.
 
 ```typescript
-import { Readable } from "node:stream";
-
 handler: async (request, reply) => {
   const client = fastify.escapiaContentClient;
   const result = await client.UnitDescriptiveInfoStream(request.body);
 
   reply.type("application/x-ndjson");
-  return reply.send(Readable.from(toNdjson(result.records)));
+  return reply.send(toNdjson(result.records));
 }
 ```
 
 The generated operation schema should keep request validation but omit the Fastify response serialization schema for streamed `200` responses. Fastify cannot serialize an unbounded stream with a normal JSON response schema.
 
-The gateway runtime should add `toNdjson()` and, later, `toJsonArrayStream()` helpers. These helpers should be deterministic, backpressure-aware, and safe for large payloads.
+The gateway runtime adds `toNdjson()` and `toJsonArray()` helpers. These helpers are deterministic, backpressure-aware, and safe for large payloads.
 
 ## Test Strategy
 
@@ -250,7 +272,7 @@ Add converter tests that split XML chunks across element boundaries to prove the
 
 Add a local Escapia-like WSDL fixture with `xs:any` output wrappers and a companion WSDL fixture with the concrete record types.
 
-Add an integration test with a fake SOAP HTTP server that writes one record, waits, writes another record, and then closes the envelope. The test should assert that the gateway emits the first NDJSON line before the upstream response completes.
+Add an integration test with a fake SOAP HTTP server that writes one record, waits, writes another record, and then closes the envelope. The test should assert that the gateway emits the first NDJSON line or JSON array record before the upstream response completes.
 
 Add snapshot tests for generated `client.ts`, `operations.ts`, OpenAPI output, gateway route files, and gateway runtime helpers.
 
@@ -273,7 +295,7 @@ Run `npm run smoke:pipeline` after implementation to verify ordinary buffered ge
 
 - Existing generated output is unchanged when no stream config is provided.
 - A stream-configured Escapia content WSDL generates typed stream client methods.
-- The generated gateway emits `application/x-ndjson` records incrementally.
+- The generated gateway emits configured stream records incrementally.
 - The generated OpenAPI document identifies stream operations and record schemas.
 - The converter maps XML attributes, arrays, text values, and nillable values consistently with buffered responses.
 - The chunked integration test proves the first record is sent before the full SOAP response is available.
@@ -286,7 +308,7 @@ The generator gains a second response execution model. This increases complexity
 
 The catalog becomes more important as the shared source of truth because OpenAPI alone cannot carry enough stream conversion metadata.
 
-NDJSON becomes the recommended stream format because it is simple, broadly consumable, and does not require buffering a complete JSON array before sending data.
+NDJSON remains the default stream format because it is simple and broadly consumable. JSON array streaming is available for clients that require one JSON document and still streams without buffering the full response.
 
 Companion catalogs are required for vendors that split stream wrappers and concrete record shapes across separate WSDLs.
 
@@ -298,7 +320,7 @@ Captured after the 0.17.0 ship for future maintainers:
 - `GenerateOpenAPIOptions` and `GenerateGatewayOptions` in the programmatic API do not carry stream-config fields for the same reason. `compileWsdlToProject` and `runGenerationPipeline` (PipelineOptions) do.
 - The client stream transport is emitted from two templates (`clientStreamMethods.tpl.txt`, `operationsStreamHelper.tpl.txt`). They embed the `StreamOperationResponse<T>` type and a `callStream()` method that POSTs a hand-built SOAP envelope via global `fetch`, bypassing `node-soap` as required by the phase-0 finding.
 - `saxes ^6.0.0` was promoted from devDependency to runtime dependency on the package, and added as a pinned dependency in the generated app scaffold so stream-enabled consumers install it automatically.
-- The `json-array` format is reserved in the config parser but not yet implemented by the emitters. Entries using `format: "json-array"` parse successfully and can be used to forward-declare intent; they do not currently generate routes or client methods.
+- The `json-array` format is implemented in `0.28.0`. The helper prefetches the first record before emitting `[`, which preserves normal error envelopes for failures before the first record and documents truncation or invalid JSON for failures after streaming starts.
 
 ## References
 

package/docs/gateway-guide.md

@@ -183,10 +183,7 @@ export async function registerRoute_v1_weather_getcityforecastbyzip(fastify: Fas
 
 ### Streaming Handlers
 
-Operations opted in via `--stream-config` emit an NDJSON response pipe
-instead of the standard envelope. The generated handler streams records as
-they arrive, and the Fastify response is flushed line-by-line with
-backpressure (ADR-002).
+Operations opted in via `--stream-config` emit a stream response instead of the standard envelope. The generated handler streams records as they arrive, and the Fastify response is flushed with backpressure. The default format is NDJSON; `format: "json-array"` emits one JSON array document.
 
 ```typescript
 import type { FastifyInstance } from "fastify";
@@ -194,7 +191,7 @@ import type { GetWeatherInformation } from "../../client/types.js";
 import schema from "../schemas/operations/getweatherinformation.json" with { type: "json" };
 import { toNdjson } from "../runtime.js";
 
-// Response schema omitted: stream operations emit NDJSON, not a single JSON object
+// Response schema omitted: stream operations send a Readable directly
 const { response: _response, ...routeSchema } = schema as Record<string, unknown>;
 
 export async function registerRoute_v1_weather_getweatherinformation(fastify: FastifyInstance) {
@@ -212,11 +209,9 @@ export async function registerRoute_v1_weather_getweatherinformation(fastify: Fa
 }
 ```
 
-The client method returns `StreamOperationResponse<RecordType>` with a
-`records: AsyncIterable<RecordType>`. Errors raised before the first record
-use the normal error envelope; errors raised mid-stream trip the chunked
-response's truncation. Consumers detect these via the absence of a clean
-terminating zero-chunk.
+For `format: "json-array"`, the same handler imports `toJsonArray`, sets `reply.type("application/json")`, and sends `reply.send(toJsonArray(result.records))`.
+
+The client method returns `StreamOperationResponse<RecordType>` with a `records: AsyncIterable<RecordType>`. Errors raised before the first record use the normal error envelope. Errors raised mid-stream truncate the response; NDJSON clients see an incomplete HTTP response, and JSON array clients see an incomplete or invalid JSON document.
 
 ## Error Handling
 

package/docs/generated-code.md

@@ -176,7 +176,7 @@ Key features of the generated handlers:
 - Envelope wrapping: `buildSuccessEnvelope()` wraps the raw SOAP response in the standard `{ status, message, data, error }` envelope
 - Route file header comments include propagated operation summary and description when present
 
-Stream-configured operations generate a different handler shape: the response serialization schema is omitted, `reply.type("application/x-ndjson")` is set, and `reply.send(toNdjson(result.records))` streams records with backpressure. See the [Gateway Guide Streaming Handlers section](gateway-guide.md#streaming-handlers) for the full example and terminal-error policy.
+Stream-configured operations generate a different handler shape: the response serialization schema is omitted and the handler streams `result.records` through the helper for the configured format. NDJSON handlers use `reply.type("application/x-ndjson")` with `toNdjson(result.records)`, and JSON array handlers use `reply.type("application/json")` with `toJsonArray(result.records)`. See the [Gateway Guide Streaming Handlers section](gateway-guide.md#streaming-handlers) for the full example and terminal-error policy.
 
 See [Gateway Guide](gateway-guide.md) for the full architecture and [CLI Reference](cli-reference.md) for generation flags.
 

package/docs/migration-playbook.md

@@ -89,7 +89,7 @@ npx wsdl-tsc pipeline \
   --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.
+The opted-in operations now return `StreamOperationResponse<RecordType>` on the client, serve `application/x-ndjson` by default on the gateway, and advertise the record schema in OpenAPI via `x-wsdl-tsc-stream`. Set `format: "json-array"` for `application/json` array streaming. 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
 

package/docs/migration.md

@@ -35,7 +35,7 @@ This upgrade adds opt-in streamable SOAP responses. No breaking changes; generat
 
 ### 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.
+The CLI gains a `--stream-config <file>` flag on `compile`, `client`, and `pipeline`. Operations listed in that file emit a new client method signature returning `StreamOperationResponse<RecordType>` with `records: AsyncIterable<RecordType>`, an OpenAPI 200 response typed as `application/x-ndjson` by default with an `x-wsdl-tsc-stream` extension, and a Fastify route that streams records with backpressure. Set `format: "json-array"` for `application/json` array streaming. The compiler now retains `xs:any` wildcard particles on compiled types (previously dropped silently), enabling honest stream-candidate detection and companion-catalog shape resolution. `saxes ^6.0.0` is now a runtime dependency of the package and is pinned automatically into the generated app scaffold.
 
 ### Steps to Upgrade to 0.17.x