tinybase 5.0.0-beta.22 → 5.0.0-beta.24

package/@types/mergeable-store/with-schemas/index.d.cts

@@ -1,5 +1,11 @@
 /**
- * The mergeable-store module
+ * The mergeable-store module contains the types, interfaces, and functions to
+ * work with MergeableStore objects, which provide merge and synchronization
+ * functionality.
+ *
+ * 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.
  * @packageDocumentation
  * @module mergeable-store
  * @since v5.0.0
@@ -27,20 +33,45 @@ import type {
 import type {Id} from '../../common/with-schemas/index.d.cts';
 
 /**
- * The Hash type
+ * The Hash type is used within the mergeable-store module to quickly compare
+ * the content of two objects.
+ *
+ * This is simply an alias for a JavaScript `number`.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Stamps
+ * @since v5.0.0
  */
 export type Hash = number;
 
 /**
- * The Time type
+ * The Time type is used within the mergeable-store module to store the value of
+ * a hybrid logical clock (HLC).
+ *
+ * It is simply an alias for a JavaScript `string`, but it comprises three HLC
+ * parts: a logical timestamp, a sequence counter, and a client Id. It is
+ * designed to be string-sortable and unique across all of the systems involved
+ * in synchronizing a MergeableStore.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Stamps
+ * @since v5.0.0
  */
 export type Time = string;
 
 /**
- * The Stamp type
+ * The Stamp type is used as metadata to decide how to merge two different
+ * MergeableStore objects together.
+ *
+ * It describes a combination of a value (or object), a Time, and optionally a
+ * Hash, all in an array.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Stamps
+ * @since v5.0.0
  */
 export type Stamp<Thing, Hashed extends boolean = false> = Hashed extends true
   ? [thing: Thing, time: Time, hash: Hash]
@@ -128,8 +159,8 @@ export type ValuesStamp<
   Hashed
 >;
 
