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

package/dist/client.d.ts

@@ -1,6 +1,13 @@
 import type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
 import { type AppendAuthor } from "@drakkar.software/starfish-protocol";
 import type { StarfishClientOptions } from "./types.js";
+/**
+ * Whether a {@link PullResult} was served from the offline read-through cache
+ * (the transport was unreachable) rather than a live server response. Used by
+ * {@link SyncManager} to surface a `stale` flag to the UI without treating a
+ * cache hit as proof the server is reachable.
+ */
+export declare function pullWasFromCache(result: PullResult): boolean;
 /** The storage `documentKey` for a push `path`: the path with the `/push/`
  *  action prefix stripped (the namespace lives only in the URL). The author
  *  signature binds to this key. */
@@ -76,12 +83,20 @@ export declare class StarfishClient {
     private readonly namespace?;
     private readonly capProvider?;
     private readonly fetch;
+    private readonly cache?;
+    private readonly cacheMaxAgeMs?;
     /**
      * Installed client-side plugins. Currently stored as inert data; no
      * hooks fire yet. Extensions can inspect this list if needed.
      */
     readonly plugins: ReadonlyArray<import("./types.js").ClientPlugin>;
     constructor(options: StarfishClientOptions);
+    /**
+     * 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}.
+     */
+    private tagFromCache;
     /**
      * 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
@@ -142,6 +157,18 @@ export declare class StarfishClient {
     pull(path: string, options: PullOptions): Promise<PullResult>;
     /** Pull an append-only collection. Extracts and returns `data[appendField]` as `T[]`. */
     pull<T = unknown>(path: string, options: AppendPullOptions): Promise<T[]>;
+    /**
+     * 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.
+     */
+    peekCache(path: string): Promise<PullResult | null>;
+    /** 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). */
+    private readCache;
     /**
      * Pull several documents in one round-trip via `/batch/pull`. `collections` is
      * the list of distinct collection names; `opts.params` supplies, per collection,

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;
@@ -470,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;
   }
@@ -480,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();
@@ -1671,6 +1775,7 @@ export {
   isServiceWorkerSupported,
   noopSyncLogger,
   pruneTombstones,
+  pullWasFromCache,
   registerBackgroundSync,
   registerServiceWorker,
   revocationListCanonicalSigningInput,