shelving 1.195.1 → 1.196.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.195.1",
+	"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 });
+    });
+}