tinybase 1.0.5 → 1.1.0

package/lib/checkpoints.js

@@ -1 +1 @@
-const e=(e,t)=>e.includes(t),t=(e,t)=>e.forEach(t),n=e=>e.length,s=e=>0==n(e),o=e=>e.slice(1),r=e=>null==e,c=(e,t,n)=>r(e)?n?.():t(e),l=(e,t)=>e?.has(t)??!1,i=e=>r(e)||0==(e=>e.size)(e),d=(e,t)=>e?.forEach(t),a=(e,t)=>e?.delete(t),p=e=>new Map(e),h=(e,t)=>e?.get(t),u=(e,t,n)=>r(n)?(a(e,t),e):e?.set(t,n),C=(e,t,n,s)=>(l(e,t)||(s?.(n),e.set(t,n)),h(e,t)),g=e=>new Set(e),k=(e,t,r)=>n(r)<2?((e,t)=>e?.add(t))(s(r)?e:C(e,r[0],g()),t):k(C(e,r[0],p()),t,o(r)),f=e=>{const n=(r,l,...i)=>c(r,(r=>s(i)?e(r,l):t([i[0],null],(e=>n(h(r,e),l,...o(i))))));return n},L=Object.freeze,v=(e=>{const t=new WeakMap;return n=>(t.has(n)||t.set(n,e(n)),t.get(n))})((o=>{let v,w,S,z=100,E=p(),I=1;const M=g(),b=p(),[j,x,y]=(e=>{let s,o=0;const l=[],i=p();return[(t,n,r=[])=>{s??=e();const c=l.pop()??""+o++;return u(i,c,[t,n,r]),k(n,c,r),c},(e,t=[],...n)=>f(d)(e,(e=>c(h(i,e),(([e])=>e(s,...t,...n)))),...t),e=>c(h(i,e),(([,t,s])=>(f(a)(t,e,...s),u(i,e),n(l)<1e3&&l.push(e),s)),(()=>[])),(e,o,l)=>c(h(i,e),(([e,,c])=>{const i=(...d)=>{const a=n(d);a==n(c)?e(s,...d,...l(d)):r(c[a])?t(o[a](...d),(e=>i(...d,e))):i(...d,c[a])};i()}))]})((()=>R)),B=p(),F=p(),O=[],T=[],W=(e,t)=>{I=0,o.transaction((()=>d(h(B,t),((t,n)=>d(t,((t,s)=>d(t,((t,c)=>r(t[e])?o.delCell(n,s,c,!0):o.setCell(n,s,c,t[e]))))))))),I=1},m=e=>{u(B,e),u(F,e),x(b,[e])},q=(e,s)=>t(((e,t)=>e.splice(0,t))(e,s??n(e)),m),A=()=>q(O,n(O)-z),D=o.addCellListener(null,null,null,((e,t,n,s,o,r)=>{if(I){c(v,(()=>{O.push(v),A(),q(T),v=void 0,S=1}));const e=C(E,t,p()),l=C(e,n,p()),d=C(l,s,[void 0,void 0],(e=>e[0]=r));d[1]=o,d[0]===d[1]&&i(u(l,s))&&i(u(e,n))&&i(u(E,t))&&(v=O.pop(),S=1),K()}})),G=(e="")=>(r(v)&&(v=""+w++,u(B,v,E),P(v,e),E=p(),S=1),v),H=()=>{s(O)||(T.unshift(G()),W(0,v),v=O.pop(),S=1)},J=()=>{s(T)||(O.push(v),v=T.shift(),W(1,v),S=1)},K=()=>{S&&(x(M),S=0)},N=e=>{const t=G(e);return K(),t},P=(e,t)=>(Q(e)&&h(F,e)!==t&&(u(F,e,t),x(b,[e])),R),Q=e=>l(B,e),R={setSize:e=>(z=e,A(),R),addCheckpoint:N,setCheckpoint:P,getStore:()=>o,getCheckpointIds:()=>[[...O],v,[...T]],forEachCheckpoint:e=>{return t=e,d(F,((e,n)=>t(n,e)));var t},hasCheckpoint:Q,getCheckpoint:e=>h(F,e),goBackward:()=>(H(),K(),R),goForward:()=>(J(),K(),R),goTo:t=>{const n=e(O,t)?H:e(T,t)?J:null;for(;!r(n)&&t!=v;)n();return K(),R},addCheckpointIdsListener:e=>j(e,M),addCheckpointListener:(e,t)=>j(t,b,[e]),delListener:e=>(y(e),R),clear:()=>(q(O),q(T),r(v)||m(v),v=void 0,w=0,N(),R),destroy:()=>{o.delListener(D)},getListenerStats:()=>({})};return L(R.clear())}));export{v as createCheckpoints};
+const e=(e,t)=>e.includes(t),t=(e,t)=>e.forEach(t),n=e=>e.length,s=e=>0==n(e),o=e=>e.slice(1),r=(e,t)=>e.push(t),c=e=>e.pop(),l=e=>null==e,i=(e,t,n)=>l(e)?n?.():t(e),d=(e,t)=>e?.has(t)??!1,a=e=>l(e)||0==(e=>e.size)(e),h=(e,t)=>e?.forEach(t),u=(e,t)=>e?.delete(t),p=e=>new Map(e),C=(e,t)=>e?.get(t),g=(e,t,n)=>l(n)?(u(e,t),e):e?.set(t,n),k=(e,t,n,s)=>(d(e,t)||(s?.(n),e.set(t,n)),C(e,t)),f=e=>new Set(e),L=(e,t,r)=>n(r)<2?((e,t)=>e?.add(t))(s(r)?e:k(e,r[0],f()),t):L(k(e,r[0],p()),t,o(r)),v=e=>{const n=(r,c,...l)=>i(r,(r=>s(l)?e(r,c):t([l[0],null],(e=>n(C(r,e),c,...o(l))))));return n},w=Object.freeze,S=(e=>{const t=new WeakMap;return n=>(t.has(n)||t.set(n,e(n)),t.get(n))})((o=>{let S,z,E,I=100,M=p(),b=1;const j=f(),x=p(),[y,B,F]=(e=>{let s,o=0;const d=[],a=p();return[(t,n,r=[])=>{s??=e();const l=c(d)??""+o++;return g(a,l,[t,n,r]),L(n,l,r),l},(e,t=[],...n)=>v(h)(e,(e=>i(C(a,e),(([e])=>e(s,...t,...n)))),...t),e=>i(C(a,e),(([,t,s])=>(v(u)(t,e,...s),g(a,e),n(d)<1e3&&r(d,e),s)),(()=>[])),(e,o,r)=>i(C(a,e),(([e,,c])=>{const i=(...d)=>{const a=n(d);a==n(c)?e(s,...d,...r(d)):l(c[a])?t(o[a](...d),(e=>i(...d,e))):i(...d,c[a])};i()}))]})((()=>V)),O=p(),T=p(),W=[],m=[],q=(e,t)=>{b=0,o.transaction((()=>h(C(O,t),((t,n)=>h(t,((t,s)=>h(t,((t,r)=>l(t[e])?o.delCell(n,s,r,!0):o.setCell(n,s,r,t[e]))))))))),b=1},A=e=>{g(O,e),g(T,e),B(x,[e])},D=(e,s)=>t(((e,t)=>e.splice(0,t))(e,s??n(e)),A),G=()=>D(W,n(W)-I),H=o.addCellListener(null,null,null,((e,t,n,s,o,l)=>{if(b){i(S,(()=>{r(W,S),G(),D(m),S=void 0,E=1}));const e=k(M,t,p()),d=k(e,n,p()),h=k(d,s,[void 0,void 0],(e=>e[0]=l));h[1]=o,h[0]===h[1]&&a(g(d,s))&&a(g(e,n))&&a(g(M,t))&&(S=c(W),E=1),P()}})),J=(e="")=>(l(S)&&(S=""+z++,g(O,S,M),R(S,e),M=p(),E=1),S),K=()=>{s(W)||(m.unshift(J()),q(0,S),S=c(W),E=1)},N=()=>{s(m)||(r(W,S),S=m.shift(),q(1,S),E=1)},P=()=>{E&&(B(j),E=0)},Q=e=>{const t=J(e);return P(),t},R=(e,t)=>(U(e)&&C(T,e)!==t&&(g(T,e,t),B(x,[e])),V),U=e=>d(O,e),V={setSize:e=>(I=e,G(),V),addCheckpoint:Q,setCheckpoint:R,getStore:()=>o,getCheckpointIds:()=>[[...W],S,[...m]],forEachCheckpoint:e=>{return t=e,h(T,((e,n)=>t(n,e)));var t},hasCheckpoint:U,getCheckpoint:e=>C(T,e),goBackward:()=>(K(),P(),V),goForward:()=>(N(),P(),V),goTo:t=>{const n=e(W,t)?K:e(m,t)?N:null;for(;!l(n)&&t!=S;)n();return P(),V},addCheckpointIdsListener:e=>y(e,j),addCheckpointListener:(e,t)=>y(t,x,[e]),delListener:e=>(F(e),V),clear:()=>(D(W),D(m),l(S)||A(S),S=void 0,z=0,Q(),V),destroy:()=>{o.delListener(H)},getListenerStats:()=>({})};return w(V.clear())}));export{S as createCheckpoints};

