/**
 * The persisters module of the TinyBase project provides a simple framework for
 * saving and loading Store and MergeableStore data, to and from different
 * destinations, or underlying storage types.
 *
 * Many entry points are provided (in separately installed modules), each of
 * which returns different types of Persister that can load and save a Store.
 * Between them, these allow you to store your TinyBase data locally, remotely,
 * to SQLite databases, and across synchronization boundaries with CRDT
 * frameworks.
 *
 * |Persister|Storage|Store|MergeableStore
 * |-|-|-|-|
 * |SessionPersister|Browser session storage|Yes|Yes
 * |LocalPersister|Browser local storage|Yes|Yes
 * |FilePersister|Local file (where possible)|Yes|Yes
 * |IndexedDbPersister|Browser IndexedDB|Yes|No
 * |RemotePersister|Remote server|Yes|No
 * |Sqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|Yes|Yes*
 * |SqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|Yes|Yes*
 * |ExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|Yes|Yes*
 * |CrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|Yes|No
 * |ElectricSqlPersister|Electric SQL, via [electric-sql](https://github.com/electric-sql/electric)|Yes|No
 * |LibSqlPersister|LibSQL for Turso, via [libsql-client](https://github.com/tursodatabase/libsql-client-ts)|Yes|No
 * |PowerSyncPersister|PowerSync, via [powersync-sdk](https://github.com/powersync-ja/powersync-js)|Yes|No
 * |YjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|Yes|No
 * |AutomergePersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|Yes|No
 * |PartyKitPersister|[PartyKit](https://www.partykit.io/), via the persister-partykit-server module|Yes|No|
 *
 * (*) Note that SQLite-based Persisters can currently only persist
 * MergeableStore data when using the JSON-based DpcJson mode, and not in a
 * tabular fashion.
 *
 * Since persistence requirements can be different for every app, the
 * createCustomPersister function in this module can also be used to easily
 * create a fully customized way to save and load Store data.
 * @see Persistence guides
 * @see Countries demo
 * @see Todo App demos
 * @see Drawing demo
 * @packageDocumentation
 * @module persisters
 * @since v1.0.0
 */

import type {Changes, Content, Store} from '../store/index.d.cts';
import type {
  MergeableChanges,
  MergeableContent,
  MergeableStore,
} from '../mergeable-store/index.d.cts';
import type {Id} from '../common/index.d.cts';

/**
 * The Persists enum is used to indicate whether a Persister can support a
 * regular Store, a MergeableStore, or both.
 *
 * The enum is intended to be used by the author of a Persister to indicate
 * which types of store can be persisted. If you discover type errors when
 * trying to instantiate a Persister, it is most likely that you are passing in
 * an unsupported type of store.
 *
 * See the createCustomPersister method for an example of this enum being used.
 * @category Mergeable
 * @since v5.0.0
 */
export const enum Persists {
  /**
   * Indicates that only a regular Store can be supported by a Persister.
   * @category Enum
   * @since v5.0.0
   */
  StoreOnly = 1,
  /**
   * Indicates that only a MergeableStore can be supported by a Persister.
   * @category Enum
   * @since v5.0.0
   */
  MergeableStoreOnly = 2,
  /**
   * Indicates that either a regular Store or a MergeableStore can be supported
   * by a Persister.
   * @category Enum
   * @since v5.0.0
   */
  StoreOrMergeableStore = 3,
}

/**
 * The PersistedStore type is a generic representation of the type of store
 * being handled by a Persister.
 *
 * Using the values of the Persists enum, the generic parameter indicates
 * whether the Persister is handling a regular Store, a MergeableStore, or
 * either.
 *
 * If the generic parameter is unspecified, the StoreOnly enum value is used,
 * meaning that PersistedStore is equivalent to a regular Store.
 * @category Mergeable
 * @since v5.0.0
 */
export type PersistedStore<Persist extends Persists = Persists.StoreOnly> =
  Persist extends Persists.StoreOrMergeableStore
    ? Store | MergeableStore
    : Persist extends Persists.MergeableStoreOnly
      ? MergeableStore
      : Store;

/**
 * The PersistedContent type is a generic representation of the content in the
 * type of store being handled by a Persister.
 *
 * Using the values of the Persists enum, the generic parameter indicates
 * whether the Persister is handling content from a regular Store (the Content
 * type), a MergeableStore (the MergeableContent type), or either (the union of
 * the two).
 *
 * If the generic parameter is unspecified, the StoreOnly enum value is used,
 * meaning that PersistedContent is equivalent to the Content type.
 * @category Mergeable
 * @since v5.0.0
 */
export type PersistedContent<Persist extends Persists = Persists.StoreOnly> =
  Persist extends Persists.StoreOrMergeableStore
    ? Content | MergeableContent
    : Persist extends Persists.MergeableStoreOnly
      ? MergeableContent
      : Content;

/**
 * The PersistedChanges type is a generic representation of changes made to the
 * type of store being handled by a Persister.
 *
 * Using the values of the Persists enum, the generic parameter indicates
 * whether the Persister is handling changes for a regular Store (the Changes
 * type), a MergeableStore (the MergeableChanges type), or either (the union of
 * the two).
 * @category Mergeable
 * @since v5.0.0
 */
export type PersistedChanges<Persist extends Persists = Persists.StoreOnly> =
  Persist extends Persists.StoreOrMergeableStore
    ? Changes | MergeableChanges
    : Persist extends Persists.MergeableStoreOnly
      ? MergeableChanges
      : Changes;

/**
 * A PersisterListener is a generic representation of the callback that lets a
 * Persister inform the store that a change has happened to the underlying data.
 *
 * Using the values of the Persists enum, the generic parameter indicates
 * whether the Persister is handling content and changes from a regular Store, a
 * MergeableStore, or either.
 *
 * If the listener is called with the `changes` parameter, it will be used to
 * make an incremental change to the Store. If not, but the `content` parameter
 * is available, that will be used to make a wholesale change to the Store. If
 * neither are present, the content will be loaded using the Persister's load
 * method. Prior to v5.0, these parameters were callbacks and the overall type
 * was non-generic.
 * @param content If provided, this is a Content object from the the Persister
 * that will be used to immediately wholesale update the Store.
 * @param changes If provided, this is a Changes object from the the Persister
 * that will be used to immediately incrementally update the Store. This takes
 * priority over the content argument above if present.
 * @category Creation
 * @since v4.0.0
 */
