@kizunajs/fetch 2.0.0-beta.20 → 2.0.0-beta.22

package/dist/index.cjs

@@ -10,10 +10,13 @@ let zod = require("zod");
 */
 const runtimeSource = String.raw`/**
  * What the client knows about one response: nothing for a body it reads as
- * JSON, the media type for one that streams.
+ * JSON, how to read one that is not, the media type for one that streams.
  */
 export type GeneratedResponse =
     | Record<string, never>
+    | {
+          read: 'bytes' | 'text';
+      }
     | {
           stream: true;
           contentType: string;
@@ -58,6 +61,7 @@ export interface ClientConfig {
     fetch?: typeof fetch;
     onRequest?: (request: OutgoingRequest) => void | Promise<void>;
     retry?: RetryOptions;
+    reconnect?: ReconnectOptions;
 }
 
 /**
@@ -79,6 +83,25 @@ export interface RetryOptions {
     maximumDelay?: number;
 }
 
+/**
+ * Reconnects an event stream on a GET, HEAD, OPTIONS, PUT or DELETE when its
+ * connection drops, sending the id of the last event as Last-Event-ID.
+ */
+export interface ReconnectOptions {
+    /**
+     * Reconnections in a row before the stream fails. An event received resets the count.
+     */
+    maximumAttempts?: number;
+    /**
+     * Milliseconds to wait before reconnecting, until the server sends a retry field.
+     */
+    reconnectionTime?: number;
+    /**
+     * Milliseconds the wait may grow to after reconnections in a row that fail.
+     */
+    maximumDelay?: number;
+}
+
 /**
  * One method on the client. Its '~route' names the method it sends and
  * whether its response streams, so a wrapper like @kizunajs/tanstack-query
@@ -187,17 +210,29 @@ const findLineEnd = (buffer: string, final: boolean): { index: number; length: n
 /**
  * Reads text/event-stream as the WHATWG HTML specification parses it.
  */
-async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent> {
+interface EventStreamState {
+    lastEventId: string;
+    reconnectionTime: number;
+}
+
+async function* readEvents(
+    body: ReadableStream<Uint8Array>,
+    state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: 3000,
+    }
+): AsyncGenerator<ServerSentEvent> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
     let first = true;
     let dataLines: string[] = [];
     let eventType = '';
-    let lastEventId = '';
+    let lastEventId = state.lastEventId;
     let retry: number | undefined;
 
     const dispatch = (): ServerSentEvent | undefined => {
+        state.lastEventId = lastEventId;
         if (dataLines.length === 0) {
             eventType = '';
             return undefined;
@@ -232,7 +267,10 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
                 if (!value.includes('\0')) lastEventId = value;
                 break;
             case 'retry':
-                if (/^\d+$/.test(value)) retry = Number(value);
+                if (/^\d+$/.test(value)) {
+                    retry = Number(value);
+                    state.reconnectionTime = Math.min(retry, 3_600_000);
+                }
                 break;
         }
         return undefined;
@@ -262,6 +300,57 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
     }
 }
 
+async function* reconnectingEvents(
+    first: Response,
+    reopen: (lastEventId: string) => Promise<Response>,
+    options: ReconnectOptions,
+    signal: AbortSignal | null | undefined
+): AsyncGenerator<ServerSentEvent> {
+    const maximumAttempts = options.maximumAttempts ?? 5;
+    const maximumDelay = options.maximumDelay ?? 30_000;
+    const state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: options.reconnectionTime ?? 3000,
+    };
+    let response: Response | undefined = first;
+    let attempts = 0;
+    let failure: unknown;
+    for (;;) {
+        if (response?.body) {
+            try {
+                for await (const message of readEvents(response.body, state)) {
+                    attempts = 0;
+                    failure = undefined;
+                    yield message;
+                }
+            } catch (error) {
+                failure = error;
+            }
+        }
+        if (signal?.aborted) throw signal.reason;
+        if (attempts >= maximumAttempts) {
+            if (failure !== undefined) throw failure;
+            return;
+        }
+        attempts += 1;
+        const ceiling = Math.min(maximumDelay, state.reconnectionTime * 2 ** (attempts - 1));
+        await wait(state.reconnectionTime + Math.random() * Math.max(0, ceiling - state.reconnectionTime), signal);
+        try {
+            response = await reopen(state.lastEventId);
+        } catch (error) {
+            if (signal?.aborted) throw error;
+            failure = error;
+            response = undefined;
+            continue;
+        }
+        if (response.status === 204) return;
+        const contentType = response.headers.get('content-type') ?? '';
+        if (response.status !== first.status || !contentType.toLowerCase().startsWith('text/event-stream')) {
+            throw new Error('Reconnecting to the event stream failed with status ' + response.status);
+        }
+    }
+}
+
 async function* readText(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -360,41 +449,52 @@ const buildMethod = (route: GeneratedRoute, config: ClientConfig) => {
     const call = async (args: CallArgs = {}) => {
         const query = args.query === undefined ? '' : buildSearchParams(args.query).toString();
         const url = config.baseUrl + buildPath(route.path, args.params) + (query.length > 0 ? '?' + query : '');
-        const headers = new Headers(config.baseHeaders);
-        for (const [name, value] of Object.entries(args.headers ?? {})) {
-            if (value !== undefined) headers.set(name, value);
-        }
-        const init: RequestInit = {
-            method: route.method,
-            headers,
-        };
-        if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
-        if (config.credentials !== undefined) init.credentials = config.credentials;
-        await config.onRequest?.({
-            url,
-            method: route.method,
-            headers,
-            route,
-        });
-
-        const response = await send(
-            url,
-            {
+        const prepare = async (lastEventId = ''): Promise<RequestInit> => {
+            const headers = new Headers(config.baseHeaders);
+            for (const [name, value] of Object.entries(args.headers ?? {})) {
+                if (value !== undefined) headers.set(name, value);
+            }
+            if (lastEventId !== '') headers.set('Last-Event-ID', lastEventId);
+            const init: RequestInit = {
+                method: route.method,
+                headers,
+            };
+            if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
+            if (config.credentials !== undefined) init.credentials = config.credentials;
+            await config.onRequest?.({
+                url,
+                method: route.method,
+                headers,
+                route,
+            });
+            return {
                 ...init,
                 ...args.fetchOptions,
-            },
-            route,
-            config
-        );
+            };
+        };
+
+        const response = await send(url, await prepare(), route, config);
         const responseHeaders: Record<string, string> = {};
         response.headers.forEach((value, name) => {
             responseHeaders[name] = value;
         });
         const declared = route.responses[response.status];
         if (declared !== undefined && 'stream' in declared && response.body !== null) {
+            const essence = (declared.contentType.split(';')[0] ?? '').trim().toLowerCase();
+            const reconnect = essence === 'text/event-stream' && IDEMPOTENT_METHODS.has(route.method) ? config.reconnect : undefined;
+            const reopen = async (lastEventId: string) => send(url, await prepare(lastEventId), route, config);
             return {
                 status: response.status,
-                body: readStream(response.body, declared.contentType),
+                body: reconnect
+                    ? reconnectingEvents(response, reopen, reconnect, args.fetchOptions?.signal)
+                    : readStream(response.body, declared.contentType),
+                headers: responseHeaders,
+            };
+        }
+        if (declared !== undefined && 'read' in declared) {
+            return {
+                status: response.status,
+                body: declared.read === 'bytes' ? new Uint8Array(await response.arrayBuffer()) : await response.text(),
                 headers: responseHeaders,
             };
         }
@@ -850,7 +950,7 @@ const emitRoute = (routeKey, key, route, collector, namespaceName) => {
 	const argsType = `{\n${indent(args.map((arg) => `${arg};`).join("\n"))}\n}`;
 	const tableEntries = [`method: '${route.method}'`, `path: '${route.path}'`];
 	if (route.contentType) tableEntries.push(`contentType: '${route.contentType}'`);
-	const responses = Object.entries(route.responses).map(([status, response]) => (0, kizunajs_generator.isStreamResponse)(response) ? `${status}: { stream: true, contentType: '${(0, kizunajs_generator.streamContentType)(response)}' }` : `${status}: {}`);
+	const responses = Object.entries(route.responses).map(([status, response]) => (0, kizunajs_generator.isStreamResponse)(response) ? `${status}: { stream: true, contentType: '${(0, kizunajs_generator.streamContentType)(response)}' }` : `${status}: ${readEntry(response)}`);
 	if (validationBody && !declaredBadRequest) responses.push("400: {}");
 	tableEntries.push(`responses: {\n${indent(responses.map((entry) => `${entry},`).join("\n"))}\n}`);
 	const streams = Object.values(route.responses).some((response) => (0, kizunajs_generator.isStreamResponse)(response));
@@ -861,6 +961,16 @@ const emitRoute = (routeKey, key, route, collector, namespaceName) => {
 		table: `${key}: {\n${indent(tableEntries.map((entry) => `${entry},`).join("\n"))}\n},`
 	};
 };
+/**
+* How the client reads a body that does not stream: as bytes for a binary schema, as text for any other media type than
+* JSON, as JSON otherwise.
+*/
+const readEntry = (response) => {
+	const schema = (0, kizunajs_generator.resolveResponseBody)(response);
+	if (schema && (0, kizunajs_generator.isBinarySchema)(schema)) return `{ read: 'bytes' }`;
+	const contentType = (0, kizunajs_generator.resolveResponseContentType)(response);
+	return contentType !== void 0 && !(0, kizunajs_generator.isJsonMediaType)(contentType) ? `{ read: 'text' }` : "{}";
+};
 const isRoute = (value) => !!value && typeof value === "object" && typeof value.method === "string";
 const emitTree = (routes, prefix, collector, namespaceName) => {
 	const signatures = [];

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { ValidationErrorSchema } from "kizunajs/schemas";
-import { defineClient, isBinarySchema, isFileSchema, isStreamResponse, isVoidSchema, listedRoutes, readDef, readDeprecation, readDiscriminatedUnion, readMetaBrand, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseHeaders, sanitizeIdentifier, streamContentType, streamMode, toPascalCase, unwrapOptionalWrappers } from "kizunajs/generator";
+import { defineClient, isBinarySchema, isFileSchema, isJsonMediaType, isStreamResponse, isVoidSchema, listedRoutes, readDef, readDeprecation, readDiscriminatedUnion, readMetaBrand, readMetaDescription, readMetaExamples, readMetaId, readObjectShape, resolveResponseBody, resolveResponseContentType, resolveResponseHeaders, sanitizeIdentifier, streamContentType, streamMode, toPascalCase, unwrapOptionalWrappers } from "kizunajs/generator";
 import { z } from "zod";
 //#region src/runtime.ts
 /**
@@ -9,10 +9,13 @@ import { z } from "zod";
 */
 const runtimeSource = String.raw`/**
  * What the client knows about one response: nothing for a body it reads as
- * JSON, the media type for one that streams.
+ * JSON, how to read one that is not, the media type for one that streams.
  */
 export type GeneratedResponse =
     | Record<string, never>
