@org-quicko/silo-client 1.0.1 → 1.1.1

package/dist/media/media-replace.d.cts

@@ -0,0 +1,17 @@
+import type { RequestOptions } from "../request-options.cjs";
+/** The fully-described replacement: raw bytes plus the name whose extension
+ *  the server checks against the one the asset already has. No `folder` — a
+ *  replace changes bytes and nothing else about where the asset sits. */
+export interface MediaReplaceBytes {
+    bytes: Uint8Array | ArrayBuffer | Blob;
+    filename: string;
+    contentType?: string;
+}
+/** The filename to read when the input carries none — a `File` has `.name`,
+ *  a bare `Blob` does not, and the extension is what the server checks. */
+export interface MediaReplaceOptions extends RequestOptions {
+    filename?: string;
+}
+/** `MediaAsset.replace()`'s input: a fully-described replacement, or a
+ *  runtime `File`/`Blob`. */
+export type MediaReplace = MediaReplaceBytes | File | Blob;

package/dist/media/media-replace.d.ts

@@ -0,0 +1,17 @@
+import type { RequestOptions } from "../request-options.js";
+/** The fully-described replacement: raw bytes plus the name whose extension
+ *  the server checks against the one the asset already has. No `folder` — a
+ *  replace changes bytes and nothing else about where the asset sits. */
+export interface MediaReplaceBytes {
+    bytes: Uint8Array | ArrayBuffer | Blob;
+    filename: string;
+    contentType?: string;
+}
+/** The filename to read when the input carries none — a `File` has `.name`,
+ *  a bare `Blob` does not, and the extension is what the server checks. */
+export interface MediaReplaceOptions extends RequestOptions {
+    filename?: string;
+}
+/** `MediaAsset.replace()`'s input: a fully-described replacement, or a
+ *  runtime `File`/`Blob`. */
+export type MediaReplace = MediaReplaceBytes | File | Blob;

package/dist/media/media-usage-page.d.cts

@@ -20,6 +20,7 @@ export interface MediaUsageQuery {
 export declare class MediaUsagePage extends Page<MediaUsage> {
     private readonly transport;
     private readonly assetId;
+    private readonly requestOptions;
     readonly visible: number;
     readonly visibleCapped: boolean;
     private constructor();

package/dist/media/media-usage-page.d.ts

@@ -20,6 +20,7 @@ export interface MediaUsageQuery {
 export declare class MediaUsagePage extends Page<MediaUsage> {
     private readonly transport;
     private readonly assetId;
+    private readonly requestOptions;
     readonly visible: number;
     readonly visibleCapped: boolean;
     private constructor();

package/dist/media/media.d.cts

@@ -30,8 +30,4 @@ export declare class Media {
      * per-id outcomes live in the report, not in a thrown error. */
     deleteMany(ids: readonly string[], options?: MediaDeleteOptions): Promise<MediaDeleteReport>;
     private static toWireQuery;
-    private static toBlob;
-    /** A `File` carries its own name; a bare `Blob` does not, and uploading it
-     * as "blob" is worse than refusing outright. */
-    private static filenameOf;
 }

package/dist/media/media.d.ts

@@ -30,8 +30,4 @@ export declare class Media {
      * per-id outcomes live in the report, not in a thrown error. */
     deleteMany(ids: readonly string[], options?: MediaDeleteOptions): Promise<MediaDeleteReport>;
     private static toWireQuery;
-    private static toBlob;
-    /** A `File` carries its own name; a bare `Blob` does not, and uploading it
-     * as "blob" is worse than refusing outright. */
-    private static filenameOf;
 }

package/dist/request-options.d.cts

@@ -1,3 +1,4 @@
+import type { CacheMode } from "./cache/cache-mode.cjs";
 /**
  * The one cancellation convention on every call: the last parameter of
  * every method in the client. A per-call value wins over the client's own
@@ -6,4 +7,6 @@
 export interface RequestOptions {
     signal?: AbortSignal;
     timeoutMilliseconds?: number;
+    /** `bypass` skips lookup and storage; `refresh` fetches and stores. Ignored on writes and disabled caches. */
+    cache?: CacheMode;
 }

package/dist/request-options.d.ts

@@ -1,3 +1,4 @@
+import type { CacheMode } from "./cache/cache-mode.js";
 /**
  * The one cancellation convention on every call: the last parameter of
  * every method in the client. A per-call value wins over the client's own
@@ -6,4 +7,6 @@
 export interface RequestOptions {
     signal?: AbortSignal;
     timeoutMilliseconds?: number;
+    /** `bypass` skips lookup and storage; `refresh` fetches and stores. Ignored on writes and disabled caches. */
+    cache?: CacheMode;
 }

package/dist/silo-options.d.cts

@@ -1,4 +1,6 @@
 import type { FetchFunction } from "./transport/fetch-function.cjs";
+import type { SiloCache } from "./cache/silo-cache.cjs";
+import type { SiloCacheOptions } from "./cache/silo-cache-options.cjs";
 /**
  * Everything `new Silo(...)` accepts. Only `url` is required: a key is
  * optional because anonymous reads are legal.
@@ -9,4 +11,6 @@ export interface SiloOptions {
     timeoutMilliseconds?: number;
     headers?: Record<string, string>;
     fetch?: FetchFunction;
+    /** Enable read caching or share an existing cache. Omit to disable. */
+    cache?: SiloCacheOptions | SiloCache;
 }

package/dist/silo-options.d.ts

@@ -1,4 +1,6 @@
 import type { FetchFunction } from "./transport/fetch-function.js";
+import type { SiloCache } from "./cache/silo-cache.js";
+import type { SiloCacheOptions } from "./cache/silo-cache-options.js";
 /**
  * Everything `new Silo(...)` accepts. Only `url` is required: a key is
  * optional because anonymous reads are legal.
@@ -9,4 +11,6 @@ export interface SiloOptions {
     timeoutMilliseconds?: number;
     headers?: Record<string, string>;
     fetch?: FetchFunction;
+    /** Enable read caching or share an existing cache. Omit to disable. */
+    cache?: SiloCacheOptions | SiloCache;
 }

