tinybase 9.5.0 → 9.6.0-beta.1

package/@types/omni/index.d.ts

@@ -22,7 +22,9 @@ export * from '../metrics/index.d.ts';
 export * from '../middleware/index.d.ts';
 export * from '../persisters/index.d.ts';
 export * from '../persisters/persister-automerge/index.d.ts';
+export * from '../persisters/persister-better-sqlite3/index.d.ts';
 export * from '../persisters/persister-browser/index.d.ts';
+export * from '../persisters/persister-capacitor-sqlite/index.d.ts';
 export * from '../persisters/persister-cr-sqlite-wasm/index.d.ts';
 export * from '../persisters/persister-durable-object-sql-storage/index.d.ts';
 export * from '../persisters/persister-durable-object-storage/index.d.ts';
@@ -33,6 +35,7 @@ export * from '../persisters/persister-indexed-db/index.d.ts';
 export * from '../persisters/persister-libsql/index.d.ts';
 export * from '../persisters/persister-partykit-client/index.d.ts';
 export * from '../persisters/persister-partykit-server/index.d.ts';
+export * from '../persisters/persister-pg/index.d.ts';
 export * from '../persisters/persister-pglite/index.d.ts';
 export * from '../persisters/persister-postgres/index.d.ts';
 export * from '../persisters/persister-powersync/index.d.ts';
@@ -42,6 +45,7 @@ export * from '../persisters/persister-remote/index.d.ts';
 export * from '../persisters/persister-sqlite-bun/index.d.ts';
 export * from '../persisters/persister-sqlite-wasm/index.d.ts';
 export * from '../persisters/persister-sqlite3/index.d.ts';
+export * from '../persisters/persister-supabase/index.d.ts';
 export * from '../persisters/persister-yjs/index.d.ts';
 export * from '../queries/index.d.ts';
 export * from '../relationships/index.d.ts';

package/@types/omni/with-schemas/index.d.ts

@@ -21,7 +21,9 @@ export * from '../../mergeable-store/with-schemas/index.d.ts';
 export * from '../../metrics/with-schemas/index.d.ts';
 export * from '../../middleware/with-schemas/index.d.ts';
 export * from '../../persisters/persister-automerge/with-schemas/index.d.ts';
+export * from '../../persisters/persister-better-sqlite3/with-schemas/index.d.ts';
 export * from '../../persisters/persister-browser/with-schemas/index.d.ts';
+export * from '../../persisters/persister-capacitor-sqlite/with-schemas/index.d.ts';
 export * from '../../persisters/persister-cr-sqlite-wasm/with-schemas/index.d.ts';
 export * from '../../persisters/persister-durable-object-sql-storage/with-schemas/index.d.ts';
 export * from '../../persisters/persister-durable-object-storage/with-schemas/index.d.ts';
@@ -32,6 +34,7 @@ export * from '../../persisters/persister-indexed-db/with-schemas/index.d.ts';
 export * from '../../persisters/persister-libsql/with-schemas/index.d.ts';
 export * from '../../persisters/persister-partykit-client/with-schemas/index.d.ts';
 export * from '../../persisters/persister-partykit-server/with-schemas/index.d.ts';
+export * from '../../persisters/persister-pg/with-schemas/index.d.ts';
 export * from '../../persisters/persister-pglite/with-schemas/index.d.ts';
 export * from '../../persisters/persister-postgres/with-schemas/index.d.ts';
 export * from '../../persisters/persister-powersync/with-schemas/index.d.ts';
@@ -41,6 +44,7 @@ export * from '../../persisters/persister-remote/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite-bun/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite-wasm/with-schemas/index.d.ts';
 export * from '../../persisters/persister-sqlite3/with-schemas/index.d.ts';
+export * from '../../persisters/persister-supabase/with-schemas/index.d.ts';
 export * from '../../persisters/persister-yjs/with-schemas/index.d.ts';
 export * from '../../persisters/with-schemas/index.d.ts';
 export * from '../../queries/with-schemas/index.d.ts';

package/@types/persisters/index.d.ts