package/lib/debug/checkpoints.js

@@ -5,6 +5,8 @@ const arrayIsEmpty = (array) => arrayLength(array) == 0;
 const arrayReduce = (array, cb, initial) => array.reduce(cb, initial);
 const arrayFromSecond = (ids) => ids.slice(1);
 const arrayClear = (array, to) => array.splice(0, to);
+const arrayPush = (array, value) => array.push(value);
+const arrayPop = (array) => array.pop();
 
 const isUndefined = (thing) => thing == void 0;
 const ifNotUndefined = (value, then, otherwise) =>
@@ -76,7 +78,7 @@ const getListenerFunctions = (getThing) => {
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
     thing ??= getThing();
-    const id = listenerPool.pop() ?? '' + nextId++;
+    const id = arrayPop(listenerPool) ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);
     return id;
@@ -97,7 +99,7 @@ const getListenerFunctions = (getThing) => {
         forDeepSet(collDel)(deepSet, id, ...idOrNulls);
         mapSet(allListeners, id);
         if (arrayLength(listenerPool) < 1e3) {
-          listenerPool.push(id);
+          arrayPush(listenerPool, id);
         }
         return idOrNulls;
       },
@@ -173,7 +175,7 @@ const createCheckpoints = getCreateFunction((store) => {
     (_store, tableId, rowId, cellId, newCell, oldCell) => {
       if (listening) {
         ifNotUndefined(currentId, () => {
-          backwardIds.push(currentId);
+          arrayPush(backwardIds, currentId);
           trimBackwardsIds();
           clearCheckpointIds(forwardIds);
           currentId = void 0;
@@ -192,7 +194,7 @@ const createCheckpoints = getCreateFunction((store) => {
           if (collIsEmpty(mapSet(row, cellId))) {
             if (collIsEmpty(mapSet(table, rowId))) {
               if (collIsEmpty(mapSet(delta, tableId))) {
-                currentId = backwardIds.pop();
+                currentId = arrayPop(backwardIds);
                 checkpointsChanged = 1;
               }
             }
@@ -216,13 +218,13 @@ const createCheckpoints = getCreateFunction((store) => {
     if (!arrayIsEmpty(backwardIds)) {
       forwardIds.unshift(addCheckpointImpl());
       updateStore(0, currentId);
-      currentId = backwardIds.pop();
+      currentId = arrayPop(backwardIds);
       checkpointsChanged = 1;
     }
   };
   const goForwardImpl = () => {
     if (!arrayIsEmpty(forwardIds)) {
-      backwardIds.push(currentId);
+      arrayPush(backwardIds, currentId);
       currentId = forwardIds.shift();
       updateStore(1, currentId);
       checkpointsChanged = 1;

package/lib/debug/indexes.js

@@ -12,6 +12,8 @@ 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) =>
@@ -203,7 +205,7 @@ const getListenerFunctions = (getThing) => {
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
     thing ??= getThing();
-    const id = listenerPool.pop() ?? '' + nextId++;
+    const id = arrayPop(listenerPool) ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);
     return id;
@@ -224,7 +226,7 @@ const getListenerFunctions = (getThing) => {
         forDeepSet(collDel)(deepSet, id, ...idOrNulls);
         mapSet(allListeners, id);
         if (arrayLength(listenerPool) < 1e3) {
-          listenerPool.push(id);
+          arrayPush(listenerPool, id);
         }
         return idOrNulls;
       },

package/lib/debug/metrics.d.ts

@@ -37,7 +37,7 @@ export type Metric = number;
 export type MetricCallback = (metricId: Id, metric?: Metric) => void;
 
 /**
- * The Aggregate type describes a custom function that takes an array or numbers
+ * The Aggregate type describes a custom function that takes an array of numbers
  * and returns an aggregate that is used as a Metric.
  *
  * There are a number of common predefined aggregators, such as for counting,

package/lib/debug/metrics.js

@@ -13,6 +13,8 @@ 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;
@@ -206,7 +208,7 @@ const getListenerFunctions = (getThing) => {
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
     thing ??= getThing();
-    const id = listenerPool.pop() ?? '' + nextId++;
+    const id = arrayPop(listenerPool) ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);
     return id;
@@ -227,7 +229,7 @@ const getListenerFunctions = (getThing) => {
         forDeepSet(collDel)(deepSet, id, ...idOrNulls);
         mapSet(allListeners, id);
         if (arrayLength(listenerPool) < 1e3) {
-          listenerPool.push(id);
+          arrayPush(listenerPool, id);
         }
         return idOrNulls;
       },

package/lib/debug/relationships.js

@@ -7,6 +7,8 @@ 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) =>
@@ -196,7 +198,7 @@ const getListenerFunctions = (getThing) => {
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
     thing ??= getThing();
-    const id = listenerPool.pop() ?? '' + nextId++;
+    const id = arrayPop(listenerPool) ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);
     return id;
@@ -217,7 +219,7 @@ const getListenerFunctions = (getThing) => {
         forDeepSet(collDel)(deepSet, id, ...idOrNulls);
         mapSet(allListeners, id);
         if (arrayLength(listenerPool) < 1e3) {
-          listenerPool.push(id);
+          arrayPush(listenerPool, id);
         }
         return idOrNulls;
       },

package/lib/debug/store.d.ts

@@ -332,6 +332,35 @@ export type CellListener = (
   getCellChange: GetCellChange | undefined,
 ) => void;
 
+/**
+ * The InvalidCellListener type describes a function that is used to listen to
+ * attempts to set invalid data to a Cell.
+ *
+ * A InvalidCellListener is provided when using the addInvalidCellListener
+ * method. See that method for specific examples.
+ *
+ * When called, a InvalidCellListener is given a reference to the Store, the Id
+ * of the Table, the Id of the Row, and the Id of Cell that were being attempted
+ * to be changed. It is also given the invalid value of the Cell, which could
+ * have been of absolutely any type. Since there could have been multiple failed
+ * attempts to set the Cell within a single transaction, this is an array
+ * containing each attempt, chronologically.
+ *
+ * @param store A reference to the Store that was being changed.
+ * @param tableId The Id of the Table that was being changed.
+ * @param rowId The Id of the Row that was being changed.
+ * @param cellId The Id of the Cell that was being changed.
+ * @param invalidCells An array of the values of the Cell that were invalid.
+ * @category Listener
+ */
+export type InvalidCellListener = (
+  store: Store,
+  tableId: Id,
+  rowId: Id,
+  cellId: Id,
+  invalidCells: any[],
+) => void;
+
 /**
  * The GetCellChange type describes a function that returns information about
  * any Cell's changes during a transaction.
@@ -545,6 +574,9 @@ export type StoreListenerStats = {
  * unique Id. And the setPartialRow method lets you update multiple Cell values
  * in a Row without affecting the others.
  *
+ * You can listen to attempts to write invalid data to a Cell with the
+ * addInvalidCellListener method.
+ *
  * The transaction method is used to wrap multiple changes to the Store so that
  * the relevant listeners only fire once.
  *
@@ -2371,6 +2403,235 @@ export interface Store {
     mutator?: boolean,
   ): Id;
 
+  /**
+   * The addInvalidCellListener method registers a listener function with the
+   * Store that will be called whenever invalid data was attempted to be written
+   * to a Cell.
+   *
+   * You can either listen to a single Cell (by specifying the Table Id, Row Id,
+   * and Cell Id as the method's first three parameters) or invalid attempts to
+   * change any Cell (by providing `null` wildcards).
+   *
+   * All, some, or none of the `tableId`, `rowId`, and `cellId` parameters can
+   * be wildcarded with `null`. You can listen to a specific Cell in a specific
+   * Row in a specific Table, any Cell in any Row in any Table, for example - or
+   * every other combination of wildcards.
+   *
+   * The provided listener is an InvalidCellListener function, and will be
+   * called with a reference to the Store, the Id of the Table, the Id of the
+   * Row, and the Id of Cell that were being attempted to be changed. It is also
+   * given the invalid value of the Cell, which could have been of absolutely
+   * any type. Since there could have been multiple failed attempts to set the
+   * Cell within a single transaction, this is an array containing each attempt,
+   * chronologically.
+   *
+   * Use the optional mutator parameter to indicate that there is code in the
+   * listener that will mutate Store data. If set to `false` (or omitted), such
+   * mutations will be silently ignored. All relevant mutator listeners (with
+   * this flag set to `true`) are called _before_ any non-mutator listeners
+   * (since the latter may become relevant due to changes made in the former).
+   * The changes made by mutator listeners do not fire other mutating listeners,
+   * though they will fire non-mutator listeners.
+   *
+   * Special note should be made for how the listener will be called when a
+   * Schema is present. The listener will be called:
+   *
+   * - if a Table is being updated that is not specified in the Schema
+   * - if a Cell is of the wrong type specified in the Schema
+   * - if a Cell is omitted and is not defaulted in the Schema
+   * - if an empty Row is provided and there are no Cell defaults in the Schema
+   *
+   * The listener will not be called if Cell that is defaulted in the Schema is
+   * not provided, as long as all of the Cells that are _not_ defaulted _are_
+   * provided.
+   *
+   * To help understand all of these schema-based conditions, please see the
+   * Schema example below.
+   *
+   * @param tableId The Id of the Table to listen to, or `null` as a wildcard.
+   * @param rowId The Id of the Row to listen to, or `null` as a wildcard.
+   * @param cellId The Id of the Cell to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever an attempt to
+   * write invalid data to the matching Cell was made.
+   * @param mutator An optional boolean that indicates that the listener mutates
+   * Store data.
+   * @returns A unique Id for the listener that can later be used to call it
+   * explicitly, or to remove it.
+   * @example
+   * This example registers a listener that responds to any invalid changes to a
+   * specific Cell.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addInvalidCellListener(
+   *   'pets',
+   *   'fido',
+   *   'color',
+   *   (store, tableId, rowId, cellId, invalidCells) => {
+   *     console.log('Invalid color cell in fido row in pets table');
+   *     console.log(invalidCells);
+   *   },
+   * );
+   *
+   * store.setCell('pets', 'fido', 'color', {r: '96', g: '4B', b: '00'});
+   * // -> 'Invalid color cell in fido row in pets table'
+   * // -> [{r: '96', g: '4B', b: '00'}]
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any invalid changes to
+   * any Cell - in a Store _without_ a Schema. Note also how it then responds to
+   * cases where an empty or invalid Row objects, or Table objects, or Tables
+   * objects are provided.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addInvalidCellListener(
+   *   null,
+   *   null,
+   *   null,
+   *   (store, tableId, rowId, cellId) => {
+   *     console.log(
+   *       `Invalid ${cellId} cell in ${rowId} row in ${tableId} table`,
+   *     );
+   *   },
+   * );
+   *
+   * store.setCell('pets', 'fido', 'color', {r: '96', g: '4B', b: '00'});
+   * // -> 'Invalid color cell in fido row in pets table'
+   * store.setTable('sales', {fido: {date: new Date()}});
+   * // -> 'Invalid date cell in fido row in sales table'
+   *
+   * store.setRow('pets', 'felix', {});
+   * // -> 'Invalid undefined cell in felix row in pets table'
+   *
+   * store.setRow('filter', 'name', /[a-z]?/);
+   * // -> 'Invalid undefined cell in name row in filter table'
+   *
+   * store.setRow('sales', '2021', {forecast: undefined});
+   * // -> 'Invalid forecast cell in 2021 row in sales table'
+   *
+   * store.addRow('filter', /[0-9]?/);
+   * // -> 'Invalid undefined cell in undefined row in filter table'
+   *
+   * store.setTable('raw', {});
+   * // -> 'Invalid undefined cell in undefined row in raw table'
+   *
+   * store.setTable('raw', ['row1', 'row2']);
+   * // -> 'Invalid undefined cell in undefined row in raw table'
+   *
+   * store.setTables(['table1', 'table2']);
+   * // -> 'Invalid undefined cell in undefined row in undefined table'
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any invalid changes to
+   * any Cell - in a Store _with_ a Schema. Note how it responds to cases where
+   * missing parameters are provided for optional, and defaulted Cell values in
+   * a Row.
+   *
+   * ```js
+   * const store = createStore().setSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     color: {type: 'string', default: 'unknown'},
+   *   },
+   * });
+   *
+   * const listenerId = store.addInvalidCellListener(
+   *   null,
+   *   null,
+   *   null,
+   *   (store, tableId, rowId, cellId) => {
+   *     console.log(
+   *       `Invalid ${cellId} cell in ${rowId} row in ${tableId} table`,
+   *     );
+   *   },
+   * );
+   *
+   * store.setRow('sales', 'fido', {price: 5});
+   * // -> 'Invalid price cell in fido row in sales table'
+   * // The listener is called, because the sales Table is not in the schema
+   *
+   * store.setRow('pets', 'felix', {species: true});
+   * // -> 'Invalid species cell in felix row in pets table'
+   * // The listener is called, because species is invalid...
+   * console.log(store.getRow('pets', 'felix'));
+   * // -> {color: 'unknown'}
+   * // ...even though a Row was set with the default value
+   *
+   * store.setRow('pets', 'fido', {color: 'brown'});
+   * // -> 'Invalid species cell in fido row in pets table'
+   * // The listener is called, because species is missing and not defaulted...
+   * console.log(store.getRow('pets', 'fido'));
+   * // -> {color: 'brown'}
+   * // ...even though a Row was set
+   *
+   * store.setRow('pets', 'rex', {species: 'dog'});
+   * console.log(store.getRow('pets', 'rex'));
+   * // -> {species: 'dog', color: 'unknown'}
+   * // The listener is not called, because color is defaulted
+   *
+   * store.delTables().setSchema({
+   *   pets: {
+   *     species: {type: 'string'},
+   *     color: {type: 'string'},
+   *   },
+   * });
+   *
+   * store.setRow('pets', 'cujo', {});
+   * // -> 'Invalid species cell in cujo row in pets table'
+   * // -> 'Invalid color cell in cujo row in pets table'
+   * // -> 'Invalid undefined cell in cujo row in pets table'
+   * // The listener is called multiple times, because neither Cell is defaulted
+   * // and the Row as a whole is empty
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any changes to a
+   * specific Cell, and which also mutates the Store itself.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog', color: 'brown'}},
+   * });
+   * const listenerId = store.addInvalidCellListener(
+   *   'pets',
+   *   'fido',
+   *   'color',
+   *   (store, tableId, rowId, cellId, invalidCells) =>
+   *     store.setCell(
+   *       'meta',
+   *       'invalid_updates',
+   *       `${tableId}_${rowId}_${cellId}`,
+   *       JSON.stringify(invalidCells[0]),
+   *     ),
+   *   true,
+   * );
+   *
+   * store.setCell('pets', 'fido', 'color', {r: '96', g: '4B', b: '00'});
+   * console.log(store.getRow('meta', 'invalid_updates'));
+   * // -> {'pets_fido_color': '{"r":"96","g":"4B","b":"00"}'}
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   */
+  addInvalidCellListener(
+    tableId: IdOrNull,
+    rowId: IdOrNull,
+    cellId: IdOrNull,
+    listener: InvalidCellListener,
+    mutator?: boolean,
+  ): Id;
+
   /**
    * The callListener method provides a way for you to manually provoke a
    * listener to be called, even if the underlying data hasn't changed.