tinybase 0.9.2 → 1.0.1

package/lib/debug/ui-react.js

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, {useContext as useContext$1} from 'react';
 
 const getTypeOf = (thing) => typeof thing;
 const EMPTY_STRING = '';
@@ -48,8 +48,11 @@ const useCheckpointsOrCheckpointsId = (checkpointsOrCheckpointsId) =>
   useThingOrThingId(checkpointsOrCheckpointsId, 8);
 
 const {useCallback, useEffect, useMemo: useMemo$1, useState} = React;
-const useCreate = (store, create, createDeps = []) =>
-  useMemo$1(() => create(store), [store, ...createDeps]);
+const useCreate = (store, create, createDeps = []) => {
+  const thing = useMemo$1(() => create(store), [store, ...createDeps]);
+  useEffect(() => () => thing.destroy(), [thing]);
+  return thing;
+};
 const useListenable = (listenable, thing, defaulted, ...args) => {
   const getListenable = thing?.['get' + listenable] ?? (() => defaulted);
   const immediateListenable = getListenable(...args);
@@ -654,6 +657,9 @@ const useCreatePersister = (
       setDone(1);
       return;
     })();
+    return () => {
+      persister.destroy();
+    };
   }, [persister, ...thenDeps]);
   return persister;
 };
@@ -735,22 +741,23 @@ const Provider = ({
   checkpoints,
   checkpointsById,
   children,
-}) =>
-  /* @__PURE__ */ createElement(
+}) => {
+  const thingsOrThingsId = useContext$1(Context);
+  return /* @__PURE__ */ createElement(
     Context.Provider,
     {
       value: useMemo(
         () => [
-          store,
-          storesById,
-          metrics,
-          metricsById,
-          indexes,
-          indexesById,
-          relationships,
-          relationshipsById,
-          checkpoints,
-          checkpointsById,
+          store ?? thingsOrThingsId[0],
+          {...thingsOrThingsId[1], ...storesById},
+          metrics ?? thingsOrThingsId[2],
+          {...thingsOrThingsId[3], ...metricsById},
+          indexes ?? thingsOrThingsId[4],
+          {...thingsOrThingsId[5], ...indexesById},
+          relationships ?? thingsOrThingsId[6],
+          {...thingsOrThingsId[7], ...relationshipsById},
+          checkpoints ?? thingsOrThingsId[8],
+          {...thingsOrThingsId[9], ...checkpointsById},
         ],
         [
           store,
@@ -763,11 +770,13 @@ const Provider = ({
           relationshipsById,
           checkpoints,
           checkpointsById,
+          thingsOrThingsId,
         ],
       ),
     },
     children,
   );
+};
 const wrap = (children, separator, encloseWithId, id) => {
   const separatedChildren =
     isUndefined(separator) || !Array.isArray(children)

package/lib/indexes.d.ts

@@ -3,8 +3,8 @@
  * and track indexes of the data in Store objects.
  *
  * The main entry point to this module is the createIndexes function, which
- * returns a new Indexes object. From there, you can create new index
- * definitions, access the contents of those indexes directly, and register
+ * returns a new Indexes object. From there, you can create new Index
+ * definitions, access the contents of those Indexes directly, and register
  * listeners for when they change.
  *
  * @packageDocumentation
@@ -12,7 +12,7 @@
  */
 
 import {GetCell, Store} from './store.d';
-import {Id, IdOrNull, Ids} from './common.d';
+import {Id, IdOrNull, Ids, SortKey} from './common.d';
 
 /**
  * The Index type represents the concept of a map of Slice objects, keyed by Id.
@@ -43,13 +43,6 @@ export type Index = {[sliceId: Id]: Slice};
  */
 export type Slice = Ids;
 
-/**
- * The SortKey type represents a value that can be used by a sort function.
- *
- * @category Parameter
- */
-export type SortKey = string | number | boolean;
-
 /**
  * The SliceIdsListener type describes a function that is used to listen to
  * changes to the Slice Ids in an Index.
@@ -60,6 +53,8 @@ export type SortKey = string | number | boolean;
  * When called, a SliceIdsListener is given a reference to the Indexes object,
  * and the Id of the Index that changed.
  *
+ * @param indexes A reference to the Indexes object that changed.
+ * @param indexId The Id of the Index that changed.
  * @category Listener
  */
 export type SliceIdsListener = (indexes: Indexes, indexId: Id) => void;
@@ -75,6 +70,9 @@ export type SliceIdsListener = (indexes: Indexes, indexId: Id) => void;
  * object, the Id of the Index that changed, and the Id of the Slice whose Row
  * Ids changed.
  *
+ * @param indexes A reference to the Indexes object that changed.
+ * @param indexId The Id of the Index that changed.
+ * @param sliceId The Id of the Slice that changed.
  * @category Listener
  */
 export type SliceRowIdsListener = (
@@ -93,7 +91,13 @@ export type SliceRowIdsListener = (
  * @category Development
  */
 export type IndexesListenerStats = {
+  /**
+   * The number of SlideIdsListeners registered with the Indexes object.
+   */
   sliceIds?: number;
+  /**
+   * The number of SliceRowIdsListeners registered with the Indexes object.
+   */
   sliceRowIds?: number;
 };
 
@@ -118,7 +122,7 @@ export type IndexesListenerStats = {
  * creation, to adding a definition, getting its contents, and then registering
  * and removing a listener for it.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTable('pets', {
  *   fido: {species: 'dog'},
  *   felix: {species: 'cat'},
@@ -146,6 +150,11 @@ export type IndexesListenerStats = {
  * indexes.delListener(listenerId);
  * indexes.destroy();
  * ```
+ * @see Metrics And Indexes guides
+ * @see Rolling Dice demos
+ * @see Country demo
+ * @see Todo App demos
+ * @category Indexes
  */
 export interface Indexes {
   /**
@@ -211,7 +220,7 @@ export interface Indexes {
    * This example creates a Store, creates an Indexes object, and defines a
    * simple Index based on the values in the `species` Cell.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -230,7 +239,7 @@ export interface Indexes {
    * This example creates a Store, creates an Indexes object, and defines an
    * Index based on the first letter of the pets' names.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -250,7 +259,7 @@ export interface Indexes {
    * Index based on the first letter of the pets' names. The Slice Ids (and Row
    * Ids within them) are alphabetically sorted.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -292,7 +301,7 @@ export interface Indexes {
    * This example creates a Store, creates an Indexes object, defines a simple
    * Index, and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -321,7 +330,7 @@ export interface Indexes {
    * This example creates an Indexes object against a newly-created Store and
    * then gets its reference in order to update its data.
    *
-   * ```tsx
+   * ```js
    * const indexes = createIndexes(createStore());
    * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
    * indexes.getStore().setCell('pets', 'fido', 'species', 'dog');
@@ -341,7 +350,7 @@ export interface Indexes {
    * This example creates an Indexes object with two definitions, and then gets
    * the Ids of the definitions.
    *
-   * ```tsx
+   * ```js
    * const indexes = createIndexes(createStore())
    *   .setIndexDefinition('bySpecies', 'pets', 'species')
    *   .setIndexDefinition('byColor', 'pets', 'color');
@@ -365,7 +374,7 @@ export interface Indexes {
    * This example creates an Indexes object, a single Index definition, and then
    * queries it (and a non-existent definition) to get the underlying Table Id.
    *
-   * ```tsx
+   * ```js
    * const indexes = createIndexes(createStore());
    * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
    *
@@ -391,7 +400,7 @@ export interface Indexes {
    * simple Index. It then uses getSliceIds to see the available Slice Ids in
    * the Index (and also the Slice Ids in an Index that has not been defined).
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -425,7 +434,7 @@ export interface Indexes {
    * simple Index. It then uses getSliceRowIds to see the Row Ids in the Slice
    * (and also the Row Ids in Slices that do not exist).
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -467,7 +476,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to a specific Index.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -495,7 +504,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to any Index.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', color: 'brown'},
    *   felix: {species: 'cat', color: 'black'},
@@ -552,7 +561,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to a specific Slice.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -581,7 +590,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, and then registers a
    * listener that responds to any changes to any Slice.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', color: 'brown'},
    *   felix: {species: 'cat', color: 'black'},
@@ -633,7 +642,7 @@ export interface Indexes {
    * This example creates a Store, a Indexes object, registers a listener, and
    * then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -675,7 +684,7 @@ export interface Indexes {
    * definition (that registers a RowListener with the underlying Store),
    * and then destroys it again, removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -714,7 +723,7 @@ export interface Indexes {
    * @example
    * This example gets the listener statistics of an Indexes object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const indexes = createIndexes(store);
    * indexes.addSliceIdsListener(null, () => {
@@ -747,7 +756,7 @@ export interface Indexes {
  * @example
  * This example creates an Indexes object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const indexes = createIndexes(store);
  * console.log(indexes.getIndexIds());
@@ -757,59 +766,13 @@ export interface Indexes {
  * This example creates an Indexes object, and calls the method a second time
  * for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const indexes1 = createIndexes(store);
  * const indexes2 = createIndexes(store);
  * console.log(indexes1 === indexes2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createIndexes(store: Store): Indexes;
-
-/**
- * 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, 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.
- *
- * ```tsx
- * 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.
- *
- * ```tsx
- * 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']
- * ```
- */
-export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;

package/lib/indexes.js

@@ -1 +1 @@
-const e=e=>typeof e,t=e(""),s=(e,t)=>e.every(((s,n)=>0==n||t(e[n-1],s)<=0)),n=(e,t)=>e.sort(t),o=(e,t)=>e.forEach(t),r=e=>e.length,d=e=>0==r(e),c=e=>e.slice(1),i=e=>null==e,l=(e,t,s)=>i(e)?s?.():t(e),a=(e,t)=>e?.has(t)??!1,u=e=>i(e)||0==(e=>e.size)(e),g=e=>e.clear(),I=(e,t)=>e?.forEach(t),f=(e,t)=>e?.delete(t),h=e=>new Map(e),w=e=>[...e?.keys()??[]],p=(e,t)=>e?.get(t),L=(e,t)=>I(e,((e,s)=>t(s,e))),S=(e,t,s)=>i(s)?(f(e,t),e):e?.set(t,s),v=(e,t,s,n)=>(a(e,t)||(n?.(s),e.set(t,s)),p(e,t)),R=e=>new Set(e),b=(e,t)=>e?.add(t),x=(s,n)=>e(s)==t?e=>e(s):s??(()=>n??""),y=(e,t,s)=>r(s)<2?b(d(s)?e:v(e,s[0],R()),t):y(v(e,s[0],h()),t,c(s)),T=e=>{const t=(s,n,...r)=>l(s,(s=>d(r)?e(s,n):o([r[0],null],(e=>t(p(s,e),n,...c(r))))));return t},k=Object.freeze,z=(e=>{const t=new WeakMap;return s=>(t.has(s)||t.set(s,e(s)),t.get(s))})((e=>{const t=h(),d=h(),[c,v,z,E,M,j,C,O]=((e,t,s)=>{const n=e.hasRow,r=h(),d=h(),c=h(),u=h(),f=h(),v=t=>l(p(f,t),(s=>{I(s,e.delListener),S(f,t)})),b=e=>{S(r,e),S(d,e),S(c,e),S(u,e),v(e)};return[()=>e,()=>w(r),e=>p(r,e),e=>p(d,e),(e,t)=>S(d,e,t),(l,w,b,x,y)=>{const T=h(),k=h();S(r,l,w),a(d,l)||(S(d,l,t()),S(c,l,h()),S(u,l,h()));const z=p(c,l),D=p(u,l),E=t=>{const o=s=>e.getCell(w,t,s),r=p(z,t),d=n(w,t)?s(x(o,t)):void 0;if(r!=d&&S(T,t,[r,d]),!i(y)){const e=p(D,t),s=n(w,t)?y(o,t):void 0;e!=s&&S(k,t,s)}},M=e=>{b((()=>{I(T,(([,e],t)=>S(z,t,e))),I(k,((e,t)=>S(D,t,e)))}),T,k,z,D,e),g(T),g(k)};L(z,E),e.hasTable(w)&&o(e.getRowIds(w),(e=>{a(z,e)||E(e)})),M(!0),v(l),S(f,l,R([e.addRowListener(w,null,((e,t,s)=>E(s))),e.addTableListener(w,(()=>M()))]))},b,()=>L(f,b)]})(e,h,(e=>i(e)?"":e+"")),[W,m,q]=(e=>{let t,s=0;const n=[],d=h();return[(o,r,c=[])=>{t??=e();const i=n.pop()??""+s++;return S(d,i,[o,r,c]),y(r,i,c),i},(e,s=[],...n)=>T(I)(e,(e=>l(p(d,e),(([e])=>e(t,...s,...n)))),...s),e=>l(p(d,e),(([,t,s])=>(T(f)(t,e,...s),S(d,e),r(n)<1e3&&n.push(e),s)),(()=>[])),(e,s,n)=>l(p(d,e),(([e,,d])=>{const c=(...l)=>{const a=r(l);a==r(d)?e(t,...l,...n(l)):i(d[a])?o(s[a](...l),(e=>c(...l,e))):c(...l,d[a])};c()}))]})((()=>A)),A={setIndexDefinition:(e,o,r,c,g,w=D)=>{const v=i(g)?void 0:([e],[t])=>g(e,t);return j(e,o,((o,r,g,x,y)=>{let T=0;const k=R(),z=R(),D=E(e);if(I(r,(([e,t],s)=>{i(e)||(b(k,e),l(p(D,e),(t=>{f(t,s),u(t)&&(S(D,e),T=1)}))),i(t)||(b(k,t),a(D,t)||(S(D,t,R()),T=1),b(p(D,t),s),i(c)||b(z,t))})),o(),L(g,(e=>l(p(x,e),(e=>b(z,e))))),u(y)||I(z,(e=>{const t=(t,s)=>w(p(y,t),p(y,s),e),o=[...p(D,e)];s(o,t)||(S(D,e,R(n(o,t))),b(k,e))})),T){if(!i(v)){const t=[...D];s(t,v)||M(e,h(n(t,v)))}m(t,[e])}I(k,(t=>m(d,[e,t])))}),x(r),l(c,x)),A},delIndexDefinition:e=>(C(e),A),getStore:c,getIndexIds:v,getTableId:z,getSliceIds:e=>w(E(e)),getSliceRowIds:(e,t)=>[...p(E(e),t)?.values()??[]],addSliceIdsListener:(e,s)=>W(s,t,[e]),addSliceRowIdsListener:(e,t,s)=>W(s,d,[e,t]),delListener:e=>(q(e),A),destroy:O,getListenerStats:()=>({})};return k(A)})),D=(e,t)=>e<t?-1:1;export{z as createIndexes,D as defaultSorter};
+const e=e=>typeof e,t=e(""),s=(e,t)=>e.every(((s,n)=>0==n||t(e[n-1],s)<=0)),n=(e,t)=>e.sort(t),o=(e,t)=>e.forEach(t),r=e=>e.length,d=e=>0==r(e),c=e=>e.slice(1),l=e=>null==e,i=(e,t,s)=>l(e)?s?.():t(e),a=(e,t)=>e?.has(t)??!1,u=e=>l(e)||0==(e=>e.size)(e),g=e=>e.clear(),I=(e,t)=>e?.forEach(t),f=(e,t)=>e?.delete(t),h=e=>new Map(e),w=e=>[...e?.keys()??[]],p=(e,t)=>e?.get(t),L=(e,t)=>I(e,((e,s)=>t(s,e))),S=(e,t,s)=>l(s)?(f(e,t),e):e?.set(t,s),v=(e,t,s,n)=>(a(e,t)||(n?.(s),e.set(t,s)),p(e,t)),R=e=>new Set(e),b=(e,t)=>e?.add(t),x=(s,n)=>e(s)==t?e=>e(s):s??(()=>n??""),y=(e,t)=>e<t?-1:1,T=(e,t,s)=>r(s)<2?b(d(s)?e:v(e,s[0],R()),t):T(v(e,s[0],h()),t,c(s)),k=e=>{const t=(s,n,...r)=>i(s,(s=>d(r)?e(s,n):o([r[0],null],(e=>t(p(s,e),n,...c(r))))));return t},z=Object.freeze,D=(e=>{const t=new WeakMap;return s=>(t.has(s)||t.set(s,e(s)),t.get(s))})((e=>{const t=h(),d=h(),[c,v,D,E,M,j,C,O]=((e,t,s)=>{const n=e.hasRow,r=h(),d=h(),c=h(),u=h(),f=h(),v=t=>i(p(f,t),(s=>{I(s,e.delListener),S(f,t)})),b=e=>{S(r,e),S(d,e),S(c,e),S(u,e),v(e)};return[()=>e,()=>w(r),e=>p(r,e),e=>p(d,e),(e,t)=>S(d,e,t),(i,w,b,x,y)=>{const T=h(),k=h();S(r,i,w),a(d,i)||(S(d,i,t()),S(c,i,h()),S(u,i,h()));const z=p(c,i),D=p(u,i),E=t=>{const o=s=>e.getCell(w,t,s),r=p(z,t),d=n(w,t)?s(x(o,t)):void 0;if(r!=d&&S(T,t,[r,d]),!l(y)){const e=p(D,t),s=n(w,t)?y(o,t):void 0;e!=s&&S(k,t,s)}},M=e=>{b((()=>{I(T,(([,e],t)=>S(z,t,e))),I(k,((e,t)=>S(D,t,e)))}),T,k,z,D,e),g(T),g(k)};L(z,E),e.hasTable(w)&&o(e.getRowIds(w),(e=>{a(z,e)||E(e)})),M(!0),v(i),S(f,i,R([e.addRowListener(w,null,((e,t,s)=>E(s))),e.addTableListener(w,(()=>M()))]))},b,()=>L(f,b)]})(e,h,(e=>l(e)?"":e+"")),[W,m,q]=(e=>{let t,s=0;const n=[],d=h();return[(o,r,c=[])=>{t??=e();const l=n.pop()??""+s++;return S(d,l,[o,r,c]),T(r,l,c),l},(e,s=[],...n)=>k(I)(e,(e=>i(p(d,e),(([e])=>e(t,...s,...n)))),...s),e=>i(p(d,e),(([,t,s])=>(k(f)(t,e,...s),S(d,e),r(n)<1e3&&n.push(e),s)),(()=>[])),(e,s,n)=>i(p(d,e),(([e,,d])=>{const c=(...i)=>{const a=r(i);a==r(d)?e(t,...i,...n(i)):l(d[a])?o(s[a](...i),(e=>c(...i,e))):c(...i,d[a])};c()}))]})((()=>A)),A={setIndexDefinition:(e,o,r,c,g,w=y)=>{const v=l(g)?void 0:([e],[t])=>g(e,t);return j(e,o,((o,r,g,x,y,T)=>{let k=0;const z=R(),D=R(),j=E(e);if(I(r,(([e,t],s)=>{l(e)||(b(z,e),i(p(j,e),(t=>{f(t,s),u(t)&&(S(j,e),k=1)}))),l(t)||(b(z,t),a(j,t)||(S(j,t,R()),k=1),b(p(j,t),s),l(c)||b(D,t))})),o(),u(y)||(T?L(j,(e=>b(D,e))):L(g,(e=>i(p(x,e),(e=>b(D,e))))),I(D,(e=>{const t=(t,s)=>w(p(y,t),p(y,s),e),o=[...p(j,e)];s(o,t)||(S(j,e,R(n(o,t))),b(z,e))}))),(k||T)&&!l(v)){const t=[...j];s(t,v)||(M(e,h(n(t,v))),k=1)}k&&m(t,[e]),I(z,(t=>m(d,[e,t])))}),x(r),i(c,x)),A},delIndexDefinition:e=>(C(e),A),getStore:c,getIndexIds:v,getTableId:D,getSliceIds:e=>w(E(e)),getSliceRowIds:(e,t)=>[...p(E(e),t)?.values()??[]],addSliceIdsListener:(e,s)=>W(s,t,[e]),addSliceRowIdsListener:(e,t,s)=>W(s,d,[e,t]),delListener:e=>(q(e),A),destroy:O,getListenerStats:()=>({})};return z(A)}));export{D as createIndexes};

package/lib/metrics.d.ts

@@ -3,8 +3,8 @@
  * and track metrics and aggregates of the data in Store objects.
  *
  * The main entry point to this module is the createMetrics function, which
- * returns a new Metrics object. From there, you can create new metric
- * definitions, access the values of those metrics directly, and register
+ * returns a new Metrics object. From there, you can create new Metric
+ * definitions, access the values of those Metrics directly, and register
  * listeners for when they change.
  *
  * @packageDocumentation
@@ -31,6 +31,9 @@ export type Metric = number;
  * use a more complex aggregation of your own devising. See the
  * setMetricDefinition method for more examples.
  *
+ * @param numbers The array of numbers in the Metric's aggregation.
+ * @param length The length of the array of numbers in the Metric's aggregation.
+ * @returns The value of the Metric.
  * @category Aggregators
  */
 export type Aggregate = (numbers: number[], length: number) => Metric;
@@ -53,6 +56,10 @@ export type Aggregate = (numbers: number[], length: number) => Metric;
  * cost of growing the input data set. See the setMetricDefinition method for
  * more examples.
  *
+ * @param metric The current value of the Metric.
+ * @param add The number being added to the Metric's aggregation.
+ * @param length The length of the array of numbers in the Metric's aggregation.
+ * @returns The new value of the Metric.
  * @category Aggregators
  */
 export type AggregateAdd = (
@@ -82,6 +89,10 @@ export type AggregateAdd = (
  * cost of shrinking the input data set. See the setMetricDefinition method for
  * more examples.
  *
+ * @param metric The current value of the Metric.
+ * @param remove The number being removed from the Metric's aggregation.
+ * @param length The length of the array of numbers in the Metric's aggregation.
+ * @returns The new value of the Metric.
  * @category Aggregators
  */
 export type AggregateRemove = (
@@ -109,6 +120,11 @@ export type AggregateRemove = (
  * cost of changing the input data set in place. See the setMetricDefinition
  * method for more examples.
  *
+ * @param metric The current value of the Metric.
+ * @param add The number being added to the Metric's aggregation.
+ * @param remove The number being removed from the Metric's aggregation.
+ * @param length The length of the array of numbers in the Metric's aggregation.
+ * @returns The new value of the Metric.
  * @category Aggregators
  */
 export type AggregateReplace = (
@@ -132,6 +148,10 @@ export type AggregateReplace = (
  * has gained its first row), the old value will be `undefined`. If a Metric now
  * no longer has a value, the new value will be `undefined`.
  *
+ * @param metrics A reference to the Metrics object that changed.
+ * @param metricId The Id of the Metric that changed.
+ * @param newMetric The new value of the Metric that changed.
+ * @param oldMetric The old value of the Metric that changed.
  * @category Listener
  */
 export type MetricListener = (
@@ -151,6 +171,9 @@ export type MetricListener = (
  * @category Development
  */
 export type MetricsListenerStats = {
+  /**
+   * The number of MetricListeners registered with the Metrics object.
+   */
   metric?: number;
 };
 
@@ -176,7 +199,7 @@ export type MetricsListenerStats = {
  * creation, to adding a definition, getting an Metric, and then registering and
  * removing a listener for it.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTable('species', {
  *   dog: {price: 5},
  *   cat: {price: 4},
@@ -203,6 +226,11 @@ export type MetricsListenerStats = {
  * metrics.delListener(listenerId);
  * metrics.destroy();
  * ```
+ * @see Metrics And Indexes guides
+ * @see Rolling Dice demos
+ * @see Country demo
+ * @see Todo App demos
+ * @category Metrics
  */
 export interface Metrics {
   /**
@@ -258,7 +286,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, and defines a
    * simple Metric to count the Row objects in the Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -276,7 +304,7 @@ export interface Metrics {
    * standard Metric to get the highest value of each `price` Cell in the Row
    * objects in the Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -293,7 +321,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, and defines a
    * custom Metric to get the lowest value of each `price` Cell, greater than 2.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -317,7 +345,7 @@ export interface Metrics {
    * However, it also reduces algorithmic complexity with two shortcut
    * functions.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -350,7 +378,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, and defines a
    * custom Metric to get the average value of a discounted price.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5, discount: 0.3},
    *   cat: {price: 4, discount: 0.2},
@@ -389,7 +417,7 @@ export interface Metrics {
    * This example creates a Store, creates a Metrics object, defines a simple
    * Metric, and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -418,7 +446,7 @@ export interface Metrics {
    * This example creates a Metrics object against a newly-created Store and
    * then gets its reference in order to update its data.
    *
-   * ```tsx
+   * ```js
    * const metrics = createMetrics(createStore());
    * metrics.setMetricDefinition('speciesCount', 'species');
    * metrics.getStore().setCell('species', 'dog', 'price', 5);
@@ -438,7 +466,7 @@ export interface Metrics {
    * This example creates a Metrics object with two definitions, and then gets
    * the Ids of the definitions.
    *
-   * ```tsx
+   * ```js
    * const metrics = createMetrics(createStore())
    *   .setMetricDefinition('speciesCount', 'species')
    *   .setMetricDefinition('petsCount', 'pets');
@@ -462,7 +490,7 @@ export interface Metrics {
    * This example creates a Metrics object, a single Metric definition, and then
    * queries it (and a non-existent definition) to get the underlying Table Id.
    *
-   * ```tsx
+   * ```js
    * const metrics = createMetrics(createStore());
    * metrics.setMetricDefinition('speciesCount', 'species');
    *
@@ -489,7 +517,7 @@ export interface Metrics {
    * getMetric to access its value (and also the value of a Metric that has not
    * been defined).
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -529,7 +557,7 @@ export interface Metrics {
    * This example creates a Store, a Metrics object, and then registers a
    * listener that responds to any changes to a specific Metric.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -557,7 +585,7 @@ export interface Metrics {
    * This example creates a Store, a Metrics object, and then registers a
    * listener that responds to any changes to any Metric.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -601,7 +629,7 @@ export interface Metrics {
    * This example creates a Store, a Metrics object, registers a listener, and
    * then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -643,7 +671,7 @@ export interface Metrics {
    * registers a RowListener with the underlying Store), and then destroys it
    * again, removing the listener.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('species', {
    *   dog: {price: 5},
    *   cat: {price: 4},
@@ -679,7 +707,7 @@ export interface Metrics {
    * @example
    * This example gets the listener statistics of a Metrics object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * const metrics = createMetrics(store);
    * metrics.addMetricListener(null, () => console.log('Metric changed'));
@@ -707,7 +735,7 @@ export interface Metrics {
  * @example
  * This example creates a Metrics object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const metrics = createMetrics(store);
  * console.log(metrics.getMetricIds());
@@ -717,12 +745,13 @@ export interface Metrics {
  * This example creates a Metrics object, and calls the method a second time
  * for the same Store to return the same object.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * const metrics1 = createMetrics(store);
  * const metrics2 = createMetrics(store);
  * console.log(metrics1 === metrics2);
  * // -> true
  * ```
+ * @category Creation
  */
 export function createMetrics(store: Store): Metrics;