@@ -1927,11 +1927,18 @@ export function createCustomPersister<
  * ideas on how to build your own Persister type, and as functional examples.
  * Examine the implementation of the createSqlite3Persister function as a good
  * starting point, for example.
+ *
+ * Your `executeCommand` function is given SQL that uses SQLite's anonymous `?`
+ * placeholders, with the parameters to bind to them in order. SQLite drivers
+ * agree on that form, whereas they vary in how they handle the numbered
+ * placeholders that PostgreSQL requires, so you should not need to rewrite
+ * statements before passing them on.
  * @param store The Store to persist.
  * @param configOrStoreTableName A DatabasePersisterConfig object, or a string
  * that will be used as the name of the Store's table in the database.
  * @param executeCommand A function that will execute a command against the
- * database.
+ * database. It receives SQL with anonymous `?` placeholders, and the parameters
+ * to bind to them in order.
  * @param addChangeListener A function that will register a listener for changes
  * to the database.
  * @param delChangeListener A function that will unregister the listener for

package/@types/persisters/persister-better-sqlite3/index.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The persister-better-sqlite3 module of the TinyBase project lets you save and
+ * load Store data to and from a local SQLite database, via the synchronous
+ * [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) module.
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-better-sqlite3
+ * @since 9.6.0
+ */
+import type {Database} from 'better-sqlite3';
+import type {MergeableStore} from '../../mergeable-store/index.d.ts';
+import type {Store} from '../../store/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  DpcJson,
+  Persister,
+  Persists,
+} from '../index.d.ts';
+
+/**
+ * The BetterSqlite3Persister interface represents a Persister that lets you
+ * save and load Store data to and from a local SQLite database.
+ *
+ * You should use the createBetterSqlite3Persister function to create a
+ * BetterSqlite3Persister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDb method for accessing a reference to the database the Store is
+ * being persisted to.
+ * @category Persister
+ * @since 9.6.0
+ */
+export interface BetterSqlite3Persister extends Persister<Persists.StoreOrMergeableStore> {
+  /**
+   * The getDb method returns a reference to the database the Store is being
+   * persisted to.
+   * @returns A reference to the database.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the database back out again.
+   *
+   * ```js
+   * import Database from 'better-sqlite3';
+   * import {createStore} from 'tinybase';
+   * import {createBetterSqlite3Persister} from 'tinybase/persisters/persister-better-sqlite3';
+   *
+   * const db = new Database(':memory:');
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createBetterSqlite3Persister(store, db, 'my_tinybase');
+   *
+   * console.log(persister.getDb() == db);
+   * // -> true
+   *
+   * await persister.destroy();
+   * db.close();
+   * ```
+   * @category Getter
+   * @since 9.6.0
+   */
+  getDb(): Database;
+}
+
+/**
+ * The createBetterSqlite3Persister function creates a BetterSqlite3Persister
+ * object that can persist a Store to a local SQLite database.
+ *
+ * A BetterSqlite3Persister supports regular Store objects, and can also be used
+ * to persist the metadata of a MergeableStore when using the JSON serialization
+ * mode, as described below.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `db` parameter which is the database returned from `new Database(...)`.
+ *
+ * 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.
+ *
+ * Note that `better-sqlite3` does not signal when the database changes, so if
+ * you enable automatic loading with the startAutoLoad method, it polls the
+ * database for changes. The Sqlite3Persister, which uses the asynchronous
+ * `sqlite3` module, is notified of changes as they happen, and may suit you
+ * better if that matters.
+ * @param store The Store or MergeableStore to persist.
+ * @param db The database that was returned from `new Database(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @param onSqlCommand An optional handler called every time the Persister
+ * executes a SQL command or query. This is suitable for logging persistence
+ * behavior in a development environment.
+ * @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.
+ * @returns A reference to the new BetterSqlite3Persister object.
+ * @example
+ * This example creates a BetterSqlite3Persister 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
+ * import Database from 'better-sqlite3';
+ * import {createStore} from 'tinybase';
+ * import {createBetterSqlite3Persister} from 'tinybase/persisters/persister-better-sqlite3';
+ *
+ * const db = new Database(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createBetterSqlite3Persister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * console.log(db.prepare('SELECT * FROM my_tinybase;').all());
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * db.prepare('UPDATE my_tinybase SET store = ? WHERE _id = ?;').run(
+ *   '[{"pets":{"felix":{"species":"cat"}}},{}]',
+ *   '_',
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @example
+ * This example creates a BetterSqlite3Persister object and persists the Store
+ * to a local SQLite database with tabular mapping.
+ *
+ * ```js
+ * import Database from 'better-sqlite3';
+ * import {createStore} from 'tinybase';
+ * import {createBetterSqlite3Persister} from 'tinybase/persisters/persister-better-sqlite3';
+ *
+ * const db = new Database(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createBetterSqlite3Persister(store, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(db.prepare('SELECT * FROM pets;').all());
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * db.prepare(
+ *   `INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`,
+ * ).run();
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @category Creation
+ * @since 9.6.0
+ */
+export function createBetterSqlite3Persister<StoreType extends Store>(
+  store: StoreType,
+  db: Database,
+  configOrStoreTableName?:
+    | (NoInfer<StoreType> extends MergeableStore
+        ? DpcJson
+        : DatabasePersisterConfig)
+    | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): BetterSqlite3Persister;

