@vyriy/request 0.2.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Vyriy Package Agent Guide
+
+This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+
+## Architecture
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package boundaries explicit and avoid project-specific coupling.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths.
+- Keep integrations replaceable and avoid hard coupling to a CMS or runtime host.
+- Prefer AWS serverless-compatible assumptions when infrastructure concerns appear.
+
+## File Shape
+
+- Prefer one exported runtime method, component, or helper per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use `.js` relative import and export specifiers in TypeScript source where package style requires it.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export should be re-exported from `index.ts`.
+- Add or update `index.test.ts` when the public export surface changes.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Do not hand-maintain source package `exports` maps unless the package has a real custom publishing need.
+
+## Tests
+
+- Tests use Jest and `@jest/globals`.
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing package behavior:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# @vyriy/<package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Keep `doc.mdx` as the Storybook/docs wrapper for the README when the package participates in docs.
+- For component packages, include Storybook coverage for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React 19+ components with TypeScript.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- Put each public component in its own file with a matching test.
+- Add Storybook stories when a component has visual states, variants, or interaction states.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, README, `doc.mdx`, and public re-exports together.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.

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,9 +1,10 @@
 {
   "name": "@vyriy/request",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared request utility for Vyriy projects",
   "type": "module",
   "main": "./index.js",
+  "agents": "./AGENTS.md",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -77,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>;