shelving 1.197.0 → 1.199.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/api/provider/DebugAPIProvider.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";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Provider that logs operations to the console. */
+/** Provider that logs everything to the console in some detail to help diagnose issues in development. */
 export declare class DebugAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
     getRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
     fetch(request: Request): Promise<Response>;

package/api/provider/DebugAPIProvider.js

@@ -1,43 +1,39 @@
-import { debugFullRequest, debugFullResponse } from "../../util/debug.js";
+import { ANSI_ICON_ERROR, ANSI_ICON_REQUEST, ANSI_ICON_RESPONSE, ANSI_ICON_SUCCESS, ANSI_ICON_WAITING } from "../../util/ansi.js";
+import { debugFullRequest, debugFullResponse, debugRequest } from "../../util/debug.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Provider that logs operations to the console. */
+/** Provider that logs everything to the console in some detail to help diagnose issues in development. */
 export class DebugAPIProvider extends ThroughAPIProvider {
     getRequest(endpoint, payload, options, caller = this.getRequest) {
-        const url = this.url.toString();
-        const ep = endpoint.toString();
         try {
             const request = super.getRequest(endpoint, payload, options, caller);
-            console.debug("✔ REQUEST", url, ep, payload);
+            console.debug(`${ANSI_ICON_WAITING} ${endpoint.toString()}`, payload);
             return request;
         }
         catch (reason) {
-            console.error("✘ REQUEST", url, ep, payload, reason);
+            console.error(`${ANSI_ICON_ERROR} ${endpoint.toString()}`, payload, reason);
             throw reason;
         }
     }
     async fetch(request) {
-        const url = this.url.toString();
         try {
-            console.debug("→ FETCH", url, await debugFullRequest(request));
+            console.debug(`${ANSI_ICON_REQUEST} ${await debugFullRequest(request)}`);
             const response = await super.fetch(request);
-            console.debug("← FETCH", url, await debugFullResponse(response));
+            console.debug(`${ANSI_ICON_RESPONSE} ${debugRequest(request)}\n\n${await debugFullResponse(response)}`);
             return response;
         }
         catch (reason) {
-            console.error("✘ FETCH", url, reason);
+            console.error(`${ANSI_ICON_ERROR} ${debugRequest(request)}`, reason);
             throw reason;
         }
     }
     async parseResponse(endpoint, response, caller = this.parseResponse) {
-        const url = this.url.toString();
-        const ep = endpoint.toString();
         try {
             const result = await super.parseResponse(endpoint, response, caller);
-            console.debug("✔ RESPONSE", url, ep, result);
+            console.debug(`${ANSI_ICON_SUCCESS} ${endpoint.toString()}`, result);
             return result;
         }
         catch (reason) {
-            console.error("✘ RESPONSE", url, ep, reason);
+            console.error(`${ANSI_ICON_ERROR} ${endpoint.toString()}`, reason);
             throw reason;
         }
     }

package/api/provider/LoggingAPIProvider.d.ts

@@ -0,0 +1,20 @@
+import type { Callback } from "../../util/function.js";
+import type { APIProvider } from "./APIProvider.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * Provider that logs fetches to the console to keep useful logs in production.
+ * - Defaults to calling `console.log()` for requests/responses and
+ */
+export declare class LoggingAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
+    protected _logRequest: Callback<[Request]>;
+    protected _logResponse: Callback<[Response, Request]>;
+    protected _logError: Callback<[reason: unknown, Request]>;
+    constructor(source: APIProvider<P, R>, 
+    /** Log requests. */
+    onRequest?: Callback<[Request]>, 
+    /** Log responses to requests. */
+    onResponse?: Callback<[Response, Request]>, 
+    /** Log errors for requests. */
+    onError?: Callback<[reason: unknown, Request]>);
+    fetch(request: Request): Promise<Response>;
+}

package/api/provider/LoggingAPIProvider.js

