tinybase 0.9.3 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-
+Copyright (c) James Pearce, 2021-
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/lib/debug/checkpoints.d.ts

@@ -142,6 +142,9 @@ export type CheckpointsListenerStats = {
  * checkpoints.delListener(listenerId);
  * checkpoints.destroy();
  * ```
+ * @see Relationships And Checkpoints guides
+ * @see Todo App demos
+ * @see TinyDraw demo
  * @category Checkpoints
  */
 export interface Checkpoints {

package/lib/debug/common.d.ts

@@ -57,3 +57,59 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
  * @category Callback
  */
 export type Callback = () => void;
+
+/**
+ * The SortKey type represents a value that can be used by a sort function.
+ *
+ * @category Parameter
+ */
+export type SortKey = string | number | boolean;
+
+/**
+ * The defaultSorter function is provided as a convenience to sort keys
+ * alphanumerically, and can be provided to the `sliceIdSorter` and
+ * `rowIdSorter` parameters of the setIndexDefinition method in the indexes
+ * module, for example.
+ *
+ * @param sortKey1 The first item of the pair to compare.
+ * @param sortKey2 The second item of the pair to compare.
+ * @returns A number indicating how to sort the pair.
+ * @example
+ * This example creates an Indexes object.
+ *
+ * ```js
+ * const store = createStore();
+ * const indexes = createIndexes(store);
+ * console.log(indexes.getIndexIds());
+ * // -> []
+ * ```
+ * @example
+ * This example creates a Store, creates an Indexes object, and defines an
+ * Index based on the first letter of the pets' names. The Slice Ids (and Row
+ * Ids within them) are alphabetically sorted using the defaultSorter function.
+ *
+ * ```js
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ *
+ * const indexes = createIndexes(store);
+ * indexes.setIndexDefinition(
+ *   'byFirst', //              indexId
+ *   'pets', //                 tableId
+ *   (_, rowId) => rowId[0], // each Row's Slice Id
+ *   (_, rowId) => rowId, //    each Row's sort key
+ *   defaultSorter, //          sort Slice Ids
+ *   defaultSorter, //          sort Row Ids by sort key
+ * );
+ *
+ * console.log(indexes.getSliceIds('byFirst'));
+ * // -> ['c', 'f']
+ * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+ * // -> ['felix', 'fido']
+ * ```
+ * @category Convenience
+ */
+export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/debug/indexes.d.ts

@@ -3,8 +3,8 @@
  * and track indexes of the data in Store objects.
  *
  * The main entry point to this module is the createIndexes function, which
- * returns a new Indexes object. From there, you can create new index
- * definitions, access the contents of those indexes directly, and register
+ * 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
@@ -12,7 +12,7 @@
  */
 
 import {GetCell, Store} from './store.d';
-import {Id, IdOrNull, Ids} from './common.d';
+import {Id, IdOrNull, Ids, SortKey} from './common.d';
 
 /**
  * The Index type represents the concept of a map of Slice objects, keyed by Id.
@@ -43,13 +43,6 @@ export type Index = {[sliceId: Id]: Slice};
  */
 export type Slice = Ids;
 
-/**
- * The SortKey type represents a value that can be used by a sort function.
- *
- * @category Parameter
- */
-export type SortKey = string | number | boolean;
-
 /**
  * The SliceIdsListener type describes a function that is used to listen to
  * changes to the Slice Ids in an Index.
@@ -157,6 +150,10 @@ export type IndexesListenerStats = {
  * indexes.delListener(listenerId);
  * indexes.destroy();
  * ```
+ * @see Metrics And Indexes guides
+ * @see Rolling Dice demos
+ * @see Country demo
+ * @see Todo App demos
  * @category Indexes
  */
 export interface Indexes {
@@ -779,51 +776,3 @@ export interface Indexes {
  * @category Creation
  */
 export function createIndexes(store: Store): Indexes;
-
-/**
- * The defaultSorter function is provided as a convenience to sort keys
- * alphanumerically, and can be provided to the `sliceIdSorter` and
- * `rowIdSorter` parameters of the setIndexDefinition method, for example.
- *
- * @param sortKey1 The first item of the pair to compare.
- * @param sortKey2 The second item of the pair to compare.
- * @returns A number indicating how to sort the pair.
- * @example
- * This example creates an Indexes object.
- *
- * ```js
- * const store = createStore();
- * const indexes = createIndexes(store);
- * console.log(indexes.getIndexIds());
- * // -> []
- * ```
- * @example
- * This example creates a Store, creates an Indexes object, and defines an
- * Index based on the first letter of the pets' names. The Slice Ids (and Row
- * Ids within them) are alphabetically sorted using the defaultSorter function.
- *
- * ```js
- * const store = createStore().setTable('pets', {
- *   fido: {species: 'dog'},
- *   felix: {species: 'cat'},
- *   cujo: {species: 'dog'},
- * });
- *
- * const indexes = createIndexes(store);
- * indexes.setIndexDefinition(
- *   'byFirst', //              indexId
- *   'pets', //                 tableId
- *   (_, rowId) => rowId[0], // each Row's Slice Id
- *   (_, rowId) => rowId, //    each Row's sort key
- *   defaultSorter, //          sort Slice Ids
- *   defaultSorter, //          sort Row Ids by sort key
- * );
- *
- * console.log(indexes.getSliceIds('byFirst'));
- * // -> ['c', 'f']
- * console.log(indexes.getSliceRowIds('byFirst', 'f'));
- * // -> ['felix', 'fido']
- * ```
- * @category Convenience
- */
-export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/debug/metrics.d.ts

@@ -3,8 +3,8 @@
  * and track metrics and aggregates of the data in Store objects.
  *
  * The main entry point to this module is the createMetrics function, which
- * returns a new Metrics object. From there, you can create new metric
- * definitions, access the values of those metrics directly, and register
+ * 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
@@ -226,6 +226,10 @@ export type MetricsListenerStats = {
  * metrics.delListener(listenerId);
  * metrics.destroy();
  * ```
+ * @see Metrics And Indexes guides
+ * @see Rolling Dice demos
+ * @see Country demo
+ * @see Todo App demos
  * @category Metrics
  */
 export interface Metrics {

package/lib/debug/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
@@ -19,12 +19,16 @@
  * 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
@@ -243,6 +247,7 @@ export interface Persister {
    * console.log(store.getTables());
    * // -> {pets: {toto: {species: 'dog'}}}
    *
+   * persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Load
@@ -284,6 +289,7 @@ export interface Persister {
    * // -> {pets: {toto: {species: 'dog'}}}
    * // Storage change has not been automatically loaded.
    *
+   * persister.destroy();
    * sessionStorage.clear();
    * ```
    * @category Load
@@ -650,8 +656,9 @@ export function createFilePersister(store: Store, filePath: string): Persister;
  * layer.
  *
  * The other creation functions (such as the createSessionPersister function and
- * createFilePersister function, for example) all use this under the covers. See
- * those implementations for ideas on how to implement your own Persister types.
+ * 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
@@ -664,9 +671,9 @@ export function createFilePersister(store: Store, filePath: string): Persister;
  * from the underlying changes to the persistence layer.
  * @returns A reference to the new Persister object.
  * @example
- * This example creates a Persister object and persists the Store to a local
- * string called `storeJson` and would automatically load by polling for changes
- * every second.
+ * 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'}}});

package/lib/debug/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
@@ -222,6 +222,8 @@ export type RelationshipsListenerStats = {
  * relationships.delListener(listenerId2);
  * relationships.destroy();
  * ```
+ * @see Relationships And Checkpoints guides
+ * @see TinyDraw demo
  * @category Relationships
  */
 export interface Relationships {

package/lib/debug/store.d.ts

@@ -17,11 +17,10 @@ import {Id, IdOrNull, Ids, Json} from './common.d';
  * The Tables type is the data structure representing all of the data in a
  * Store.
  *
- * A Tables object can be provided to the createStore function when first
- * creating the Store. It is also used when setting all of the tables together
- * with the setTables method, and when getting them back out again with the
- * getTables method. A Tables object is a regular JavaScript object containing
- * individual Table objects, keyed by their Id.
+ * A Tables object is used when setting all of the tables together with the
+ * setTables method, and when getting them back out again with the getTables
+ * method. A Tables object is a regular JavaScript object containing individual
+ * Table objects, keyed by their Id.
  *
  * @example
  * ```js
@@ -371,8 +370,8 @@ export type CellChange = [
  * Ids and the types of Cell that can exist within them.
  *
  * A Schema comprises a JavaScript object describing each Table, in turn a
- * nested JavaScript object containing the each Cell and its CellSchema. It is
- * provided to the createStore function or to the setSchema method.
+ * nested JavaScript object containing information about each Cell and its
+ * CellSchema. It is provided to the setSchema method.
  *
  * @example
  * When applied to a Store, this Schema only allows one Table called `pets`, in
@@ -613,6 +612,10 @@ export type StoreListenerStats = {
  *
  * store.delListener(listenerId);
  * ```
+ * @see The Basics guides
+ * @see Using Schemas guides
+ * @see Hello World demos
+ * @see Todo App demos
  * @category Store
  */
 export interface Store {
@@ -1339,9 +1342,8 @@ export interface Store {
    * applied or as invalid Table, Row, or Cell objects are removed. These
    * changes will fire any listeners to that data, as expected.
    *
-   * You can also specify the Schema at the time of creation, as the second
-   * parameter of the createStore function. When no longer needed, you can also
-   * completely remove an existing Schema with the delSchema method.
+   * When no longer needed, you can also completely remove an existing Schema
+   * with the delSchema method.
    *
    * @param schema The Schema to be set for the Store.
    * @returns A reference to the Store.
@@ -2498,6 +2500,7 @@ export interface Store {
  * console.log(store.getTables());
  * // -> {pets: {fido: {species: 'dog', sold: false}}}
  * ```
+ * @see The Basics guides
  * @category Creation
  */
 export function createStore(): Store;

package/lib/debug/tinybase.js

@@ -509,6 +509,8 @@ const createCheckpoints = getCreateFunction((store) => {
   return objFreeze(checkpoints.clear());
 });
 
+const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
+
 const createIndexes = getCreateFunction((store) => {
   const sliceIdsListeners = mapNew();
   const sliceRowIdsListeners = mapNew();
@@ -541,7 +543,7 @@ const createIndexes = getCreateFunction((store) => {
     setDefinition(
       indexId,
       tableId,
-      (change, changedSliceIds, changedSortKeys, sliceIds, sortKeys) => {
+      (change, changedSliceIds, changedSortKeys, sliceIds, sortKeys, force) => {
         let sliceIdsChanged = 0;
         const changedSlices = setNew();
         const unsortedSlices = setNew();
@@ -570,12 +572,16 @@ const createIndexes = getCreateFunction((store) => {
           }
         });
         change();
-        mapForEach(changedSortKeys, (rowId) =>
-          ifNotUndefined(mapGet(sliceIds, rowId), (sliceId) =>
-            setAdd(unsortedSlices, sliceId),
-          ),
-        );
         if (!collIsEmpty(sortKeys)) {
+          if (force) {
+            mapForEach(index, (sliceId) => setAdd(unsortedSlices, sliceId));
+          } else {
+            mapForEach(changedSortKeys, (rowId) =>
+              ifNotUndefined(mapGet(sliceIds, rowId), (sliceId) =>
+                setAdd(unsortedSlices, sliceId),
+              ),
+            );
+          }
           collForEach(unsortedSlices, (sliceId) => {
             const rowIdArraySorter = (rowId1, rowId2) =>
               rowIdSorter(
@@ -594,7 +600,7 @@ const createIndexes = getCreateFunction((store) => {
             }
           });
         }
-        if (sliceIdsChanged) {
+        if (sliceIdsChanged || force) {
           if (!isUndefined(sliceIdArraySorter)) {
             const indexArray = [...index];
             if (!arrayIsSorted(indexArray, sliceIdArraySorter)) {
@@ -602,8 +608,11 @@ const createIndexes = getCreateFunction((store) => {
                 indexId,
                 mapNew(arraySort(indexArray, sliceIdArraySorter)),
               );
+              sliceIdsChanged = 1;
             }
           }
+        }
+        if (sliceIdsChanged) {
           callListeners(sliceIdsListeners, [indexId]);
         }
         collForEach(changedSlices, (sliceId) =>
@@ -650,7 +659,6 @@ const createIndexes = getCreateFunction((store) => {
   };
   return objFreeze(indexes);
 });
-const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
 
 const aggregators = mapNew([
   [

package/lib/debug/ui-react.d.ts

@@ -10,11 +10,19 @@
  * The components in this module provide a further abstraction over those hooks
  * to ease the composition of user interfaces that use TinyBase.
  *
+ * @see Building UIs guides
+ * @see Building UIs With Metrics guide
+ * @see Building UIs With Indexes guide
+ * @see Building UIs With Relationships guide
+ * @see Building UIs With Checkpoints guide
+ * @see Countries demo
+ * @see Todo App demos
+ * @see TinyDraw demo
  * @packageDocumentation
  * @module ui-react
  */
 
-import {Callback, Id, IdOrNull, Ids, ParameterizedCallback} from './common';
+import {Callback, Id, IdOrNull, Ids, ParameterizedCallback} from './common.d';
 import {
   Cell,
   CellIdsListener,
@@ -2213,6 +2221,9 @@ export function useCellListener(
  * an array in the optional second parameter, just as you would for any React
  * hook with dependencies.
  *
+ * This hook ensures the Metrics object is destroyed whenever a new one is
+ * created or the component is unmounted.
+ *
  * @param store A reference to the Store for which to create a new Metrics
  * object.
  * @param create A function for performing the creation steps of the Metrics
@@ -2554,6 +2565,9 @@ export function useMetricListener(
  * an array in the optional second parameter, just as you would for any React
  * hook with dependencies.
  *
+ * This hook ensures the Indexes object is destroyed whenever a new one is
+ * created or the component is unmounted.
+ *
  * @param store A reference to the Store for which to create a new Indexes
  * object.
  * @param create A function for performing the creation steps of the Indexes
@@ -3104,6 +3118,9 @@ export function useSliceRowIdsListener(
  * them in an array in the optional second parameter, just as you would for any
  * React hook with dependencies.
  *
+ * This hook ensures the Relationships object is destroyed whenever a new one is
+ * created or the component is unmounted.
+ *
  * @param store A reference to the Store for which to create a new Relationships
  * object.
  * @param create An optional callback for performing post-creation steps on the
@@ -3900,6 +3917,9 @@ export function useLinkedRowIdsListener(
  * them in an array in the optional second parameter, just as you would for any
  * React hook with dependencies.
  *
+ * This hook ensures the Checkpoints object is destroyed whenever a new one is
+ * created or the component is unmounted.
+ *
  * @param store A reference to the Store for which to create a new Checkpoints
  * object.
  * @param create A function for performing the creation steps of the Checkpoints
@@ -4751,6 +4771,9 @@ export function useCheckpointListener(
  * an array in the fifth parameter. The Persister itself is used as a dependency
  * by default.
  *
+ * This hook ensures the Persister object is destroyed whenever a new one is
+ * created or the component is unmounted.
+ *
  * @param store A reference to the Store for which to create a new Persister
  * object.
  * @param create A function for performing the creation steps of the Persister
@@ -4795,10 +4818,12 @@ export function useCheckpointListener(
  *
  * // ... // !act
  * ReactDOM.render(<App />, app); // !act
- * // No second Checkpoints creation
+ * // No second Persister creation
  *
  * console.log(app.innerHTML);
  * // -> '<span>{\"pets\":{\"fido\":{\"species\":\"dog\"}}}</span>'
+ *
+ * ReactDOM.unmountComponentAtNode(app); // !act
  * ```
  * @example
  * This example creates a Persister at the top level of a React application. The
@@ -4841,6 +4866,8 @@ export function useCheckpointListener(
  * // ... // !act
  * console.log(app.innerHTML);
  * // -> '<span>{\"pets\":{\"cujo\":{\"species\":\"dog\"}}}</span>'
+ *
+ * ReactDOM.unmountComponentAtNode(app); // !act
  * ```
  *  @category Persister hooks
  */

package/lib/debug/ui-react.js

@@ -48,8 +48,11 @@ const useCheckpointsOrCheckpointsId = (checkpointsOrCheckpointsId) =>
   useThingOrThingId(checkpointsOrCheckpointsId, 8);
 
 const {useCallback, useEffect, useMemo: useMemo$1, useState} = React;
-const useCreate = (store, create, createDeps = []) =>
-  useMemo$1(() => create(store), [store, ...createDeps]);
+const useCreate = (store, create, createDeps = []) => {
+  const thing = useMemo$1(() => create(store), [store, ...createDeps]);
+  useEffect(() => () => thing.destroy(), [thing]);
+  return thing;
+};
 const useListenable = (listenable, thing, defaulted, ...args) => {
   const getListenable = thing?.['get' + listenable] ?? (() => defaulted);
   const immediateListenable = getListenable(...args);
@@ -654,6 +657,9 @@ const useCreatePersister = (
       setDone(1);
       return;
     })();
+    return () => {
+      persister.destroy();
+    };
   }, [persister, ...thenDeps]);
   return persister;
 };

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "tinybase",
-  "version": "0.9.3",
+  "version": "1.0.2",
   "author": "jamesgpearce",
   "repository": "github:tinyplex/tinybase",
   "license": "MIT",
   "homepage": "https://tinybase.org",
   "description": "A tiny, reactive JavaScript library for structured state and tabular data.",
+  "keywords": [
+    "tiny",
+    "reactive",
+    "state",
+    "data",
+    "react"
+  ],
   "type": "module",
   "files": [
     "lib/**"
@@ -14,6 +21,14 @@
     ".": "./lib/tinybase.js",
     "./*": "./lib/*.js"
   },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*.d.ts",
+        "./lib/tinybase.d.ts"
+      ]
+    }
+  },
   "browser": {
     "fs": false
   },
@@ -33,15 +48,16 @@
     "compileDocsPagesOnly": "gulp compileDocsPagesOnly",
     "compileDocsAssetsOnly": "gulp compileDocsAssetsOnly",
     "compileDocs": "gulp compileDocs",
+    "compileForProdAndDocs": "gulp compileForProdAndDocs",
     "serveDocs": "gulp serveDocs",
     "preCommit": "gulp preCommit",
     "prePublishPackage": "gulp prePublishPackage",
     "publishPackage": "gulp publishPackage"
   },
   "devDependencies": {
-    "@babel/cli": "^7.16.7",
+    "@babel/cli": "^7.16.8",
     "@babel/core": "^7.16.7",
-    "@babel/preset-env": "^7.16.7",
+    "@babel/preset-env": "^7.16.8",
     "@babel/preset-react": "^7.16.7",
     "@babel/preset-typescript": "^7.16.7",
     "@rollup/plugin-replace": "^3.0.1",
@@ -56,24 +72,24 @@
     "@types/react-dom": "^17.0.11",
     "@types/react-test-renderer": "^17.0.1",
     "@types/tmp": "^0.2.3",
-    "@typescript-eslint/eslint-plugin": "^5.9.0",
-    "@typescript-eslint/parser": "^5.9.0",
+    "@typescript-eslint/eslint-plugin": "^5.9.1",
+    "@typescript-eslint/parser": "^5.9.1",
     "asciichart": "^1.5.25",
     "babel-eslint": "^10.1.0",
     "babel-jest": "^27.4.6",
     "babel-preset-minify": "^0.5.1",
     "country-flag-emoji-json": "^2.0.0",
-    "cspell": "^5.14.0",
-    "esbuild": "^0.14.10",
-    "eslint": "^8.6.0",
+    "cspell": "^5.15.2",
+    "esbuild": "^0.14.11",
+    "eslint": "^8.7.0",
     "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-jest": "^25.3.4",
-    "eslint-plugin-jsdoc": "^37.5.1",
+    "eslint-plugin-jest": "^25.7.0",
+    "eslint-plugin-jsdoc": "^37.6.1",
     "eslint-plugin-react": "^7.28.0",
     "eslint-plugin-react-hooks": "^4.3.0",
     "gulp": "^4.0.2",
     "gulp-gzip": "^1.4.2",
-    "http-server": "^14.0.0",
+    "http-server": "^14.1.0",
     "jest": "^27.4.7",
     "jest-fetch-mock": "^3.0.3",
     "jest-puppeteer": "^6.0.3",
@@ -83,7 +99,7 @@
     "react": "^17.0.2",
     "react-dom": "^17.0.2",
     "react-test-renderer": "^17.0.2",
-    "rollup": "^2.63.0",
+    "rollup": "^2.64.0",
     "rollup-plugin-esbuild": "^4.8.2",
     "rollup-plugin-gzip": "^3.0.0",
     "rollup-plugin-prettier": "^2.2.2",