tinybase 0.9.1 → 1.0.0

package/lib/store.d.ts

@@ -17,14 +17,13 @@ import {Id, IdOrNull, Ids, Json} from './common.d';
  * The Tables type is the data structure representing all of the data in a
  * Store.
  *
- * A Tables object can be provided to the createStore function when first
- * creating the Store. It is also used when setting all of the tables together
- * with the setTables method, and when getting them back out again with the
- * getTables method. A Tables object is a regular JavaScript object containing
- * individual Table objects, keyed by their Id.
+ * A Tables object is used when setting all of the tables together with the
+ * setTables method, and when getting them back out again with the getTables
+ * method. A Tables object is a regular JavaScript object containing individual
+ * Table objects, keyed by their Id.
  *
  * @example
- * ```tsx
+ * ```js
  * const tables: Tables = {
  *   pets: {
  *     fido: {species: 'dog', color: 'brown'},
@@ -49,7 +48,7 @@ export type Tables = {[tableId: Id]: Table};
  * Id.
  *
  * @example
- * ```tsx
+ * ```js
  * const table: Table = {
  *   fido: {species: 'dog', color: 'brown'},
  *   felix: {species: 'cat'},
@@ -67,7 +66,7 @@ export type Table = {[rowId: Id]: Row};
  * object containing individual Cell objects, keyed by their Id.
  *
  * @example
- * ```tsx
+ * ```js
  * const row: Row = {species: 'dog', color: 'brown'};
  * ```
  * @category Store
@@ -82,7 +81,7 @@ export type Row = {[cellId: Id]: Cell};
  * number, or boolean.
  *
  * @example
- * ```tsx
+ * ```js
  * const cell: Cell = 'dog';
  * ```
  * @category Store
@@ -97,6 +96,9 @@ export type Cell = string | number | boolean;
  * can do something based on every Table in the Store. See that method for
  * specific examples.
  *
+ * @param tableId The Id of the Table that the callback can operate on.
+ * @param forEachRow A function that will let you iterate over the Row objects
+ * in this Table.
  * @category Callback
  */
 export type TableCallback = (
@@ -112,6 +114,9 @@ export type TableCallback = (
  * do something based on every Row in a Table. See that method for specific
  * examples.
  *
+ * @param rowId The Id of the Row that the callback can operate on.
+ * @param forEachRow A function that will let you iterate over the Cell values
+ * in this Row.
  * @category Callback
  */
 export type RowCallback = (
@@ -127,6 +132,8 @@ export type RowCallback = (
  * do something based on every Cell in a Row. See that method for specific
  * examples.
  *
+ * @param cellId The Id of the Cell that the callback can operate on.
+ * @param cell The value of the Cell.
  * @category Callback
  */
 export type CellCallback = (cellId: Id, cell: Cell) => void;
@@ -139,6 +146,7 @@ export type CellCallback = (cellId: Id, cell: Cell) => void;
  * new one, such as when incrementing a number. See that method for specific
  * examples.
  *
+ * @param cell The current value of the Cell to map to a new value.
  * @category Callback
  */
 export type MapCell = (cell: Cell | undefined) => Cell;
@@ -151,6 +159,7 @@ export type MapCell = (cell: Cell | undefined) => Cell;
  * setMetricDefinition method of a Metrics object, or the setIndexDefinition
  * method of an Indexes object. See those methods for specific examples.
  *
+ * @param cellId The Id of the Cell to fetch the value for.
  * @category Callback
  */
 export type GetCell = (cellId: Id) => Cell | undefined;
@@ -170,6 +179,9 @@ export type GetCell = (cellId: Id) => Cell | undefined;
  * callListener method rather than due to a real change in the Store), the
  * GetCellChange function will not be present.
  *
+ * @param store A reference to the Store that changed.
+ * @param getCellChange A function that returns information about any Cell's
+ * changes.
  * @category Listener
  */
 export type TablesListener = (
@@ -186,6 +198,7 @@ export type TablesListener = (
  *
  * When called, a TableIdsListener is given a reference to the Store.
  *
+ * @param store A reference to the Store that changed.
  * @category Listener
  */
 export type TableIdsListener = (store: Store) => void;
@@ -205,6 +218,10 @@ export type TableIdsListener = (store: Store) => void;
  * callListener method rather than due to a real change in the Store), the
  * GetCellChange function will not be present.
  *
+ * @param store A reference to the Store that changed.
+ * @param tableId The Id of the Table that changed.
+ * @param getCellChange A function that returns information about any Cell's
+ * changes.
  * @category Listener
  */
 export type TableListener = (
@@ -223,6 +240,8 @@ export type TableListener = (
  * When called, a RowIdsListener is given a reference to the Store, and the Id
  * of the Table whose Row Ids changed.
  *
+ * @param store A reference to the Store that changed.
+ * @param tableId The Id of the Table that changed.
  * @category Listener
  */
 export type RowIdsListener = (store: Store, tableId: Id) => void;
@@ -243,6 +262,11 @@ export type RowIdsListener = (store: Store, tableId: Id) => void;
  * callListener method rather than due to a real change in the Store), the
  * GetCellChange function will not be present.
  *
+ * @param store A reference to the Store that changed.
+ * @param tableId The Id of the Table that changed.
+ * @param rowId The Id of the Row that changed.
+ * @param getCellChange A function that returns information about any Cell's
+ * changes.
  * @category Listener
  */
 export type RowListener = (
@@ -262,6 +286,10 @@ export type RowListener = (
  * When called, a CellIdsListener is given a reference to the Store, the Id of
  * the Table that changed, and the Id of the Row whose Cell Ids changed.
  *
+ * @param store A reference to the Store that changed.
+ * @param tableId The Id of the Table that changed.
+ * @param rowId The Id of the Row that changed.
+ * changes.
  * @category Listener
  */
 export type CellIdsListener = (store: Store, tableId: Id, rowId: Id) => void;
@@ -284,6 +312,14 @@ export type CellIdsListener = (store: Store, tableId: Id, rowId: Id) => void;
  * GetCellChange function will not be present and the new and old values of the
  * Cell will be the same.
  *
+ * @param store A reference to the Store that changed.
+ * @param tableId The Id of the Table that changed.
+ * @param rowId The Id of the Row that changed.
+ * @param cellId The Id of the Cell that changed.
+ * @param newCell The new value of the Cell that changed.
+ * @param oldCell The old value of the Cell that changed.
+ * @param getCellChange A function that returns information about any Cell's
+ * changes.
  * @category Listener
  */
 export type CellListener = (
@@ -297,36 +333,52 @@ export type CellListener = (
 ) => void;
 
 /**
- * The GetCellChange type describes a function that returns information about a
- * Cell's changes during a transaction.
+ * The GetCellChange type describes a function that returns information about
+ * any Cell's changes during a transaction.
  *
  * A GetCellChange function is provided to every listener when called due the
  * Store changing. The listener can then fetch the previous value of a Cell
  * before the current transaction, the new value after it, and a convenience
  * flag that indicates that the value has changed.
  *
+ * @param tableId The Id of the Table to inspect.
+ * @param rowId The Id of the Row to inspect.
+ * @param cellId The Id of the Cell to inspect.
+ * @returns A CellChange array containing information about the Cell's changes.
  * @category Listener
  */
-export type GetCellChange = (
-  tableId: Id,
-  rowId: Id,
-  cellId: Id,
-) => [changed: boolean, oldCell: Cell | undefined, newCell: Cell | undefined];
+export type GetCellChange = (tableId: Id, rowId: Id, cellId: Id) => CellChange;
+
+/**
+ * The CellChange type describes a Cell's changes during a transaction.
+ *
+ * This is returned by the GetCellChange function that is provided to every
+ * listener when called. This array contains the previous value of a Cell
+ * before the current transaction, the new value after it, and a convenience
+ * flag that indicates that the value has changed.
+ *
+ * @category Listener
+ */
+export type CellChange = [
+  changed: boolean,
+  oldCell: Cell | undefined,
+  newCell: Cell | undefined,
+];
 
 /**
  * The Schema type describes the structure of a Store in terms of valid Table
  * Ids and the types of Cell that can exist within them.
  *
  * A Schema comprises a JavaScript object describing each Table, in turn a
- * nested JavaScript object containing the each Cell and its CellSchema. It is
- * provided to the createStore function or to the setSchema method.
+ * nested JavaScript object containing information about each Cell and its
+ * CellSchema. It is provided to the setSchema method.
  *
  * @example
  * When applied to a Store, this Schema only allows one Table called `pets`, in
  * which each Row may contain a string `species` Cell, and is guaranteed to
  * contain a boolean `sold` Cell that defaults to `false`.
  *
- *```tsx
+ *```js
  * const schema: Schema = {
  *   pets: {
  *     species: {type: 'string'},
@@ -361,7 +413,7 @@ export type Schema = {
  * When applied to a Store, this CellSchema ensures a boolean Cell is always
  * present, and defaults it to `false`.
  *
- *```tsx
+ *```js
  * const requiredBoolean: CellSchema = {type: 'boolean', default: false};
  * ```
  * @category Schema
@@ -392,12 +444,33 @@ export type CellSchema =
  * @category Development
  */
 export type StoreListenerStats = {
+  /**
+   * The number of TablesListeners registered with the Store.
+   */
   tables?: number;
+  /**
+   * The number of TableIdsListeners registered with the Store.
+   */
   tableIds?: number;
+  /**
+   * The number of TableListeners registered with the Store.
+   */
   table?: number;
+  /**
+   * The number of RowIdsListeners registered with the Store.
+   */
   rowIds?: number;
+  /**
+   * The number of RowListeners registered with the Store.
+   */
   row?: number;
+  /**
+   * The number of CellIdsListeners registered with the Store.
+   */
   cellIds?: number;
+  /**
+   * The number of CellListeners registered with the Store.
+   */
   cell?: number;
 };
 
@@ -467,10 +540,10 @@ export type StoreListenerStats = {
  * |Cell Ids|getCellIds|-|-|addCellIdsListener|
  * |Cell|getCell|setCell|delCell|addCellListener|
  *
- * Additionally, there are two extra methods to manipulate a Row. The addRow
- * method is like the setRow method but automatically assigns it a new unique
- * Id. And the setPartialRow method lets you update multiple Cell values in a
- * Row without affecting the others.
+ * Additionally, there are two extra methods to manipulate Row objects. The
+ * addRow method is like the setRow method but automatically assigns it a new
+ * unique Id. And the setPartialRow method lets you update multiple Cell values
+ * in a Row without affecting the others.
  *
  * The transaction method is used to wrap multiple changes to the Store so that
  * the relevant listeners only fire once.
@@ -521,7 +594,7 @@ export type StoreListenerStats = {
  * This example shows a very simple lifecycle of a Store: from creation, to
  * adding and getting some data, and then registering and removing a listener.
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
  * console.log(store.getRow('pets', 'fido'));
  * // -> {species: 'dog'}
@@ -539,6 +612,11 @@ export type StoreListenerStats = {
  *
  * store.delListener(listenerId);
  * ```
+ * @see The Basics guides
+ * @see Using Schemas guides
+ * @see Hello World demos
+ * @see Todo App demos
+ * @category Store
  */
 export interface Store {
   /**
@@ -553,7 +631,7 @@ export interface Store {
    * @example
    * This example retrieves the data in a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog'}},
    *   species: {dog: {price: 5}},
@@ -565,7 +643,7 @@ export interface Store {
    * This example retrieves the Tables of an empty Store, returning an empty
    * object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * console.log(store.getTables());
    * // -> {}
@@ -590,7 +668,7 @@ export interface Store {
    * @example
    * This example retrieves the Table Ids in a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog'}},
    *   species: {dog: {price: 5}},
@@ -602,7 +680,7 @@ export interface Store {
    * This example retrieves the Table Ids of an empty Store, returning an empty
    * array.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * console.log(store.getTableIds());
    * // -> []
@@ -624,7 +702,7 @@ export interface Store {
    * @example
    * This example retrieves the data in a single Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog'}},
    *   species: {dog: {price: 5}},
@@ -636,7 +714,7 @@ export interface Store {
    * This example retrieves a Table that does not exist, returning an empty
    * object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.getTable('employees'));
    * // -> {}
@@ -658,7 +736,7 @@ export interface Store {
    * @example
    * This example retrieves the Row Ids in a Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {
    *     fido: {species: 'dog'},
@@ -672,7 +750,7 @@ export interface Store {
    * This example retrieves the Row Ids of a Table that does not exist,
    * returning an empty array.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.getRowIds('employees'));
    * // -> []
@@ -695,7 +773,7 @@ export interface Store {
    * @example
    * This example retrieves the data in a single Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {
    *     fido: {species: 'dog'},
@@ -709,7 +787,7 @@ export interface Store {
    * This example retrieves a Row that does not exist, returning an empty
    * object.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.getRow('pets', 'felix'));
    * // -> {}
@@ -733,7 +811,7 @@ export interface Store {
    * @example
    * This example retrieves the Cell Ids in a Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {
    *     fido: {species: 'dog', color: 'brown'},
@@ -746,7 +824,7 @@ export interface Store {
    * This example retrieves the Cell Ids of a Cell that does not exist,
    * returning an empty array.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.getCellIds('pets', 'felix'));
    * // -> []
@@ -770,7 +848,7 @@ export interface Store {
    * @example
    * This example retrieves a single Cell.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -780,7 +858,7 @@ export interface Store {
    * @example
    * This example retrieves a Cell that does not exist, returning `undefined`.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.getCell('pets', 'fido', 'color'));
    * // -> undefined
@@ -798,7 +876,7 @@ export interface Store {
    * @example
    * This example shows two simple Table existence checks.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.hasTable('pets'));
    * // -> true
@@ -819,7 +897,7 @@ export interface Store {
    * @example
    * This example shows two simple Row existence checks.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.hasRow('pets', 'fido'));
    * // -> true
@@ -841,7 +919,7 @@ export interface Store {
    * @example
    * This example shows two simple Cell existence checks.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.hasCell('pets', 'fido', 'species'));
    * // -> true
@@ -860,7 +938,7 @@ export interface Store {
    * @example
    * This example serializes the contents of a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * console.log(store.getJson());
    * // -> '{"pets":{"fido":{"species":"dog"}}}'
@@ -868,7 +946,7 @@ export interface Store {
    * @example
    * This example serializes the contents of an empty Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * console.log(store.getJson());
    * // -> '{}'
@@ -889,7 +967,7 @@ export interface Store {
    * @example
    * This example serializes the Schema of a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setSchema({
    *   pets: {
    *     species: {type: 'string'},
@@ -902,7 +980,7 @@ export interface Store {
    * @example
    * This example serializes the Schema of an empty Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * console.log(store.getSchemaJson());
    * // -> '{}'
@@ -932,7 +1010,7 @@ export interface Store {
    * @example
    * This example sets the data of a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog'}},
    *   species: {dog: {price: 5}},
@@ -944,7 +1022,7 @@ export interface Store {
    * This example attempts to set the data of an existing Store with partly
    * invalid, and then completely invalid, Tables objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * store.setTables({pets: {felix: {species: 'cat', bug: []}}});
@@ -983,7 +1061,7 @@ export interface Store {
    * @example
    * This example sets the data of a single Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog'},
    *   felix: {species: 'cat'},
@@ -995,7 +1073,7 @@ export interface Store {
    * This example attempts to set the data of an existing Store with partly
    * invalid, and then completely invalid, Table objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * store.setTable('pets', {felix: {species: 'cat', bug: []}});
@@ -1036,7 +1114,7 @@ export interface Store {
    * @example
    * This example sets the data of a single Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setRow('pets', 'fido', {species: 'dog'});
    * console.log(store.getTables());
    * // -> {pets: {fido: {species: 'dog'}}}
@@ -1045,7 +1123,7 @@ export interface Store {
    * This example attempts to set the data of an existing Store with partly
    * invalid, and then completely invalid, Row objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * store.setRow('pets', 'fido', {color: 'brown', bug: []});
@@ -1085,7 +1163,7 @@ export interface Store {
    * @example
    * This example adds a single Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * console.log(store.addRow('pets', {species: 'dog'}));
    * // -> '0'
@@ -1096,7 +1174,7 @@ export interface Store {
    * This example attempts to add Rows to an existing Store with partly invalid,
    * and then completely invalid, Row objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {'0': {species: 'dog'}}});
    *
    * console.log(store.addRow('pets', {species: 'cat', bug: []}));
@@ -1138,7 +1216,7 @@ export interface Store {
    * @example
    * This example sets some of the data of a single Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1150,7 +1228,7 @@ export interface Store {
    * This example attempts to set some of the data of an existing Store with
    * partly invalid, and then completely invalid, Row objects.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * store.setPartialRow('pets', 'fido', {color: 'brown', bug: []});
@@ -1192,7 +1270,7 @@ export interface Store {
    * @example
    * This example sets the value of a single Cell.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setCell('pets', 'fido', 'species', 'dog');
    * console.log(store.getTables());
    * // -> {pets: {fido: {species: 'dog'}}}
@@ -1200,7 +1278,7 @@ export interface Store {
    * @example
    * This example sets the data of a single Cell by mapping the existing value.
    *
-   * ```tsx
+   * ```js
    * const increment = (cell) => cell + 1;
    * const store = createStore().setTables({pets: {fido: {visits: 1}}});
    *
@@ -1212,7 +1290,7 @@ export interface Store {
    * This example attempts to set the data of an existing Store with an invalid
    * Cell value.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * store.setCell('pets', 'fido', 'bug', []);
@@ -1237,7 +1315,7 @@ export interface Store {
    * @example
    * This example sets the contents of a Store from a serialization.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * store.setJson('{"pets":{"fido":{"species":"dog"}}}');
    * console.log(store.getTables());
@@ -1247,7 +1325,7 @@ export interface Store {
    * This example attempts to set the contents of a Store from an invalid
    * serialization.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * store.setJson('{"pets":{"fido":{');
    * console.log(store.getTables());
@@ -1264,16 +1342,15 @@ export interface Store {
    * applied or as invalid Table, Row, or Cell objects are removed. These
    * changes will fire any listeners to that data, as expected.
    *
-   * You can also specify the Schema at the time of creation, as the second
-   * parameter of the createStore function. When no longer needed, you can also
-   * completely remove an existing Schema with the delSchema method.
+   * When no longer needed, you can also completely remove an existing Schema
+   * with the delSchema method.
    *
    * @param schema The Schema to be set for the Store.
    * @returns A reference to the Store.
    * @example
    * This example sets the Schema of a Store after it has been created.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setSchema({
    *   pets: {
    *     species: {type: 'string'},
@@ -1295,7 +1372,7 @@ export interface Store {
    * @example
    * This example removes the data of a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    *
    * store.delTables();
@@ -1314,7 +1391,7 @@ export interface Store {
    * @example
    * This example removes a Table from a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog'}},
    *   species: {dog: {price: 5}},
@@ -1339,7 +1416,7 @@ export interface Store {
    * @example
    * This example removes a Row from a Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog'}, felix: {species: 'cat'}},
    * });
@@ -1382,7 +1459,7 @@ export interface Store {
    * @example
    * This example removes a Cell from a Row without a Schema.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', sold: true}},
    * });
@@ -1395,7 +1472,7 @@ export interface Store {
    * This example removes a Cell from a Row with a Schema that defaults its
    * value.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTables({
    *     pets: {fido: {species: 'dog', sold: true}},
@@ -1415,7 +1492,7 @@ export interface Store {
    * This example removes a Cell from a Row with a Schema that defaults its
    * value, but uses the `forceDel` parameter to override it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore()
    *   .setTables({
    *     pets: {fido: {species: 'dog', sold: true}, felix: {species: 'cat'}},
@@ -1442,7 +1519,7 @@ export interface Store {
    * @example
    * This example removes the Schema of a Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setSchema({pets: {species: {type: 'string'}}});
    * store.delSchema();
    * console.log(store.getSchemaJson());
@@ -1481,7 +1558,7 @@ export interface Store {
    * within, a transaction. In the second case, the Row listener is only called
    * once.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * store.addRowListener('pets', 'fido', () => console.log('Fido changed'));
    *
@@ -1501,7 +1578,7 @@ export interface Store {
    * called once - and with the final value - only if there is a net overall
    * change.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * store.addCellListener(
    *   'pets',
@@ -1543,7 +1620,7 @@ export interface Store {
    * This example iterates over each Table in a Store, and lists each Row Id
    * within them.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog'}},
    *   species: {dog: {price: 5}},
@@ -1575,7 +1652,7 @@ export interface Store {
    * This example iterates over each Row in a Table, and lists each Cell Id
    * within them.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {
    *     fido: {species: 'dog'},
@@ -1607,7 +1684,7 @@ export interface Store {
    * @example
    * This example iterates over each Cell in a Row, and lists its value.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1647,7 +1724,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to the whole
    * Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1666,7 +1743,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to the whole
    * Store, and which also mutates the Store itself.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1713,7 +1790,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Table
    * Ids.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addTableIdsListener((store) => {
    *   console.log('Table Ids changed');
@@ -1730,7 +1807,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Table
    * Ids, and which also mutates the Store itself.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addTableIdsListener(
    *   (store) => store.setCell('meta', 'update', 'store', true),
@@ -1743,6 +1820,7 @@ export interface Store {
    *
    * store.delListener(listenerId);
    * ```
+   * @category Listener
    */
   addTableIdsListener(listener: TableIdsListener, mutator?: boolean): Id;
 
@@ -1778,7 +1856,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to a
    * specific Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1800,7 +1878,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to any
    * Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1819,7 +1897,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to a
    * specific Table, and which also mutates the Store itself.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1875,7 +1953,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Row
    * Ids of a specific Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addRowIdsListener('pets', (store) => {
    *   console.log('Row Ids for pets table changed');
@@ -1892,7 +1970,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Row
    * Ids of any Table.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addRowIdsListener(null, (store, tableId) => {
    *   console.log(`Row Ids for ${tableId} table changed`);
@@ -1912,7 +1990,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Row
    * Ids of a specific Table, and which also mutates the Store itself.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addRowIdsListener(
    *   'pets',
@@ -1926,6 +2004,7 @@ export interface Store {
    *
    * store.delListener(listenerId);
    * ```
+   * @category Listener
    */
   addRowIdsListener(
     tableId: IdOrNull,
@@ -1971,7 +2050,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to a
    * specific Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -1993,7 +2072,7 @@ export interface Store {
    * @example
    * This example registers a listener that responds to any changes to any Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -2016,7 +2095,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to a
    * specific Row, and which also mutates the Store itself.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -2083,7 +2162,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Cell
    * Ids of a specific Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addCellIdsListener('pets', 'fido', (store) => {
    *   console.log('Cell Ids for fido row in pets table changed');
@@ -2100,7 +2179,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Cell
    * Ids of any Row.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addCellIdsListener(
    *   null,
@@ -2124,7 +2203,7 @@ export interface Store {
    * This example registers a listener that responds to any change to the Cell
    * Ids of a specific Row, and which also mutates the Store itself.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addCellIdsListener(
    *   'pets',
@@ -2140,6 +2219,7 @@ export interface Store {
    *
    * store.delListener(listenerId);
    * ```
+   * @category Listener
    */
   addCellIdsListener(
     tableId: IdOrNull,
@@ -2188,7 +2268,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to a
    * specific Cell.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -2213,7 +2293,7 @@ export interface Store {
    * @example
    * This example registers a listener that responds to any changes to any Cell.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -2239,7 +2319,7 @@ export interface Store {
    * This example registers a listener that responds to any changes to a
    * specific Cell, and which also mutates the Store itself.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -2283,7 +2363,7 @@ export interface Store {
    * valid values. After that list changes, the listener is called to apply the
    * condition to the existing data.
    *
-   * ```tsx
+   * ```js
    * const validColors = ['walnut', 'brown', 'black'];
    * const store = createStore();
    * const listenerId = store.addCellListener(
@@ -2328,7 +2408,7 @@ export interface Store {
    * @example
    * This example registers a listener and then removes it.
    *
-   * ```tsx
+   * ```js
    * const store = createStore().setTables({
    *   pets: {fido: {species: 'dog', color: 'brown'}},
    * });
@@ -2365,7 +2445,7 @@ export interface Store {
    * @example
    * This example gets the listener statistics of a small and simple Store.
    *
-   * ```tsx
+   * ```js
    * const store = createStore();
    * store.addTablesListener(() => console.log('Tables changed'));
    * store.addRowIdsListener(() => console.log('Row Ids changed'));
@@ -2392,7 +2472,7 @@ export interface Store {
  * @example
  * This example creates a Store.
  *
- * ```tsx
+ * ```js
  * const store = createStore();
  * console.log(store.getTables());
  * // -> {}
@@ -2400,7 +2480,7 @@ export interface Store {
  * @example
  * This example creates a Store with some initial data:
  *
- * ```tsx
+ * ```js
  * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
  * console.log(store.getTables());
  * // -> {pets: {fido: {species: 'dog'}}}
@@ -2408,7 +2488,7 @@ export interface Store {
  * @example
  * This example creates a Store with some initial data and a Schema:
  *
- * ```tsx
+ * ```js
  * const store = createStore()
  *   .setTables({pets: {fido: {species: 'dog'}}})
  *   .setSchema({
@@ -2420,5 +2500,7 @@ export interface Store {
  * console.log(store.getTables());
  * // -> {pets: {fido: {species: 'dog', sold: false}}}
  * ```
+ * @see The Basics guides
+ * @category Creation
  */
 export function createStore(): Store;