tinybase 5.0.0-beta.1 → 5.0.0-beta.10

package/lib/types/with-schemas/mergeable-store.d.ts

@@ -0,0 +1,492 @@
+/**
+ * The mergeable-store module
+ * @packageDocumentation
+ * @module mergeable-store
+ * @since v5.0.0
+ */
+
+import {
+  CellIdFromSchema,
+  TableIdFromSchema,
+  ValueIdFromSchema,
+} from './internal/store';
+import {
+  CellOrUndefined,
+  Content,
+  NoSchemas,
+  NoTablesSchema,
+  NoValuesSchema,
+  OptionalSchemas,
+  OptionalTablesSchema,
+  OptionalValuesSchema,
+  Store,
+  TablesSchema,
+  ValueOrUndefined,
+  ValuesSchema,
+} from './store.d.ts';
+import {Id} from './common';
+
+/**
+ * The Hash type
+ * @category Stamps
+ */
+export type Hash = number;
+
+/**
+ * The Time type
+ * @category Stamps
+ */
+export type Time = string;
+
+/**
+ * The Stamp type
+ * @category Stamps
+ */
+export type Stamp<Thing, Hashed extends boolean = false> = Hashed extends true
+  ? [thing: Thing, time: Time, hash: Hash]
+  : [thing: Thing, time?: Time];
+
+// ContentHashes
+export type ContentHashes = [tablesHash: Hash, valuesHash: Hash];
+
+// TablesStamp
+export type TablesStamp<
+  Schema extends OptionalTablesSchema,
+  Hashed extends boolean = false,
+> = Stamp<
+  {
+    [TableId in TableIdFromSchema<Schema>]?: TableStamp<
+      Schema,
+      TableId,
+      Hashed
+    >;
+  },
+  Hashed
+>;
+
+// TableHashes
+export type TableHashes<Schema extends OptionalTablesSchema> = {
+  [TableId in TableIdFromSchema<Schema>]?: Hash;
+};
+
+// TableStamp
+export type TableStamp<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  Hashed extends boolean = false,
+> = Stamp<{[rowId: Id]: RowStamp<Schema, TableId, Hashed>}, Hashed>;
+
+// RowHashes
+export type RowHashes<Schema extends OptionalTablesSchema> = {
+  [TableId in TableIdFromSchema<Schema>]?: {[rowId: Id]: Hash};
+};
+
+// RowStamp
+export type RowStamp<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  Hashed extends boolean = false,
+> = Stamp<
+  {
+    [CellId in CellIdFromSchema<Schema, TableId>]?: CellStamp<
+      Schema,
+      TableId,
+      CellId,
+      Hashed
+    >;
+  },
+  Hashed
+>;
+
+// CellHashes
+export type CellHashes<Schema extends OptionalTablesSchema> = {
+  [TableId in TableIdFromSchema<Schema>]?: {
+    [rowId: Id]: {[CellId in CellIdFromSchema<Schema, TableId>]?: Hash};
+  };
+};
+
+// CellStamp
+export type CellStamp<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+  CellId extends CellIdFromSchema<Schema, TableId>,
+  Hashed extends boolean = false,
+> = Stamp<CellOrUndefined<Schema, TableId, CellId>, Hashed>;
+
+// ValuesStamp
+export type ValuesStamp<
+  Schema extends OptionalValuesSchema,
+  Hashed extends boolean = false,
+> = Stamp<
+  {
+    [ValueId in ValueIdFromSchema<Schema>]?: ValueStamp<
+      Schema,
+      ValueId,
+      Hashed
+    >;
+  },
+  Hashed
+>;
+
+// ValuesHashes
+export type ValuesHashes<Schema extends OptionalValuesSchema> = {
+  [ValueId in ValueIdFromSchema<Schema>]?: Hash;
+};
+
+// ValueStamp
+export type ValueStamp<
+  Schema extends OptionalValuesSchema,
+  ValueId extends ValueIdFromSchema<Schema>,
+  Hashed extends boolean = false,
+> = Stamp<ValueOrUndefined<Schema, ValueId>, Hashed>;
+
+/**
+ * The MergeableContent type
+ * @category Mergeable
+ */
+export type MergeableContent<Schemas extends OptionalSchemas> = [
+  mergeableTables: TablesStamp<Schemas[0], true>,
+  mergeableValues: ValuesStamp<Schemas[1], true>,
+];
+
+/**
+ * The MergeableChanges type
+ * @category Mergeable
+ */
+export type MergeableChanges<Schemas extends OptionalSchemas> = [
+  mergeableTables: TablesStamp<Schemas[0]>,
+  mergeableValues: ValuesStamp<Schemas[1]>,
+  isChanges: 1,
+];
+
+/**
+ * The MergeableStore type
+ * @category Mergeable
+ */
+export interface MergeableStore<Schemas extends OptionalSchemas>
+  extends Store<Schemas> {
+  //
+  /**
+   * The getId method
+   * @category Getter
+   */
+  getId(): Id;
+
+  /**
+   * The getMergeableContent method
+   * @category Getter
+   */
+  getMergeableContent(): MergeableContent<Schemas>;
+
+  /**
+   * The getMergeableContentHashes method
+   * @category Syncing
+   */
+  getMergeableContentHashes(): ContentHashes;
+
+  /**
+   * The getMergeableTableHashes method
+   * @category Syncing
+   */
+  getMergeableTableHashes(): TableHashes<Schemas[0]>;
+
+  /**
+   * The getMergeableTableDiff method
+   * @category Syncing
+   */
+  getMergeableTableDiff(
+    relativeTo: TableHashes<Schemas[0]>,
+  ): [
+    newTables: TablesStamp<Schemas[0]>,
+    differentTableHashes: TableHashes<Schemas[0]>,
+  ];
+
+  /**
+   * The getMergeableRowHashes method
+   * @category Syncing
+   */
+  getMergeableRowHashes(
+    otherTableHashes: TableHashes<Schemas[0]>,
+  ): RowHashes<Schemas[0]>;
+
+  /**
+   * The getMergeableRowDiff method
+   * @category Syncing
+   */
+  getMergeableRowDiff(
+    otherTableRowHashes: RowHashes<Schemas[0]>,
+  ): [
+    newRows: TablesStamp<Schemas[0]>,
+    differentRowHashes: RowHashes<Schemas[0]>,
+  ];
+
+  /**
+   * The getMergeableCellHashes method
+   * @category Syncing
+   */
+  getMergeableCellHashes(
+    otherTableRowHashes: RowHashes<Schemas[0]>,
+  ): CellHashes<Schemas[0]>;
+
+  /**
+   * The getMergeableCellDiff method
+   * @category Syncing
+   */
+  getMergeableCellDiff(
+    otherTableRowCellHashes: CellHashes<Schemas[0]>,
+  ): TablesStamp<Schemas[0]>;
+
+  /**
+   * The getMergeableValuesHashes method
+   * @category Syncing
+   */
+  getMergeableValuesHashes(): ValuesHashes<Schemas[1]>;
+
+  /**
+   * The getMergeableValueDiff method
+   * @category Syncing
+   */
+  getMergeableValueDiff(
+    relativeTo: ValuesHashes<Schemas[1]>,
+  ): ValuesStamp<Schemas[1]>;
+
+  /**
+   * The setMergeableContent method
+   * @category Setter
+   */
+  setMergeableContent(
+    mergeableContent: MergeableContent<Schemas>,
+  ): MergeableStore<Schemas>;
+
+  /**
+   * The setDefaultContent method
+   * @category Setter
+   */
+  setDefaultContent(content: Content<Schemas>): MergeableStore<Schemas>;
+
+  /**
+   * The getTransactionMergeableChanges method
+   * @category Getter
+   */
+  getTransactionMergeableChanges(): MergeableChanges<Schemas>;
+
+  /**
+   * The applyMergeableChanges method
+   * @category Setter
+   */
+  applyMergeableChanges(
+    mergeableChanges: MergeableChanges<Schemas> | MergeableContent<Schemas>,
+  ): MergeableStore<Schemas>;
+
+  /**
+   * The merge method
+   * @category Setter
+   */
+  merge(mergeableStore: MergeableStore<Schemas>): MergeableStore<Schemas>;
+
+  /**
+   * The setTablesSchema method lets you specify the TablesSchema of the tabular
+   * part of the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Table, Row, or Cell objects are removed. These
+   * changes will fire any listeners to that data, as expected.
+   *
+   * When no longer needed, you can also completely remove an existing
+   * TablesSchema with the delTablesSchema method.
+   * @param tablesSchema The TablesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the TablesSchema of a Store after it has been created.
+   *
+   * ```js
+   * const store = createStore().setTablesSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     sold: {type: 'boolean', default: false},
+   *   },
+   * });
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * ```
+   * @category Setter
+   * @since v3.0.0
+   */
+  setTablesSchema<TS extends TablesSchema>(
+    tablesSchema: TS,
+  ): MergeableStore<[typeof tablesSchema, Schemas[1]]>;
+
+  /**
+   * The setValuesSchema method lets you specify the ValuesSchema of the keyed
+   * Values part of the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Values are removed. These changes will fire any
+   * listeners to that data, as expected.
+   *
+   * When no longer needed, you can also completely remove an existing
+   * ValuesSchema with the delValuesSchema method.
+   * @param valuesSchema The ValuesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the ValuesSchema of a Store after it has been created.
+   *
+   * ```js
+   * const store = createStore().setValuesSchema({
+   *   open: {type: 'boolean', default: false},
+   * });
+   * store.setValue('open', 'maybe');
+   *
+   * console.log(store.getValues());
+   * // -> {open: false}
+   * ```
+   * @category Setter
+   * @since v3.0.0
+   */
+  setValuesSchema<VS extends ValuesSchema>(
+    valuesSchema: VS,
+  ): MergeableStore<[Schemas[0], typeof valuesSchema]>;
+
+  /**
+   * The setSchema method lets you specify the TablesSchema and ValuesSchema of
+   * the Store.
+   *
+   * Note that this may result in a change to data in the Store, as defaults are
+   * applied or as invalid Table, Row, Cell, or Value objects are removed. These
+   * changes will fire any listeners to that data, as expected.
+   *
+   * From v3.0 onwards, this method takes two arguments. The first is the
+   * TablesSchema object, the second the ValuesSchema. In previous versions
+   * (before the existence of the ValuesSchema data structure), only the first
+   * was present. For backwards compatibility the new second parameter is
+   * optional.
+   * @param tablesSchema The TablesSchema to be set for the Store.
+   * @param valuesSchema The ValuesSchema to be set for the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example sets the TablesSchema and ValuesSchema of a Store after it has
+   * been created.
+   *
+   * ```js
+   * const store = createStore().setSchema(
+   *   {
+   *     pets: {
+   *       species: {type: 'string'},
+   *       sold: {type: 'boolean', default: false},
+   *     },
+   *   },
+   *   {open: {type: 'boolean', default: false}},
+   * );
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   * store.setValue('open', 'maybe');
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * console.log(store.getValues());
+   * // -> {open: false}
+   * ```
+   * @example
+   * This example sets just the TablesSchema of a Store after it has been
+   * created.
+   *
+   * ```js
+   * const store = createStore().setSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     sold: {type: 'boolean', default: false},
+   *   },
+   * });
+   * store.addRow('pets', {species: 'dog', color: 'brown', sold: 'maybe'});
+   *
+   * console.log(store.getTables());
+   * // -> {pets: {0: {species: 'dog', sold: false}}}
+   * ```
+   * @category Setter
+   */
+  setSchema<TS extends TablesSchema, VS extends ValuesSchema>(
+    tablesSchema: TS,
+    valuesSchema?: VS,
+  ): MergeableStore<
+    [
+      typeof tablesSchema,
+      Exclude<ValuesSchema, typeof valuesSchema> extends never
+        ? NoValuesSchema
+        : NonNullable<typeof valuesSchema>,
+    ]
+  >;
+
+  /**
+   * The delTablesSchema method lets you remove the TablesSchema of the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the TablesSchema of a Store.
+   *
+   * ```js
+   * const store = createStore().setTablesSchema({
+   *   pets: {species: {type: 'string'}},
+   * });
+   * store.delTablesSchema();
+   * console.log(store.getTablesSchemaJson());
+   * // -> '{}'
+   * ```
+   * @category Deleter
+   */
+  delTablesSchema<
+    ValuesSchema extends OptionalValuesSchema = Schemas[1],
+  >(): MergeableStore<[NoTablesSchema, ValuesSchema]>;
+
+  /**
+   * The delValuesSchema method lets you remove the ValuesSchema of the Store.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the ValuesSchema of a Store.
+   *
+   * ```js
+   * const store = createStore().setValuesSchema({
+   *   sold: {type: 'boolean', default: false},
+   * });
+   * store.delValuesSchema();
+   * console.log(store.getValuesSchemaJson());
+   * // -> '{}'
+   * ```
+   * @category Deleter
+   * @since v3.0.0
+   */
+  delValuesSchema<
+    TablesSchema extends OptionalTablesSchema = Schemas[0],
+  >(): MergeableStore<[TablesSchema, NoValuesSchema]>;
+
+  /**
+   * The delSchema method lets you remove both the TablesSchema and ValuesSchema
+   * of the Store.
+   *
+   * Prior to v3.0, this method removed the TablesSchema only.
+   * @returns A reference to the Store.
+   * @example
+   * This example removes the TablesSchema and ValuesSchema of a Store.
+   *
+   * ```js
+   * const store = createStore()
+   *   .setTablesSchema({
+   *     pets: {species: {type: 'string'}},
+   *   })
+   *   .setValuesSchema({
+   *     sold: {type: 'boolean', default: false},
+   *   });
+   * store.delSchema();
+   * console.log(store.getSchemaJson());
+   * // -> '[{},{}]'
+   * ```
+   * @category Deleter
+   * @since v3.0.0
+   */
+  delSchema(): MergeableStore<NoSchemas>;
+}
+
+/**
+ * The createMergeableStore function
+ * @category Creation
+ */
+export function createMergeableStore(id: Id): MergeableStore<NoSchemas>;

