shelving 1.195.0 → 1.196.0

package/api/provider/DebugAPIProvider.d.ts

@@ -2,7 +2,9 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Provider that logs API operations to the console. */
+/** Provider that logs operations to the console. */
 export declare class DebugAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
-    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
+    getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    fetch(request: Request): Promise<Response>;
+    parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/DebugAPIProvider.js

@@ -1,37 +1,43 @@
 import { debugFullRequest, debugFullResponse } from "../../util/debug.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Provider that logs API operations to the console. */
+/** Provider that logs operations to the console. */
 export class DebugAPIProvider extends ThroughAPIProvider {
-    async call(endpoint, payload, options, caller = this.call) {
-        // Turn the payload into a request and debug it before sending.
-        let request;
+    getRequest(endpoint, payload, options, caller = this.getRequest) {
+        const url = this.url.toString();
+        const ep = endpoint.toString();
         try {
-            request = this.getRequest(endpoint, payload, options, caller);
+            const request = super.getRequest(endpoint, payload, options, caller);
+            console.debug("✔ REQUEST", url, ep, payload);
+            return request;
         }
         catch (reason) {
-            console.error("✘ FETCH", this.url.toString(), endpoint.toString(), payload, reason);
+            console.error("✘ REQUEST", url, ep, payload, reason);
             throw reason;
         }
-        const debuggedRequest = await debugFullRequest(request);
-        console.debug("… FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest);
-        // Fetch the response and debug if it throws.
-        let response;
+    }
+    async fetch(request) {
+        const url = this.url.toString();
         try {
-            response = await this.fetch(request);
+            console.error("→ FETCH", url, await debugFullRequest(request));
+            const response = await super.fetch(request);
+            console.error("← FETCH", url, await debugFullResponse(response));
+            return response;
         }
         catch (reason) {
-            console.error("✘ FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest, reason);
+            console.error("✘ FETCH", url, reason);
             throw reason;
         }
-        const debuggedResponse = await debugFullResponse(response);
-        // Convert the  result or any parsing error.
+    }
+    async parseResponse(endpoint, response, caller = this.parseResponse) {
+        const url = this.url.toString();
+        const ep = endpoint.toString();
         try {
-            const result = await this.parseResponse(endpoint, response, caller);
-            console.debug("✔ FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest, debuggedResponse, result);
+            const result = await super.parseResponse(endpoint, response, caller);
+            console.debug("✔ RESPONSE", url, ep, result);
             return result;
         }
         catch (reason) {
-            console.error("✘ FETCH", this.url.toString(), endpoint.toString(), payload, debuggedRequest, debuggedResponse, reason);
+            console.error("✘ RESPONSE", url, ep, reason);
             throw reason;
         }
     }

package/package.json

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

package/store/PayloadFetchStore.d.ts

@@ -8,6 +8,7 @@ export type PayloadFetchCallback<P, R> = (payload: P, signal: AbortSignal) => R
  * @param payload The initial payload for the store.
  * @param value The initial value for the store, or `NONE` if it does not have one yet.
  * @param callback An optional callback that, if set, will be called with the current payload when the `fetch()` method is invoked to fetch the next value.
+ * @param debounce Delay in milliseconds before the fetch is triggered after a payload change. `busy` becomes `true` immediately; the actual fetch waits for the debounce period to expire. If the payload changes again before the delay expires the previous fetch is cancelled and the timer resets.
  */
 export declare class PayloadFetchStore<P, R> extends FetchStore<R> {
     /**
@@ -15,6 +16,6 @@ export declare class PayloadFetchStore<P, R> extends FetchStore<R> {
      * - New payloads can be set using `this.payload.value`
      */
     readonly payload: Store<P>;
-    constructor(payload: P, value: R | typeof NONE, callback?: PayloadFetchCallback<P, R>);
+    constructor(payload: P, value: R | typeof NONE, callback?: PayloadFetchCallback<P, R>, debounce?: number);
     [Symbol.asyncDispose](): Promise<void>;
 }

package/store/PayloadFetchStore.js

@@ -1,3 +1,4 @@
+import { awaitAbort, getDelay } from "../util/async.js";
 import { awaitDispose } from "../util/dispose.js";
 import { FetchStore } from "./FetchStore.js";
 import { Store } from "./Store.js";
@@ -7,6 +8,7 @@ import { Store } from "./Store.js";
  * @param payload The initial payload for the store.
  * @param value The initial value for the store, or `NONE` if it does not have one yet.
  * @param callback An optional callback that, if set, will be called with the current payload when the `fetch()` method is invoked to fetch the next value.
+ * @param debounce Delay in milliseconds before the fetch is triggered after a payload change. `busy` becomes `true` immediately; the actual fetch waits for the debounce period to expire. If the payload changes again before the delay expires the previous fetch is cancelled and the timer resets.
  */
 export class PayloadFetchStore extends FetchStore {
     /**
@@ -15,9 +17,17 @@ export class PayloadFetchStore extends FetchStore {
      */
     payload;
     // Override to save initial payload and callback.
-    constructor(payload, value, callback) {
+    constructor(payload, value, callback, debounce = 0) {
         const payloadStore = new Store(payload);
-        super(value, callback && (signal => callback(payloadStore.value, signal)));
+        const fetch = callback &&
+            (debounce > 0
+                ? async (signal) => {
+                    const snap = payloadStore.value;
+                    await Promise.race([getDelay(debounce), awaitAbort(signal)]);
+                    return callback(snap, signal);
+                }
+                : (signal) => callback(payloadStore.value, signal));
+        super(value, fetch);
         this.payload = payloadStore;
         void _iterate(this);
     }

package/util/async.d.ts

@@ -62,3 +62,11 @@ export type Deferred<T = unknown> = {
 export declare function getDeferred<T = void>(): Deferred<T>;
 /** Get a promise that automatically resolves after a delay. */
 export declare function getDelay(ms: number): Promise<void>;
+/**
+ * Get a promise that rejects with the signal's reason when an `AbortSignal` fires.
+ * - Rejects immediately if the signal is already aborted.
+ * - Use with `Promise.race()` to cancel a concurrent operation when a signal fires.
+ *
+ * @example await Promise.race([getDelay(300), awaitAbort(signal)]);
+ */
+export declare function awaitAbort(signal: AbortSignal): Promise<never>;

package/util/async.js

@@ -110,3 +110,18 @@ export function getDeferred() {
 export function getDelay(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Get a promise that rejects with the signal's reason when an `AbortSignal` fires.
+ * - Rejects immediately if the signal is already aborted.
+ * - Use with `Promise.race()` to cancel a concurrent operation when a signal fires.
+ *
+ * @example await Promise.race([getDelay(300), awaitAbort(signal)]);
+ */
+export function awaitAbort(signal) {
+    return new Promise((_, reject) => {
+        if (signal.aborted)
+            reject(signal.reason);
+        else
+            signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+    });
+}

package/util/sequence.js

@@ -2,8 +2,12 @@ import { UnexpectedError } from "../error/UnexpectedError.js";
 import { getDeferred, getDelay } from "./async.js";
 import { ABORT } from "./constants.js";
 /** Turn a `Promise<R>` into an `IteratorAbortResult<R>` */
-async function _awaitAbort(value) {
-    return { done: ABORT, value: await value };
+function _awaitAbortResult(value) {
+    return value.then(_getAbortResult);
+}
+/** Turn a result `R` into an `IteratorAbortResult<R>` */
+function _getAbortResult(value) {
+    return { done: ABORT, value };
 }
 /** Call an iterator's `return()` method (if it exists) with an initial value, and return the `value` it returns. */
 async function _iteratorReturn(iterator, initial, caller) {
@@ -26,13 +30,12 @@ export function isSequence(value) {
 /** Infinite sequence that yields until a `SIGNAL` is received. */
 export async function* repeatUntil(source, ...signals) {
     const iterator = source[Symbol.asyncIterator]();
+    const aborts = signals.map(_awaitAbortResult);
     let n;
     while (true) {
         try {
-            const { done, value } = await Promise.race([
-                iterator.next(n),
-                ...signals.map(_awaitAbort),
-            ]);
+            const next = iterator.next(n);
+            const { done, value } = await (aborts.length ? Promise.race([next, ...aborts]) : next);
             if (done) {
                 // For aborts, tell the iterator we're no longer using it.
                 if (done === ABORT)
@@ -81,7 +84,7 @@ export async function* callSequence(sequence, callback) {
 export function runSequence(sequence, onNext, onError, onReturn) {
     const { promise, resolve } = getDeferred();
     void _runSequenceIterator(sequence[Symbol.asyncIterator](), promise, onNext, onError, onReturn);
-    return (value) => resolve({ done: ABORT, value });
+    return (value) => resolve(_getAbortResult(value));
 }
 async function _runSequenceIterator(iterator, stopped, onNext, onError, onReturn) {
     let n;