tinybase 1.0.2 → 1.1.0-beta.0

package/lib/debug/indexes.d.ts

@@ -11,7 +11,7 @@
  * @module indexes
  */
 
-import {GetCell, Store} from './store.d';
+import {GetCell, RowCallback, Store} from './store.d';
 import {Id, IdOrNull, Ids, SortKey} from './common.d';
 
 /**
@@ -43,6 +43,42 @@ export type Index = {[sliceId: Id]: Slice};
  */
 export type Slice = Ids;
 
+/**
+ * The IndexCallback type describes a function that takes an Index's Id and a
+ * callback to loop over each Slice within it.
+ *
+ * A IndexCallback is provided when using the forEachIndex method, so that you
+ * can do something based on every Index in the Indexes object. See that method
+ * for specific examples.
+ *
+ * @param indexId The Id of the Index that the callback can operate on.
+ * @param forEachRow A function that will let you iterate over the Slice objects
+ * in this Index.
+ * @category Callback
+ */
+export type IndexCallback = (
+  indexId: Id,
+  forEachSlice: (sliceCallback: SliceCallback) => void,
+) => void;
+
+/**
+ * The SliceCallback type describes a function that takes a Slice's Id and a
+ * callback to loop over each Row within it.
+ *
+ * A SliceCallback is provided when using the forEachSlice method, so that you
+ * can do something based on every Slice in an Index. See that method for
+ * specific examples.
+ *
+ * @param sliceId The Id of the Slice that the callback can operate on.
+ * @param forEachRow A function that will let you iterate over the Row objects
+ * in this Slice.
+ * @category Callback
+ */
+export type SliceCallback = (
+  sliceId: Id,
+  forEachRow: (rowCallback: RowCallback) => void,
+) => void;
+
 /**
  * The SliceIdsListener type describes a function that is used to listen to
  * changes to the Slice Ids in an Index.
@@ -362,6 +398,131 @@ export interface Indexes {
    */
   getIndexIds(): Ids;
 