package/dist/silo.d.cts

@@ -7,6 +7,7 @@ import type { EnvironmentHandle } from "./scope/environment-handle.cjs";
 import type { SearchPage } from "./search/search-page.cjs";
 import type { SearchQuery } from "./search/search-query.cjs";
 import type { SiloOptions } from "./silo-options.cjs";
+import { SiloCache } from "./cache/silo-cache.cjs";
 /**
  * One silo instance. Navigate it the way the API is shaped:
  * `silo.project("acme").environment("prod").collection<Post>("posts")`.
@@ -20,6 +21,8 @@ export declare class Silo {
     readonly projects: Projects;
     /** The media catalog. Media is instance-global, so it takes no scope. */
     readonly media: Media;
+    /** This instance's optional read cache. */
+    readonly cache: SiloCache;
     private readonly options;
     private readonly transport;
     constructor(options: SiloOptions);

package/dist/silo.d.ts

@@ -7,6 +7,7 @@ import type { EnvironmentHandle } from "./scope/environment-handle.js";
 import type { SearchPage } from "./search/search-page.js";
 import type { SearchQuery } from "./search/search-query.js";
 import type { SiloOptions } from "./silo-options.js";
+import { SiloCache } from "./cache/silo-cache.js";
 /**
  * One silo instance. Navigate it the way the API is shaped:
  * `silo.project("acme").environment("prod").collection<Post>("posts")`.
@@ -20,6 +21,8 @@ export declare class Silo {
     readonly projects: Projects;
     /** The media catalog. Media is instance-global, so it takes no scope. */
     readonly media: Media;
+    /** This instance's optional read cache. */
+    readonly cache: SiloCache;
     private readonly options;
     private readonly transport;
     constructor(options: SiloOptions);

package/dist/transport/api-path.d.cts

@@ -31,6 +31,7 @@ export declare class ApiPath {
     static mediaExtensions(): string;
     static mediaAsset(id: string): string;
     static mediaAssetUsages(id: string): string;
+    static mediaAssetContent(id: string): string;
     static mediaBulkDelete(): string;
     static mediaFolders(): string;
 }

