shelving 1.195.1 → 1.196.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.195.1",
+	"version": "1.196.1",
 	"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 | typeof NONE, value: R | typeof NONE, callback?: PayloadFetchCallback<P, R>, debounce?: number);
     [Symbol.asyncDispose](): Promise<void>;
 }

package/store/PayloadFetchStore.js

@@ -1,3 +1,4 @@
+import { awaitAbort, awaitRace, 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,16 @@ 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 &&
+            (async (signal) => {
+                if (debounce > 0)
+                    await awaitRace(getDelay(debounce), awaitAbort(signal));
+                const value = payloadStore.loading ? await awaitRace(payloadStore.next, awaitAbort(signal)) : payloadStore.value;
+                return callback(value, signal);
+            });
+        super(value, fetch);
         this.payload = payloadStore;
         void _iterate(this);
     }

package/util/async.d.ts

@@ -1,5 +1,5 @@
 import type { ImmutableArray } from "./array.js";
-import type { ErrorCallback, ValueCallback } from "./function.js";
+import { type ErrorCallback, type ValueCallback } from "./function.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export declare function isAsync<T>(value: PromiseLike<T> | T): value is PromiseLike<T>;
 /** Is a value a synchronous value. */
@@ -62,3 +62,20 @@ 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 `awaitRace()` to cancel a concurrent operation when a signal fires.
+ *
+ * @example await awaitRace(getDelay(300), awaitAbort(signal));
+ */
+export declare function awaitAbort(signal: AbortSignal): Promise<never>;
+/**
+ * Race promises like `Promise.race()` but silently swallow rejections from the losers.
+ * - Returns a promise that settles with the first input to settle, exactly like `Promise.race()`.
+ * - The losing inputs keep running (Promises cannot be cancelled), but their eventual rejection — if any — is silently absorbed instead of bubbling up as an unhandled rejection.
+ * - Built for cancellation/timeout patterns, where the loser's eventual fate is genuinely uninteresting once another arm has settled. Do not use when both arms might surface meaningful errors that the caller should see.
+ *
+ * @example await awaitRace(getDelay(300), awaitAbort(signal)); // delay or abort, no leaked ABORT rejection if delay wins
+ */
+export declare function awaitRace<T>(...promises: Promise<T>[]): Promise<T>;

package/util/async.js

@@ -1,5 +1,6 @@
 import { Errors } from "../error/Errors.js";
 import { RequiredError } from "../error/RequiredError.js";
+import { BLACKHOLE } from "./function.js";
 /** Is a value an asynchronous value implementing a `then()` function. */
 export function isAsync(value) {
     return typeof value === "object" && value !== null && typeof value.then === "function";
@@ -110,3 +111,33 @@ 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 `awaitRace()` to cancel a concurrent operation when a signal fires.
+ *
+ * @example await awaitRace(getDelay(300), awaitAbort(signal));
+ */
+export function awaitAbort(signal) {
+    const promise = new Promise((_, reject) => {
+        if (signal.aborted)
+            reject(signal.reason);
+        else
+            signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+    });
+    promise.catch(BLACKHOLE);
+    return promise;
+}
+/**
+ * Race promises like `Promise.race()` but silently swallow rejections from the losers.
+ * - Returns a promise that settles with the first input to settle, exactly like `Promise.race()`.
+ * - The losing inputs keep running (Promises cannot be cancelled), but their eventual rejection — if any — is silently absorbed instead of bubbling up as an unhandled rejection.
+ * - Built for cancellation/timeout patterns, where the loser's eventual fate is genuinely uninteresting once another arm has settled. Do not use when both arms might surface meaningful errors that the caller should see.
+ *
+ * @example await awaitRace(getDelay(300), awaitAbort(signal)); // delay or abort, no leaked ABORT rejection if delay wins
+ */
+export function awaitRace(...promises) {
+    for (const promise of promises)
+        promise.catch(BLACKHOLE);
+    return Promise.race(promises);
+}