-// ValuesHashes
-export type ValuesHashes<Schema extends OptionalValuesSchema> = {
+// ValueHashes
+export type ValueHashes<Schema extends OptionalValuesSchema> = {
   [ValueId in ValueIdFromSchema<Schema>]?: Hash;
 };
 
@@ -141,8 +172,25 @@ export type ValueStamp<
 > = Stamp<ValueOrUndefined<Schema, ValueId>, Hashed>;
 
 /**
- * The MergeableContent type
+ * The MergeableContent type represents the content of a MergeableStore and the
+ * metadata about that content) required to merge it with another.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * [
+ *   mergeableTables: TablesStamp<true>,
+ *   mergeableValues: ValuesStamp<true>,
+ * ];
+ * ```
+ *
+ * It is simply an array of two Stamp types, one for the MergeableStore's Tables
+ * and one for its Values.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Mergeable
+ * @since v5.0.0
  */
 export type MergeableContent<Schemas extends OptionalSchemas> = [
   mergeableTables: TablesStamp<Schemas[0], true>,
@@ -150,8 +198,28 @@ export type MergeableContent<Schemas extends OptionalSchemas> = [
 ];
 
 /**
- * The MergeableChanges type
+ * The MergeableChanges type represents changes to the content of a
+ * MergeableStore and the metadata about that content) required to merge it with
+ * another.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * [
+ *   mergeableTables: TablesStamp,
+ *   mergeableValues: ValuesStamp,
+ *   isChanges: 1,
+ * ];
+ * ```
+ *
+ * It is simply an array of two Stamp types, one for changes to the
+ * MergeableStore's Tables and one for changes to its Values. A final `1` is
+ * used to distinguish it from a full MergeableContent object.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Mergeable
+ * @since v5.0.0
  */
 export type MergeableChanges<Schemas extends OptionalSchemas> = [
   mergeableTables: TablesStamp<Schemas[0]>,
@@ -162,6 +230,7 @@ export type MergeableChanges<Schemas extends OptionalSchemas> = [
 /**
  * The MergeableStore type
  * @category Mergeable
+ * @since v5.0.0
  */
 export interface MergeableStore<Schemas extends OptionalSchemas>
   extends Store<Schemas> {
@@ -169,24 +238,28 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableContent method
    * @category Getter
+   * @since v5.0.0
    */
   getMergeableContent(): MergeableContent<Schemas>;
 
   /**
    * The getMergeableContentHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableContentHashes(): ContentHashes;
 
   /**
    * The getMergeableTableHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableHashes(): TableHashes<Schemas[0]>;
 
   /**
    * The getMergeableTableDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableDiff(
     relativeTo: TableHashes<Schemas[0]>,
@@ -198,6 +271,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableRowHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowHashes(
     otherTableHashes: TableHashes<Schemas[0]>,
@@ -206,6 +280,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableRowDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowDiff(
     otherTableRowHashes: RowHashes<Schemas[0]>,
@@ -217,6 +292,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableCellHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellHashes(
     otherTableRowHashes: RowHashes<Schemas[0]>,
@@ -225,28 +301,32 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableCellDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellDiff(
     otherTableRowCellHashes: CellHashes<Schemas[0]>,
   ): TablesStamp<Schemas[0]>;
 
   /**
-   * The getMergeableValuesHashes method
+   * The getMergeableValueHashes method
    * @category Syncing
+   * @since v5.0.0
    */
-  getMergeableValuesHashes(): ValuesHashes<Schemas[1]>;
+  getMergeableValueHashes(): ValueHashes<Schemas[1]>;
 
   /**
    * The getMergeableValueDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableValueDiff(
-    relativeTo: ValuesHashes<Schemas[1]>,
+    relativeTo: ValueHashes<Schemas[1]>,
   ): ValuesStamp<Schemas[1]>;
 
   /**
    * The setMergeableContent method
    * @category Setter
+   * @since v5.0.0
    */
   setMergeableContent(
     mergeableContent: MergeableContent<Schemas>,
@@ -255,18 +335,21 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The setDefaultContent method
    * @category Setter
+   * @since v5.0.0
    */
   setDefaultContent(content: Content<Schemas>): MergeableStore<Schemas>;
 
   /**
    * The getTransactionMergeableChanges method
    * @category Getter
+   * @since v5.0.0
    */
   getTransactionMergeableChanges(): MergeableChanges<Schemas>;
 
   /**
    * The applyMergeableChanges method
    * @category Setter
+   * @since v5.0.0
    */
   applyMergeableChanges(
     mergeableChanges: MergeableChanges<Schemas> | MergeableContent<Schemas>,
@@ -275,6 +358,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The merge method
    * @category Setter
+   * @since v5.0.0
    */
   merge(mergeableStore: MergeableStore<Schemas>): MergeableStore<Schemas>;
 
@@ -505,5 +589,6 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
 /**
  * The createMergeableStore function
  * @category Creation
+ * @since v5.0.0
  */
 export function createMergeableStore(uniqueId?: Id): MergeableStore<NoSchemas>;

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

@@ -1,5 +1,11 @@
 /**
- * The mergeable-store module
+ * The mergeable-store module contains the types, interfaces, and functions to
+ * work with MergeableStore objects, which provide merge and synchronization
+ * functionality.
+ *
+ * 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.
  * @packageDocumentation
  * @module mergeable-store
  * @since v5.0.0
@@ -27,20 +33,45 @@ import type {
 import type {Id} from '../../common/with-schemas/index.d.ts';
 
 /**
- * The Hash type
+ * The Hash type is used within the mergeable-store module to quickly compare
+ * the content of two objects.
+ *
+ * This is simply an alias for a JavaScript `number`.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Stamps
+ * @since v5.0.0
  */
 export type Hash = number;
 
 /**
- * The Time type
+ * The Time type is used within the mergeable-store module to store the value of
+ * a hybrid logical clock (HLC).
+ *
+ * It is simply an alias for a JavaScript `string`, but it comprises three HLC
+ * parts: a logical timestamp, a sequence counter, and a client Id. It is
+ * designed to be string-sortable and unique across all of the systems involved
+ * in synchronizing a MergeableStore.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Stamps
+ * @since v5.0.0
  */
 export type Time = string;
 
 /**
- * The Stamp type
+ * The Stamp type is used as metadata to decide how to merge two different
+ * MergeableStore objects together.
+ *
+ * It describes a combination of a value (or object), a Time, and optionally a
+ * Hash, all in an array.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Stamps
+ * @since v5.0.0
  */
 export type Stamp<Thing, Hashed extends boolean = false> = Hashed extends true
   ? [thing: Thing, time: Time, hash: Hash]
@@ -128,8 +159,8 @@ export type ValuesStamp<
   Hashed
 >;
 
-// ValuesHashes
-export type ValuesHashes<Schema extends OptionalValuesSchema> = {
+// ValueHashes
+export type ValueHashes<Schema extends OptionalValuesSchema> = {
   [ValueId in ValueIdFromSchema<Schema>]?: Hash;
 };
 
@@ -141,8 +172,25 @@ export type ValueStamp<
 > = Stamp<ValueOrUndefined<Schema, ValueId>, Hashed>;
 
 /**
- * The MergeableContent type
+ * The MergeableContent type represents the content of a MergeableStore and the
+ * metadata about that content) required to merge it with another.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * [
+ *   mergeableTables: TablesStamp<true>,
+ *   mergeableValues: ValuesStamp<true>,
+ * ];
+ * ```
+ *
+ * It is simply an array of two Stamp types, one for the MergeableStore's Tables
+ * and one for its Values.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Mergeable
+ * @since v5.0.0
  */
 export type MergeableContent<Schemas extends OptionalSchemas> = [
   mergeableTables: TablesStamp<Schemas[0], true>,
@@ -150,8 +198,28 @@ export type MergeableContent<Schemas extends OptionalSchemas> = [
 ];
 
 /**
- * The MergeableChanges type
+ * The MergeableChanges type represents changes to the content of a
+ * MergeableStore and the metadata about that content) required to merge it with
+ * another.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * [
+ *   mergeableTables: TablesStamp,
+ *   mergeableValues: ValuesStamp,
+ *   isChanges: 1,
+ * ];
+ * ```
+ *
+ * It is simply an array of two Stamp types, one for changes to the
+ * MergeableStore's Tables and one for changes to its Values. A final `1` is
+ * used to distinguish it from a full MergeableContent object.
+ *
+ * This type is mostly utilized internally within TinyBase itself and is
+ * generally assumed to be opaque to applications that use it.
  * @category Mergeable
+ * @since v5.0.0
  */
 export type MergeableChanges<Schemas extends OptionalSchemas> = [
   mergeableTables: TablesStamp<Schemas[0]>,
@@ -162,6 +230,7 @@ export type MergeableChanges<Schemas extends OptionalSchemas> = [
 /**
  * The MergeableStore type
  * @category Mergeable
+ * @since v5.0.0
  */
 export interface MergeableStore<Schemas extends OptionalSchemas>
   extends Store<Schemas> {
@@ -169,24 +238,28 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableContent method
    * @category Getter
+   * @since v5.0.0
    */
   getMergeableContent(): MergeableContent<Schemas>;
 
   /**
    * The getMergeableContentHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableContentHashes(): ContentHashes;
 
   /**
    * The getMergeableTableHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableHashes(): TableHashes<Schemas[0]>;
 
   /**
    * The getMergeableTableDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableDiff(
     relativeTo: TableHashes<Schemas[0]>,
@@ -198,6 +271,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableRowHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowHashes(
     otherTableHashes: TableHashes<Schemas[0]>,
@@ -206,6 +280,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableRowDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowDiff(
     otherTableRowHashes: RowHashes<Schemas[0]>,
@@ -217,6 +292,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableCellHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellHashes(
     otherTableRowHashes: RowHashes<Schemas[0]>,
@@ -225,28 +301,32 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The getMergeableCellDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellDiff(
     otherTableRowCellHashes: CellHashes<Schemas[0]>,
   ): TablesStamp<Schemas[0]>;
 
   /**
-   * The getMergeableValuesHashes method
+   * The getMergeableValueHashes method
    * @category Syncing
+   * @since v5.0.0
    */
-  getMergeableValuesHashes(): ValuesHashes<Schemas[1]>;
+  getMergeableValueHashes(): ValueHashes<Schemas[1]>;
 
   /**
    * The getMergeableValueDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableValueDiff(
-    relativeTo: ValuesHashes<Schemas[1]>,
+    relativeTo: ValueHashes<Schemas[1]>,
   ): ValuesStamp<Schemas[1]>;
 
   /**
    * The setMergeableContent method
    * @category Setter
+   * @since v5.0.0
    */
   setMergeableContent(
     mergeableContent: MergeableContent<Schemas>,
@@ -255,18 +335,21 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The setDefaultContent method
    * @category Setter
+   * @since v5.0.0
    */
   setDefaultContent(content: Content<Schemas>): MergeableStore<Schemas>;
 
   /**
    * The getTransactionMergeableChanges method
    * @category Getter
+   * @since v5.0.0
    */
   getTransactionMergeableChanges(): MergeableChanges<Schemas>;
 
   /**
    * The applyMergeableChanges method
    * @category Setter
+   * @since v5.0.0
    */
   applyMergeableChanges(
     mergeableChanges: MergeableChanges<Schemas> | MergeableContent<Schemas>,
@@ -275,6 +358,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
   /**
    * The merge method
    * @category Setter
+   * @since v5.0.0
    */
   merge(mergeableStore: MergeableStore<Schemas>): MergeableStore<Schemas>;
 
@@ -505,5 +589,6 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
 /**
  * The createMergeableStore function
  * @category Creation
+ * @since v5.0.0
  */
 export function createMergeableStore(uniqueId?: Id): MergeableStore<NoSchemas>;

package/@types/persisters/index.d.cts

@@ -20,7 +20,6 @@
  * |persister-sqlite-wasm|createSqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|
  * |persister-cr-sqlite-wasm|createCrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|
  * |persister-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|
- * |persister-expo-sqlite-next|createExpoSqliteNextPersister|SQLite in React Native, via [expo-sqlite/next](https://github.com/expo/expo/tree/main/packages/expo-sqlite/next)|
  * |persister-electric-sql|createElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|
  * |persister-libsql|createLibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|
  * |persister-powersync|createPowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|

package/@types/persisters/index.d.ts

@@ -20,7 +20,6 @@
  * |persister-sqlite-wasm|createSqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|
  * |persister-cr-sqlite-wasm|createCrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|
  * |persister-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|
- * |persister-expo-sqlite-next|createExpoSqliteNextPersister|SQLite in React Native, via [expo-sqlite/next](https://github.com/expo/expo/tree/main/packages/expo-sqlite/next)|
  * |persister-electric-sql|createElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|
  * |persister-libsql|createLibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|
  * |persister-powersync|createPowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|