@relayfile/sdk 0.9.6 → 0.10.1

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type CommitForkInput, type CommitForkResponse, type CreateForkInput, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type DeleteWebhookOptions, type DiscardForkInput, type EventFeedResponse, type ExportJsonResponse, type ExportOptions, type FileQueryResponse, type FileReadResponse, type FilesystemEvent, type GetEventsOptions, type GetAdminIngressStatusOptions, type GetAdminSyncStatusOptions, type GetOperationsOptions, type GetSyncDeadLettersOptions, type GetSyncIngressStatusOptions, type GetSyncStatusOptions, type GetWebhookDeadLettersOptions, type ListWebhooksOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type ResourceAtEventResult, type ReadFileInput, type QueryFilesOptions, type RegisterWebhookInput, type RegisterWebhookResponse, type Subscription, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type WebhookDeliveryDeadLetterFeedResponse, type WebhookSubscription, type AckWritebackInput, type AckWritebackResponse, type SweepWritebackDraftsInput, type SweepWritebackDraftsResponse, type ChangeEvent, type ChangeLogQueryResult, type ChangeStreamConnection, type ChangeStreamConnectionOptions, type SubscribeOptions } from "./types.js";
+import { type AdminIngressStatusResponse, type AdminSyncStatusResponse, type BulkWriteInput, type BulkWriteResponse, type BackendStatusResponse, type AckResponse, type CommitForkInput, type CommitForkResponse, type CreateForkInput, type DeleteFileInput, type DeadLetterItem, type DeadLetterFeedResponse, type DeleteWebhookOptions, type DiscardForkInput, type EventFeedResponse, type ExportJsonResponse, type ExportOptions, type FileQueryResponse, type FileReadResponse, type FilesystemEvent, type GetEventsOptions, type GetAdminIngressStatusOptions, type GetAdminSyncStatusOptions, type GetOperationsOptions, type GetSyncDeadLettersOptions, type GetSyncIngressStatusOptions, type GetSyncStatusOptions, type GetWebhookDeadLettersOptions, type ListWebhooksOptions, type ListTreeOptions, type OperationFeedResponse, type OperationStatusResponse, type QueuedResponse, type ResourceAtEventResult, type ReadFileInput, type QueryFilesOptions, type RegisterWebhookInput, type RegisterWebhookResponse, type RelayFileReadCacheOptions, type Subscription, type SyncIngressStatusResponse, type SyncStatusResponse, type TreeResponse, type WriteFileInput, type WriteQueuedResponse, type IngestWebhookInput, type WritebackItem, type WebhookDeliveryDeadLetterFeedResponse, type WebhookSubscription, type AckWritebackInput, type AckWritebackResponse, type SweepWritebackDraftsInput, type SweepWritebackDraftsResponse, type ChangeEvent, type ChangeLogQueryResult, type ChangeStreamConnection, type ChangeStreamConnectionOptions, type SubscribeOptions } from "./types.js";
 import type { ForkHandle } from "@relayfile/core";
 /**
  * Bearer token or token factory used for Relayfile API requests.
@@ -41,6 +41,12 @@ export interface RelayFileClientOptions {
     userAgent?: string;
     retry?: RelayFileRetryOptions;
     changeLog?: RelayFileChangeLogOptions;
+    /**
+     * Client-side file read cache with in-flight deduplication.
+     * Enabled by default. Set to `false` to disable.
+     * Active change streams automatically evict paths on remote mutations.
+     */
+    readCache?: false | RelayFileReadCacheOptions;
 }
 type WebSocketEventName = "event" | "error" | "open" | "close";
 type WebSocketHandlerMap = {

package/dist/client.js

@@ -17,6 +17,72 @@ const changeStreamManagers = new WeakMap();
 const changeLogCaches = new WeakMap();
 const changeLogSettings = new WeakMap();
 const pendingChangeHydrations = new WeakMap();
+const fileReadCaches = new WeakMap();
+const DEFAULT_READ_CACHE_TTL_MS = 5_000;
+const DEFAULT_READ_CACHE_MAX_ENTRIES = 500;
+class FileReadCache {
+    ttlMs;
+    maxEntries;
+    entries = new Map();
+    inFlight = new Map();
+    constructor(options) {
+        this.ttlMs = options?.ttlMs ?? DEFAULT_READ_CACHE_TTL_MS;
+        this.maxEntries = options?.maxEntries ?? DEFAULT_READ_CACHE_MAX_ENTRIES;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value) {
+        if (this.entries.size >= this.maxEntries && !this.entries.has(key)) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined) {
+                this.entries.delete(oldest);
+            }
+        }
+        this.entries.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    }
+    evict(workspaceId, path) {
+        this.entries.delete(`${workspaceId}:${path}`);
+        this.inFlight.delete(`${workspaceId}:${path}`);
+    }
+    getInFlight(key) {
+        return this.inFlight.get(key);
+    }
+    setInFlight(key, promise) {
+        this.inFlight.set(key, promise);
+        promise.then((result) => {
+            if (this.inFlight.get(key) === promise) {
+                this.inFlight.delete(key);
+                this.set(key, result);
+            }
+        }, () => {
+            if (this.inFlight.get(key) === promise) {
+                this.inFlight.delete(key);
+            }
+        });
+    }
+}
+function getFileReadCache(client) {
+    const cached = fileReadCaches.get(client);
+    if (cached !== undefined)
+        return cached;
+    return false;
+}
+function initFileReadCache(client, options) {
+    if (options.readCache === false) {
+        fileReadCaches.set(client, false);
+    }
+    else {
+        fileReadCaches.set(client, new FileReadCache(options.readCache));
+    }
+}
 function createM2NotImplementedError(feature) {
     const error = new Error(`M2_NOT_IMPLEMENTED: ${feature} is reserved for proactive runtime M2.`);
     error.name = "M2NotImplementedError";
@@ -473,6 +539,14 @@ class RelayFileChangeStreamManager {
             }
         });
         sync.on("event", (event) => {
+            // Evict the cached read when the server signals a mutation so stale
+            // content is never returned after a change event arrives.
+            if (event.type === "file.updated" || event.type === "file.created" || event.type === "file.deleted") {
+                const cacheOrFalse = getFileReadCache(this.client);
+                if (cacheOrFalse !== false) {
+                    cacheOrFalse.evict(this.workspaceId, event.path);
+                }
+            }
             for (const subscription of this.subscriptions) {
                 subscription.push(event);
             }
@@ -1037,6 +1111,7 @@ export class RelayFileClient {
         this.userAgent = options.userAgent;
         this.retryOptions = normalizeRetryOptions(options.retry);
         changeLogSettings.set(this, normalizeChangeLogOptions(options.changeLog));
+        initFileReadCache(this, options);
     }
     /**
      * Resolve the current access token via the configured token provider.
@@ -1085,14 +1160,30 @@ export class RelayFileClient {
                 signal
             }
             : workspaceOrInput;
+        const cacheRaw = getFileReadCache(this);
+        // Skip cache for fork-scoped reads (isolated state) and when cache is disabled.
+        const cache = cacheRaw !== false ? cacheRaw : undefined;
+        const cacheKey = (cache && !input.forkId) ? `${input.workspaceId}:${input.path}` : undefined;
+        if (cache && cacheKey) {
+            const hit = cache.get(cacheKey);
+            if (hit)
+                return hit;
+            const pending = cache.getInFlight(cacheKey);
+            if (pending)
+                return pending;
+        }
         const query = buildQuery({ path: input.path, forkId: input.forkId });
-        return this.request({
+        const fetch = this.request({
             method: "GET",
             path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/file${query}`,
             correlationId: input.correlationId,
             signal: input.signal,
             tokenOverride: input.token
         });
+        if (cache && cacheKey) {
+            cache.setInFlight(cacheKey, fetch);
+        }
+        return fetch;
     }
     async queryFiles(workspaceId, options = {}) {
         const params = new URLSearchParams();
@@ -1131,7 +1222,7 @@ export class RelayFileClient {
     async writeFile(input) {
         const { workspaceId, path, correlationId, baseRevision, content, contentType, encoding, contentIdentity, signal } = input;
         const query = buildQuery({ path, forkId: input.forkId });
-        return this.request({
+        const result = await this.request({
             method: "PUT",
             path: `/v1/workspaces/${encodeURIComponent(workspaceId)}/fs/file${query}`,
             correlationId,
@@ -1148,6 +1239,10 @@ export class RelayFileClient {
             },
             signal
         });
+        const cache = getFileReadCache(this);
+        if (cache !== false)
+            cache.evict(workspaceId, path);
+        return result;
     }
     async bulkWrite(input) {
         const query = buildQuery({ forkId: input.forkId });
@@ -1160,11 +1255,18 @@ export class RelayFileClient {
             },
             signal: input.signal
         });
-        return this.readPayload(response);
+        const result = await this.readPayload(response);
+        const cache = getFileReadCache(this);
+        if (cache !== false) {
+            for (const file of input.files) {
+                cache.evict(input.workspaceId, file.path);
+            }
+        }
+        return result;
     }
     async deleteFile(input) {
         const query = buildQuery({ path: input.path, forkId: input.forkId });
-        return this.request({
+        const result = await this.request({
             method: "DELETE",
             path: `/v1/workspaces/${encodeURIComponent(input.workspaceId)}/fs/file${query}`,
             correlationId: input.correlationId,
@@ -1173,6 +1275,10 @@ export class RelayFileClient {
             },
             signal: input.signal
         });
+        const cache = getFileReadCache(this);
+        if (cache !== false)
+            cache.evict(input.workspaceId, input.path);
+        return result;
     }
     async createFork(input) {
         const body = {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { RelayFileClient, DEFAULT_RELAYFILE_BASE_URL, type AccessTokenProvider, type RelayFileChangeLogOptions, type ConnectWebSocketOptions, type RelayFileClientOptions, type RelayFileRetryOptions, type WebSocketConnection } from "./client.js";
+export type { RelayFileReadCacheOptions } from "./types.js";
 export { RelayfileSetup, RELAYFILE_SDK_VERSION, WorkspaceHandle } from "./setup.js";
 export { type RelayfileCloudLoginOptions, type RelayfileCloudTokenSet, type RelayfileCloudTokenSetupOptions } from "./cloud-login.js";
 export { CloudAbortError, CloudApiError, CloudTimeoutError, InvalidLocalDirError, InvalidMountModeError, InvalidRemotePathError, IntegrationConnectionTimeoutError, MalformedCloudResponseError, MissingConnectionIdError, MountModeUnavailableError, MountReadyTimeoutError, MountSessionInputError, ProviderNotConnectedError, ProviderNotReadyError, RelayfileSetupError, UnknownProviderError } from "./setup-errors.js";

package/dist/types.d.ts

@@ -56,6 +56,12 @@ export interface ContentIdentity {
     key: string;
     ttlSeconds?: number;
 }
+export interface RelayFileReadCacheOptions {
+    /** Cache TTL in ms. Default: 5000. */
+    ttlMs?: number;
+    /** Max cached entries before LRU eviction. Default: 500. */
+    maxEntries?: number;
+}
 export interface FileReadResponse {
     path: string;
     revision: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.9.6",
+  "version": "0.10.1",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -59,15 +59,15 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.9.6",
+    "@relayfile/core": "0.10.1",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
   "optionalDependencies": {
-    "@relayfile/mount-darwin-arm64": "0.9.6",
-    "@relayfile/mount-darwin-x64": "0.9.6",
-    "@relayfile/mount-linux-arm64": "0.9.6",
-    "@relayfile/mount-linux-x64": "0.9.6"
+    "@relayfile/mount-darwin-arm64": "0.10.1",
+    "@relayfile/mount-darwin-x64": "0.10.1",
+    "@relayfile/mount-linux-arm64": "0.10.1",
+    "@relayfile/mount-linux-x64": "0.10.1"
   },
   "devDependencies": {
     "typescript": "^5.7.3",