tinybase 1.0.2 → 1.1.0-beta.0

package/lib/debug/relationships.d.ts

@@ -11,7 +11,7 @@
  * @module relationships
  */
 
-import {GetCell, Store} from './store.d';
+import {GetCell, RowCallback, Store} from './store.d';
 import {Id, IdOrNull, Ids} from './common.d';
 
 /**
@@ -39,6 +39,25 @@ export type Relationship = {
   linkedRowIds: {[firstRowId: Id]: Ids};
 };
 
+/**
+ * The RelationshipCallback type describes a function that takes a
+ * Relationship's Id and a callback to loop over each local Row within it.
+ *
+ * A RelationshipCallback is provided when using the forEachRelationship method,
+ * so that you can do something based on every Relationship in the Relationships
+ * object. See that method for specific examples.
+ *
+ * @param relationshipId The Id of the Relationship that the callback can
+ * operate on.
+ * @param forEachRow A function that will let you iterate over the local Row
+ * objects in this Relationship.
+ * @category Callback
+ */
+export type RelationshipCallback = (
+  relationshipId: Id,
+  forEachRow: (rowCallback: RowCallback) => void,
+) => void;
+
 /**
  * The RemoteRowIdListener type describes a function that is used to listen to
  * changes to the remote Row Id end of a Relationship.
@@ -405,6 +424,72 @@ export interface Relationships {
    */
   getRelationshipIds(): Ids;
 
