tinybase 6.1.0-beta.4 → 6.1.0-beta.5

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

@@ -39,9 +39,9 @@
  * create a fully customized way to save and load Store data.
  *
  * Similarly, the createCustomSqlitePersister function and
- * createCustomPostgreSqlPersister function can be used to build Persister objects
- * against SQLite and PostgreSQL SDKs (or forks) that are not already included
- * with TinyBase.
+ * createCustomPostgreSqlPersister function can be used to build Persister
+ * objects against SQLite and PostgreSQL SDKs (or forks) that are not already
+ * included with TinyBase.
  * @see Persistence guides
  * @see Countries demo
  * @see Todo App demos
@@ -66,8 +66,8 @@ import type {
 import type {Id} from '../../with-schemas/index.d.ts';
 
 /**
- * The Status enum is used to indicate whether a Persister is idle, or loading or
- * saving data.
+ * The Status enum is used to indicate whether a Persister is idle, or loading
+ * or saving data.
  *
  * The enum is intended to be used to understand the status of the Persister in
  * conjunction with the getStatus and addStatusListener methods.
@@ -592,6 +592,23 @@ export type DpcTabular<Schema extends OptionalTablesSchema> = {
   autoLoadIntervalSeconds?: number;
 };
 
+/**
+ * The DpcTabularCondition type describes the SQL WHERE clause that will be used
+ * to filter the rows that are loaded and saved to in the Store Table.
+ *
+ * This provides a way to enact pagination or selective loading of data from the
+ * database into TinyBase so that only a fraction of the full data in the
+ * database is loaded into memory.
+ *
+ * This clause must include at least one `$tableName` placeholder for the table
+ * name. For example, if you only wanted to load and save records that have an
+ * 'active' flag set, this string would be something like `$tableName.active =
+ * 1`.
+ * @category Configuration
+ * @since v6.1.0
+ */
+export type DpcTabularCondition = `${string}$tableName${string}` | 'true';
+
 /**
  * The DpcTabularLoad type describes the configuration for loading Tables in a
  * database-oriented Persister that is operating in tabular mode.
@@ -604,6 +621,7 @@ export type DpcTabular<Schema extends OptionalTablesSchema> = {
  * |-|-|-|
  * |`tableId`|Id|The Id of the Store Table into which data from this database table should be loaded.|
  * |`rowIdColumnName?`|string|The optional name of the column in the database table that will be used as the Row Ids in the Store Table, defaulting to '_id'.|
+ * |`condition?`|string|The optional SQL WHERE clause that will be used to filter the rows that are loaded into the Store Table. When set it must include the `$tableName` placeholder for the table name, since v6.1.0.|
  *
  * As a shortcut, if you do not need to specify a custom `rowIdColumnName`, you
  * can simply provide the Id of the Store Table instead of the whole object.
@@ -690,6 +708,16 @@ export type DpcTabularLoad<Schema extends OptionalTablesSchema> = {
          * @since v4.0.0
          */
         rowIdColumnName?: string;
+        /**
+         * The optional SQL WHERE clause that will be used to filter the rows
+         * that are loaded into the Store Table. When set it must include the
+         * `$tableName` placeholder for the table name. See the 'Syncing with
+         * subsets of database tables' section of the Database Persistence guide
+         * for more details.
+         * @category Configuration
+         * @since v6.1.0
+         */
+        condition?: DpcTabularCondition;
       }
     | TableIdFromSchema<Schema>;
 };