package/lib/types/with-schemas/metrics.d.ts

@@ -11,8 +11,8 @@
  */
 
 import {CellIdFromSchema, TableIdFromSchema} from './internal/store';
-import {GetCell, OptionalSchemas, Store} from './store.d';
-import {Id, IdOrNull, Ids} from './common.d';
+import {GetCell, OptionalSchemas, Store} from './store.d.ts';
+import {Id, IdOrNull, Ids} from './common.d.ts';
 
 /**
  * The Metric type is simply an alias, but represents a number formed by

package/lib/types/with-schemas/persisters/persister-automerge.d.ts

@@ -12,7 +12,7 @@
  */
 
 import {OptionalSchemas, Store} from '../store';
-import {DocHandle} from 'automerge-repo';
+import {DocHandle} from '@automerge/automerge-repo';
 import {Persister} from '../persisters';
 
 /**
@@ -21,6 +21,10 @@ import {Persister} from '../persisters';
  *
  * It simply provides an extra getDocHandle method for accessing the Automerge
  * document handler the Store is being persisted to.
+ *
+ * You should use the createAutomergePersister function to create an
+ * AutomergePersister object.
+ * @category Persister
  * @since v4.3.14
  */
 export interface AutomergePersister<Schemas extends OptionalSchemas>
@@ -46,7 +50,7 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
    * @category Getter
    * @since v4.3.14
    */