+  /**
+   * The forEachRelationship method takes a function that it will then call for
+   * each Relationship in a specified Relationships object.
+   *
+   * This method is useful for iterating over the structure of the Relationships
+   * object in a functional style. The `relationshipCallback` parameter is a
+   * RelationshipCallback function that will be called with the Id of each
+   * Relationship, and with a function that can then be used to iterate over
+   * each local Row involved in the Relationship.
+   *
+   * @param relationshipCallback The function that should be called for every
+   * Relationship.
+   * @example
+   * This example iterates over each Relationship in a Relationships object, and
+   * lists each Row Id within them.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', next: 'felix'},
+   *   felix: {species: 'cat', next: 'cujo'},
+   *   cujo: {species: 'dog'},
+   * });
+   * const relationships = createRelationships(store)
+   *   .setRelationshipDefinition('petSpecies', 'pets', 'species', 'species')
+   *   .setRelationshipDefinition('petSequence', 'pets', 'pets', 'next');
+   *
+   * relationships.forEachRelationship((relationshipId, forEachRow) => {
+   *   console.log(relationshipId);
+   *   forEachRow((rowId) => console.log(`- ${rowId}`));
+   * });
+   * // -> 'petSpecies'
+   * // -> '- fido'
+   * // -> '- felix'
+   * // -> '- cujo'
+   * // -> 'petSequence'
+   * // -> '- fido'
+   * // -> '- felix'
+   * // -> '- cujo'
+   * ```
+   * @category Iterator
+   */
+  forEachRelationship(relationshipCallback: RelationshipCallback): void;
+
+  /**
+   * The hasRelationship method returns a boolean indicating whether a given
+   * Relationship exists in the Relationships object.
+   *
+   * @param relationshipId The Id of a possible Relationship in the
+   * Relationships object.
+   * @returns Whether a Relationship with that Id exists.
+   * @example
+   * This example shows two simple Relationship existence checks.
+   *
+   * ```js
+   * const relationships = createRelationships(
+   *   createStore(),
+   * ).setRelationshipDefinition('petSpecies', 'pets', 'species', 'species');
+   * console.log(relationships.hasRelationship('petSpecies'));
+   * // -> true
+   * console.log(relationships.hasRelationship('petColor'));
+   * // -> false
+   * ```
+   * @category Getter
+   */
+  hasRelationship(indexId: Id): boolean;
+
   /**
    * The getLocalTableId method returns the Id of the underlying local Table
    * that is used in the Relationship.

package/lib/debug/relationships.js

@@ -0,0 +1,434 @@
+const getTypeOf = (thing) => typeof thing;
+const EMPTY_STRING = '';
+const STRING = getTypeOf(EMPTY_STRING);
+
+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 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 createRelationships = getCreateFunction((store) => {
+  const remoteTableIds = mapNew();
+  const remoteRowIdListeners = mapNew();
+  const localRowIdsListeners = mapNew();
+  const linkedRowIdsListeners = mapNew();
+  const [
+    getStore,
+    getRelationshipIds,
+    forEachRelationshipImpl,
+    hasRelationship,
+    getLocalTableId,
+    getRelationship,
+    _setRelationship,
+    setDefinition,
+    delDefinition,
+    destroy,
+  ] = getDefinableFunctions(
+    store,
+    () => [mapNew(), mapNew(), mapNew(), mapNew()],
+    (value) => (isUndefined(value) ? void 0 : value + EMPTY_STRING),
+  );
+  const [addListener, callListeners, delListenerImpl] = getListenerFunctions(
+    () => relationships,
+  );
+  const getLinkedRowIdsCache = (relationshipId, firstRowId, skipCache) =>
+    ifNotUndefined(
+      getRelationship(relationshipId),
+      ([remoteRows, , linkedRowsCache]) => {
+        if (!collHas(linkedRowsCache, firstRowId)) {
+          const linkedRows = setNew();
+          if (
+            getLocalTableId(relationshipId) != getRemoteTableId(relationshipId)
+          ) {
+            setAdd(linkedRows, firstRowId);
+          } else {
+            let rowId = firstRowId;
+            while (!isUndefined(rowId) && !collHas(linkedRows, rowId)) {
+              setAdd(linkedRows, rowId);
+              rowId = mapGet(remoteRows, rowId);
+            }
+          }
+          if (skipCache) {
+            return linkedRows;
+          }
+          mapSet(linkedRowsCache, firstRowId, linkedRows);
+        }
+        return mapGet(linkedRowsCache, firstRowId);
+      },
+    );
+  const delLinkedRowIdsCache = (relationshipId, firstRowId) =>
+    ifNotUndefined(getRelationship(relationshipId), ([, , linkedRowsCache]) =>
+      mapSet(linkedRowsCache, firstRowId),
+    );
+  const setRelationshipDefinition = (
+    relationshipId,
+    localTableId,
+    remoteTableId,
+    getRemoteRowId2,
+  ) => {
+    mapSet(remoteTableIds, relationshipId, remoteTableId);
+    setDefinition(
+      relationshipId,
+      localTableId,
+      (change, changedRemoteRowIds) => {
+        const changedLocalRows = setNew();
+        const changedRemoteRows = setNew();
+        const changedLinkedRows = setNew();
+        const [localRows, remoteRows] = getRelationship(relationshipId);
+        collForEach(
+          changedRemoteRowIds,
+          ([oldRemoteRowId, newRemoteRowId], localRowId) => {
+            if (!isUndefined(oldRemoteRowId)) {
+              setAdd(changedRemoteRows, oldRemoteRowId);
+              ifNotUndefined(
+                mapGet(remoteRows, oldRemoteRowId),
+                (oldRemoteRow) => {
+                  collDel(oldRemoteRow, localRowId);
+                  if (collIsEmpty(oldRemoteRow)) {
+                    mapSet(remoteRows, oldRemoteRowId);
+                  }
+                },
+              );
+            }
+            if (!isUndefined(newRemoteRowId)) {
+              setAdd(changedRemoteRows, newRemoteRowId);
+              if (!collHas(remoteRows, newRemoteRowId)) {
+                mapSet(remoteRows, newRemoteRowId, setNew());
+              }
+              setAdd(mapGet(remoteRows, newRemoteRowId), localRowId);
+            }
+            setAdd(changedLocalRows, localRowId);
+            mapSet(localRows, localRowId, newRemoteRowId);
+            mapForEach(
+              mapGet(linkedRowIdsListeners, relationshipId),
+              (firstRowId) => {
+                if (
+                  collHas(
+                    getLinkedRowIdsCache(relationshipId, firstRowId),
+                    localRowId,
+                  )
+                ) {
+                  setAdd(changedLinkedRows, firstRowId);
+                }
+              },
+            );
+          },
+        );
+        change();
+        collForEach(changedLocalRows, (localRowId) =>
+          callListeners(remoteRowIdListeners, [relationshipId, localRowId]),
+        );
+        collForEach(changedRemoteRows, (remoteRowId) =>
+          callListeners(localRowIdsListeners, [relationshipId, remoteRowId]),
+        );
+        collForEach(changedLinkedRows, (firstRowId) => {
+          delLinkedRowIdsCache(relationshipId, firstRowId);
+          callListeners(linkedRowIdsListeners, [relationshipId, firstRowId]);
+        });
+      },
+      getRowCellFunction(getRemoteRowId2),
+    );
+    return relationships;
+  };
+  const forEachRelationship = (relationshipCallback) =>
+    forEachRelationshipImpl((relationshipId) =>
+      relationshipCallback(relationshipId, (rowCallback) =>
+        store.forEachRow(getLocalTableId(relationshipId), rowCallback),
+      ),
+    );
+  const delRelationshipDefinition = (relationshipId) => {
+    mapSet(remoteTableIds, relationshipId);
+    delDefinition(relationshipId);
+    return relationships;
+  };
+  const getRemoteTableId = (relationshipId) =>
+    mapGet(remoteTableIds, relationshipId);
+  const getRemoteRowId = (relationshipId, localRowId) =>
+    mapGet(getRelationship(relationshipId)?.[0], localRowId);
+  const getLocalRowIds = (relationshipId, remoteRowId) =>
+    collValues(mapGet(getRelationship(relationshipId)?.[1], remoteRowId));
+  const getLinkedRowIds = (relationshipId, firstRowId) =>
+    isUndefined(getRelationship(relationshipId))
+      ? [firstRowId]
+      : collValues(getLinkedRowIdsCache(relationshipId, firstRowId, true));
+  const addRemoteRowIdListener = (relationshipId, localRowId, listener) =>
+    addListener(listener, remoteRowIdListeners, [relationshipId, localRowId]);
+  const addLocalRowIdsListener = (relationshipId, remoteRowId, listener) =>
+    addListener(listener, localRowIdsListeners, [relationshipId, remoteRowId]);
+  const addLinkedRowIdsListener = (relationshipId, firstRowId, listener) => {
+    getLinkedRowIdsCache(relationshipId, firstRowId);
+    return addListener(listener, linkedRowIdsListeners, [
+      relationshipId,
+      firstRowId,
+    ]);
+  };
+  const delListener = (listenerId) => {
+    delLinkedRowIdsCache(...delListenerImpl(listenerId));
+    return relationships;
+  };
+  const getListenerStats = () => ({
+    remoteRowId: collSize3(remoteRowIdListeners),
+    localRowIds: collSize3(localRowIdsListeners),
+    linkedRowIds: collSize3(linkedRowIdsListeners),
+  });
+  const relationships = {
+    setRelationshipDefinition,
+    delRelationshipDefinition,
+    getStore,
+    getRelationshipIds,
+    forEachRelationship,
+    hasRelationship,
+    getLocalTableId,
+    getRemoteTableId,
+    getRemoteRowId,
+    getLocalRowIds,
+    getLinkedRowIds,
+    addRemoteRowIdListener,
+    addLocalRowIdsListener,
+    addLinkedRowIdsListener,
+    delListener,
+    destroy,
+    getListenerStats,
+  };
+  return objFreeze(relationships);
+});
+
+export {createRelationships};