export type PersisterListener<Persist extends Persists = Persists.StoreOnly> = (
  content?: PersistedContent<Persist>,
  changes?: PersistedChanges<Persist>,
) => void;

/**
 * The PersisterStats type describes the number of times a Persister object has
 * loaded or saved data.
 *
 * A PersisterStats object is returned from the getStats method.
 * @category Development
 * @since v1.0.0
 */
export type PersisterStats = {
  /**
   * The number of times data has been loaded.
   * @category Stat
   * @since v1.0.0
   */
  loads: number;
  /**
   * The number of times data has been saved.
   * @category Stat
   * @since v1.0.0
   */
  saves: number;
};

/**
 * The DatabasePersisterConfig type describes the configuration of a
 * database-oriented Persister, such as those for SQLite.
 *
 * There are two modes for persisting a Store with a database:
 *
 * - A JSON serialization of the whole Store, which is stored in a single row of
 *   a table (normally called `tinybase`) within the database. This is
 *   configured by providing a DpcJson object.
 * - A tabular mapping of Table Ids to database table names (and vice-versa).
 *   Values are stored in a separate special table (normally called
 *   `tinybase_values`). This is configured by providing a DpcTabular object.
 *
 * Please see the DpcJson and DpcTabular type documentation for more detail on
 * each. If not specified otherwise, JSON serialization will be used for
 * persistence.
 *
 * Changes made to the database (outside of this Persister) are picked up
 * immediately if they are made via the same connection or library that it is
 * using. If the database is being changed by another client, the Persister
 * needs to poll for changes. Hence both configuration types also contain an
 * `autoLoadIntervalSeconds` property which indicates how often it should do
 * that. This defaults to 1 second.
 *
 * Note that all the nested types within this type have a 'Dpc' prefix, short
 * for 'DatabasePersisterConfig'.
 * @example
 * When applied to a database Persister, this DatabasePersisterConfig will load
 * and save a JSON serialization from and to a table called `my_tinybase`,
 * polling the database every 2 seconds. See DpcJson for more details on these
 * settings.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'json',
 *   storeTableName: 'my_tinybase',
 *   autoLoadIntervalSeconds: 2,
 * };
 * ```
 * @example
 * When applied to a database Persister, this DatabasePersisterConfig will load
 * and save tabular data from and to tables specified in the `load` and `save`
 * mappings. See DpcTabular for more details on these settings.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'tabular',
 *   tables: {
 *     load: {petsInDb: 'pets', speciesInDb: 'species'},
 *     save: {pets: 'petsInDb', species: 'speciesInDb'},
 *   },
 * };
 * ```
 * @category Configuration
 * @since v4.0.0
 */
export type DatabasePersisterConfig = DpcJson | DpcTabular;

/**
 * The DpcJson type describes the configuration of a database-oriented Persister
 * operating in serialized JSON mode.
 *
 * One setting is the `storeTableName` property, which indicates the name of a
 * table in the database which will be used to serialize the Store content into.
 * It defaults to `tinybase`.
 *
 * That table in the database will be given two columns: a primary key column
 * called `_id`, and one called `store`. (These column names can be changed
 * using the `rowIdColumnName` and `storeColumnName` settings). The Persister
 * will place a single row in this table with `_` in the `_id` column, and the
 * JSON serialization in the `store` column, something like the following.
 *
 * ```
 * > SELECT * FROM tinybase;
 * +-----+-----------------------------------------------------+
 * | _id | store                                               |
 * +-----+-----------------------------------------------------+
 * | _   | [{"pets":{"fido":{"species":"dog"}}},{"open":true}] |
 * +-----+-----------------------------------------------------+
 * ```
 *
 * The 'Dpc' prefix indicates that this type is used within the
 * DatabasePersisterConfig type.
 * @example
 * When applied to a database Persister, this DatabasePersisterConfig will load
 * and save a JSON serialization from and to a table called `tinybase_json`.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'json',
 *   storeTableName: 'tinybase_json',
 * };
 * ```
 * @category Configuration
 * @since v4.0.0
 */
export type DpcJson = {
  /**
   * The mode to be used for persisting the Store to the database, in this case
   * JSON serialization. See the DpcTabular type for the alternative tabular
   * mapping mode.
   * @category Configuration
   * @since v4.0.0
   */
  mode: 'json';
  /**
   * An optional string which indicates the name of a table in the database
   * which will be used to serialize the Store content into. It defaults to
   * `tinybase`.
   * @category Configuration
   * @since v4.0.0
   */
  storeTableName?: string;
  /**
   * The optional name of the column in the database table that will be used as
   * the Id for the Store, defaulting to '_id', since v5.0.
   * @category Configuration
   * @since v4.0.0
   */
  storeIdColumnName?: string;
  /**
   * The optional name of the column in the database table that will be used for
   * the JSON of the Store, defaulting to 'store', since v5.0.
   * @category Configuration
   * @since v4.0.0
   */
  storeColumnName?: string;
  /**
   * How often the Persister should poll the database for any changes made to it
   * by other clients, defaulting to 1 second.
   * @category Configuration
   * @since v4.0.0
   */
  autoLoadIntervalSeconds?: number;
};