+  /**
+   * The forEachIndex method takes a function that it will then call for each
+   * Index in a specified Indexes object.
+   *
+   * This method is useful for iterating over the structure of the Indexes
+   * object in a functional style. The `indexCallback` parameter is a
+   * IndexCallback function that will be called with the Id of each Index, and
+   * with a function that can then be used to iterate over each Slice of the
+   * Index, should you wish.
+   *
+   * @param indexCallback The function that should be called for every Index.
+   * @example
+   * This example iterates over each Index in an Indexes object, and lists each
+   * Slice Id within them.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   * const indexes = createIndexes(store)
+   *   .setIndexDefinition('bySpecies', 'pets', 'species')
+   *   .setIndexDefinition('byColor', 'pets', 'color');
+   *
+   * indexes.forEachIndex((indexId, forEachSlice) => {
+   *   console.log(indexId);
+   *   forEachSlice((sliceId) => console.log(`- ${sliceId}`));
+   * });
+   * // -> 'bySpecies'
+   * // -> '- dog'
+   * // -> '- cat'
+   * // -> 'byColor'
+   * // -> '- brown'
+   * // -> '- black'
+   * ```
+   * @category Iterator
+   */
+  forEachIndex(indexCallback: IndexCallback): void;
+
+  /**
+   * The forEachSlice method takes a function that it will then call for each
+   * Slice in a specified Index.
+   *
+   * This method is useful for iterating over the Slice structure of the Index
+   * in a functional style. The `rowCallback` parameter is a RowCallback
+   * function that will be called with the Id and value of each Row in the
+   * Slice.
+   *
+   * @param indexId The Id of the Index to iterate over.
+   * @param sliceCallback The function that should be called for every Slice.
+   * @example
+   * This example iterates over each Row in a Slice, and lists its Id.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * indexes.forEachSlice('bySpecies', (sliceId, forEachRow) => {
+   *   console.log(sliceId);
+   *   forEachRow((rowId) => console.log(`- ${rowId}`));
+   * });
+   * // -> 'dog'
+   * // -> '- fido'
+   * // -> '- cujo'
+   * // -> 'cat'
+   * // -> '- felix'
+   * ```
+   * @category Iterator
+   */
+  forEachSlice(indexId: Id, sliceCallback: SliceCallback): void;
+
+  /**
+   * The hasIndex method returns a boolean indicating whether a given Index
+   * exists in the Indexes object.
+   *
+   * @param indexId The Id of a possible Index in the Indexes object.
+   * @returns Whether an Index with that Id exists.
+   * @example
+   * This example shows two simple Index existence checks.
+   *
+   * ```js
+   * const indexes = createIndexes(createStore());
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   * console.log(indexes.hasIndex('bySpecies'));
+   * // -> true
+   * console.log(indexes.hasIndex('byColor'));
+   * // -> false
+   * ```
+   * @category Getter
+   */
+  hasIndex(indexId: Id): boolean;
+
+  /**
+   * The hasSlice method returns a boolean indicating whether a given Slice
+   * exists in the Indexes object.
+   *
+   * @param indexId The Id of a possible Index in the Indexes object.
+   * @param sliceId The Id of a possible Slice in the Index.
+   * @returns Whether a Slice with that Id exists.
+   * @example
+   * This example shows two simple Index existence checks.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   * console.log(indexes.hasSlice('bySpecies', 'dog'));
+   * // -> true
+   * console.log(indexes.hasSlice('bySpecies', 'worm'));
+   * // -> false
+   * ```
+   * @category Getter
+   */
+  hasSlice(indexId: Id, sliceId: Id): boolean;
+
   /**
    * The getTableId method returns the Id of the underlying Table that is
    * backing an Index.
@@ -473,7 +634,7 @@ export interface Indexes {
    * the Index change.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
-   * This example creates a Store, a Indexes object, and then registers a
+   * This example creates a Store, an Indexes object, and then registers a
    * listener that responds to any changes to a specific Index.
    *
    * ```js
@@ -501,7 +662,7 @@ export interface Indexes {
    * indexes.delListener(listenerId);
    * ```
    * @example
-   * This example creates a Store, a Indexes object, and then registers a
+   * This example creates a Store, an Indexes object, and then registers a
    * listener that responds to any changes to any Index.
    *
    * ```js
@@ -558,7 +719,7 @@ export interface Indexes {
    * the Slice change.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
-   * This example creates a Store, a Indexes object, and then registers a
+   * This example creates a Store, an Indexes object, and then registers a
    * listener that responds to any changes to a specific Slice.
    *
    * ```js
@@ -587,7 +748,7 @@ export interface Indexes {
    * indexes.delListener(listenerId);
    * ```
    * @example
-   * This example creates a Store, a Indexes object, and then registers a
+   * This example creates a Store, an Indexes object, and then registers a
    * listener that responds to any changes to any Slice.
    *
    * ```js
@@ -639,7 +800,7 @@ export interface Indexes {
    * @param listenerId The Id of the listener to remove.
    * @returns A reference to the Indexes object.
    * @example
-   * This example creates a Store, a Indexes object, registers a listener, and
+   * This example creates a Store, an Indexes object, registers a listener, and
    * then removes it.
    *
    * ```js

package/lib/debug/indexes.js

@@ -0,0 +1,431 @@
+const getTypeOf = (thing) => typeof thing;
+const EMPTY_STRING = '';
+const STRING = getTypeOf(EMPTY_STRING);
+
+const arrayIsSorted = (array, sorter) =>
+  array.every(
+    (value, index) => index == 0 || sorter(array[index - 1], value) <= 0,
+  );
+const arraySort = (array, sorter) => array.sort(sorter);
+const arrayForEach = (array, cb) => array.forEach(cb);
+const arrayLength = (array) => array.length;
+const arrayIsEmpty = (array) => arrayLength(array) == 0;
+const arrayReduce = (array, cb, initial) => array.reduce(cb, initial);
+const arrayFromSecond = (ids) => ids.slice(1);
+const arrayPush = (array, value) => array.push(value);
+const arrayPop = (array) => array.pop();
+
+const isUndefined = (thing) => thing == void 0;
+const ifNotUndefined = (value, then, otherwise) =>
+  isUndefined(value) ? otherwise?.() : then(value);
+const isString = (thing) => getTypeOf(thing) == STRING;
+
+const collSizeN = (collSizer) => (coll) =>
+  arrayReduce(collValues(coll), (total, coll2) => total + collSizer(coll2), 0);
+const collSize = (coll) => coll.size;
+const collSize2 = collSizeN(collSize);
+const collSize3 = collSizeN(collSize2);
+const collHas = (coll, keyOrValue) => coll?.has(keyOrValue) ?? false;
+const collIsEmpty = (coll) => isUndefined(coll) || collSize(coll) == 0;
+const collValues = (coll) => [...(coll?.values() ?? [])];
+const collClear = (coll) => coll.clear();
+const collForEach = (coll, cb) => coll?.forEach(cb);
+const collDel = (coll, keyOrValue) => coll?.delete(keyOrValue);
+
+const mapNew = (entries) => new Map(entries);
+const mapKeys = (map) => [...(map?.keys() ?? [])];
+const mapGet = (map, key) => map?.get(key);
+const mapForEach = (map, cb) =>
+  collForEach(map, (value, key) => cb(key, value));
+const mapSet = (map, key, value) =>
+  isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
+const mapEnsure = (map, key, defaultValue, onWillAdd) => {
+  if (!collHas(map, key)) {
+    onWillAdd?.(defaultValue);
+    map.set(key, defaultValue);
+  }
+  return mapGet(map, key);
+};
+
+const setNew = (entries) => new Set(entries);
+const setAdd = (set, value) => set?.add(value);
+
+const getDefinableFunctions = (store, getDefaultThing, validateRowValue) => {
+  const hasRow = store.hasRow;
+  const tableIds = mapNew();
+  const things = mapNew();
+  const allRowValues = mapNew();
+  const allSortKeys = mapNew();
+  const storeListenerIds = mapNew();
+  const getStore = () => store;
+  const getThingIds = () => mapKeys(tableIds);
+  const forEachThing = (cb) => mapForEach(things, cb);
+  const hasThing = (id) => collHas(things, id);
+  const getTableId = (id) => mapGet(tableIds, id);
+  const getThing = (id) => mapGet(things, id);
+  const setThing = (id, thing) => mapSet(things, id, thing);
+  const removeStoreListeners = (id) =>
+    ifNotUndefined(mapGet(storeListenerIds, id), (listenerIds) => {
+      collForEach(listenerIds, store.delListener);
+      mapSet(storeListenerIds, id);
+    });
+  const setDefinition = (id, tableId, onChanged, getRowValue, getSortKey) => {
+    const changedRowValues = mapNew();
+    const changedSortKeys = mapNew();
+    mapSet(tableIds, id, tableId);
+    if (!collHas(things, id)) {
+      mapSet(things, id, getDefaultThing());
+      mapSet(allRowValues, id, mapNew());
+      mapSet(allSortKeys, id, mapNew());
+    }
+    const rowValues = mapGet(allRowValues, id);
+    const sortKeys = mapGet(allSortKeys, id);
+    const processRow = (rowId) => {
+      const getCell = (cellId) => store.getCell(tableId, rowId, cellId);
+      const oldRowValue = mapGet(rowValues, rowId);
+      const newRowValue = hasRow(tableId, rowId)
+        ? validateRowValue(getRowValue(getCell, rowId))
+        : void 0;
+      if (oldRowValue != newRowValue) {
+        mapSet(changedRowValues, rowId, [oldRowValue, newRowValue]);
+      }
+      if (!isUndefined(getSortKey)) {
+        const oldSortKey = mapGet(sortKeys, rowId);
+        const newSortKey = hasRow(tableId, rowId)
+          ? getSortKey(getCell, rowId)
+          : void 0;
+        if (oldSortKey != newSortKey) {
+          mapSet(changedSortKeys, rowId, newSortKey);
+        }
+      }
+    };
+    const processTable = (force) => {
+      onChanged(
+        () => {
+          collForEach(changedRowValues, ([, newRowValue], rowId) =>
+            mapSet(rowValues, rowId, newRowValue),
+          );
+          collForEach(changedSortKeys, (newSortKey, rowId) =>
+            mapSet(sortKeys, rowId, newSortKey),
+          );
+        },
+        changedRowValues,
+        changedSortKeys,
+        rowValues,
+        sortKeys,
+        force,
+      );
+      collClear(changedRowValues);
+      collClear(changedSortKeys);
+    };
+    mapForEach(rowValues, processRow);
+    if (store.hasTable(tableId)) {
+      arrayForEach(store.getRowIds(tableId), (rowId) => {
+        if (!collHas(rowValues, rowId)) {
+          processRow(rowId);
+        }
+      });
+    }
+    processTable(true);
+    removeStoreListeners(id);
+    mapSet(
+      storeListenerIds,
+      id,
+      setNew([
+        store.addRowListener(tableId, null, (_store, _tableId, rowId) =>
+          processRow(rowId),
+        ),
+        store.addTableListener(tableId, () => processTable()),
+      ]),
+    );
+  };
+  const delDefinition = (id) => {
+    mapSet(tableIds, id);
+    mapSet(things, id);
+    mapSet(allRowValues, id);
+    mapSet(allSortKeys, id);
+    removeStoreListeners(id);
+  };
+  const destroy = () => mapForEach(storeListenerIds, delDefinition);
+  return [
+    getStore,
+    getThingIds,
+    forEachThing,
+    hasThing,
+    getTableId,
+    getThing,
+    setThing,
+    setDefinition,
+    delDefinition,
+    destroy,
+  ];
+};
+const getRowCellFunction = (getRowCell, defaultCellValue) =>
+  isString(getRowCell)
+    ? (getCell) => getCell(getRowCell)
+    : getRowCell ?? (() => defaultCellValue ?? EMPTY_STRING);
+const getCreateFunction = (getFunction) => {
+  const getFunctionsByStore = /* @__PURE__ */ new WeakMap();
+  return (store) => {
+    if (!getFunctionsByStore.has(store)) {
+      getFunctionsByStore.set(store, getFunction(store));
+    }
+    return getFunctionsByStore.get(store);
+  };
+};
+
+const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
+
+const addDeepSet = (deepSet, value, ids) =>
+  arrayLength(ids) < 2
+    ? setAdd(
+        arrayIsEmpty(ids) ? deepSet : mapEnsure(deepSet, ids[0], setNew()),
+        value,
+      )
+    : addDeepSet(
+        mapEnsure(deepSet, ids[0], mapNew()),
+        value,
+        arrayFromSecond(ids),
+      );
+const forDeepSet = (valueDo) => {
+  const deep = (deepIdSet, arg, ...ids) =>
+    ifNotUndefined(deepIdSet, (deepIdSet2) =>
+      arrayIsEmpty(ids)
+        ? valueDo(deepIdSet2, arg)
+        : arrayForEach([ids[0], null], (id) =>
+            deep(mapGet(deepIdSet2, id), arg, ...arrayFromSecond(ids)),
+          ),
+    );
+  return deep;
+};
+const getListenerFunctions = (getThing) => {
+  let thing;
+  let nextId = 0;
+  const listenerPool = [];
+  const allListeners = mapNew();
+  const addListener = (listener, deepSet, idOrNulls = []) => {
+    thing ??= getThing();
+    const id = arrayPop(listenerPool) ?? '' + nextId++;
+    mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
+    addDeepSet(deepSet, id, idOrNulls);
+    return id;
+  };
+  const callListeners = (deepSet, ids = [], ...extraArgs) =>
+    forDeepSet(collForEach)(
+      deepSet,
+      (id) =>
+        ifNotUndefined(mapGet(allListeners, id), ([listener]) =>
+          listener(thing, ...ids, ...extraArgs),
+        ),
+      ...ids,
+    );
+  const delListener = (id) =>
+    ifNotUndefined(
+      mapGet(allListeners, id),
+      ([, deepSet, idOrNulls]) => {
+        forDeepSet(collDel)(deepSet, id, ...idOrNulls);
+        mapSet(allListeners, id);
+        if (arrayLength(listenerPool) < 1e3) {
+          arrayPush(listenerPool, id);
+        }
+        return idOrNulls;
+      },
+      () => [],
+    );
+  const callListener = (id, idNullGetters, extraArgsGetter) =>
+    ifNotUndefined(mapGet(allListeners, id), ([listener, , idOrNulls]) => {
+      const callWithIds = (...ids) => {
+        const index = arrayLength(ids);
+        index == arrayLength(idOrNulls)
+          ? listener(thing, ...ids, ...extraArgsGetter(ids))
+          : isUndefined(idOrNulls[index])
+          ? arrayForEach(idNullGetters[index](...ids), (id2) =>
+              callWithIds(...ids, id2),
+            )
+          : callWithIds(...ids, idOrNulls[index]);
+      };
+      callWithIds();
+    });
+  return [addListener, callListeners, delListener, callListener];
+};
+
+const object = Object;
+const objFreeze = object.freeze;
+
+const createIndexes = getCreateFunction((store) => {
+  const sliceIdsListeners = mapNew();
+  const sliceRowIdsListeners = mapNew();
+  const [
+    getStore,
+    getIndexIds,
+    forEachIndexImpl,
+    hasIndex,
+    getTableId,
+    getIndex,
+    setIndex,
+    setDefinition,
+    delDefinition,
+    destroy,
+  ] = getDefinableFunctions(store, mapNew, (value) =>
+    isUndefined(value) ? EMPTY_STRING : value + EMPTY_STRING,
+  );
+  const [addListener, callListeners, delListenerImpl] = getListenerFunctions(
+    () => indexes,
+  );
+  const hasSlice = (indexId, sliceId) => collHas(getIndex(indexId), sliceId);
+  const setIndexDefinition = (
+    indexId,
+    tableId,
+    getSliceId,
+    getSortKey,
+    sliceIdSorter,
+    rowIdSorter = defaultSorter,
+  ) => {
+    const sliceIdArraySorter = isUndefined(sliceIdSorter)
+      ? void 0
+      : ([id1], [id2]) => sliceIdSorter(id1, id2);
+    setDefinition(
+      indexId,
+      tableId,
+      (change, changedSliceIds, changedSortKeys, sliceIds, sortKeys, force) => {
+        let sliceIdsChanged = 0;
+        const changedSlices = setNew();
+        const unsortedSlices = setNew();
+        const index = getIndex(indexId);
+        collForEach(changedSliceIds, ([oldSliceId, newSliceId], rowId) => {
+          if (!isUndefined(oldSliceId)) {
+            setAdd(changedSlices, oldSliceId);
+            ifNotUndefined(mapGet(index, oldSliceId), (oldSlice) => {
+              collDel(oldSlice, rowId);
+              if (collIsEmpty(oldSlice)) {
+                mapSet(index, oldSliceId);
+                sliceIdsChanged = 1;
+              }
+            });
+          }
+          if (!isUndefined(newSliceId)) {
+            setAdd(changedSlices, newSliceId);
+            if (!collHas(index, newSliceId)) {
+              mapSet(index, newSliceId, setNew());
+              sliceIdsChanged = 1;
+            }
+            setAdd(mapGet(index, newSliceId), rowId);
+            if (!isUndefined(getSortKey)) {
+              setAdd(unsortedSlices, newSliceId);
+            }
+          }
+        });
+        change();
+        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(
+                mapGet(sortKeys, rowId1),
+                mapGet(sortKeys, rowId2),
+                sliceId,
+              );
+            const sliceArray = [...mapGet(index, sliceId)];
+            if (!arrayIsSorted(sliceArray, rowIdArraySorter)) {
+              mapSet(
+                index,
+                sliceId,
+                setNew(arraySort(sliceArray, rowIdArraySorter)),
+              );
+              setAdd(changedSlices, sliceId);
+            }
+          });
+        }
+        if (sliceIdsChanged || force) {
+          if (!isUndefined(sliceIdArraySorter)) {
+            const indexArray = [...index];
+            if (!arrayIsSorted(indexArray, sliceIdArraySorter)) {
+              setIndex(
+                indexId,
+                mapNew(arraySort(indexArray, sliceIdArraySorter)),
+              );
+              sliceIdsChanged = 1;
+            }
+          }
+        }
+        if (sliceIdsChanged) {
+          callListeners(sliceIdsListeners, [indexId]);
+        }
+        collForEach(changedSlices, (sliceId) =>
+          callListeners(sliceRowIdsListeners, [indexId, sliceId]),
+        );
+      },
+      getRowCellFunction(getSliceId),
+      ifNotUndefined(getSortKey, getRowCellFunction),
+    );
+    return indexes;
+  };
+  const forEachIndex = (indexCallback) =>
+    forEachIndexImpl((indexId, slices) =>
+      indexCallback(indexId, (sliceCallback) =>
+        forEachSliceImpl(indexId, sliceCallback, slices),
+      ),
+    );
+  const forEachSlice = (indexId, sliceCallback) =>
+    forEachSliceImpl(indexId, sliceCallback, getIndex(indexId));
+  const forEachSliceImpl = (indexId, sliceCallback, slices) => {
+    const tableId = getTableId(indexId);
+    collForEach(slices, (rowIds, sliceId) =>
+      sliceCallback(sliceId, (rowCallback) =>
+        collForEach(rowIds, (rowId) =>
+          rowCallback(rowId, (cellCallback) =>
+            store.forEachCell(tableId, rowId, cellCallback),
+          ),
+        ),
+      ),
+    );
+  };
+  const delIndexDefinition = (indexId) => {
+    delDefinition(indexId);
+    return indexes;
+  };
+  const getSliceIds = (indexId) => mapKeys(getIndex(indexId));
+  const getSliceRowIds = (indexId, sliceId) =>
+    collValues(mapGet(getIndex(indexId), sliceId));
+  const addSliceIdsListener = (indexId, listener) =>
+    addListener(listener, sliceIdsListeners, [indexId]);
+  const addSliceRowIdsListener = (indexId, sliceId, listener) =>
+    addListener(listener, sliceRowIdsListeners, [indexId, sliceId]);
+  const delListener = (listenerId) => {
+    delListenerImpl(listenerId);
+    return indexes;
+  };
+  const getListenerStats = () => ({
+    sliceIds: collSize2(sliceIdsListeners),
+    sliceRowIds: collSize3(sliceRowIdsListeners),
+  });
+  const indexes = {
+    setIndexDefinition,
+    delIndexDefinition,
+    getStore,
+    getIndexIds,
+    forEachIndex,
+    forEachSlice,
+    hasIndex,
+    hasSlice,
+    getTableId,
+    getSliceIds,
+    getSliceRowIds,
+    addSliceIdsListener,
+    addSliceRowIdsListener,
+    delListener,
+    destroy,
+    getListenerStats,
+  };
+  return objFreeze(indexes);
+});
+
+export {createIndexes};