-  getDocHandle: () => DocHandle<any>;
+  getDocHandle(): DocHandle<any>;
 }
 
 /**
@@ -86,7 +90,7 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  * await persister.save();
  * // Store will be saved to the document.
  *
- * console.log(docHandler.doc);
+ * console.log(await docHandler.doc());
  * // -> {tinybase: {t: {pets: {fido: {species: 'dog'}}}, v: {}}}
  *
  * persister.destroy();
@@ -102,7 +106,7 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  *   network: [new BroadcastChannelNetworkAdapter()],
  * });
  * const docHandler1 = repo1.create();
- * await docHandler1.value();
+ * await docHandler1.doc();
  * const store1 = createStore();
  * const persister1 = createAutomergePersister(store1, docHandler1);
  * await persister1.startAutoLoad();
@@ -113,7 +117,7 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  *   network: [new BroadcastChannelNetworkAdapter()],
  * });
  * const docHandler2 = repo2.find(docHandler1.documentId);
- * await docHandler2.value();
+ * await docHandler2.doc();
  * const store2 = createStore();
  * const persister2 = createAutomergePersister(store2, docHandler2);
  * await persister2.startAutoLoad();
@@ -122,9 +126,9 @@ export interface AutomergePersister<Schemas extends OptionalSchemas>
  * // A function that waits briefly and then for the documents to synchronize
  * // with each other, merely for the purposes of sequentiality in this example.
  * const syncDocsWait = async () => {
- *   await new Promise((resolve) => setTimeout(() => resolve(0), 10));
- *   await docHandler1.value();
- *   await docHandler2.value();
+ *   await new Promise((resolve) => setTimeout(() => resolve(0), 100));
+ *   await docHandler1.doc();
+ *   await docHandler2.doc();
  * };
  *
  * // Wait for the documents to synchronize in their initial state.

package/lib/types/with-schemas/persisters/persister-browser.d.ts

@@ -15,6 +15,7 @@
  */
 
 import {OptionalSchemas, Store} from '../store';
