tinybase 4.0.2 → 4.0.4

package/lib/types/persisters/persister-browser.d.ts

@@ -26,6 +26,9 @@ import {Store} from '../store';
  * 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.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to the
@@ -47,6 +50,7 @@ import {Store} from '../store';
 export function createSessionPersister(
   store: Store,
   storageName: string,
+  onIgnoredError?: (error: any) => void,
 ): Persister;
 
 /**
@@ -58,6 +62,9 @@ export function createSessionPersister(
  * 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.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to the
@@ -79,4 +86,5 @@ export function createSessionPersister(
 export function createLocalPersister(
   store: Store,
   storageName: string,
+  onIgnoredError?: (error: any) => void,
 ): Persister;

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

@@ -16,8 +16,8 @@ import {Store} from '../store';
  * persist the Store to a local CR-SQLite database (in an appropriate
  * environment).
  *
- * As well as providing a reference to the Store to persist, you must provide
- * a `db` parameter which identifies the database instance.
+ * 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
@@ -35,6 +35,12 @@ import {Store} from '../store';
  * @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, since v4.0.4.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a local
@@ -94,4 +100,6 @@ export function createCrSqliteWasmPersister(
   store: Store,
   db: DB,
   configOrStoreTableName?: DatabasePersisterConfig | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
 ): Persister;

package/lib/types/persisters/persister-expo-sqlite.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The persister-expo-sqlite module of the TinyBase project lets you save and
+ * load Store data to and from a local Expo-SQLite database (in an appropriate
+ * React Native environment).
+ *
+ * Note that this Persister is currently experimental as Expo themselves iterate
+ * on the underlying database library API.
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-expo-sqlite
+ */
+
+import {DatabasePersisterConfig, Persister} from '../persisters';
+import {SQLiteDatabase} from 'expo-sqlite';
+import {Store} from '../store';
+
+/**
+ * The createExpoSqlitePersister function creates a Persister object that can
+ * persist the Store to a local Expo-SQLite database (in an appropriate React
+ * Native environment).
+ *
+ * Note that this Persister is currently experimental as Expo themselves iterate
+ * on the underlying database library API.
+ *
+ * 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
+ * `SQLite.openDatabase(...)`.
+ * @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, since v4.0.4.
+ * @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.
+ * @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 yolo
+ * const db = SQLite.openDatabase('my.db');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createExpoSqlitePersister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * 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 yolo
+ * const db = SQLite.openDatabase('my.db');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createExpoSqlitePersister(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 createExpoSqlitePersister(
+  store: Store,
+  db: SQLiteDatabase,
+  configOrStoreTableName?: DatabasePersisterConfig | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): Persister;

package/lib/types/persisters/persister-file.d.ts

@@ -17,6 +17,9 @@ import {Store} from '../store';
  * `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.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a local
@@ -36,4 +39,8 @@ import {Store} from '../store';
  * ```
  * @category Creation
  */
-export function createFilePersister(store: Store, filePath: string): Persister;
+export function createFilePersister(
+  store: Store,
+  filePath: string,
+  onIgnoredError?: (error: any) => void,
+): Persister;

package/lib/types/persisters/persister-remote.d.ts

@@ -26,6 +26,9 @@ import {Store} from '../store';
  * @param saveUrl The endpoint that supports a `POST` method to save JSON.
  * @param autoLoadIntervalSeconds How often to poll the `loadUrl` when
  * automatically loading changes from the server.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a remote
@@ -55,4 +58,5 @@ export function createRemotePersister(
   loadUrl: string,
   saveUrl: string,
   autoLoadIntervalSeconds: number,
+  onIgnoredError?: (error: any) => void,
 ): Persister;

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

@@ -36,6 +36,12 @@ import {Store} from '../store';
  * @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, since v4.0.4.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a local
@@ -101,4 +107,6 @@ export function createSqliteWasmPersister(
   sqlite3: any,
   db: any,
   configOrStoreTableName?: DatabasePersisterConfig | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
 ): Persister;

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

@@ -35,6 +35,12 @@ import {Store} from '../store';
  * @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, since v4.0.4.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a local
@@ -108,4 +114,6 @@ export function createSqlite3Persister(
   store: Store,
   db: Database,
   configOrStoreTableName?: DatabasePersisterConfig | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
 ): Persister;

package/lib/types/persisters/persister-yjs.d.ts