package/dist/transport/api-path.d.ts

@@ -31,6 +31,7 @@ export declare class ApiPath {
     static mediaExtensions(): string;
     static mediaAsset(id: string): string;
     static mediaAssetUsages(id: string): string;
+    static mediaAssetContent(id: string): string;
     static mediaBulkDelete(): string;
     static mediaFolders(): string;
 }

package/dist/transport/caching-transport.d.cts

@@ -0,0 +1,14 @@
+import { ResponseCache } from "../cache/response-cache.cjs";
+import type { FetchTransport } from "./fetch-transport.cjs";
+import type { TransportRequest } from "./transport-request.cjs";
+import type { Transport } from "./transport.cjs";
+/** Adds opt-in GET JSON caching to the fetch transport. */
+export declare class CachingTransport implements Transport {
+    #private;
+    constructor(fetchTransport: FetchTransport, cache: ResponseCache);
+    json<T>(request: TransportRequest): Promise<T>;
+    empty(request: TransportRequest): Promise<void>;
+    stream(request: TransportRequest): Promise<ReadableStream<Uint8Array> | null>;
+    upload<T>(request: TransportRequest, form: FormData): Promise<T>;
+    private write;
+}

package/dist/transport/caching-transport.d.ts

@@ -0,0 +1,14 @@
+import { ResponseCache } from "../cache/response-cache.js";
+import type { FetchTransport } from "./fetch-transport.js";
+import type { TransportRequest } from "./transport-request.js";
+import type { Transport } from "./transport.js";
+/** Adds opt-in GET JSON caching to the fetch transport. */
+export declare class CachingTransport implements Transport {
+    #private;
+    constructor(fetchTransport: FetchTransport, cache: ResponseCache);
+    json<T>(request: TransportRequest): Promise<T>;
+    empty(request: TransportRequest): Promise<void>;
+    stream(request: TransportRequest): Promise<ReadableStream<Uint8Array> | null>;
+    upload<T>(request: TransportRequest, form: FormData): Promise<T>;
+    private write;
+}

package/dist/transport/fetch-transport.d.cts

@@ -0,0 +1,31 @@
+import { NetworkError } from "../errors/network-error.cjs";
+import type { FetchFunction } from "./fetch-function.cjs";
+import type { PreparedTransportRequest } from "./prepared-transport-request.cjs";
+import type { TransportRequest } from "./transport-request.cjs";
+import type { Transport } from "./transport.cjs";
+export interface FetchTransportOptions {
+    url: string;
+    key?: string;
+    headers?: Record<string, string>;
+    timeoutMilliseconds?: number;
+    fetch?: FetchFunction;
+}
+/** The fetch-backed implementation behind the internal transport seam. */
+export declare class FetchTransport implements Transport {
+    #private;
+    constructor(options: FetchTransportOptions);
+    json<T>(request: TransportRequest): Promise<T>;
+    jsonPrepared<T>(request: TransportRequest, prepared: PreparedTransportRequest): Promise<T>;
+    empty(request: TransportRequest): Promise<void>;
+    stream(request: TransportRequest): Promise<ReadableStream<Uint8Array> | null>;
+    upload<T>(request: TransportRequest, form: FormData): Promise<T>;
+    withKey(key: string | undefined): FetchTransport;
+    withUrl(url: string): FetchTransport;
+    prepare(request: TransportRequest, form?: FormData): PreparedTransportRequest;
+    preparationFailure(request: TransportRequest, caught: unknown): NetworkError;
+    private snapshot;
+    private execute;
+    private transportFailure;
+    private static normalizeUrl;
+    private static resolveFetch;
+}

package/dist/transport/fetch-transport.d.ts

