@vyriy/request 0.2.1 → 0.3.0

package/README.md

@@ -22,23 +22,108 @@ yarn add @vyriy/request
 
 ## Usage
 
+Read JSON:
+
 ```ts
-import { request } from '@vyriy/request';
+import { request, requestStream } from '@vyriy/request';
 
 const profile = await request<{ id: string; name: string }>('/api/profile');
+```
+
+Read text with custom retry and timeout behavior:
 
+```ts
 const html = await request<string>('https://example.com', null, {
   retries: 1,
   timeout: 5000,
 });
 ```
 
+Send JSON with `POST`:
+
+```ts
+type CreatedProfile = {
+  id: string;
+};
+
+const created = await request<CreatedProfile>('/api/profile', {
+  method: 'POST',
+  headers: {
+    'content-type': 'application/json',
+  },
+  body: JSON.stringify({
+    name: 'Ada',
+  }),
+});
+```
+
+Send authenticated requests:
+
+```ts
+const projects = await request<Array<{ id: string; name: string }>>('/api/projects', {
+  headers: {
+    authorization: `Bearer ${token}`,
+    accept: 'application/json',
+  },
+});
+```
+
+Send form data:
+
+```ts
+const form = new FormData();
+form.append('title', 'Draft');
+form.append('file', file);
+
+await request('/api/upload', {
+  method: 'POST',
+  body: form,
+});
+```
+
+Use an external abort signal:
+
+```ts
+const controller = new AbortController();
+
+const pending = request('/api/search', {
+  signal: controller.signal,
+});
+
+controller.abort();
+
+await pending;
+```
+
+Consume streaming chunks:
+
+```ts
+const decoder = new TextDecoder();
+
+await requestStream('/api/events', null, {
+  onChunk: (chunk) => {
+    console.info(decoder.decode(chunk));
+  },
+});
+```
+
+Get the raw streaming response:
+
+```ts
+const response = await requestStream('/api/download');
+const body = response.body;
+```
+
 ## API
 
 - `request(input, init?, options?)` performs a `fetch` call and returns parsed JSON or text.
+- `requestStream(input, init?, options?)` performs a `fetch` call and returns the successful `Response`.
+- `requestStream(..., { onChunk })` consumes `response.body` and calls `onChunk` for each `Uint8Array` chunk in order.
 - `init` may be `null` when you want to skip request init and pass `options` as the third argument.
 - `options.timeout` sets the per-attempt timeout in milliseconds.
 - `options.retries` controls how many retry attempts are allowed after the initial request.
 - `options.retryDelay` sets the base delay in milliseconds between retry attempts.
 - `options.retryMethods` overrides which HTTP methods are allowed to retry.
 - `options.retryStatuses` overrides which HTTP status codes are considered retryable.
+
+For streaming requests, retries happen only before chunk consumption starts. This avoids delivering duplicate chunks to `onChunk`.

package/index.d.ts

@@ -1,2 +1,3 @@
 export * from './request.js';
+export * from './stream.js';
 export type * from './types.js';

package/index.js

@@ -1 +1,2 @@
 export * from './request.js';
+export * from './stream.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vyriy/request",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Shared request utility for Vyriy projects",
   "type": "module",
   "main": "./index.js",
@@ -78,6 +78,16 @@
       "import": "./retry.js",
       "default": "./retry.js"
     },
+    "./stream": {
+      "types": "./stream.d.ts",
+      "import": "./stream.js",
+      "default": "./stream.js"
+    },
+    "./stream.js": {
+      "types": "./stream.d.ts",
+      "import": "./stream.js",
+      "default": "./stream.js"
+    },
     "./timeout": {
       "types": "./timeout.d.ts",
       "import": "./timeout.js",

package/stream.d.ts

@@ -0,0 +1,2 @@
+import type { RequestStream } from './types.js';
+export declare const requestStream: RequestStream;

package/stream.js

@@ -0,0 +1,56 @@
+import { DEFAULT_RETRY_METHODS, DEFAULT_RETRY_STATUSES } from './constants.js';
+import { TimeoutError } from './error.js';
+import { assertSuccessfulResponse } from './response.js';
+import { isRetryableError, isRetryableMethod, wait } from './retry.js';
+import { withTimeoutSignal } from './timeout.js';
+export const requestStream = async (input, init = {}, options = {}) => {
+    const normalizedInit = init ?? {};
+    const { onChunk, retries = 2, retryDelay = 300, retryMethods = DEFAULT_RETRY_METHODS, retryStatuses = DEFAULT_RETRY_STATUSES, timeout = 25000, } = options;
+    const method = normalizedInit.method?.toUpperCase() ?? 'GET';
+    const run = async (attempt = 0) => {
+        const { cleanup, signal, timeoutSignal } = withTimeoutSignal(timeout, normalizedInit.signal);
+        let chunkConsumptionStarted = false;
+        try {
+            const response = await fetch(input, { ...normalizedInit, signal });
+            assertSuccessfulResponse(response);
+            if (!onChunk) {
+                cleanup();
+                return response;
+            }
+            const reader = response.body?.getReader();
+            if (!reader) {
+                cleanup();
+                return response;
+            }
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    chunkConsumptionStarted = true;
+                    await onChunk(value, { attempt, response });
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            cleanup();
+            return response;
+        }
+        catch (error) {
+            const canRetry = !chunkConsumptionStarted &&
+                attempt < retries &&
+                isRetryableMethod(method, retryMethods) &&
+                isRetryableError(error, normalizedInit.signal, retryStatuses);
+            if (!canRetry) {
+                cleanup();
+                throw timeoutSignal.aborted && timeoutSignal.reason instanceof TimeoutError ? timeoutSignal.reason : error;
+            }
+            await wait(retryDelay * (attempt + 1));
+            cleanup();
+            return run(attempt + 1);
+        }
+    };
+    return run();
+};

package/types.d.ts

@@ -5,4 +5,13 @@ export type Options = {
     retryMethods?: string[];
     retryStatuses?: number[];
 };
+export type StreamChunkHandlerParams = {
+    attempt: number;
+    response: Response;
+};
+export type StreamChunkHandler = (chunk: Uint8Array, params: StreamChunkHandlerParams) => Promise<void> | void;
+export type StreamOptions = Options & {
+    onChunk?: StreamChunkHandler;
+};
 export type Request = <R = Record<string, unknown>>(input: RequestInfo | URL, init?: RequestInit | null, options?: Options) => Promise<R>;
+export type RequestStream = (input: RequestInfo | URL, init?: RequestInit | null, options?: StreamOptions) => Promise<Response>;