shelving 1.200.0 → 1.200.1

package/api/cache/APICache.js

@@ -1,3 +1,4 @@
+import { AVOID_REFRESH } from "../../store/FetchStore.js";
 import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { EndpointCache } from "./EndpointCache.js";
@@ -23,7 +24,7 @@ export class APICache {
      * - 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) {
+    async call(endpoint, payload, maxAge = AVOID_REFRESH, caller = this.call) {
         return this.get(endpoint).call(payload, maxAge, caller);
     }
     /** Invalidate a specific store for an endpoint. */

package/api/cache/EndpointCache.d.ts

@@ -18,6 +18,8 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
      * - 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.
+     *
+     * @param maxAge The maximum age (defaults to only refreshing if the value is still in a loading state).
      */
     call(payload: P, maxAge?: number, caller?: AnyCaller): Promise<R>;
     /** Invalidate a specific store. */

package/api/cache/EndpointCache.js

@@ -1,3 +1,4 @@
+import { AVOID_REFRESH } from "../../store/FetchStore.js";
 import { awaitValues } from "../../util/async.js";
 import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
@@ -24,8 +25,10 @@ export class EndpointCache {
      * - 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.
+     *
+     * @param maxAge The maximum age (defaults to only refreshing if the value is still in a loading state).
      */
-    async call(payload, maxAge, caller = this.call) {
+    async call(payload, maxAge = AVOID_REFRESH, caller = this.call) {
         const store = this.get(payload, caller);
         await store.refresh(maxAge);
         return store.value;

package/api/provider/CachedAPIProvider.d.ts

@@ -1,4 +1,5 @@
 import type { AnyCaller } from "../../util/function.js";
+import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "./APIProvider.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
@@ -7,12 +8,16 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - Constructor accepts a `source` provider and an optional default `maxAge`.
  * - On `call(...)`, triggers `cache.refresh(maxAge)` for the endpoint+payload before awaiting `cache.call(...)`.
  * - `invalidate`, `invalidateAll`, `refresh`, and `refreshAll` pass through to the underlying cache and use `this.maxAge` as the default refresh timing.
+ *
+ * @param `maxAge` The maximum age used when calling `call()` (defaults to `AVOID_REFRESH`, i.e. only refresh if the value is invalidated or still loading).
+ * - Note: This is not used for `refresh()` calls — when you call `refresh()` you likely mean "do it now".
+ * - When we are using `call()` on a cache, the entire point of the cache is to "cache", so the default isn't `0` like it is for `refresh()`
  */
 export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
     readonly maxAge: number | undefined;
     private readonly _cache;
     constructor(source: APIProvider<P, R>, maxAge?: number);
-    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, maxAge?: number | undefined, caller?: AnyCaller): Promise<RR>;
+    call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, _options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
     invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
     invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
     refresh<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;

package/api/provider/CachedAPIProvider.js

@@ -1,3 +1,4 @@
+import { AVOID_REFRESH } from "../../store/FetchStore.js";
 import { APICache } from "../cache/APICache.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
@@ -5,19 +6,22 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - Constructor accepts a `source` provider and an optional default `maxAge`.
  * - On `call(...)`, triggers `cache.refresh(maxAge)` for the endpoint+payload before awaiting `cache.call(...)`.
  * - `invalidate`, `invalidateAll`, `refresh`, and `refreshAll` pass through to the underlying cache and use `this.maxAge` as the default refresh timing.
+ *
+ * @param `maxAge` The maximum age used when calling `call()` (defaults to `AVOID_REFRESH`, i.e. only refresh if the value is invalidated or still loading).
+ * - Note: This is not used for `refresh()` calls — when you call `refresh()` you likely mean "do it now".
+ * - When we are using `call()` on a cache, the entire point of the cache is to "cache", so the default isn't `0` like it is for `refresh()`
  */
 export class CachedAPIProvider extends ThroughAPIProvider {
     maxAge;
     _cache;
-    constructor(source, maxAge) {
+    constructor(source, maxAge = AVOID_REFRESH) {
         super(source);
         this.maxAge = maxAge;
         this._cache = new APICache(source);
     }
-    // @ts-expect-error TS2416: intentionally diverges from `APIProvider.call` — `RequestOptions` are not used by the cache, so the third arg is repurposed as `maxAge`.
-    call(endpoint, payload, maxAge = this.maxAge, caller = this.call) {
-        this._cache.refresh(endpoint, payload, maxAge);
-        return this._cache.call(endpoint, payload, maxAge, caller);
+    // Override call to use the cache racther than calling fresh each time.
+    call(endpoint, payload, _options, caller = this.call) {
+        return this._cache.call(endpoint, payload, this.maxAge, caller);
     }
     invalidate(endpoint, payload) {
         this._cache.invalidate(endpoint, payload);

package/package.json

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

package/store/FetchStore.d.ts

@@ -1,6 +1,10 @@
 import { type NONE } from "../util/constants.js";
 import { BusyStore } from "./BusyStore.js";
 import type { AsyncStoreInput, StoreInput } from "./Store.js";
+/** Zero passed to `refresh()` means "always refresh this value" (this is the default). */
+export declare const ALWAYS_REFRESH = 0;
+/** Infinity passed to `refresh()` means "only refresh if this value is not loaded or invalid". */
+export declare const AVOID_REFRESH: number;
 /** Callback for a callback fetch store. */
 export type FetchCallback<T> = (signal: AbortSignal) => StoreInput<T> | PromiseLike<StoreInput<T>>;
 /**
@@ -21,6 +25,11 @@ export declare class FetchStore<T, TT = T> extends BusyStore<T, TT> {
      * - Triggered automatically when someone reads `value` or `loading`.
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
+     *
+     * @param maxAge The maximum age for whether we refresh or not.
+     * - `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`
      */
     refresh(maxAge?: number): Promise<boolean> | boolean;
     private _pendingRefresh;

package/store/FetchStore.js

@@ -2,6 +2,10 @@ import { RequiredError } from "../error/RequiredError.js";
 import { isAsync } from "../util/async.js";
 import { ABORT, SKIP } from "../util/constants.js";
 import { BusyStore } from "./BusyStore.js";
+/** Zero passed to `refresh()` means "always refresh this value" (this is the default). */
+export const ALWAYS_REFRESH = 0;
+/** Infinity passed to `refresh()` means "only refresh if this value is not loaded or invalid". */
+export const AVOID_REFRESH = Infinity;
 /**
  * Store that fetches its values from a remote source.
  *
@@ -47,8 +51,13 @@ export class FetchStore extends BusyStore {
      * - Triggered automatically when someone reads `value` or `loading`.
      * - Refreshes are de-duplicated. Concurrent calls while a fetch is in-flight return the same promise.
      * - Never throws — errors are stored as `reason`.
+     *
+     * @param maxAge The maximum age for whether we refresh or not.
+     * - `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`
      */
-    refresh(maxAge) {
+    refresh(maxAge = ALWAYS_REFRESH) {
         if (this._pendingRefresh)
             return this._pendingRefresh;
         if (!this.stale(maxAge))

package/store/Store.d.ts

@@ -99,10 +99,10 @@ export declare class Store<T, TT = T> implements AsyncIterable<T, void, void>, A
      *
      * @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.
+     * - `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;
+    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

@@ -137,10 +137,10 @@ export class Store {
      *
      * @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.
+     * - `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) {
+    stale(maxAge) {
         return this.age >= maxAge;
     }
     /** Current error of this store, or `undefined` if there is no error. */