/**
 * The DpcTabular type describes the configuration of a database-oriented
 * Persister that is operating in tabular mapping mode.
 *
 * This configuration can only be used when the Persister is persisting a
 * regular Store. For those database-oriented Persister types that support
 * MergeableStore data, you will need to use JSON-serialization, es described
 * in the DpcJson section.
 *
 * It is important to note that both the tabular mapping in ('save') and out
 * ('load') of an underlying database are disabled by default. This is to ensure
 * that if you pass in an existing populated database you don't run the
 * immediate risk of corrupting or losing all your data.
 *
 * This configuration therefore takes a `tables` property object (with child
 * `load` and `save` property objects) and a `values` property object. These
 * indicate how you want to load and save Tables and Values respectively. At
 * least one of these two properties are required for the Persister to do
 * anything!
 *
 * Note that if you are planning to both load from and save to a database, it is
 * important to make sure that the load and save table mappings are symmetrical.
 * For example, consider the following.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'tabular',
 *   tables: {
 *     load: {petsInDb: 'pets', speciesInDb: 'species'},
 *     save: {pets: 'petsInDb', species: 'speciesInDb'},
 *   },
 * };
 * ```
 *
 * See the documentation for the DpcTabularLoad, DpcTabularSave, and
 * DpcTabularValues types for more details on how to configure the tabular
 * mapping mode.
 *
 * The 'Dpc' prefix indicates that this type is used within the
 * DatabasePersisterConfig type.
 * @example
 * When applied to a database Persister, this DatabasePersisterConfig will load
 * and save Tables data from and to tables specified in the `load` and `save`
 * mappings, and Values data from and to a table called `my_tinybase_values`.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'tabular',
 *   tables: {
 *     load: {petsInDb: 'pets', speciesInDb: 'species'},
 *     save: {pets: 'petsInDb', species: 'speciesInDb'},
 *   },
 *   values: {
 *     load: true,
 *     save: true,
 *     tableName: 'my_tinybase_values',
 *   },
 * };
 * ```
 * @category Configuration
 * @since v4.0.0
 */
export type DpcTabular = {
  /**
   * The mode to be used for persisting the Store to the database, in this case
   * tabular mapping. See the DpcJson type for the alternative JSON
   * serialization mode.
   * @category Configuration
   * @since v4.0.0
   */
  mode: 'tabular';
  /**
   * The settings for how the Store Tables are mapped to and from the database.
   * @category Configuration
   * @since v4.0.0
   */
  tables?: {
    /**
     * The settings for how the database tables are mapped into the Store Tables
     * when loading.
     * @category Configuration
     * @since v4.0.0
     */
    load?: DpcTabularLoad;
    /**
     * The settings for how the Store Tables are mapped out to the database
     * tables when saving.
     * @category Configuration
     * @since v4.0.0
     */
    save?: DpcTabularSave;
  };
  /**
   * The settings for how the Store Values are mapped to and from the database.
   * @category Configuration
   * @since v4.0.0
   */
  values?: DpcTabularValues;
  /**
   * How often the Persister should poll the database for any changes made to it
   * by other clients, defaulting to 1 second.
   * @category Configuration
   * @since v4.0.0
   */
  autoLoadIntervalSeconds?: number;
};

/**
 * The DpcTabularLoad type describes the configuration for loading Tables in a
 * database-oriented Persister that is operating in tabular mode.
 *
 * It is an object where each key is a name of a database table, and the value
 * is a child configuration object for how that table should be loaded into the
 * Store. The properties of the child configuration object are:
 *
 * ||Type|Description|
 * |-|-|-|
 * |`tableId`|Id|The Id of the Store Table into which data from this database table should be loaded.|
 * |`rowIdColumnName?`|string|The optional name of the column in the database table that will be used as the Row Ids in the Store Table, defaulting to '_id'.|
 *
 * As a shortcut, if you do not need to specify a custom `rowIdColumnName`, you
 * can simply provide the Id of the Store Table instead of the whole object.
 *
 * The 'Dpc' prefix indicates that this type is used within the
 * DatabasePersisterConfig type.
 * @example
 * When applied to a database Persister, this DatabasePersisterConfig will load
 * the data of two database tables (called 'petsInDb' and 'speciesInDb') into
 * two Store Tables (called 'pets' and 'species'). One has a column for the Row
 * Id called 'id' and the other defaults it to '_id'.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'tabular',
 *   tables: {
 *     load: {
 *       petsInDb: {tableId: 'pets', rowIdColumnName: 'id'},
 *       speciesInDb: 'species',
 *     },
 *   },
 * };
 * ```
 *
 * Imagine database tables that look like this:
 *
 * ```
 * > SELECT * FROM petsInDb;
 * +-------+---------+-------+
 * | id    | species | color |
 * +-------+---------+-------+
 * | fido  | dog     | brown |
 * | felix | cat     | black |
 * +-------+---------+-------+
 *
 * > SELECT * FROM speciesInDb;
 * +------+-------+
 * | _id  | price |
 * +------+-------+
 * | dog  | 5     |
 * | cat  | 4     |
 * +------+-------+
 * ```
 *
 * With the configuration above, this will load into a Store with Tables that
 * look like this:
 *
 * ```json
 * {
 *   "pets": {
 *     "fido": {"species": "dog", "color": "brown"},
 *     "felix": {"species": "cat", "color": "black"},
 *   },
 *   "species": {
 *     "dog": {"price": 5},
 *     "cat": {"price": 4},
 *   },
 * }
 * ```
 * @category Configuration
 * @since v4.0.0
 */
export type DpcTabularLoad = {
  [tableName: string]:
    | {
        /**
         * The Id of the Store Table into which data from this database table
         * should be loaded.
         * @category Configuration
         * @since v4.0.0
         */
        tableId: Id;
        /**
         * The optional name of the column in the database table that will be
         * used as the Row Ids in the Store Table, defaulting to '_id'.
         * @category Configuration
         * @since v4.0.0
         */
        rowIdColumnName?: string;
      }
    | Id;
};

