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

package/@types/mergeable-store/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
@@ -14,20 +20,45 @@ import type {
 import type {Id} from '../common/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]
@@ -75,8 +106,8 @@ export type ValuesStamp<Hashed extends boolean = false> = Stamp<
   Hashed
 >;
 
-// ValuesHashes
-export type ValuesHashes = {[valueId: Id]: Hash};
+// ValueHashes
+export type ValueHashes = {[valueId: Id]: Hash};
 
 // ValueStamp
 export type ValueStamp<Hashed extends boolean = false> = Stamp<
@@ -85,8 +116,16 @@ export type ValueStamp<Hashed extends boolean = false> = Stamp<
 >;
 
 /**
- * The MergeableContent type
+ * The MergeableContent type represents the content of a MergeableStore and the
+ * metadata about that content) required to merge it with another.
+ *
+ * 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 = [
   mergeableTables: TablesStamp<true>,
@@ -94,8 +133,18 @@ export type MergeableContent = [
 ];
 
 /**
- * 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.
+ *
+ * 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 = [
   mergeableTables: TablesStamp,
@@ -106,30 +155,35 @@ export type MergeableChanges = [
 /**
  * The MergeableStore type
  * @category Mergeable
+ * @since v5.0.0
  */
 export interface MergeableStore extends Store {
   //
   /**
    * The getMergeableContent method
    * @category Getter
+   * @since v5.0.0
    */
   getMergeableContent(): MergeableContent;
 
   /**
    * The getMergeableContentHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableContentHashes(): ContentHashes;
 
   /**
    * The getMergeableTableHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableHashes(): TableHashes;
 
   /**
    * The getMergeableTableDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableDiff(
     relativeTo: TableHashes,
@@ -138,12 +192,14 @@ export interface MergeableStore extends Store {
   /**
    * The getMergeableRowHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowHashes(otherTableHashes: TableHashes): RowHashes;
 
   /**
    * The getMergeableRowDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowDiff(
     otherTableRowHashes: RowHashes,
@@ -152,48 +208,56 @@ export interface MergeableStore extends Store {
   /**
    * The getMergeableCellHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellHashes(otherTableRowHashes: RowHashes): CellHashes;
 
   /**
    * The getMergeableCellDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellDiff(otherTableRowCellHashes: CellHashes): TablesStamp;
 
   /**
-   * The getMergeableValuesHashes method
+   * The getMergeableValueHashes method
    * @category Syncing
+   * @since v5.0.0
    */
-  getMergeableValuesHashes(): ValuesHashes;
+  getMergeableValueHashes(): ValueHashes;
 
   /**
    * The getMergeableValueDiff method
    * @category Syncing
+   * @since v5.0.0
    */
-  getMergeableValueDiff(relativeTo: ValuesHashes): ValuesStamp;
+  getMergeableValueDiff(relativeTo: ValueHashes): ValuesStamp;
 
   /**
    * The setMergeableContent method
    * @category Setter
+   * @since v5.0.0
    */
   setMergeableContent(mergeableContent: MergeableContent): MergeableStore;
 
   /**
    * The setDefaultContent method
    * @category Setter
+   * @since v5.0.0
    */
   setDefaultContent(content: Content): MergeableStore;
 
   /**
    * The getTransactionMergeableChanges method
    * @category Getter
+   * @since v5.0.0
    */
   getTransactionMergeableChanges(): MergeableChanges;
 
   /**
    * The applyMergeableChanges method
    * @category Setter
+   * @since v5.0.0
    */
   applyMergeableChanges(
     mergeableChanges: MergeableChanges | MergeableContent,
@@ -202,6 +266,7 @@ export interface MergeableStore extends Store {
   /**
    * The merge method
    * @category Setter
+   * @since v5.0.0
    */
   merge(mergeableStore: MergeableStore): MergeableStore;
 
@@ -218,5 +283,6 @@ export interface MergeableStore extends Store {
 /**
  * The createMergeableStore function
  * @category Creation
+ * @since v5.0.0
  */
 export function createMergeableStore(uniqueId?: Id): MergeableStore;

package/@types/mergeable-store/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
@@ -14,20 +20,45 @@ import type {
 import type {Id} from '../common/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]
@@ -75,8 +106,8 @@ export type ValuesStamp<Hashed extends boolean = false> = Stamp<
   Hashed
 >;
 
-// ValuesHashes
-export type ValuesHashes = {[valueId: Id]: Hash};
+// ValueHashes
+export type ValueHashes = {[valueId: Id]: Hash};
 
 // ValueStamp
 export type ValueStamp<Hashed extends boolean = false> = Stamp<
@@ -85,8 +116,16 @@ export type ValueStamp<Hashed extends boolean = false> = Stamp<
 >;
 
 /**
- * The MergeableContent type
+ * The MergeableContent type represents the content of a MergeableStore and the
+ * metadata about that content) required to merge it with another.
+ *
+ * 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 = [
   mergeableTables: TablesStamp<true>,
@@ -94,8 +133,18 @@ export type MergeableContent = [
 ];
 
 /**
- * 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.
+ *
+ * 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 = [
   mergeableTables: TablesStamp,
@@ -106,30 +155,35 @@ export type MergeableChanges = [
 /**
  * The MergeableStore type
  * @category Mergeable
+ * @since v5.0.0
  */
 export interface MergeableStore extends Store {
   //
   /**
    * The getMergeableContent method
    * @category Getter
+   * @since v5.0.0
    */
   getMergeableContent(): MergeableContent;
 
   /**
    * The getMergeableContentHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableContentHashes(): ContentHashes;
 
   /**
    * The getMergeableTableHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableHashes(): TableHashes;
 
   /**
    * The getMergeableTableDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableTableDiff(
     relativeTo: TableHashes,
@@ -138,12 +192,14 @@ export interface MergeableStore extends Store {
   /**
    * The getMergeableRowHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowHashes(otherTableHashes: TableHashes): RowHashes;
 
   /**
    * The getMergeableRowDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableRowDiff(
     otherTableRowHashes: RowHashes,
@@ -152,48 +208,56 @@ export interface MergeableStore extends Store {
   /**
    * The getMergeableCellHashes method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellHashes(otherTableRowHashes: RowHashes): CellHashes;
 
   /**
    * The getMergeableCellDiff method
    * @category Syncing
+   * @since v5.0.0
    */
   getMergeableCellDiff(otherTableRowCellHashes: CellHashes): TablesStamp;
 
   /**
-   * The getMergeableValuesHashes method
+   * The getMergeableValueHashes method
    * @category Syncing
+   * @since v5.0.0
    */
-  getMergeableValuesHashes(): ValuesHashes;
+  getMergeableValueHashes(): ValueHashes;
 
   /**
    * The getMergeableValueDiff method
    * @category Syncing
+   * @since v5.0.0
    */
-  getMergeableValueDiff(relativeTo: ValuesHashes): ValuesStamp;
+  getMergeableValueDiff(relativeTo: ValueHashes): ValuesStamp;
 
   /**
    * The setMergeableContent method
    * @category Setter
+   * @since v5.0.0
    */
   setMergeableContent(mergeableContent: MergeableContent): MergeableStore;
 
   /**
    * The setDefaultContent method
    * @category Setter
+   * @since v5.0.0
    */
   setDefaultContent(content: Content): MergeableStore;
 
   /**
    * The getTransactionMergeableChanges method
    * @category Getter
+   * @since v5.0.0
    */
   getTransactionMergeableChanges(): MergeableChanges;
 
   /**
    * The applyMergeableChanges method
    * @category Setter
+   * @since v5.0.0
    */
   applyMergeableChanges(
     mergeableChanges: MergeableChanges | MergeableContent,
@@ -202,6 +266,7 @@ export interface MergeableStore extends Store {
   /**
    * The merge method
    * @category Setter
+   * @since v5.0.0
    */
   merge(mergeableStore: MergeableStore): MergeableStore;
 
@@ -218,5 +283,6 @@ export interface MergeableStore extends Store {
 /**
  * The createMergeableStore function
  * @category Creation
+ * @since v5.0.0
  */
 export function createMergeableStore(uniqueId?: Id): MergeableStore;