tinybase 0.9.2 → 1.0.1

package/lib/persisters.d.ts

@@ -1,6 +1,6 @@
 /**
- * The persisters module of the TinyBase project provides a simple framework
- * for saving and loading Store data, to and from different destinations, or
+ * The persisters module of the TinyBase project provides a simple framework for
+ * 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
@@ -11,20 +11,24 @@
  * - The createLocalPersister function returns a Persister that uses the
  *   browser's local storage.
  * - The createRemotePersister function returns a Persister that uses a remote
- *   endpoint
+ *   server.
  * - The createFilePersister function returns a Persister that uses a local file
- *   (in an appropriate environment)
+ *   (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.
  *
+ * @see Persisting Data guide
+ * @see Countries demo
+ * @see Todo App demos
+ * @see TinyDraw demo
  * @packageDocumentation
  * @module persisters
  */
 
 import {Store, Tables} from './store.d';
-import {Callback} from './common';
+import {Callback} from './common.d';
 
 /**
  * The PersisterStats type describes the number of times a Persister object has
@@ -89,7 +93,7 @@ export type PersisterStats = {
  * a JSON string, changes the persisted data, updates the Store from it, and
  * finally destroys the Persister again.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
  * const persister = createSessionPersister(store, 'pets');
  *
@@ -110,7 +114,7 @@ export type PersisterStats = {
  * browser's session storage as a JSON string. Changes to the Store data, or the
  * persisted data (implicitly firing a StorageEvent), are reflected accordingly.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const persister = createSessionPersister(store, 'pets');
  *
@@ -133,6 +137,7 @@ export type PersisterStats = {
  * persister.destroy();
  * sessionStorage.clear();
  * ```
+ * @category Persister
  */
 export interface Persister {
   /**
@@ -158,7 +163,7 @@ export interface Persister {
    * browser's session storage, which for the purposes of this example has been
    * previously populated.
    *
-   * ```tsx
+   * ```js
    * sessionStorage.setItem('pets', '{"pets":{"fido":{"species":"dog"}}}');
    *
    * const store = createStore();
@@ -176,7 +181,7 @@ export interface Persister {
    * parameter is used. The second time the load method is called, data has
    * previously been persisted and instead, that is loaded.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const persister = createSessionPersister(store, 'pets');
    *
@@ -226,7 +231,7 @@ export interface Persister {
    * reflected in the Store (in this case through detection of StorageEvents
    * from session storage changes made in another browser tab).
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const persister = createSessionPersister(store, 'pets');
    *
@@ -242,6 +247,7 @@ export interface Persister {
    * console.log(store.getTables());
    * // -> {pets: {toto: {species: 'dog'}}}
    *
+   * persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Load
@@ -261,7 +267,7 @@ export interface Persister {
    * into it from the browser's session storage. Once the automatic loading is
    * stopped, subsequent changes are not reflected in the Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const persister = createSessionPersister(store, 'pets');
    * await persister.startAutoLoad();
@@ -283,6 +289,7 @@ export interface Persister {
    * // -> {pets: {toto: {species: 'dog'}}}
    * // Storage change has not been automatically loaded.
    *
+   * persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Load
@@ -303,7 +310,7 @@ export interface Persister {
    * This example creates a Store with some data, and saves into the browser's
    * session storage.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const persister = createSessionPersister(store, 'pets');
    *
@@ -314,6 +321,7 @@ export interface Persister {
    * persister.destroy();
    * sessionStorage.clear();
    * ```
+   * @category Save
    */
   save(): Promise<Persister>;
 
@@ -336,7 +344,7 @@ export interface Persister {
    * session storage. Subsequent changes to the Store are then automatically
    * saved to the underlying storage.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const persister = createSessionPersister(store, 'pets');
    *
@@ -351,6 +359,7 @@ export interface Persister {
    *
    * sessionStorage.clear();
    * ```
+   * @category Save
    */
   startAutoSave(): Promise<Persister>;
 
@@ -368,7 +377,7 @@ export interface Persister {
    * saved to the underlying storage. Once the automatic saving is
    * stopped, subsequent changes are not reflected.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const persister = createSessionPersister(store, 'pets');
    * await persister.startAutoSave();
@@ -401,7 +410,7 @@ export interface Persister {
    * This example creates a Persister object against a newly-created Store and
    * then gets its reference in order to update its data.
    *
-   * ```tsx
+   * ```js
    * const persister = createSessionPersister(createStore(), 'pets');
    * await persister.startAutoSave();
    *
@@ -430,7 +439,7 @@ export interface Persister {
    * registers a TablesListener with the underlying Store), and then destroys it
    * again, removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const persister = createSessionPersister(store, 'pets');
    * await persister.startAutoSave();
@@ -468,7 +477,7 @@ export interface Persister {
    * starts - so those numbers are included in addition to the loads and saves
    * invoked by changes to the Store and to the underlying storage.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const persister = createSessionPersister(store, 'pets');
    *
@@ -493,16 +502,114 @@ export interface Persister {
   getStats(): PersisterStats;
 }
 
+/**
+ * The createSessionPersister function creates an 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 an 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 an 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,
@@ -510,8 +617,91 @@ export function createRemotePersister(
   autoLoadIntervalSeconds: number,
 ): Persister;
 
+/**
+ * The createFilePersister function creates an 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 an Persister object that you can
+ * configure to persist the Store in any way you wish.
+ *
+ * As well as providing a reference to the Store to persist, you must provide
+ * functions that handle how to fetch, write, and listen to, the persistence
+ * layer.
+ *
+ * The other creation functions (such as the createSessionPersister function and
+ * createFilePersister function, for example) all use this function under the
+ * covers. See those implementations for ideas on how to implement your own
+ * Persister types.
+ *
+ * @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
+ * persistence layer.
+ * @param startListeningToPersisted A function that will register a `didChange`
+ * listener on underlying changes to the persistence layer.
+ * @param stopListeningToPersisted A function that will unregister the listener
+ * from the underlying changes to the persistence layer.
+ * @returns A reference to the new Persister object.
+ * @example
+ * This example creates a custom Persister object and persists the Store to a
+ * local string called `storeJson` and which would automatically load by polling
+ * for changes every second.
+ *
+ * ```js
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * let storeJson;
+ * let interval;
+ *
+ * const persister = createCustomPersister(
+ *   store,
+ *   async () => storeJson,
+ *   async (json) => (storeJson = json),
+ *   (didChange) => (interval = setInterval(didChange, 1000)),
+ *   () => clearInterval(interval),
+ * );
+ *
+ * await persister.save();
+ * console.log(storeJson);
+ * // -> '{"pets":{"fido":{"species":"dog"}}}'
+ *
+ * storeJson = '{"pets":{"fido":{"species":"dog","color":"brown"}}}';
+ * await persister.load();
+ *
+ * console.log(store.getTables());
+ * // -> {pets: {fido: {species: 'dog', color: 'brown'}}}
+ *
+ * persister.destroy();
+ * ```
+ * @category Creation
+ */
 export function createCustomPersister(
   store: Store,
   getPersisted: () => Promise<string | null | undefined>,

package/lib/relationships.d.ts

@@ -4,7 +4,7 @@
  *
  * The main entry point to this module is the createRelationships function,
  * which returns a new Relationships object. From there, you can create new
- * relationship definitions, access the associations within those relationships
+ * Relationship definitions, access the associations within those Relationships
  * directly, and register listeners for when they change.
  *
  * @packageDocumentation
@@ -50,6 +50,9 @@ export type Relationship = {
  * object, the Id of the Relationship that changed, and the Id of the local Row
  * whose remote Row Id changed.
  *
+ * @param relationships A reference to the Relationships object that changed.
+ * @param relationshipId The Id of the Relationship that changed.
+ * @param localRowId The Id of the local Row whose remote Row Id changed.
  * @category Listener
  */
 export type RemoteRowIdListener = (
@@ -67,8 +70,11 @@ export type RemoteRowIdListener = (
  *
  * When called, a LocalRowIdsListener is given a reference to the Relationships
  * object, the Id of the Relationship that changed, and the Id of the remote Row
- * whose local Row Id changed.
+ * whose local Row Ids changed.
  *
+ * @param relationships A reference to the Relationships object that changed.
+ * @param relationshipId The Id of the Relationship that changed.
+ * @param remoteRowId The Id of the remote Row whose local Row Ids changed.
  * @category Listener
  */
 export type LocalRowIdsListener = (
@@ -88,6 +94,10 @@ export type LocalRowIdsListener = (
  * object, the Id of the Relationship that changed, and the Id of the first Row
  * of the the linked list whose members changed.
  *
+ * @param relationships A reference to the Relationships object that changed.
+ * @param relationshipId The Id of the Relationship that changed.
+ * @param firstRowId The Id of the first Row of the the linked list whose
+ * members changed.
  * @category Listener
  */
 export type LinkedRowIdsListener = (
@@ -107,8 +117,19 @@ export type LinkedRowIdsListener = (
  * @category Development
  */
 export type RelationshipsListenerStats = {
+  /**
+   * The number of RemoteRowIdListeners registered with the Relationships
+   * object.
+   */
   remoteRowId?: number;
+  /**
+   * The number of LocalRowIdsListeners registered with the Relationships
+   * object.
+   */
   localRowIds?: number;
+  /**
+   * The number of LinkedRowIds registered with the Relationships object.
+   */
   linkedRowIds?: number;
 };
 
@@ -137,7 +158,7 @@ export type RelationshipsListenerStats = {
  * creation, to adding definitions (both local/remote table and linked list),
  * getting their contents, and then registering and removing listeners for them.
  *
- * ```tsx
+ * ```js
  * const store = createStore()
  *   .setTable('pets', {
  *     fido: {species: 'dog', next: 'felix'},
@@ -201,6 +222,9 @@ export type RelationshipsListenerStats = {
  * relationships.delListener(listenerId2);
  * relationships.destroy();
  * ```
+ * @see Relationships And Checkpoints guides
+ * @see TinyDraw demo
+ * @category Relationships
  */
 export interface Relationships {
   /**
@@ -239,7 +263,7 @@ export interface Relationships {
    * a simple Relationship based on the values in the `species` Cell of the
    * `pets` Table that relates a Row to another in the `species` Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -269,7 +293,7 @@ export interface Relationships {
    * a linked list Relationship based on the values in the `next` Cell of the
    * `pets` Table that relates a Row to another in the same Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', next: 'felix'},
    *   felix: {species: 'cat', next: 'cujo'},
@@ -306,7 +330,7 @@ export interface Relationships {
    * This example creates a Store, creates a Relationships object, defines a
    * simple Relationship, and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -345,7 +369,7 @@ export interface Relationships {
    * This example creates a Relationships object against a newly-created Store
    * and then gets its reference in order to update its data.
    *
-   * ```tsx
+   * ```js
    * const relationships = createRelationships(createStore());
    * relationships.setRelationshipDefinition(
    *   'petSpecies',
@@ -370,7 +394,7 @@ export interface Relationships {
    * This example creates a Relationships object with two definitions, and then
    * gets the Ids of the definitions.
    *
-   * ```tsx
+   * ```js
    * const relationships = createRelationships(createStore())
    *   .setRelationshipDefinition('petSpecies', 'pets', 'species', 'species')
    *   .setRelationshipDefinition('petSequence', 'pets', 'pets', 'next');
@@ -395,7 +419,7 @@ export interface Relationships {
    * definition, and then queries it (and a non-existent definition) to get the
    * underlying local Table Id.
    *
-   * ```tsx
+   * ```js
    * const relationships = createRelationships(createStore());
    * relationships.setRelationshipDefinition(
    *   'petSpecies',
@@ -427,7 +451,7 @@ export interface Relationships {
    * definition, and then queries it (and a non-existent definition) to get the
    * underlying remote Table Id.
    *
-   * ```tsx
+   * ```js
    * const relationships = createRelationships(createStore());
    * relationships.setRelationshipDefinition(
    *   'petSpecies',
@@ -461,7 +485,7 @@ export interface Relationships {
    * in the Relationship (and also the remote Row Ids for a local Row that does
    * not exist, and for a Relationship that has not been defined).
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -508,7 +532,7 @@ export interface Relationships {
    * in the Relationship (and also the local Row Ids for a remote Row that does
    * not exist, and for a Relationship that has not been defined).
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -560,7 +584,7 @@ export interface Relationships {
    * linked Row Ids in the Relationship (and also the linked Row Ids for a Row
    * that does not exist, and for a Relationship that has not been defined).
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', next: 'felix'},
    *   felix: {species: 'cat', next: 'cujo'},
@@ -618,7 +642,7 @@ export interface Relationships {
    * This example creates a Store, a Relationships object, and then registers a
    * listener that responds to any changes to a specific local Row's remote Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -660,7 +684,7 @@ export interface Relationships {
    * also illustrates how you can use the getStore method and the getRemoteRowId
    * method to resolve the remote Row as a whole.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog', color: 'brown'},
@@ -750,7 +774,7 @@ export interface Relationships {
    * listener that responds to any changes to a specific remote Row's local Row
    * objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -791,7 +815,7 @@ export interface Relationships {
    * listener that responds to any changes to any remote Row's local Row
    * objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog', color: 'brown'},
@@ -877,7 +901,7 @@ export interface Relationships {
    * listener that responds to any changes to a specific first Row's linked Row
    * objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', next: 'felix'},
    *   felix: {species: 'cat', next: 'cujo'},
@@ -930,7 +954,7 @@ export interface Relationships {
    * This example creates a Store, a Relationships object, registers a listener,
    * and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -984,7 +1008,7 @@ export interface Relationships {
    * definition (that registers a RowListener with the underlying Store),
    * and then destroys it again, removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTable('pets', {
    *     fido: {species: 'dog'},
@@ -1034,7 +1058,7 @@ export interface Relationships {
    * @example
    * This example gets the listener statistics of a Relationships object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const relationships = createRelationships(store);
    * relationships.addRemoteRowIdListener(null, null, () => {
@@ -1070,7 +1094,7 @@ export interface Relationships {
  * @example
  * This example creates an Relationships object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const relationships = createRelationships(store);
  * console.log(relationships.getRelationshipIds());
@@ -1080,12 +1104,13 @@ export interface Relationships {
  * This example creates a Relationships object, and calls the method a second
  * time for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const relationships1 = createRelationships(store);
  * const relationships2 = createRelationships(store);
  * console.log(relationships1 === relationships2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createRelationships(store: Store): Relationships;