/**
 * The DpcTabularSave type describes the configuration for saving Tables in a
 * database-oriented Persister that is operating in tabular mode.
 *
 * It is an object where each key is an Id of a Store Table, and the value is a
 * child configuration object for how that Table should be saved out to the
 * database. The properties of the child configuration object are:
 *
 * ||Type|Description|
 * |-|-|-|
 * |`tableName`|string|The name of the database table out to which the Store Table should be saved.|
 * |`rowIdColumnName?`|string|The optional name of the column in the database table that will be used to save the Row Ids from the Store Table, defaulting to '_id'.|
 * |`deleteEmptyColumns?`|boolean|Whether columns in the database table will be removed if they are empty in the Store Table, defaulting to false.|
 * |`deleteEmptyTable?`|boolean|Whether tables in the database will be removed if the Store Table is empty, defaulting to false.|
 *
 * As a shortcut, if you do not need to specify a custom `rowIdColumnName`, or
 * enable the `deleteEmptyColumns` or `deleteEmptyTable` settings, you can
 * simply provide the name of the database table instead of the whole object.
 *
 * `deleteEmptyColumns` and `deleteEmptyTable` only have a guaranteed effect
 * when an explicit call is made to the Persister's save method. Columns and
 * tables will not necessarily be removed when the Persister is incrementally
 * 'autoSaving', due to performance reasons. If you want to be sure that your
 * database table matches a TinyBase Table without any extraneous columns,
 * simply call the save method at an idle moment.
 *
 * The 'Dpc' prefix indicates that this type is used within the
 * DatabasePersisterConfig type.
 * @example
 * When applied to a database Persister, this DatabasePersisterConfig will save
 * the data of two Store Tables (called 'pets' and 'species') into two database
 * tables (called 'petsInDb' and 'speciesInDb'). One has a column for the Row
 * Id called 'id' and will delete columns and the whole table if empty, the
 * other defaults to '_id' and will not delete columns or the whole table if
 * empty.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'tabular',
 *   tables: {
 *     save: {
 *       pets: {
 *         tableName: 'petsInDb',
 *         deleteEmptyColumns: true,
 *         deleteEmptyTable: true,
 *       },
 *       species: 'speciesInDb',
 *     },
 *   },
 * };
 * ```
 *
 * Imagine a Store with Tables that look like this:
 *
 * ```json
 * {
 *   "pets": {
 *     "fido": {"species": "dog", "color": "brown"},
 *     "felix": {"species": "cat", "color": "black"},
 *   },
 *   "species": {
 *     "dog": {"price": 5},
 *     "cat": {"price": 4},
 *   },
 * }
 * ```
 *
 * With the configuration above, this will save out to a database with tables
 * that look like this:
 *
 * ```
 * > SELECT * FROM petsInDb;
 * +-------+---------+-------+
 * | id    | species | color |
 * +-------+---------+-------+
 * | fido  | dog     | brown |
 * | felix | cat     | black |
 * +-------+---------+-------+
 *
 * > SELECT * FROM speciesInDb;
 * +------+-------+
 * | _id  | price |
 * +------+-------+
 * | dog  | 5     |
 * | cat  | 4     |
 * +------+-------+
 * ```
 * @category Configuration
 * @since v4.0.0
 */
export type DpcTabularSave = {
  [tableId: Id]:
    | {
        /**
         * The name of the database table out to which the Store Table should be
         * saved.
         * @category Configuration
         * @since v4.0.0
         */
        tableName: string;
        /**
         * The optional name of the column in the database table that will be
         * used to save the Row Ids from the Store Table, defaulting to '_id'.
         * @category Configuration
         * @since v4.0.0
         */
        rowIdColumnName?: string;
        /**
         * Whether columns in the database table will be removed if they are
         * empty in the Store Table, defaulting to false.
         * @category Configuration
         * @since v4.0.0
         */
        deleteEmptyColumns?: boolean;
        /**
         * Whether tables in the database will be removed if the Store Table is
         * empty, defaulting to false.
         * @category Configuration
         * @since v4.0.0
         */
        deleteEmptyTable?: boolean;
      }
    | string;
};

/**
 * The DpcTabularValues type describes the configuration for handling Values in
 * a database-oriented Persister that is operating in tabular mode.
 *
 * Note that both loading and saving of Values from and to the database are
 * disabled by default.
 *
 * The 'Dpc' prefix indicates that this type is used within the
 * DatabasePersisterConfig type.
 * @example
 * When applied to a database Persister, this DatabasePersisterConfig will load
 * and save the data of a Store's Values into a database
 * table called 'my_tinybase_values'.
 *
 * ```js
 * import type {DatabasePersisterConfig} from 'tinybase';
 *
 * export const databasePersisterConfig: DatabasePersisterConfig = {
 *   mode: 'tabular',
 *   values: {
 *     load: true,
 *     save: true,
 *     tableName: 'my_tinybase_values',
 *   },
 * };
 * ```
 * @category Configuration
 * @since v4.0.0
 */
export type DpcTabularValues = {
  /**
   * Whether Store Values will be loaded from a database table.
   * @category Configuration
   * @since v4.0.0
   */
  load?: boolean;
  /**
   * Whether Store Values will be saved to a database table.
   * @category Configuration
   * @since v4.0.0
   */
  save?: boolean;
  /**
   * The optional name of the database table from and to which the Store Values
   * should be loaded or saved, defaulting to `tinybase_values`.
   * @category Configuration
   * @since v4.0.0
   */
  tableName?: string;
};

