tinybase 0.9.0 → 0.9.4

package/lib/checkpoints.d.ts

@@ -43,6 +43,7 @@ export type CheckpointIds = [Ids, Id | undefined, Ids];
  * When called, a CheckpointIdsListener is given a reference to the Checkpoints
  * object.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
  * @category Listener
  */
 export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
@@ -57,6 +58,8 @@ export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
  * When called, a CheckpointListener is given a reference to the Checkpoints
  * object, and the Id of the checkpoint whose label changed.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
+ * @param checkpointId The Id of the checkpoint that changed.
  * @category Listener
  */
 export type CheckpointListener = (
@@ -75,7 +78,14 @@ export type CheckpointListener = (
  * @category Development
  */
 export type CheckpointsListenerStats = {
+  /**
+   * The number of CheckpointIdsListeners registered with the Checkpoints
+   * object.
+   */
   checkpointIds?: number;
+  /**
+   * The number of CheckpointListeners registered with the Checkpoints object.
+   */
   checkpoint?: number;
 };
 
@@ -101,7 +111,7 @@ export type CheckpointsListenerStats = {
  * to adding a checkpoint, getting the list of available checkpoints, and then
  * registering and removing a listener for them.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTables({pets: {fido: {sold: false}}});
  *
  * const checkpoints = createCheckpoints(store);
@@ -132,6 +142,7 @@ export type CheckpointsListenerStats = {
  * checkpoints.delListener(listenerId);
  * checkpoints.destroy();
  * ```
+ * @category Checkpoints
  */
 export interface Checkpoints {
   /**
@@ -151,7 +162,7 @@ export interface Checkpoints {
    * of the Checkpoints object dramatically and then creates more than that
    * number of checkpoints to demonstrate the oldest being pruned.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {views: 0}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -196,7 +207,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and adds two
    * checkpoints, one with a label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -245,7 +256,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets two
    * checkpoints, one with a label, which are both then re-labelled.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -288,7 +299,7 @@ export interface Checkpoints {
    * and then gets its reference in order to update its data and set a
    * checkpoint.
    *
-   * ```tsx
+   * ```js
    * const checkpoints = createCheckpoints(createStore());
    * checkpoints.getStore().setCell('pets', 'fido', 'species', 'dog');
    * checkpoints.addCheckpoint();
@@ -315,7 +326,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and then gets the
    * Ids of the checkpoints as it sets them and moves around the stack.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -354,7 +365,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets a
    * checkpoint with a label, before retrieving it again.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -370,7 +381,7 @@ export interface Checkpoints {
    * checkpoint without a label, setting it subsequently. A non-existent
    * checkpoint return an `undefined` label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -405,7 +416,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, and then registers a
    * listener that responds to any changes to the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -463,7 +474,7 @@ export interface Checkpoints {
    * listener that responds to any changes to a specific checkpoint label,
    * including when the checkpoint no longer exists.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -516,7 +527,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, registers a listener,
    * and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -554,7 +565,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, makes a change and then
    * goes backward to the state of the Store before the change.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -572,6 +583,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [[], '0', ['1']]
    * ```
+   * @category Movement
    */
   goBackward(): Checkpoints;
 
@@ -592,7 +604,7 @@ export interface Checkpoints {
    * goes backward to the state of the Store before the change. It then goes
    * forward again to restore the state with the changes.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -622,7 +634,7 @@ export interface Checkpoints {
    * change, the redo stack disappears, and then the attempt to forward again
    * has no effect.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -651,6 +663,7 @@ export interface Checkpoints {
    * // -> [['0'], undefined, []]
    * // The original change cannot be redone.
    * ```
+   * @category Movement
    */
   goForward(): Checkpoints;
 
@@ -668,7 +681,7 @@ export interface Checkpoints {
    * then goes forward again one change, also using the goTo method. Finally it
    * tries to go to a checkpoint that does not exist.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -700,6 +713,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [['0'], '1', ['2']]
    * ```
+   * @category Movement
    */
   goTo(checkpointId: Id): Checkpoints;
 
@@ -724,7 +738,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, adds a listener, makes
    * a change and then clears the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -773,7 +787,7 @@ export interface Checkpoints {
    * CellListener with the underlying Store), and then destroys it again,
    * removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -807,7 +821,7 @@ export interface Checkpoints {
    * @example
    * This example gets the listener statistics of a Checkpoints object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const checkpoints = createCheckpoints(store);
    * checkpoints.addCheckpointIdsListener(() => {
@@ -840,7 +854,7 @@ export interface Checkpoints {
  * @example
  * This example creates a Checkpoints object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints = createCheckpoints(store);
  * console.log(checkpoints.getCheckpointIds());
@@ -850,12 +864,13 @@ export interface Checkpoints {
  * This example creates a Checkpoints object, and calls the method a second
  * time for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints1 = createCheckpoints(store);
  * const checkpoints2 = createCheckpoints(store);
  * console.log(checkpoints1 === checkpoints2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createCheckpoints(store: Store): Checkpoints;

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

package/lib/common.d.ts

@@ -57,3 +57,59 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
  * @category Callback
  */
 export type Callback = () => void;
+
+/**
+ * The SortKey type represents a value that can be used by a sort function.
+ *
+ * @category Parameter
+ */
+export type SortKey = string | number | boolean;
+
+/**
+ * The defaultSorter function is provided as a convenience to sort keys
+ * alphanumerically, and can be provided to the `sliceIdSorter` and
+ * `rowIdSorter` parameters of the setIndexDefinition method in the indexes
+ * module, for example.
+ *
+ * @param sortKey1 The first item of the pair to compare.
+ * @param sortKey2 The second item of the pair to compare.
+ * @returns A number indicating how to sort the pair.
+ * @example
+ * This example creates an Indexes object.
+ *
+ * ```js
+ * const store = createStore();
+ * const indexes = createIndexes(store);
+ * console.log(indexes.getIndexIds());
+ * // -> []
+ * ```
+ * @example
+ * This example creates a Store, creates an Indexes object, and defines an
+ * Index based on the first letter of the pets' names. The Slice Ids (and Row
+ * Ids within them) are alphabetically sorted using the defaultSorter function.
+ *
+ * ```js
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ *
+ * const indexes = createIndexes(store);
+ * indexes.setIndexDefinition(
+ *   'byFirst', //              indexId
+ *   'pets', //                 tableId
+ *   (_, rowId) => rowId[0], // each Row's Slice Id
+ *   (_, rowId) => rowId, //    each Row's sort key
+ *   defaultSorter, //          sort Slice Ids
+ *   defaultSorter, //          sort Row Ids by sort key
+ * );
+ *
+ * console.log(indexes.getSliceIds('byFirst'));
+ * // -> ['c', 'f']
+ * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+ * // -> ['felix', 'fido']
+ * ```
+ * @category Convenience
+ */
+export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/common.js

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

package/lib/debug/checkpoints.d.ts

@@ -43,6 +43,7 @@ export type CheckpointIds = [Ids, Id | undefined, Ids];
  * When called, a CheckpointIdsListener is given a reference to the Checkpoints
  * object.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
  * @category Listener
  */
 export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
@@ -57,6 +58,8 @@ export type CheckpointIdsListener = (checkpoints: Checkpoints) => void;
  * When called, a CheckpointListener is given a reference to the Checkpoints
  * object, and the Id of the checkpoint whose label changed.
  *
+ * @param checkpoints A reference to the Checkpoints object that changed.
+ * @param checkpointId The Id of the checkpoint that changed.
  * @category Listener
  */
 export type CheckpointListener = (
@@ -75,7 +78,14 @@ export type CheckpointListener = (
  * @category Development
  */
 export type CheckpointsListenerStats = {
+  /**
+   * The number of CheckpointIdsListeners registered with the Checkpoints
+   * object.
+   */
   checkpointIds?: number;
+  /**
+   * The number of CheckpointListeners registered with the Checkpoints object.
+   */
   checkpoint?: number;
 };
 
@@ -101,7 +111,7 @@ export type CheckpointsListenerStats = {
  * to adding a checkpoint, getting the list of available checkpoints, and then
  * registering and removing a listener for them.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTables({pets: {fido: {sold: false}}});
  *
  * const checkpoints = createCheckpoints(store);
@@ -132,6 +142,7 @@ export type CheckpointsListenerStats = {
  * checkpoints.delListener(listenerId);
  * checkpoints.destroy();
  * ```
+ * @category Checkpoints
  */
 export interface Checkpoints {
   /**
@@ -151,7 +162,7 @@ export interface Checkpoints {
    * of the Checkpoints object dramatically and then creates more than that
    * number of checkpoints to demonstrate the oldest being pruned.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {views: 0}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -196,7 +207,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and adds two
    * checkpoints, one with a label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -245,7 +256,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets two
    * checkpoints, one with a label, which are both then re-labelled.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -288,7 +299,7 @@ export interface Checkpoints {
    * and then gets its reference in order to update its data and set a
    * checkpoint.
    *
-   * ```tsx
+   * ```js
    * const checkpoints = createCheckpoints(createStore());
    * checkpoints.getStore().setCell('pets', 'fido', 'species', 'dog');
    * checkpoints.addCheckpoint();
@@ -315,7 +326,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and then gets the
    * Ids of the checkpoints as it sets them and moves around the stack.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -354,7 +365,7 @@ export interface Checkpoints {
    * This example creates a Store, adds a Checkpoints object, and sets a
    * checkpoint with a label, before retrieving it again.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -370,7 +381,7 @@ export interface Checkpoints {
    * checkpoint without a label, setting it subsequently. A non-existent
    * checkpoint return an `undefined` label.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -405,7 +416,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, and then registers a
    * listener that responds to any changes to the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -463,7 +474,7 @@ export interface Checkpoints {
    * listener that responds to any changes to a specific checkpoint label,
    * including when the checkpoint no longer exists.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -516,7 +527,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, registers a listener,
    * and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -554,7 +565,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, makes a change and then
    * goes backward to the state of the Store before the change.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -572,6 +583,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [[], '0', ['1']]
    * ```
+   * @category Movement
    */
   goBackward(): Checkpoints;
 
@@ -592,7 +604,7 @@ export interface Checkpoints {
    * goes backward to the state of the Store before the change. It then goes
    * forward again to restore the state with the changes.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -622,7 +634,7 @@ export interface Checkpoints {
    * change, the redo stack disappears, and then the attempt to forward again
    * has no effect.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -651,6 +663,7 @@ export interface Checkpoints {
    * // -> [['0'], undefined, []]
    * // The original change cannot be redone.
    * ```
+   * @category Movement
    */
   goForward(): Checkpoints;
 
@@ -668,7 +681,7 @@ export interface Checkpoints {
    * then goes forward again one change, also using the goTo method. Finally it
    * tries to go to a checkpoint that does not exist.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -700,6 +713,7 @@ export interface Checkpoints {
    * console.log(checkpoints.getCheckpointIds());
    * // -> [['0'], '1', ['2']]
    * ```
+   * @category Movement
    */
   goTo(checkpointId: Id): Checkpoints;
 
@@ -724,7 +738,7 @@ export interface Checkpoints {
    * This example creates a Store, a Checkpoints object, adds a listener, makes
    * a change and then clears the checkpoints.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -773,7 +787,7 @@ export interface Checkpoints {
    * CellListener with the underlying Store), and then destroys it again,
    * removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {sold: false}}});
    *
    * const checkpoints = createCheckpoints(store);
@@ -807,7 +821,7 @@ export interface Checkpoints {
    * @example
    * This example gets the listener statistics of a Checkpoints object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const checkpoints = createCheckpoints(store);
    * checkpoints.addCheckpointIdsListener(() => {
@@ -840,7 +854,7 @@ export interface Checkpoints {
  * @example
  * This example creates a Checkpoints object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints = createCheckpoints(store);
  * console.log(checkpoints.getCheckpointIds());
@@ -850,12 +864,13 @@ export interface Checkpoints {
  * This example creates a Checkpoints object, and calls the method a second
  * time for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const checkpoints1 = createCheckpoints(store);
  * const checkpoints2 = createCheckpoints(store);
  * console.log(checkpoints1 === checkpoints2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createCheckpoints(store: Store): Checkpoints;

package/lib/debug/checkpoints.js

@@ -73,7 +73,7 @@ const getListenerFunctions = (getThing) => {
   const listenerPool = [];
   const allListeners = mapNew();
   const addListener = (listener, deepSet, idOrNulls = []) => {
-    thing ?? (thing = getThing());
+    thing ??= getThing();
     const id = listenerPool.pop() ?? '' + nextId++;
     mapSet(allListeners, id, [listener, deepSet, idOrNulls]);
     addDeepSet(deepSet, id, idOrNulls);

package/lib/debug/common.d.ts

@@ -57,3 +57,59 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
  * @category Callback
  */
 export type Callback = () => void;
+
+/**
+ * The SortKey type represents a value that can be used by a sort function.
+ *
+ * @category Parameter
+ */
+export type SortKey = string | number | boolean;
+
+/**
+ * The defaultSorter function is provided as a convenience to sort keys
+ * alphanumerically, and can be provided to the `sliceIdSorter` and
+ * `rowIdSorter` parameters of the setIndexDefinition method in the indexes
+ * module, for example.
+ *
+ * @param sortKey1 The first item of the pair to compare.
+ * @param sortKey2 The second item of the pair to compare.
+ * @returns A number indicating how to sort the pair.
+ * @example
+ * This example creates an Indexes object.
+ *
+ * ```js
+ * const store = createStore();
+ * const indexes = createIndexes(store);
+ * console.log(indexes.getIndexIds());
+ * // -> []
+ * ```
+ * @example
+ * This example creates a Store, creates an Indexes object, and defines an
+ * Index based on the first letter of the pets' names. The Slice Ids (and Row
+ * Ids within them) are alphabetically sorted using the defaultSorter function.
+ *
+ * ```js
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ *
+ * const indexes = createIndexes(store);
+ * indexes.setIndexDefinition(
+ *   'byFirst', //              indexId
+ *   'pets', //                 tableId
+ *   (_, rowId) => rowId[0], // each Row's Slice Id
+ *   (_, rowId) => rowId, //    each Row's sort key
+ *   defaultSorter, //          sort Slice Ids
+ *   defaultSorter, //          sort Row Ids by sort key
+ * );
+ *
+ * console.log(indexes.getSliceIds('byFirst'));
+ * // -> ['c', 'f']
+ * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+ * // -> ['felix', 'fido']
+ * ```
+ * @category Convenience
+ */
+export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/debug/common.js

@@ -0,0 +1,3 @@
+const defaultSorter = (sortKey1, sortKey2) => (sortKey1 < sortKey2 ? -1 : 1);
+
+export {defaultSorter};