tinybase 4.0.0-beta.4 → 4.0.0-beta.5

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

@@ -6,7 +6,6 @@
  * returns a new Metrics object. From there, you can create new Metric
  * definitions, access the values of those Metrics directly, and register
  * listeners for when they change.
- *
  * @packageDocumentation
  * @module metrics
  */
@@ -18,7 +17,6 @@ import {Id, IdOrNull, Ids} from './common.d';
 /**
  * The Metric type is simply an alias, but represents a number formed by
  * aggregating multiple other numbers together.
- *
  * @category Metric
  */
 export type Metric = number;
@@ -30,7 +28,6 @@ export type Metric = number;
  * A MetricCallback is provided when using the forEachMetric method, so that you
  * can do something based on every Metric in the Metrics object. See that method
  * for specific examples.
- *
  * @param metricId The Id of the Metric that the callback can operate on.
  * @param metric The value of the Metric.
  * @category Callback
@@ -45,7 +42,6 @@ export type MetricCallback = (metricId: Id, metric?: Metric) => void;
  * summing, and averaging values. This type is instead used for when you wish to
  * use a more complex aggregation of your own devising. See the
  * setMetricDefinition method for more examples.
- *
  * @param numbers The array of numbers in the Metric's aggregation.
  * @param length The length of the array of numbers in the Metric's aggregation.
  * @returns The value of the Metric.
@@ -70,7 +66,6 @@ export type MetricAggregate = (numbers: number[], length: number) => Metric;
  * implementation of an MetricAggregateAdd function that can reduce the
  * complexity cost of growing the input data set. See the setMetricDefinition
  * method for more examples.
- *
  * @param metric The current value of the Metric.
  * @param add The number being added to the Metric's aggregation.
  * @param length The length of the array of numbers in the Metric's aggregation.
