shelving 1.200.0 → 1.201.0

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/APIProvider.d.ts

@@ -2,7 +2,7 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 /** Provider for API endpoints rooted at a common base URL. */
-export declare abstract class APIProvider<P = unknown, R = unknown> {
+export declare abstract class APIProvider<P = unknown, R = unknown> implements AsyncDisposable {
     /** The base URL for this API. */
     abstract readonly url: URL;
     /**
@@ -43,4 +43,5 @@ export declare abstract class APIProvider<P = unknown, R = unknown> {
     abstract parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
     /** Send a payload to an `Endpoint` and retrieve the result. */
     call<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Promise<RR>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/APIProvider.js

@@ -6,4 +6,8 @@ export class APIProvider {
         const response = await this.fetch(request);
         return this.parseResponse(endpoint, response, caller);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        // Empty by default.
+    }
 }

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,14 +8,19 @@ 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> {
+export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> implements AsyncDisposable {
     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;
     refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/CachedAPIProvider.js

@@ -1,3 +1,5 @@
+import { AVOID_REFRESH } from "../../store/FetchStore.js";
+import { awaitDispose } from "../../util/dispose.js";
 import { APICache } from "../cache/APICache.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
 /**
@@ -5,19 +7,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);
@@ -31,4 +36,9 @@ export class CachedAPIProvider extends ThroughAPIProvider {
     refreshAll(endpoint) {
         this._cache.refreshAll(endpoint, this.maxAge);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this._cache, // Dispose the cache.
+        super[Symbol.asyncDispose]());
+    }
 }

package/api/provider/ThroughAPIProvider.d.ts

@@ -15,4 +15,5 @@ export declare class ThroughAPIProvider<P, R> extends APIProvider<P, R> implemen
     getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
     fetch(request: Request): Promise<Response>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/ThroughAPIProvider.js

@@ -1,3 +1,4 @@
+import { awaitDispose } from "../../util/dispose.js";
 import { APIProvider } from "./APIProvider.js";
 /**
  * Provider wrapper that delegates API operations to a source provider.
@@ -24,4 +25,8 @@ export class ThroughAPIProvider extends APIProvider {
     fetch(request) {
         return this.source.fetch(request);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this.source);
+    }
 }

package/db/provider/CacheDBProvider.d.ts

@@ -23,4 +23,5 @@ export declare class CacheDBProvider<I extends Identifier, T extends Data> exten
     setQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, data: TT): Promise<void>;
     updateQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>, updates: Updates<TT>): Promise<void>;
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/CacheDBProvider.js

@@ -1,3 +1,4 @@
+import { awaitDispose } from "../../util/dispose.js";
 import { DBProvider } from "./DBProvider.js";
 import { MemoryDBProvider } from "./MemoryDBProvider.js";
 /** Keep a copy of asynchronous remote data in a local synchronous cache. */
@@ -58,4 +59,10 @@ export class CacheDBProvider extends DBProvider {
         await this.source.deleteQuery(collection, query);
         this.memory.getTable(collection).deleteQuery(query);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this.source, // Dispose the source API provider.
+        this.memory, // Dispose the source API provider.
+        super[Symbol.asyncDispose]());
+    }
 }

package/db/provider/ChangesDBProvider.d.ts

@@ -14,7 +14,10 @@ export type DBChange<I extends Identifier> = {
     readonly data?: unknown;
     readonly updates?: unknown;
 };
-/** Asynchronous provider that keeps a log of any written changes to its `.changes` property. */
+/**
+ * Database provider that keeps a log of any written changes to its `.changes` property.
+ * - This is useful if you want to hook into a database to build out audit logging functionality.
+ */
 export declare class ChangesDBProvider<I extends Identifier, T extends Data> extends ThroughDBProvider<I, T> {
     get changes(): ReadonlyArray<DBChange<I>>;
     readonly _changes: MutableArray<DBChange<I>>;

package/db/provider/ChangesDBProvider.js

@@ -1,5 +1,8 @@
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
-/** Asynchronous provider that keeps a log of any written changes to its `.changes` property. */
+/**
+ * Database provider that keeps a log of any written changes to its `.changes` property.
+ * - This is useful if you want to hook into a database to build out audit logging functionality.
+ */
 export class ChangesDBProvider extends ThroughDBProvider {
     get changes() {
         return this._changes;

package/db/provider/DBProvider.d.ts

@@ -4,7 +4,7 @@ import type { Query } from "../../util/query.js";
 import type { Updates } from "../../util/update.js";
 import type { Collection } from "../collection/Collection.js";
 /** Provider with a fully asynchronous interface for database access. */
-export declare abstract class DBProvider<I extends Identifier = Identifier, T extends Data = Data> {
+export declare abstract class DBProvider<I extends Identifier = Identifier, T extends Data = Data> implements AsyncDisposable {
     abstract getItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<OptionalItem<II, TT>>;
     requireItem<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): Promise<Item<II, TT>>;
     abstract getItemSequence<II extends I, TT extends T>(collection: Collection<string, II, TT>, id: II): OptionalItemSequence<II, TT>;
@@ -20,4 +20,5 @@ export declare abstract class DBProvider<I extends Identifier = Identifier, T ex
     abstract deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/DBProvider.js

@@ -1,5 +1,6 @@
 import { RequiredError } from "../../error/RequiredError.js";
 import { countArray, getFirst } from "../../util/array.js";
+import { awaitDispose } from "../../util/dispose.js";
 /** Provider with a fully asynchronous interface for database access. */
 export class DBProvider {
     async requireItem(collection, id) {
@@ -30,4 +31,10 @@ export class DBProvider {
             });
         return first;
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(
+        // Empty by default.
+        );
+    }
 }

package/db/provider/MemoryDBProvider.d.ts

@@ -8,7 +8,7 @@ import { DBProvider } from "./DBProvider.js";
 /**
  * Fast in-memory store for data.
  * - Extremely fast (ideal for caching!), but does not persist data after the browser window is closed.
- * - `get()` etc return the exact same instance of an object that's passed into `set()`
+ * - `getItem()` etc return the exact same instance of an object that's passed into `setItem()`
  */
 export declare class MemoryDBProvider<I extends Identifier = Identifier, T extends Data = Data> extends DBProvider<I, T> {
     /** List of tables in `{ name: MemoryTable }` format. */

package/db/provider/MemoryDBProvider.js

@@ -11,7 +11,7 @@ import { DBProvider } from "./DBProvider.js";
 /**
  * Fast in-memory store for data.
  * - Extremely fast (ideal for caching!), but does not persist data after the browser window is closed.
- * - `get()` etc return the exact same instance of an object that's passed into `set()`
+ * - `getItem()` etc return the exact same instance of an object that's passed into `setItem()`
  */
 export class MemoryDBProvider extends DBProvider {
     /** List of tables in `{ name: MemoryTable }` format. */

package/db/provider/ThroughDBProvider.d.ts

@@ -24,4 +24,5 @@ export declare class ThroughDBProvider<I extends Identifier, T extends Data> imp
     deleteQuery<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<void>;
     getFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<OptionalItem<II, TT>>;
     requireFirst<II extends I, TT extends T>(collection: Collection<string, II, TT>, query: Query<Item<II, TT>>): Promise<Item<II, TT>>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/db/provider/ThroughDBProvider.js

@@ -1,3 +1,4 @@
+import { awaitDispose } from "../../util/dispose.js";
 /** A provider that passes through to an asynchronous source. */
 export class ThroughDBProvider {
     source;
@@ -49,4 +50,8 @@ export class ThroughDBProvider {
     requireFirst(collection, query) {
         return this.source.requireFirst(collection, query);
     }
+    // Implement `AsyncDisposable`
+    async [Symbol.asyncDispose]() {
+        await awaitDispose(this.source);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "shelving",
-	"version": "1.200.0",
+	"version": "1.201.0",
 	"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. */