shelving 1.236.0 → 1.236.1

package/api/cache/APICache.d.ts

@@ -3,30 +3,93 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
 import { EndpointCache } from "./EndpointCache.js";
 /**
- * Cache of `EndpointCache` objects for multiple endpoints.
+ * Cache of `EndpointCache` objects keyed by `Endpoint`, providing memoised API results across many endpoints.
  * - Use `get(endpoint)` to retrieve or create the `EndpointCache` for a given endpoint, then `get(payload)` on that to get a specific `EndpointStore`.
+ * - Disposing the cache disposes every nested `EndpointCache` and clears the map.
+ *
+ * @example
+ * const cache = new APICache(provider);
+ * const user = await cache.call(getUser, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache
  */
 export declare class APICache<P, R> implements AsyncDisposable {
     private readonly _endpoints;
+    /**
+     * The underlying `APIProvider` that backs every cached endpoint.
+     *
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/provider
+     */
     readonly provider: APIProvider<P, R>;
+    /**
+     * Create a new `APICache` backed by an `APIProvider`.
+     *
+     * @param provider The `APIProvider` used to fetch results for every cached endpoint.
+     * @example new APICache(provider)
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache
+     */
     constructor(provider: APIProvider<P, R>);
     private _get;
-    /** Get (or create) the `EndpointCache` for the given endpoint. */
+    /**
+     * Get (or create) the `EndpointCache` for the given endpoint.
+     *
+     * @param endpoint The endpoint whose `EndpointCache` should be returned.
+     * @returns The existing `EndpointCache` for `endpoint`, or a newly created one.
+     * @example cache.get(getUser).get({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/get
+     */
     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.
+     *
+     * @param endpoint The endpoint to fetch a result for.
+     * @param payload The payload to send to the endpoint.
+     * @param maxAge The maximum age in milliseconds (defaults to only refreshing if the value is still in a loading state).
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The cached or freshly fetched result.
+     * @throws Whatever `APIProvider.call` throws if the fetch fails.
+     * @example await cache.call(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/call
      */
     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 a specific store for an endpoint so the next read refetches.
+     *
+     * @param endpoint The endpoint whose cached payload should be invalidated.
+     * @param payload The payload identifying the specific store to invalidate.
+     * @example cache.invalidate(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/invalidate
+     */
     invalidate<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP): void;
-    /** Invalidate all stores for an endpoint. */
+    /**
+     * Invalidate all stores for an endpoint so the next read of any payload refetches.
+     *
+     * @param endpoint The endpoint whose stores should all be invalidated.
+     * @example cache.invalidateAll(getUser)
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/invalidateAll
+     */
     invalidateAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>): void;
-    /** Trigger a refetch on a specific store for an endpoint. */
+    /**
+     * Trigger a refetch on a specific store for an endpoint.
+     *
+     * @param endpoint The endpoint whose store should be refreshed.
+     * @param payload The payload identifying the specific store to refresh.
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @example cache.refresh(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/refresh
+     */
     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. */
+    /**
+     * Trigger a refetch on all stores for an endpoint.
+     *
+     * @param endpoint The endpoint whose stores should all be refreshed.
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @example cache.refreshAll(getUser)
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/refreshAll
+     */
     refreshAll<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, maxAge?: number): void;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/cache/APICache.js

