[docs] Document onIgnoredError and onSqlCommand

Author: jamesgpearce

site/guides/3_schemas_and_persistence/4_persisting_data.md

@@ -115,13 +115,21 @@ 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.
+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 persistence
+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.
+
 ## Summary
 
 Use the persisters module to load and save data from and to a variety of common

src/types/docs/persisters.js

@@ -565,13 +565,21 @@
  * 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
@@ -1052,6 +1060,9 @@
  * @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

src/types/docs/persisters/persister-automerge.js

@@ -21,6 +21,9 @@
  * @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

src/types/docs/persisters/persister-browser.js

@@ -23,6 +23,9 @@
  * 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
@@ -51,6 +54,9 @@
  * 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

src/types/docs/persisters/persister-cr-sqlite-wasm.js

@@ -12,8 +12,8 @@
  * 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
@@ -31,6 +31,12 @@
  * @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

src/types/docs/persisters/persister-expo-sqlite.js

@@ -38,6 +38,12 @@
  * @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

src/types/docs/persisters/persister-file.js

@@ -14,6 +14,9 @@
  * `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

src/types/docs/persisters/persister-remote.js

@@ -23,6 +23,9 @@
  * @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

src/types/docs/persisters/persister-sqlite-wasm.js

@@ -33,6 +33,12 @@
  * @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

src/types/docs/persisters/persister-sqlite3.js

@@ -31,6 +31,12 @@
  * @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