shelving 1.196.3 → 1.197.0

package/api/provider/ClientAPIProvider.d.ts

@@ -21,7 +21,11 @@ export interface ClientAPIProviderOptions {
      * - Omits `signal` because it's not relevant at the provider level.
      */
     readonly options?: Omit<RequestOptions, "signal">;
-    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    /**
+     * Timeout in milliseconds before the request is aborted with `TimeoutError`.
+     * - Defaults to `20_000` (20 seconds) — chosen to fire before common platform wall-clock caps (Cloudflare Workers ~30s, Vercel/AWS API Gateway ~29s) so the abort propagates as a clean rejection instead of an opaque runtime termination.
+     * - Pass `0` to disable the timeout (e.g. for streaming or long-poll endpoints). Raise it for specifically slow endpoints.
+     */
     readonly timeout?: number | undefined;
 }
 /**
@@ -37,8 +41,8 @@ export declare class ClientAPIProvider<P = unknown, R = unknown> extends APIProv
     readonly url: URL;
     /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
     readonly options: RequestOptions;
-    /** Timeout in milliseconds, or `undefined` for no timeout. */
-    readonly timeout: number | undefined;
+    /** Timeout in milliseconds before the request is aborted, or `0` for no timeout. */
+    readonly timeout: number;
     constructor({ url, options, timeout }: ClientAPIProviderOptions);
     renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
     getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;

package/api/provider/ClientAPIProvider.js

@@ -19,9 +19,9 @@ export class ClientAPIProvider extends APIProvider {
     url;
     /** Default options used for HTTP requests created with `this.getRequest()` and `this.fetch()` */
     options;
-    /** Timeout in milliseconds, or `undefined` for no timeout. */
+    /** Timeout in milliseconds before the request is aborted, or `0` for no timeout. */
     timeout;
-    constructor({ url, options = {}, timeout }) {
+    constructor({ url, options = {}, timeout = 20_000 }) {
         super();
         this.url = requireBaseURL(url, ClientAPIProvider);
         this.options = options;

package/api/provider/DebugAPIProvider.js

@@ -18,9 +18,9 @@ export class DebugAPIProvider extends ThroughAPIProvider {
     async fetch(request) {
         const url = this.url.toString();
         try {
-            console.error("→ FETCH", url, await debugFullRequest(request));
+            console.debug("→ FETCH", url, await debugFullRequest(request));
             const response = await super.fetch(request);
-            console.error("← FETCH", url, await debugFullResponse(response));
+            console.debug("← FETCH", url, await debugFullResponse(response));
             return response;
         }
         catch (reason) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.196.3",
+	"version": "1.197.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",

package/store/PayloadFetchStore.d.ts

@@ -1,7 +1,7 @@
 import type { NONE } from "../util/constants.js";
 import { FetchStore } from "./FetchStore.js";
-import { Store } from "./Store.js";
-export type PayloadFetchCallback<P, R> = (payload: P, signal: AbortSignal) => R | PromiseLike<R>;
+import { type AsyncStoreInput, Store } from "./Store.js";
+export type PayloadFetchCallback<P, R> = (payload: P, signal: AbortSignal) => AsyncStoreInput<R>;
 /**
  * Store that fetches its values from a remote source by sending a payload to them.
  *

package/util/debug.js

@@ -77,8 +77,36 @@ async function _debugFullMessage(head, message) {
     const body = await _debugMessageBody(message);
     return `${head}${headers && `\n${headers}`}${body && `\n\n${body}`}`;
 }
+/** Maximum bytes read from a Request/Response body when debugging. Caps memory and prevents hangs on streaming bodies. */
+const _DEBUG_BODY_LIMIT = 64 * 1024;
 async function _debugMessageBody(message) {
-    return message.bodyUsed ? "[body used]" : await message.clone().text();
+    if (message.bodyUsed)
+        return "[body used]";
+    const body = message.clone().body;
+    if (!body)
+        return "";
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let bytes = 0;
+    let text = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                return text + decoder.decode();
+            bytes += value.byteLength;
+            if (bytes > _DEBUG_BODY_LIMIT) {
+                const keep = value.byteLength - (bytes - _DEBUG_BODY_LIMIT);
+                text += decoder.decode(value.subarray(0, keep), { stream: true });
+                await reader.cancel();
+                return `${text}${decoder.decode()}\n[truncated at ${_DEBUG_BODY_LIMIT} bytes]`;
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    catch (reason) {
+        return `${text}\n[read failed: ${reason?.message ?? reason}]`;
+    }
 }
 /** Debug a `Request` as a string. */
 export function debugRequest(request) {