@@ -3,12 +3,31 @@ import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { EndpointCache } from "./EndpointCache.js";
 /**
- * Cache of `EndpointCache` objects for multiple endpoints.
+ * Cache of `EndpointCache` objects keyed by `Endpoint`, providing memoised API results across many endpoints.
  * - Use `get(endpoint)` to retrieve or create the `EndpointCache` for a given endpoint, then `get(payload)` on that to get a specific `EndpointStore`.
+ * - Disposing the cache disposes every nested `EndpointCache` and clears the map.
+ *
+ * @example
+ * const cache = new APICache(provider);
+ * const user = await cache.call(getUser, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache
  */
 export class APICache {
     _endpoints = new Map();
+    /**
+     * The underlying `APIProvider` that backs every cached endpoint.
+     *
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/provider
+     */
     provider;
+    /**
+     * Create a new `APICache` backed by an `APIProvider`.
+     *
+     * @param provider The `APIProvider` used to fetch results for every cached endpoint.
+     * @example new APICache(provider)
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache
+     */
     constructor(provider) {
         this.provider = provider;
     }
@@ -23,23 +42,60 @@ export class APICache {
      * - 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 endpoint The endpoint to fetch a result for.
+     * @param payload The payload to send to the endpoint.
+     * @param maxAge The maximum age in milliseconds (defaults to only refreshing if the value is still in a loading state).
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The cached or freshly fetched result.
+     * @throws Whatever `APIProvider.call` throws if the fetch fails.
+     * @example await cache.call(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/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. */
+    /**
+     * Invalidate a specific store for an endpoint so the next read refetches.
+     *
+     * @param endpoint The endpoint whose cached payload should be invalidated.
+     * @param payload The payload identifying the specific store to invalidate.
+     * @example cache.invalidate(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/invalidate
+     */
     invalidate(endpoint, payload) {
         this._get(endpoint)?.invalidate(payload);
     }
-    /** Invalidate all stores for an endpoint. */
+    /**
+     * Invalidate all stores for an endpoint so the next read of any payload refetches.
+     *
+     * @param endpoint The endpoint whose stores should all be invalidated.
+     * @example cache.invalidateAll(getUser)
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/invalidateAll
+     */
     invalidateAll(endpoint) {
         this._get(endpoint)?.invalidateAll();
     }
-    /** Trigger a refetch on a specific store for an endpoint. */
+    /**
+     * Trigger a refetch on a specific store for an endpoint.
+     *
+     * @param endpoint The endpoint whose store should be refreshed.
+     * @param payload The payload identifying the specific store to refresh.
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @example cache.refresh(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/refresh
+     */
     refresh(endpoint, payload, maxAge) {
         this._get(endpoint)?.refresh(payload, maxAge);
     }
-    /** Trigger a refetch on all stores for an endpoint. */
+    /**
+     * Trigger a refetch on all stores for an endpoint.
+     *
+     * @param endpoint The endpoint whose stores should all be refreshed.
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @example cache.refreshAll(getUser)
+     * @see https://dhoulb.github.io/shelving/api/cache/APICache/APICache/refreshAll
+     */
     refreshAll(endpoint, maxAge) {
         this._get(endpoint)?.refreshAll(maxAge);
     }

package/api/cache/EndpointCache.d.ts

@@ -3,15 +3,49 @@ import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
 import { EndpointStore } from "../store/EndpointStore.js";
 /**
- * Cache of `EndpointStore` objects for a single endpoint, keyed by serialized payload.
+ * Cache of `EndpointStore` objects for a single endpoint, keyed by the rendered request URL of each payload.
  * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
+ * - Disposing the cache disposes every nested `EndpointStore` and clears the map.
+ *
+ * @example
+ * const cache = new EndpointCache(getUser, provider);
+ * const user = await cache.call({ id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache
  */
 export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDisposable {
     private readonly _endpoints;
+    /**
+     * The endpoint that every store in this cache fetches from.
+     *
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/endpoint
+     */
     readonly endpoint: Endpoint<P, R>;
+    /**
+     * The `APIProvider` used to render URLs and fetch results for this endpoint.
+     *
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/provider
+     */
     readonly provider: APIProvider<P, R>;
+    /**
+     * Create a new `EndpointCache` for a single endpoint and provider.
+     *
+     * @param endpoint The endpoint that every cached store fetches from.
+     * @param provider The `APIProvider` used to render URLs and fetch results.
+     * @example new EndpointCache(getUser, provider)
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache
+     */
     constructor(endpoint: Endpoint<P, R>, provider: APIProvider<P, R>);
-    /** Get (or create) the `EndpointStore` for the given payload. */
+    /**
+     * Get (or create) the `EndpointStore` for the given payload.
+     * - Stores are keyed by the rendered request URL, so equivalent payloads share a store.
+     *
+     * @param payload The payload identifying the store to return.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The existing `EndpointStore` for `payload`, or a newly created one.
+     * @example cache.get({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/get
+     */
     get(payload: P, caller?: AnyCaller): EndpointStore<P, R>;
     /**
      * Fetch (or return a cached result) for the given payload.
@@ -19,16 +53,50 @@ export declare class EndpointCache<P = unknown, R = unknown> implements AsyncDis
      * - 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).
+     * @param payload The payload to send to the endpoint.
+     * @param maxAge The maximum age in milliseconds (defaults to only refreshing if the value is still in a loading state).
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The cached or freshly fetched result.
+     * @throws Whatever `APIProvider.call` throws if the fetch fails.
+     * @example await cache.call({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/call
      */
     call(payload: P, maxAge?: number, caller?: AnyCaller): Promise<R>;
-    /** Invalidate a specific store. */
+    /**
+     * Invalidate a specific store so the next read refetches.
+     *
+     * @param payload The payload identifying the store to invalidate.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @example cache.invalidate({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/invalidate
+     */
     invalidate(payload: P, caller?: AnyCaller): void;
-    /** Invalidate all stores. */
+    /**
+     * Invalidate all stores so the next read of any payload refetches.
+     *
+     * @example cache.invalidateAll()
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/invalidateAll
+     */
     invalidateAll(): void;
-    /** Trigger a refetch on a specific store. */
+    /**
+     * Trigger a refetch on a specific store.
+     *
+     * @param payload The payload identifying the store to refresh.
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise that resolves when the refetch settles.
+     * @example await cache.refresh({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/refresh
+     */
     refresh(payload: P, maxAge?: number, caller?: AnyCaller): Promise<void>;
-    /** Trigger a refetch on all stores. */
+    /**
+     * Trigger a refetch on all stores.
+     *
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @returns A promise that resolves when every refetch settles.
+     * @example await cache.refreshAll()
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/refreshAll
+     */
     refreshAll(maxAge?: number): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/cache/EndpointCache.js

@@ -4,18 +4,52 @@ import { awaitDispose } from "../../util/dispose.js";
 import { setMapItem } from "../../util/map.js";
 import { EndpointStore } from "../store/EndpointStore.js";
 /**
- * Cache of `EndpointStore` objects for a single endpoint, keyed by serialized payload.
+ * Cache of `EndpointStore` objects for a single endpoint, keyed by the rendered request URL of each payload.
  * - Use `get(payload)` to retrieve or create the `EndpointStore` for a given payload.
+ * - Disposing the cache disposes every nested `EndpointStore` and clears the map.
+ *
+ * @example
+ * const cache = new EndpointCache(getUser, provider);
+ * const user = await cache.call({ id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache
  */
 export class EndpointCache {
     _endpoints = new Map();
+    /**
+     * The endpoint that every store in this cache fetches from.
+     *
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/endpoint
+     */
     endpoint;
+    /**
+     * The `APIProvider` used to render URLs and fetch results for this endpoint.
+     *
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/provider
+     */
     provider;
+    /**
+     * Create a new `EndpointCache` for a single endpoint and provider.
+     *
+     * @param endpoint The endpoint that every cached store fetches from.
+     * @param provider The `APIProvider` used to render URLs and fetch results.
+     * @example new EndpointCache(getUser, provider)
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache
+     */
     constructor(endpoint, provider) {
         this.endpoint = endpoint;
         this.provider = provider;
     }
-    /** Get (or create) the `EndpointStore` for the given payload. */
+    /**
+     * Get (or create) the `EndpointStore` for the given payload.
+     * - Stores are keyed by the rendered request URL, so equivalent payloads share a store.
+     *
+     * @param payload The payload identifying the store to return.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The existing `EndpointStore` for `payload`, or a newly created one.
+     * @example cache.get({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/get
+     */
     get(payload, caller = this.get) {
         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));
@@ -26,27 +60,61 @@ export class EndpointCache {
      * - 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).
+     * @param payload The payload to send to the endpoint.
+     * @param maxAge The maximum age in milliseconds (defaults to only refreshing if the value is still in a loading state).
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The cached or freshly fetched result.
+     * @throws Whatever `APIProvider.call` throws if the fetch fails.
+     * @example await cache.call({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/call
      */
     async call(payload, maxAge = AVOID_REFRESH, caller = this.call) {
         const store = this.get(payload, caller);
         await store.refresh(maxAge);
         return store.value;
     }
-    /** Invalidate a specific store. */
+    /**
+     * Invalidate a specific store so the next read refetches.
+     *
+     * @param payload The payload identifying the store to invalidate.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @example cache.invalidate({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/invalidate
+     */
     invalidate(payload, caller = this.invalidate) {
         this.get(payload, caller)?.invalidate();
     }
-    /** Invalidate all stores. */
+    /**
+     * Invalidate all stores so the next read of any payload refetches.
+     *
+     * @example cache.invalidateAll()
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/invalidateAll
+     */
     invalidateAll() {
         for (const store of this._endpoints.values())
             store.invalidate();
     }
-    /** Trigger a refetch on a specific store. */
+    /**
+     * Trigger a refetch on a specific store.
+     *
+     * @param payload The payload identifying the store to refresh.
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise that resolves when the refetch settles.
+     * @example await cache.refresh({ id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/refresh
+     */
     async refresh(payload, maxAge, caller = this.invalidate) {
         await this.get(payload, caller)?.refresh(maxAge);
     }
-    /** Trigger a refetch on all stores. */
+    /**
+     * Trigger a refetch on all stores.
+     *
+     * @param maxAge The maximum age in milliseconds before a refetch is triggered.
+     * @returns A promise that resolves when every refetch settles.
+     * @example await cache.refreshAll()
+     * @see https://dhoulb.github.io/shelving/api/cache/EndpointCache/EndpointCache/refreshAll
+     */
     async refreshAll(maxAge) {
         await awaitValues(...this._endpoints.values().map(store => store.refresh(maxAge)));
     }