tinybase 2.0.0-beta.1 → 2.0.0-beta.2

package/lib/checkpoints.d.ts

@@ -93,12 +93,13 @@ export type CheckpointListener = (
  */
 export type CheckpointsListenerStats = {
   /**
-   * The number of CheckpointIdsListeners registered with the Checkpoints
-   * object.
+   * The number of CheckpointIdsListener functions registered with the
+   * Checkpoints object.
    */
   checkpointIds?: number;
   /**
-   * The number of CheckpointListeners registered with the Checkpoints object.
+   * The number of CheckpointListener functions registered with the Checkpoints
+   * object.
    */
   checkpoint?: number;
 };

package/lib/checkpoints.js

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

package/lib/common.js

@@ -1 +1 @@
-const o=(o,t)=>o<t?-1:1;export{o as defaultSorter};
+const o=(o,t)=>o<t?-1:1,t=o=>""+o;export{o as defaultSorter,t as id};

package/lib/debug/checkpoints.d.ts

@@ -93,12 +93,13 @@ export type CheckpointListener = (
  */
 export type CheckpointsListenerStats = {
   /**
-   * The number of CheckpointIdsListeners registered with the Checkpoints
-   * object.
+   * The number of CheckpointIdsListener functions registered with the
+   * Checkpoints object.
    */
   checkpointIds?: number;
   /**
-   * The number of CheckpointListeners registered with the Checkpoints object.
+   * The number of CheckpointListener functions registered with the Checkpoints
+   * object.
    */
   checkpoint?: number;
 };

package/lib/debug/checkpoints.js

@@ -32,7 +32,7 @@ const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
 const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    map.set(key, getDefaultValue());
+    mapSet(map, key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -72,32 +72,32 @@ const getCreateFunction = (getFunction) => {
 };
 
 const getWildcardedLeaves = (deepIdSet, path = [EMPTY_STRING]) => {
-  const sets = [];
-  const deep = (set, p) =>
+  const leaves = [];
+  const deep = (node, p) =>
     p == arrayLength(path)
-      ? arrayPush(sets, set)
-      : arrayForEach([path[p], null], (id) => deep(mapGet(set, id), p + 1));
+      ? arrayPush(leaves, node)
+      : path[p] === null
+      ? collForEach(node, (node2) => deep(node2, p + 1))
+      : arrayForEach([path[p], null], (id) => deep(mapGet(node, id), p + 1));
   deep(deepIdSet, 0);
-  return sets;
+  return leaves;
 };
 const getListenerFunctions = (getThing) => {
   let thing;
   let nextId = 0;
   const listenerPool = [];
   const allListeners = mapNew();
-  const addListener = (listener, idSetNode, idOrNulls) => {
+  const addListener = (listener, idSetNode, path) => {
     thing ??= getThing();
     const id = arrayPop(listenerPool) ?? EMPTY_STRING + nextId++;
-    mapSet(allListeners, id, [listener, idSetNode, idOrNulls]);
-    setAdd(visitTree(idSetNode, idOrNulls ?? [EMPTY_STRING], setNew), id);
+    mapSet(allListeners, id, [listener, idSetNode, path]);
+    setAdd(visitTree(idSetNode, path ?? [EMPTY_STRING], setNew), id);
     return id;
   };
   const callListeners = (idSetNode, ids, ...extraArgs) =>
     arrayForEach(getWildcardedLeaves(idSetNode, ids), (set) =>
       collForEach(set, (id) =>
-        ifNotUndefined(mapGet(allListeners, id), ([listener]) =>
-          listener(thing, ...(ids ?? []), ...extraArgs),
-        ),
+        mapGet(allListeners, id)[0](thing, ...(ids ?? []), ...extraArgs),
       ),
     );
   const delListener = (id) =>

package/lib/debug/common.js

@@ -1,3 +1,6 @@
+const EMPTY_STRING = '';
+
 const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
+const id = (key) => EMPTY_STRING + key;
 
-export {defaultSorter};
+export {defaultSorter, id};

package/lib/debug/indexes.d.ts

@@ -128,11 +128,13 @@ export type SliceRowIdsListener = (
  */
 export type IndexesListenerStats = {
   /**
-   * The number of SlideIdsListeners registered with the Indexes object.
+   * The number of SlideIdsListener functions registered with the Indexes
+   * object.
    */
   sliceIds?: number;
   /**
-   * The number of SliceRowIdsListeners registered with the Indexes object.
+   * The number of SliceRowIdsListener functions registered with the Indexes
+   * object.
    */
   sliceRowIds?: number;
 };

package/lib/debug/indexes.js

@@ -42,7 +42,7 @@ const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
 const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    map.set(key, getDefaultValue());
+    mapSet(map, key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -225,32 +225,32 @@ const getCreateFunction = (getFunction) => {
 const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
 
 const getWildcardedLeaves = (deepIdSet, path = [EMPTY_STRING]) => {
-  const sets = [];
-  const deep = (set, p) =>
+  const leaves = [];
+  const deep = (node, p) =>
     p == arrayLength(path)
-      ? arrayPush(sets, set)
-      : arrayForEach([path[p], null], (id) => deep(mapGet(set, id), p + 1));
+      ? arrayPush(leaves, node)
+      : path[p] === null
+      ? collForEach(node, (node2) => deep(node2, p + 1))
+      : arrayForEach([path[p], null], (id) => deep(mapGet(node, id), p + 1));
   deep(deepIdSet, 0);
-  return sets;
+  return leaves;
 };
 const getListenerFunctions = (getThing) => {
   let thing;
   let nextId = 0;
   const listenerPool = [];
   const allListeners = mapNew();
-  const addListener = (listener, idSetNode, idOrNulls) => {
+  const addListener = (listener, idSetNode, path) => {
     thing ??= getThing();
     const id = arrayPop(listenerPool) ?? EMPTY_STRING + nextId++;
-    mapSet(allListeners, id, [listener, idSetNode, idOrNulls]);
-    setAdd(visitTree(idSetNode, idOrNulls ?? [EMPTY_STRING], setNew), id);
+    mapSet(allListeners, id, [listener, idSetNode, path]);
+    setAdd(visitTree(idSetNode, path ?? [EMPTY_STRING], setNew), id);
     return id;
   };
   const callListeners = (idSetNode, ids, ...extraArgs) =>
     arrayForEach(getWildcardedLeaves(idSetNode, ids), (set) =>
       collForEach(set, (id) =>
-        ifNotUndefined(mapGet(allListeners, id), ([listener]) =>
-          listener(thing, ...(ids ?? []), ...extraArgs),
-        ),
+        mapGet(allListeners, id)[0](thing, ...(ids ?? []), ...extraArgs),
       ),
     );
   const delListener = (id) =>

package/lib/debug/metrics.d.ts

@@ -186,7 +186,7 @@ export type MetricListener = (
  */
 export type MetricsListenerStats = {
   /**
-   * The number of MetricListeners registered with the Metrics object.
+   * The number of MetricListener functions registered with the Metrics object.
    */
   metric?: number;
 };

package/lib/debug/metrics.js

@@ -46,7 +46,7 @@ const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
 const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    map.set(key, getDefaultValue());
+    mapSet(map, key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -296,32 +296,32 @@ const getCreateFunction = (getFunction) => {
 };
 
 const getWildcardedLeaves = (deepIdSet, path = [EMPTY_STRING]) => {
-  const sets = [];
-  const deep = (set, p) =>
+  const leaves = [];
+  const deep = (node, p) =>
     p == arrayLength(path)
-      ? arrayPush(sets, set)
-      : arrayForEach([path[p], null], (id) => deep(mapGet(set, id), p + 1));
+      ? arrayPush(leaves, node)
+      : path[p] === null
+      ? collForEach(node, (node2) => deep(node2, p + 1))
+      : arrayForEach([path[p], null], (id) => deep(mapGet(node, id), p + 1));
   deep(deepIdSet, 0);
-  return sets;
+  return leaves;
 };
 const getListenerFunctions = (getThing) => {
   let thing;
   let nextId = 0;
   const listenerPool = [];
   const allListeners = mapNew();
-  const addListener = (listener, idSetNode, idOrNulls) => {
+  const addListener = (listener, idSetNode, path) => {
     thing ??= getThing();
     const id = arrayPop(listenerPool) ?? EMPTY_STRING + nextId++;
-    mapSet(allListeners, id, [listener, idSetNode, idOrNulls]);
-    setAdd(visitTree(idSetNode, idOrNulls ?? [EMPTY_STRING], setNew), id);
+    mapSet(allListeners, id, [listener, idSetNode, path]);
+    setAdd(visitTree(idSetNode, path ?? [EMPTY_STRING], setNew), id);
     return id;
   };
   const callListeners = (idSetNode, ids, ...extraArgs) =>
     arrayForEach(getWildcardedLeaves(idSetNode, ids), (set) =>
       collForEach(set, (id) =>
-        ifNotUndefined(mapGet(allListeners, id), ([listener]) =>
-          listener(thing, ...(ids ?? []), ...extraArgs),
-        ),
+        mapGet(allListeners, id)[0](thing, ...(ids ?? []), ...extraArgs),
       ),
     );
   const delListener = (id) =>

package/lib/debug/persisters.d.ts

@@ -40,7 +40,13 @@ import {Callback} from './common.d';
  * @category Development
  */
 export type PersisterStats = {
+  /**
+   * The number of times data has been loaded.
+   */
   loads?: number;
+  /**
+   * The number of times data has been saved.
+   */
   saves?: number;
 };
 

package/lib/debug/queries.d.ts

@@ -194,6 +194,36 @@ export type ResultTableListener = (
  */
 export type ResultRowIdsListener = (queries: Queries, tableId: Id) => void;
 
+/**
+ * The ResultSortedRowIdsListener type describes a function that is used to
+ * listen to changes to the sorted Row Ids in a query's result Table.
+ *
+ * A ResultSortedRowIdsListener is provided when using the
+ * addResultSortedRowIdsListener method. See that method for specific examples.
+ *
+ * When called, a ResultSortedRowIdsListener is given a reference to the Queries
+ * object, the Id of the Table whose Row Ids changed (which is the same as the
+ * query Id), the Cell Id being used to sort them, and and whether descending or
+ * not. It also receives the sorted array of Ids itself, so that you can use
+ * them in the listener without the additional cost of an explicit call to
+ * getResultSortedRowIds.
+ *
+ * @param queries A reference to the Queries object that changed.
+ * @param tableId The Id of the Table that changed, which is also the query Id.
+ * @param cellId The Id of the Cell whose values were used for the sorting.
+ * @param descending Whether the sorting was in descending order.
+ * @param sortedRowIds The sorted Row Ids themselves.
+ * @category Listener
+ * @since v2.0.0-beta
+ */
+export type ResultSortedRowIdsListener = (
+  queries: Queries,
+  tableId: Id,
+  cellId: Id | undefined,
+  descending: boolean,
+  sortedRowIds: Ids,
+) => void;
+
 /**
  * The ResultRowListener type describes a function that is used to listen to
  * changes to a Row in a query's result Table.
@@ -290,23 +320,23 @@ export type ResultCellListener = (
  */
 export type QueriesListenerStats = {
   /**
-   * The number of ResultTableListeners registered with the Store.
+   * The number of ResultTableListener functions registered with the Store.
    */
   table?: number;
   /**
-   * The number of ResultRowIdsListeners registered with the Store.
+   * The number of ResultRowIdsListener functions registered with the Store.
    */
   rowIds?: number;
   /**
-   * The number of ResultRowListeners registered with the Store.
+   * The number of ResultRowListener functions registered with the Store.
    */
   row?: number;
   /**
-   * The number of ResultCellIdsListeners registered with the Store.
+   * The number of ResultCellIdsListener functions registered with the Store.
    */
   cellIds?: number;
   /**
-   * The number of ResultCellListeners registered with the Store.
+   * The number of ResultCellListener functions registered with the Store.
    */
   cell?: number;
 };
@@ -1949,6 +1979,60 @@ export interface Queries {
    */
   getResultRowIds(queryId: Id): Ids;
 
+  /**
+   * The getResultSortedRowIds method returns the Ids of every Row in the result
+   * Table of the given query, sorted according to the values in a specified
+   * Cell.
+   *
+   * This has the same behavior as a Store's getSortedRowIds method. For
+   * example, if the query Id is invalid, the method returns an empty array.
+   * Similarly, the sorting of the rows is alphanumeric, and you can indicate
+   * whether it should be in descending order.
+   *
+   * Note that every call to this method will perform the sorting afresh - there
+   * is no caching of the results - and so you are advised to memoize the
+   * results yourself, especially when the result Table is large. For a
+   * performant approach to tracking the sorted Row Ids when they change, use
+   * the addResultSortedRowIdsListener method.
+   *
+   * @param queryId The Id of a query.
+   * @param cellId The Id of the Cell whose values are used for the sorting, or
+   * `undefined` to by sort the Row Id itself.
+   * @param descending Whether the sorting should be in descending order.
+   * @returns An array of the sorted Ids of every Row in the result of the
+   * query.
+   * @example
+   * This example creates a Queries object, a single query definition, and then
+   * calls this method on it (as well as a non-existent definition) to get the
+   * result Row Ids.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   *
+   * const queries = createQueries(store).setQueryDefinition(
+   *   'dogColors',
+   *   'pets',
+   *   ({select, where}) => {
+   *     select('color');
+   *     where('species', 'dog');
+   *   },
+   * );
+   *
+   * console.log(queries.getResultSortedRowIds('dogColors', 'color'));
+   * // -> ['cujo', 'fido']
+   *
+   * console.log(queries.getResultSortedRowIds('catColors', 'color'));
+   * // -> []
+   * ```
+   * @category Result
+   * @since v2.0.0-beta
+   */
+  getResultSortedRowIds(queryId: Id, cellId?: Id, descending?: boolean): Ids;
+
   /**
    * The getResultRow method returns an object containing the entire data of a
    * single Row in the result Table of the given query.
@@ -2120,8 +2204,8 @@ export interface Queries {
   hasResultTable(queryId: Id): boolean;
 
   /**
-   * The hasResultRow method returns a boolean indicating whether a given
-   * result Row exists.
+   * The hasResultRow method returns a boolean indicating whether a given result
+   * Row exists.
    *
    * @param queryId The Id of a possible query.
    * @param rowId The Id of a possible Row.
@@ -2471,7 +2555,7 @@ export interface Queries {
    *
    * const listenerId = queries.addResultRowIdsListener(
    *   'dogColors',
-   *   (store, tableId) => {
+   *   (queries, tableId) => {
    *     console.log(`Row Ids for dogColors result table changed`);
    *     console.log(queries.getResultRowIds('dogColors'));
    *   },
@@ -2511,7 +2595,7 @@ export interface Queries {
    *
    * const listenerId = queries.addResultRowIdsListener(
    *   'dogColors',
-   *   (store, tableId) => {
+   *   (queries, tableId) => {
    *     console.log(`Row Ids for dogColors result table changed`);
    *     console.log(queries.getResultRowIds('dogColors'));
    *   },
@@ -2571,6 +2655,119 @@ export interface Queries {
     trackReorder?: boolean,
   ): Id;
 
+  /**
+   * The addResultSortedRowIdsListener method registers a listener function with
+   * the Queries object that will be called whenever sorted Row Ids in a result
+   * Table change.
+   *
+   * The provided listener is a ResultSortedRowIdsListener function, and will be
+   * called with a reference to the Queries object, the Id of the result Table
+   * whose Row Ids sorting changed (which is also the query Id), the Cell Id
+   * being used to sort them, and whether descending or not. It also receives
+   * the sorted array of Ids itself, so that you can use them in the listener
+   * without the additional cost of an explicit call to getResultSortedRowIds
+   *
+   * Such a listener is called when a Row is added or removed, but also when a
+   * value in the specified Cell (somewhere in the result Table) has changed
+   * enough to change the sorting of the Row Ids.
+   *
+   * Unlike most other listeners, you cannot provide wildcards (due to the cost
+   * of detecting changes to the sorting). You can only listen to a single
+   * specified result Table, sorted by a single specified Cell.
+   *
+   * @param queryId The Id of the query to listen to.
+   * @param cellId The Id of the Cell whose values are used for the sorting, or
+   * `undefined` to by sort the result Row Id itself.
+   * @param descending Whether the sorting should be in descending order.
+   * @param listener The function that will be called whenever the sorted Row
+   * Ids in the result Table change.
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @example
+   * This example registers a listener that responds to any change to the sorted
+   * Row Ids of a specific result Table.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   *
+   * const queries = createQueries(store).setQueryDefinition(
+   *   'dogColors',
+   *   'pets',
+   *   ({select, where}) => {
+   *     select('color');
+   *     where('species', 'dog');
+   *   },
+   * );
+   *
+   * const listenerId = queries.addResultSortedRowIdsListener(
+   *   'dogColors',
+   *   'color',
+   *   false,
+   *   (queries, tableId, cellId, descending, sortedRowIds) => {
+   *     console.log(`Sorted Row Ids for dogColors result table changed`);
+   *     console.log(sortedRowIds);
+   *     // ^ cheaper than calling getResultSortedRowIds again
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'rex', {species: 'dog', color: 'tan'});
+   * // -> 'Sorted Row Ids for dogColors result table changed'
+   * // -> ['cujo', 'fido', 'rex']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any change to the sorted
+   * Row Ids of a specific Table. The Row Ids are sorted by their own value,
+   * since the `cellId` parameter is explicitly undefined.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   *
+   * const queries = createQueries(store).setQueryDefinition(
+   *   'dogColors',
+   *   'pets',
+   *   ({select, where}) => {
+   *     select('color');
+   *     where('species', 'dog');
+   *   },
+   * );
+   * console.log(queries.getResultSortedRowIds('dogColors', undefined, false));
+   * // -> ['cujo', 'fido']
+   *
+   * const listenerId = queries.addResultSortedRowIdsListener(
+   *   'dogColors',
+   *   undefined,
+   *   false,
+   *   (queries, tableId, cellId, descending, sortedRowIds) => {
+   *     console.log(`Sorted Row Ids for dogColors result table changed`);
+   *     console.log(sortedRowIds);
+   *     // ^ cheaper than calling getSortedRowIds again
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'rex', {species: 'dog', color: 'tan'});
+   * // -> 'Sorted Row Ids for dogColors result table changed'
+   * // -> ['cujo', 'fido', 'rex']
+   *
+   * store.delListener(listenerId);
+   * ```
+   * @category Listener
+   */
+  addResultSortedRowIdsListener(
+    queryId: Id,
+    cellId: Id | undefined,
+    descending: boolean,
+    listener: ResultSortedRowIdsListener,
+  ): Id;
+
   /**
    * The addResultRowListener method registers a listener function with the
    * Queries object that will be called whenever data in a result Row changes.

package/lib/debug/queries.js

@@ -50,7 +50,7 @@ const mapSet = (map, key, value) =>
   isUndefined(value) ? (collDel(map, key), map) : map?.set(key, value);
 const mapEnsure = (map, key, getDefaultValue) => {
   if (!collHas(map, key)) {
-    map.set(key, getDefaultValue());
+    mapSet(map, key, getDefaultValue());
   }
   return mapGet(map, key);
 };
@@ -313,6 +313,7 @@ const objFreeze = object.freeze;
 const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
 
 const createQueries = getCreateFunction((store) => {
+  const createStore = store.createStore;
   const [
     getStore,
     getQueryIds,
@@ -328,9 +329,9 @@ const createQueries = getCreateFunction((store) => {
     addStoreListeners,
     delStoreListeners,
   ] = getDefinableFunctions(store, () => true, getUndefined);
-  const preStore1 = store.createStore();
-  const preStore2 = store.createStore();
-  const resultStore = store.createStore();
+  const preStore1 = createStore();
+  const preStore2 = createStore();
+  const resultStore = createStore();
   const preStoreListenerIds = mapNew();
   const addPreStoreListener = (preStore, queryId, ...listenerIds) =>
     arrayForEach(listenerIds, (listenerId) =>
@@ -343,10 +344,14 @@ const createQueries = getCreateFunction((store) => {
         listenerId,
       ),
     );
+  const cleanPreStores = (queryId) =>
+    arrayForEach([resultStore, preStore2, preStore1], (store2) =>
+      store2.delTable(queryId),
+    );
   const synchronizeTransactions = (queryId, fromStore, toStore) =>
-    addStoreListeners(
+    addPreStoreListener(
+      fromStore,
       queryId,
-      0,
       fromStore.addWillFinishTransactionListener(toStore.startTransaction),
       fromStore.addDidFinishTransactionListener(() =>
         toStore.finishTransaction(),
@@ -354,9 +359,7 @@ const createQueries = getCreateFunction((store) => {
     );
   const setQueryDefinition = (queryId, tableId, build) => {
     setDefinition(queryId, tableId);
-    preStore1.delTable(queryId);
-    preStore2.delTable(queryId);
-    resultStore.delTable(queryId);
+    cleanPreStores(queryId);
     let offsetLimit;
     const selectEntries = [];
     const joinEntries = [[null, [tableId, null, null, [], mapNew()]]];
@@ -791,11 +794,14 @@ const createQueries = getCreateFunction((store) => {
         preStore.delListener(listenerId),
       ),
     );
+    cleanPreStores(queryId);
     delDefinition(queryId);
     return queries;
   };
   const getResultTable = (queryId) => resultStore.getTable(queryId);
   const getResultRowIds = (queryId) => resultStore.getRowIds(queryId);
+  const getResultSortedRowIds = (queryId, cellId, descending) =>
+    resultStore.getSortedRowIds(queryId, cellId, descending);
   const getResultRow = (queryId, rowId) => resultStore.getRow(queryId, rowId);
   const getResultCellIds = (queryId, rowId) =>
     resultStore.getCellIds(queryId, rowId);
@@ -821,6 +827,18 @@ const createQueries = getCreateFunction((store) => {
       (_store, ...args) => listener(queries, ...args),
       trackReorder,
     );
+  const addResultSortedRowIdsListener = (
+    queryId,
+    cellId,
+    descending,
+    listener,
+  ) =>
+    resultStore.addSortedRowIdsListener(
+      queryId,
+      cellId,
+      descending,
+      (_store, ...args) => listener(queries, ...args),
+    );
   const addResultRowListener = (queryId, rowId, listener) =>
     resultStore.addRowListener(queryId, rowId, (_store, ...args) =>
       listener(queries, ...args),
@@ -856,6 +874,7 @@ const createQueries = getCreateFunction((store) => {
     getTableId,
     getResultTable,
     getResultRowIds,
+    getResultSortedRowIds,
     getResultRow,
     getResultCellIds,
     getResultCell,
@@ -867,6 +886,7 @@ const createQueries = getCreateFunction((store) => {
     forEachResultCell,
     addResultTableListener,
     addResultRowIdsListener,
+    addResultSortedRowIdsListener,
     addResultRowListener,
     addResultCellIdsListener,
     addResultCellListener,