tinybase 0.9.0 → 0.9.4

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.
@@ -60,6 +53,8 @@ export type SortKey = string | number | boolean;
  * 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
  */
 export type SliceIdsListener = (indexes: Indexes, indexId: Id) => void;
@@ -75,6 +70,9 @@ export type SliceIdsListener = (indexes: Indexes, indexId: Id) => void;
  * 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.
  * @category Listener
  */
 export type SliceRowIdsListener = (
@@ -93,7 +91,13 @@ export type SliceRowIdsListener = (
  * @category Development
  */
 export type IndexesListenerStats = {
+  /**
+   * The number of SlideIdsListeners registered with the Indexes object.
+   */
   sliceIds?: number;
+  /**
+   * The number of SliceRowIdsListeners registered with the Indexes object.
+   */
   sliceRowIds?: number;
 };
 
@@ -118,7 +122,7 @@ export type IndexesListenerStats = {
  * creation, to adding a definition, getting its contents, and then registering
  * and removing a listener for it.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTable('pets', {
  *   fido: {species: 'dog'},
  *   felix: {species: 'cat'},
@@ -146,6 +150,7 @@ export type IndexesListenerStats = {
  * indexes.delListener(listenerId);
  * indexes.destroy();
  * ```
+ * @category Indexes
  */
 export interface Indexes {
   /**
@@ -211,7 +216,7 @@ export interface Indexes {
    * This example creates a Store, creates an Indexes object, and defines a
    * simple Index based on the values in the `species` Cell.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -230,7 +235,7 @@ export interface Indexes {
    * This example creates a Store, creates an Indexes object, and defines an
    * Index based on the first letter of the pets' names.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -250,7 +255,7 @@ export interface Indexes {
    * Index based on the first letter of the pets' names. The Slice Ids (and Row
    * Ids within them) are alphabetically sorted.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -292,7 +297,7 @@ export interface Indexes {
    * This example creates a Store, creates an Indexes object, defines a simple
    * Index, and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -321,7 +326,7 @@ export interface Indexes {
    * This example creates an Indexes object against a newly-created Store and
    * then gets its reference in order to update its data.
    *
-   * ```tsx
+   * ```js
    * const indexes = createIndexes(createStore());
    * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
    * indexes.getStore().setCell('pets', 'fido', 'species', 'dog');
@@ -341,7 +346,7 @@ export interface Indexes {
    * This example creates an Indexes object with two definitions, and then gets
    * the Ids of the definitions.
    *
-   * ```tsx
+   * ```js
    * const indexes = createIndexes(createStore())
    *   .setIndexDefinition('bySpecies', 'pets', 'species')
    *   .setIndexDefinition('byColor', 'pets', 'color');
@@ -365,7 +370,7 @@ export interface Indexes {
    * This example creates an Indexes object, a single Index definition, and then
    * queries it (and a non-existent definition) to get the underlying Table Id.
    *
-   * ```tsx
+   * ```js
    * const indexes = createIndexes(createStore());
    * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
    *
@@ -391,7 +396,7 @@ export interface Indexes {
    * simple Index. It then uses getSliceIds to see the available Slice Ids in
    * the Index (and also the Slice Ids in an Index that has not been defined).
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -425,7 +430,7 @@ export interface Indexes {
    * simple Index. It then uses getSliceRowIds to see the Row Ids in the Slice
    * (and also the Row Ids in Slices that do not exist).
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -467,7 +472,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to a specific Index.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -495,7 +500,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to any Index.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', color: 'brown'},
    *   felix: {species: 'cat', color: 'black'},
@@ -552,7 +557,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to a specific Slice.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -581,7 +586,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to any Slice.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', color: 'brown'},
    *   felix: {species: 'cat', color: 'black'},
@@ -633,7 +638,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, registers a listener, and
    * then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -675,7 +680,7 @@ export interface Indexes {
    * 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'},
    *   felix: {species: 'cat'},
@@ -714,7 +719,7 @@ export interface Indexes {
    * @example
    * This example gets the listener statistics of an Indexes object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const indexes = createIndexes(store);
    * indexes.addSliceIdsListener(null, () => {
@@ -747,7 +752,7 @@ export interface Indexes {
  * @example
  * This example creates an Indexes object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const indexes = createIndexes(store);
  * console.log(indexes.getIndexIds());
@@ -757,59 +762,13 @@ export interface Indexes {
  * This example creates an Indexes object, and calls the method a second time
  * for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const indexes1 = createIndexes(store);
  * const indexes2 = createIndexes(store);
  * console.log(indexes1 === indexes2);
  * // -> true
  * ```
+ * @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.
- *
- * ```tsx
- * 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.
- *
- * ```tsx
- * 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']
- * ```
- */
-export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/debug/indexes.js

@@ -168,6 +168,8 @@ const getCreateFunction = (getFunction) => {
   };
 };
 
+const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
+
 const addDeepSet = (deepSet, value, ids) =>
   arrayLength(ids) < 2
     ? setAdd(
@@ -196,7 +198,7 @@ const getListenerFunctions = (getThing) => {
   const listenerPool = [];
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
-    thing ?? (thing = getThing());
+    thing ??= getThing();
     const id = listenerPool.pop() ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);
@@ -276,7 +278,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();
@@ -305,12 +307,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(
@@ -329,7 +335,7 @@ const createIndexes = getCreateFunction((store) => {
             }
           });
         }
-        if (sliceIdsChanged) {
+        if (sliceIdsChanged || force) {
           if (!isUndefined(sliceIdArraySorter)) {
             const indexArray = [...index];
             if (!arrayIsSorted(indexArray, sliceIdArraySorter)) {
@@ -337,8 +343,11 @@ const createIndexes = getCreateFunction((store) => {
                 indexId,
                 mapNew(arraySort(indexArray, sliceIdArraySorter)),
               );
+              sliceIdsChanged = 1;
             }
           }
+        }
+        if (sliceIdsChanged) {
           callListeners(sliceIdsListeners, [indexId]);
         }
         collForEach(changedSlices, (sliceId) =>
@@ -385,6 +394,5 @@ const createIndexes = getCreateFunction((store) => {
   };
   return objFreeze(indexes);
 });
-const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
 
-export {createIndexes, defaultSorter};
+export {createIndexes};

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
@@ -31,6 +31,9 @@ export type Metric = number;
  * 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.
  * @category Aggregators
  */
 export type Aggregate = (numbers: number[], length: number) => Metric;
@@ -53,6 +56,10 @@ export type Aggregate = (numbers: number[], length: number) => Metric;
  * 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.
+ * @returns The new value of the Metric.
  * @category Aggregators
  */
 export type AggregateAdd = (
@@ -82,6 +89,10 @@ export type AggregateAdd = (
  * 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.
+ * @returns The new value of the Metric.
  * @category Aggregators
  */
 export type AggregateRemove = (
@@ -109,6 +120,11 @@ export type AggregateRemove = (
  * 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.
+ * @param length The length of the array of numbers in the Metric's aggregation.
+ * @returns The new value of the Metric.
  * @category Aggregators
  */
 export type AggregateReplace = (
@@ -132,6 +148,10 @@ export type AggregateReplace = (
  * 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.
+ * @param oldMetric The old value of the Metric that changed.
  * @category Listener
  */
 export type MetricListener = (
@@ -151,6 +171,9 @@ export type MetricListener = (
  * @category Development
  */
 export type MetricsListenerStats = {
+  /**
+   * The number of MetricListeners registered with the Metrics object.
+   */
   metric?: number;
 };
 
@@ -176,7 +199,7 @@ export type MetricsListenerStats = {
  * creation, to adding a definition, getting an Metric, and then registering and
  * removing a listener for it.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTable('species', {
  *   dog: {price: 5},
  *   cat: {price: 4},
@@ -203,6 +226,7 @@ export type MetricsListenerStats = {
  * metrics.delListener(listenerId);
  * metrics.destroy();
  * ```
+ * @category Metrics
  */
 export interface Metrics {
   /**
@@ -258,7 +282,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, and defines a
    * simple Metric to count the Row objects in the Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -276,7 +300,7 @@ export interface Metrics {
    * standard Metric to get the highest value of each `price` Cell in the Row
    * objects in the Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -293,7 +317,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, and defines a
    * custom Metric to get the lowest value of each `price` Cell, greater than 2.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -317,7 +341,7 @@ export interface Metrics {
    * However, it also reduces algorithmic complexity with two shortcut
    * functions.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -350,7 +374,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, and defines a
    * custom Metric to get the average value of a discounted price.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5, discount: 0.3},
    *   cat: {price: 4, discount: 0.2},
@@ -389,7 +413,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, defines a simple
    * Metric, and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -418,7 +442,7 @@ export interface Metrics {
    * This example creates a Metrics object against a newly-created Store and
    * then gets its reference in order to update its data.
    *
-   * ```tsx
+   * ```js
    * const metrics = createMetrics(createStore());
    * metrics.setMetricDefinition('speciesCount', 'species');
    * metrics.getStore().setCell('species', 'dog', 'price', 5);
@@ -438,7 +462,7 @@ export interface Metrics {
    * This example creates a Metrics object with two definitions, and then gets
    * the Ids of the definitions.
    *
-   * ```tsx
+   * ```js
    * const metrics = createMetrics(createStore())
    *   .setMetricDefinition('speciesCount', 'species')
    *   .setMetricDefinition('petsCount', 'pets');
@@ -462,7 +486,7 @@ export interface Metrics {
    * This example creates a Metrics object, a single Metric definition, and then
    * queries it (and a non-existent definition) to get the underlying Table Id.
    *
-   * ```tsx
+   * ```js
    * const metrics = createMetrics(createStore());
    * metrics.setMetricDefinition('speciesCount', 'species');
    *
@@ -489,7 +513,7 @@ export interface Metrics {
    * getMetric to access its value (and also the value of a Metric that has not
    * been defined).
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -529,7 +553,7 @@ export interface Metrics {
    * This example creates a Store, a Metrics object, and then registers a
    * listener that responds to any changes to a specific Metric.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -557,7 +581,7 @@ export interface Metrics {
    * This example creates a Store, a Metrics object, and then registers a
    * listener that responds to any changes to any Metric.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -601,7 +625,7 @@ export interface Metrics {
    * This example creates a Store, a Metrics object, registers a listener, and
    * then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -643,7 +667,7 @@ export interface Metrics {
    * registers a RowListener with the underlying Store), and then destroys it
    * again, removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -679,7 +703,7 @@ export interface Metrics {
    * @example
    * This example gets the listener statistics of a Metrics object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const metrics = createMetrics(store);
    * metrics.addMetricListener(null, () => console.log('Metric changed'));
@@ -707,7 +731,7 @@ export interface Metrics {
  * @example
  * This example creates a Metrics object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const metrics = createMetrics(store);
  * console.log(metrics.getMetricIds());
@@ -717,12 +741,13 @@ export interface Metrics {
  * This example creates a Metrics object, and calls the method a second time
  * for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const metrics1 = createMetrics(store);
  * const metrics2 = createMetrics(store);
  * console.log(metrics1 === metrics2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createMetrics(store: Store): Metrics;

package/lib/debug/metrics.js

@@ -201,7 +201,7 @@ const getListenerFunctions = (getThing) => {
   const listenerPool = [];
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
-    thing ?? (thing = getThing());
+    thing ??= getThing();
     const id = listenerPool.pop() ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);