tinybase 5.0.0-beta.2 → 5.0.0-beta.3

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

@@ -39,13 +39,15 @@
  */
 
 import {
-  GetTransactionChanges,
+  Changes,
+  Content,
   OptionalSchemas,
   OptionalTablesSchema,
   Store,
   Tables,
   Values,
 } from './store.d';
+import {MergeableContent, MergeableStore} from './mergeable-store';
 import {TableIdFromSchema} from './internal/store';
 
 /**
@@ -75,27 +77,26 @@ export type PersisterStats = {
  *
  * ```ts override
  * (
- *   getContent?: () => [Tables, Values],
- *   getTransactionChanges?: GetTransactionChanges,
+ *   getContent?: () => Content,
+ *   getChanges?: () => Changes,
  * ) => void;
  * ```
  *
- * 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<Schemas extends OptionalSchemas> = (
-  getContent?: () => [Tables<Schemas[0], true>, Values<Schemas[1], true>],
-  getTransactionChanges?: GetTransactionChanges<Schemas>,
+  getContent?: () => Content<Schemas, true>,
+  getChanges?: () => Changes<Schemas>,
 ) => void;
 
 /**
@@ -664,7 +665,10 @@ export type DpcTabularValues = {
  * ```
  * @category Persister
  */
-export interface Persister<in out Schemas extends OptionalSchemas> {
+export interface Persister<
+  in out Schemas extends OptionalSchemas,
+  SupportsMergeableStore extends boolean = false,
+> {
   /**
    * The load method gets persisted data from storage, and loads it into the
    * Store with which the Persister is associated, once.
@@ -672,7 +676,10 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * load(initialTables?: Tables, initialValues?: Values): Promise<Persister>;
+   * load(
+   *   initialTables?: Tables,
+   *   initialValues?: Values,
+   * ): Promise<Persister<SupportsMergeableStore>>;
    * ```
    *
    * The optional parameters allow you to specify what the initial content for
@@ -733,7 +740,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
   load(
     initialTables?: Tables<Schemas[0], true>,
     initialValues?: Values<Schemas[1], true>,
-  ): Promise<Persister<Schemas>>;
+  ): Promise<Persister<Schemas, SupportsMergeableStore>>;
 
   /**
    * The startAutoLoad method gets persisted data from storage, and loads it
@@ -746,7 +753,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * startAutoLoad(
    *   initialTables?: Tables,
    *   initialValues?: Values,
-   * ): Promise<Persister>;
+   * ): Promise<Persister<SupportsMergeableStore>>;
    * ```
    *
    * The optional parameters allow you to specify what the initial content for
@@ -800,7 +807,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
   startAutoLoad(
     initialTables?: Tables<Schemas[0], true>,
     initialValues?: Values<Schemas[1], true>,
-  ): Promise<Persister<Schemas>>;
+  ): Promise<Persister<Schemas, SupportsMergeableStore>>;
 
   /**
    * The stopAutoLoad method stops the automatic loading of data from storage
@@ -809,7 +816,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * stopAutoLoad(): Persister;
+   * stopAutoLoad(): Persister<SupportsMergeableStore>;
    * ```
    *
    * If the Persister is not currently set to automatically load, this method
@@ -850,7 +857,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Load
    */
-  stopAutoLoad(): Persister<Schemas>;
+  stopAutoLoad(): Persister<Schemas, SupportsMergeableStore>;
 
   /**
    * The save method takes data from the Store with which the Persister is
@@ -859,7 +866,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * save(): Promise<Persister>;
+   * save(): Promise<Persister<SupportsMergeableStore>>;
    * ```
    *
    * This method is asynchronous because the persisted data may be on a remote
@@ -884,7 +891,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Save
    */
-  save(): Promise<Persister<Schemas>>;
+  save(): Promise<Persister<Schemas, SupportsMergeableStore>>;
 
   /**
    * The save method takes data from the Store with which the Persister is
@@ -893,7 +900,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * startAutoSave(): Promise<Persister>;
+   * startAutoSave(): Promise<Persister<SupportsMergeableStore>>;
    * ```
    *
    * This method first runs a single call to the save method to ensure the data
@@ -927,7 +934,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Save
    */
-  startAutoSave(): Promise<Persister<Schemas>>;
+  startAutoSave(): Promise<Persister<Schemas, SupportsMergeableStore>>;
 
   /**
    * The stopAutoSave method stops the automatic save of data to storage
@@ -936,7 +943,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * stopAutoSave(): Persister;
+   * stopAutoSave(): Persister<SupportsMergeableStore>;
    * ```
    *
    * If the Persister is not currently set to automatically save, this method
@@ -970,7 +977,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Save
    */
-  stopAutoSave(): Persister<Schemas>;
+  stopAutoSave(): Persister<Schemas, SupportsMergeableStore>;
 
   /**
    * The schedule method allows you to queue up a series of asynchronous actions
@@ -979,7 +986,9 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * schedule(...actions: Promise<any>[]): Promise<Persister>;
+   * schedule(
+   *   ...actions: Promise<any>[]
+   * ): Promise<Persister<SupportsMergeableStore>>;
    * ```
    *
    * For example, a database Persister may need to ensure that multiple
@@ -1019,7 +1028,9 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * @category Lifecycle
    * @since v4.0.0
    */
-  schedule(...actions: Promise<any>[]): Promise<Persister<Schemas>>;
+  schedule(
+    ...actions: Promise<any>[]
+  ): Promise<Persister<Schemas, SupportsMergeableStore>>;
 
   /**
    * The getStore method returns a reference to the underlying Store that is
@@ -1032,7 +1043,9 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * getStore(): Store;
+   * getStore(): SupportsMergeableStore extends true
+   *   ? Store | MergeableStore
+   *   : Store;
    * ```
    *
    * ```js
@@ -1057,7 +1070,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * This has schema-based typing. The following is a simplified representation:
    *
    * ```ts override
-   * destroy(): Persister;
+   * destroy(): Persister<SupportsMergeableStore>;
    * ```
    *
    * This guarantees that all of the listeners that the object registered with
@@ -1084,7 +1097,7 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ```
    * @category Lifecycle
    */
-  destroy(): Persister<Schemas>;
+  destroy(): Persister<Schemas, SupportsMergeableStore>;
 
   /**
    * The getStats method provides a set of statistics about the Persister, and
@@ -1138,17 +1151,27 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * createCustomPersister<ListeningHandle>(
- *   store: Store,
- *   getPersisted: () => Promise<[Tables, Values] | undefined>,
+ * 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>;
  * ```
  *
  * As well as providing a reference to the Store to persist, you must provide
@@ -1184,6 +1207,9 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
  * @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
@@ -1225,18 +1251,28 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
 export function createCustomPersister<
   Schemas extends OptionalSchemas,
   ListeningHandle,
+  SupportsMergeableStore extends boolean,
 >(
-  store: Store<Schemas>,
+  store:
+    | Store<Schemas>
+    | (SupportsMergeableStore extends true ? MergeableStore<Schemas> : never),
   getPersisted: () => Promise<
-    [Tables<Schemas[0]>, Values<Schemas[1]>] | undefined
+    | Content<Schemas>
+    | (SupportsMergeableStore extends true ? MergeableContent<Schemas> : never)
+    | undefined
   >,
   setPersisted: (
-    getContent: () => [Tables<Schemas[0]>, Values<Schemas[1]>],
-    getTransactionChanges?: GetTransactionChanges<Schemas>,
+    getContent: () =>
+      | Content<Schemas>
+      | (SupportsMergeableStore extends true
+          ? MergeableContent<Schemas>
+          : never),
+    getChanges?: () => Changes<Schemas>,
   ) => Promise<void>,
   addPersisterListener: (
     listener: PersisterListener<Schemas>,
   ) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
   onIgnoredError?: (error: any) => void,
-): Persister<Schemas>;
+  supportsMergeableStore?: SupportsMergeableStore,
+): Persister<Schemas, SupportsMergeableStore>;