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

package/dist/connect.d.ts

@@ -4335,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>;
 }
@@ -4348,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
  *
@@ -4399,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>;
     /**
@@ -6664,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 {
@@ -6754,9 +6780,10 @@ declare class VfsLimitError extends Error {
  *
  * 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`). That ordering is per namespace instance
- * only; nothing orders writes across tabs or devices - that would take a
- * compare-and-swap at the server.
+ * 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.
  */
 
 /**
@@ -6832,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.
      *
@@ -7121,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.
      *
@@ -7131,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
@@ -9018,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.2";
+declare const VERSION = "0.15.0-alpha.3";
 
 /**
  * The SDK's process-global logger.