@@ -25,6 +25,9 @@ import {Doc as YDoc} from 'yjs';
  * @param yDoc The Yjs document to persist the Store to.
  * @param yMapName The name of the Y.Map used inside the Yjs document to sync
  * the Store to (which otherwise will default to 'tinybase').
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a Yjs
@@ -102,4 +105,5 @@ export function createYjsPersister(
   store: Store,
   yDoc: YDoc,
   yMapName?: string,
+  onIgnoredError?: (error: any) => void,
 ): Persister;

package/lib/types/persisters.d.ts

@@ -17,6 +17,7 @@
  * |persister-sqlite3|createSqlite3Persister|SQLite in Node, via [sqlite3](https://github.com/TryGhost/node-sqlite3)|
  * |persister-sqlite-wasm|createSqliteWasmPersister|SQLite in a browser, via [sqlite-wasm](https://github.com/tomayac/sqlite-wasm)|
  * |persister-cr-sqlite-wasm|createCrSqliteWasmPersister|SQLite CRDTs, via [cr-sqlite-wasm](https://github.com/vlcn-io/cr-sqlite)|
+ * |persister-expo-sqlite|createExpoSqlitePersister|SQLite in React Native, via [expo-sqlite](https://github.com/expo/expo/tree/main/packages/expo-sqlite)|
  * |persister-yjs|createYjsPersister|Yjs CRDTs, via [yjs](https://github.com/yjs/yjs)|
  * |persister-automerge|createSqliteWasmPersister|Automerge CRDTs, via [automerge-repo](https://github.com/automerge/automerge-repo)|
  *
@@ -569,13 +570,21 @@ export type DpcTabularValues = {
  * 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.
+ * it is currently loading it and vice-versa - and will sequentially schedule
+ * methods that could cause race conditions.
  *
- * Be aware, however, that the default implementations do not provide complex
- * synchronization heuristics and you should comprehensively test your
+ * 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
@@ -1070,6 +1079,9 @@ export interface Persister {
  * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a custom Persister object and persists the Store to a
@@ -1117,4 +1129,5 @@ export function createCustomPersister<ListeningHandle>(
   ) => Promise<void>,
   addPersisterListener: (listener: PersisterListener) => ListeningHandle,
   delPersisterListener: (listeningHandle: ListeningHandle) => void,
+  onIgnoredError?: (error: any) => void,
 ): Persister;

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

@@ -26,6 +26,7 @@ import {Persister} from '../persisters';
  *   store: Store,
  *   docHandle: DocHandle<any>,
  *   docMapName?: string,
+ *   onIgnoredError?: (error: any) => void,
  * ): Persister;
  * ```
  *
@@ -35,6 +36,9 @@ import {Persister} from '../persisters';
  * @param docHandle The Automerge document handler to persist the Store with.
  * @param docMapName The name of the map used inside the Automerge document to
  * sync the Store to (which otherwise will default to 'tinybase').
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to an
@@ -115,4 +119,5 @@ export function createAutomergePersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,
   docHandle: DocHandle<any>,
   docMapName?: string,
+  onIgnoredError?: (error: any) => void,
 ): Persister<Schemas>;

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

@@ -27,6 +27,7 @@ import {Persister} from '../persisters';
  * createSessionPersister(
  *   store: Store,
  *   storageName: string,
+ *   onIgnoredError?: (error: any) => void,
  * ): Persister;
  * ```
  *
@@ -35,6 +36,9 @@ import {Persister} from '../persisters';
  * 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.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to the
@@ -56,6 +60,7 @@ import {Persister} from '../persisters';
 export function createSessionPersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,
   storageName: string,
+  onIgnoredError?: (error: any) => void,
 ): Persister<Schemas>;
 
 /**
@@ -68,6 +73,7 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
  * createLocalPersister(
  *   store: Store,
  *   storageName: string,
+ *   onIgnoredError?: (error: any) => void,
  * ): Persister;
  * ```
  *
@@ -76,6 +82,9 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
  * 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.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to the
@@ -97,4 +106,5 @@ export function createSessionPersister<Schemas extends OptionalSchemas>(
 export function createLocalPersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,
   storageName: string,
+  onIgnoredError?: (error: any) => void,
 ): Persister<Schemas>;

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

@@ -23,11 +23,13 @@ import {DB} from '@vlcn.io/crsqlite-wasm';
  *   store: Store,
  *   db: DB,
  *   configOrStoreTableName?: DatabasePersisterConfig | string,
+ *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onIgnoredError?: (error: any) => void,
  * ): Persister;
  * ```
  *
- * As well as providing a reference to the Store to persist, you must provide
- * a `db` parameter which identifies the database instance.
+ * 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
@@ -45,6 +47,12 @@ import {DB} from '@vlcn.io/crsqlite-wasm';
  * @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, since v4.0.4.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a local
@@ -104,4 +112,6 @@ export function createCrSqliteWasmPersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,
   db: DB,
   configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
 ): Persister<Schemas>;

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

@@ -0,0 +1,138 @@
+/**
+ * The persister-expo-sqlite module of the TinyBase project lets you save and
+ * load Store data to and from a local Expo-SQLite database (in an appropriate
+ * React Native environment).
+ *
+ * Note that this Persister is currently experimental as Expo themselves iterate
+ * on the underlying database library API.
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-expo-sqlite
+ */
+
+import {DatabasePersisterConfig, Persister} from '../persisters';
+import {OptionalSchemas, Store} from '../store';
+import {SQLiteDatabase} from 'expo-sqlite';
+
+/**
+ * The createExpoSqlitePersister function creates a Persister object that can
+ * persist the Store to a local Expo-SQLite database (in an appropriate React
+ * Native environment).
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createExpoSqlitePersister(
+ *   store: Store,
+ *   db: SQLiteDatabase,
+ *   configOrStoreTableName?: DatabasePersisterConfig | string,
+ *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onIgnoredError?: (error: any) => void,
+ * ): Persister;
+ * ```
+ *
+ * Note that this Persister is currently experimental as Expo themselves iterate
+ * on the underlying database library API.
+ *
+ * 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
+ * `SQLite.openDatabase(...)`.
+ * @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, since v4.0.4.
+ * @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.
+ * @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 yolo
+ * const db = SQLite.openDatabase('my.db');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createExpoSqlitePersister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * // Store will be saved to the database.
+ *
+ * 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 yolo
+ * const db = SQLite.openDatabase('my.db');
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createExpoSqlitePersister(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 createExpoSqlitePersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  db: SQLiteDatabase,
+  configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
+): Persister<Schemas>;

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

@@ -16,13 +16,20 @@ import {Persister} from '../persisters';
  * This has schema-based typing. The following is a simplified representation:
  *
  * ```ts override
- * createFilePersister(store: Store, filePath: string): Persister;
+ * createFilePersister(
+ *   store: Store,
+ *   filePath: string,
+ *   onIgnoredError?: (error: any) => void,
+ * ): Persister;
  * ```
  *
  * 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.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a local
@@ -45,4 +52,5 @@ import {Persister} from '../persisters';
 export function createFilePersister<Schemas extends OptionalSchemas>(
   store: Store<Schemas>,
   filePath: string,
+  onIgnoredError?: (error: any) => void,
 ): Persister<Schemas>;

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

@@ -21,6 +21,7 @@ import {Persister} from '../persisters';
  *   loadUrl: string,
  *   saveUrl: string,
  *   autoLoadIntervalSeconds: number,
+ *   onIgnoredError?: (error: any) => void,
  * ): Persister;
  * ```
  *
@@ -37,6 +38,9 @@ import {Persister} from '../persisters';
  * @param saveUrl The endpoint that supports a `POST` method to save JSON.
  * @param autoLoadIntervalSeconds How often to poll the `loadUrl` when
  * automatically loading changes from the server.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a remote
@@ -66,4 +70,5 @@ export function createRemotePersister<Schemas extends OptionalSchemas>(
   loadUrl: string,
   saveUrl: string,
   autoLoadIntervalSeconds: number,
+  onIgnoredError?: (error: any) => void,
 ): Persister<Schemas>;

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

@@ -22,6 +22,8 @@ import {OptionalSchemas, Store} from '../store';
  *   sqlite3: any,
  *   db: any,
  *   configOrStoreTableName?: DatabasePersisterConfig | string,
+ *   onSqlCommand?: (sql: string, args?: any[]) => void,
+ *   onIgnoredError?: (error: any) => void,
  * ): Persister;
  * ```
  *
@@ -47,6 +49,12 @@ import {OptionalSchemas, Store} from '../store';
  * @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, since v4.0.4.
+ * @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.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a Persister object and persists the Store to a local
@@ -112,4 +120,6 @@ export function createSqliteWasmPersister<Schemas extends OptionalSchemas>(
   sqlite3: any,
   db: any,
   configOrStoreTableName?: DatabasePersisterConfig<Schemas> | string,
+  onSqlCommand?: (sql: string, args?: any[]) => void,
+  onIgnoredError?: (error: any) => void,
 ): Persister<Schemas>;