@@ -0,0 +1,35 @@
+import { logRequest, logRequestError, logRequestResponse } from "../../util/log.js";
+import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * Provider that logs fetches to the console to keep useful logs in production.
+ * - Defaults to calling `console.log()` for requests/responses and
+ */
+export class LoggingAPIProvider extends ThroughAPIProvider {
+    _logRequest;
+    _logResponse;
+    _logError;
+    constructor(source, 
+    /** Log requests. */
+    onRequest = logRequest, 
+    /** Log responses to requests. */
+    onResponse = logRequestResponse, 
+    /** Log errors for requests. */
+    onError = logRequestError) {
+        super(source);
+        this._logRequest = onRequest;
+        this._logResponse = onResponse;
+        this._logError = onError;
+    }
+    async fetch(request) {
+        try {
+            this._logRequest(request);
+            const response = await super.fetch(request);
+            this._logResponse(response, request);
+            return response;
+        }
+        catch (reason) {
+            this._logError(reason, request);
+            throw reason;
+        }
+    }
+}

package/db/provider/DebugDBProvider.js

@@ -1,143 +1,144 @@
+import { ANSI_ICON_ERROR, ANSI_ICON_REQUEST, ANSI_ICON_RESPONSE, ANSI_ICON_SUCCESS } from "../../util/ansi.js";
 import { ThroughDBProvider } from "./ThroughDBProvider.js";
 /** Provider that logs operations to the console. */
 export class DebugDBProvider extends ThroughDBProvider {
     async getItem(collection, id) {
         try {
-            console.debug("⋯ GET", collection.name, id);
+            console.debug(`${ANSI_ICON_REQUEST} GET ITEM`, collection.name, id);
             const item = await super.getItem(collection, id);
-            console.debug("↩ GET", collection.name, id, item);
+            console.debug(`${ANSI_ICON_RESPONSE} GET ITEM`, collection.name, id, item);
             return item;
         }
         catch (reason) {
-            console.error("✘ GET", collection.name, id, reason);
+            console.error(`${ANSI_ICON_ERROR} GET ITEM`, collection.name, id, reason);
             throw reason;
         }
     }
     async *getItemSequence(collection, id) {
         try {
-            console.debug("⋯ ITERATE", collection.name, id);
+            console.debug(`${ANSI_ICON_REQUEST} SEQUENCE ITEM`, collection.name, id);
             for await (const item of super.getItemSequence(collection, id)) {
-                console.debug("↩ ITERATE", collection.name, id, item);
+                console.debug(`${ANSI_ICON_RESPONSE} SEQUENCE ITEM`, collection.name, id, item);
                 yield item;
             }
-            console.debug("✔ ITERATE", collection.name, id);
+            console.debug(`${ANSI_ICON_SUCCESS} SEQUENCE ITEM`, collection.name, id);
         }
         catch (thrown) {
-            console.error("✘ ITERATE", collection.name, id, thrown);
+            console.error(`${ANSI_ICON_ERROR} SEQUENCE ITEM`, collection.name, id, thrown);
         }
     }
     async addItem(collection, data) {
         try {
-            console.debug("⋯ ADD", collection.name, data);
+            console.debug(`${ANSI_ICON_REQUEST} ADD ITEM`, collection.name, data);
             const id = await super.addItem(collection, data);
-            console.debug("✔ ADD", collection.name, id, data);
+            console.debug(`${ANSI_ICON_SUCCESS} ADD ITEM`, collection.name, id, data);
             return id;
         }
         catch (reason) {
-            console.error("✘ ADD", collection.name, data, reason);
+            console.error(`${ANSI_ICON_ERROR} ADD ITEM`, collection.name, data, reason);
             throw reason;
         }
     }
     async setItem(collection, id, data) {
         try {
-            console.debug("⋯ SET", collection.name, id, data);
+            console.debug(`${ANSI_ICON_REQUEST} SET ITEM`, collection.name, id, data);
             await super.setItem(collection, id, data);
-            console.debug("✔ SET", collection.name, id, data);
+            console.debug(`${ANSI_ICON_SUCCESS} SET ITEM`, collection.name, id, data);
         }
         catch (reason) {
-            console.error("✘ SET", collection.name, id, data, reason);
+            console.error(`${ANSI_ICON_ERROR} SET ITEM`, collection.name, id, data, reason);
             throw reason;
         }
     }
     async updateItem(collection, id, updates) {
         try {
-            console.debug("⋯ UPDATE", collection.name, id, updates);
+            console.debug(`${ANSI_ICON_REQUEST} UPDATE ITEM`, collection.name, id, updates);
             await super.updateItem(collection, id, updates);
-            console.debug("✔ UPDATE", collection.name, id, updates);
+            console.debug(`${ANSI_ICON_SUCCESS} UPDATE ITEM`, collection.name, id, updates);
         }
         catch (reason) {
-            console.error("✘ UPDATE", collection.name, id, updates, reason);
+            console.error(`${ANSI_ICON_ERROR} UPDATE ITEM`, collection.name, id, updates, reason);
             throw reason;
         }
     }
     async deleteItem(collection, id) {
         try {
-            console.debug("⋯ DELETE", collection.name, id);
+            console.debug(`${ANSI_ICON_REQUEST} DELETE`, collection.name, id);
             await super.deleteItem(collection, id);
-            console.debug("✔ DELETE", collection.name, id);
+            console.debug(`${ANSI_ICON_SUCCESS} DELETE`, collection.name, id);
         }
         catch (reason) {
-            console.error("✘ DELETE", collection.name, id, reason);
+            console.error(`${ANSI_ICON_ERROR} DELETE`, collection.name, id, reason);
             throw reason;
         }
     }
     async countQuery(collection, query) {
         try {
-            console.debug("⋯ COUNT", collection.name, query);
+            console.debug(`${ANSI_ICON_REQUEST} COUNT QUERY`, collection.name, query);
             const count = await super.countQuery(collection, query);
-            console.debug("✔ COUNT", collection.name, query, count);
+            console.debug(`${ANSI_ICON_RESPONSE} COUNT QUERY`, collection.name, query, count);
             return count;
         }
         catch (reason) {
-            console.error("✘ COUNT", collection.name, query, reason);
+            console.error(`${ANSI_ICON_ERROR} COUNT QUERY`, collection.name, query, reason);
             throw reason;
         }
     }
     async getQuery(collection, query) {
         try {
-            console.debug("⋯ GET", collection.name, query);
+            console.debug(`${ANSI_ICON_REQUEST} GET`, collection.name, query);
             const items = await super.getQuery(collection, query);
-            console.debug("✔ GET", collection.name, query, items);
+            console.debug(`${ANSI_ICON_RESPONSE} GET`, collection.name, query, items);
             return items;
         }
         catch (reason) {
-            console.error("✘ GET", collection.name, query, reason);
+            console.error(`${ANSI_ICON_ERROR} GET`, collection.name, query, reason);
             throw reason;
         }
     }
     async *getQuerySequence(collection, query) {
         try {
-            console.debug("⋯ ITERATE", collection.name, query);
+            console.debug(`${ANSI_ICON_REQUEST} SEQUENCE QUERY`, collection.name, query);
             for await (const items of super.getQuerySequence(collection, query)) {
-                console.debug("↩ ITERATE", collection.name, query, items);
+                console.debug(`${ANSI_ICON_RESPONSE} SEQUENCE QUERY`, collection.name, query, items);
                 yield items;
             }
-            console.debug("✔ ITERATE", collection.name, query);
+            console.debug(`${ANSI_ICON_SUCCESS} SEQUENCE QUERY`, collection.name, query);
         }
         catch (thrown) {
-            console.error("✘ ITERATE", collection.name, query, thrown);
+            console.error(`${ANSI_ICON_ERROR} SEQUENCE QUERY`, collection.name, query, thrown);
         }
     }
     async setQuery(collection, query, data) {
         try {
-            console.debug("⋯ SET", collection.name, query, data);
+            console.debug(`${ANSI_ICON_REQUEST} SET QUERY`, collection.name, query, data);
             await super.setQuery(collection, query, data);
-            console.debug("✔ SET", collection.name, query, data);
+            console.debug(`${ANSI_ICON_SUCCESS} SET QUERY`, collection.name, query, data);
         }
         catch (reason) {
-            console.error("✘ SET", collection.name, query, data, reason);
+            console.error(`${ANSI_ICON_ERROR} SET QUERY`, collection.name, query, data, reason);
             throw reason;
         }
     }
     async updateQuery(collection, query, updates) {
         try {
-            console.debug("⋯ UPDATE", collection.name, query, updates);
+            console.debug(`${ANSI_ICON_REQUEST} UPDATE QUERY`, collection.name, query, updates);
             await super.updateQuery(collection, query, updates);
-            console.debug("✔ UPDATE", collection.name, query, updates);
+            console.debug(`${ANSI_ICON_SUCCESS} UPDATE QUERY`, collection.name, query, updates);
         }
         catch (reason) {
-            console.error("✘ UPDATE", collection.name, query, updates, reason);
+            console.error(`${ANSI_ICON_ERROR} UPDATE QUERY`, collection.name, query, updates, reason);
             throw reason;
         }
     }
     async deleteQuery(collection, query) {
         try {
-            console.debug("⋯ DELETE", collection.name, query);
+            console.debug(`${ANSI_ICON_REQUEST} DELETE QUERY`, collection.name, query);
             await super.deleteQuery(collection, query);
-            console.debug("✔ DELETE", collection.name, query);
+            console.debug(`${ANSI_ICON_SUCCESS} DELETE QUERY`, collection.name, query);
         }
         catch (reason) {
-            console.error("✘ DELETE", collection.name, query, reason);
+            console.error(`${ANSI_ICON_ERROR} DELETE QUERY`, collection.name, query, reason);
             throw reason;
         }
     }

package/package.json

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

package/util/ansi.d.ts

@@ -13,3 +13,8 @@ export declare const ANSI_UNDERLINE = "\u001B[4m";
 export declare const ANSI_STRIKE = "\u001B[9m";
 export declare const ANSI_INVERSE = "\u001B[7m";
 export declare const ANSI_RESET = "\u001B[0m";
+export declare const ANSI_ICON_WAITING = "\u001B[34m\u22EF\u001B[0m";
+export declare const ANSI_ICON_SUCCESS = "\u001B[32m\u2713\u001B[0m";
+export declare const ANSI_ICON_ERROR = "\u001B[31m\u2717\u001B[0m";
+export declare const ANSI_ICON_REQUEST = "\u001B[34m\u2192\u001B[0m";
+export declare const ANSI_ICON_RESPONSE = "\u001B[34m\u2190\u001B[0m";

package/util/ansi.js

@@ -16,3 +16,9 @@ export const ANSI_STRIKE = "\x1b[9m";
 export const ANSI_INVERSE = "\x1b[7m";
 // Reset.
 export const ANSI_RESET = "\x1b[0m";
+// Icons.
+export const ANSI_ICON_WAITING = "\x1b[34m⋯\x1b[0m"; // ⋯
+export const ANSI_ICON_SUCCESS = "\x1b[32m✓\x1b[0m"; // ✓
+export const ANSI_ICON_ERROR = "\x1b[31m✗\x1b[0m"; // ✗
+export const ANSI_ICON_REQUEST = "\x1b[34m→\x1b[0m"; // →
+export const ANSI_ICON_RESPONSE = "\x1b[34m←\x1b[0m"; // ←

package/util/log.d.ts

@@ -0,0 +1,7 @@
+/** biome-ignore-all lint/suspicious/noConsole: This file's purpose is to write logs. */
+/** Log a `Request` */
+export declare function logRequest(request: Request): Promise<void>;
+/** Log a `Response` to a `Request` */
+export declare function logRequestResponse(response: Response, request: Request): Promise<void>;
+/** Log an `Error` from a `Request` */
+export declare function logRequestError(reason: unknown, request: Request): void;

package/util/log.js

@@ -0,0 +1,15 @@
+/** biome-ignore-all lint/suspicious/noConsole: This file's purpose is to write logs. */
+import { ANSI_ICON_ERROR, ANSI_ICON_REQUEST, ANSI_ICON_RESPONSE } from "./ansi.js";
+import { debug, debugFullRequest, debugFullResponse, debugRequest } from "./debug.js";
+/** Log a `Request` */
+export async function logRequest(request) {
+    console.log(`${ANSI_ICON_REQUEST} ${await debugFullRequest(request)}`);
+}
+/** Log a `Response` to a `Request` */
+export async function logRequestResponse(response, request) {
+    console.log(`${ANSI_ICON_RESPONSE} ${debugRequest(request)}\n\n${await debugFullResponse(response)}`);
+}
+/** Log an `Error` from a `Request` */
+export function logRequestError(reason, request) {
+    console.error(`${ANSI_ICON_ERROR} ${debugRequest(request)}\n\n${debug(reason)}`);
+}