+import {MergeableStore} from '../mergeable-store';
 import {Persister} from '../persisters';
 
 /**
@@ -23,10 +24,14 @@ import {Persister} from '../persisters';
  *
  * It simply provides an extra getStorageName method for accessing the unique
  * key of the storage location the Store is being persisted to.
+ *
+ * You should use the createSessionPersister function to create a
+ * SessionPersister object.
+ * @category Persister
  * @since v4.3.14
  */
 export interface SessionPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+  extends Persister<Schemas, true> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.
@@ -47,7 +52,7 @@ export interface SessionPersister<Schemas extends OptionalSchemas>
    * @category Getter
    * @since v4.3.14
    */
-  getStorageName: () => string;
+  getStorageName(): string;
 }
 
 /**
@@ -55,10 +60,14 @@ export interface SessionPersister<Schemas extends OptionalSchemas>
  *
  * It simply provides an extra getStorageName method for accessing the unique
  * key of the storage location the Store is being persisted to.
+ *
+ * You should use the createLocalPersister function to create a LocalPersister
+ * object.
+ * @category Persister
  * @since v4.3.14
  */
 export interface LocalPersister<Schemas extends OptionalSchemas>
-  extends Persister<Schemas> {
+  extends Persister<Schemas, true> {
   /**
    * The getStorageName method returns the unique key of the storage location
    * the Store is being persisted to.
@@ -79,7 +88,7 @@ export interface LocalPersister<Schemas extends OptionalSchemas>
    * @category Getter
    * @since v4.3.14
    */
-  getStorageName: () => string;
+  getStorageName(): string;
 }
 
 /**
@@ -90,7 +99,7 @@ export interface LocalPersister<Schemas extends OptionalSchemas>
  *
  * ```ts override
  * createSessionPersister(
- *   store: Store,
+ *   store: Store | MergeableStore,
  *   storageName: string,
  *   onIgnoredError?: (error: any) => void,
  * ): SessionPersister;
@@ -123,7 +132,7 @@ export interface LocalPersister<Schemas extends OptionalSchemas>
  * @category Creation
  */
 export function createSessionPersister<Schemas extends OptionalSchemas>(
-  store: Store<Schemas>,
+  store: Store<Schemas> | MergeableStore<Schemas>,
   storageName: string,
   onIgnoredError?: (error: any) => void,
 ): SessionPersister<Schemas>;
@@ -136,7 +145,7 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
  *
  * ```ts override
  * createLocalPersister(
- *   store: Store,
+ *   store: Store | MergeableStore,
  *   storageName: string,
  *   onIgnoredError?: (error: any) => void,
  * ): LocalPersister;
@@ -169,7 +178,7 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
  * @category Creation
  */
 export function createLocalPersister<Schemas extends OptionalSchemas>(
-  store: Store<Schemas>,
+  store: Store<Schemas> | MergeableStore<Schemas>,
   storageName: string,
   onIgnoredError?: (error: any) => void,
 ): LocalPersister<Schemas>;

package/lib/types/with-schemas/persisters/persister-cr-sqlite-wasm.d.ts

@@ -18,6 +18,10 @@ import {DB} from '@vlcn.io/crsqlite-wasm';
  *
  * It simply provides an extra getDb method for accessing a reference to the
  * database instance the Store is being persisted to.
+ *
+ * You should use the createCrSqliteWasmPersister function to create a
+ * CrSqliteWasmPersister object.
+ * @category Persister
  * @since v4.3.14
  */
 export interface CrSqliteWasmPersister<Schemas extends OptionalSchemas>
@@ -44,7 +48,7 @@ export interface CrSqliteWasmPersister<Schemas extends OptionalSchemas>
    * @category Getter
    * @since v4.3.14
    */
-  getDb: () => DB;
+  getDb(): DB;
 }
 
 /**

package/lib/types/with-schemas/persisters/persister-electric-sql.d.ts

@@ -18,6 +18,10 @@ import {ElectricClient} from 'electric-sql/client/model';
  *
  * It simply provides an extra getElectricClient method for accessing a
  * reference to the Electric client the Store is being persisted to.
+ *
+ * You should use the createElectricSqlPersister function to create an
+ * ElectricSqlPersister object.
+ * @category Persister
  * @since v4.6.0
  */
 export interface ElectricSqlPersister<Schemas extends OptionalSchemas>
@@ -51,7 +55,7 @@ export interface ElectricSqlPersister<Schemas extends OptionalSchemas>
    * @category Getter
    * @since v4.6.0
    */
-  getElectricClient: () => ElectricClient<any>;
+  getElectricClient(): ElectricClient<any>;
 }
 
 /**