shelving 1.200.1 → 1.201.0

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

@@ -13,7 +13,7 @@ import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
  * - 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);
@@ -22,4 +22,5 @@ export declare class CachedAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
     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,4 +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";
 /**
@@ -35,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.1",
+	"version": "1.201.0",
 	"author": "Dave Houlbrooke <dave@shax.com>",
 	"repository": {
 		"type": "git",