tinybase 5.0.0-beta.1 → 5.0.0-beta.3

package/lib/types/persisters.d.ts

@@ -38,7 +38,8 @@
  * @module persisters
  */
 
-import {GetTransactionChanges, Store, Tables, Values} from './store.d';
+import {Changes, Content, Store, Tables, Values} from './store.d';
+import {MergeableContent, MergeableStore} from './mergeable-store';
 import {Id} from './common.d';
 
 /**
@@ -64,22 +65,21 @@ export type PersisterStats = {
  * A PersisterListener is a callback that lets a Persister inform the Store that
  * a change has happened to the underlying data.
  *
- * If the listener has the `getTransactionChanges` parameter, it will be used to
- * make an incremental change to the Store. If not, but the `getContent`
- * function _is_ available, that will be used to make a wholesale change to the
- * Store. If neither are present, the content will be loaded from the
- * Persister's load method.
+ * If the listener has the `getChanges` parameter, it will be used to make an
+ * incremental change to the Store. If not, but the `getContent` function _is_
+ * available, that will be used to make a wholesale change to the Store. If
+ * neither are present, the content will be loaded from the Persister's load
+ * method.
  * @param getContent An optional function that, if provided, returns an array of
  * Store content and can be used to immediately wholesale update the Store.
- * @param getTransactionChanges An optional function that, if provided, returns
- * a TransactionChanges object and can be used to immediately incrementally
- * update the Store.
+ * @param getChanges An optional function that, if provided, returns a Changes
+ * object and can be used to immediately incrementally update the Store.
  * @category Creation
  * @since v4.0.0
  */
 export type PersisterListener = (
-  getContent?: () => [Tables, Values],
-  getTransactionChanges?: GetTransactionChanges,
+  getContent?: () => Content,
+  getChanges?: () => Changes,
 ) => void;
 
 /**
@@ -548,9 +548,9 @@ export type DpcTabularValues = {
  *
  * Creating a Persister depends on the choice of underlying storage where the
  * data is to be stored. Options include the createSessionPersister function,
- * the createLocalPersister, the createRemotePersister function, and the
- * createFilePersister function. The createCustomPersister function can also be
- * used to easily create a fully customized way to save and load Store data.
+ * the createLocalPersister function, the createRemotePersister function, and
+ * the createFilePersister function. The createCustomPersister function can also
+ * be used to easily create a fully customized way to save and load Store data.
  *
  * A Persister lets you explicit save or load data, with the save method and the
  * load method respectively. These methods are both asynchronous (since the
@@ -640,7 +640,7 @@ export type DpcTabularValues = {
  * ```
  * @category Persister
  */
-export interface Persister {
+export interface Persister<SupportsMergeableStore extends boolean = false> {
   //
   /**
    * The load method gets persisted data from storage, and loads it into the
@@ -701,7 +701,10 @@ export interface Persister {
    * ```
    * @category Load
    */
-  load(initialTables?: Tables, initialValues?: Values): Promise<Persister>;
+  load(
+    initialTables?: Tables,
+    initialValues?: Values,
+  ): Promise<Persister<SupportsMergeableStore>>;
 
   /**
    * The startAutoLoad method gets persisted data from storage, and loads it
@@ -759,7 +762,7 @@ export interface Persister {
   startAutoLoad(
     initialTables?: Tables,
     initialValues?: Values,
-  ): Promise<Persister>;
+  ): Promise<Persister<SupportsMergeableStore>>;
 
   /**
    * The stopAutoLoad method stops the automatic loading of data from storage
@@ -803,7 +806,7 @@ export interface Persister {
    * ```
    * @category Load
    */
-  stopAutoLoad(): Persister;
+  stopAutoLoad(): Persister<SupportsMergeableStore>;
 
   /**
    * The save method takes data from the Store with which the Persister is
@@ -831,7 +834,7 @@ export interface Persister {
    * ```
    * @category Save
    */
-  save(): Promise<Persister>;
+  save(): Promise<Persister<SupportsMergeableStore>>;
 
   /**
    * The save method takes data from the Store with which the Persister is
@@ -868,7 +871,7 @@ export interface Persister {
    * ```
    * @category Save
    */
-  startAutoSave(): Promise<Persister>;
+  startAutoSave(): Promise<Persister<SupportsMergeableStore>>;
 
   /**
    * The stopAutoSave method stops the automatic save of data to storage
@@ -905,7 +908,7 @@ export interface Persister {
    * ```
    * @category Save
    */
-  stopAutoSave(): Persister;
+  stopAutoSave(): Persister<SupportsMergeableStore>;
 
   /**
    * The schedule method allows you to queue up a series of asynchronous actions
@@ -948,7 +951,9 @@ export interface Persister {
    * @category Lifecycle
    * @since v4.0.0
    */
-  schedule(...actions: Promise<any>[]): Promise<Persister>;
+  schedule(
+    ...actions: Promise<any>[]
+  ): Promise<Persister<SupportsMergeableStore>>;
 
   /**
    * The getStore method returns a reference to the underlying Store that is
@@ -971,7 +976,9 @@ export interface Persister {
    * ```
    * @category Getter
    */
-  getStore(): Store;
+  getStore(): SupportsMergeableStore extends true
+    ? Store | MergeableStore
+    : Store;
 
   /**
    * The destroy method should be called when this Persister object is no longer
@@ -1001,7 +1008,7 @@ export interface Persister {
    * ```
    * @category Lifecycle
    */
-  destroy(): Persister;
+  destroy(): Persister<SupportsMergeableStore>;
 
   /**
    * The getStats method provides a set of statistics about the Persister, and
@@ -1086,6 +1093,9 @@ export interface Persister {
  * @param onIgnoredError An optional handler for the errors that the Persister
  * would otherwise ignore when trying to save or load data. This is suitable for
  * debugging persistence issues in a development environment, since v4.0.4.
+ * @param supportsMergeableStore An optional boolean to indicate that this
+ * Persister will be able to handle MergeableStore persistence as well as
+ * regular Store persistence, since v5.0.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a custom Persister object and persists the Store to a
@@ -1124,14 +1134,24 @@ export interface Persister {
  * ```
  * @category Creation
  */
-export function createCustomPersister<ListeningHandle>(
-  store: Store,
-  getPersisted: () => Promise<[Tables, Values] | undefined>,
+export function createCustomPersister<
+  ListeningHandle,
+  SupportsMergeableStore extends boolean,
+>(
+  store: Store | (SupportsMergeableStore extends true ? MergeableStore : never),
+  getPersisted: () => Promise<
+    | Content
+    | (SupportsMergeableStore extends true ? MergeableContent : never)
+    | undefined
+  >,
   setPersisted: (
-    getContent: () => [Tables, Values],
-    getTransactionChanges?: GetTransactionChanges,
+    getContent: () =>
+      | Content
+      | (SupportsMergeableStore extends true ? MergeableContent : never),
+    getChanges?: () => Changes,
   ) => Promise<void>,
   addPersisterListener: (listener: PersisterListener) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
   onIgnoredError?: (error: any) => void,
-): Persister;
+  supportsMergeableStore?: SupportsMergeableStore,
+): Persister<SupportsMergeableStore>;