tinybase 4.0.0-beta.4 → 4.0.0-beta.5.1

package/lib/types/indexes.d.ts

@@ -6,7 +6,6 @@
  * returns a new Indexes object. From there, you can create new Index
  * definitions, access the contents of those Indexes directly, and register
  * listeners for when they change.
- *
  * @packageDocumentation
  * @module indexes
  */
@@ -24,7 +23,6 @@ import {Id, IdOrNull, Ids, SortKey} from './common.d';
  * Note that the Index type is not actually used in the API, and you instead
  * enumerate and access its structure with the getSliceIds method and
  * getSliceRowIds method.
- *
  * @category Concept
  */
 export type Index = {[sliceId: Id]: Slice};
@@ -38,7 +36,6 @@ export type Index = {[sliceId: Id]: Slice};
  *
  * Note that the Slice type is not actually used in the API, and you instead get
  * Row Ids directly with the getSliceRowIds method.
- *
  * @category Concept
  */
 export type Slice = Ids;
@@ -50,7 +47,6 @@ export type Slice = Ids;
  * A IndexCallback is provided when using the forEachIndex method, so that you
  * can do something based on every Index in the Indexes object. See that method
  * for specific examples.
- *
  * @param indexId The Id of the Index that the callback can operate on.
  * @param forEachRow A function that will let you iterate over the Slice objects
  * in this Index.
