tinybase 4.0.0-beta.0 → 4.0.0-beta.1

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

@@ -0,0 +1,60 @@
+/**
+ * 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';
+
+/**
+ * The createRemotePersister function creates a Persister object that can
+ * persist the Store to a remote server.
+ *
+ * As well as providing a reference to the Store to persist, you must provide
+ * `loadUrl` and `saveUrl` parameters. These identify the endpoints of the
+ * server that support the `GET` method (to fetch the Store JSON to load) and
+ * the `POST` method (to send the Store JSON to save) respectively.
+ *
+ * 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.
+ * @param autoLoadIntervalSeconds How often to poll the `loadUrl` when
+ * automatically loading changes from the server.
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a Persister object and persists the Store to a remote
+ * server.
+ *
+ * ```js yolo
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createRemotePersister(
+ *   store,
+ *   'https://example.com/load',
+ *   'https://example.com/save',
+ *   5,
+ * );
+ *
+ * await persister.save();
+ * // Store JSON will be sent to server in a POST request.
+ *
+ * await persister.load();
+ * // Store JSON will be fetched from server with a GET request.
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createRemotePersister(
+  store: Store,
+  loadUrl: string,
+  saveUrl: string,
+  autoLoadIntervalSeconds: number,
+): Persister;

package/lib/types/persisters.d.ts

@@ -3,21 +3,21 @@
  * saving and loading Store data, to and from different destinations, or
  * underlying storage types.
  *
- * Several entry points are provided, each of which returns a new Persister
- * object that can load and save a Store:
- *
- * - The createSessionPersister function returns a Persister that uses the
- *   browser's session storage.
- * - The createLocalPersister function returns a Persister that uses the
- *   browser's local storage.
- * - The createRemotePersister function returns a Persister that uses a remote
- *   server.
- * - The createFilePersister function returns a Persister that uses a local file
- *   (in an appropriate environment).
+ * Several entry points are provided (in separately installed modules), each of
+ * which returns a new Persister object that can load and save a Store:
+ *
+ * - The createSessionPersister function (in the persister-browser module)
+ *   returns a Persister that uses the browser's session storage.
+ * - The createLocalPersister function (in the persister-browser module) returns
+ *   a Persister that uses the browser's local storage.
+ * - The createRemotePersister function (in the persister-remote module) returns
+ *   a Persister that uses a remote server.
+ * - The createFilePersister function (in the persister-file module) returns a
+ *   Persister that uses a local file (in an appropriate environment).
  *
  * Since persistence requirements can be different for every app, the
- * createCustomPersister function can also be used to easily create a fully
- * customized way to save and load Store data.
+ * createCustomPersister function in this module can also be used to easily
+ * create a fully customized way to save and load Store data.
  *
  * @see Persisting Data guide
  * @see Countries demo
@@ -28,7 +28,6 @@
  */
 
 import {Store, Tables, Values} from './store.d';
