shelving 1.194.0 → 1.195.0

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/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.0",
 	"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;