@@ -708,6 +736,7 @@ export type DpcTabularLoad<Schema extends OptionalTablesSchema> = {
  * |`rowIdColumnName?`|string|The optional name of the column in the database table that will be used to save the Row Ids from the Store Table, defaulting to '_id'.|
  * |`deleteEmptyColumns?`|boolean|Whether columns in the database table will be removed if they are empty in the Store Table, defaulting to false.|
  * |`deleteEmptyTable?`|boolean|Whether tables in the database will be removed if the Store Table is empty, defaulting to false.|
+ * |`condition?`|string|The optional SQL WHERE clause that will be used to scope cleanup operations to the Store Table. When set it must include the `$tableName` placeholder for the table name, since v6.1.0. Defaults to `DpcTabularLoad.condition`.|
  *
  * As a shortcut, if you do not need to specify a custom `rowIdColumnName`, or
  * enable the `deleteEmptyColumns` or `deleteEmptyTable` settings, you can
@@ -821,6 +850,16 @@ export type DpcTabularSave<Schema extends OptionalTablesSchema> = {
          * @since v4.0.0
          */
         deleteEmptyTable?: boolean;
+        /**
+         * The optional SQL WHERE clause that will be used to scope cleanup
+         * operations to the Store Table. When set it must include the
+         * `$tableName` placeholder for the table name. Defaults to
+         * `DpcTabularLoad.condition`.See the 'Syncing with subsets of database
+         * tables' section of the Database Persistence guide for more details.
+         * @category Configuration
+         * @since v6.1.0
+         */
+        condition?: DpcTabularCondition;
       }
     | string;
 };