package/@types/persisters/persister-better-sqlite3/with-schemas/index.d.ts

@@ -0,0 +1,202 @@
+/**
+ * The persister-better-sqlite3 module of the TinyBase project lets you save and
+ * load Store data to and from a local SQLite database, via the synchronous
+ * [`better-sqlite3`](https://github.com/WiseLibs/better-sqlite3) module.
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-better-sqlite3
+ * @since 9.6.0
+ */
+import type {Database} from 'better-sqlite3';
+import type {MergeableStore} from '../../../mergeable-store/with-schemas/index.d.ts';
+import type {
+  OptionalSchemas,
+  Store,
+} from '../../../store/with-schemas/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  DpcJson,
+  Persister,
+  Persists,
+} from '../../with-schemas/index.d.ts';
+
+/**
+ * The BetterSqlite3Persister interface represents a Persister that lets you
+ * save and load Store data to and from a local SQLite database.
+ *
+ * You should use the createBetterSqlite3Persister function to create a
+ * BetterSqlite3Persister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDb method for accessing a reference to the database the Store is
+ * being persisted to.
+ * @category Persister
+ * @since 9.6.0
+ */
+export interface BetterSqlite3Persister<
+  Schemas extends OptionalSchemas,
+> extends Persister<Schemas, Persists.StoreOrMergeableStore> {
+  /**
+   * The getDb method returns a reference to the database the Store is being
+   * persisted to.
+   * @returns A reference to the database.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the database back out again.
+   *
+   * ```js
+   * import Database from 'better-sqlite3';
+   * import {createStore} from 'tinybase';
+   * import {createBetterSqlite3Persister} from 'tinybase/persisters/persister-better-sqlite3';
+   *
+   * const db = new Database(':memory:');
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createBetterSqlite3Persister(store, db, 'my_tinybase');
+   *
+   * console.log(persister.getDb() == db);
+   * // -> true
+   *
+   * await persister.destroy();
+   * db.close();
+   * ```
+   * @category Getter
+   * @since 9.6.0
+   */
+  getDb(): Database;
+}
+
+/**
+ * The createBetterSqlite3Persister function creates a BetterSqlite3Persister
+ * object that can persist a Store to a local SQLite database.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createBetterSqlite3Persister<StoreType extends Store>(
+ *   store: StoreType,
+ *   db: Database,
+ *   configOrStoreTableName?:
+ *     | (NoInfer<StoreType> extends MergeableStore
+ *         ? DpcJson
+ *         : DatabasePersisterConfig)
+ *     | string,
+ *   onSqlCommand?: (sql: string, params?: any[]) => void,
+ *   onIgnoredError?: (error: any) => void,
+ * ): BetterSqlite3Persister;
+ * ```
+ *
+ * A BetterSqlite3Persister supports regular Store objects, and can also be used
+ * to persist the metadata of a MergeableStore when using the JSON serialization
+ * mode, as described below.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `db` parameter which is the database returned from `new Database(...)`.
+ *
+ * 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.
+ *
+ * Note that `better-sqlite3` does not signal when the database changes, so if
+ * you enable automatic loading with the startAutoLoad method, it polls the
+ * database for changes. The Sqlite3Persister, which uses the asynchronous
+ * `sqlite3` module, is notified of changes as they happen, and may suit you
+ * better if that matters.
+ * @param store The Store or MergeableStore to persist.
+ * @param db The database that was returned from `new Database(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @param onSqlCommand An optional handler called every time the Persister
+ * executes a SQL command or query. This is suitable for logging persistence
+ * behavior in a development environment.
+ * @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.
+ * @returns A reference to the new BetterSqlite3Persister object.
+ * @example
+ * This example creates a BetterSqlite3Persister 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
+ * import Database from 'better-sqlite3';
+ * import {createStore} from 'tinybase';
+ * import {createBetterSqlite3Persister} from 'tinybase/persisters/persister-better-sqlite3';
+ *
+ * const db = new Database(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createBetterSqlite3Persister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * console.log(db.prepare('SELECT * FROM my_tinybase;').all());
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * db.prepare('UPDATE my_tinybase SET store = ? WHERE _id = ?;').run(
+ *   '[{"pets":{"felix":{"species":"cat"}}},{}]',
+ *   '_',
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @example
+ * This example creates a BetterSqlite3Persister object and persists the Store
+ * to a local SQLite database with tabular mapping.
+ *
+ * ```js
+ * import Database from 'better-sqlite3';
+ * import {createStore} from 'tinybase';
+ * import {createBetterSqlite3Persister} from 'tinybase/persisters/persister-better-sqlite3';
+ *
+ * const db = new Database(':memory:');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createBetterSqlite3Persister(store, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(db.prepare('SELECT * FROM pets;').all());
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * db.prepare(
+ *   `INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`,
+ * ).run();
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * db.close();
+ * ```
+ * @category Creation
+ * @since 9.6.0
+ */
+export function createBetterSqlite3Persister<Schemas extends OptionalSchemas>(
+  store: MergeableStore<Schemas>,
+  db: Database,
+  configOrStoreTableName?: DpcJson | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): BetterSqlite3Persister<Schemas>;
+export function createBetterSqlite3Persister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas> & {getMergeableContent?: never},
+  db: Database,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): BetterSqlite3Persister<Schemas>;

