@org-quicko/silo-client 1.0.1 → 1.1.1

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,
@@ -181,6 +182,9 @@ class ApiPath {
   static mediaAssetUsages(id) {
     return `${ApiPath.mediaAsset(id)}/usages`;
   }
+  static mediaAssetContent(id) {
+    return `${ApiPath.mediaAsset(id)}/content`;
+  }
   static mediaBulkDelete() {
     return "/api/media/delete";
   }
@@ -227,6 +231,22 @@ class MediaAssetMapper {
   }
 }
 
+// src/media/media-file.ts
+class MediaFile {
+  static toBlob(bytes, contentType) {
+    if (bytes instanceof Blob)
+      return bytes;
+    return new Blob([bytes], contentType ? { type: contentType } : undefined);
+  }
+  static nameOf(input, explicit) {
+    if (explicit)
+      return explicit;
+    if (input instanceof File && input.name)
+      return input.name;
+    throw new Error("media: a Blob has no filename — pass { filename } explicitly");
+  }
+}
+
 // src/media/media-reference.ts
 class MediaReference {
   static Scheme = "silo://media/";
@@ -286,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;
   }
@@ -306,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);
@@ -322,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);
   }
 }
 
@@ -388,6 +411,22 @@ class MediaAsset {
   async setTags(tags, options) {
     return this.patch({ tags: [...tags] }, options);
   }
+  async replace(input, options) {
+    const form = new FormData;
+    if (input instanceof Blob) {
+      form.set("file", input, MediaFile.nameOf(input, options?.filename));
+    } else {
+      form.set("file", MediaFile.toBlob(input.bytes, input.contentType), input.filename);
+    }
+    const payload = await this.transport.upload({
+      method: "POST",
+      path: ApiPath.mediaAssetContent(this.id),
+      signal: options?.signal,
+      timeoutMilliseconds: options?.timeoutMilliseconds
+    }, form);
+    this.record = MediaAssetMapper.toRecord(payload);
+    return this;
+  }
   async delete(options) {
     await this.transport.empty({
       method: "DELETE",
@@ -405,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;
@@ -467,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;
   }
@@ -509,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({
@@ -531,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);
   }
 }
 
@@ -621,11 +665,11 @@ class Media {
     let options;
     if (input instanceof Blob) {
       const fileOptions = second ?? {};
-      form.set("file", input, Media.filenameOf(input, fileOptions.filename));
+      form.set("file", input, MediaFile.nameOf(input, fileOptions.filename));
       folder = fileOptions.folder;
       options = third ?? fileOptions;
     } else {
-      form.set("file", Media.toBlob(input.bytes, input.contentType), input.filename);
+      form.set("file", MediaFile.toBlob(input.bytes, input.contentType), input.filename);
       folder = input.folder;
       options = second;
     }
@@ -654,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));
   }
@@ -663,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;
   }
@@ -693,18 +739,6 @@ class Media {
       sort: query.sort
     };
   }
-  static toBlob(bytes, contentType) {
-    if (bytes instanceof Blob)
-      return bytes;
-    return new Blob([bytes], contentType ? { type: contentType } : undefined);
-  }
-  static filenameOf(input, explicit) {
-    if (explicit)
-      return explicit;
-    if (input instanceof File && input.name)
-      return input.name;
-    throw new Error("media upload: a Blob has no filename — pass { filename } explicitly");
-  }
 }
 
 // src/variables/variable.ts
@@ -1388,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;
@@ -1568,12 +1728,19 @@ class NetworkError extends Error {
   method;
   path;
   constructor(method, path, cause) {
-    super(`network error on ${method} ${path}: the request never reached the server`, { cause });
+    super(`network error on ${method} ${path}: the request never reached the server${NetworkError.reason(cause)}`, { cause });
     this.name = "NetworkError";
     this.method = method;
     this.path = path;
     Object.setPrototypeOf(this, NetworkError.prototype);
   }
+  static reason(cause) {
+    if (cause instanceof Error && cause.message)
+      return ` (${cause.message})`;
+    if (typeof cause === "string" && cause)
+      return ` (${cause})`;
+    return "";
+  }
 }
 
 // src/errors/timeout-error.ts
@@ -1675,60 +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 = options.fetch ?? 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)}`;
+  async execute(request, prepared, form) {
+    const abortSignals = new AbortSignals(request.signal, request.timeoutMilliseconds ?? this.#timeoutMilliseconds);
+    const sendRequest = this.#fetchFunction;
     let response;
     try {
-      response = await this.fetchFunction(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) {
@@ -1742,44 +1929,44 @@ 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(/\/+$/, "");
   }
+  static resolveFetch(fetchFunction) {
+    if (fetchFunction)
+      return fetchFunction;
+    if (typeof globalThis.fetch !== "function") {
+      throw new Error("this runtime has no global fetch: pass one as SiloOptions.fetch");
+    }
+    return globalThis.fetch.bind(globalThis);
+  }
 }
 
 // src/silo.ts
 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);
   }
@@ -1797,7 +1984,8 @@ class Silo {
       method: "GET",
       path: ApiPath.health(),
       signal: options?.signal,
-      timeoutMilliseconds: options?.timeoutMilliseconds
+      timeoutMilliseconds: options?.timeoutMilliseconds,
+      cache: "bypass"
     });
   }
   withKey(key) {
@@ -1847,6 +2035,7 @@ class RouteInventory {
     "PATCH /api/media/:id",
     "DELETE /api/media/:id",
     "GET /api/media/:id/usages",
+    "POST /api/media/:id/content",
     "POST /api/media/delete",
     "GET /api/media/folders",
     "POST /api/media/folders",
@@ -1857,6 +2046,7 @@ class RouteInventory {
     "GET /api/session": "key introspection, an operator surface",
     "GET /api/keys": "keys and claims are an operator surface",
     "POST /api/keys": "keys and claims are an operator surface",
+    "PATCH /api/keys/:id": "keys and claims are an operator surface",
     "DELETE /api/keys/:id": "keys and claims are an operator surface",
     "GET /api/audit": "an operator surface",
     "GET /api/observability": "an operator surface",

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";
@@ -71,6 +74,7 @@ export type { MediaAssetRecord } from "./media/media-asset.cjs";
 export type { MediaQuery } from "./media/media-query.cjs";
 export type { MediaUsage } from "./media/media-usage.cjs";
 export type { MediaUsageQuery } from "./media/media-usage-page.cjs";
+export type { MediaReplace, MediaReplaceBytes, MediaReplaceOptions } from "./media/media-replace.cjs";
 export type { MediaUpload, MediaUploadBytes, MediaUploadFileOptions } from "./media/media-upload.cjs";
 export type { MediaDeleteFailure } from "./media/media-delete-failure.cjs";
 export type { MediaDeleteOptions } from "./media/media-delete-options.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";
@@ -71,6 +74,7 @@ export type { MediaAssetRecord } from "./media/media-asset.js";
 export type { MediaQuery } from "./media/media-query.js";
 export type { MediaUsage } from "./media/media-usage.js";
 export type { MediaUsageQuery } from "./media/media-usage-page.js";
+export type { MediaReplace, MediaReplaceBytes, MediaReplaceOptions } from "./media/media-replace.js";
 export type { MediaUpload, MediaUploadBytes, MediaUploadFileOptions } from "./media/media-upload.js";
 export type { MediaDeleteFailure } from "./media/media-delete-failure.js";
 export type { MediaDeleteOptions } from "./media/media-delete-options.js";