+    | {
+          read: 'bytes' | 'text';
+      }
     | {
           stream: true;
           contentType: string;
@@ -57,6 +60,7 @@ export interface ClientConfig {
     fetch?: typeof fetch;
     onRequest?: (request: OutgoingRequest) => void | Promise<void>;
     retry?: RetryOptions;
+    reconnect?: ReconnectOptions;
 }
 
 /**
@@ -78,6 +82,25 @@ export interface RetryOptions {
     maximumDelay?: number;
 }
 
+/**
+ * Reconnects an event stream on a GET, HEAD, OPTIONS, PUT or DELETE when its
+ * connection drops, sending the id of the last event as Last-Event-ID.
+ */
+export interface ReconnectOptions {
+    /**
+     * Reconnections in a row before the stream fails. An event received resets the count.
+     */
+    maximumAttempts?: number;
+    /**
+     * Milliseconds to wait before reconnecting, until the server sends a retry field.
+     */
+    reconnectionTime?: number;
+    /**
+     * Milliseconds the wait may grow to after reconnections in a row that fail.
+     */
+    maximumDelay?: number;
+}
+
 /**
  * One method on the client. Its '~route' names the method it sends and
  * whether its response streams, so a wrapper like @kizunajs/tanstack-query
@@ -186,17 +209,29 @@ const findLineEnd = (buffer: string, final: boolean): { index: number; length: n
 /**
  * Reads text/event-stream as the WHATWG HTML specification parses it.
  */
-async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<ServerSentEvent> {
+interface EventStreamState {
+    lastEventId: string;
+    reconnectionTime: number;
+}
+
+async function* readEvents(
+    body: ReadableStream<Uint8Array>,
+    state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: 3000,
+    }
+): AsyncGenerator<ServerSentEvent> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
     let first = true;
     let dataLines: string[] = [];
     let eventType = '';
-    let lastEventId = '';
+    let lastEventId = state.lastEventId;
     let retry: number | undefined;
 
     const dispatch = (): ServerSentEvent | undefined => {
+        state.lastEventId = lastEventId;
         if (dataLines.length === 0) {
             eventType = '';
             return undefined;
@@ -231,7 +266,10 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
                 if (!value.includes('\0')) lastEventId = value;
                 break;
             case 'retry':
-                if (/^\d+$/.test(value)) retry = Number(value);
+                if (/^\d+$/.test(value)) {
+                    retry = Number(value);
+                    state.reconnectionTime = Math.min(retry, 3_600_000);
+                }
                 break;
         }
         return undefined;
@@ -261,6 +299,57 @@ async function* readEvents(body: ReadableStream<Uint8Array>): AsyncGenerator<Ser
     }
 }
 
