tinybase 1.0.2 → 1.1.0-beta.0

package/lib/debug/metrics.d.ts

@@ -22,6 +22,20 @@ import {Id, IdOrNull, Ids} from './common.d';
  */
 export type Metric = number;
 
+/**
+ * The MetricCallback type describes a function that takes a Metric's Id and a
+ * callback to loop over each Row within it.
+ *
+ * A MetricCallback is provided when using the forEachMetric method, so that you
+ * can do something based on every Metric in the Metrics object. See that method
+ * for specific examples.
+ *
+ * @param metricId The Id of the Metric that the callback can operate on.
+ * @param metric The value of the Metric.
+ * @category Callback
+ */
+export type MetricCallback = (metricId: Id, metric?: Metric) => void;
+
 /**
  * The Aggregate type describes a custom function that takes an array or numbers
  * and returns an aggregate that is used as a Metric.
@@ -478,6 +492,64 @@ export interface Metrics {
    */
   getMetricIds(): Ids;
 
+  /**
+   * The forEachMetric method takes a function that it will then call for each
+   * Metric in the Metrics object.
+   *
+   * This method is useful for iterating over all the Metrics in a functional
+   * style. The `metricCallback` parameter is a MetricCallback function that
+   * will be called with the Id of each Metric and its value.
+   *
+   * @param metricCallback The function that should be called for every Metric.
+   * @example
+   * This example iterates over each Metric in a Metrics object.
+   *
+   * ```js
+   * const store = createStore().setTable('species', {
+   *   dog: {price: 5},
+   *   cat: {price: 4},
+   *   worm: {price: 1},
+   * });
+   * const metrics = createMetrics(store)
+   *   .setMetricDefinition('highestPrice', 'species', 'max', 'price')
+   *   .setMetricDefinition('lowestPrice', 'species', 'min', 'price');
+   *
+   * metrics.forEachMetric((metricId, metric) => {
+   *   console.log([metricId, metric]);
+   * });
+   * // -> ['highestPrice', 5]
+   * // -> ['lowestPrice', 1]
+   * ```
+   * @category Iterator
+   */
+  forEachMetric(metricCallback: MetricCallback): void;
+
+  /**
+   * The hasMetric method returns a boolean indicating whether a given Metric
+   * exists in the Metrics object, and has a value.
+   *
+   * @param metricId The Id of a possible Metric in the Metrics object.
+   * @returns Whether a Metric with that Id exists.
+   * @example
+   * This example shows two simple Metric existence checks.
+   *
+   * ```js
+   * const store = createStore();
+   * const metrics = createMetrics(store);
+   * metrics.setMetricDefinition('highestPrice', 'species', 'max', 'price');
+   *
+   * console.log(metrics.hasMetric('lowestPrice'));
+   * // -> false
+   * console.log(metrics.hasMetric('highestPrice'));
+   * // -> false
+   * store.setTable('species', {dog: {price: 5}, cat: {price: 4}});
+   * console.log(metrics.hasMetric('highestPrice'));
+   * // -> true
+   * ```
+   * @category Getter
+   */
+  hasMetric(metricId: Id): boolean;
+
   /**
    * The getTableId method returns the Id of the underlying Table that is
    * backing a Metric.

package/lib/debug/metrics.js

@@ -0,0 +1,401 @@
+const getTypeOf = (thing) => typeof thing;
+const EMPTY_STRING = '';
+const STRING = getTypeOf(EMPTY_STRING);
+const FUNCTION = getTypeOf(getTypeOf);
+const SUM = 'sum';
+const AVG = 'avg';
+const MIN = 'min';
+const MAX = 'max';
+
+const arrayForEach = (array, cb) => array.forEach(cb);
+const arraySum = (array) => arrayReduce(array, (i, j) => i + j, 0);
+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 mathMax = Math.max;
+const mathMin = Math.min;
+const isFiniteNumber = isFinite;
+const isUndefined = (thing) => thing == void 0;
+const ifNotUndefined = (value, then, otherwise) =>
+  isUndefined(value) ? otherwise?.() : then(value);
+const isString = (thing) => getTypeOf(thing) == STRING;
+const isFunction = (thing) => getTypeOf(thing) == FUNCTION;
+const getUndefined = () => void 0;
+
+const collSizeN = (collSizer) => (coll) =>
+  arrayReduce(collValues(coll), (total, coll2) => total + collSizer(coll2), 0);
+const collSize = (coll) => coll.size;
+const collSize2 = collSizeN(collSize);
+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 aggregators = mapNew([
+  [
+    AVG,
+    [
+      (numbers, length) => arraySum(numbers) / length,
+      (metric, add, length) => metric + (add - metric) / (length + 1),
+      (metric, remove, length) => metric + (metric - remove) / (length - 1),
+      (metric, add, remove, length) => metric + (add - remove) / length,
+    ],
+  ],
+  [
+    MAX,
+    [
+      (numbers) => mathMax(...numbers),
+      (metric, add) => mathMax(add, metric),
+      (metric, remove) => (remove == metric ? void 0 : metric),
+      (metric, add, remove) =>
+        remove == metric ? void 0 : mathMax(add, metric),
+    ],
+  ],
+  [
+    MIN,
+    [
+      (numbers) => mathMin(...numbers),
+      (metric, add) => mathMin(add, metric),
+      (metric, remove) => (remove == metric ? void 0 : metric),
+      (metric, add, remove) =>
+        remove == metric ? void 0 : mathMin(add, metric),
+    ],
+  ],
+  [
+    SUM,
+    [
+      (numbers) => arraySum(numbers),
+      (metric, add) => metric + add,
+      (metric, remove) => metric - remove,
+      (metric, add, remove) => metric - remove + add,
+    ],
+  ],
+]);
+const createMetrics = getCreateFunction((store) => {
+  const metricListeners = mapNew();
+  const [
+    getStore,
+    getMetricIds,
+    forEachMetric,
+    hasMetric,
+    getTableId,
+    getMetric,
+    setMetric,
+    setDefinition,
+    delDefinition,
+    destroy,
+  ] = getDefinableFunctions(store, getUndefined, (value) =>
+    isNaN(value) ||
+    isUndefined(value) ||
+    value === true ||
+    value === false ||
+    value === EMPTY_STRING
+      ? void 0
+      : value * 1,
+  );
+  const [addListener, callListeners, delListenerImpl] = getListenerFunctions(
+    () => metrics,
+  );
+  const setMetricDefinition = (
+    metricId,
+    tableId,
+    aggregate,
+    getNumber,
+    aggregateAdd,
+    aggregateRemove,
+    aggregateReplace,
+  ) => {
+    const metricAggregators = isFunction(aggregate)
+      ? [aggregate, aggregateAdd, aggregateRemove, aggregateReplace]
+      : mapGet(aggregators, aggregate) ?? mapGet(aggregators, SUM);
+    setDefinition(
+      metricId,
+      tableId,
+      (change, changedNumbers, _changedSortKeys, numbers, _sortKeys, force) => {
+        let newMetric = getMetric(metricId);
+        let length = collSize(numbers);
+        const [aggregate2, aggregateAdd2, aggregateRemove2, aggregateReplace2] =
+          metricAggregators;
+        force = force || isUndefined(newMetric);
+        collForEach(changedNumbers, ([oldNumber, newNumber]) => {
+          if (!force) {
+            newMetric = isUndefined(oldNumber)
+              ? aggregateAdd2?.(newMetric, newNumber, length++)
+              : isUndefined(newNumber)
+              ? aggregateRemove2?.(newMetric, oldNumber, length--)
+              : aggregateReplace2?.(newMetric, newNumber, oldNumber, length);
+          }
+          force = force || isUndefined(newMetric);
+        });
+        change();
+        if (collIsEmpty(numbers)) {
+          newMetric = void 0;
+        } else if (force) {
+          newMetric = aggregate2(collValues(numbers), collSize(numbers));
+        }
+        if (!isFiniteNumber(newMetric)) {
+          newMetric = void 0;
+        }
+        const oldMetric = getMetric(metricId);
+        if (newMetric != oldMetric) {
+          setMetric(metricId, newMetric);
+          callListeners(metricListeners, [metricId], newMetric, oldMetric);
+        }
+      },
+      getRowCellFunction(getNumber, 1),
+    );
+    return metrics;
+  };
+  const delMetricDefinition = (metricId) => {
+    delDefinition(metricId);
+    return metrics;
+  };
+  const addMetricListener = (metricId, listener) =>
+    addListener(listener, metricListeners, [metricId]);
+  const delListener = (listenerId) => {
+    delListenerImpl(listenerId);
+    return metrics;
+  };
+  const getListenerStats = () => ({metric: collSize2(metricListeners)});
+  const metrics = {
+    setMetricDefinition,
+    delMetricDefinition,
+    getStore,
+    getMetricIds,
+    forEachMetric,
+    hasMetric,
+    getTableId,
+    getMetric,
+    addMetricListener,
+    delListener,
+    destroy,
+    getListenerStats,
+  };
+  return objFreeze(metrics);
+});
+
+export {createMetrics};

package/lib/debug/persisters.js

@@ -0,0 +1,191 @@
+import {promises, watch} from 'fs';
+
+const UTF8 = 'utf8';
+
+const isUndefined = (thing) => thing == void 0;
+const ifNotUndefined = (value, then, otherwise) =>
+  isUndefined(value) ? otherwise?.() : then(value);
+
+const object = Object;
+const objFreeze = object.freeze;
+
+const createCustomPersister = (
+  store,
+  getPersisted,
+  setPersisted,
+  startListeningToPersisted,
+  stopListeningToPersisted,
+) => {
+  let tablesListenerId;
+  let loadSave = 0;
+  let loads = 0;
+  let saves = 0;
+  const persister = {
+    load: async (initialTables) => {
+      /* istanbul ignore else */
+      if (loadSave != 2) {
+        loadSave = 1;
+        {
+          loads++;
+        }
+        const body = await getPersisted();
+        if (!isUndefined(body) && body != '') {
+          store.setJson(body);
+        } else {
+          store.setTables(initialTables);
+        }
+        loadSave = 0;
+      }
+      return persister;
+    },
+    startAutoLoad: async (initialTables) => {
+      persister.stopAutoLoad();
+      await persister.load(initialTables);
+      startListeningToPersisted(persister.load);
+      return persister;
+    },
+    stopAutoLoad: () => {
+      stopListeningToPersisted();
+      return persister;
+    },
+    save: async () => {
+      /* istanbul ignore else */
+      if (loadSave != 1) {
+        loadSave = 2;
+        {
+          saves++;
+        }
+        await setPersisted(store.getJson());
+        loadSave = 0;
+      }
+      return persister;
+    },
+    startAutoSave: async () => {
+      await persister.stopAutoSave().save();
+      tablesListenerId = store.addTablesListener(() => persister.save());
+      return persister;
+    },
+    stopAutoSave: () => {
+      ifNotUndefined(tablesListenerId, store.delListener);
+      return persister;
+    },
+    getStore: () => store,
+    destroy: () => persister.stopAutoLoad().stopAutoSave(),
+    getStats: () => ({loads, saves}),
+  };
+  return objFreeze(persister);
+};
+
+const STORAGE = 'storage';
+const WINDOW = globalThis.window;
+const getStoragePersister = (store, storageName, storage) => {
+  let listener;
+  const getPersisted = async () => storage.getItem(storageName);
+  const setPersisted = async (json) => storage.setItem(storageName, json);
+  const startListeningToPersisted = (didChange) => {
+    listener = (event) => {
+      if (event.storageArea === storage && event.key === storageName) {
+        didChange();
+      }
+    };
+    WINDOW.addEventListener(STORAGE, listener);
+  };
+  const stopListeningToPersisted = () => {
+    WINDOW.removeEventListener(STORAGE, listener);
+    listener = void 0;
+  };
+  return createCustomPersister(
+    store,
+    getPersisted,
+    setPersisted,
+    startListeningToPersisted,
+    stopListeningToPersisted,
+  );
+};
+const createLocalPersister = (store, storageName) =>
+  getStoragePersister(store, storageName, localStorage);
+const createSessionPersister = (store, storageName) =>
+  getStoragePersister(store, storageName, sessionStorage);
+
+const createFilePersister = (store, filePath) => {
+  let watcher;
+  const getPersisted = async () => {
+    try {
+      return await promises.readFile(filePath, UTF8);
+    } catch {}
+  };
+  const setPersisted = async (json) => {
+    try {
+      await promises.writeFile(filePath, json, UTF8);
+    } catch {}
+  };
+  const startListeningToPersisted = (didChange) => {
+    watcher = watch(filePath, didChange);
+  };
+  const stopListeningToPersisted = () => {
+    watcher?.close();
+    watcher = void 0;
+  };
+  return createCustomPersister(
+    store,
+    getPersisted,
+    setPersisted,
+    startListeningToPersisted,
+    stopListeningToPersisted,
+  );
+};
+
+const getETag = (response) => response.headers.get('ETag');
+const createRemotePersister = (
+  store,
+  loadUrl,
+  saveUrl,
+  autoLoadIntervalSeconds,
+) => {
+  let interval;
+  let lastEtag;
+  const getPersisted = async () => {
+    const response = await fetch(loadUrl);
+    lastEtag = getETag(response);
+    return response.text();
+  };
+  const setPersisted = async (json) =>
+    await fetch(saveUrl, {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: json,
+    });
+  const startListeningToPersisted = (didChange) => {
+    interval = setInterval(async () => {
+      const response = await fetch(loadUrl, {method: 'HEAD'});
+      const currentEtag = getETag(response);
+      if (
+        !isUndefined(lastEtag) &&
+        !isUndefined(currentEtag) &&
+        currentEtag != lastEtag
+      ) {
+        lastEtag = currentEtag;
+        didChange();
+      }
+    }, autoLoadIntervalSeconds * 1e3);
+  };
+  const stopListeningToPersisted = () => {
+    ifNotUndefined(interval, clearInterval);
+    interval = void 0;
+  };
+  return createCustomPersister(
+    store,
+    getPersisted,
+    setPersisted,
+    startListeningToPersisted,
+    stopListeningToPersisted,
+  );
+};
+
+export {
+  createCustomPersister,
+  createFilePersister,
+  createLocalPersister,
+  createRemotePersister,
+  createSessionPersister,
+};