/**
 * A Persister object lets you save and load Store data to and from different
 * locations, or underlying storage types.
 *
 * This is useful for preserving Store or MergeableStore data between browser
 * sessions or reloads, saving or loading browser state to or from a server, or
 * saving Store data to disk in a environment with filesystem access.
 *
 * Creating a Persister depends on the choice of underlying storage where the
 * data is to be stored. Options include the createSessionPersister function,
 * the createLocalPersister function, the createRemotePersister function, and
 * the createFilePersister function, as just simple examples. The
 * createCustomPersister function can also be used to easily create a fully
 * customized way to save and load Store data.
 *
 * Using the values of the Persists enum, the generic parameter to the Persister
 * indicates whether it can handle a regular Store, a MergeableStore, or either.
 * Consult the table in the overall persisters module documentation to see
 * current support for each. The different levels of support are also described
 * for each of the types of Persister themselves.
 *
 * 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
 * underlying data storage may also be) and return promises. As a result you
 * should use the `await` keyword to call them in a way that guarantees
 * subsequent execution order.
 *
 * When you don't want to deal with explicit persistence operations, a Persister
 * object also provides automatic saving and loading. Automatic saving listens
 * for changes to the Store and persists the data immediately. Automatic loading
 * listens (or polls) for changes to the persisted data and reflects those
 * changes in the Store.
 *
 * You can start automatic saving or loading with the startAutoSave method and
 * startAutoLoad method. Both are asynchronous since they will do an immediate
 * save and load before starting to listen for subsequent changes. You can stop
 * the behavior with the stopAutoSave method and stopAutoLoad method (which are
 * synchronous).
 *
 * You may often want to have both automatic saving and loading of a Store so
 * that changes are constantly synchronized (allowing basic state preservation
 * between browser tabs, for example). The framework has some basic provisions
 * to prevent race conditions - for example it will not attempt to save data if
 * it is currently loading it and vice-versa - and will sequentially schedule
 * methods that could cause race conditions.
 *
 * That said, be aware that you should always comprehensively test your
 * persistence strategy to understand the opportunity for data loss (in the case
 * of trying to save data to a server under poor network conditions, for
 * example).
 *
 * To help debug such issues, since v4.0.4, the create methods for all Persister
 * objects take an optional `onIgnoredError` argument. This is a handler for the
 * errors that the Persister would otherwise ignore when trying to save or load
 * data (such as when handling corrupted stored data). It's recommended you use
 * this for debugging persistence issues, but only in a development environment.
 * Database-based Persister objects also take an optional `onSqlCommand`
 * argument for logging commands and queries made to the underlying database.
 * @example
 * This example creates a Store, persists it to the browser's session storage as
 * a JSON string, changes the persisted data, updates the Store from it, and
 * finally destroys the Persister again.
 *
 * ```js
 * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
 * import {createStore} from 'tinybase';
 *
 * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
 * const persister = createSessionPersister(store, 'pets');
 *
 * await persister.save();
 * console.log(sessionStorage.getItem('pets'));
 * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
 *
 * sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
 * await persister.load();
 * console.log(store.getTables());
 * // -> {pets: {toto: {species: 'dog'}}}
 *
 * persister.destroy();
 * sessionStorage.clear();
 * ```
 * @example
 * This example creates a Store, and automatically saves and loads it to the
 * browser's session storage as a JSON string. Changes to the Store data, or the
 * persisted data (implicitly firing a StorageEvent), are reflected accordingly.
 *
 * ```js
 * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
 * import {createStore} from 'tinybase';
 *
 * const store = createStore();
 * const persister = createSessionPersister(store, 'pets');
 *
 * await persister.startAutoLoad([{pets: {fido: {species: 'dog'}}}, {}]);
 * await persister.startAutoSave();
 *
 * store.setTables({pets: {felix: {species: 'cat'}}});
 * // ...
 * console.log(sessionStorage.getItem('pets'));
 * // -> '[{"pets":{"felix":{"species":"cat"}}},{}]'
 *
 * // In another browser tab:
 * sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
 * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
 *
 * // ...
 * console.log(store.getTables());
 * // -> {pets: {toto: {species: 'dog'}}}
 *
 * persister.destroy();
 * sessionStorage.clear();
 * ```
 * @category Persister
 * @since v1.0.0
 */
export interface Persister<Persist extends Persists = Persists.StoreOnly> {
  //
  /**
   * The load method gets persisted data from storage, and loads it into the
   * Store with which the Persister is associated, once.
   *
   * The optional parameter allows you to specify what the initial content for
   * the Store will be if there is nothing currently persisted or if the load
   * fails (for example when the Persister is remote and the environment is
   * offline). This allows you to fallback or instantiate a Store whether it's
   * loading from previously persisted storage or being run for the first time.
   *
   * This method is asynchronous because the persisted data may be on a remote
   * machine or a filesystem. Even for those storage types that are synchronous
   * (like browser storage) it is still recommended that you `await` calls to
   * this method or handle the return type natively as a Promise.
   * @param initialContent An optional Content object used when the underlying
   * storage has not previously been populated.
   * @returns A Promise containing a reference to the Persister object.
   * @example
   * This example creates an empty Store, and loads data into it from the
   * browser's session storage, which for the purposes of this example has been
   * previously populated.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * sessionStorage.setItem('pets', '[{"pets":{"fido":{"species":"dog"}}},{}]');
   *
   * const store = createStore();
   * const persister = createSessionPersister(store, 'pets');
   *
   * await persister.load();
   * console.log(store.getTables());
   * // -> {pets: {fido: {species: 'dog'}}}
   *
   * sessionStorage.clear();
   * ```
   * @example
   * This example creates an empty Store, and loads data into it from the
   * browser's session storage, which is at first empty, so the optional
   * parameter is used. The second time the load method is called, data has
   * previously been persisted and instead, that is loaded.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore();
   * const persister = createSessionPersister(store, 'pets');
   *
   * await persister.load([{pets: {fido: {species: 'dog'}}}, {}]);
   * console.log(store.getTables());
   * // -> {pets: {fido: {species: 'dog'}}}
   *
   * sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
   * await persister.load({pets: {fido: {species: 'dog'}}});
   * console.log(store.getTables());
   * // -> {pets: {toto: {species: 'dog'}}}
   *
   * sessionStorage.clear();
   * ```
   * @category Load
   * @since v1.0.0
   */
  load(initialContent?: Content): Promise<this>;

