@muhkoo/connect 0.15.0-alpha.1 → 0.15.0-alpha.3

package/dist/connect.d.ts

@@ -2463,7 +2463,7 @@ declare class ShardClient {
     private readonly pathPrefix;
     private readonly fetchFn;
     private readonly cache?;
-    /** Hashes waiting for the next batch, each with everyone awaiting it. */
+    /** Hashes waiting for the next batch, each with everyone awaiting it and its size if a caller gave it. */
     private pendingShards;
     private batchTimer;
     /** False once the server is known not to have the batch route. */
@@ -2496,8 +2496,13 @@ declare class ShardClient {
     /**
      * Fetch a shard by hash. Throws if the server returns a non-200; returns
      * `null` for 404 so callers can distinguish "missing" from "errored".
+     *
+     * `size`, the shard's byte length when known (a manifest's `shardSize`),
+     * lets concurrent reads be batched within what the server will send.
      */
-    getShard(hash: string): Promise<Uint8Array | null>;
+    getShard(hash: string, opts?: {
+        size?: number;
+    }): Promise<Uint8Array | null>;
     /**
      * Fetch from origin, COALESCING concurrent requests into one batch.
      *
@@ -2520,6 +2525,8 @@ declare class ShardClient {
     private fetchFromOrigin;
     /** Send one batch of whatever has accumulated, and settle those callers. */
     private flushShardBatch;
+    /** POST one batch and settle everyone waiting on it. Never throws. */
+    private sendShardBatch;
     /** Fetch a shard from origin. Returns `null` for 404 (or offline when a
      *  cache is present, so RS recovery can proceed); throws otherwise. */
     private fetchOneFromOrigin;
@@ -4328,8 +4335,12 @@ declare class KvCache {
      * state but a fresh local write wins.
      */
     mergeRemote(commitment: string, fullKey: string, envelope: unknown | null, op: "set" | "delete", hlc?: string): Promise<void>;
-    /** Non-tombstoned full keys for a commitment (used for offline `list`). */
-    liveKeys(commitment: string): Promise<string[]>;
+    /**
+     * Non-tombstoned full keys for a commitment that start with `prefix` (all
+     * of them by default), for offline `list`. The store scans the key range
+     * `${commitment}|${prefix}`, so other collections are never read.
+     */
+    liveKeys(commitment: string, prefix?: string): Promise<string[]>;
     /** Queue a kv mutation for replay on reconnect. */
     enqueue(method: "set" | "delete", args: unknown, hlc: string, clientId: string): Promise<void>;
 }
@@ -4341,6 +4352,7 @@ declare class KvCache {
  *   await client.kv.set('todos', id, { title, completed })
  *   const todo = await client.kv.get('todos', id)
  *   const ids  = await client.kv.list('todos')
+ *   const keys = await client.kv.keys('todos/')   // full keys, any prefix
  *   await client.kv.delete('todos', id)
  *   const off  = client.kv.on('change', e => …)   // realtime, cross-device
  *
@@ -4392,8 +4404,23 @@ declare class KvNamespace {
     get<T = unknown>(collection: string, id: string): Promise<T | null>;
     /** Delete `collection`/`id`. Returns whether the key existed. */
     delete(collection: string, id: string): Promise<boolean>;
-    /** List the ids present in `collection`. */
+    /**
+     * List the ids present in `collection`. The server filters by
+     * `${collection}/` and pages; values are not fetched.
+     */
     list(collection: string): Promise<string[]>;
+    /**
+     * Every key in the signed-in user's personal space that starts with
+     * `prefix` (all of them when it is ""), as full keys: `todos/t1`, not
+     * `t1`. Values are not fetched. The personal space is shared by every
+     * app the user signs into, so expect keys you did not write: the VFS's
+     * `vfs/…`, version control's `vcs/…`, the SDK's own `chat-keys` and
+     * `space-keys/…`.
+     *
+     * The local `startsWith` filter stays on purpose: a server older than
+     * the key index ignores `prefix` and returns every key.
+     */
+    keys(prefix?: string): Promise<string[]>;
     /** Reserved — server-side query is deferred (see the overhaul plan). */
     query(_collection: string, _filter?: unknown): Promise<never>;
     /**
@@ -6657,8 +6684,14 @@ interface VfsStore {
     get(key: string): Promise<unknown | null>;
     put(key: string, value: unknown): Promise<void>;
     delete(key: string): Promise<void>;
-    /** Every key in the store — the personal space is shared, so this is NOT VFS-only. */
-    list(): Promise<string[]>;
+    /**
+     * Keys in the store that start with `prefix`, or every key without one.
+     * The personal space is shared, so this is NOT VFS-only. An implementation
+     * may ignore `prefix` and return more (the parameter is optional so that
+     * a store written for the old no-argument `list()` still fits), so callers
+     * filter what they get back.
+     */
+    list(prefix?: string): Promise<string[]>;
 }
 /** Raised when the master seed is not held, so the root key cannot be derived. */
 declare class VfsLockedError extends Error {
@@ -6737,11 +6770,20 @@ declare class VfsLimitError extends Error {
  * Every mutation is a read-modify-write of exactly ONE directory record, so a
  * write cannot leave the tree half-updated: either the parent names the new
  * child or it does not. Two tabs writing different directories never conflict;
- * two tabs writing the SAME directory resolve last-writer-wins at the personal
- * space, which carries an HLC per key. Orphaned records (a directory whose
- * parent entry lost the race) are unreachable rather than corrupting — they
- * cost storage until a future sweep, which is the trade this shape makes in
+ * two tabs (or devices) writing the SAME directory are last-writer-wins. A VFS
+ * write sends no HLC and the personal space has no compare-and-swap: it applies
+ * puts of one key in the order they arrive, so whichever arrives last is kept,
+ * and the other tab's edit is lost. Orphaned records (a directory whose parent
+ * entry lost the race) are unreachable rather than corrupting — they cost
+ * storage until a future sweep, which is the trade this shape makes in
  * exchange for single-record writes.
+ *
+ * Within ONE tab, writes of a record are queued and sent one at a time, in the
+ * order they were made, and a read that has to fetch a record waits for its
+ * write in flight (see `writing`). Every edit of a record is made to one
+ * in-memory copy of it, and that copy is what is written (see `mutate`). All
+ * of this is per namespace instance only; nothing orders writes across tabs
+ * or devices - that would take a compare-and-swap at the server.
  */
 
 /**
@@ -6817,8 +6859,25 @@ declare class VfsNamespace {
      * The file tree re-lists constantly while typing, and every miss is a
      * network round trip plus a decrypt. Invalidated precisely on write rather
      * than by TTL — a stale directory listing shows files that are not there.
+     *
+     * What a cached read resolves to is also THE copy of that record: the one
+     * every edit of it is made to, and the one written. See `mutate`.
      */
     private cache;
+    /**
+     * Bumped by `clearCache`, which is for a change of identity.
+     *
+     * A read or write begun before it can finish after it, and what it read
+     * or wrote belongs to whoever was signed in before. So every record
+     * carries the generation it was read under, and none goes into the cache,
+     * or is edited as the cache's copy, under another.
+     */
+    private generation;
+    /**
+     * The record each promise in `cache` resolved to, and each write in
+     * `writing` is sending: what `editable` finds without waiting.
+     */
+    private readonly copyOf;
     /**
      * The write of each directory record still in flight, by id.
      *
@@ -6828,7 +6887,9 @@ declare class VfsNamespace {
      * that is often the one sent first. Then the earlier write, sealed before
      * the later edit was made, undoes it. That is how a file deleted forever
      * from the Trash, while the move that put it there was still being
-     * written, came back. So each write waits for the one before it.
+     * written, came back. So each write waits for the one before it, and a
+     * read that has to fetch the record waits for its write too: see
+     * `openDirById`.
      */
     private readonly writing;
     private readonly historyLimit;
@@ -7052,8 +7113,11 @@ declare class VfsNamespace {
      * Delete metadata records no longer reachable from the root.
      *
      * These accumulate because every write touches exactly one record: if two
-     * tabs edit the same directory, last-writer-wins at the personal space can
-     * leave a child whose parent entry lost the race. Unreachable is harmless —
+     * tabs or devices edit the same directory, the personal space keeps
+     * whichever put arrives last (a VFS write sends no HLC, and the space
+     * applies puts of one key in arrival order), which can leave a child whose
+     * parent entry lost the race. The per-record write queue (`writing`) only
+     * orders writes within one tab. Unreachable is harmless —
      * it is invisible and undecryptable-by-nobody — but it costs storage, so
      * this reclaims it.
      *
@@ -7101,8 +7165,47 @@ declare class VfsNamespace {
      * aside in `hidden` instead: out of every read, but kept for the write.
      */
     private readRecord;
-    /** Apply an edit to a directory record and persist it. */
+    /**
+     * Apply an edit to a directory record and persist it.
+     *
+     * `dir` says which record - its id, key and path - and nothing more. The
+     * edit is made to THE copy of that record (see `editable`), which `dir`
+     * may no longer be, and that copy is what is written. Editing whichever
+     * copy the caller held let two copies of one record exist at once: an
+     * overwrite held its directory across storing the old version's
+     * history, a write of the directory failed meanwhile and dropped it from
+     * the cache, and a save that then read a second copy and stored it,
+     * successfully, was undone when the overwrite stored the first.
+     *
+     * So `edit` must take what it writes from the record it is given, not
+     * from anything read off `dir` before an await - and re-check whatever it
+     * relies on from then, throwing if another write changed it. Returning
+     * false writes nothing after all.
+     */
     private mutate;
+    /**
+     * The copy of `dir`'s record that edits are made to, if there is one
+     * without waiting: the one the cache holds, once read.
+     *
+     * Failing that, the one a write in flight is sending. The record was
+     * dropped from the cache - a change was reported, our own write's echo
+     * among them - and a read that came in since is waiting for that write,
+     * to answer with this very copy if it lands (see `openDirById`); if it
+     * fails, the write an edit now queues behind it carries the copy instead.
+     *
+     * Undefined when the record is not cached and nothing is writing it, or
+     * it is still being read: `reopen` waits for that. A record read before
+     * `clearCache` is edited as it is, as it always was. It is not the copy of
+     * anything the cache holds now, and must not be handed the next identity's.
+     */
+    private editable;
+    /**
+     * Read `dir`'s record - the cached read, or a fetch made once any write of
+     * it in flight has settled - and then find the copy edits are made to.
+     */
+    private reopen;
+    /** Make `dir` the cached copy of its record - unless the cache has been cleared since it was read. */
+    private adopt;
     /**
      * Seal a directory record as it stands NOW and put it in the store.
      *
@@ -7111,6 +7214,7 @@ declare class VfsNamespace {
      * then, its own included.
      */
     private writeRecord;
+    /** For `mkdir`: name a new, empty directory `path` in the one at `parentPath`. */
     private createDir;
     /**
      * Every directory record in a subtree, each once, opened - and nothing
@@ -8998,7 +9102,7 @@ declare function getId(row: {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-declare const VERSION = "0.15.0-alpha.1";
+declare const VERSION = "0.15.0-alpha.3";
 
 /**
  * The SDK's process-global logger.