tinybase 4.4.0-beta.0 → 4.4.0-beta.2

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

@@ -12,6 +12,40 @@ import {DatabasePersisterConfig, Persister} from '../persisters';
 import {OptionalSchemas, Store} from '../store';
 import {Database} from 'sqlite3';
 
+/**
+ * The Sqlite3Persister interface is a minor extension to the Persister
+ * interface.
+ *
+ * It simply provides an extra getDb method for accessing a reference to the
+ * database instance the Store is being persisted to.
+ * @since v4.3.14
+ */
+export interface Sqlite3Persister<Schemas extends OptionalSchemas>
+  extends Persister<Schemas> {
+  /**
+   * The getDb method returns a reference to the database instance the Store is
+   * being persisted to.
+   * @returns A reference to the database instance.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the database instance back out again.
+   *
+   * ```js
+   * const db = new sqlite3.Database(':memory:');
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createSqlite3Persister(store, db, 'my_tinybase');
+   *
+   * console.log(persister.getDb() == db);
+   * // -> true
+   *
+   * persister.destroy();
+   * ```
+   * @category Getter
+   * @since v4.3.14
+   */
+  getDb: () => Database;
+}
+
 /**
  * The createSqlite3Persister function creates a Persister object that can
  * persist the Store to a local SQLite database (in an appropriate environment).
@@ -25,7 +59,7 @@ import {Database} from 'sqlite3';
  *   configOrStoreTableName?: DatabasePersisterConfig | string,
  *   onSqlCommand?: (sql: string, args?: any[]) => void,
  *   onIgnoredError?: (error: any) => void,
- * ): Persister;
+ * ): Sqlite3Persister;
  * ```
  *
  * As well as providing a reference to the Store to persist, you must provide a
@@ -54,11 +88,11 @@ import {Database} from 'sqlite3';
  * @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.
+ * @returns A reference to the new Sqlite3Persister 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
+ * This example creates a Sqlite3Persister 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
@@ -90,8 +124,8 @@ import {Database} from 'sqlite3';
  * persister.destroy();
  * ```
  * @example
- * This example creates a Persister object and persists the Store to a local
- * SQLite database with tabular mapping.
+ * This example creates a Sqlite3Persister object and persists the Store to a
+ * local SQLite database with tabular mapping.
  *
  * ```js
  * const db = new sqlite3.Database(':memory:');

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

@@ -15,6 +15,39 @@ import {OptionalSchemas, Store} from '../store.d';
 import {Persister} from '../persisters.d';
 import {Doc as YDoc} from 'yjs';
 
+/**
+ * The YjsPersister interface is a minor extension to the Persister interface.
+ *
+ * It simply provides an extra getYDoc method for accessing the Yjs document the
+ * Store is being persisted to.
+ * @since v4.3.14
+ */
+export interface YjsPersister<Schemas extends OptionalSchemas>
+  extends Persister<Schemas> {
+  /**
+   * The getYDoc method returns the Yjs document the Store is being persisted
+   * to.
+   * @returns The Yjs document.
+   * @example
+   * This example creates a Persister object against a newly-created Store and
+   * then gets the Yjs document back out again.
+   *
+   * ```js
+   * const doc = new Y.Doc();
+   * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+   * const persister = createYjsPersister(store, doc);
+   *
+   * console.log(persister.getYDoc() == doc);
+   * // -> true
+   *
+   * persister.destroy();
+   * ```
+   * @category Getter
+   * @since v4.3.14
+   */
+  getYDoc: () => YDoc;
+}
+
 /**
  * The createYjsPersister function creates a Persister object that can persist
  * the Store to a Yjs document.
@@ -27,7 +60,7 @@ import {Doc as YDoc} from 'yjs';
  *   yDoc: YDoc,
  *   yMapName?: string,
  *   onIgnoredError?: (error: any) => void,
- * ): Persister;
+ * ): YjsPersister;
  * ```
  *
  * As well as providing a reference to the Store to persist, you must provide
@@ -39,9 +72,9 @@ import {Doc as YDoc} from 'yjs';
  * @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.
+ * @returns A reference to the new YjsPersister object.
  * @example
- * This example creates a Persister object and persists the Store to a Yjs
+ * This example creates a YjsPersister object and persists the Store to a Yjs
  * document.
  *
  * ```js
@@ -59,8 +92,8 @@ import {Doc as YDoc} from 'yjs';
  * ```
  * @example
  * This more complex example uses Yjs updates to keep two Store objects (each
- * with their own Persister objects and Yjs documents) in sync with each other.
- * We use the `await` keyword extensively for the purpose of ensuring
+ * with their own YjsPersister objects and Yjs documents) in sync with each
+ * other. We use the `await` keyword extensively for the purpose of ensuring
  * sequentiality in this example.
  *
  * Typically, real-world synchronization would happen between two systems via a
@@ -117,4 +150,4 @@ export function createYjsPersister<Schemas extends OptionalSchemas>(
   yDoc: YDoc,
   yMapName?: string,
   onIgnoredError?: (error: any) => void,
-): Persister<Schemas>;
+): YjsPersister<Schemas>;

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

@@ -672,11 +672,11 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * load(initialTables?: Tables, initialValues?: Values): Promise<Persister>;
    * ```
    *
-   * The optional parameter allows you to specify what the initial Tables object
-   * for the Store will be if there is nothing currently persisted. Using this
-   * instead of the `initialTables` parameter in the regular createStore
-   * function allows you to easily instantiate a Store whether it's loading from
-   * previously persisted storage or being run for the first time.
+   * The optional parameters allow you to specify what the initial content for
+   * the Store will be if there is nothing currently persisted or if the load
+   * fails (for example when the Persister is remote and the environment is
+   * offline). This allows you to fallback or instantiate a Store whether it's
+   * loading from previously persisted storage or being run for the first time.
    *
    * This method is asynchronous because the persisted data may be on a remote
    * machine or a filesystem. Even for those storage types that are synchronous
@@ -746,11 +746,11 @@ export interface Persister<in out Schemas extends OptionalSchemas> {
    * ): Promise<Persister>;
    * ```
    *
-   * The optional parameter allows you to specify what the initial Tables object
-   * for the Store will be if there is nothing at first persisted. Using this
-   * instead of the `initialTables` parameter in the regular createStore
-   * function allows you to easily instantiate a Store whether it's loading from
-   * previously persisted storage or being run for the first time.
+   * The optional parameters allow you to specify what the initial content for
+   * the Store will be if there is nothing currently persisted or if the load
+   * fails (for example when the Persister is remote and the environment is
+   * offline). This allows you to fallback or instantiate a Store whether it's
+   * loading from previously persisted storage or being run for the first time.
    *
    * This method first runs a single call to the load method to ensure the data
    * is in sync with the persisted storage. It then continues to watch for

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

@@ -293,6 +293,9 @@ export type QueryIdsListener<Schemas extends OptionalSchemas> = (
  * object, the Id of the ResultTable that changed (which is the same as the
  * query Id), and a GetResultCellChange function that can be used to query
  * ResultCell values before and after the change.
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
@@ -328,6 +331,9 @@ export type ResultTableListener<Schemas extends OptionalSchemas> = (
  * When called, a ResultTableCellIdsListener is given a reference to the Queries
  * object, and the Id of the ResultTable whose Cell Ids changed (which is the
  * same as the query Id).
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
@@ -360,6 +366,9 @@ export type ResultTableCellIdsListener<Schemas extends OptionalSchemas> = (
  * When called, a ResultRowCountListener is given a reference to the Queries
  * object, the Id of the ResultTable whose ResultRow Ids changed (which is the
  * same as the query Id), and the count of ResultRow objects in the ResultTable.
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
@@ -393,6 +402,9 @@ export type ResultRowCountListener<Schemas extends OptionalSchemas> = (
  * When called, a ResultRowIdsListener is given a reference to the Queries
  * object, and the Id of the ResultTable whose ResultRow Ids changed (which is
  * the same as the query Id).
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
@@ -433,6 +445,9 @@ export type ResultRowIdsListener<Schemas extends OptionalSchemas> = (
  * for pagination purposes. It also receives the sorted array of Ids itself, so
  * that you can use them in the listener without the additional cost of an
  * explicit call to getResultSortedRowIds.
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
@@ -477,6 +492,9 @@ export type ResultSortedRowIdsListener<Schemas extends OptionalSchemas> = (
  * the Id of the ResultTable that changed (which is the same as the query Id),
  * the Id of the ResultRow that changed, and a GetResultCellChange function that
  * can be used to query ResultCell values before and after the change.
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
@@ -514,6 +532,9 @@ export type ResultRowListener<Schemas extends OptionalSchemas> = (
  * When called, a ResultCellIdsListener is given a reference to the Queries
  * object, the Id of the ResultTable that changed (which is the same as the
  * query Id), and the Id of the ResultRow whose ResultCell Ids changed.
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.
@@ -555,6 +576,9 @@ export type ResultCellIdsListener<Schemas extends OptionalSchemas> = (
  * It is also given the new value of the ResultCell, the old value of the
  * ResultCell, and a GetResultCellChange function that can be used to query
  * ResultCell values before and after the change.
+ *
+ * You can create new query definitions within the body of this listener, though
+ * obviously be aware of the possible cascading effects of doing so.
  * @param queries A reference to the Queries object that changed.
  * @param tableId The Id of the ResultTable that changed, which is also the
  * query Id.