@org-quicko/silo-client 1.1.0 → 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.
 
@@ -319,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/index.cjs

@@ -47,6 +47,7 @@ __export(exports_src, {
   SortTerm: () => SortTerm,
   Sort: () => Sort,
   SiloError: () => SiloError,
+  SiloCache: () => SiloCache,
   Silo: () => Silo,
   SearchReach: () => SearchReach,
   SearchPage: () => SearchPage,
@@ -305,12 +306,14 @@ var DefaultUsageLimit = 50;
 class MediaUsagePage extends Page {
   transport;
   assetId;
+  requestOptions;
   visible;
   visibleCapped;
-  constructor(rows, total, visible, visibleCapped, window, transport, assetId) {
+  constructor(rows, total, visible, visibleCapped, window, transport, assetId, requestOptions) {
     super(rows, total, window);
     this.transport = transport;
     this.assetId = assetId;
+    this.requestOptions = requestOptions;
     this.visible = visible;
     this.visibleCapped = visibleCapped;
   }
@@ -325,11 +328,11 @@ class MediaUsagePage extends Page {
   }
   async next(options) {
     const window = this.windowForNext();
-    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, options) : null;
+    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, { ...this.requestOptions, ...options }) : null;
   }
   async previous(options) {
     const window = this.window.previous();
-    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, options) : null;
+    return window ? MediaUsagePage.loadWindow(this.transport, this.assetId, window, { ...this.requestOptions, ...options }) : null;
   }
   static load(transport, assetId, query, options) {
     const window = new PageWindow(query.limit ?? DefaultUsageLimit, query.offset ?? 0);
@@ -341,10 +344,11 @@ class MediaUsagePage extends Page {
       path: ApiPath.mediaAssetUsages(assetId),
       query: { limit: window.limit, offset: window.offset },
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     const mapped = MediaAssetMapper.toUsagePage(body);
-    return new MediaUsagePage(mapped.items, mapped.total, mapped.visible, mapped.visibleCapped, window, transport, assetId);
+    return new MediaUsagePage(mapped.items, mapped.total, mapped.visible, mapped.visibleCapped, window, transport, assetId, options);
   }
 }
 
@@ -440,7 +444,8 @@ class MediaAsset {
       method: "GET",
       path: ApiPath.mediaAsset(this.id),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache ?? "refresh"
     });
     this.record = MediaAssetMapper.toRecord(payload);
     return this;
@@ -502,7 +507,8 @@ class MediaFolders {
       method: "GET",
       path: ApiPath.mediaFolders(),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     return body.items;
   }
@@ -544,21 +550,23 @@ class MediaFolders {
 class MediaPage extends Page {
   transport;
   wireQuery;
-  constructor(rows, total, window, transport, wireQuery) {
+  requestOptions;
+  constructor(rows, total, window, transport, wireQuery, requestOptions) {
     super(rows, total, window);
     this.transport = transport;
     this.wireQuery = wireQuery;
+    this.requestOptions = requestOptions;
   }
   get files() {
     return this.rows;
   }
   async next(options) {
     const window = this.windowForNext();
-    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, options) : null;
+    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, { ...this.requestOptions, ...options }) : null;
   }
   async previous(options) {
     const window = this.window.previous();
-    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, options) : null;
+    return window ? MediaPage.loadWindow(this.transport, this.wireQuery, window, { ...this.requestOptions, ...options }) : null;
   }
   static async loadWindow(transport, wireQuery, window, options) {
     const body = await transport.json({
@@ -566,10 +574,11 @@ class MediaPage extends Page {
       path: ApiPath.media(),
       query: { ...wireQuery, limit: window.limit, offset: window.offset },
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     const rows = body.items.map((payload) => new MediaAsset(transport, MediaAssetMapper.toRecord(payload)));
-    return new MediaPage(rows, body.total, new PageWindow(body.limit, body.offset), transport, wireQuery);
+    return new MediaPage(rows, body.total, new PageWindow(body.limit, body.offset), transport, wireQuery, options);
   }
 }
 
@@ -689,7 +698,8 @@ class Media {
       method: "GET",
       path: ApiPath.mediaAsset(id),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     return new MediaAsset(this.transport, MediaAssetMapper.toRecord(payload));
   }
@@ -698,7 +708,8 @@ class Media {
       method: "GET",
       path: ApiPath.mediaExtensions(),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: options?.cache
     });
     return body.items;
   }