@@ -103,7 +98,6 @@ export type MetricAggregateAdd = (
  * implementation of an MetricAggregateRemove function that can reduce the
  * complexity cost of shrinking the input data set. See the setMetricDefinition
  * method for more examples.
- *
  * @param metric The current value of the Metric.
  * @param remove The number being removed from the Metric's aggregation.
  * @param length The length of the array of numbers in the Metric's aggregation.
@@ -133,7 +127,6 @@ export type MetricAggregateRemove = (
  * implementation of an MetricAggregateReplace function that can reduce the
  * complexity cost of changing the input data set in place. See the
  * setMetricDefinition method for more examples.
- *
  * @param metric The current value of the Metric.
  * @param add The number being added to the Metric's aggregation.
  * @param remove The number being removed from the Metric's aggregation.
@@ -172,7 +165,6 @@ export type MetricAggregateReplace = (
  * If this is the first time that a Metric has had a value (such as when a table
  * has gained its first row), the old value will be `undefined`. If a Metric now
  * no longer has a value, the new value will be `undefined`.
- *
  * @param metrics A reference to the Metrics object that changed.
  * @param metricId The Id of the Metric that changed.
  * @param newMetric The new value of the Metric that changed.
@@ -192,7 +184,6 @@ export type MetricListener<Schemas extends OptionalSchemas> = (
  *
  * A MetricsListenerStats object is returned from the getListenerStats method,
  * and is only populated in a debug build.
- *
  * @category Development
  */
 export type MetricsListenerStats = {
@@ -218,7 +209,6 @@ export type MetricsListenerStats = {
  * ('sum', 'avg', 'min', and 'max'), and defaults to counting Row objects when
  * using the setMetricDefinition method. However, far more complex aggregations
  * can be configured with custom functions.
- *
  * @example
  * This example shows a very simple lifecycle of a Metrics object: from
  * creation, to adding a definition, getting a Metric, and then registering and
@@ -299,7 +289,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * function's algorithmic complexity by providing shortcuts that can nudge an
    * aggregation result when a single value is added, removed, or replaced in
    * the input values.
-   *
    * @param metricId The Id of the Metric to define.
    * @param tableId The Id of the Table the Metric will be calculated from.
    * @param aggregate Either a string representing one of a set of common
@@ -451,6 +440,11 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
 
   /**
    * The delMetricDefinition method removes an existing Metric definition.
+   * @param metricId The Id of the Metric to remove.
+   * @returns A reference to the Metrics object.
+   * @example
+   * This example creates a Store, creates a Metrics object, defines a simple
+   * Metric, and then removes it.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -458,12 +452,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * delMetricDefinition(metricId: Id): Metrics;
    * ```
    *
-   * @param metricId The Id of the Metric to remove.
-   * @returns A reference to the Metrics object.
-   * @example
-   * This example creates a Store, creates a Metrics object, defines a simple
-   * Metric, and then removes it.
-   *
    * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
@@ -487,6 +475,10 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
   /**
    * The getStore method returns a reference to the underlying Store that is
    * backing this Metrics object.
+   * @returns A reference to the Store.
+   * @example
+   * This example creates a Metrics object against a newly-created Store and
+   * then gets its reference in order to update its data.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -494,11 +486,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * getStore(): Store;
    * ```
    *
-   * @returns A reference to the Store.
-   * @example
-   * This example creates a Metrics object against a newly-created Store and
-   * then gets its reference in order to update its data.
-   *
    * ```js
    * const metrics = createMetrics(createStore());
    * metrics.setMetricDefinition('speciesCount', 'species');
@@ -513,7 +500,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
   /**
    * The getMetricIds method returns an array of the Metric Ids registered with
    * this Metrics object.
-   *
    * @returns An array of Ids.
    * @example
    * This example creates a Metrics object with two definitions, and then gets
@@ -538,7 +524,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * This method is useful for iterating over all the Metrics in a functional
    * style. The `metricCallback` parameter is a MetricCallback function that
    * will be called with the Id of each Metric and its value.
-   *
    * @param metricCallback The function that should be called for every Metric.
    * @example
    * This example iterates over each Metric in a Metrics object.
@@ -566,7 +551,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
   /**
    * The hasMetric method returns a boolean indicating whether a given Metric
    * exists in the Metrics object, and has a value.
-   *
    * @param metricId The Id of a possible Metric in the Metrics object.
    * @returns Whether a Metric with that Id exists.
    * @example
@@ -600,7 +584,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * ```
    *
    * If the Metric Id is invalid, the method returns `undefined`.
-   *
    * @param metricId The Id of a Metric.
    * @returns The Id of the Table backing the Metric, or `undefined`.
    * @example
@@ -627,7 +610,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    *
    * If the identified Metric does not exist (or if the definition references a
    * Table or Cell value that does not exist) then `undefined` is returned.
-   *
    * @param metricId The Id of the Metric.
    * @returns The numeric value of the Metric, or `undefined`.
    * @example
@@ -673,7 +655,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * The provided listener is a MetricListener function, and will be called with
    * a reference to the Metrics object, the Id of the Metric that changed, the
    * new Metric value, and the old Metric value.
-   *
    * @param metricId The Id of the Metric to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Metric
    * changes.
@@ -753,7 +734,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    *
    * Use the Id returned by the addMetricListener method. Note that the Metrics
    * object may re-use this Id for future listeners added to it.
-   *
    * @param listenerId The Id of the listener to remove.
    * @returns A reference to the Metrics object.
    * @example
@@ -796,7 +776,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    *
    * This guarantees that all of the listeners that the object registered with
    * the underlying Store are removed and it can be correctly garbage collected.
-   *
    * @example
    * This example creates a Store, adds a Metrics object with a definition (that
    * registers a RowListener with the underlying Store), and then destroys it
@@ -832,7 +811,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
    * return an empty object. The method is intended to be used during
    * development to ensure your application is not leaking listener
    * registrations, for example.
-   *
    * @returns A MetricsListenerStats object containing Metrics listener
    * statistics.
    * @example
@@ -864,7 +842,6 @@ export interface Metrics<in out Schemas extends OptionalSchemas> {
  * A given Store can only have one Metrics object associated with it. If you
  * call this function twice on the same Store, your second call will return a
  * reference to the Metrics object created by the first.
- *
  * @param store The Store for which to register Metric definitions.
  * @returns A reference to the new Metrics object.
  * @example

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

@@ -5,16 +5,15 @@
  * A single entry point, the createAutomergePersister function, is provided,
  * which returns a new Persister object that can bind a Store to a provided
  * Automerge document handle (and in turn, its document).
- *
  * @see Synchronizing Data guide
  * @packageDocumentation
  * @module persister-automerge
- * @since v4.0
+ * @since v4.0.0
  */
 
-import {OptionalSchemas, Store} from './store';
+import {OptionalSchemas, Store} from '../store';
 import {DocHandle} from 'automerge-repo';
-import {Persister} from './persisters';
+import {Persister} from '../persisters';
 
 /**
  * The createAutomergePersister function creates a Persister object that can
@@ -32,7 +31,6 @@ import {Persister} from './persisters';
  *
  * As well as providing a reference to the Store to persist, you must provide
  * the Automerge document handler to persist it with.
- *
  * @param store The Store to persist.
  * @param docHandle The Automerge document handler to persist the Store with.
  * @param docMapName The name of the map used inside the Automerge document to
@@ -111,7 +109,7 @@ import {Persister} from './persisters';
  * persister2.destroy();
  * ```
  * @category Creation
- * @since v4.0
+ * @since v4.0.0
  */
 export function createAutomergePersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,

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

@@ -9,14 +9,13 @@
  *   browser's session storage.
  * - The createLocalPersister function returns a Persister that uses the
  *   browser's local storage.
- *
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-browser
  */
 
-import {OptionalSchemas, Store} from './store';
-import {Persister} from './persisters';
+import {OptionalSchemas, Store} from '../store';
+import {Persister} from '../persisters';
 
 /**
  * The createSessionPersister function creates a Persister object that can
@@ -34,7 +33,6 @@ import {Persister} from './persisters';
  * As well as providing a reference to the Store to persist, you must provide a
  * `storageName` parameter which is unique to your application. This is the key
  * that the browser uses to identify the storage location.
- *
  * @param store The Store to persist.
  * @param storageName The unique key to identify the storage location.
  * @returns A reference to the new Persister object.
@@ -76,7 +74,6 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
  * As well as providing a reference to the Store to persist, you must provide a
  * `storageName` parameter which is unique to your application. This is the key
  * that the browser uses to identify the storage location.
- *
  * @param store The Store to persist.
  * @param storageName The unique key to identify the storage location.
  * @returns A reference to the new Persister object.

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

@@ -0,0 +1,105 @@
+/**
+ * The persister-cr-sqlite-wasm module of the TinyBase project lets you save and
+ * load Store data to and from a local CR-SQLite database (in an appropriate
+ * environment).
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-cr-sqlite-wasm
+ */
+
+import {DatabasePersisterConfig, Persister} from '../persisters';
+import {OptionalSchemas, Store} from '../store';
+import {DB} from '@vlcn.io/crsqlite-wasm';
+
+/**
+ * The createCrSqliteWasmPersister function creates a Persister object that can
+ * persist the Store to a local CR-SQLite database (in an appropriate
+ * environment).
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createCrSqliteWasmPersister(
+ *   store: Store,
+ *   db: DB,
+ *   configOrStoreTableName?: DatabasePersisterConfig | string,
+ * ): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide
+ * a `db` parameter which identifies the database instance.
+ *
+ * A database Persister uses one of two modes: either a JSON serialization of
+ * the whole Store stored in a single row of a table (the default), or a tabular
+ * mapping of Table Ids to database table names and vice-versa).
+ *
+ * The third argument is a DatabasePersisterConfig object that configures which
+ * of those modes to use, and settings for each. If the third argument is simply
+ * a string, it is used as the `storeTableName` property of the JSON
+ * serialization.
+ *
+ * See the documentation for the DpcJson and DpcTabular types for more
+ * information on how both of those modes can be configured.
+ * @param store The Store to persist.
+ * @param db The database instance that was returned from `crSqlite3.open(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * CR-SQLite database as a JSON serialization into the `my_tinybase` table. It
+ * makes a change to the database directly and then reloads it back into the
+ * Store.
+ *
+ * ```js
+ * const crSqlite3 = await initWasm();
+ * const db = await crSqlite3.open();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createCrSqliteWasmPersister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * console.log(await db.execO('SELECT * FROM my_tinybase;'));
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * await db.exec(
+ *   'UPDATE my_tinybase SET store = ' +
+ *     `'[{"pets":{"felix":{"species":"cat"}}},{}]' WHERE _id = '_';`,
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * SQLite database with tabular mapping.
+ *
+ * ```js
+ * const crSqlite3 = await initWasm();
+ * const db = await crSqlite3.open();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createCrSqliteWasmPersister(store, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(await db.execO('SELECT * FROM pets;'));
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * await db.exec(`INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`);
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createCrSqliteWasmPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  db: DB,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+): Persister<Schemas>;

package/lib/types/with-schemas/{persister-file.d.ts → persisters/persister-file.d.ts}

@@ -1,14 +1,13 @@
 /**
  * The persister-file module of the TinyBase project lets you save and load
  * Store data to and from a local file system (in an appropriate environment).
- *
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-file
  */
 
-import {OptionalSchemas, Store} from './store';
-import {Persister} from './persisters';
+import {OptionalSchemas, Store} from '../store';
+import {Persister} from '../persisters';
 
 /**
  * The createFilePersister function creates a Persister object that can persist
@@ -20,9 +19,8 @@ import {Persister} from './persisters';
  * createFilePersister(store: Store, filePath: string): Persister;
  * ```
  *
- * As well as providing a reference to the Store to persist, you must provide
+ * As well as providing a reference to the Store to persist, you must provide a
  * `filePath` parameter which identifies the file to persist it to.
- *
  * @param store The Store to persist.
  * @param filePath The location of the local file to persist the Store to.
  * @returns A reference to the new Persister object.

package/lib/types/with-schemas/{persister-remote.d.ts → persisters/persister-remote.d.ts}

@@ -1,14 +1,13 @@
 /**
  * The persister-remote module of the TinyBase project lets you save and load
  * Store data to and from a remote server.
- *
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-remote
  */
 
-import {OptionalSchemas, Store} from './store';
-import {Persister} from './persisters';
+import {OptionalSchemas, Store} from '../store';
+import {Persister} from '../persisters';
 
 /**
  * The createRemotePersister function creates a Persister object that can
@@ -33,7 +32,6 @@ import {Persister} from './persisters';
  * For when you choose to enable automatic loading for the Persister (with the
  * startAutoLoad method), it will poll the loadUrl for changes. The
  * `autoLoadIntervalSeconds` method is used to indicate how often to do this.
- *
  * @param store The Store to persist.
  * @param loadUrl The endpoint that supports a `GET` method to load JSON.
  * @param saveUrl The endpoint that supports a `POST` method to save JSON.

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

@@ -0,0 +1,113 @@
+/**
+ * The persister-sqlite-wasm module of the TinyBase project lets you save and
+ * load Store data to and from a local SQLite database (in an appropriate
+ * environment).
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-sqlite-wasm
+ */
+
+import {DatabasePersisterConfig, Persister} from '../persisters';
+import {OptionalSchemas, Store} from '../store';
+
+/**
+ * The createSqliteWasmPersister function creates a Persister object that can
+ * persist the Store to a local SQLite database (in an appropriate environment).
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createSqliteWasmPersister(
+ *   store: Store,
+ *   sqlite3: any,
+ *   db: any,
+ *   configOrStoreTableName?: DatabasePersisterConfig | string,
+ * ): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide
+ * `sqlite3` and `db` parameters which identify the WASM module and database
+ * instance respectively.
+ *
+ * A database Persister uses one of two modes: either a JSON serialization of
+ * the whole Store stored in a single row of a table (the default), or a tabular
+ * mapping of Table Ids to database table names and vice-versa).
+ *
+ * The fourth argument is a DatabasePersisterConfig object that configures which
+ * of those modes to use, and settings for each. If the fourth argument is
+ * simply a string, it is used as the `storeTableName` property of the JSON
+ * serialization.
+ *
+ * See the documentation for the DpcJson and DpcTabular types for more
+ * information on how both of those modes can be configured.
+ * @param store The Store to persist.
+ * @param sqlite3 The WASM module that was returned from `sqlite3InitModule`.
+ * @param db The database instance that was returned from `new
+ * sqlite3.oo1.DB(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * SQLite database as a JSON serialization into the `my_tinybase` table. It
+ * makes a change to the database directly and then reloads it back into the
+ * Store.
+ *
+ * ```js
+ * const sqlite3 = await sqlite3InitModule();
+ * const db = new sqlite3.oo1.DB(':memory:', 'c');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqliteWasmPersister(
+ *   store,
+ *   sqlite3,
+ *   db,
+ *   'my_tinybase',
+ * );
+ *
+ * await persister.save();
+ * console.log(db.exec('SELECT * FROM my_tinybase;', {rowMode: 'object'}));
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * db.exec(
+ *   'UPDATE my_tinybase SET store = ' +
+ *     `'[{"pets":{"felix":{"species":"cat"}}},{}]' WHERE _id = '_';`,
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * SQLite database with tabular mapping.
+ *
+ * ```js
+ * const sqlite3 = await sqlite3InitModule();
+ * const db = new sqlite3.oo1.DB(':memory:', 'c');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqliteWasmPersister(store, sqlite3, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(db.exec('SELECT * FROM pets;', {rowMode: 'object'}));
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * db.exec(`INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`);
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createSqliteWasmPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  sqlite3: any,
+  db: any,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+): Persister<Schemas>;

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

@@ -0,0 +1,119 @@
+/**
+ * The persister-sqlite3 module of the TinyBase project lets you save and load
+ * Store data to and from a local SQLite database (in an appropriate
+ * environment).
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-sqlite3
+ */
+
+import {DatabasePersisterConfig, Persister} from '../persisters';
+import {OptionalSchemas, Store} from '../store';
+import {Database} from 'sqlite3';
+
+/**
+ * The createSqlite3Persister function creates a Persister object that can
+ * persist the Store to a local SQLite database (in an appropriate environment).
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createSqlite3Persister(
+ *   store: Store,
+ *   db: Database,
+ *   configOrStoreTableName?: DatabasePersisterConfig | string,
+ * ): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `db` parameter which identifies the database instance.
+ *
+ * A database Persister uses one of two modes: either a JSON serialization of
+ * the whole Store stored in a single row of a table (the default), or a tabular
+ * mapping of Table Ids to database table names and vice-versa).
+ *
+ * The third argument is a DatabasePersisterConfig object that configures which
+ * of those modes to use, and settings for each. If the third argument is simply
+ * a string, it is used as the `storeTableName` property of the JSON
+ * serialization.
+ *
+ * See the documentation for the DpcJson and DpcTabular types for more
+ * information on how both of those modes can be configured.
+ * @param store The Store to persist.
+ * @param db The database instance that was returned from `new
+ * sqlite3.Database(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * SQLite database as a JSON serialization into the `my_tinybase` table. It
+ * makes a change to the database directly and then reloads it back into the
+ * Store.
+ *
+ * ```js
+ * const db = new sqlite3.Database(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqlite3Persister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * console.log(
+ *   await new Promise((resolve) =>
+ *     db.all('SELECT * FROM my_tinybase;', (_, rows) => resolve(rows)),
+ *   ),
+ * );
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * await new Promise((resolve) =>
+ *   db.all(
+ *     'UPDATE my_tinybase SET store = ' +
+ *       `'[{"pets":{"felix":{"species":"cat"}}},{}]' WHERE _id = '_';`,
+ *     resolve,
+ *   ),
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * SQLite database with tabular mapping.
+ *
+ * ```js
+ * const db = new sqlite3.Database(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSqlite3Persister(store, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(
+ *   await new Promise((resolve) =>
+ *     db.all('SELECT * FROM pets;', (_, rows) => resolve(rows)),
+ *   ),
+ * );
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * await new Promise((resolve) =>
+ *   db.all(
+ *     `INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`,
+ *     resolve,
+ *   ),
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createSqlite3Persister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  db: Database,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+): Persister<Schemas>;