+async function* reconnectingEvents(
+    first: Response,
+    reopen: (lastEventId: string) => Promise<Response>,
+    options: ReconnectOptions,
+    signal: AbortSignal | null | undefined
+): AsyncGenerator<ServerSentEvent> {
+    const maximumAttempts = options.maximumAttempts ?? 5;
+    const maximumDelay = options.maximumDelay ?? 30_000;
+    const state: EventStreamState = {
+        lastEventId: '',
+        reconnectionTime: options.reconnectionTime ?? 3000,
+    };
+    let response: Response | undefined = first;
+    let attempts = 0;
+    let failure: unknown;
+    for (;;) {
+        if (response?.body) {
+            try {
+                for await (const message of readEvents(response.body, state)) {
+                    attempts = 0;
+                    failure = undefined;
+                    yield message;
+                }
+            } catch (error) {
+                failure = error;
+            }
+        }
+        if (signal?.aborted) throw signal.reason;
+        if (attempts >= maximumAttempts) {
+            if (failure !== undefined) throw failure;
+            return;
+        }
+        attempts += 1;
+        const ceiling = Math.min(maximumDelay, state.reconnectionTime * 2 ** (attempts - 1));
+        await wait(state.reconnectionTime + Math.random() * Math.max(0, ceiling - state.reconnectionTime), signal);
+        try {
+            response = await reopen(state.lastEventId);
+        } catch (error) {
+            if (signal?.aborted) throw error;
+            failure = error;
+            response = undefined;
+            continue;
+        }
+        if (response.status === 204) return;
+        const contentType = response.headers.get('content-type') ?? '';
+        if (response.status !== first.status || !contentType.toLowerCase().startsWith('text/event-stream')) {
+            throw new Error('Reconnecting to the event stream failed with status ' + response.status);
+        }
+    }
+}
+
 async function* readText(body: ReadableStream<Uint8Array>): AsyncGenerator<string> {
     const reader = body.getReader();
     const decoder = new TextDecoder();
@@ -359,41 +448,52 @@ const buildMethod = (route: GeneratedRoute, config: ClientConfig) => {
     const call = async (args: CallArgs = {}) => {
         const query = args.query === undefined ? '' : buildSearchParams(args.query).toString();
         const url = config.baseUrl + buildPath(route.path, args.params) + (query.length > 0 ? '?' + query : '');
-        const headers = new Headers(config.baseHeaders);
-        for (const [name, value] of Object.entries(args.headers ?? {})) {
-            if (value !== undefined) headers.set(name, value);
-        }
-        const init: RequestInit = {
-            method: route.method,
-            headers,
-        };
-        if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
-        if (config.credentials !== undefined) init.credentials = config.credentials;
-        await config.onRequest?.({
-            url,
-            method: route.method,
-            headers,
-            route,
-        });
-
-        const response = await send(
-            url,
-            {
+        const prepare = async (lastEventId = ''): Promise<RequestInit> => {
+            const headers = new Headers(config.baseHeaders);
+            for (const [name, value] of Object.entries(args.headers ?? {})) {
+                if (value !== undefined) headers.set(name, value);
+            }
+            if (lastEventId !== '') headers.set('Last-Event-ID', lastEventId);
+            const init: RequestInit = {
+                method: route.method,
+                headers,
+            };
+            if (args.body !== undefined) init.body = encodeBody(route, args.body, headers);
+            if (config.credentials !== undefined) init.credentials = config.credentials;
+            await config.onRequest?.({
+                url,
+                method: route.method,
+                headers,
+                route,
+            });
+            return {
                 ...init,
                 ...args.fetchOptions,
-            },
-            route,
-            config
-        );
+            };
+        };
+
+        const response = await send(url, await prepare(), route, config);
         const responseHeaders: Record<string, string> = {};
         response.headers.forEach((value, name) => {
             responseHeaders[name] = value;
         });
         const declared = route.responses[response.status];
         if (declared !== undefined && 'stream' in declared && response.body !== null) {
+            const essence = (declared.contentType.split(';')[0] ?? '').trim().toLowerCase();
+            const reconnect = essence === 'text/event-stream' && IDEMPOTENT_METHODS.has(route.method) ? config.reconnect : undefined;
+            const reopen = async (lastEventId: string) => send(url, await prepare(lastEventId), route, config);
             return {
                 status: response.status,
-                body: readStream(response.body, declared.contentType),
+                body: reconnect
+                    ? reconnectingEvents(response, reopen, reconnect, args.fetchOptions?.signal)
+                    : readStream(response.body, declared.contentType),
+                headers: responseHeaders,
+            };
+        }
+        if (declared !== undefined && 'read' in declared) {
+            return {
+                status: response.status,
+                body: declared.read === 'bytes' ? new Uint8Array(await response.arrayBuffer()) : await response.text(),
                 headers: responseHeaders,
             };
         }
@@ -849,7 +949,7 @@ const emitRoute = (routeKey, key, route, collector, namespaceName) => {
 	const argsType = `{\n${indent(args.map((arg) => `${arg};`).join("\n"))}\n}`;
 	const tableEntries = [`method: '${route.method}'`, `path: '${route.path}'`];
 	if (route.contentType) tableEntries.push(`contentType: '${route.contentType}'`);
-	const responses = Object.entries(route.responses).map(([status, response]) => isStreamResponse(response) ? `${status}: { stream: true, contentType: '${streamContentType(response)}' }` : `${status}: {}`);
+	const responses = Object.entries(route.responses).map(([status, response]) => isStreamResponse(response) ? `${status}: { stream: true, contentType: '${streamContentType(response)}' }` : `${status}: ${readEntry(response)}`);
 	if (validationBody && !declaredBadRequest) responses.push("400: {}");
 	tableEntries.push(`responses: {\n${indent(responses.map((entry) => `${entry},`).join("\n"))}\n}`);
 	const streams = Object.values(route.responses).some((response) => isStreamResponse(response));
@@ -860,6 +960,16 @@ const emitRoute = (routeKey, key, route, collector, namespaceName) => {
 		table: `${key}: {\n${indent(tableEntries.map((entry) => `${entry},`).join("\n"))}\n},`
 	};
 };
+/**
+* How the client reads a body that does not stream: as bytes for a binary schema, as text for any other media type than
+* JSON, as JSON otherwise.
+*/
+const readEntry = (response) => {
+	const schema = resolveResponseBody(response);
+	if (schema && isBinarySchema(schema)) return `{ read: 'bytes' }`;
+	const contentType = resolveResponseContentType(response);
+	return contentType !== void 0 && !isJsonMediaType(contentType) ? `{ read: 'text' }` : "{}";
+};
 const isRoute = (value) => !!value && typeof value === "object" && typeof value.method === "string";
 const emitTree = (routes, prefix, collector, namespaceName) => {
 	const signatures = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kizunajs/fetch",
-  "version": "2.0.0-beta.20",
+  "version": "2.0.0-beta.22",
   "description": "Fetch client generation for Kizuna.js APIs",
   "keywords": [
     "kizunajs",
@@ -56,12 +56,12 @@
     "access": "public"
   },
   "peerDependencies": {
-    "kizunajs": "2.0.0-beta.20",
+    "kizunajs": "2.0.0-beta.22",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "kizunajs": "2.0.0-beta.20",
-    "@kizunajs/express": "2.0.0-beta.20",
+    "kizunajs": "2.0.0-beta.22",
+    "@kizunajs/express": "2.0.0-beta.22",
     "@types/express": "^5.0.0",
     "express": "^5.0.0",
     "tsdown": "^0.21.0",