@@ -955,7 +994,7 @@ export type DpcTabularValues = {
  * console.log(store.getTables());
  * // -> {pets: {toto: {species: 'dog'}}}
  *
- * persister.destroy();
+ * await persister.destroy();
  * sessionStorage.clear();
  * ```
  * @example
@@ -986,7 +1025,7 @@ export type DpcTabularValues = {
  * console.log(store.getTables());
  * // -> {pets: {toto: {species: 'dog'}}}
  *
- * persister.destroy();
+ * await persister.destroy();
  * sessionStorage.clear();
  * ```
  * @category Persister
@@ -1129,7 +1168,7 @@ export interface Persister<
    * console.log(store.getTables());
    * // -> {pets: {toto: {species: 'dog'}}}
    *
-   * persister.destroy();
+   * await persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Load
@@ -1144,8 +1183,8 @@ export interface Persister<
    * previously started with the startAutoLoad method.
    *
    * If the Persister is not currently set to automatically load, this method
-   * has no effect.
-   * @returns A reference to the Persister object.
+   * has no effect. This method is asynchronous.
+   * @returns A Promise containing a reference to the Persister object.
    * @example
    * This example creates an empty Store, and starts automatically loading data
    * into it from the browser's session storage. Once the automatic loading is
@@ -1166,7 +1205,7 @@ export interface Persister<
    * console.log(store.getTables());
    * // -> {pets: {toto: {species: 'dog'}}}
    *
-   * persister.stopAutoLoad();
+   * await persister.stopAutoLoad();
    *
    * // In another browser tab:
    * sessionStorage.setItem(
@@ -1179,13 +1218,13 @@ export interface Persister<
    * // -> {pets: {toto: {species: 'dog'}}}
    * // Storage change has not been automatically loaded.
    *
-   * persister.destroy();
+   * await persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Load
    * @since v1.0.0
    */
-  stopAutoLoad(): this;
+  stopAutoLoad(): Promise<this>;
 
   /**
    * The isAutoLoading method lets you find out if the Persister is currently
@@ -1241,7 +1280,7 @@ export interface Persister<
    * console.log(sessionStorage.getItem('pets'));
    * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
    *
-   * persister.destroy();
+   * await persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Save
@@ -1295,8 +1334,8 @@ export interface Persister<
    * previously started with the startAutoSave method.
    *
    * If the Persister is not currently set to automatically save, this method
-   * has no effect.
-   * @returns A reference to the Persister object.
+   * has no effect. This method is asynchronous.
+   * @returns A Promise containing a reference to the Persister object.
    * @example
    * This example creates a Store with some data, and saves into the browser's
    * session storage. Subsequent changes to the Store are then automatically
@@ -1316,7 +1355,7 @@ export interface Persister<
    * console.log(sessionStorage.getItem('pets'));
    * // -> '[{"pets":{"toto":{"species":"dog"}}},{}]'
    *
-   * persister.stopAutoSave();
+   * await persister.stopAutoSave();
    *
    * store.setTables({pets: {felix: {species: 'cat'}}});
    * // ...
@@ -1329,7 +1368,7 @@ export interface Persister<
    * @category Save
    * @since v1.0.0
    */
-  stopAutoSave(): this;
+  stopAutoSave(): Promise<this>;
 
   /**
    * The isAutoSaving method lets you find out if the Persister is currently
@@ -1515,8 +1554,8 @@ export interface Persister<
    *   async (getContent) => {
    *     // setPersisted
    *     await persister.schedule(
-   *       async () => await checkRemoteSystemIsReady(),
-   *       async () => await sendDataToRemoteSystem(getContent()),
+   *       () => checkRemoteSystemIsReady(),
+   *       () => sendDataToRemoteSystem(getContent()),
    *     );
    *   },
    *   (listener) => setInterval(listener, 1000),
@@ -1568,8 +1607,8 @@ export interface Persister<
    * This guarantees that all of the listeners that the object registered with
    * the underlying Store and storage are removed and it can be correctly
    * garbage collected. It is equivalent to running the stopAutoLoad method and
-   * the stopAutoSave method in succession.
-   * @returns A reference to the Persister object.
+   * the stopAutoSave method in succession. This method is asynchronous.
+   * @returns A Promise containing a reference to the Persister object.
    * @example
    * This example creates a Store, associates a Persister object with it (that
    * registers a TablesListener with the underlying Store), and then destroys it
@@ -1586,7 +1625,7 @@ export interface Persister<
    * console.log(store.getListenerStats().transaction);
    * // -> 1
    *
-   * persister.destroy();
+   * await persister.destroy();
    *
    * console.log(store.getListenerStats().transaction);
    * // -> 0
@@ -1594,7 +1633,7 @@ export interface Persister<
    * @category Lifecycle
    * @since v1.0.0
    */
-  destroy(): this;
+  destroy(): Promise<this>;
 
   /**
    * The getStats method provides a set of statistics about the Persister, and
@@ -1634,7 +1673,7 @@ export interface Persister<
    * console.log(persister.getStats());
    * // -> {loads: 2, saves: 2}
    *
-   * persister.destroy();
+   * await persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Development
@@ -1714,7 +1753,9 @@ export type DatabaseChangeListener = (tableName: string) => void;
  *   addPersisterListener: (
  *     listener: PersisterListener<Persist>,
  *   ) => ListenerHandle | Promise<ListenerHandle>,
- *   delPersisterListener: (listenerHandle: ListenerHandle) => void,
+ *   delPersisterListener: (
+ *     listenerHandle: ListenerHandle,
+ *   ) => void | Promise<void>,
  *   onIgnoredError?: (error: any) => void,
  *   persist?: Persist,
  * ): Persister<Persist>;
@@ -1754,7 +1795,8 @@ export type DatabaseChangeListener = (tableName: string) => void;
  * called. This function can be asynchronous.
  * @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.
+ * returned from your `addPersisterListener` implementation. This function can
+ * be asynchronous.
  * @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.
@@ -1801,7 +1843,7 @@ export type DatabaseChangeListener = (tableName: string) => void;
  * console.log(store.getTables());
  * // -> {pets: {fido: {species: 'dog', color: 'brown'}}}
  *
- * persister.destroy();
+ * await persister.destroy();
  * ```
  * @example
  * This example demonstrates a Persister creation function which returns a
@@ -1838,7 +1880,7 @@ export type DatabaseChangeListener = (tableName: string) => void;
  * await storePersister.save();
  * console.log(persistedJson);
  * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
- * storePersister.destroy();
+ * await storePersister.destroy();
  *
  * const mergeableStore = createMergeableStore('mergeableStore1'); // !reset
  * mergeableStore.setTables({pets: {fido: {species: 'dog'}}});
@@ -1866,7 +1908,7 @@ export type DatabaseChangeListener = (tableName: string) => void;
  *   ],
  *   [{}, '', 0],
  * ];
- * mergeableStorePersister.destroy();
+ * await mergeableStorePersister.destroy();
  * ```
  * @category Creation
  * @since v1.0.0
@@ -1885,7 +1927,9 @@ export function createCustomPersister<
   addPersisterListener: (
     listener: PersisterListener<Schemas, Persist>,
   ) => ListenerHandle | Promise<ListenerHandle>,
-  delPersisterListener: (listenerHandle: ListenerHandle) => void,
+  delPersisterListener: (
+    listenerHandle: ListenerHandle,
+  ) => void | Promise<void>,
   onIgnoredError?: (error: any) => void,
   persist?: Persist,
 ): Persister<Schemas, Persist>;
@@ -1970,8 +2014,8 @@ export function createCustomSqlitePersister<
 ): Persister<Schemas, Persist>;
 
 /**
- * The createCustomSqlitePersister function creates a Persister object that you
- * can configure to persist the Store to a PostgreSQL database.
+ * The createCustomPostgreSqlPersister function creates a Persister object that
+ * you can configure to persist the Store to a PostgreSQL database.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -1987,7 +2031,7 @@ export function createCustomSqlitePersister<
  *     channel: string,
  *     listener: DatabaseChangeListener,
  *   ) => Promise<ListenerHandle>,
- *   delChangeListener: (listenerHandle: ListenerHandle) => void,
+ *   delChangeListener: (listenerHandle: ListenerHandle) => void | Promise<void>,
  *   onSqlCommand: ((sql: string, params?: any[]) => void) | undefined,
  *   onIgnoredError: ((error: any) => void) | undefined,
  *   destroy: () => void,
@@ -2002,18 +2046,18 @@ export function createCustomSqlitePersister<
  *
  * All of the TinyBase PostgreSQL-oriented Persister functions use this function
  * under the covers, and so you may wish to look at those implementations for
- * ideas on how to build your own Persister type, and as functional
- * examples. Examine the implementation of the createPostgresPersister function
- * as a good starting point, for example.
+ * ideas on how to build your own Persister type, and as functional examples.
+ * Examine the implementation of the createPostgresPersister function as a good
+ * starting point, for example.
  * @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.
- * @param addChangeListener A function that will register a listener for changes
- * to the database.
- * @param delChangeListener A function that will unregister the listener for
- * changes to the database.
+ * @param addChangeListener An asynchronous function that will register a
+ * listener for changes to the database.
+ * @param delChangeListener An asynchronous function that will unregister the
+ * listener for changes to the database.
  * @param onSqlCommand A function that will be called for each SQL command
  * executed against the database.
  * @param onIgnoredError An optional handler for the errors that the Persister
@@ -2045,7 +2089,7 @@ export function createCustomPostgreSqlPersister<
     channel: string,
     listener: DatabaseChangeListener,
   ) => Promise<ListenerHandle>,
-  delChangeListener: (listenerHandle: ListenerHandle) => void,
+  delChangeListener: (listenerHandle: ListenerHandle) => void | Promise<void>,
   onSqlCommand: ((sql: string, params?: any[]) => void) | undefined,
   onIgnoredError: ((error: any) => void) | undefined,
   destroy: () => void,

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

@@ -194,8 +194,8 @@ export type SynchronizerStats = {
  * console.log(store1.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
  * ```
  * @category Synchronizer
  * @since v5.0.0
@@ -243,8 +243,8 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
    * console.log(store1.getTables());
    * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
    *
-   * synchronizer1.destroy();
-   * synchronizer2.destroy();
+   * await synchronizer1.destroy();
+   * await synchronizer2.destroy();
    * ```
    * @example
    * This example creates two empty MergeableStore objects, creates a
@@ -274,8 +274,8 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
    * console.log(store2.getTables());
    * // -> {pets: {fido: {species: 'dog'}}}
    *
-   * synchronizer1.destroy();
-   * synchronizer2.destroy();
+   * await synchronizer1.destroy();
+   * await synchronizer2.destroy();
    * ```
    * @category Synchronization
    * @since v5.0.0
@@ -289,7 +289,9 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
    * Persister framework, and so this startSync method is equivalent to stopping
    * both auto-loading (listening to sync messages from other active
    * Synchronizer instances) and auto-saving (sending sync messages to them).
-   * @returns A reference to the Synchronizer object.
+   *
+   * This method is asynchronous.
+   * @returns A Promise containing a reference to the Synchronizer object.
    * @example
    * This example creates two empty MergeableStore objects, creates a
    * LocalSynchronizer for each, and starts - then stops - synchronizing them.
@@ -314,8 +316,8 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
    * console.log(store2.getTables());
    * // -> {pets: {fido: {species: 'dog'}}}
    *
-   * synchronizer1.stopSync();
-   * synchronizer2.stopSync();
+   * await synchronizer1.stopSync();
+   * await synchronizer2.stopSync();
    *
    * store1.setCell('pets', 'fido', 'color', 'brown');
    * // ...
@@ -324,13 +326,13 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
    * console.log(store2.getTables());
    * // -> {pets: {fido: {species: 'dog'}}}
    *
-   * synchronizer1.destroy();
-   * synchronizer2.destroy();
+   * await synchronizer1.destroy();
+   * await synchronizer2.destroy();
    * ```
    * @category Synchronization
    * @since v5.0.0
    */
-  stopSync(): this;
+  stopSync(): Promise<this>;
   /**
    * The getSynchronizerStats method provides a set of statistics about the
    * Synchronizer, and is used for debugging purposes.
@@ -369,8 +371,8 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
    * console.log(synchronizer2.getSynchronizerStats());
    * // -> {receives: 5, sends: 4}
    *
-   * synchronizer1.destroy();
-   * synchronizer2.destroy();
+   * await synchronizer1.destroy();
+   * await synchronizer2.destroy();
    * ```
    * @category Synchronization
    * @since v5.0.0
@@ -467,8 +469,8 @@ export interface Synchronizer extends Persister<Persists.MergeableStoreOnly> {
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
  * ```
  * @category Creation
  * @since v5.0.0

package/@types/synchronizers/synchronizer-broadcast-channel/index.d.ts

@@ -42,7 +42,7 @@ export interface BroadcastChannelSynchronizer extends Synchronizer {
    * console.log(synchronizer.getChannelName());
    * // -> 'channelA'
    *
-   * synchronizer.destroy();
+   * await synchronizer.destroy();
    * ```
    * @category Getter
    * @since v5.0.0
@@ -106,8 +106,8 @@ export interface BroadcastChannelSynchronizer extends Synchronizer {
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
  * ```
  * @category Creation
  * @since v5.0.0

package/@types/synchronizers/synchronizer-broadcast-channel/with-schemas/index.d.ts

@@ -44,7 +44,7 @@ export interface BroadcastChannelSynchronizer<Schemas extends OptionalSchemas>
    * console.log(synchronizer.getChannelName());
    * // -> 'channelA'
    *
-   * synchronizer.destroy();
+   * await synchronizer.destroy();
    * ```
    * @category Getter
    * @since v5.0.0
@@ -120,8 +120,8 @@ export interface BroadcastChannelSynchronizer<Schemas extends OptionalSchemas>
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
  * ```
  * @category Creation
  * @since v5.0.0

package/@types/synchronizers/synchronizer-local/index.d.ts

@@ -81,8 +81,8 @@ export interface LocalSynchronizer extends Synchronizer {}
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
  * ```
  * @category Creation
  * @since v5.0.0

package/@types/synchronizers/synchronizer-local/with-schemas/index.d.ts

@@ -100,8 +100,8 @@ export interface LocalSynchronizer<Schemas extends OptionalSchemas>
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
  * ```
  * @category Creation
  * @since v5.0.0

package/@types/synchronizers/synchronizer-ws-client/index.d.ts

@@ -63,8 +63,8 @@ export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
    * console.log(synchronizer.getWebSocket() == webSocket);
    * // -> true
    *
-   * synchronizer.destroy();
-   * server.destroy();
+   * await synchronizer.destroy();
+   * await server.destroy();
    * ```
    * @category Getter
    * @since v5.0.0
@@ -143,9 +143,9 @@ export interface WsSynchronizer<WebSocketType extends WebSocketTypes>
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
- * server.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
+ * await server.destroy();
  * ```
  * @category Creation
  * @since v5.0.0

package/@types/synchronizers/synchronizer-ws-client/with-schemas/index.d.ts

@@ -66,8 +66,8 @@ export interface WsSynchronizer<
    * console.log(synchronizer.getWebSocket() == webSocket);
    * // -> true
    *
-   * synchronizer.destroy();
-   * server.destroy();
+   * await synchronizer.destroy();
+   * await server.destroy();
    * ```
    * @category Getter
    * @since v5.0.0
@@ -159,9 +159,9 @@ export interface WsSynchronizer<
  * console.log(store2.getTables());
  * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
  *
- * synchronizer1.destroy();
- * synchronizer2.destroy();
- * server.destroy();
+ * await synchronizer1.destroy();
+ * await synchronizer2.destroy();
+ * await server.destroy();
  * ```
  * @category Creation
  * @since v5.0.0