@techspokes/typescript-wsdl-client 0.27.0 → 0.28.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.
 
@@ -234,7 +234,7 @@ See [CLI Reference](docs/cli-reference.md) for all flags and examples.
 | [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` |
+| [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/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

@@ -30,7 +30,7 @@ Human-maintained reference documents for `@techspokes/typescript-wsdl-client`. T
 - [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
+- [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
 

package/docs/output-anatomy.md

@@ -75,7 +75,7 @@ CLI OpenAPI generation always validates the generated spec using `@apidevtools/s
 
 ### 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:
+Stream operations do not use the standard success envelope for `200` responses. NDJSON streams declare 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
 {
@@ -94,7 +94,29 @@ Stream operations do not use the standard success envelope for `200` responses.
 }
 ```
 
-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.
+JSON array streams default to `application/json` and declare the record schema as the array item schema while keeping the same extension:
+
+```json
+{
+  "200": {
+    "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" }
+        }
+      }
+    }
+  }
+}
+```
+
+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. JSON array streams use a normal array schema and keep the extension for downstream tooling. Error responses (400, 502, and the rest) still use the normal envelope.
 
 ## Gateway Output
 
@@ -117,11 +139,11 @@ Each route file in `routes/` follows the same pattern: validate the JSON request
 
 ### 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.
+Stream-configured operations generate a different route shape. The Fastify response serialization schema is omitted because the handler sends a `Readable` directly. NDJSON handlers set `reply.type("application/x-ndjson")` and return `reply.send(toNdjson(result.records))`; JSON array handlers set `reply.type("application/json")` and return `reply.send(toJsonArray(result.records))`. `runtime.ts` gains `toNdjson<T>(records: AsyncIterable<T>): Readable` and `toJsonArray<T>(records: AsyncIterable<T>): Readable` helpers. 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.
+When `--test-dir` is combined with `--stream-config`, the generated happy-path tests for stream operations assert on the configured content type. NDJSON tests parse each line as a separate JSON record, and JSON array tests parse the response body once as an array. Mock clients use async-generator overrides that yield records to drive those tests; see the [Testing Guide](testing.md) for the pattern.
 
 ### Plugin registration
 

package/docs/production.md

@@ -83,7 +83,7 @@ Log the time to first record, not just the time to response completion. First-re
 
 ### 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.
+Errors raised before the first record use the normal gateway error envelope because the JSON array helper prefetches the first record before emitting `[`. Errors raised mid-stream truncate the response. NDJSON consumers detect this as an incomplete HTTP response, and JSON array consumers must treat an incomplete or invalid JSON document as a failed stream. Document this behavior for downstream API consumers so they distinguish truncation from a legitimate empty stream.
 
 ## Known Limitations
 
@@ -105,7 +105,7 @@ Single-child sequences with maxOccurs>1 become array schemas. Sequences with mul
 
 ### 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.
+`ndjson` is the default stream format. `json-array` is supported for operations that need a single JSON document response; it streams records incrementally as a JSON array and does not buffer the full SOAP response.
 
 ### Stream Transport Bypasses node-soap
 

package/docs/releases/v0.28.0.md

@@ -0,0 +1,32 @@
+# TypeScript WSDL Client v0.28.0
+
+## JSON Array Streaming
+
+This release implements `format: "json-array"` for operations opted into streaming with `--stream-config`.
+
+## What This Improves
+
+Teams can now serve large SOAP response records as one streamed `application/json` array without buffering the full upstream response. NDJSON remains the default stream format, and JSON array operations keep the same generated client return shape: `StreamOperationResponse<RecordType>` with `records: AsyncIterable<RecordType>`.
+
+## Highlights
+
+- Adds `toJsonArray()` runtime streaming alongside the existing NDJSON helper.
+- Emits OpenAPI `application/json` array schemas for JSON array stream operations.
+- Generates Fastify routes that call `toJsonArray(result.records)` for `format: "json-array"`.
+- Generates route tests that parse JSON array stream responses as one array document.
+- Documents the terminal-error behavior for JSON array streams.
+
+## Upgrade Notes
+
+No special upgrade steps. Existing stream operations keep `ndjson` unless the stream config opts an operation into `format: "json-array"`.
+
+## Validation
+
+- CI passed.
+- NPM package contents were validated.
+- Documentation links and TypeScript fenced snippets were validated.
+- Agent skill artifact was validated and packaged.
+
+## Notes
+
+Release tag: `v0.28.0`.

package/docs/roadmap/README.md

@@ -1,6 +1,6 @@
 # Version 1.0 Roadmap Plan
 
-Detailed plan for moving `@techspokes/typescript-wsdl-client` from `0.26.x` to a stable `1.0.0` release.
+Detailed plan for moving `@techspokes/typescript-wsdl-client` from `0.28.x` to a stable `1.0.0` release.
 
 See the root [README.md](../../README.md) for project overview and the root [ROADMAP.md](../../ROADMAP.md) for the public roadmap summary.
 
@@ -37,7 +37,7 @@ Choice union mode is complete in `0.26.0`. The default `all-optional` mode remai
 
 ### Slice 4: JSON Array Streaming
 
-Implement streaming JSON array output after stream error behavior is researched. This is the next implementation slice after `0.26.0`, and the result must stream records incrementally without buffering the full SOAP response.
+JSON array streaming is complete in `0.28.0`. The default `ndjson` format remains unchanged, and `format: "json-array"` streams records incrementally without buffering the full SOAP response.
 
 ### Slice 5: WSDL Coverage Matrix
 

package/docs/roadmap/v1.0-contract-audit.md

@@ -36,7 +36,7 @@ This slice prevents later work from building on ambiguous behavior. It also give
 
 ### JSON Array Streaming
 
-`format: "json-array"` must stay in the 1.0 roadmap because 1.0 requires the format. The audit should identify every parser, client, OpenAPI, gateway, runtime, and docs surface that currently assumes NDJSON.
+`format: "json-array"` is implemented in `0.28.0`. The audit should keep every parser, client, OpenAPI, gateway, runtime, and docs surface aligned across both stream formats.
 
 ### Roadmap State
 

package/docs/roadmap/v1.0-json-array-streaming.md

@@ -1,8 +1,8 @@
 # Version 1.0 JSON Array Streaming
 
-Plan for implementing `format: "json-array"` streaming for SOAP operations that already use the stream configuration model.
+Status: implemented for `0.28.0`.
 
-This is the next planned feature slice after the `0.26.0` choice union mode release.
+This document records the implementation slice for `format: "json-array"` streaming for SOAP operations that already use the stream configuration model.
 
 See the root [README.md](../../README.md) for project overview and [Version 1.0 Roadmap Plan](README.md) for the complete 1.0 route.
 
@@ -12,9 +12,9 @@ See the root [README.md](../../README.md) for project overview and [Version 1.0
 
 ## Design Direction
 
-JSON array streaming should write an opening bracket, stream comma-separated JSON records, and write a closing bracket after the async iterable completes. The implementation must preserve backpressure by converting the async iterable into a Node `Readable` stream.
+JSON array streaming writes an opening bracket with the first record, streams comma-separated JSON records, and writes a closing bracket after the async iterable completes. The implementation preserves backpressure by converting the async iterable into a Node `Readable` stream.
 
-The key research question is error timing. If the route can observe an upstream error before sending the first byte, it should still return the normal error envelope. Once the JSON array response has started, a later error must truncate the response and clients must treat the JSON parse failure as a failed stream.
+The key researched constraint is error timing. The helper prefetches the first record before sending the first byte, so an upstream error before the first record still returns the normal error envelope. Once the JSON array response has started, a later error truncates the response and clients must treat the JSON parse failure as a failed stream.
 
 ## Scope
 
@@ -39,7 +39,7 @@ Research whether generated routes should prefetch the first record before callin
 
 ### Empty Stream Handling
 
-Confirm that an empty stream returns `[]` with `application/json`. The helper must emit a syntactically valid empty array without special route code where possible.
+An empty stream returns `[]` with `application/json`. The helper emits a syntactically valid empty array without special route code.
 
 ### Backpressure Handling
 
@@ -47,7 +47,7 @@ Confirm that the helper does not pull from the async iterable faster than the HT
 
 ### Terminal Error Handling
 
-Confirm how Fastify and Node surface stream errors after the JSON array has begun. Document the client-visible behavior in production docs and troubleshooting docs.
+Fastify surfaces stream errors after the JSON array has begun as a destroyed or reset response under inject and as a truncated response to real clients. Production docs and troubleshooting docs describe this as a failed stream.
 
 ## Implementation Units
 

package/docs/start-here.md

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

package/docs/supported-patterns.md

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

package/docs/testing.md

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

package/docs/troubleshooting.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.27.0",
+  "version": "0.28.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",

package/src/runtime/jsonArray.ts

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