@dabble/patches 0.8.10 → 0.8.12

package/dist/client/IndexedDBStore.d.ts

@@ -13,6 +13,12 @@ import '../json-patch/types.js';
  * Can be used as a standalone store or as a shared database connection
  * for multiple algorithm-specific stores (OT, LWW).
  *
+ * Supports two modes:
+ * - **Managed mode** (pass a `dbName`): Opens and owns the database lifecycle.
+ * - **External mode** (pass an `IDBDatabase` or `Promise<IDBDatabase>`): Uses a
+ *   caller-provided database. The caller owns the lifecycle; `close()` detaches
+ *   without closing, `deleteDB()` is a no-op, and `setName()` throws.
+ *
  * Provides:
  * - Database lifecycle management (open, close, delete)
  * - Transaction helpers
@@ -26,29 +32,37 @@ declare class IndexedDBStore implements PatchesStore, BranchClientStore {
     protected db: IDBDatabase | null;
     protected dbName?: string;
     protected dbPromise: Deferred<IDBDatabase>;
+    protected external: boolean;
     /**
      * Signal emitted during database upgrade, allowing algorithm-specific stores
      * to create their object stores.
      */
     readonly onUpgrade: easy_signal.Signal<(db: IDBDatabase, oldVersion: number, transaction: IDBTransaction) => void>;
-    constructor(dbName?: string);
+    constructor(dbOrName?: string | IDBDatabase | Promise<IDBDatabase>);
     /**
-     * Creates shared object stores used by all sync algorithms.
+     * Creates shared object stores (docs, snapshots, branches) during database upgrade.
      */
-    protected createSharedStores(db: IDBDatabase, _oldVersion: number, _transaction: IDBTransaction): void;
+    static upgradeSharedStores(db: IDBDatabase, transaction: IDBTransaction): void;
     protected initDB(): Promise<void>;
     protected getDB(): Promise<IDBDatabase>;
     /**
      * Set the name of the database, loads a new database connection.
      * @param dbName - The new name of the database.
+     * @throws When using an externally-provided database.
      */
     setName(dbName: string): void;
     /**
      * Closes the database connection. After calling this method, the store
      * will no longer be usable. A new instance must be created to reopen
      * the database.
+     *
+     * When using an externally-provided database, this detaches from the
+     * database without closing it (the caller owns the lifecycle).
      */
     close(): Promise<void>;
+    /**
+     * Deletes the database. No-op when using an externally-provided database.
+     */
     deleteDB(): Promise<void>;
     transaction(storeNames: string[], mode: IDBTransactionMode): Promise<[IDBTransactionWrapper, ...IDBStoreWrapper[]]>;
     /**

package/dist/client/IndexedDBStore.js

@@ -7,25 +7,38 @@ class IndexedDBStore {
   db = null;
   dbName;
   dbPromise;
+  external;
   /**
    * Signal emitted during database upgrade, allowing algorithm-specific stores
    * to create their object stores.
    */
   onUpgrade = signal();
-  constructor(dbName) {
-    this.dbName = dbName;
+  constructor(dbOrName) {
     this.dbPromise = deferred();
-    this.onUpgrade((db, oldVersion, transaction) => {
-      this.createSharedStores(db, oldVersion, transaction);
-    });
-    if (this.dbName) {
-      this.initDB();
+    if (dbOrName != null && typeof dbOrName !== "string") {
+      this.external = true;
+      Promise.resolve(dbOrName).then(
+        (db) => {
+          this.db = db;
+          this.dbPromise.resolve(db);
+        },
+        (err) => this.dbPromise.reject(err)
+      );
+    } else {
+      this.external = false;
+      this.dbName = dbOrName;
+      this.onUpgrade((db, _oldVersion, transaction) => {
+        IndexedDBStore.upgradeSharedStores(db, transaction);
+      });
+      if (this.dbName) {
+        this.initDB();
+      }
     }
   }
   /**
-   * Creates shared object stores used by all sync algorithms.
+   * Creates shared object stores (docs, snapshots, branches) during database upgrade.
    */
-  createSharedStores(db, _oldVersion, _transaction) {
+  static upgradeSharedStores(db, transaction) {
     if (!db.objectStoreNames.contains("docs")) {
       const docsStore = db.createObjectStore("docs", { keyPath: "docId" });
       docsStore.createIndex("algorithm", "algorithm", { unique: false });
@@ -38,7 +51,7 @@ class IndexedDBStore {
       branchStore.createIndex("_docId", "_docId", { unique: false });
       branchStore.createIndex("_pending", "_pending", { unique: false });
     } else {
-      const branchStore = _transaction.objectStore("branches");
+      const branchStore = transaction.objectStore("branches");
       if (!branchStore.indexNames.contains("_pending")) {
         branchStore.createIndex("_pending", "_pending", { unique: false });
       }
@@ -65,8 +78,12 @@ class IndexedDBStore {
   /**
    * Set the name of the database, loads a new database connection.
    * @param dbName - The new name of the database.
+   * @throws When using an externally-provided database.
    */
   setName(dbName) {
+    if (this.external) {
+      throw new Error("Cannot set name on an externally-provided database");
+    }
     this.dbName = dbName;
     if (this.db) {
       this.db.close();
@@ -79,18 +96,27 @@ class IndexedDBStore {
    * Closes the database connection. After calling this method, the store
    * will no longer be usable. A new instance must be created to reopen
    * the database.
+   *
+   * When using an externally-provided database, this detaches from the
+   * database without closing it (the caller owns the lifecycle).
    */
   async close() {
+    if (!this.db) return;
     await this.dbPromise.promise;
     if (this.db) {
-      this.db.close();
+      if (!this.external) {
+        this.db.close();
+      }
       this.db = null;
       this.dbPromise = deferred();
       this.dbPromise.reject(new Error("Store has been closed"));
     }
   }
+  /**
+   * Deletes the database. No-op when using an externally-provided database.
+   */
   async deleteDB() {
-    if (!this.dbName) return;
+    if (this.external || !this.dbName) return;
     await this.close();
     await new Promise((resolve, reject) => {
       const request = indexedDB.deleteDatabase(this.dbName);

package/dist/client/LWWIndexedDBStore.d.ts

@@ -16,7 +16,7 @@ import './BranchClientStore.js';
  * - docs<{ docId: string; committedRev: number; deleted?: boolean }> (primary key: docId) [shared with OT]
  * - snapshots<{ docId: string; rev: number; state: any }> (primary key: docId) [shared with OT]
  * - committedOps<{ docId: string; op: string; path: string; from?: string; value?: any }> (primary key: [docId, path])
- * - pendingOps<{ docId: string; path: string; op: string; ts: number; value: any }> (primary key: [docId, path])
+ * - pendingOps<{ docId: string; path: string; op: string; ts: number; value: any; soft?: boolean }> (primary key: [docId, path])
  * - sendingChanges<{ docId: string; change: Change }> (primary key: docId)
  *
  * This store manages field-level operations for LWW conflict resolution:
@@ -32,7 +32,7 @@ declare class LWWIndexedDBStore implements LWWClientStore {
     /**
      * Creates LWW-specific object stores during database upgrade.
      */
-    protected createLWWStores(db: IDBDatabase): void;
+    static upgradeStores(db: IDBDatabase, _transaction: IDBTransaction): void;
     /**
      * List documents for the LWW algorithm.
      * Uses the algorithm index for efficient querying.

package/dist/client/LWWIndexedDBStore.js

@@ -12,19 +12,19 @@ import { blockable } from "../utils/concurrency.js";
 import { IDBStoreWrapper, IndexedDBStore } from "./IndexedDBStore.js";
 const SNAPSHOT_INTERVAL = 200;
 _getDoc_dec = [blockable], _saveDoc_dec = [blockable], _deleteDoc_dec = [blockable], _getPendingOps_dec = [blockable], _savePendingOps_dec = [blockable], _getSendingChange_dec = [blockable], _saveSendingChange_dec = [blockable], _confirmSendingChange_dec = [blockable], _applyServerChanges_dec = [blockable];
-class LWWIndexedDBStore {
+const _LWWIndexedDBStore = class _LWWIndexedDBStore {
   constructor(db) {
     __runInitializers(_init, 5, this);
     __publicField(this, "db");
     this.db = !db || typeof db === "string" ? new IndexedDBStore(db) : db;
-    this.db.onUpgrade((db2, _oldVersion, _transaction) => {
-      this.createLWWStores(db2);
+    this.db.onUpgrade((db2, _oldVersion, transaction) => {
+      _LWWIndexedDBStore.upgradeStores(db2, transaction);
     });
   }
   /**
    * Creates LWW-specific object stores during database upgrade.
    */
-  createLWWStores(db) {
+  static upgradeStores(db, _transaction) {
     if (!db.objectStoreNames.contains("committedOps")) {
       db.createObjectStore("committedOps", { keyPath: ["docId", "path"] });
     }
@@ -109,7 +109,8 @@ class LWWIndexedDBStore {
         op: op.op,
         path: op.path,
         value: op.value,
-        ts: op.ts
+        ts: op.ts,
+        ...op.soft ? { soft: true } : void 0
       }));
       state = applyPatch(state, pendingOps2, { partial: true });
     }
@@ -188,7 +189,8 @@ class LWWIndexedDBStore {
       op: op.op,
       path: op.path,
       value: op.value,
-      ts: op.ts
+      ts: op.ts,
+      ...op.soft ? { soft: true } : void 0
     }));
   }
   async savePendingOps(docId, ops, pathsToDelete) {
@@ -211,7 +213,8 @@ class LWWIndexedDBStore {
           path: op.path,
           op: op.op,
           ts: op.ts ?? Date.now(),
-          value: op.value
+          value: op.value,
+          ...op.soft ? { soft: true } : void 0
         })
       )
     );
@@ -285,7 +288,8 @@ class LWWIndexedDBStore {
       op: op.op,
       path: op.path,
       value: op.value,
-      ts: op.ts
+      ts: op.ts,
+      ...op.soft ? { soft: true } : void 0
     }));
     return [createChange(baseRev, baseRev + 1, opsArray)];
   }
@@ -312,18 +316,19 @@ class LWWIndexedDBStore {
     await snapshots.put({ docId, state, rev });
     await this.deleteFieldsForDoc(committedOps, docId);
   }
-}
+};
 _init = __decoratorStart(null);
-__decorateElement(_init, 1, "getDoc", _getDoc_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "saveDoc", _saveDoc_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "deleteDoc", _deleteDoc_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "getPendingOps", _getPendingOps_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "savePendingOps", _savePendingOps_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "getSendingChange", _getSendingChange_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "saveSendingChange", _saveSendingChange_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "confirmSendingChange", _confirmSendingChange_dec, LWWIndexedDBStore);
-__decorateElement(_init, 1, "applyServerChanges", _applyServerChanges_dec, LWWIndexedDBStore);
-__decoratorMetadata(_init, LWWIndexedDBStore);
+__decorateElement(_init, 1, "getDoc", _getDoc_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "saveDoc", _saveDoc_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "deleteDoc", _deleteDoc_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "getPendingOps", _getPendingOps_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "savePendingOps", _savePendingOps_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "getSendingChange", _getSendingChange_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "saveSendingChange", _saveSendingChange_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "confirmSendingChange", _confirmSendingChange_dec, _LWWIndexedDBStore);
+__decorateElement(_init, 1, "applyServerChanges", _applyServerChanges_dec, _LWWIndexedDBStore);
+__decoratorMetadata(_init, _LWWIndexedDBStore);
+let LWWIndexedDBStore = _LWWIndexedDBStore;
 export {
   LWWIndexedDBStore
 };

package/dist/client/OTIndexedDBStore.d.ts

@@ -33,7 +33,7 @@ declare class OTIndexedDBStore implements OTClientStore {
     /**
      * Creates OT-specific object stores during database upgrade.
      */
-    protected createOTStores(db: IDBDatabase): void;
+    static upgradeStores(db: IDBDatabase, _transaction: IDBTransaction): void;
     /**
      * List documents for the OT algorithm.
      * Uses the algorithm index for efficient querying.

package/dist/client/OTIndexedDBStore.js

@@ -11,19 +11,19 @@ import { blockable } from "../utils/concurrency.js";
 import { IndexedDBStore } from "./IndexedDBStore.js";
 const SNAPSHOT_INTERVAL = 200;
 _getDoc_dec = [blockable], _deleteDoc_dec = [blockable], _saveDoc_dec = [blockable], _savePendingChanges_dec = [blockable], _getPendingChanges_dec = [blockable], _listChanges_dec = [blockable], _applyServerChanges_dec = [blockable];
-class OTIndexedDBStore {
+const _OTIndexedDBStore = class _OTIndexedDBStore {
   constructor(db) {
     __runInitializers(_init, 5, this);
     __publicField(this, "db");
     this.db = !db || typeof db === "string" ? new IndexedDBStore(db) : db;
-    this.db.onUpgrade((db2, _oldVersion, _transaction) => {
-      this.createOTStores(db2);
+    this.db.onUpgrade((db2, _oldVersion, transaction) => {
+      _OTIndexedDBStore.upgradeStores(db2, transaction);
     });
   }
   /**
    * Creates OT-specific object stores during database upgrade.
    */
-  createOTStores(db) {
+  static upgradeStores(db, _transaction) {
     if (!db.objectStoreNames.contains("committedChanges")) {
       db.createObjectStore("committedChanges", { keyPath: ["docId", "rev"] });
     }
@@ -207,16 +207,17 @@ class OTIndexedDBStore {
     );
     await tx.complete();
   }
-}
+};
 _init = __decoratorStart(null);
-__decorateElement(_init, 1, "getDoc", _getDoc_dec, OTIndexedDBStore);
-__decorateElement(_init, 1, "deleteDoc", _deleteDoc_dec, OTIndexedDBStore);
-__decorateElement(_init, 1, "saveDoc", _saveDoc_dec, OTIndexedDBStore);
-__decorateElement(_init, 1, "savePendingChanges", _savePendingChanges_dec, OTIndexedDBStore);
-__decorateElement(_init, 1, "getPendingChanges", _getPendingChanges_dec, OTIndexedDBStore);
-__decorateElement(_init, 1, "listChanges", _listChanges_dec, OTIndexedDBStore);
-__decorateElement(_init, 1, "applyServerChanges", _applyServerChanges_dec, OTIndexedDBStore);
-__decoratorMetadata(_init, OTIndexedDBStore);
+__decorateElement(_init, 1, "getDoc", _getDoc_dec, _OTIndexedDBStore);
+__decorateElement(_init, 1, "deleteDoc", _deleteDoc_dec, _OTIndexedDBStore);
+__decorateElement(_init, 1, "saveDoc", _saveDoc_dec, _OTIndexedDBStore);
+__decorateElement(_init, 1, "savePendingChanges", _savePendingChanges_dec, _OTIndexedDBStore);
+__decorateElement(_init, 1, "getPendingChanges", _getPendingChanges_dec, _OTIndexedDBStore);
+__decorateElement(_init, 1, "listChanges", _listChanges_dec, _OTIndexedDBStore);
+__decorateElement(_init, 1, "applyServerChanges", _applyServerChanges_dec, _OTIndexedDBStore);
+__decoratorMetadata(_init, _OTIndexedDBStore);
+let OTIndexedDBStore = _OTIndexedDBStore;
 export {
   OTIndexedDBStore
 };

package/dist/client/PatchesBranchClient.d.ts

@@ -1,7 +1,7 @@
 import { Store } from 'easy-signal';
 import { SizeCalculator } from '../algorithms/ot/shared/changeBatching.js';
 import { BranchAPI } from '../net/protocol/types.js';
-import { Branch, ListBranchesOptions, CreateBranchMetadata } from '../types.js';
+import { Branch, ListBranchesOptions, CreateBranchMetadata, EditableBranchMetadata } from '../types.js';
 import { BranchClientStore } from './BranchClientStore.js';
 import { Patches } from './Patches.js';
 import { AlgorithmName } from './PatchesStore.js';
@@ -64,6 +64,10 @@ declare class PatchesBranchClient {
      * When `initialState` is omitted, the branch is created directly via the API.
      */
     createBranch(rev: number, metadata?: CreateBranchMetadata, initialState?: any): Promise<string>;
+    /**
+     * Update branch metadata (e.g. name).
+     */
+    updateBranch(branchId: string, metadata: EditableBranchMetadata): Promise<void>;
     /**
      * Delete a branch.
      * The API implementation handles tombstones (offline store) or direct deletion (online).

package/dist/client/PatchesBranchClient.js

@@ -61,6 +61,13 @@ class PatchesBranchClient {
     await this.listBranches();
     return branchId;
   }
+  /**
+   * Update branch metadata (e.g. name).
+   */
+  async updateBranch(branchId, metadata) {
+    await this.api.updateBranch(branchId, metadata);
+    this.branches.state = this.branches.state.map((b) => b.id === branchId ? { ...b, ...metadata } : b);
+  }
   /**
    * Delete a branch.
    * The API implementation handles tombstones (offline store) or direct deletion (online).

package/dist/client/factories.d.ts

@@ -69,5 +69,20 @@ declare function createMultiAlgorithmPatches(options?: MultiAlgorithmFactoryOpti
  * Both algorithms share the same IndexedDB database with unified stores.
  */
 declare function createMultiAlgorithmIndexedDBPatches(options: MultiAlgorithmIndexedDBFactoryOptions): Patches;
+/**
+ * Creates a Patches instance with both OT and LWW algorithms using an externally-managed
+ * IDBDatabase. The caller is responsible for opening the database and calling
+ * `upgradePatchesDB()` during `onupgradeneeded` to create the required stores.
+ *
+ * Use this when you want to host Patches stores inside your own IndexedDB database
+ * rather than having Patches open a separate one.
+ */
+declare function createMultiAlgorithmExternalDBPatches(db: IDBDatabase | Promise<IDBDatabase>, options?: MultiAlgorithmFactoryOptions): Patches;
+/**
+ * Creates all Patches object stores in an externally-managed database.
+ * Call this from your `onupgradeneeded` handler when hosting Patches stores
+ * inside your own IndexedDB database.
+ */
+declare function upgradePatchesDB(db: IDBDatabase, transaction: IDBTransaction): void;
 
-export { type IndexedDBFactoryOptions, type MultiAlgorithmFactoryOptions, type MultiAlgorithmIndexedDBFactoryOptions, type PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches };
+export { type IndexedDBFactoryOptions, type MultiAlgorithmFactoryOptions, type MultiAlgorithmIndexedDBFactoryOptions, type PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmExternalDBPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches, upgradePatchesDB };

package/dist/client/factories.js

@@ -72,11 +72,31 @@ function createMultiAlgorithmIndexedDBPatches(options) {
     docOptions: options.docOptions
   });
 }
+function createMultiAlgorithmExternalDBPatches(db, options = {}) {
+  const baseStore = new IndexedDBStore(db);
+  const otStore = new OTIndexedDBStore(baseStore);
+  const lwwStore = new LWWIndexedDBStore(baseStore);
+  const otAlgorithm = new OTAlgorithm(otStore, options.docOptions);
+  const lwwAlgorithm = new LWWAlgorithm(lwwStore);
+  return new Patches({
+    algorithms: { ot: otAlgorithm, lww: lwwAlgorithm },
+    defaultAlgorithm: options.defaultAlgorithm ?? "ot",
+    metadata: options.metadata,
+    docOptions: options.docOptions
+  });
+}
+function upgradePatchesDB(db, transaction) {
+  IndexedDBStore.upgradeSharedStores(db, transaction);
+  OTIndexedDBStore.upgradeStores(db, transaction);
+  LWWIndexedDBStore.upgradeStores(db, transaction);
+}
 export {
   createLWWIndexedDBPatches,
   createLWWPatches,
+  createMultiAlgorithmExternalDBPatches,
   createMultiAlgorithmIndexedDBPatches,
   createMultiAlgorithmPatches,
   createOTIndexedDBPatches,
-  createOTPatches
+  createOTPatches,
+  upgradePatchesDB
 };

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
 export { B as BaseDoc, O as OTDoc, P as PatchesDoc, a as PatchesDocOptions } from '../BaseDoc-BT18xPxU.js';
-export { IndexedDBFactoryOptions, MultiAlgorithmFactoryOptions, MultiAlgorithmIndexedDBFactoryOptions, PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches } from './factories.js';
+export { IndexedDBFactoryOptions, MultiAlgorithmFactoryOptions, MultiAlgorithmIndexedDBFactoryOptions, PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmExternalDBPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches, upgradePatchesDB } from './factories.js';
 export { IDBStoreWrapper, IDBTransactionWrapper, IndexedDBStore } from './IndexedDBStore.js';
 export { OTIndexedDBStore } from './OTIndexedDBStore.js';
 export { LWWIndexedDBStore } from './LWWIndexedDBStore.js';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Delta } from '@dabble/delta';
 export { B as BaseDoc, O as OTDoc, P as PatchesDoc, a as PatchesDocOptions } from './BaseDoc-BT18xPxU.js';
-export { IndexedDBFactoryOptions, MultiAlgorithmFactoryOptions, MultiAlgorithmIndexedDBFactoryOptions, PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches } from './client/factories.js';
+export { IndexedDBFactoryOptions, MultiAlgorithmFactoryOptions, MultiAlgorithmIndexedDBFactoryOptions, PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmExternalDBPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches, upgradePatchesDB } from './client/factories.js';
 export { IDBStoreWrapper, IDBTransactionWrapper, IndexedDBStore } from './client/IndexedDBStore.js';
 export { OTIndexedDBStore } from './client/OTIndexedDBStore.js';
 export { LWWIndexedDBStore } from './client/LWWIndexedDBStore.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {