tinybase 5.0.0-beta.24 → 5.0.0-beta.26

package/@types/mergeable-store/index.d.ts

@@ -6,6 +6,15 @@
  * The main entry point to this module is the createMergeableStore function,
  * which returns a new MergeableStore, a subtype of Store that can be merged
  * with another with deterministic results.
+ *
+ * Please be aware that a lot of the types and methods exposed by this module
+ * are used internally within TinyBase itself (in particular the Synchronizer
+ * framework). They're documented here, but mostly for interest, and it is
+ * generally assumed that they won't be called directly by applications.
+ *
+ * As an application developer, it's more likely that you will continue to use
+ * the main Store methods for reading, writing, and listening to data, and rely
+ * on Synchronizer instances to keep the data in step with other places.
  * @packageDocumentation
  * @module mergeable-store
  * @since v5.0.0
@@ -153,109 +162,663 @@ export type MergeableChanges = [
 ];
 
 /**
- * The MergeableStore type
+ * The MergeableStore type represents a Store that carries with it sufficient
+ * metadata to be able to be merged with another MergeableStore with
+ * deterministic results.
+ *
+ * This is the key data type used when you need TinyBase data to be cleanly
+ * synchronized or merged with data elsewhere on the system, or on another
+ * system. It acts as a Conflict-Free Replicated Data Type (CRDT) which allows
+ * deterministic disambiguation of how changes to different instances should be
+ * merged.
+ *
+ * Please be aware that a lot of the methods exposed by this interface are used
+ * internally within TinyBase itself (in particular the Synchronizer framework).
+ * They're documented here, but mostly for interest, and it is generally assumed
+ * that they won't be called directly by applications.
+ *
+ * As an application developer, it's more likely that you will continue to use
+ * the main Store methods for reading, writing, and listening to data, and rely
+ * on Synchronizer instances to keep the data in step with other places.
+ *
+ * One possible exceptions is the merge method, which can be used to simply
+ * merge two co-located MergeableStore instances together.
+ * @example
+ * This example shows very simple usage of the MergeableStore: whereby two are
+ * created, updated with different data, and then merged with one another.
+ *
+ * ```js
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const localStore1 = createMergeableStore();
+ * const localStore2 = createMergeableStore();
+ *
+ * localStore1.setCell('pets', 'fido', 'color', 'brown');
+ * localStore2.setCell('pets', 'felix', 'color', 'black');
+ *
+ * localStore1.merge(localStore2);
+ *
+ * console.log(localStore1.getContent());
+ * // -> [{pets: {felix: {color: 'black'}, fido: {color: 'brown'}}}, {}]
+ *
+ * console.log(localStore2.getContent());
+ * // -> [{pets: {felix: {color: 'black'}, fido: {color: 'brown'}}}, {}]
+ *```
  * @category Mergeable
  * @since v5.0.0
  */
 export interface MergeableStore extends Store {
   //
   /**
-   * The getMergeableContent method
+   * The getMergeableContent method returns the full content of a
+   * MergeableStore, together with the metadata required to make it mergeable
+   * with another.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @returns A MergeableContent object for the full content of the
+   * MergeableStore.
+   * @example
+   * This example creates a MergeableStore, sets some data, and then accesses
+   * the content and metadata required to make it mergeable.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore('store1'); // !resetHlc
+   *
+   * store.setCell('pets', 'fido', 'color', 'brown');
+   *
+   * console.log(store.getMergeableContent());
+   * // ->
+   * [
+   *   [
+   *     {
+   *       pets: [
+   *         {
+   *           fido: [
+   *             {color: ['brown', 'Nn1JUF-----FnHIC', 923684530]},
+   *             '',
+   *             851131566,
+   *           ],
+   *         },
+   *         '',
+   *         518810247,
+   *       ],
+   *     },
+   *     '',
+   *     784336119,
+   *   ],
+   *   [{}, '', 0],
+   * ];
+   * ```
    * @category Getter
    * @since v5.0.0
    */
   getMergeableContent(): MergeableContent;
 
   /**
-   * The getMergeableContentHashes method
+   * The getMergeableContentHashes method returns hashes for the full content of
+   * a MergeableStore.
+   *
+   * If two MergeableStore instances have different hashes, that indicates that
+   * the mergeable Tables or Values within them are different and should be
+   * synchronized.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @returns A ContentHashes array for the hashes of the full content of the
+   * MergeableStore.
+   * @example
+   * This example creates a MergeableStore, sets some data, and then accesses
+   * the content hashes.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore('store1'); // !resetHlc
+   *
+   * store.setCell('pets', 'fido', 'color', 'brown');
+   * console.log(store.getMergeableContentHashes());
+   * // -> [784336119, 0]
+   *
+   * store.setValue('open', true);
+   * console.log(store.getMergeableContentHashes());
+   * // -> [784336119, 2829789038]
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableContentHashes(): ContentHashes;
 
   /**
-   * The getMergeableTableHashes method
+   * The getMergeableTableHashes method returns hashes for the Table objects in
+   * a MergeableStore.
+   *
+   * If two Table Ids have different hashes, that indicates that the content
+   * within them is different and should be synchronized.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @returns A TableHashes object with the hashes of each Table in the
+   * MergeableStore.
+   * @example
+   * This example creates a MergeableStore, sets some data, and then accesses
+   * the Table hashes.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore('store1'); // !resetHlc
+   *
+   * store.setCell('pets', 'fido', 'color', 'brown');
+   * console.log(store.getMergeableTableHashes());
+   * // -> {pets: 518810247}
+   *
+   * store.setCell('species', 'dog', 'price', 5);
+   * console.log(store.getMergeableTableHashes());
+   * // -> {pets: 518810247, species: 2324343240}
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableTableHashes(): TableHashes;
 
   /**
-   * The getMergeableTableDiff method
+   * The getMergeableTableDiff method returns information about new and
+   * differing Table objects of a MergeableStore relative to another.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param otherTableHashes The TableHashes of another MergeableStore.
+   * @returns A pair of objects describing the new and differing Table objects
+   * of this MergeableStore relative to the other.
+   * @example
+   * This example creates two MergeableStores, sets some differing data, and
+   * then identifies the differences in the Table objects of one versus the
+   * other. Once they have been merged, the differences are empty.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setTables({pets: {fido: {color: 'brown'}}});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setTables({
+   *   pets: {fido: {species: 'dog'}},
+   *   species: {dog: {price: 5}},
+   * });
+   *
+   * console.log(
+   *   store2.getMergeableTableDiff(store1.getMergeableTableHashes()),
+   * );
+   * // ->
+   * [
+   *   [{species: [{dog: [{price: [5, 'Nn1JUF----0CnH-J']}]}]}],
+   *   {pets: 1212600658},
+   * ];
+   *
+   * store1.merge(store2);
+   *
+   * console.log(
+   *   store2.getMergeableTableDiff(store1.getMergeableTableHashes()),
+   * );
+   * // -> [[{}], {}]
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableTableDiff(
-    relativeTo: TableHashes,
-  ): [newTables: TablesStamp, differentTableHashes: TableHashes];
+    otherTableHashes: TableHashes,
+  ): [newTables: TablesStamp, differingTableHashes: TableHashes];
 
   /**
-   * The getMergeableRowHashes method
+   * The getMergeableRowHashes method returns hashes for Row objects in a
+   * MergeableStore.
+   *
+   * If two Row Ids have different hashes, that indicates that the content
+   * within them is different and should be synchronized.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param otherTableHashes The TableHashes from the other MergeableStore so
+   * that the differences can be efficiently identified.
+   * @returns A RowHashes object with the hashes of each Row in the relevant
+   * Table objects of the MergeableStore.
+   * @example
+   * This example creates a MergeableStore, sets some data, and then accesses
+   * the Row hashes for the differing Table Ids.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setTables({pets: {fido: {color: 'brown'}, felix: {color: 'tan'}}});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setTables({pets: {fido: {color: 'black'}, felix: {color: 'tan'}}});
+   *
+   * console.log(
+   *   store1.getMergeableRowHashes(
+   *     store2.getMergeableTableDiff(store1.getMergeableTableHashes())[1],
+   *   ),
+   * );
+   * // -> {pets: {felix: 1683761402, fido: 851131566}}
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableRowHashes(otherTableHashes: TableHashes): RowHashes;
 
   /**
-   * The getMergeableRowDiff method
+   * The getMergeableRowDiff method returns information about new and differing
+   * Row objects of a MergeableStore relative to another.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param otherTableRowHashes The RowHashes of another MergeableStore.
+   * @returns A pair of objects describing the new and differing Row objects of
+   * this MergeableStore relative to the other.
+   * @example
+   * This example creates two MergeableStores, sets some differing data, and
+   * then identifies the differences in the Row objects of one versus the other.
+   * Once they have been merged, the differences are empty.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setTables({pets: {fido: {color: 'brown'}}});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setTables({pets: {fido: {color: 'black'}, felix: {color: 'tan'}}});
+   *
+   * console.log(
+   *   store2.getMergeableRowDiff(
+   *     store1.getMergeableRowHashes(
+   *       store2.getMergeableTableDiff(store1.getMergeableTableHashes())[1],
+   *     ),
+   *   ),
+   * );
+   * // ->
+   * [
+   *   [{pets: [{felix: [{color: ['tan', 'Nn1JUF----0CnH-J']}]}]}],
+   *   {pets: {fido: 1038491054}},
+   * ];
+   *
+   * store1.merge(store2);
+   *
+   * console.log(
+   *   store2.getMergeableRowDiff(
+   *     store1.getMergeableRowHashes(
+   *       store2.getMergeableTableDiff(store1.getMergeableTableHashes())[1],
+   *     ),
+   *   ),
+   * );
+   * // -> [[{}], {}]
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableRowDiff(
     otherTableRowHashes: RowHashes,
-  ): [newRows: TablesStamp, differentRowHashes: RowHashes];
+  ): [newRows: TablesStamp, differingRowHashes: RowHashes];
 
   /**
-   * The getMergeableCellHashes method
+   * The getMergeableCellHashes method returns hashes for Cell objects in a
+   * MergeableStore.
+   *
+   * If two Cell Ids have different hashes, that indicates that the content
+   * within them is different and should be synchronized.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param otherTableRowHashes The RowHashes from the other MergeableStore so
+   * that the differences can be efficiently identified.
+   * @returns A CellHashes object with the hashes of each Cell in the relevant
+   * Row objects of the MergeableStore.
+   * @example
+   * This example creates a MergeableStore, sets some data, and then accesses
+   * the Cell hashes for the differing Table Ids.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setTables({pets: {fido: {color: 'brown', species: 'dog'}}});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setTables({pets: {fido: {color: 'black', species: 'dog'}}});
+   *
+   * console.log(
+   *   store1.getMergeableCellHashes(
+   *     store2.getMergeableRowDiff(
+   *       store1.getMergeableRowHashes(
+   *         store2.getMergeableTableDiff(store1.getMergeableTableHashes())[1],
+   *       ),
+   *     )[1],
+   *   ),
+   * );
+   * // -> {pets: {fido: {color: 923684530, species: 227729753}}}
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableCellHashes(otherTableRowHashes: RowHashes): CellHashes;
 
   /**
-   * The getMergeableCellDiff method
+   * The getMergeableCellDiff method returns information about new and differing
+   * Cell objects of a MergeableStore relative to another.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param otherTableRowCellHashes The CellHashes of another MergeableStore.
+   * @returns The new and differing Cell objects of this MergeableStore relative
+   * to the other.
+   * @example
+   * This example creates two MergeableStores, sets some differing data, and
+   * then identifies the differences in the Cell objects of one versus the
+   * other. Once they have been merged, the differences are empty.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setTables({pets: {fido: {color: 'brown'}}});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setTables({pets: {fido: {color: 'black', species: 'dog'}}});
+   *
+   * console.log(
+   *   store2.getMergeableCellDiff(
+   *     store1.getMergeableCellHashes(
+   *       store2.getMergeableRowDiff(
+   *         store1.getMergeableRowHashes(
+   *           store2.getMergeableTableDiff(
+   *             store1.getMergeableTableHashes(),
+   *           )[1],
+   *         ),
+   *       )[1],
+   *     ),
+   *   ),
+   * );
+   * // ->
+   * [
+   *   {
+   *     pets: [
+   *       {
+   *         fido: [
+   *           {
+   *             color: ['black', 'Nn1JUF-----CnH-J'],
+   *             species: ['dog', 'Nn1JUF----0CnH-J'],
+   *           },
+   *         ],
+   *       },
+   *     ],
+   *   },
+   * ];
+   *
+   * store1.merge(store2);
+   *
+   * console.log(
+   *   store2.getMergeableCellDiff(
+   *     store1.getMergeableCellHashes(
+   *       store2.getMergeableRowDiff(
+   *         store1.getMergeableRowHashes(
+   *           store2.getMergeableTableDiff(
+   *             store1.getMergeableTableHashes(),
+   *           )[1],
+   *         ),
+   *       )[1],
+   *     ),
+   *   ),
+   * );
+   * // -> [{}]
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableCellDiff(otherTableRowCellHashes: CellHashes): TablesStamp;
 
   /**
-   * The getMergeableValueHashes method
+   * The getMergeableValueHashes method returns hashes for the Value objects in
+   * a MergeableStore.
+   *
+   * If two Value Ids have different hashes, that indicates that the content
+   * within them is different and should be synchronized.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @returns A ValueHashes object with the hashes of each Value in the
+   * MergeableStore.
+   * @example
+   * This example creates a MergeableStore, sets some data, and then accesses
+   * the Value hashes.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore('store1'); // !resetHlc
+   *
+   * store.setValue('employees', 3);
+   * console.log(store.getMergeableValueHashes());
+   * // -> {employees: 1940815977}
+   *
+   * store.setValue('open', true);
+   * console.log(store.getMergeableValueHashes());
+   * // -> {employees: 1940815977, open: 3860530645}
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
   getMergeableValueHashes(): ValueHashes;
 
   /**
-   * The getMergeableValueDiff method
+   * The getMergeableValueDiff method returns information about new and
+   * differing Value objects of a MergeableStore relative to another.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param otherValueHashes The ValueHashes of another MergeableStore.
+   * @returns The new and differing Value objects of this MergeableStore
+   * relative to the other.
+   * @example
+   * This example creates two MergeableStores, sets some differing data, and
+   * then identifies the differences in the Value objects of one versus the
+   * other. Once they have been merged, the differences are empty.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setValues({employees: 3});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setValues({employees: 4, open: true});
+   *
+   * console.log(
+   *   store2.getMergeableValueDiff(store1.getMergeableValueHashes()),
+   * );
+   * // ->
+   * [
+   *   {
+   *     employees: [4, 'Nn1JUF-----CnH-J'],
+   *     open: [true, 'Nn1JUF----0CnH-J'],
+   *   },
+   * ];
+   *
+   * store1.merge(store2);
+   *
+   * console.log(
+   *   store2.getMergeableValueDiff(store1.getMergeableValueHashes()),
+   * );
+   * // -> [{}]
+   * ```
    * @category Syncing
    * @since v5.0.0
    */
-  getMergeableValueDiff(relativeTo: ValueHashes): ValuesStamp;
+  getMergeableValueDiff(otherValueHashes: ValueHashes): ValuesStamp;
 
   /**
-   * The setMergeableContent method
+   * The setMergeableContent method sets the full content of a MergeableStore,
+   * together with the metadata required to make it mergeable with another.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param mergeableContent The full content and metadata of a MergeableStore.
+   * @returns A reference to the MergeableStore.
+   * @example
+   * This example creates a new MergeableStore and initializes it with
+   * the content and metadata from another.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setValues({employees: 3});
+   * console.log(store1.getMergeableContent());
+   * // ->
+   * [
+   *   [{}, '', 0],
+   *   [{employees: [3, 'Nn1JUF-----FnHIC', 1940815977]}, '', 1260895905],
+   * ];
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setMergeableContent(store1.getMergeableContent());
+   * console.log(store2.getMergeableContent());
+   * // ->
+   * [
+   *   [{}, '', 0],
+   *   [{employees: [3, 'Nn1JUF-----FnHIC', 1940815977]}, '', 1260895905],
+   * ];
+   * ```
    * @category Setter
    * @since v5.0.0
    */
   setMergeableContent(mergeableContent: MergeableContent): MergeableStore;
 
   /**
-   * The setDefaultContent method
+   * The setDefaultContent method sets initial content of a MergeableStore.
+   *
+   * This differs from the setMergeableContent method in that all of the
+   * metadata is initialized with a empty HLC timestamp - meaning that any
+   * changes applied to it will 'win', yet ensuring that at least default,
+   * initial data exists.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param content An array containing the tabular and keyed-value data to be
+   * set.
+   * @returns A reference to the MergeableStore.
+   * @example
+   * This example creates a new MergeableStore with default data, and
+   * demonstrates that it is overwritten with another MergeableStore's data on
+   * merge, even if the other MergeableStore was provisioned earlier.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1'); // !resetHlc
+   * store1.setValues({employees: 3});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setDefaultContent([{}, {employees: 4}]);
+   * console.log(store2.getMergeableContent());
+   * // -> [[{}, "", 0], [{"employees": [4, "", 2414055963]}, "", 3035768673]]
+   * ```
+   *
+   * store2.merge(store1);
+   *
+   * console.log(store2.getContent());
+   * // -> [{}, {employees: 3}]
+   * ```
    * @category Setter
    * @since v5.0.0
    */
   setDefaultContent(content: Content): MergeableStore;
 
   /**
-   * The getTransactionMergeableChanges method
-   * @category Getter
+   * The getTransactionMergeableChanges method returns the net meaningful
+   * changes that have been made to a MergeableStore during a transaction.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @returns A MergeableChanges object representing the changes.
+   * @example
+   * This example makes changes to the MergeableStore. At the end of the
+   * transaction, detail about what changed is enumerated.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore('store1'); // !resetHlc
+   * store.setTables({pets: {fido: {species: 'dog', color: 'brown'}}});
+   * store.setValues({open: true});
+   *
+   * store
+   *   .startTransaction()
+   *   .setCell('pets', 'fido', 'color', 'black')
+   *   .setValue('open', false)
+   *   .finishTransaction(() => {
+   *     console.log(store.getTransactionMergeableChanges());
+   *   });
+   * // ->
+   * [
+   *   [{pets: [{fido: [{color: ['black', 'Nn1JUF----2FnHIC']}]}]}],
+   *   [{open: [false, 'Nn1JUF----3FnHIC']}],
+   *   1,
+   * ];
+   * ```
+   * @category Transaction
    * @since v5.0.0
    */
   getTransactionMergeableChanges(): MergeableChanges;
 
   /**
-   * The applyMergeableChanges method
+   * The applyMergeableChanges method applies a set of mergeable changes or
+   * content to the MergeableStore.
+   *
+   * The method is generally intended to be used internally within TinyBase
+   * itself and the return type is assumed to be opaque to applications that use
+   * it.
+   * @param mergeableChanges The MergeableChanges or MergeableContent to apply
+   * to the MergeableStore.
+   * @returns A reference to the MergeableStore.
+   * @example
+   * This example applies a MergeableChanges object that sets a Cell and removes
+   * a Value.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store = createMergeableStore('store1')
+   *   .setTables({pets: {fido: {species: 'dog', color: 'brown'}}})
+   *   .setValues({open: true});
+   *
+   * store.applyMergeableChanges([
+   *   [{pets: [{fido: [{color: ['black', 'Nn1JUF----2FnHIC']}]}]}],
+   *   [{open: [null, 'Nn1JUF----3FnHIC']}],
+   *   1,
+   * ]);
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog', color: 'black'}}}
+   * console.log(store.getValues());
+   * // -> {}
+   * ```
    * @category Setter
    * @since v5.0.0
    */
@@ -264,7 +827,88 @@ export interface MergeableStore extends Store {
   ): MergeableStore;
 
   /**
-   * The merge method
+   * The merge method is a convenience method that applies the mergeable content
+   * from two MergeableStores to each other in order to bring them to the same
+   * state.
+   *
+   * This method is symmetrical: applying `store1` to `store2` will have exactly
+   * the same effect as applying `store2` to `store1`.
+   * @param mergeableStore A reference to the other MergeableStore to merge with
+   * this one.
+   * @returns A reference to this MergeableStore.
+   * @example
+   * This example merges two MergeableStore objects together. Note how the final
+   * part of the timestamps on each Cell give you a clue that the data comes
+   * from changes made to different MergeableStore objects.
+   *
+   * ```js
+   * import {createMergeableStore} from 'tinybase';
+   *
+   * const store1 = createMergeableStore('store1');
+   * store1.setTables({pets: {fido: {species: 'dog', color: 'brown'}}});
+   *
+   * const store2 = createMergeableStore('store2');
+   * store2.setTables({pets: {felix: {species: 'cat', color: 'tan'}}});
+   *
+   * store1.merge(store2);
+   *
+   * console.log(store1.getContent());
+   * // ->
+   * [
+   *   {
+   *     pets: {
+   *       felix: {color: 'tan', species: 'cat'},
+   *       fido: {color: 'brown', species: 'dog'},
+   *     },
+   *   },
+   *   {},
+   * ];
+   *
+   * console.log(store2.getContent());
+   * // ->
+   * [
+   *   {
+   *     pets: {
+   *       felix: {color: 'tan', species: 'cat'},
+   *       fido: {color: 'brown', species: 'dog'},
+   *     },
+   *   },
+   *   {},
+   * ];
+   * console.log(store2.getMergeableContent());
+   * // ->
+   * [
+   *   [
+   *     {
+   *       pets: [
+   *         {
+   *           felix: [
+   *             {
+   *               color: ['tan', 'Nn1JUF----0CnH-J', 2576658292],
+   *               species: ['cat', 'Nn1JUF-----CnH-J', 3409607562],
+   *             },
+   *             '',
+   *             4146239216,
+   *           ],
+   *           fido: [
+   *             {
+   *               color: ['brown', 'Nn1JUF----0FnHIC', 1240535355],
+   *               species: ['dog', 'Nn1JUF-----FnHIC', 290599168],
+   *             },
+   *             '',
+   *             3989065420,
+   *           ],
+   *         },
+   *         '',
+   *         4155188296,
+   *       ],
+   *     },
+   *     '',
+   *     972931118,
+   *   ],
+   *   [{}, '', 0],
+   * ];
+   * ```
    * @category Setter
    * @since v5.0.0
    */
@@ -281,7 +925,108 @@ export interface MergeableStore extends Store {
 }
 
 /**
- * The createMergeableStore function
+ * The createMergeableStore function creates a MergeableStore, and is the main
+ * entry point into the mergeable-store module.
+ *
+ * There is one optional parameter which is a uniqueId for the MergeableStore.
+ * This is used to distinguish conflicting changes made in the same millisecond
+ * by two different MergeableStore objects as its hash is added to the end of
+ * the HLC timestamps. Generally this can be omitted unless you have a need for
+ * deterministic HLCs, such as in a testing scenario. Otherwise, TinyBase will
+ * assign a unique Id to the Store at the time of creation.
+ * @returns A reference to the new MergeableStore.
+ * @example
+ * This example creates a MergeableStore.
+ *
+ * ```js
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store = createMergeableStore('store1');
+ *
+ * console.log(store.getContent());
+ * // -> [{}, {}]
+ * console.log(store.getMergeableContent());
+ * // -> [[{}, '', 0], [{}, '', 0]]
+ * ```
+ * @example
+ * This example creates a MergeableStore with some initial data:
+ *
+ * ```js
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store = createMergeableStore('store1').setTables({
+ *   pets: {fido: {species: 'dog'}},
+ * });
+ *
+ * console.log(store.getContent());
+ * // -> [{pets: {fido: {species: 'dog'}}}, {}]
+ * console.log(store.getMergeableContent());
+ * // ->
+ * [
+ *   [
+ *     {
+ *       pets: [
+ *         {
+ *           fido: [
+ *             {species: ['dog', 'Nn1JUF-----FnHIC', 290599168]},
+ *             '',
+ *             2682656941,
+ *           ],
+ *         },
+ *         '',
+ *         2102515304,
+ *       ],
+ *     },
+ *     '',
+ *     3506229770,
+ *   ],
+ *   [{}, '', 0],
+ * ];
+ * ```
+ * @example
+ * This example creates a MergeableStore with some initial data and a
+ * TablesSchema:
+ *
+ * ```js
+ * import {createMergeableStore} from 'tinybase';
+ *
+ * const store = createMergeableStore('store1')
+ *   .setTables({pets: {fido: {species: 'dog'}}})
+ *   .setTablesSchema({
+ *     pets: {
+ *       species: {type: 'string'},
+ *       sold: {type: 'boolean', default: false},
+ *     },
+ *   });
+ *
+ * console.log(store.getContent());
+ * // -> [{pets: {fido: {sold: false, species: 'dog'}}}, {}]
+ * console.log(store.getMergeableContent());
+ * // ->
+ * [
+ *   [
+ *     {
+ *       pets: [
+ *         {
+ *           fido: [
+ *             {
+ *               sold: [false, 'Nn1JUF----2FnHIC', 2603026204],
+ *               species: ['dog', 'Nn1JUF----1FnHIC', 2817056260],
+ *             },
+ *             '',
+ *             2859424112,
+ *           ],
+ *         },
+ *         '',
+ *         1640515891,
+ *       ],
+ *     },
+ *     '',
+ *     2077041985,
+ *   ],
+ *   [{}, '', 0],
+ * ];
+ * ```
  * @category Creation
  * @since v5.0.0
  */