@@ -1411,6 +1422,132 @@ class Projects {
   }
 }
 
+// src/transport/caching-transport.ts
+class CachingTransport {
+  #fetchTransport;
+  #cache;
+  constructor(fetchTransport, cache) {
+    this.#fetchTransport = fetchTransport;
+    this.#cache = cache;
+  }
+  async json(request) {
+    if (request.method !== "GET")
+      return this.write(() => this.#fetchTransport.json(request));
+    if (request.cache === "bypass")
+      return this.#fetchTransport.json(request);
+    if (request.signal?.aborted)
+      throw new RequestAbortedError(request.method, request.path);
+    let prepared;
+    try {
+      prepared = this.#fetchTransport.prepare(request);
+    } catch (caught) {
+      throw this.#fetchTransport.preparationFailure(request, caught);
+    }
+    const key = JSON.stringify([prepared.url, [...prepared.headers]]);
+    if (request.cache !== "refresh") {
+      const cached = this.#cache.get(key);
+      if (cached)
+        return cached.body;
+    }
+    const ticket = this.#cache.start(key);
+    try {
+      const body = await this.#fetchTransport.jsonPrepared(request, prepared);
+      this.#cache.set(key, ticket, body);
+      return body;
+    } finally {
+      this.#cache.finish(key, ticket);
+    }
+  }
+  empty(request) {
+    return request.method === "GET" ? this.#fetchTransport.empty(request) : this.write(() => this.#fetchTransport.empty(request));
+  }
+  stream(request) {
+    return request.method === "GET" ? this.#fetchTransport.stream(request) : this.write(() => this.#fetchTransport.stream(request));
+  }
+  upload(request, form) {
+    return request.method === "GET" ? this.#fetchTransport.upload(request, form) : this.write(() => this.#fetchTransport.upload(request, form));
+  }
+  async write(dispatch) {
+    this.#cache.clear();
+    try {
+      return await dispatch();
+    } finally {
+      this.#cache.clear();
+    }
+  }
+}
+
+// src/cache/response-cache.ts
+var import_ttlcache = require("@isaacs/ttlcache");
+
+class ResponseCache {
+  #store;
+  #pending = new Map;
+  constructor(options) {
+    this.#store = new import_ttlcache.TTLCache({
+      ttl: options.ttlMilliseconds,
+      ...options.maxEntries === undefined || options.maxEntries === Infinity ? {} : { max: options.maxEntries },
+      checkAgeOnGet: true,
+      updateAgeOnGet: false
+    });
+  }
+  get size() {
+    return this.#store.size;
+  }
+  get(key) {
+    const cached = this.#store.get(key);
+    return cached === undefined ? undefined : { body: structuredClone(cached.body) };
+  }
+  set(key, ticket, body) {
+    if (this.#pending.get(key) !== ticket)
+      return;
+    this.#store.set(key, { body: structuredClone(body) });
+  }
+  start(key) {
+    const ticket = Symbol();
+    this.#pending.set(key, ticket);
+    return ticket;
+  }
+  finish(key, ticket) {
+    if (this.#pending.get(key) === ticket)
+      this.#pending.delete(key);
+  }
+  clear() {
+    this.#pending.clear();
+    this.#store.clear();
+  }
+}
+
+// src/cache/silo-cache.ts
+class SiloCache {
+  #responseCache;
+  constructor(options) {
+    if (options !== undefined)
+      SiloCache.validate(options);
+    this.#responseCache = options === undefined ? undefined : new ResponseCache(options);
+  }
+  get enabled() {
+    return this.#responseCache !== undefined;
+  }
+  get size() {
+    return this.#responseCache?.size ?? 0;
+  }
+  clear() {
+    this.#responseCache?.clear();
+  }
+  wrap(fetchTransport) {
+    return this.#responseCache ? new CachingTransport(fetchTransport, this.#responseCache) : fetchTransport;
+  }
+  static validate(options) {
+    if (!Number.isSafeInteger(options.ttlMilliseconds) || options.ttlMilliseconds <= 0) {
+      throw new TypeError("SiloOptions.cache.ttlMilliseconds must be a positive finite safe integer");
+    }
+    if (options.maxEntries !== undefined && options.maxEntries !== Infinity && (!Number.isSafeInteger(options.maxEntries) || options.maxEntries <= 0)) {
+      throw new TypeError("SiloOptions.cache.maxEntries must be a positive safe integer or Infinity");
+    }
+  }
+}
+
 // src/errors/silo-error.ts
 class SiloError extends Error {
   status;
@@ -1705,61 +1842,80 @@ class ResponseDecoder {
   }
 }
 
-// src/transport/transport.ts
-class Transport {
-  url;
-  key;
-  headers;
-  timeoutMilliseconds;
-  fetchFunction;
+// src/transport/fetch-transport.ts
+class FetchTransport {
+  #url;
+  #key;
+  #headers;
+  #timeoutMilliseconds;
+  #fetchFunction;
   constructor(options) {
-    this.url = Transport.normalizeUrl(options.url);
-    this.key = options.key;
-    this.headers = options.headers ?? {};
-    this.timeoutMilliseconds = options.timeoutMilliseconds;
-    this.fetchFunction = Transport.resolveFetch(options.fetch);
+    this.#url = FetchTransport.normalizeUrl(options.url);
+    this.#key = options.key;
+    this.#headers = options.headers ?? {};
+    this.#timeoutMilliseconds = options.timeoutMilliseconds;
+    this.#fetchFunction = FetchTransport.resolveFetch(options.fetch);
   }
   async json(request) {
     const response = await this.execute(request);
     return await ResponseDecoder.decode(response, request, true);
   }
+  async jsonPrepared(request, prepared) {
+    const response = await this.execute(request, prepared);
+    return await ResponseDecoder.decode(response, request, true);
+  }
   async empty(request) {
     const response = await this.execute(request);
     await ResponseDecoder.decode(response, request, false);
   }
   async stream(request) {
-    const response = await this.execute(request);
-    return response.body;
+    return (await this.execute(request)).body;
   }
   async upload(request, form) {
-    const response = await this.execute(request, form);
+    const response = await this.execute(request, undefined, form);
     return await ResponseDecoder.decode(response, request, true);
   }
   withKey(key) {
-    return new Transport({ ...this.snapshot(), key });
+    return new FetchTransport({ ...this.snapshot(), key });
   }
   withUrl(url) {
-    return new Transport({ ...this.snapshot(), url });
+    return new FetchTransport({ ...this.snapshot(), url });
+  }
+  prepare(request, form) {
+    const rawHeaders = { ...this.#headers, ...request.headers };
+    if (this.#key)
+      rawHeaders.Authorization = `Bearer ${this.#key}`;
+    if (!form && request.body !== undefined && !("Content-Type" in rawHeaders)) {
+      rawHeaders["Content-Type"] = "application/json";
+    }
+    return {
+      url: `${this.#url}${request.path}${QueryString.build(request.query)}`,
+      headers: new Headers(rawHeaders),
+      body: form ?? (request.body === undefined ? undefined : JSON.stringify(request.body))
+    };
+  }
+  preparationFailure(request, caught) {
+    return new NetworkError(request.method, request.path, caught);
   }
   snapshot() {
     return {
-      url: this.url,
-      key: this.key,
-      headers: this.headers,
-      timeoutMilliseconds: this.timeoutMilliseconds,
-      fetch: this.fetchFunction
+      url: this.#url,
+      key: this.#key,
+      headers: this.#headers,
+      timeoutMilliseconds: this.#timeoutMilliseconds,
+      fetch: this.#fetchFunction
     };
   }
-  async execute(request, form) {
-    const abortSignals = new AbortSignals(request.signal, request.timeoutMilliseconds ?? this.timeoutMilliseconds);
-    const url = `${this.url}${request.path}${QueryString.build(request.query)}`;
-    const sendRequest = this.fetchFunction;
+  async execute(request, prepared, form) {
+    const abortSignals = new AbortSignals(request.signal, request.timeoutMilliseconds ?? this.#timeoutMilliseconds);
+    const sendRequest = this.#fetchFunction;
     let response;
     try {
-      response = await sendRequest(url, {
+      const outbound = prepared ?? this.prepare(request, form);
+      response = await sendRequest(outbound.url, {
         method: request.method,
-        headers: this.buildHeaders(request, Boolean(form)),
-        body: form ?? (request.body === undefined ? undefined : JSON.stringify(request.body)),
+        headers: outbound.headers,
+        body: outbound.body,
         signal: abortSignals.signal
       });
     } catch (caught) {
@@ -1773,24 +1929,13 @@ class Transport {
     return response;
   }
   transportFailure(request, abortSignals, caught) {
-    const firedBy = abortSignals.firedBy();
-    if (firedBy === "timeout") {
-      return new TimeoutError(request.method, request.path, request.timeoutMilliseconds ?? this.timeoutMilliseconds ?? 0);
+    if (abortSignals.firedBy() === "timeout") {
+      return new TimeoutError(request.method, request.path, request.timeoutMilliseconds ?? this.#timeoutMilliseconds ?? 0);
     }
-    if (firedBy === "caller") {
+    if (abortSignals.firedBy() === "caller")
       return new RequestAbortedError(request.method, request.path);
-    }
     return new NetworkError(request.method, request.path, caught);
   }
-  buildHeaders(request, isUpload) {
-    const headers = { ...this.headers, ...request.headers };
-    if (this.key)
-      headers["Authorization"] = `Bearer ${this.key}`;
-    if (!isUpload && request.body !== undefined && !("Content-Type" in headers)) {
-      headers["Content-Type"] = "application/json";
-    }
-    return headers;
-  }
   static normalizeUrl(url) {
     return url.replace(/\/+$/, "");
   }
@@ -1808,17 +1953,20 @@ class Transport {
 class Silo {
   projects;
   media;
+  cache;
   options;
   transport;
   constructor(options) {
-    this.options = options;
-    this.transport = new Transport({
+    this.cache = options.cache instanceof SiloCache ? options.cache : new SiloCache(options.cache);
+    this.options = { ...options, cache: this.cache };
+    const fetchTransport = new FetchTransport({
       url: options.url,
       key: options.key,
       headers: options.headers,
       timeoutMilliseconds: options.timeoutMilliseconds,
       fetch: options.fetch
     });
+    this.transport = this.cache.wrap(fetchTransport);
     this.projects = new Projects(this.transport);
     this.media = new Media(this.transport);
   }
@@ -1836,7 +1984,8 @@ class Silo {
       method: "GET",
       path: ApiPath.health(),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: "bypass"
     });
   }
   withKey(key) {

package/dist/index.d.cts

@@ -5,7 +5,10 @@
  * change rather than a hand-built request.
  */
 export { Silo } from "./silo.cjs";
+export { SiloCache } from "./cache/silo-cache.cjs";
 export type { SiloOptions } from "./silo-options.cjs";
+export type { CacheMode } from "./cache/cache-mode.cjs";
+export type { SiloCacheOptions } from "./cache/silo-cache-options.cjs";
 export type { RequestOptions } from "./request-options.cjs";
 export type { FetchFunction } from "./transport/fetch-function.cjs";
 export { RouteInventory } from "./transport/route-inventory.cjs";

package/dist/index.d.ts

@@ -5,7 +5,10 @@
  * change rather than a hand-built request.
  */
 export { Silo } from "./silo.js";
+export { SiloCache } from "./cache/silo-cache.js";
 export type { SiloOptions } from "./silo-options.js";
+export type { CacheMode } from "./cache/cache-mode.js";
+export type { SiloCacheOptions } from "./cache/silo-cache-options.js";
 export type { RequestOptions } from "./request-options.js";
 export type { FetchFunction } from "./transport/fetch-function.js";
 export { RouteInventory } from "./transport/route-inventory.js";