-import {Callback} from './common.d';
 
 /**
  * The PersisterStats type describes the number of times a Persister object has
@@ -50,6 +49,12 @@ export type PersisterStats = {
   saves?: number;
 };
 
+/**
+ * A PersisterListener is a callback that lets a Persister inform the Store that
+ * a change has happened to the underlying data.
+ */
+export type PersisterListener = (content?: [Tables, Values]) => void;
+
 /**
  * A Persister object lets you save and load Store data to and from different
  * locations, or underlying storage types.
@@ -461,12 +466,12 @@ export interface Persister {
    * const persister = createSessionPersister(store, 'pets');
    * await persister.startAutoSave();
    *
-   * console.log(store.getListenerStats().tables);
+   * console.log(store.getListenerStats().transaction);
    * // -> 1
    *
    * persister.destroy();
    *
-   * console.log(store.getListenerStats().tables);
+   * console.log(store.getListenerStats().transaction);
    * // -> 0
    * ```
    * @category Lifecycle
@@ -520,151 +525,6 @@ export interface Persister {
   //
 }
 
-/**
- * The createSessionPersister function creates a Persister object that can
- * persist the Store to the browser's session storage.
- *
- * 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.
- * @example
- * This example creates a Persister object and persists the Store to the
- * browser's session storage.
- *
- * ```js
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createSessionPersister(store, 'pets');
- *
- * await persister.save();
- * console.log(sessionStorage.getItem('pets'));
- * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
- *
- * persister.destroy();
- * sessionStorage.clear();
- * ```
- * @category Creation
- */
-export function createSessionPersister(
-  store: Store,
-  storageName: string,
-): Persister;
-
-/**
- * The createLocalPersister function creates a Persister object that can
- * persist the Store to the browser's local storage.
- *
- * 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.
- * @example
- * This example creates a Persister object and persists the Store to the
- * browser's local storage.
- *
- * ```js
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createLocalPersister(store, 'pets');
- *
- * await persister.save();
- * console.log(localStorage.getItem('pets'));
- * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
- *
- * persister.destroy();
- * localStorage.clear();
- * ```
- * @category Creation
- */
-export function createLocalPersister(
-  store: Store,
-  storageName: string,
-): Persister;
-
-/**
- * The createRemotePersister function creates a Persister object that can
- * persist the Store to a remote server.
- *
- * As well as providing a reference to the Store to persist, you must provide
- * `loadUrl` and `saveUrl` parameters. These identify the endpoints of the
- * server that support the `GET` method (to fetch the Store JSON to load) and
- * the `POST` method (to send the Store JSON to save) respectively.
- *
- * 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.
- * @param autoLoadIntervalSeconds How often to poll the `loadUrl` when
- * automatically loading changes from the server.
- * @returns A reference to the new Persister object.
- * @example
- * This example creates a Persister object and persists the Store to a remote
- * server.
- *
- * ```js yolo
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createRemotePersister(
- *   store,
- *   'https://example.com/load',
- *   'https://example.com/save',
- *   5,
- * );
- *
- * await persister.save();
- * // Store JSON will be sent to server in a POST request.
- *
- * await persister.load();
- * // Store JSON will be fetched from server with a GET request.
- *
- * persister.destroy();
- * ```
- * @category Creation
- */
-export function createRemotePersister(
-  store: Store,
-  loadUrl: string,
-  saveUrl: string,
-  autoLoadIntervalSeconds: number,
-): Persister;
-
-/**
- * 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
- * `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.
- * @example
- * This example creates a Persister object and persists the Store to a local
- * file.
- *
- * ```js yolo
- * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
- * const persister = createFilePersister(store, '/app/persisted.json');
- *
- * await persister.save();
- * // Store JSON will be saved to the file.
- *
- * await persister.load();
- * // Store JSON will be loaded from the file.
- *
- * persister.destroy();
- * ```
- * @category Creation
- */
-export function createFilePersister(store: Store, filePath: string): Persister;
-
 /**
  * The createCustomPersister function creates a Persister object that you can
  * configure to persist the Store in any way you wish.
@@ -678,18 +538,25 @@ export function createFilePersister(store: Store, filePath: string): Persister;
  * covers. See those implementations for ideas on how to implement your own
  * Persister types.
  *
+ * This API changed in v4.0.0. Any custom persisters created on previous
+ * versions should be upgraded. Most notably, the `setPersisted` function
+ * parameter is provided with a `getContent` function to get the content from
+ * the Store itself, rather than being passed pre-serialized JSON.
+ * `addPersisterListener` has been renamed `addPersisterListener`, and
+ * `addPersisterListener` has been renamed `delPersisterListener`.
+ *
  * @param store The Store to persist.
- * @param getPersisted An asynchronous function which will fetch JSON from the
- * persistence layer (or `null` or `undefined` if not present).
- * @param setPersisted An asynchronous function which will send JSON to the
+ * @param getPersisted An asynchronous function which will fetch content from
+ * the persistence layer (or `null` or `undefined` if not present).
+ * @param setPersisted An asynchronous function which will send content to the
  * persistence layer.
- * @param startListeningToPersisted A function that will register a `didChange`
+ * @param addPersisterListener A function that will register a `listener`
  * listener on underlying changes to the persistence layer. You can return a
- * listening handle that will be provided again when `stopListeningToPersisted`
+ * listening handle that will be provided again when `delPersisterListener`
  * is called.
- * @param stopListeningToPersisted A function that will unregister the listener
+ * @param delPersisterListener A function that will unregister the listener
  * from the underlying changes to the persistence layer. It receives whatever
- * was returned from your `startListeningToPersisted` implementation.
+ * was returned from your `addPersisterListener` implementation.
  * @returns A reference to the new Persister object.
  * @example
  * This example creates a custom Persister object and persists the Store to a
@@ -703,8 +570,8 @@ export function createFilePersister(store: Store, filePath: string): Persister;
  * const persister = createCustomPersister(
  *   store,
  *   async () => storeJson,
- *   async (json) => (storeJson = json),
- *   (didChange) => setInterval(didChange, 1000),
+ *   async (getContent) => (storeJson = JSON.stringify(getContent())),
+ *   (listener) => setInterval(listener, 1000),
  *   (interval) => clearInterval(interval),
  * );
  *
@@ -725,7 +592,7 @@ export function createFilePersister(store: Store, filePath: string): Persister;
 export function createCustomPersister<ListeningHandle>(
   store: Store,
   getPersisted: () => Promise<string | null | undefined>,
-  setPersisted: (json: string) => Promise<void>,
-  startListeningToPersisted: (didChange: Callback) => ListeningHandle,
-  stopListeningToPersisted: (listeningHandle: ListeningHandle) => void,
+  setPersisted: (getContent: () => [Tables, Values]) => Promise<void>,
+  addPersisterListener: (listener: PersisterListener) => ListeningHandle,
+  delPersisterListener: (listeningHandle: ListeningHandle) => void,
 ): Persister;

package/lib/types/store.d.ts

@@ -451,17 +451,30 @@ export type DoRollback = (
  * of `cellsTouched` and `valuesTouched` in the listener will be `false` because
  * all changes have been reverted.
  *
+ * Since v4.0, the listener also receives the list of (valid and invalid) Cell
+ * and Value changes made during the transaction.
+ *
  * @param store A reference to the Store that is completing a transaction.
  * @param cellsTouched Whether Cell values have been touched during the
  * transaction.
  * @param valuesTouched Whether Values have been touched during the transaction,
  * since v3.0.0.
+ * @param changedCells Any Cells that were changed during the transaction, since
+ * v4.0.0.
+ * @param invalidCells Any invalid attempts to change Cells, since v4.0.0.
+ * @param changedValues Any Values that were changed during the transaction,
+ * since v4.0.0.
+ * @param invalidValues Any invalid attempts to change Values, since v4.0.0.
  * @category Listener
  */
 export type TransactionListener = (
   store: Store,
   cellsTouched: boolean,
   valuesTouched: boolean,
+  changedCells: ChangedCells,
+  invalidCells: InvalidCells,
+  changedValues: ChangedValues,
+  invalidValues: InvalidValues,
 ) => void;
 
 /**
@@ -1221,16 +1234,49 @@ export type StoreListenerStats = {
 export interface Store {
   //
   /**
-   * The getTables method returns a Tables object containing the entire data of
-   * the Store.
+   * The getContent method returns a Tables object and a Values object in an
+   * array, representing the entire content of the Store.
+   *
+   * Note that this returns a copy of, rather than a reference to the underlying
+   * data, so changes made to the returned objects are not made to the Store
+   * itself.
+   *
+   * @returns An array of a Tables object and a Values object.
+   * @example
+   * This example retrieves the content of a Store.
+   *
+   * ```js
+   * const store = createStore()
+   *   .setTables({pets: {fido: {species: 'dog'}}})
+   *   .setValues({open: true, employees: 3});
+   * console.log(store.getContent());
+   * // -> [{pets: {fido: {species: 'dog'}}}, {open: true, employees: 3}]
+   * ```
+   * @example
+   * This example retrieves the Tables and Values of an empty Store, returning
+   * empty objects.
+   *
+   * ```js
+   * const store = createStore();
+   * console.log(store.getContent());
+   * // -> [{}, {}]
+   * ```
+   * @category Getter
+   * @since v4.0.0
+   */
+  getContent(): [Tables, Values];
+
+  /**
+   * The getTables method returns a Tables object containing the entire tabular
+   * data of the Store.
    *
    * Note that this returns a copy of, rather than a reference to the underlying
    * data, so changes made to the returned object are not made to the Store
    * itself.
    *
-   * @returns A Tables object containing the entire data of the Store.
+   * @returns A Tables object containing the tabular data of the Store.
    * @example
-   * This example retrieves the data in a Store.
+   * This example retrieves the tabular data in a Store.
    *
    * ```js
    * const store = createStore().setTables({
@@ -1569,9 +1615,9 @@ export interface Store {
    * data, so changes made to the returned object are not made to the Store
    * itself.
    *
-   * @returns An object containing the entire data of the Values.
+   * @returns An object containing the set of keyed Values in the Store.
    * @example
-   * This example retrieves the keyed Values data in a Store.
+   * This example retrieves the set of keyed Values in the Store.
    *
    * ```js
    * const store = createStore().setValues({open: true, employees: 3});
@@ -1579,7 +1625,7 @@ export interface Store {
    * // -> {open: true, employees: 3}
    * ```
    * @example
-   * This example retrieves a Values from a Store that has none, returning an
+   * This example retrieves Values from a Store that has none, returning an
    * empty object.
    *
    * ```js
@@ -1964,7 +2010,67 @@ export interface Store {
   getSchemaJson(): Json;
 
   /**
-   * The setTables method takes an object and sets the entire data of the Store.
+   * The setContent method takes an object and sets the entire data of the
+   * Store.
+   *
+   * This method will cause listeners to be called for any Table, Row, Cell,
+   * Value, or Id changes resulting from it.
+   *
+   * Any part of the provided objects that are invalid (either according to the
+   * Tables or Values type, or because it does not match a TablesSchema or
+   * ValuesSchema associated with the Store), will be ignored silently.
+   *
+   * Assuming that at least some of the provided Tables object or Values object
+   * is valid, any data that was already present in that part of the Store will
+   * be completely overwritten. If either object is completely invalid, no
+   * change will be made to the corresponding part of the Store.
+   *
+   * The method returns a reference to the Store so that subsequent operations
+   * can be chained in a fluent style.
+   *
+   * @param content An array containing the tabular and keyed-value data of the
+   * Store to be set.
+   * @example
+   * This example sets the data of a Store.
+   *
+   * ```js
+   * const store = createStore().setContent([
+   *   {pets: {fido: {species: 'dog'}}},
+   *   {open: true, employees: 3},
+   * ]);
+   * console.log(store.getTables());
+   * // -> {pets: {fido: {species: 'dog'}}}
+   * console.log(store.getValues());
+   * // -> {open: true, employees: 3}
+   * ```
+   * @example
+   * This example attempts to set the data of an existing Store with partly
+   * invalid, and then completely invalid objects.
+   *
+   * ```js
+   * const store = createStore().setContent([
+   *   {pets: {fido: {species: 'dog'}}},
+   *   {open: true, employees: 3},
+   * ]);
+   *
+   * store.setContent([{pets: {felix: {species: 'cat', bug: []}}}, '']);
+   * console.log(store.getTables());
+   * // -> {pets: {felix: {species: 'cat'}}}
+   * console.log(store.getValues());
+   * // -> {open: true, employees: 3}
+   *
+   * store.setContent([{meaning: 42}]);
+   * console.log(store.getTables());
+   * // -> {pets: {felix: {species: 'cat'}}}
+   * ```
+   * @category Setter
+   * @since 4.0.0
+   */
+  setContent([tables, values]: [Tables, Values]): Store;
+
+  /**
+   * The setTables method takes an object and sets the entire tabular data of
+   * the Store.
    *
    * This method will cause listeners to be called for any Table, Row, Cell, or
    * Id changes resulting from it.
@@ -1982,7 +2088,7 @@ export interface Store {
    *
    * @param tables The data of the Store to be set.
    * @example
-   * This example sets the data of a Store.
+   * This example sets the tabular data of a Store.
    *
    * ```js
    * const store = createStore().setTables({
@@ -1993,8 +2099,8 @@ export interface Store {
    * // -> {pets: {fido: {species: 'dog'}}, species: {dog: {price: 5}}}
    * ```
    * @example
-   * This example attempts to set the data of an existing Store with partly
-   * invalid, and then completely invalid, Tables objects.
+   * This example attempts to set the tabular data of an existing Store with
+   * partly invalid, and then completely invalid, Tables objects.
    *
    * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});

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

@@ -0,0 +1,103 @@
+/**
+ * The persister-browser module of the TinyBase project lets you save and load
+ * Store data to and from browser storage.
+ *
+ * Two entry points are provided, each of which returns a new Persister object
+ * that can load and save a Store:
+ *
+ * - The createSessionPersister function returns a Persister that uses the
+ *   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 {OptionalSchemas, Store} from './store';
+import {Persister} from './persisters';
+
+/**
+ * The createSessionPersister function creates a Persister object that can
+ * persist the Store to the browser's session storage.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createSessionPersister(
+ *   store: Store,
+ *   storageName: string,
+ * ): Persister;
+ * ```
+ *
+ * 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.
+ * @example
+ * This example creates a Persister object and persists the Store to the
+ * browser's session storage.
+ *
+ * ```js
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createSessionPersister(store, 'pets');
+ *
+ * await persister.save();
+ * console.log(sessionStorage.getItem('pets'));
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ *
+ * persister.destroy();
+ * sessionStorage.clear();
+ * ```
+ * @category Creation
+ */
+export function createSessionPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  storageName: string,
+): Persister<Schemas>;
+
+/**
+ * The createLocalPersister function creates a Persister object that can
+ * persist the Store to the browser's local storage.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createLocalPersister(
+ *   store: Store,
+ *   storageName: string,
+ * ): Persister;
+ * ```
+ *
+ * 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.
+ * @example
+ * This example creates a Persister object and persists the Store to the
+ * browser's local storage.
+ *
+ * ```js
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createLocalPersister(store, 'pets');
+ *
+ * await persister.save();
+ * console.log(localStorage.getItem('pets'));
+ * // -> '[{"pets":{"fido":{"species":"dog"}}},{}]'
+ *
+ * persister.destroy();
+ * localStorage.clear();
+ * ```
+ * @category Creation
+ */
+export function createLocalPersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  storageName: string,
+): Persister<Schemas>;

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

@@ -0,0 +1,50 @@
+/**
+ * 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 {OptionalSchemas, Store} from './store';
+import {Persister} from './persisters';
+
+/**
+ * The createFilePersister function creates a Persister object that can persist
+ * the Store to a local file (in an appropriate environment).
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * createFilePersister(store: Store, filePath: string): Persister;
+ * ```
+ *
+ * As well as providing a reference to the Store to persist, you must provide
+ * `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.
+ * @example
+ * This example creates a Persister object and persists the Store to a local
+ * file.
+ *
+ * ```js yolo
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const persister = createFilePersister(store, '/app/persisted.json');
+ *
+ * await persister.save();
+ * // Store JSON will be saved to the file.
+ *
+ * await persister.load();
+ * // Store JSON will be loaded from the file.
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
+export function createFilePersister<Schemas extends OptionalSchemas>(
+  store: Store<Schemas>,
+  filePath: string,
+): Persister<Schemas>;