@drakkar.software/starfish-client 3.0.0-alpha.13 → 3.0.0-alpha.16

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { stableStringify, computeHash } from "@drakkar.software/starfish-protoco
 export { buildRevocationList, revocationListCanonicalSigningInput } from "@drakkar.software/starfish-protocol";
 export type { RevocationList, RevocationEntry, RevokedSubject, BuildRevocationListOpts, } from "@drakkar.software/starfish-protocol";
 export type { PullResult, PushSuccess, PullKeyringProjection } from "@drakkar.software/starfish-protocol";
-export { StarfishClient } from "./client.js";
+export { StarfishClient, pullWasFromCache } from "./client.js";
 export type { BlobPullResult, BlobPushResult, AppendPullOptions, PullOptions, BatchPullOptions, BatchPullResult, BatchPullEntry, } from "./client.js";
 export { SyncManager, AbortError } from "./sync.js";
 export type { SyncManagerOptions, SyncSigner } from "./sync.js";
@@ -13,7 +13,7 @@ export type { AppendLogCursorOptions, AppendElement, AuthorVerifier, ElementErro
 export { ENCRYPTED_KEY } from "@drakkar.software/starfish-protocol";
 export type { Encryptor } from "@drakkar.software/starfish-protocol";
 export { ConflictError, StarfishHttpError, } from "./types.js";
-export type { StarfishClientOptions, StarfishCapProvider, ConflictResolver, ClientPlugin, } from "./types.js";
+export type { StarfishClientOptions, StarfishCapProvider, PullCache, ConflictResolver, ClientPlugin, } from "./types.js";
 export { consoleSyncLogger, noopSyncLogger, createMetricsCollector } from "./logger.js";
 export type { SyncLogger, SyncMetrics, MetricsCollector } from "./logger.js";
 export { createMigrator } from "./migrate.js";

package/dist/index.js

@@ -41,6 +41,13 @@ var StarfishHttpError = class extends Error {
 
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
+function pullCacheKey(pathAndQuery) {
+  const q = pathAndQuery.indexOf("?");
+  return q === -1 ? pathAndQuery : pathAndQuery.slice(0, q);
+}
+function pullWasFromCache(result) {
+  return result.fromCache === true;
+}
 function stripPushPrefix(path) {
   return path.startsWith(PUSH_PATH_PREFIX) ? path.slice(PUSH_PATH_PREFIX.length) : path;
 }
@@ -58,6 +65,8 @@ var StarfishClient = class {
   namespace;
   capProvider;
   fetch;
+  cache;
+  cacheMaxAgeMs;
   /**
    * Installed client-side plugins. Currently stored as inert data; no
    * hooks fire yet. Extensions can inspect this list if needed.
@@ -68,8 +77,19 @@ var StarfishClient = class {
     this.namespace = options.namespace || void 0;
     this.capProvider = options.capProvider;
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.cache = options.cache;
+    this.cacheMaxAgeMs = options.cacheMaxAgeMs;
     this.plugins = options.plugins ? [...options.plugins] : [];
   }
+  /**
+   * Mark a `PullResult` as having been served from the offline read-through
+   * cache (transport was unreachable). Non-enumerable so it doesn't leak into
+   * JSON / equality / re-caching; read via {@link pullWasFromCache}.
+   */
+  tagFromCache(result) {
+    Object.defineProperty(result, "fromCache", { value: true, enumerable: false });
+    return result;
+  }
   /**
    * Resolve the host portion of the URL the client will send to. The host
    * is folded into the signed canonical input as the `h` field so the
@@ -189,10 +209,20 @@ var StarfishClient = class {
     }
     const url = `${this.baseUrl}${pathAndQuery}`;
     const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
-    const res = await this.fetch(url, {
-      method: "GET",
-      headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
-    });
+    const cacheKey = this.cache && appendField === void 0 ? pullCacheKey(pathAndQuery) : void 0;
+    let res;
+    try {
+      res = await this.fetch(url, {
+        method: "GET",
+        headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+      });
+    } catch (err) {
+      if (cacheKey) {
+        const cached = await this.readCache(cacheKey);
+        if (cached) return cached;
+      }
+      throw err;
+    }
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
@@ -201,8 +231,46 @@ var StarfishClient = class {
       const list = result.data?.[appendField];
       return Array.isArray(list) ? list : [];
     }
+    if (cacheKey) {
+      const snapshot = {
+        data: result.data,
+        hash: result.hash,
+        timestamp: result.timestamp,
+        cachedAt: Date.now()
+      };
+      void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
+      });
+    }
     return result;
   }
+  /**
+   * Read the cached snapshot for a document `path` WITHOUT hitting the network —
+   * the basis for cache-first paint (seed the UI from the last-synced snapshot,
+   * then revalidate with a live {@link pull}). Returns the tagged `PullResult`,
+   * or null when no cache is configured / there's no entry. Namespacing matches
+   * {@link pull}, so the key lines up with whatever `pull` wrote.
+   */
+  async peekCache(path) {
+    if (!this.cache) return null;
+    return this.readCache(pullCacheKey(this.applyNamespace(path)));
+  }
+  /** Read + parse a cached pull snapshot, tagged {@link tagFromCache}. Returns
+   *  null on a miss or an unparseable blob (never throws — a corrupt cache entry
+   *  must not break a pull, just miss). */
+  async readCache(cacheKey) {
+    try {
+      const raw = await this.cache.get(cacheKey);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed.hash !== "string") return null;
+      if (this.cacheMaxAgeMs != null && Date.now() - (parsed.cachedAt ?? 0) > this.cacheMaxAgeMs) {
+        return null;
+      }
+      return this.tagFromCache({ data: parsed.data ?? {}, hash: parsed.hash, timestamp: parsed.timestamp ?? 0 });
+    } catch {
+      return null;
+    }
+  }
   /**
    * Pull several documents in one round-trip via `/batch/pull`. `collections` is
    * the list of distinct collection names; `opts.params` supplies, per collection,
@@ -430,6 +498,7 @@ var SyncManager = class {
   lastCheckpoint = 0;
   localData = {};
   aborted = false;
+  lastFromCache = false;
   constructor(options) {
     this.client = options.client;
     this.pullPath = options.pullPath;
@@ -451,6 +520,18 @@ var SyncManager = class {
   getData() {
     return { ...this.localData };
   }
+  /**
+   * Merge a remote snapshot with local (optimistic) data using this manager's
+   * conflict resolver — the same resolver the push-conflict path uses. A plain
+   * {@link pull} overwrites the store's data with the server snapshot, which
+   * would drop un-pushed local writes (they live only in the store, never in
+   * `localData` until a push succeeds). The zustand binding calls this on pull
+   * while the store is dirty so those writes survive. `local` wins by the same
+   * rules as a push conflict.
+   */
+  resolve(local, remote) {
+    return this.onConflict(local, remote);
+  }
   getHash() {
     return this.lastHash;
   }
@@ -458,6 +539,40 @@ var SyncManager = class {
   setHash(hash) {
     this.lastHash = hash;
   }
+  /**
+   * Whether the most recent {@link pull} (or {@link seedFromCache}) was served
+   * from the client's offline read-through cache rather than a live server
+   * response. The binding surfaces this as a `stale` flag so the UI can show an
+   * offline indicator without treating a cache hit as "reachable". Reset to
+   * false by the next successful network pull.
+   */
+  getLastPullFromCache() {
+    return this.lastFromCache;
+  }
+  /**
+   * Cache-first paint: seed `localData` from the client's read-through cache
+   * WITHOUT touching the network, decrypting in memory for E2E collections.
+   * Returns whether anything was seeded (false on a miss, an expired entry, or
+   * a decrypt failure — e.g. keyring skew). Call once on store creation before
+   * the initial live {@link pull}, which then supersedes the seeded snapshot.
+   * Requires the client to have been built with a `cache`.
+   */
+  async seedFromCache() {
+    if (this.aborted) return false;
+    const cached = await this.client.peekCache(this.pullPath);
+    if (!cached) return false;
+    let data;
+    try {
+      data = this.encryptor ? await this.encryptor.decrypt(cached.data) : cached.data;
+    } catch {
+      return false;
+    }
+    if (this.aborted) return false;
+    this.localData = data;
+    this.lastHash = cached.hash;
+    this.lastFromCache = true;
+    return true;
+  }
   getCheckpoint() {
     return this.lastCheckpoint;
   }
@@ -468,6 +583,7 @@ var SyncManager = class {
     try {
       const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
       if (this.aborted) throw new AbortError();
+      this.lastFromCache = pullWasFromCache(result);
       if (this.encryptor) {
         const decrypted = await this.encryptor.decrypt(result.data);
         if (this.aborted) throw new AbortError();
@@ -1659,6 +1775,7 @@ export {
   isServiceWorkerSupported,
   noopSyncLogger,
   pruneTombstones,
+  pullWasFromCache,
   registerBackgroundSync,
   registerServiceWorker,
   revocationListCanonicalSigningInput,