  /**
   * The startAutoLoad method gets persisted data from storage, and loads it
   * into the Store with which the Persister is associated, once, and then
   * continuously.
   *
   * The optional parameter allows you to specify what the initial content for
   * the Store will be if there is nothing currently persisted or if the load
   * fails (for example when the Persister is remote and the environment is
   * offline). This allows you to fallback or instantiate a Store whether it's
   * loading from previously persisted storage or being run for the first time.
   *
   * This method first runs a single call to the load method to ensure the data
   * is in sync with the persisted storage. It then continues to watch for
   * changes to the underlying data (either through events or polling, depending
   * on the storage type), automatically loading the data into the Store.
   *
   * This method is asynchronous because it starts by making a single call to
   * the asynchronous load method. Even for those storage types that are
   * synchronous (like browser storage) it is still recommended that you `await`
   * calls to this method or handle the return type natively as a Promise.
   * @param initialContent An optional Content object used when the underlying
   * storage has not previously been populated.
   * @returns A Promise containing a reference to the Persister object.
   * @example
   * This example creates an empty Store, and loads data into it from the
   * browser's session storage, which at first is empty (so the `initialTables`
   * parameter is used). Subsequent changes to the underlying storage are then
   * reflected in the Store (in this case through detection of StorageEvents
   * from session storage changes made in another browser tab).
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore();
   * const persister = createSessionPersister(store, 'pets');
   *
   * await persister.startAutoLoad([{pets: {fido: {species: 'dog'}}}, {}]);
   * console.log(store.getTables());
   * // -> {pets: {fido: {species: 'dog'}}}
   *
   * // In another browser tab:
   * sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
   *
   * // ...
   * console.log(store.getTables());
   * // -> {pets: {toto: {species: 'dog'}}}
   *
   * persister.destroy();
   * sessionStorage.clear();
   * ```
   * @category Load
   * @since v1.0.0
   */
  startAutoLoad(initialContent?: Content): Promise<this>;

  /**
   * The stopAutoLoad method stops the automatic loading of data from storage
   * previously started with the startAutoLoad method.
   *
   * If the Persister is not currently set to automatically load, this method
   * has no effect.
   * @returns A reference to the Persister object.
   * @example
   * This example creates an empty Store, and starts automatically loading data
   * into it from the browser's session storage. Once the automatic loading is
   * stopped, subsequent changes are not reflected in the Store.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore();
   * const persister = createSessionPersister(store, 'pets');
   * await persister.startAutoLoad();
   *
   * // In another browser tab:
   * sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
   * // ...
   * console.log(store.getTables());
   * // -> {pets: {toto: {species: 'dog'}}}
   *
   * persister.stopAutoLoad();
   *
   * // In another browser tab:
   * sessionStorage.setItem(
   *   'pets',
   *   '[{"pets":{"felix":{"species":"cat"}}},{}]',
   * );
   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
   * // ...
   * console.log(store.getTables());
   * // -> {pets: {toto: {species: 'dog'}}}
   * // Storage change has not been automatically loaded.
   *
   * persister.destroy();
   * sessionStorage.clear();
   * ```
   * @category Load
   * @since v1.0.0
   */
  stopAutoLoad(): this;

  /**
   * The isAutoLoading method lets you find out if the Persister is currently
   * automatically loading its content.
   * @returns A boolean indicating whether the Persister is currently
   * autoLoading.
   * @example
   * This example creates a Persister and queries whether it is autoLoading.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const persister = createSessionPersister(createStore(), 'pets');
   *
   * console.log(persister.isAutoLoading());
   * // -> false
   *
   * await persister.startAutoLoad();
   * console.log(persister.isAutoLoading());
   * // -> true
   *
   * await persister.stopAutoLoad();
   * console.log(persister.isAutoLoading());
   * // -> false
   * ```
   * @category Load
   * @since v5.0.0
   */
  isAutoLoading(): boolean;

  /**
   * The save method takes data from the Store with which the Persister is
   * associated and persists it into storage, once.
   *
   * This method is asynchronous because the persisted data may be on a remote
   * machine or a filesystem. Even for those storage types that are synchronous
   * (like browser storage) it is still recommended that you `await` calls to
   * this method or handle the return type natively as a Promise.
   * @returns A Promise containing a reference to the Persister object.
   * @example
   * This example creates a Store with some data, and saves into the browser's
   * session storage.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
   * const persister = createSessionPersister(store, 'pets');
   *
   * await persister.save();
   * console.log(sessionStorage.getItem('pets'));
   * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
   *
   * persister.destroy();
   * sessionStorage.clear();
   * ```
   * @category Save
   * @since v1.0.0
   */
  save(): Promise<this>;

  /**
   * The save method takes data from the Store with which the Persister is
   * associated and persists it into storage, once, and then continuously.
   *
   * This method first runs a single call to the save method to ensure the data
   * is in sync with the persisted storage. It then continues to watch for
   * changes to the Store, automatically saving the data to storage.
   *
   * This method is asynchronous because it starts by making a single call to
   * the asynchronous save method. Even for those storage types that are
   * synchronous (like browser storage) it is still recommended that you `await`
   * calls to this method or handle the return type natively as a Promise.
   * @returns A Promise containing a reference to the Persister object.
   * @example
   * This example creates a Store with some data, and saves into the browser's
   * session storage. Subsequent changes to the Store are then automatically
   * saved to the underlying storage.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
   * const persister = createSessionPersister(store, 'pets');
   *
   * await persister.startAutoSave();
   * console.log(sessionStorage.getItem('pets'));
   * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
   *
   * store.setTables({pets: {toto: {species: 'dog'}}});
   * // ...
   * console.log(sessionStorage.getItem('pets'));
   * // -> '[{"pets":{"toto":{"species":"dog"}}},{}]'
   *
   * sessionStorage.clear();
   * ```
   * @category Save
   * @since v1.0.0
   */
  startAutoSave(): Promise<this>;

  /**
   * The stopAutoSave method stops the automatic save of data to storage
   * previously started with the startAutoSave method.
   *
   * If the Persister is not currently set to automatically save, this method
   * has no effect.
   * @returns A reference to the Persister object.
   * @example
   * This example creates a Store with some data, and saves into the browser's
   * session storage. Subsequent changes to the Store are then automatically
   * saved to the underlying storage. Once the automatic saving is
   * stopped, subsequent changes are not reflected.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
   * const persister = createSessionPersister(store, 'pets');
   * await persister.startAutoSave();
   *
   * store.setTables({pets: {toto: {species: 'dog'}}});
   * // ...
   * console.log(sessionStorage.getItem('pets'));
   * // -> '[{"pets":{"toto":{"species":"dog"}}},{}]'
   *
   * persister.stopAutoSave();
   *
   * store.setTables({pets: {felix: {species: 'cat'}}});
   * // ...
   * console.log(sessionStorage.getItem('pets'));
   * // -> '[{"pets":{"toto":{"species":"dog"}}},{}]'
   * // Store change has not been automatically saved.
   *
   * sessionStorage.clear();
   * ```
   * @category Save
   * @since v1.0.0
   */
  stopAutoSave(): this;

