shelving 1.197.0 → 1.198.0

package/api/index.d.ts

@@ -3,6 +3,7 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
+export * from "./provider/CachedAPIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/JSONAPIProvider.js";

package/api/index.js

@@ -3,6 +3,7 @@ export * from "./cache/EndpointCache.js";
 export * from "./endpoint/Endpoint.js";
 export * from "./endpoint/util.js";
 export * from "./provider/APIProvider.js";
+export * from "./provider/CachedAPIProvider.js";
 export * from "./provider/ClientAPIProvider.js";
 export * from "./provider/DebugAPIProvider.js";
 export * from "./provider/JSONAPIProvider.js";

package/api/provider/CachedAPIProvider.d.ts

@@ -0,0 +1,20 @@
+import type { AnyCaller } from "../../util/function.js";
+import type { Endpoint } from "../endpoint/Endpoint.js";
+import type { APIProvider } from "./APIProvider.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * API provider wrapper that serves requests through an `APICache`.
+ * - 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.
+ */
+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>;
+    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;
+}

package/api/provider/CachedAPIProvider.js

@@ -0,0 +1,34 @@
+import { APICache } from "../cache/APICache.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * API provider wrapper that serves requests through an `APICache`.
+ * - 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.
+ */
+export class CachedAPIProvider extends ThroughAPIProvider {
+    maxAge;
+    _cache;
+    constructor(source, maxAge) {
+        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);
+    }
+    invalidate(endpoint, payload) {
+        this._cache.invalidate(endpoint, payload);
+    }
+    invalidateAll(endpoint) {
+        this._cache.invalidateAll(endpoint);
+    }
+    refresh(endpoint, payload) {
+        this._cache.refresh(endpoint, payload, this.maxAge);
+    }
+    refreshAll(endpoint) {
+        this._cache.refreshAll(endpoint, this.maxAge);
+    }
+}

package/package.json

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