@org-quicko/silo-client 1.0.1 → 1.1.1

package/README.md

@@ -8,7 +8,8 @@ an environment holds collections, and a collection holds entries.
 npm install @org-quicko/silo-client
 ```
 
-Runs on Node 18+, Bun, Deno, browsers and workers. It has no dependencies.
+Runs on Node 18+, Bun, Deno, browsers and workers. Its optional cache uses one
+runtime dependency, `@isaacs/ttlcache`.
 
 The examples below build moviespace, a small film database.
 
@@ -208,6 +209,7 @@ value you store. Storing the URL instead is what a later rename breaks.
 await poster.rename("arrival-2016.jpg")
 await poster.moveTo("posters/2016")
 await poster.setTags(["poster"])        // replaces the whole list
+await poster.replace(file)              // new bytes, same id, name and URL
 await poster.delete()                   // refused while an entry refers to it
 await poster.delete({ force: true })
 
@@ -217,6 +219,12 @@ usage.total                             // the true count
 usage.visible                           // how many of them this key may see
 ```
 
+`replace` swaps the file behind an asset. The id, the reference, the name and
+the URL all stay, so every entry that refers to it shows the new file and none
+of them is rewritten. The new file must keep the same extension. It needs the
+`media:replace` claim, and `entries:update` on each scope that refers to the
+asset.
+
 Folders, and a bulk delete that takes up to 100 ids:
 
 ```ts
@@ -312,6 +320,46 @@ await movies.get(id, { timeoutMilliseconds: 2_000 })
 Nothing is retried for you. A retried `POST` creates a second entry, and only
 the caller knows whether a call was safe to repeat.
 
+## Optional read cache
+
+Reads go to the server unless you enable caching. Choose a positive finite
+integer TTL in milliseconds. It starts when a response is stored and does
+not reset on a hit. `maxEntries` is optional; set it to bound memory use in a
+long-running client. When full, the soonest-expiring entry is removed first.
+
+```ts
+const silo = new Silo({
+  url: "https://cms.moviespace.com",
+  cache: { ttlMilliseconds: 5_000, maxEntries: 100 },
+})
+const movies = silo.scope("moviespace", "prod").collection<Movie>("movies")
+
+await movies.get(id)                       // may use a cached response
+await movies.get(id, { cache: "bypass" })  // fetch without reading or storing
+await movies.get(id, { cache: "refresh" }) // fetch and store on success
+silo.cache.clear()                         // after a change made elsewhere
+```
+
+Only successful GET JSON responses are cached, with separate entries for
+different URLs, queries and headers, including API keys. Returned objects
+are independent copies. A failed refresh leaves the existing cache unchanged.
+Your writes clear the shared cache before dispatch and after settlement,
+including failures. Pending reads cannot refill it after a clear or overwrite
+a newer read. `health()` always bypasses; `MediaAsset.refresh()` refreshes by
+default and accepts an explicit bypass. Modes do nothing when caching is off.
+
+`withKey()` and `withUrl()` share the cache. To share it explicitly, pass
+`cache: otherClient.cache`, or construct `new SiloCache({ ttlMilliseconds: 5000 })`.
+The facade exposes only `enabled`, `size` and `clear()`. Sharing preserves
+isolation by URL and headers. If a custom fetch adds authentication or changes
+the destination, include that context in the client's URL/headers or bypass
+caching.
+
+The cache lives in the tab, worker or process. Changes made elsewhere can
+remain hidden until expiry or a fresh read. Infinite TTLs are unsupported;
+`maxEntries` defaults to unlimited and may be `Infinity`. On Deno, an active
+expiry timer can keep the process alive; call `clear()` when finished.
+
 ## Anonymous reads
 
 A key is optional. Without one you reach the collections whose schema does not

package/dist/cache/cache-mode.d.cts

@@ -0,0 +1,2 @@
+/** Controls an enabled cache for one read. */
+export type CacheMode = "bypass" | "refresh";

package/dist/cache/cache-mode.d.ts

@@ -0,0 +1,2 @@
+/** Controls an enabled cache for one read. */
+export type CacheMode = "bypass" | "refresh";

package/dist/cache/response-cache.d.cts

@@ -0,0 +1,16 @@
+import type { SiloCacheOptions } from "./silo-cache-options.cjs";
+interface CachedResponse {
+    body: unknown;
+}
+/** The cache's values and pending-read tickets. */
+export declare class ResponseCache {
+    #private;
+    constructor(options: SiloCacheOptions);
+    get size(): number;
+    get(key: string): CachedResponse | undefined;
+    set(key: string, ticket: symbol, body: unknown): void;
+    start(key: string): symbol;
+    finish(key: string, ticket: symbol): void;
+    clear(): void;
+}
+export {};

package/dist/cache/response-cache.d.ts

@@ -0,0 +1,16 @@
+import type { SiloCacheOptions } from "./silo-cache-options.js";
+interface CachedResponse {
+    body: unknown;
+}
+/** The cache's values and pending-read tickets. */
+export declare class ResponseCache {
+    #private;
+    constructor(options: SiloCacheOptions);
+    get size(): number;
+    get(key: string): CachedResponse | undefined;
+    set(key: string, ticket: symbol, body: unknown): void;
+    start(key: string): symbol;
+    finish(key: string, ticket: symbol): void;
+    clear(): void;
+}
+export {};

package/dist/cache/silo-cache-options.d.cts

@@ -0,0 +1,7 @@
+/** Bounds an opt-in in-memory read cache. */
+export interface SiloCacheOptions {
+    /** Positive finite safe integer in milliseconds, counted from storage. */
+    ttlMilliseconds: number;
+    /** Positive safe integer or Infinity. Omit for no count limit. */
+    maxEntries?: number;
+}

package/dist/cache/silo-cache-options.d.ts

@@ -0,0 +1,7 @@
+/** Bounds an opt-in in-memory read cache. */
+export interface SiloCacheOptions {
+    /** Positive finite safe integer in milliseconds, counted from storage. */
+    ttlMilliseconds: number;
+    /** Positive safe integer or Infinity. Omit for no count limit. */
+    maxEntries?: number;
+}

package/dist/cache/silo-cache.d.cts

@@ -0,0 +1,11 @@
+import type { SiloCacheOptions } from "./silo-cache-options.cjs";
+/** An optional, in-memory cache shared by one or more `Silo` instances. */
+export declare class SiloCache {
+    #private;
+    constructor(options?: SiloCacheOptions);
+    get enabled(): boolean;
+    get size(): number;
+    /** Clears responses and prevents pending reads from storing their results. */
+    clear(): void;
+    private static validate;
+}

package/dist/cache/silo-cache.d.ts

@@ -0,0 +1,11 @@
+import type { SiloCacheOptions } from "./silo-cache-options.js";
+/** An optional, in-memory cache shared by one or more `Silo` instances. */
+export declare class SiloCache {
+    #private;
+    constructor(options?: SiloCacheOptions);
+    get enabled(): boolean;
+    get size(): number;
+    /** Clears responses and prevents pending reads from storing their results. */
+    clear(): void;
+    private static validate;
+}

package/dist/errors/network-error.d.cts

@@ -8,4 +8,9 @@ export declare class NetworkError extends Error {
     readonly method: string;
     readonly path: string;
     constructor(method: string, path: string, cause: unknown);
+    /** What `fetch` rejected with, in the message itself: a `cause` chain is
+     * printed by some consoles and by no log line, and "never reached the
+     * server" alone reads as a verdict on the network when the fault can be the
+     * call. */
+    private static reason;
 }

package/dist/errors/network-error.d.ts

@@ -8,4 +8,9 @@ export declare class NetworkError extends Error {
     readonly method: string;
     readonly path: string;
     constructor(method: string, path: string, cause: unknown);
+    /** What `fetch` rejected with, in the message itself: a `cause` chain is
+     * printed by some consoles and by no log line, and "never reached the
+     * server" alone reads as a verdict on the network when the fault can be the
+     * call. */
+    private static reason;
 }