  /**
   * The isAutoSaving method lets you find out if the Persister is currently
   * automatically saving its content.
   * @returns A boolean indicating whether the Persister is currently
   * autoSaving.
   * @example
   * This example creates a Persister and queries whether it is autoSaving.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const persister = createSessionPersister(createStore(), 'pets');
   *
   * console.log(persister.isAutoSaving());
   * // -> false
   *
   * await persister.startAutoSave();
   * console.log(persister.isAutoSaving());
   * // -> true
   *
   * await persister.stopAutoSave();
   * console.log(persister.isAutoSaving());
   * // -> false
   * ```
   * @category Save
   * @since v5.0.0
   */
  isAutoSaving(): boolean;

  /**
   * The schedule method allows you to queue up a series of asynchronous actions
   * that must run in sequence during persistence.
   *
   * For example, a database Persister may need to ensure that multiple
   * asynchronous tasks to check and update the database schema are completed
   * before data is written to it. Therefore it's most likely you will be using
   * this method inside your `setPersisted` implementation.
   *
   * Call this method to add a single asynchronous action, or a sequence of them
   * in one call. This will also start to run the first task in the queue (which
   * once complete will then run the next, and so on), and so this method itself
   * is also asynchronous and returns a promise of the Persister.
   * @param actions One or many functions which will be scheduled, and which can
   * be asynchronous.
   * @returns A reference to the Persister object.
   * @example
   * This example creates a custom Persister object against a newly-created
   * Store and then sequences two tasks in order to update its data on a
   * hypothetical remote system.
   *
   * ```js yolo
   * import {
   *   checkRemoteSystemIsReady,
   *   getDataFromRemoteSystem,
   *   sendDataToRemoteSystem,
   * } from 'custom-remote-handlers';
   * import {createCustomPersister, createStore} from 'tinybase';
   *
   * const store = createStore();
   * const persister = createCustomPersister(
   *   store,
   *   async () => {
   *     // getPersisted
   *     return await getDataFromRemoteSystem();
   *   },
   *   async (getContent) => {
   *     // setPersisted
   *     await persister.schedule(
   *       async () => await checkRemoteSystemIsReady(),
   *       async () => await sendDataToRemoteSystem(getContent()),
   *     );
   *   },
   *   (listener) => setInterval(listener, 1000),
   *   (interval) => clearInterval(interval),
   * );
   * ```
   * @category Lifecycle
   * @since v4.0.0
   */
  schedule(...actions: (() => Promise<any>)[]): Promise<this>;

  /**
   * The getStore method returns a reference to the underlying Store or
   * MergeableStore that is backing this Persister object.
   * @returns A reference to the Store or MergeableStore.
   * @example
   * This example creates a Persister object against a newly-created Store and
   * then gets its reference in order to update its data.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const persister = createSessionPersister(createStore(), 'pets');
   * await persister.startAutoSave();
   *
   * persister.getStore().setTables({pets: {fido: {species: 'dog'}}});
   * // ...
   * console.log(sessionStorage.getItem('pets'));
   * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
   *
   * sessionStorage.clear();
   * ```
   * @category Getter
   * @since v1.0.0
   */
  getStore(): PersistedStore<Persist>;

  /**
   * The destroy method should be called when this Persister object is no longer
   * used.
   *
   * This guarantees that all of the listeners that the object registered with
   * the underlying Store and storage are removed and it can be correctly
   * garbage collected. It is equivalent to running the stopAutoLoad method and
   * the stopAutoSave method in succession.
   * @example
   * This example creates a Store, associates a Persister object with it (that
   * registers a TablesListener with the underlying Store), and then destroys it
   * again, removing the listener.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore();
   * const persister = createSessionPersister(store, 'pets');
   * await persister.startAutoSave();
   *
   * console.log(store.getListenerStats().transaction);
   * // -> 1
   *
   * persister.destroy();
   *
   * console.log(store.getListenerStats().transaction);
   * // -> 0
   * ```
   * @category Lifecycle
   * @since v1.0.0
   */
  destroy(): this;

  /**
   * The getStats method provides a set of statistics about the Persister, and
   * is used for debugging purposes.
   *
   * The PersisterStats object contains a count of the number of times the
   * Persister has loaded and saved data.
   *
   * The method is intended to be used during development to ensure your
   * persistence layer is acting as expected, for example.
   * @returns A PersisterStats object containing Persister load and save
   * statistics.
   * @example
   * This example gets the load and save statistics of a Persister object.
   * Remember that the startAutoLoad method invokes an explicit load when it
   * starts, and the startAutoSave method invokes an explicit save when it
   * starts - so those numbers are included in addition to the loads and saves
   * invoked by changes to the Store and to the underlying storage.
   *
   * ```js
   * import {createSessionPersister} from 'tinybase/persisters/persister-browser';
   * import {createStore} from 'tinybase';
   *
   * const store = createStore();
   * const persister = createSessionPersister(store, 'pets');
   *
   * await persister.startAutoLoad({pets: {fido: {species: 'dog'}}});
   * await persister.startAutoSave();
   *
   * store.setTables({pets: {felix: {species: 'cat'}}});
   * // ...
   *
   * sessionStorage.setItem('pets', '[{"pets":{"toto":{"species":"dog"}}},{}]');
   * // -> StorageEvent('storage', {storageArea: sessionStorage, key: 'pets'})
   * // ...
   *
   * console.log(persister.getStats());
   * // -> {loads: 2, saves: 2}
   *
   * persister.destroy();
   * sessionStorage.clear();
   * ```
   * @category Development
   * @since v1.0.0
   */
  getStats(): PersisterStats;
  //
}