@@ -68,7 +64,6 @@ export type IndexCallback = (
  * A SliceCallback is provided when using the forEachSlice method, so that you
  * can do something based on every Slice in an Index. See that method for
  * specific examples.
- *
  * @param sliceId The Id of the Slice that the callback can operate on.
  * @param forEachRow A function that will let you iterate over the Row objects
  * in this Slice.
@@ -88,7 +83,6 @@ export type SliceCallback = (
  *
  * When called, a SliceIdsListener is given a reference to the Indexes object,
  * and the Id of the Index that changed.
- *
  * @param indexes A reference to the Indexes object that changed.
  * @param indexId The Id of the Index that changed.
  * @category Listener
@@ -105,7 +99,6 @@ export type SliceIdsListener = (indexes: Indexes, indexId: Id) => void;
  * When called, a SliceRowIdsListener is given a reference to the Indexes
  * object, the Id of the Index that changed, and the Id of the Slice whose Row
  * Ids changed.
- *
  * @param indexes A reference to the Indexes object that changed.
  * @param indexId The Id of the Index that changed.
  * @param sliceId The Id of the Slice that changed.
@@ -123,7 +116,6 @@ export type SliceRowIdsListener = (
  *
  * A IndexesListenerStats object is returned from the getListenerStats method,
  * and is only populated in a debug build.
- *
  * @category Development
  */
 export type IndexesListenerStats = {
@@ -154,7 +146,6 @@ export type IndexesListenerStats = {
  *
  * This module defaults to indexing Row objects by one of their Cell values.
  * However, far more complex indexes can be configured with a custom function.
- *
  * @example
  * This example shows a very simple lifecycle of an Indexes object: from
  * creation, to adding a definition, getting its contents, and then registering
@@ -241,7 +232,6 @@ export interface Indexes {
    * Slice Id parameter, in case you want to sort Row Ids differently in each
    * Slice. You can use the convenient defaultSorter function to default this to
    * be alphanumeric.
-   *
    * @param indexId The Id of the Index to define.
    * @param tableId The Id of the Table the Index will be generated from.
    * @param getSliceIdOrIds Either the Id of the Cell containing, or a function
@@ -360,7 +350,6 @@ export interface Indexes {
 
   /**
    * The delIndexDefinition method removes an existing Index definition.
-   *
    * @param indexId The Id of the Index to remove.
    * @returns A reference to the Indexes object.
    * @example
@@ -390,7 +379,6 @@ export interface Indexes {
   /**
    * The getStore method returns a reference to the underlying Store that is
    * backing this Indexes object.
-   *
    * @returns A reference to the Store.
    * @example
    * This example creates an Indexes object against a newly-created Store and
@@ -410,7 +398,6 @@ export interface Indexes {
   /**
    * The getIndexIds method returns an array of the Index Ids registered with
    * this Indexes object.
-   *
    * @returns An array of Ids.
    * @example
    * This example creates an Indexes object with two definitions, and then gets
@@ -437,7 +424,6 @@ export interface Indexes {
    * IndexCallback function that will be called with the Id of each Index, and
    * with a function that can then be used to iterate over each Slice of the
    * Index, should you wish.
-   *
    * @param indexCallback The function that should be called for every Index.
    * @example
    * This example iterates over each Index in an Indexes object, and lists each
@@ -476,7 +462,6 @@ export interface Indexes {
    * in a functional style. The `rowCallback` parameter is a RowCallback
    * function that will be called with the Id and value of each Row in the
    * Slice.
-   *
    * @param indexId The Id of the Index to iterate over.
    * @param sliceCallback The function that should be called for every Slice.
    * @example
@@ -508,7 +493,6 @@ export interface Indexes {
   /**
    * The hasIndex method returns a boolean indicating whether a given Index
    * exists in the Indexes object.
-   *
    * @param indexId The Id of a possible Index in the Indexes object.
    * @returns Whether an Index with that Id exists.
    * @example
@@ -529,7 +513,6 @@ export interface Indexes {
   /**
    * The hasSlice method returns a boolean indicating whether a given Slice
    * exists in the Indexes object.
-   *
    * @param indexId The Id of a possible Index in the Indexes object.
    * @param sliceId The Id of a possible Slice in the Index.
    * @returns Whether a Slice with that Id exists.
@@ -558,7 +541,6 @@ export interface Indexes {
    * backing an Index.
    *
    * If the Index Id is invalid, the method returns `undefined`.
-   *
    * @param indexId The Id of an Index.
    * @returns The Id of the Table backing the Index, or `undefined`.
    * @example
@@ -583,7 +565,6 @@ export interface Indexes {
    *
    * If the identified Index does not exist (or if the definition references a
    * Table that does not exist) then an empty array is returned.
-   *
    * @param indexId The Id of the Index.
    * @returns The Slice Ids in the Index, or an empty array.
    * @example
@@ -616,7 +597,6 @@ export interface Indexes {
    *
    * If the identified Index or Slice do not exist (or if the definition
    * references a Table that does not exist) then an empty array is returned.
-   *
    * @param indexId The Id of the Index.
    * @param sliceId The Id of the Slice in the Index.
    * @returns The Row Ids in the Slice, or an empty array.
@@ -658,7 +638,6 @@ export interface Indexes {
    * The provided listener is a SliceIdsListener function, and will be called
    * with a reference to the Indexes object, and the Id of the Index that
    * changed.
-   *
    * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Slice Ids in
    * the Index change.
@@ -742,7 +721,6 @@ export interface Indexes {
    * The provided listener is a SliceRowIdsListener function, and will be called
    * with a reference to the Indexes object, the Id of the Index, and the Id of
    * the Slice that changed.
-   *
    * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
    * @param sliceId The Id of the Slice to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Row Ids in
@@ -826,7 +804,6 @@ export interface Indexes {
    * Use the Id returned by whichever method was used to add the listener. Note
    * that the Indexes object may re-use this Id for future listeners added to
    * it.
-   *
    * @param listenerId The Id of the listener to remove.
    * @returns A reference to the Indexes object.
    * @example
@@ -869,7 +846,6 @@ export interface Indexes {
    *
    * This guarantees that all of the listeners that the object registered with
    * the underlying Store are removed and it can be correctly garbage collected.
-   *
    * @example
    * This example creates a Store, adds an Indexes object with a
    * definition (that registers a RowListener with the underlying Store),
@@ -908,7 +884,6 @@ export interface Indexes {
    * return an empty object. The method is intended to be used during
    * development to ensure your application is not leaking listener
    * registrations, for example.
-   *
    * @returns A IndexesListenerStats object containing Indexes listener
    * statistics.
    * @example
@@ -940,7 +915,6 @@ export interface Indexes {
  * A given Store can only have one Indexes object associated with it. If you
  * call this function twice on the same Store, your second call will return a
  * reference to the Indexes object created by the first.
- *
  * @param store The Store for which to register Index definitions.
  * @returns A reference to the new Indexes object.
  * @example

package/lib/types/metrics.d.ts

@@ -6,7 +6,6 @@
  * returns a new Metrics object. From there, you can create new Metric
  * definitions, access the values of those Metrics directly, and register
  * listeners for when they change.
- *
  * @packageDocumentation
  * @module metrics
  */
@@ -17,7 +16,6 @@ import {Id, IdOrNull, Ids} from './common.d';
 /**
  * The Metric type is simply an alias, but represents a number formed by
  * aggregating multiple other numbers together.
- *
  * @category Metric
  */
 export type Metric = number;
@@ -29,7 +27,6 @@ export type Metric = number;
  * A MetricCallback is provided when using the forEachMetric method, so that you
  * can do something based on every Metric in the Metrics object. See that method
  * for specific examples.
- *
  * @param metricId The Id of the Metric that the callback can operate on.
  * @param metric The value of the Metric.
  * @category Callback
@@ -44,7 +41,6 @@ export type MetricCallback = (metricId: Id, metric?: Metric) => void;
  * summing, and averaging values. This type is instead used for when you wish to
  * use a more complex aggregation of your own devising. See the
  * setMetricDefinition method for more examples.
- *
  * @param numbers The array of numbers in the Metric's aggregation.
  * @param length The length of the array of numbers in the Metric's aggregation.
  * @returns The value of the Metric.
@@ -69,7 +65,6 @@ export type MetricAggregate = (numbers: number[], length: number) => Metric;
  * implementation of an MetricAggregateAdd function that can reduce the
  * complexity cost of growing the input data set. See the setMetricDefinition
  * method for more examples.
- *
  * @param metric The current value of the Metric.
  * @param add The number being added to the Metric's aggregation.
  * @param length The length of the array of numbers in the Metric's aggregation.
@@ -102,7 +97,6 @@ export type MetricAggregateAdd = (
  * implementation of an MetricAggregateRemove function that can reduce the
  * complexity cost of shrinking the input data set. See the setMetricDefinition
  * method for more examples.
- *
  * @param metric The current value of the Metric.
  * @param remove The number being removed from the Metric's aggregation.
  * @param length The length of the array of numbers in the Metric's aggregation.
@@ -132,7 +126,6 @@ export type MetricAggregateRemove = (
  * implementation of an MetricAggregateReplace function that can reduce the
  * complexity cost of changing the input data set in place. See the
  * setMetricDefinition method for more examples.
- *
  * @param metric The current value of the Metric.
  * @param add The number being added to the Metric's aggregation.
  * @param remove The number being removed from the Metric's aggregation.
@@ -160,7 +153,6 @@ export type MetricAggregateReplace = (
  * If this is the first time that a Metric has had a value (such as when a table
  * has gained its first row), the old value will be `undefined`. If a Metric now
  * no longer has a value, the new value will be `undefined`.
- *
  * @param metrics A reference to the Metrics object that changed.
  * @param metricId The Id of the Metric that changed.
  * @param newMetric The new value of the Metric that changed.
@@ -180,7 +172,6 @@ export type MetricListener = (
  *
  * A MetricsListenerStats object is returned from the getListenerStats method,
  * and is only populated in a debug build.
- *
  * @category Development
  */
 export type MetricsListenerStats = {
@@ -206,7 +197,6 @@ export type MetricsListenerStats = {
  * ('sum', 'avg', 'min', and 'max'), and defaults to counting Row objects when
  * using the setMetricDefinition method. However, far more complex aggregations
  * can be configured with custom functions.
- *
  * @example
  * This example shows a very simple lifecycle of a Metrics object: from
  * creation, to adding a definition, getting a Metric, and then registering and
@@ -274,7 +264,6 @@ export interface Metrics {
    * function's algorithmic complexity by providing shortcuts that can nudge an
    * aggregation result when a single value is added, removed, or replaced in
    * the input values.
-   *
    * @param metricId The Id of the Metric to define.
    * @param tableId The Id of the Table the Metric will be calculated from.
    * @param aggregate Either a string representing one of a set of common
@@ -424,7 +413,6 @@ export interface Metrics {
 
   /**
    * The delMetricDefinition method removes an existing Metric definition.
-   *
    * @param metricId The Id of the Metric to remove.
    * @returns A reference to the Metrics object.
    * @example
@@ -454,7 +442,6 @@ export interface Metrics {
   /**
    * The getStore method returns a reference to the underlying Store that is
    * backing this Metrics object.
-   *
    * @returns A reference to the Store.
    * @example
    * This example creates a Metrics object against a newly-created Store and
@@ -474,7 +461,6 @@ export interface Metrics {
   /**
    * The getMetricIds method returns an array of the Metric Ids registered with
    * this Metrics object.
-   *
    * @returns An array of Ids.
    * @example
    * This example creates a Metrics object with two definitions, and then gets
@@ -499,7 +485,6 @@ export interface Metrics {
    * This method is useful for iterating over all the Metrics in a functional
    * style. The `metricCallback` parameter is a MetricCallback function that
    * will be called with the Id of each Metric and its value.
-   *
    * @param metricCallback The function that should be called for every Metric.
    * @example
    * This example iterates over each Metric in a Metrics object.
@@ -527,7 +512,6 @@ export interface Metrics {
   /**
    * The hasMetric method returns a boolean indicating whether a given Metric
    * exists in the Metrics object, and has a value.
-   *
    * @param metricId The Id of a possible Metric in the Metrics object.
    * @returns Whether a Metric with that Id exists.
    * @example
@@ -555,7 +539,6 @@ export interface Metrics {
    * backing a Metric.
    *
    * If the Metric Id is invalid, the method returns `undefined`.
-   *
    * @param metricId The Id of a Metric.
    * @returns The Id of the Table backing the Metric, or `undefined`.
    * @example
@@ -580,7 +563,6 @@ export interface Metrics {
    *
    * If the identified Metric does not exist (or if the definition references a
    * Table or Cell value that does not exist) then `undefined` is returned.
-   *
    * @param metricId The Id of the Metric.
    * @returns The numeric value of the Metric, or `undefined`.
    * @example
@@ -620,7 +602,6 @@ export interface Metrics {
    * The provided listener is a MetricListener function, and will be called with
    * a reference to the Metrics object, the Id of the Metric that changed, the
    * new Metric value, and the old Metric value.
-   *
    * @param metricId The Id of the Metric to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Metric
    * changes.
@@ -694,7 +675,6 @@ export interface Metrics {
    *
    * Use the Id returned by the addMetricListener method. Note that the Metrics
    * object may re-use this Id for future listeners added to it.
-   *
    * @param listenerId The Id of the listener to remove.
    * @returns A reference to the Metrics object.
    * @example
@@ -737,7 +717,6 @@ export interface Metrics {
    *
    * This guarantees that all of the listeners that the object registered with
    * the underlying Store are removed and it can be correctly garbage collected.
-   *
    * @example
    * This example creates a Store, adds a Metrics object with a definition (that
    * registers a RowListener with the underlying Store), and then destroys it
@@ -773,7 +752,6 @@ export interface Metrics {
    * return an empty object. The method is intended to be used during
    * development to ensure your application is not leaking listener
    * registrations, for example.
-   *
    * @returns A MetricsListenerStats object containing Metrics listener
    * statistics.
    * @example
@@ -800,7 +778,6 @@ export interface Metrics {
  * A given Store can only have one Metrics object associated with it. If you
  * call this function twice on the same Store, your second call will return a
  * reference to the Metrics object created by the first.
- *
  * @param store The Store for which to register Metric definitions.
  * @returns A reference to the new Metrics object.
  * @example

package/lib/types/{persister-automerge.d.ts → persisters/persister-automerge.d.ts}

@@ -5,16 +5,15 @@
  * A single entry point, the createAutomergePersister function, is provided,
  * which returns a new Persister object that can bind a Store to a provided
  * Automerge document handle (and in turn, its document).
- *
  * @see Synchronizing Data guide
  * @packageDocumentation
  * @module persister-automerge
- * @since v4.0
+ * @since v4.0.0
  */
 
 import {DocHandle} from 'automerge-repo';
-import {Persister} from './persisters';
-import {Store} from './store';
+import {Persister} from '../persisters';
+import {Store} from '../store';
 
 /**
  * The createAutomergePersister function creates a Persister object that can
@@ -22,7 +21,6 @@ import {Store} from './store';
  *
  * As well as providing a reference to the Store to persist, you must provide
  * the Automerge document handler to persist it with.
- *
  * @param store The Store to persist.
  * @param docHandle The Automerge document handler to persist the Store with.
  * @param docMapName The name of the map used inside the Automerge document to
@@ -101,7 +99,7 @@ import {Store} from './store';
  * persister2.destroy();
  * ```
  * @category Creation
- * @since v4.0
+ * @since v4.0.0
  */
 export function createAutomergePersister(
   store: Store,

package/lib/types/{persister-browser.d.ts → persisters/persister-browser.d.ts}

@@ -9,14 +9,13 @@
  *   browser's session storage.
  * - The createLocalPersister function returns a Persister that uses the
  *   browser's local storage.
- *
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-browser
  */
 
-import {Persister} from './persisters';
-import {Store} from './store';
+import {Persister} from '../persisters';
+import {Store} from '../store';
 
 /**
  * The createSessionPersister function creates a Persister object that can
@@ -25,7 +24,6 @@ import {Store} from './store';
  * As well as providing a reference to the Store to persist, you must provide a
  * `storageName` parameter which is unique to your application. This is the key
  * 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.
  * @returns A reference to the new Persister object.
@@ -58,7 +56,6 @@ export function createSessionPersister(
  * As well as providing a reference to the Store to persist, you must provide a
  * `storageName` parameter which is unique to your application. This is the key
  * 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.
  * @returns A reference to the new Persister object.

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

@@ -0,0 +1,95 @@
+/**
+ * The persister-cr-sqlite-wasm module of the TinyBase project lets you save and
+ * load Store data to and from a local CR-SQLite database (in an appropriate
+ * environment).
+ * @see Persisting Data guide
+ * @packageDocumentation
+ * @module persister-cr-sqlite-wasm
+ */
+
+import {DatabasePersisterConfig, Persister} from '../persisters';
+import {DB} from '@vlcn.io/crsqlite-wasm';
+import {Store} from '../store';
+
+/**
+ * The createCrSqliteWasmPersister function creates a Persister object that can
+ * 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.
+ *
+ * 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 `crSqlite3.open(...)`.
+ * @param configOrStoreTableName A DatabasePersisterConfig to configure the
+ * persistence mode (or a string to set the `storeTableName` property of the
+ * JSON serialization).
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * CR-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
+ * const crSqlite3 = await initWasm();
+ * const db = await crSqlite3.open();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createCrSqliteWasmPersister(store, db, 'my_tinybase');
+ *
+ * await persister.save();
+ * console.log(await db.execO('SELECT * FROM my_tinybase;'));
+ * // -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]
+ *
+ * await db.exec(
+ *   'UPDATE my_tinybase SET store = ' +
+ *     `'[{"pets":{"felix":{"species":"cat"}}},{}]' WHERE _id = '_';`,
+ * );
+ * 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
+ * const crSqlite3 = await initWasm();
+ * const db = await crSqlite3.open();
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createCrSqliteWasmPersister(store, db, {
+ *   mode: 'tabular',
+ *   tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
+ * });
+ *
+ * await persister.save();
+ * console.log(await db.execO('SELECT * FROM pets;'));
+ * // -> [{_id: 'fido', species: 'dog'}]
+ *
+ * await db.exec(`INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`);
+ * await persister.load();
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createCrSqliteWasmPersister(
+  store: Store,
+  db: DB,
+  configOrStoreTableName?: DatabasePersisterConfig | string,
+): Persister;

package/lib/types/{persister-file.d.ts → persisters/persister-file.d.ts}

@@ -1,22 +1,20 @@
 /**
  * The persister-file module of the TinyBase project lets you save and load
  * Store data to and from a local file system (in an appropriate environment).
- *
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-file
  */
 
-import {Persister} from './persisters';
-import {Store} from './store';
+import {Persister} from '../persisters';
+import {Store} from '../store';
 
 /**
  * The createFilePersister function creates a Persister object that can persist
  * the Store to a local file (in an appropriate environment).
  *
- * As well as providing a reference to the Store to persist, you must provide
+ * 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.
  * @returns A reference to the new Persister object.

package/lib/types/{persister-remote.d.ts → persisters/persister-remote.d.ts}

@@ -1,14 +1,13 @@
 /**
  * The persister-remote module of the TinyBase project lets you save and load
  * Store data to and from a remote server.
- *
  * @see Persisting Data guide
  * @packageDocumentation
  * @module persister-remote
  */
 
-import {Persister} from './persisters';
-import {Store} from './store';
+import {Persister} from '../persisters';
+import {Store} from '../store';
 
 /**
  * The createRemotePersister function creates a Persister object that can
@@ -22,7 +21,6 @@ import {Store} from './store';
  * For when you choose to enable automatic loading for the Persister (with the
  * startAutoLoad method), it will poll the loadUrl for changes. The
  * `autoLoadIntervalSeconds` method is used to indicate how often to do this.
- *
  * @param store The Store to persist.
  * @param loadUrl The endpoint that supports a `GET` method to load JSON.
  * @param saveUrl The endpoint that supports a `POST` method to save JSON.