@@ -0,0 +1,31 @@
+import { NetworkError } from "../errors/network-error.js";
+import type { FetchFunction } from "./fetch-function.js";
+import type { PreparedTransportRequest } from "./prepared-transport-request.js";
+import type { TransportRequest } from "./transport-request.js";
+import type { Transport } from "./transport.js";
+export interface FetchTransportOptions {
+    url: string;
+    key?: string;
+    headers?: Record<string, string>;
+    timeoutMilliseconds?: number;
+    fetch?: FetchFunction;
+}
+/** The fetch-backed implementation behind the internal transport seam. */
+export declare class FetchTransport implements Transport {
+    #private;
+    constructor(options: FetchTransportOptions);
+    json<T>(request: TransportRequest): Promise<T>;
+    jsonPrepared<T>(request: TransportRequest, prepared: PreparedTransportRequest): Promise<T>;
+    empty(request: TransportRequest): Promise<void>;
+    stream(request: TransportRequest): Promise<ReadableStream<Uint8Array> | null>;
+    upload<T>(request: TransportRequest, form: FormData): Promise<T>;
+    withKey(key: string | undefined): FetchTransport;
+    withUrl(url: string): FetchTransport;
+    prepare(request: TransportRequest, form?: FormData): PreparedTransportRequest;
+    preparationFailure(request: TransportRequest, caught: unknown): NetworkError;
+    private snapshot;
+    private execute;
+    private transportFailure;
+    private static normalizeUrl;
+    private static resolveFetch;
+}

package/dist/transport/prepared-transport-request.d.cts

@@ -0,0 +1,6 @@
+/** One request after its final URL, headers and body have been prepared. */
+export interface PreparedTransportRequest {
+    url: string;
+    headers: Headers;
+    body: BodyInit | undefined;
+}

package/dist/transport/prepared-transport-request.d.ts

@@ -0,0 +1,6 @@
+/** One request after its final URL, headers and body have been prepared. */
+export interface PreparedTransportRequest {
+    url: string;
+    headers: Headers;
+    body: BodyInit | undefined;
+}

package/dist/transport/transport-request.d.cts

@@ -1,3 +1,4 @@
+import type { CacheMode } from "../cache/cache-mode.cjs";
 /** One query parameter's value. An object (the `filter` AST) is JSON-encoded
  *  by {@link QueryString}; everything else is stringified. */
 export type TransportQueryValue = string | number | boolean | object | undefined;
@@ -15,4 +16,5 @@ export interface TransportRequest {
     headers?: Record<string, string>;
     signal?: AbortSignal;
     timeoutMilliseconds?: number;
+    cache?: CacheMode;
 }

package/dist/transport/transport-request.d.ts

@@ -1,3 +1,4 @@
+import type { CacheMode } from "../cache/cache-mode.js";
 /** One query parameter's value. An object (the `filter` AST) is JSON-encoded
  *  by {@link QueryString}; everything else is stringified. */
 export type TransportQueryValue = string | number | boolean | object | undefined;
@@ -15,4 +16,5 @@ export interface TransportRequest {
     headers?: Record<string, string>;
     signal?: AbortSignal;
     timeoutMilliseconds?: number;
+    cache?: CacheMode;
 }

package/dist/transport/transport.d.cts

@@ -1,45 +1,8 @@
-import type { FetchFunction } from "./fetch-function.cjs";
 import type { TransportRequest } from "./transport-request.cjs";
