shelving 1.196.3 → 1.198.0

package/api/index.d.ts

@@ -3,6 +3,7 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
+export * from "./provider/CachedAPIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/JSONAPIProvider.js";

package/api/index.js

@@ -3,6 +3,7 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
+export * from "./provider/CachedAPIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/JSONAPIProvider.js";

package/api/provider/CachedAPIProvider.d.ts

@@ -0,0 +1,20 @@
+import type { AnyCaller } from "../../util/function.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import type { APIProvider } from "./APIProvider.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * API provider wrapper that serves requests through an `APICache`.
+ * - Constructor accepts a `source` provider and an optional default `maxAge`.
+ * - On `call(...)`, triggers `cache.refresh(maxAge)` for the endpoint+payload before awaiting `cache.call(...)`.
+ * - `invalidate`, `invalidateAll`, `refresh`, and `refreshAll` pass through to the underlying cache and use `this.maxAge` as the default refresh timing.
+ */
+export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
+    readonly maxAge: number | undefined;
+    private readonly _cache;
+    constructor(source: APIProvider<P, R>, maxAge?: number);
+    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number | undefined, caller?: AnyCaller): Promise<RR>;
+    invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
+    invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
+    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+}

package/api/provider/CachedAPIProvider.js

@@ -0,0 +1,34 @@
+import { APICache } from "../cache/APICache.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * API provider wrapper that serves requests through an `APICache`.
+ * - Constructor accepts a `source` provider and an optional default `maxAge`.
+ * - On `call(...)`, triggers `cache.refresh(maxAge)` for the endpoint+payload before awaiting `cache.call(...)`.
+ * - `invalidate`, `invalidateAll`, `refresh`, and `refreshAll` pass through to the underlying cache and use `this.maxAge` as the default refresh timing.
+ */
+export class CachedAPIProvider extends ThroughAPIProvider {
+    maxAge;
+    _cache;
+    constructor(source, maxAge) {
+        super(source);
+        this.maxAge = maxAge;
+        this._cache = new APICache(source);
+    }
+    // @ts-expect-error TS2416: intentionally diverges from `APIProvider.call` — `RequestOptions` are not used by the cache, so the third arg is repurposed as `maxAge`.
+    call(endpoint, payload, maxAge = this.maxAge, caller = this.call) {
+        this._cache.refresh(endpoint, payload, maxAge);
+        return this._cache.call(endpoint, payload, maxAge, caller);
+    }
+    invalidate(endpoint, payload) {
+        this._cache.invalidate(endpoint, payload);
+    }
+    invalidateAll(endpoint) {
+        this._cache.invalidateAll(endpoint);
+    }
+    refresh(endpoint, payload) {
+        this._cache.refresh(endpoint, payload, this.maxAge);
+    }
+    refreshAll(endpoint) {
+        this._cache.refreshAll(endpoint, this.maxAge);
+    }
+}

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.198.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) {