shelving 1.194.0 → 1.195.1

package/api/cache/APICache.d.ts

@@ -1,3 +1,4 @@
+import type { AnyCaller } from "../../util/function.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
 import { EndpointCache } from "./EndpointCache.js";
@@ -12,13 +13,20 @@ export declare class APICache<P, R> implements AsyncDisposable {
     private _get;
     /** Get (or create) the `EndpointCache` for the given endpoint. */
     get<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): EndpointCache<PP, RR>;
+    /**
+     * Fetch (or return a cached result) for the given endpoint and payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number, caller?: AnyCaller): Promise<RR>;
     /** Invalidate a specific store for an endpoint. */
     invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
     /** Invalidate all stores for an endpoint. */
     invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     /** Trigger a refetch on a specific store for an endpoint. */
-    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
+    refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number): void;
     /** Trigger a refetch on all stores for an endpoint. */
-    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+    refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, maxAge?: number): void;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/cache/APICache.js

@@ -17,6 +17,15 @@ export class APICache {
     get(endpoint) {
         return this._get(endpoint) || setMapItem(this._endpoints, endpoint, new EndpointCache(endpoint, this.provider));
     }
+    /**
+     * Fetch (or return a cached result) for the given endpoint and payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    async call(endpoint, payload, maxAge, caller = this.call) {
+        return this.get(endpoint).call(payload, maxAge, caller);
+    }
     /** Invalidate a specific store for an endpoint. */
     invalidate(endpoint, payload) {
         this._get(endpoint)?.invalidate(payload);
@@ -26,12 +35,12 @@ export class APICache {
         this._get(endpoint)?.invalidateAll();
     }
     /** Trigger a refetch on a specific store for an endpoint. */
-    refresh(endpoint, payload) {
-        this._get(endpoint)?.refresh(payload);
+    refresh(endpoint, payload, maxAge) {
+        this._get(endpoint)?.refresh(payload, maxAge);
     }
     /** Trigger a refetch on all stores for an endpoint. */
-    refreshAll(endpoint) {
-        this._get(endpoint)?.refreshAll();
+    refreshAll(endpoint, maxAge) {
+        this._get(endpoint)?.refreshAll(maxAge);
     }
     // Implement `AsyncDisposable`
     [Symbol.asyncDispose]() {

package/api/cache/EndpointCache.d.ts

@@ -13,13 +13,20 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
     constructor(endpoint: Endpoint<P, R>, provider: APIProvider<P, R>);
     /** Get (or create) the `EndpointStore` for the given payload. */
     get(payload: P, caller?: AnyCaller): EndpointStore<P, R>;
+    /**
+     * Fetch (or return a cached result) for the given payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    call(payload: P, maxAge?: number, caller?: AnyCaller): Promise<R>;
     /** Invalidate a specific store. */
     invalidate(payload: P, caller?: AnyCaller): void;
     /** Invalidate all stores. */
     invalidateAll(): void;
     /** Trigger a refetch on a specific store. */
-    refresh(payload: P, caller?: AnyCaller): Promise<void>;
+    refresh(payload: P, maxAge?: number, caller?: AnyCaller): Promise<void>;
     /** Trigger a refetch on all stores. */
-    refreshAll(): Promise<void>;
+    refreshAll(maxAge?: number): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/cache/EndpointCache.js

@@ -19,6 +19,17 @@ export class EndpointCache {
         const url = this.provider.renderURL(this.endpoint, payload, caller).href;
         return this._endpoints.get(url) || setMapItem(this._endpoints, url, new EndpointStore(this.endpoint, payload, this.provider));
     }
+    /**
+     * Fetch (or return a cached result) for the given payload.
+     * - Returns the cached value immediately if one exists.
+     * - Waits for the in-flight fetch if the store is loading.
+     * - Throws if the fetch fails, matching `APIProvider.call` behaviour.
+     */
+    async call(payload, maxAge, caller = this.call) {
+        const store = this.get(payload, caller);
+        await store.refresh(maxAge);
+        return store.value;
+    }
     /** Invalidate a specific store. */
     invalidate(payload, caller = this.invalidate) {
         this.get(payload, caller)?.invalidate();
@@ -29,12 +40,12 @@ export class EndpointCache {
             store.invalidate();
     }
     /** Trigger a refetch on a specific store. */
-    async refresh(payload, caller = this.invalidate) {
-        await this.get(payload, caller)?.refresh();
+    async refresh(payload, maxAge, caller = this.invalidate) {
+        await this.get(payload, caller)?.refresh(maxAge);
     }
     /** Trigger a refetch on all stores. */
-    async refreshAll() {
-        await awaitValues(...this._endpoints.values().map(store => store.refresh()));
+    async refreshAll(maxAge) {
+        await awaitValues(...this._endpoints.values().map(store => store.refresh(maxAge)));
     }
     // Implement `AsyncDisposable`
     [Symbol.asyncDispose]() {

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/db/cache/CollectionCache.d.ts

@@ -23,15 +23,15 @@ export declare class CollectionCache<I extends Identifier, T extends Data> imple
     /** Get (or create) the `QueryStore` for the given query. */
     getQuery(query: Query<Item<I, T>>): QueryStore<I, T>;
     /** Refresh a specific item store. */
-    refreshItem(id: I): Promise<void>;
+    refreshItem(id: I, maxAge?: number): Promise<void>;
     /** Refresh every cached item store. */
-    refreshItems(): Promise<void>;
+    refreshItems(maxAge?: number): Promise<void>;
     /** Refresh a specific query store. */
-    refreshQuery(query: Query<Item<I, T>>): Promise<void>;
+    refreshQuery(query: Query<Item<I, T>>, maxAge?: number): Promise<void>;
     /** Refresh every cached query store. */
-    refreshQueries(): Promise<void>;
+    refreshQueries(maxAge?: number): Promise<void>;
     /** Refresh every cached store (items and queries). */
-    refreshAll(): Promise<void>;
+    refreshAll(maxAge?: number): Promise<void>;
     private _queryKey;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/cache/CollectionCache.js

@@ -29,24 +29,24 @@ export class CollectionCache {
         return this._queries.get(key) || setMapItem(this._queries, key, new QueryStore(this.collection, query, this.provider, this.memory));
     }
     /** Refresh a specific item store. */
-    async refreshItem(id) {
-        await this._items.get(id)?.refresh();
+    async refreshItem(id, maxAge) {
+        await this._items.get(id)?.refresh(maxAge);
     }
     /** Refresh every cached item store. */
-    async refreshItems() {
-        await awaitValues(...this._items.values().map(store => store.refresh()));
+    async refreshItems(maxAge) {
+        await awaitValues(...this._items.values().map(store => store.refresh(maxAge)));
     }
     /** Refresh a specific query store. */
-    async refreshQuery(query) {
-        await this._queries.get(this._queryKey(query))?.refresh();
+    async refreshQuery(query, maxAge) {
+        await this._queries.get(this._queryKey(query))?.refresh(maxAge);
     }
     /** Refresh every cached query store. */
-    async refreshQueries() {
-        await awaitValues(...this._queries.values().map(store => store.refresh()));
+    async refreshQueries(maxAge) {
+        await awaitValues(...this._queries.values().map(store => store.refresh(maxAge)));
     }
     /** Refresh every cached store (items and queries). */
-    async refreshAll() {
-        await awaitValues(this.refreshItems(), this.refreshQueries());
+    async refreshAll(maxAge) {
+        await awaitValues(this.refreshItems(maxAge), this.refreshQueries(maxAge));
     }
     _queryKey(query) {
         return JSON.stringify(query);

package/db/cache/DBCache.d.ts

@@ -25,14 +25,14 @@ export declare class DBCache<I extends Identifier = Identifier, T extends Data =
     /** Get (or create) a `QueryStore` for a collection/query in one hop. */
     getQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): QueryStore<II, TT>;
     /** Refresh a specific item store for a collection. */
-    refreshItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<void>;
+    refreshItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II, maxAge?: number): Promise<void>;
     /** Refresh every cached item store for a collection. */
-    refreshItems<II extends I, TT extends T>(collection: Collection<string, II, TT>): Promise<void>;
+    refreshItems<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
     /** Refresh a specific query store for a collection. */
-    refreshQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    refreshQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, maxAge?: number): Promise<void>;
     /** Refresh every cached query store for a collection. */
-    refreshQueries<II extends I, TT extends T>(collection: Collection<string, II, TT>): Promise<void>;
+    refreshQueries<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
     /** Refresh every cached store (items and queries) for a collection. */
-    refreshAll<II extends I, TT extends T>(collection: Collection<string, II, TT>): Promise<void>;
+    refreshAll<II extends I, TT extends T>(collection: Collection<string, II, TT>, maxAge?: number): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/db/cache/DBCache.js

@@ -32,24 +32,24 @@ export class DBCache {
         return this.get(collection).getQuery(query);
     }
     /** Refresh a specific item store for a collection. */
-    async refreshItem(collection, id) {
-        await this._get(collection)?.refreshItem(id);
+    async refreshItem(collection, id, maxAge) {
+        await this._get(collection)?.refreshItem(id, maxAge);
     }
     /** Refresh every cached item store for a collection. */
-    async refreshItems(collection) {
-        await this._get(collection)?.refreshItems();
+    async refreshItems(collection, maxAge) {
+        await this._get(collection)?.refreshItems(maxAge);
     }
     /** Refresh a specific query store for a collection. */
-    async refreshQuery(collection, query) {
-        await this._get(collection)?.refreshQuery(query);
+    async refreshQuery(collection, query, maxAge) {
+        await this._get(collection)?.refreshQuery(query, maxAge);
     }
     /** Refresh every cached query store for a collection. */
-    async refreshQueries(collection) {
-        await this._get(collection)?.refreshQueries();
+    async refreshQueries(collection, maxAge) {
+        await this._get(collection)?.refreshQueries(maxAge);
     }
     /** Refresh every cached store (items and queries) for a collection. */
-    async refreshAll(collection) {
-        await this._get(collection)?.refreshAll();
+    async refreshAll(collection, maxAge) {
+        await this._get(collection)?.refreshAll(maxAge);
     }
     // Implement `AsyncDisposable`
     async [Symbol.asyncDispose]() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.194.0",
+	"version": "1.195.1",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",
@@ -9,12 +9,12 @@
 	"main": "./index.js",
 	"module": "./index.js",
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.13",
+		"@biomejs/biome": "^2.4.14",
 		"@google-cloud/firestore": "^8.5.0",
 		"@types/bun": "^1.3.13",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
-		"@typescript/native-preview": "^7.0.0-dev.20260421.2",
+		"@typescript/native-preview": "^7.0.0-dev.20260502.1",
 		"firebase": "^12.12.1",
 		"react": "^19.2.5",
 		"react-dom": "^19.2.5"

package/store/FetchStore.d.ts

@@ -14,6 +14,7 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
     get loading(): boolean;
     write(input: StoreInput<TT>): void;
     read(): import("./Store.js").StoreInternal<T>;
+    get age(): number;
     constructor(value: T | typeof NONE, callback?: FetchCallback<TT>);
     /**
      * Fetch the result for this store now.
@@ -21,7 +22,7 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
      */
-    refresh(): Promise<boolean> | boolean;
+    refresh(maxAge?: number): Promise<boolean> | boolean;
     private _pendingRefresh;
     /**
      * Current `AbortSignal` for this store's in-flight fetch.
@@ -36,13 +37,13 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      */
     protected _fetch(signal: AbortSignal): TT | PromiseLike<TT>;
     private _callback;
+    /** Whether this store is has currently been invalidated and needs a refresh. */
+    get invalidated(): boolean;
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
      * - Triggers `abort()` so any current awaits are cancelled.
      */
     invalidate(): void;
     private _invalidation;
-    /** Re-fetch now if the current value is older than `maxAge` milliseconds or has been invalidated. */
-    refreshStale(maxAge: number): Promise<boolean> | boolean;
     abort(): void;
 }

package/store/FetchStore.js

@@ -15,7 +15,7 @@ export class FetchStore extends BusyStore {
     // We optimistically refresh so the value is available the next time the user wants it.
     get loading() {
         const loading = super.loading;
-        if (this._invalidation || loading)
+        if (this.invalidated || loading)
             void this.refresh();
         return loading;
     }
@@ -33,6 +33,10 @@ export class FetchStore extends BusyStore {
         this.loading; // Ping loading to possibly trigger the intiial fetch.
         return super.read();
     }
+    // Override to consider invalid to be really old.
+    get age() {
+        return this.invalidated ? Infinity : super.age;
+    }
     // Override to create to save `callback`
     constructor(value, callback) {
         super(value);
@@ -44,9 +48,11 @@ export class FetchStore extends BusyStore {
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
      */
-    refresh() {
+    refresh(maxAge) {
         if (this._pendingRefresh)
             return this._pendingRefresh;
+        if (!this.stale(maxAge))
+            return false;
         try {
             const value = this._fetch(this.signal); // Retrieving a new signal calls `abort()` which cancels the previous one.
             if (isAsync(value))
@@ -81,6 +87,10 @@ export class FetchStore extends BusyStore {
         return this._callback(signal);
     }
     _callback;
+    /** Whether this store is has currently been invalidated and needs a refresh. */
+    get invalidated() {
+        return !!this._invalidation;
+    }
     /**
      * Invalidate this store so a new fetch is triggered on the next read of `loading` or `value`.
      * - Triggers `abort()` so any current awaits are cancelled.
@@ -90,12 +100,6 @@ export class FetchStore extends BusyStore {
         this._invalidation++;
     }
     _invalidation = 0;
-    /** Re-fetch now if the current value is older than `maxAge` milliseconds or has been invalidated. */
-    refreshStale(maxAge) {
-        if (this._invalidation || this.age > maxAge)
-            return this.refresh();
-        return true;
-    }
     // Override to abort any current in-flight fetch and pending async operation.
     // - Sends `ABORT` to the current `AbortSignal` and clears the controller (a new signal will be created on the next read or fetch).
     // - Any pending `await()` result will be silently discarded.

package/store/Store.d.ts

@@ -92,6 +92,15 @@ export declare class Store<T, TT = T> implements AsyncIterable<T, void, void>, A
      * @example if (store.age > MINUTE) refreshStore(store);
      */
     get age(): number;
+    /**
+     * Whether this store is stale based on a `maxAge` value in milliseconds.
+     *
+     * @param maxAge The maximum age for the stale check.
+     * - `0` zero means "always refresh" (this is the default).
+     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - Any other value may or may not be stale based on `this.age`
+     */
+    stale(maxAge?: number): boolean;
     /** Current error of this store, or `undefined` if there is no error. */
     get reason(): unknown;
     set reason(reason: unknown);

package/store/Store.js

@@ -132,6 +132,17 @@ export class Store {
         const time = this.time;
         return typeof time === "number" ? Date.now() - time : Infinity;
     }
+    /**
+     * Whether this store is stale based on a `maxAge` value in milliseconds.
+     *
+     * @param maxAge The maximum age for the stale check.
+     * - `0` zero means "always refresh" (this is the default).
+     * - `Infinity` means "refresh only if store is still in a loading state.
+     * - Any other value may or may not be stale based on `this.age`
+     */
+    stale(maxAge = 0) {
+        return this.age >= maxAge;
+    }
     /** Current error of this store, or `undefined` if there is no error. */
     get reason() {
         return this._reason;

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;