-/** What `Transport` needs to construct — its own options shape. */
-export interface TransportOptions {
-    url: string;
-    key?: string;
-    headers?: Record<string, string>;
-    timeoutMilliseconds?: number;
-    fetch?: FetchFunction;
-}
-/**
- * The one place a request is made. Sends `Authorization: Bearer <key>`
- * when a key is set and nothing when it is not, since anonymous reads are
- * legal. A `fetch` rejection becomes `NetworkError`; an abort from the
- * caller's own signal becomes `RequestAbortedError`; an abort from the
- * deadline becomes `TimeoutError` — `AbortSignals` is what tells the three
- * apart.
- */
-export declare class Transport {
-    private readonly url;
-    private readonly key;
-    private readonly headers;
-    private readonly timeoutMilliseconds;
-    private readonly fetchFunction;
-    constructor(options: TransportOptions);
+/** The requests every client handle issues. */
+export interface Transport {
     json<T>(request: TransportRequest): Promise<T>;
-    /** For a `204` response: decodes it, and discards the result. */
     empty(request: TransportRequest): Promise<void>;
     stream(request: TransportRequest): Promise<ReadableStream<Uint8Array> | null>;
-    /** Multipart upload. Never sets `Content-Type` by hand — the runtime sets
-     * it, boundary included, from the `FormData` body. */
     upload<T>(request: TransportRequest, form: FormData): Promise<T>;
-    /** A new `Transport` reading a different key, sharing everything else. */
-    withKey(key: string | undefined): Transport;
-    /** A new `Transport` reading a different base URL, sharing everything
-     * else. */
-    withUrl(url: string): Transport;
-    private snapshot;
-    private execute;
-    /** Distinguishes why `fetch` itself failed: the deadline, the caller's own
-     * signal, or the request never landing at all. */
-    private transportFailure;
-    private buildHeaders;
-    private static normalizeUrl;
 }

package/dist/transport/transport.d.ts

@@ -1,45 +1,8 @@
-import type { FetchFunction } from "./fetch-function.js";
 import type { TransportRequest } from "./transport-request.js";
-/** What `Transport` needs to construct — its own options shape. */
-export interface TransportOptions {
-    url: string;
-    key?: string;
-    headers?: Record<string, string>;
-    timeoutMilliseconds?: number;
-    fetch?: FetchFunction;
-}
-/**
- * The one place a request is made. Sends `Authorization: Bearer <key>`
- * when a key is set and nothing when it is not, since anonymous reads are
- * legal. A `fetch` rejection becomes `NetworkError`; an abort from the
- * caller's own signal becomes `RequestAbortedError`; an abort from the
- * deadline becomes `TimeoutError` — `AbortSignals` is what tells the three
- * apart.
- */
-export declare class Transport {
-    private readonly url;
-    private readonly key;
-    private readonly headers;
-    private readonly timeoutMilliseconds;
-    private readonly fetchFunction;
-    constructor(options: TransportOptions);
+/** The requests every client handle issues. */
+export interface Transport {
     json<T>(request: TransportRequest): Promise<T>;
-    /** For a `204` response: decodes it, and discards the result. */
     empty(request: TransportRequest): Promise<void>;
     stream(request: TransportRequest): Promise<ReadableStream<Uint8Array> | null>;
-    /** Multipart upload. Never sets `Content-Type` by hand — the runtime sets
-     * it, boundary included, from the `FormData` body. */
     upload<T>(request: TransportRequest, form: FormData): Promise<T>;
-    /** A new `Transport` reading a different key, sharing everything else. */
-    withKey(key: string | undefined): Transport;
-    /** A new `Transport` reading a different base URL, sharing everything
-     * else. */
-    withUrl(url: string): Transport;
-    private snapshot;
-    private execute;
-    /** Distinguishes why `fetch` itself failed: the deadline, the caller's own
-     * signal, or the request never landing at all. */
-    private transportFailure;
-    private buildHeaders;
-    private static normalizeUrl;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@org-quicko/silo-client",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "A typed, object-oriented client for silo's HTTP API",
   "keywords": [
     "silo",
@@ -41,14 +41,17 @@
   },
   "scripts": {
     "build": "bun run build:esm && bun run build:cjs && bun run build:types",
-    "build:esm": "bun build src/index.ts --format=esm --outfile dist/index.js",
-    "build:cjs": "bun build src/index.ts --format=cjs --outfile dist/index.cjs",
+    "build:esm": "bun build src/index.ts --format=esm --packages=external --outfile dist/index.js",
+    "build:cjs": "bun build src/index.ts --format=cjs --packages=external --outfile dist/index.cjs",
     "build:types": "tsc -p tsconfig.build.json && bun run tools/emit-cts-types.ts",
     "test": "bun test",
     "test:packaged": "bun run tools/packaged-tests.ts",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
     "prepublishOnly": "bun run build"
   },
+  "dependencies": {
+    "@isaacs/ttlcache": "2.1.5"
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@silo/shared": "workspace:*",