package/@types/persisters/persister-capacitor-sqlite/index.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The persister-capacitor-sqlite module of the TinyBase project lets you save
+ * and load Store data to and from a SQLite database in a Capacitor app, via the
+ * `@capacitor-community/sqlite` plugin.
+ * @see Database Persistence guide
+ * @packageDocumentation
+ * @module persister-capacitor-sqlite
+ * @since 9.6.0
+ */
+import type {SQLiteDBConnection} from '@capacitor-community/sqlite';
+import type {MergeableStore} from '../../mergeable-store/index.d.ts';
+import type {Store} from '../../store/index.d.ts';
+import type {
+  DatabasePersisterConfig,
+  DpcJson,
+  Persister,
+  Persists,
+} from '../index.d.ts';
+
+/**
+ * The CapacitorSqlitePersister interface represents a Persister that lets you
+ * save and load Store data to and from a SQLite database in a Capacitor app.
+ *
+ * You should use the createCapacitorSqlitePersister function to create a
+ * CapacitorSqlitePersister object.
+ *
+ * It is a minor extension to the Persister interface and simply provides an
+ * extra getDb method for accessing a reference to the database connection the
+ * Store is being persisted to.
+ * @category Persister
+ * @since 9.6.0
+ */
+export interface CapacitorSqlitePersister extends Persister<Persists.StoreOrMergeableStore> {
+  /**
+   * The getDb method returns a reference to the database connection the Store
+   * is being persisted to.
+   * @returns A reference to the database connection.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the database connection back out again.
+   *
+   * ```js ignore
+   * import {
+   *   CapacitorSQLite,
+   *   SQLiteConnection,
+   * } from '@capacitor-community/sqlite';
+   * import {createStore} from 'tinybase';
+   * import {createCapacitorSqlitePersister} from 'tinybase/persisters/persister-capacitor-sqlite';
+   *
+   * const sqlite = new SQLiteConnection(CapacitorSQLite);
+   * const db = await sqlite.createConnection(
+   *   'my.db',
+   *   false,
+   *   'no-encryption',
+   *   1,
+   *   false,
+   * );
+   * await db.open();
+   *
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createCapacitorSqlitePersister(store, db, 'my_tinybase');
+   *
+   * console.log(persister.getDb() == db);
+   * // -> true
+   *
+   * await persister.destroy();
+   * ```
+   * @category Getter
+   * @since 9.6.0
+   */
+  getDb(): SQLiteDBConnection;
+}
+
+/**
+ * The createCapacitorSqlitePersister function creates a
+ * CapacitorSqlitePersister object that can persist a Store to a SQLite database
+ * in a Capacitor app.
+ *
+ * A CapacitorSqlitePersister supports regular Store objects, and can also be
+ * used to persist the metadata of a MergeableStore when using the JSON
+ * serialization mode, as described below.
+ *
+ * As well as providing a reference to the Store to persist, you must provide a
+ * `db` parameter which is an open SQLiteDBConnection, as returned from the
+ * plugin's `createConnection` method.
+ *
+ * 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.
+ *
+ * The plugin does not signal when the database changes underneath the
+ * Persister, so if you enable automatic loading with the startAutoLoad method,
+ * it polls the database for changes in the same way that the LibSqlPersister
+ * does.
+ *
+ * Note: TinyBase's tests for this module run against a mocked plugin rather
+ * than a real device, since `@capacitor-community/sqlite` needs a native iOS or
+ * Android runtime (or its `jeep-sqlite` web component) that a Node test suite
+ * cannot provide. The SQL behavior itself is covered by the other SQLite
+ * Persisters, which share all of it, but the binding to the plugin is only
+ * verified against those mocks. Please report anything that behaves differently
+ * on a real device.
+ * @param store The Store or MergeableStore to persist.
+ * @param db The database connection that was returned from
+ * `createConnection(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @param onSqlCommand An optional handler called every time the Persister
+ * executes a SQL command or query. This is suitable for logging persistence
+ * behavior in a development environment.
+ * @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.
+ * @returns A reference to the new CapacitorSqlitePersister object.
+ * @example
+ * This example creates a CapacitorSqlitePersister object and persists the Store
+ * to a 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 ignore
+ * import {
+ *   CapacitorSQLite,
+ *   SQLiteConnection,
+ * } from '@capacitor-community/sqlite';
+ * import {createStore} from 'tinybase';
+ * import {createCapacitorSqlitePersister} from 'tinybase/persisters/persister-capacitor-sqlite';
+ *
+ * const sqlite = new SQLiteConnection(CapacitorSQLite);
+ * const db = await sqlite.createConnection(
+ *   'my.db',
+ *   false,
+ *   'no-encryption',
+ *   1,
+ *   false,
+ * );
+ * await db.open();
+ *
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createCapacitorSqlitePersister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * console.log((await db.query('SELECT * FROM my_tinybase;')).values);
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * await db.run(
+ *   'UPDATE my_tinybase SET store = ? WHERE _id = ?;',
+ *   ['[{"pets":{"felix":{"species":"cat"}}},{}]', '_'],
+ *   false,
+ * );
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {felix: {species: 'cat'}}}
+ *
+ * await persister.destroy();
+ * ```
+ * @category Creation
+ * @since 9.6.0
+ */
+export function createCapacitorSqlitePersister<StoreType extends Store>(
+  store: StoreType,
+  db: SQLiteDBConnection,
+  configOrStoreTableName?:
+    | (NoInfer<StoreType> extends MergeableStore
+        ? DpcJson
+        : DatabasePersisterConfig)
+    | string,
+  onSqlCommand?: (sql: string, params?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): CapacitorSqlitePersister;