/**
 * The createCustomPersister function creates a Persister object that you can
 * configure to persist the Store in any way you wish.
 *
 * As well as providing a reference to the Store to persist, you must provide
 * functions that handle how to fetch, write, and listen to, the persistence
 * layer.
 *
 * The other creation functions (such as the createSessionPersister function and
 * createFilePersister function, for example) all use this function under the
 * covers. See those implementations for ideas on how to implement your own
 * Persister types.
 *
 * This API changed in v4.0. Any custom persisters created on previous versions
 * should be upgraded. Most notably, the `setPersisted` function parameter is
 * provided with a `getContent` function to get the content from the Store
 * itself, rather than being passed pre-serialized JSON. It also receives
 * information about the changes made during a transaction. The `getPersisted`
 * function must return the content (or nothing) rather than JSON.
 * `startListeningToPersisted` has been renamed `addPersisterListener`, and
 * `stopListeningToPersisted` has been renamed `delPersisterListener`.
 * @param store The Store to persist.
 * @param getPersisted An asynchronous function which will fetch content from
 * the persistence layer (or `undefined` if not present).
 * @param setPersisted An asynchronous function which will send content to the
 * persistence layer. Since v4.0, it receives functions for getting the Store
 * content and information about the changes made during a transaction. Since
 * v5.0, the changes are received directly by reference, rather than an
 * accessor.
 * @param addPersisterListener A function that will register a `listener`
 * listener on underlying changes to the persistence layer. You can return a
 * listening handle that will be provided again when `delPersisterListener` is
 * called.
 * @param delPersisterListener A function that will unregister the listener from
 * the underlying changes to the persistence layer. It receives whatever was
 * returned from your `addPersisterListener` implementation.
 * @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 persist Since v5.0, an optional integer from the Persists enum to
 * indicate which types of Store are supported by this Persister: `1` indicates
 * only a regular Store is supported, `2` indicates only a MergeableStore is
 * supported, and `3` indicates that both Store and MergeableStore are
 * supported.
 * @returns A reference to the new Persister object.
 * @example
 * This example creates a custom Persister object and persists a Store to a
 * local string called `persistedJson` and which would automatically load by
 * polling for changes every second. It implicitly supports only a regular
 * Store.
 *
 * ```js
 * import {createCustomPersister, createStore} from 'tinybase';
 *
 * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
 * let persistedJson;
 *
 * const persister = createCustomPersister(
 *   store,
 *   async () => {
 *     // getPersisted
 *     return JSON.parse(persistedJson);
 *   },
 *   async (getContent) => {
 *     // setPersisted
 *     persistedJson = JSON.stringify(getContent());
 *   },
 *   (listener) => setInterval(listener, 1000),
 *   (interval) => clearInterval(interval),
 * );
 *
 * await persister.save();
 * console.log(persistedJson);
 * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
 *
 * persistedJson = '[{"pets":{"fido":{"species":"dog","color":"brown"}}},{}]';
 * await persister.load();
 *
 * console.log(store.getTables());
 * // -> {pets: {fido: {species: 'dog', color: 'brown'}}}
 *
 * persister.destroy();
 * ```
 * @example
 * This example demonstrates a Persister creation function which returns a
 * Persister. This can persists a store to a local string called `persistedJson`
 * and which would automatically load by polling for changes every second.
 * It emits warnings to the console and explicitly supports either a Store or a
 * MergeableStore.
 *
 * ```js
 * import {
 *   Persists,
 *   createCustomPersister,
 *   createMergeableStore,
 *   createStore,
 * } from 'tinybase';
 *
 * let persistedJson;
 * const createJsonPersister = (storeOrMergeableStore) =>
 *   createCustomPersister(
 *     storeOrMergeableStore,
 *     async () => {
 *       // getPersisted
 *       return JSON.parse(persistedJson);
 *     },
 *     async (getContent) => {
 *       // setPersisted
 *       persistedJson = JSON.stringify(getContent());
 *     },
 *     (listener) => setInterval(listener, 1000),
 *     (interval) => clearInterval(interval),
 *     console.warn,
 *     Persists.StoreOrMergeableStore,
 *   );
 *
 * const store = createStore();
 * store.setTables({pets: {fido: {species: 'dog'}}});
 * const storePersister = createJsonPersister(store);
 * await storePersister.save();
 * console.log(persistedJson);
 * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
 * storePersister.destroy();
 *
 * const mergeableStore = createMergeableStore('mergeableStore1'); // !resetHlc
 * mergeableStore.setTables({pets: {fido: {species: 'dog'}}});
 * const mergeableStorePersister = createJsonPersister(mergeableStore);
 * await mergeableStorePersister.save();
 * console.log(JSON.parse(persistedJson));
 * // ->
 * [
 *   [
 *     {
 *       pets: [
 *         {
 *           fido: [
 *             {species: ['dog', 'Nn1JUF-----Zjl0M', 4176151067]},
 *             '',
 *             2722999044,
 *           ],
 *         },
 *         '',
 *         3367164653,
 *       ],
 *     },
 *     '',
 *     30627183,
 *   ],
 *   [{}, '', 0],
 * ];
 * mergeableStorePersister.destroy();
 * ```
 * @category Creation
 * @since v1.0.0
 */
export function createCustomPersister<
  ListeningHandle,
  Persist extends Persists = Persists.StoreOnly,
>(
  store: PersistedStore<Persist>,
  getPersisted: () => Promise<PersistedContent<Persist> | undefined>,
  setPersisted: (
    getContent: () => PersistedContent<Persist>,
    changes?: PersistedChanges<Persist>,
  ) => Promise<void>,
  addPersisterListener: (
    listener: PersisterListener<Persist>,
  ) => ListeningHandle,
  delPersisterListener: (listeningHandle: ListeningHandle) => void,
  onIgnoredError?: (error: any) => void,
  persist?: Persist,
): Persister<Persist>;