tinybase/@types/store/index.d.ts

A reactive data store and sync engine.

/**
 * The store module is the core of the TinyBase project and contains the types,
 * interfaces, and functions to work with Store objects.
 *
 * The main entry point to this module is the createStore function, which
 * returns a new Store. From there, you can set and get data, register
 * listeners, and use other modules to build an entire app around the state and
 * tabular data within.
 * @packageDocumentation
 * @module store
 * @since v1.0.0
 */
import type {StoreAlias} from '../_internal/store/index.d.ts';
import type {Id, IdOrNull, Ids, Json} from '../common/index.d.ts';

/**
 * The TablesSchema type describes the tabular structure of a Store in terms of
 * valid Table Ids and the types of Cell that can exist within them.
 *
 * A TablesSchema comprises a JavaScript object describing each Table, in turn a
 * nested JavaScript object containing information about each Cell and its
 * CellSchema. It is provided to the setTablesSchema method.
 * @example
 * When applied to a Store, this TablesSchema 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`.
 *
 * ```js
 * import type {TablesSchema} from 'tinybase';
 *
 * export const tableSchema: TablesSchema = {
 *   pets: {
 *     species: {type: 'string'},
 *     sold: {type: 'boolean', default: false},
 *   },
 * };
 * ```
 * @category Schema
 * @since v1.0.0
 */
export type TablesSchema = {[tableId: Id]: {[cellId: Id]: CellSchema}};

/**
 * The CellSchema type describes what values are allowed for each Cell in a
 * Table.
 *
 * A CellSchema specifies the type of the Cell (`string`, `boolean`, or
 * `number`), and what the default value can be when an explicit value is not
 * specified.
 *
 * If a default value is provided (and its type is correct), you can be certain
 * that that Cell will always be present in a Row.
 *
 * If the default value is _not_ provided (or its type is incorrect), the Cell
 * may be missing from the Row, but when present you can be guaranteed it is of
 * the correct type.
 * @example
 * When applied to a Store, this CellSchema ensures a boolean Cell is always
 * present, and defaults it to `false`.
 *
 * ```js
 * import type {CellSchema} from 'tinybase';
 *
 * export const requiredBoolean: CellSchema = {
 *   type: 'boolean',
 *   default: false,
 * };
 * ```
 * @category Schema
 * @since v1.0.0
 */
export type CellSchema =
  | {type: 'string'; default?: string}
  | {type: 'number'; default?: number}
  | {type: 'boolean'; default?: boolean};

/**
 * The ValuesSchema type describes the keyed Values that can be set in a Store
 * and their types.
 *
 * A ValuesSchema comprises a JavaScript object describing each Value and its
 * ValueSchema. It is provided to the setValuesSchema method.
 * @example
 * When applied to a Store, this ValuesSchema only allows one boolean Value
 * called `open`, that defaults to `false`.
 *
 * ```js
 * import type {ValuesSchema} from 'tinybase';
 *
 * export const valuesSchema: ValuesSchema = {
 *   open: {type: 'boolean', default: false},
 * };
 * ```
 * @category Schema
 * @since v3.0.0
 */
export type ValuesSchema = {[valueId: Id]: ValueSchema};

/**
 * The ValueSchema type describes what values are allowed for keyed Values in a
 * Store.
 *
 * A ValueSchema specifies the type of the Value (`string`, `boolean`, or
 * `number`), and what the default value can be when an explicit value is not
 * specified.
 *
 * If a default value is provided (and its type is correct), you can be certain
 * that the Value will always be present in a Store.
 *
 * If the default value is _not_ provided (or its type is incorrect), the Value
 * may not be present in the Store, but when present you can be guaranteed it is
 * of the correct type.
 * @example
 * When applied to a Store, this ValueSchema ensures a boolean Value is always
 * present, and defaults it to `false`.
 *
 * ```js
 * import type {ValueSchema} from 'tinybase';
 *
 * export const requiredBoolean: ValueSchema = {
 *   type: 'boolean',
 *   default: false,
 * };
 * ```
 * @category Schema
 * @since v3.0.0
 */
export type ValueSchema =
  | {type: 'string'; default?: string}
  | {type: 'number'; default?: number}
  | {type: 'boolean'; default?: boolean};

/**
 * The NoTablesSchema type is a TablesSchema-like type for when one has not been
 * provided.
 * @category Schema
 * @since v1.0.0
 */
export type NoTablesSchema = {[tableId: Id]: {[cellId: Id]: {type: 'any'}}};

/**
 * The NoValuesSchema type is a ValuesSchema-like type for when one has not been
 * provided.
 * @category Schema
 * @since v1.0.0
 */
export type NoValuesSchema = {[valueId: Id]: {type: 'any'}};

/**
 * The OptionalTablesSchema type is used by generic types that can optionally
 * take a TablesSchema.
 * @category Schema
 * @since v1.0.0
 */
export type OptionalTablesSchema = TablesSchema | NoTablesSchema;

/**
 * The OptionalValuesSchema type is used by generic types that can optionally
 * take a ValuesSchema.
 * @category Schema
 * @since v1.0.0
 */
export type OptionalValuesSchema = ValuesSchema | NoValuesSchema;

/**
 * The OptionalSchemas type is used by generic types that can optionally take
 * either or both of a TablesSchema and ValuesSchema.
 * @category Schema
 * @since v1.0.0
 */
export type OptionalSchemas = [OptionalTablesSchema, OptionalValuesSchema];

/**
 * The NoSchemas type is used as a default by generic types that can optionally
 * take either or both of a TablesSchema and ValuesSchema.
 * @category Schema
 * @since v1.0.0
 */
export type NoSchemas = [NoTablesSchema, NoValuesSchema];

/**
 * The Content type describes both the Tables and Values in a Store.
 *
 * It is an array of two objects, representing tabular and keyed value content.
 * @example
 * The following is a valid Content array:
 * ```json
 * [
 *   {
 *     "pets": {
 *       "fido": {
 *         "sold": false,
 *         "price": 4,
 *       },
 *       "felix": {
 *         "sold": true,
 *         "price": 5,
 *       },
 *     },
 *   },
 *   {
 *     open: true,
 *     employees: 3,
 *   },
 * ]
 * ```
 * @category Store
 * @since v5.0.0
 */
export type Content = [Tables, Values];

/**
 * The Tables type is the data structure representing all of the data in a
 * Store.
 *
 * 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
 * ```js
 * import type {Tables} from 'tinybase';
 *
 * export const tables: Tables = {
 *   pets: {
 *     fido: {species: 'dog', color: 'brown'},
 *     felix: {species: 'cat'},
 *   },
 *   species: {
 *     dog: {price: 5},
 *     cat: {price: 4},
 *   },
 * };
 * ```
 * @category Store
 * @since v1.0.0
 */
export type Tables = {[tableId: Id]: Table};

/**
 * The Table type is the data structure representing the data in a single table.
 *
 * A Table is used when setting a table with the setTable method, and when
 * getting it back out again with the getTable method. A Table object is a
 * regular JavaScript object containing individual Row objects, keyed by their
 * Id.
 * @example
 * ```js
 * import type {Table} from 'tinybase';
 *
 * export const table: Table = {
 *   fido: {species: 'dog', color: 'brown'},
 *   felix: {species: 'cat'},
 * };
 * ```
 * @category Store
 * @since v1.0.0
 */
export type Table = {[rowId: Id]: Row};

/**
 * The Row type is the data structure representing the data in a single row.
 *
 * A Row is used when setting a row with the setRow method, and when getting it
 * back out again with the getRow method. A Row object is a regular JavaScript
 * object containing individual Cell objects, keyed by their Id.
 * @example
 * ```js
 * import type {Row} from 'tinybase';
 *
 * export const row: Row = {species: 'dog', color: 'brown'};
 * ```
 * @category Store
 * @since v1.0.0
 */
export type Row = {[cellId: Id]: Cell};

/**
 * The Cell type is the data structure representing the data in a single cell.
 *
 * A Cell is used when setting a cell with the setCell method, and when getting
 * it back out again with the getCell method. A Cell is a JavaScript string,
 * number, or boolean.
 * @example
 * ```js
 * import type {Cell} from 'tinybase';
 *
 * export const cell: Cell = 'dog';
 * ```
 * @category Store
 * @since v1.0.0
 */
export type Cell = string | number | boolean;

/**
 * The CellOrUndefined type is a data structure representing the data in a
 * single cell, or the value `undefined`.
 *
 * This is used when describing a Cell that is present _or_ that is not present,
 * such as when it has been deleted, or when describing a previous state where
 * the Cell value has since been added.
 * @category Store
 * @since v1.0.0
 */
export type CellOrUndefined = Cell | undefined;

/**
 * The Values type is the data structure representing all the keyed values in a
 * Store.
 *
 * A Values object is used when setting values with the setValues method, and
 * when getting them back out again with the getValues method. A Values object
 * is a regular JavaScript object containing individual Value objects, keyed by
 * their Id.
 * @example
 * ```js
 * import type {Values} from 'tinybase';
 *
 * export const values: Values = {open: true, employees: 4};
 * ```
 * @category Store
 * @since v3.0.0
 */
export type Values = {[valueId: Id]: Value};

/**
 * The Value type is the data structure representing the data in a single keyed
 * value.
 *
 * A Value is used when setting a value with the setValue method, and when
 * getting it back out again with the getValue method. A Value is a JavaScript
 * string, number, or boolean.
 * @example
 * ```js
 * import type {Value} from 'tinybase';
 *
 * export const value: Value = 'dog';
 * ```
 * @category Store
 * @since v3.0.0
 */
export type Value = string | number | boolean;

/**
 * The ValueOrUndefined type is a data structure representing the data in a
 * single value, or the value `undefined`.
 *
 * This is used when describing a Value that is present _or_ that is not
 * present, such as when it has been deleted, or when describing a previous
 * state where the Value has since been added.
 * @category Store
 * @since v3.0.0
 */
export type ValueOrUndefined = Value | undefined;

/**
 * The TableCallback type describes a function that takes a Table's Id and a
 * callback to loop over each Row within it.
 *
 * A TableCallback is provided when using the forEachTable method, so that you
 * 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
 * @since v1.0.0
 */
export type TableCallback = (
  tableId: Id,
  forEachRow: (rowCallback: RowCallback) => void,
) => void;

/**
 * The TableCellCallback type describes a function that takes a Cell's Id and
 * the count of times it appears across a whole Table.
 *
 * A TableCellCallback is provided when using the forEachTableCell method, so
 * that you can do something based on every Cell used across a Table. See that
 * method for specific examples.
 * @param cellId The Id of the Cell that the callback can operate on.
 * @param count The number of times this Cell is used across a whole Table.
 * @category Callback
 * @since v1.0.0
 */
export type TableCellCallback = (cellId: Id, count: number) => void;

/**
 * The RowCallback type describes a function that takes a Row's Id and a
 * callback to loop over each Cell within it.
 *
 * A RowCallback is provided when using the forEachRow method, so that you can
 * 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 forEachCell A function that will let you iterate over the Cell values
 * in this Row.
 * @category Callback
 * @since v1.0.0
 */
export type RowCallback = (
  rowId: Id,
  forEachCell: (cellCallback: CellCallback) => void,
) => void;

/**
 * The CellCallback type describes a function that takes a Cell's Id and its
 * value.
 *
 * A CellCallback is provided when using the forEachCell method, so that you can
 * 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
 * @since v1.0.0
 */
export type CellCallback = (cellId: Id, cell: Cell) => void;

/**
 * The ValueCallback type describes a function that takes a Value's Id and its
 * actual value.
 *
 * A ValueCallback is provided when using the forEachValue method, so that you
 * can do something based on every Value in a Store. See that method for
 * specific examples.
 * @param valueId The Id of the Value that the callback can operate on.
 * @param value The Value itself.
 * @category Callback
 * @since v3.0.0
 */
export type ValueCallback = (valueId: Id, value: Value) => void;

/**
 * The MapCell type describes a function that takes an existing Cell value and
 * returns another.
 *
 * A MapCell can be provided in the setCell method to map an existing value to a
 * 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
 * @since v1.0.0
 */
export type MapCell = (cell: CellOrUndefined) => Cell;

/**
 * The MapValue type describes a function that takes an existing Value and
 * returns another.
 *
 * A MapValue can be provided in the setValue method to map an existing Value to
 * a new one, such as when incrementing a number. See that method for specific
 * examples.
 * @param value The current Value to map to a new Value.
 * @category Callback
 * @since v3.0.0
 */
export type MapValue = (value: ValueOrUndefined) => Value;

/**
 * The GetCell type describes a function that takes a Id and returns the Cell
 * value for a particular Row.
 *
 * A GetCell can be provided when setting definitions, as in the
 * 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
 * @since v1.0.0
 */
export type GetCell = (cellId: Id) => CellOrUndefined;

/**
 * The IdAddedOrRemoved type describes a change made to an Id in either the
 * tabular or keyed-value part of the Store (or in other TinyBase modules).
 *
 * This type is used in other types like ChangedTableIds, ChangedRowIds,
 * ChangedCellIds, and ChangedValueIds, as well as in other events or listeners
 * where a list of Ids has changed.
 *
 * It is a simple number: a 1 indicates that a given Id was added to a list of
 * Ids, and a -1 indicates that it was removed.
 * @category Transaction
 * @since v4.0.0
 */
export type IdAddedOrRemoved = 1 | -1;

/**
 * The ChangedTableIds type describes the Table Ids that were added or removed
 * during a transaction.
 *
 * It is available to the DoRollback function and to a TransactionListener
 * function via the TransactionLog object.
 *
 * It is a simple object that has Table Id as key, and an IdAddedOrRemoved
 * number indicating whether the Table Id was added (1) or removed (-1).
 *
 * Note that there will be no entry if the content of the Table itself changed.
 * For that you should consult the ChangedRowIds, ChangedCellIds, or
 * ChangedCells types.
 * @category Transaction
 * @since v4.0.0
 */
export type ChangedTableIds = {[tableId: Id]: IdAddedOrRemoved};

/**
 * The ChangedRowIds type describes the Row Ids that were added or removed
 * during a transaction.
 *
 * It is available to the DoRollback function and to a TransactionListener
 * function via the TransactionLog object.
 *
 * It is a nested object that has Table Id as a top-level key, and then Row Id
 * as an inner key. The values of the inner objects are IdAddedOrRemoved numbers
 * indicating whether the Row Id was added (1) or removed (-1) to the given
 * Table.
 *
 * Note that there will be no entry if the content of the Row itself changed.
 * For that you should consult the ChangedCellIds or ChangedCells types.
 * @category Transaction
 * @since v4.0.0
 */
export type ChangedRowIds = {[tableId: Id]: {[rowId: Id]: IdAddedOrRemoved}};

/**
 * The ChangedCellIds type describes the Cell Ids that were added or removed
 * during a transaction.
 *
 * It is available to the DoRollback function and to a TransactionListener
 * function via the TransactionLog object.
 *
 * It is a nested object that has Table Id as a top-level key, and Row Id, and
 * then CellId as inner keys. The values of the inner objects are
 * IdAddedOrRemoved numbers indicating whether the Cell Id was added (1) or
 * removed (-1) to the given Row.
 *
 * Note that there will be no entry if the content of the Cell itself changed.
 * For that you should consult the ChangedCells type.
 * @category Transaction
 * @since v4.0.0
 */
export type ChangedCellIds = {
  [tableId: Id]: {[rowId: Id]: {[cellId: Id]: IdAddedOrRemoved}};
};

/**
 * The ChangedValueIds type describes the Value Ids that were added or removed
 * during a transaction.
 *
 * It is available to the DoRollback function and to a TransactionListener
 * function via the TransactionLog object.
 *
 * It is a simple object that has Value Id as key, and an IdAddedOrRemoved
 * number indicating whether the Value Id was added (1) or removed (-1).
 *
 * Note that there will be no entry if the content of the Value itself changed.
 * For that you should consult the ChangedValues type.
 * @category Transaction
 * @since v4.0.0
 */
export type ChangedValueIds = {[valueId: Id]: IdAddedOrRemoved};

/**
 * The DoRollback type describes a function that you can use to rollback the
 * transaction if it did not complete to your satisfaction.
 *
 * A DoRollback can be provided when calling the transaction method or the
 * finishTransaction method. See those methods for specific examples.
 *
 * Since v5.0, this function is called with the Store as a single argument. You
 * can use the getTransactionChanges method and getTransactionLog method of the
 * Store directly to decide whether to do the rollback.
 * @param store A reference to the Store that is completing a transaction.
 * @category Callback
 * @since v1.0.0
 */
export type DoRollback = (store: Store) => boolean;

/**
 * The TransactionListener type describes a function that is used to listen to
 * the completion of a transaction for the Store.
 *
 * A TransactionListener is provided when using the
 * addWillFinishTransactionListener and addDidFinishTransactionListener methods.
 * See those methods for specific examples.
 *
 * Since v5.0, this listener is called with no arguments other than the Store.
 * You can use the getTransactionChanges method and getTransactionLog method of
 * the Store directly to get information about the changes made within the
 * transaction.
 * @param store A reference to the Store that is completing a transaction.
 * @category Listener
 * @since v1.0.0
 */
export type TransactionListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
) => void;

/**
 * The HasTablesListener type describes a function that is used to listen to
 * Tables as a whole being added to or removed from the Store.
 *
 * A HasTablesListener is provided when using the addHasTablesListener method.
 * See that method for specific examples.
 *
 * When called, a HasTablesListener is given a reference to the Store. It is
 * also given a flag to indicate whether Tables now exist (having not done
 * previously), or do not (having done so previously).
 * @param store A reference to the Store that changed.
 * @param hasTables Whether Tables now exist or not.
 * @category Listener
 * @since v4.4.0
 */
export type HasTablesListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  hasTables: boolean,
) => void;

/**
 * The TablesListener type describes a function that is used to listen to
 * changes to the tabular part of the Store.
 *
 * A TablesListener is provided when using the addTablesListener method. See
 * that method for specific examples.
 *
 * When called, a TablesListener is given a reference to the Store and a
 * GetCellChange function that can be used to query Cell values before and after
 * the current transaction.
 *
 * Note that if the listener was manually forced to be called (with the
 * 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
 * @since v1.0.0
 */
export type TablesListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  getCellChange: GetCellChange | undefined,
) => void;

/**
 * The TableIdsListener type describes a function that is used to listen to
 * changes to the Table Ids in the Store.
 *
 * A TableIdsListener is provided when using the addTableIdsListener method. See
 * that method for specific examples.
 *
 * When called, a TableIdsListener is given a reference to the Store.
 *
 * Since v3.3, the listener is also passed a GetIdChanges function that can be
 * used to query which Ids changed during the transaction.
 * @param store A reference to the Store that changed.
 * @param getIdChanges A function that returns information about the Id changes,
 * since v3.3.
 * @category Listener
 * @since v1.0.0
 */
export type TableIdsListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  getIdChanges: GetIdChanges | undefined,
) => void;

/**
 * The HasTableListener type describes a function that is used to listen to a
 * Table being added to or removed from the Store.
 *
 * A HasTableListener is provided when using the addHasTableListener method. See
 * that method for specific examples.
 *
 * When called, a HasTableListener is given a reference to the Store, and the Id
 * of the Table that changed. It is also given a flag to indicate whether the
 * Table now exists (having not done previously), or does not (having done so
 * previously).
 * @param store A reference to the Store that changed.
 * @param tableId The Id of the Table that changed.
 * @param hasTable Whether the Table now exists or not.
 * @category Listener
 * @since v4.4.0
 */
export type HasTableListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  hasTable: boolean,
) => void;

/**
 * The TableListener type describes a function that is used to listen to changes
 * to a Table.
 *
 * A TableListener is provided when using the addTableListener method. See that
 * method for specific examples.
 *
 * When called, a TableListener is given a reference to the Store, the Id of the
 * Table that changed, and a GetCellChange function that can be used to query
 * Cell values before and after the current transaction.
 *
 * Note that if the listener was manually forced to be called (with the
 * 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
 * @since v1.0.0
 */
export type TableListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  getCellChange: GetCellChange | undefined,
) => void;

/**
 * The TableCellIdsListener type describes a function that is used to listen to
 * changes to the Cell Ids that appear anywhere in a Table.
 *
 * A TableCellIdsListener is provided when using the addTableCellIdsListener
 * method. See that method for specific examples.
 *
 * When called, a TableCellIdsListener is given a reference to the Store, the Id
 * of the Table whose Cell Ids changed, and a GetIdChanges function that can be
 * used to query which Ids changed during the transaction.
 * @param store A reference to the Store that changed.
 * @param tableId The Id of the Table that changed.
 * @param getIdChanges A function that returns information about the Id changes.
 * @category Listener
 * @since v3.3.0
 */
export type TableCellIdsListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  getIdChanges: GetIdChanges | undefined,
) => void;

/**
 * The HasTableCellListener type describes a function that is used to listen to
 * a Cell being added to or removed from a Table as a whole.
 *
 * A HasTableCellListener is provided when using the addHasTableCellListener
 * method. See that method for specific examples.
 *
 * When called, a HasTableCellListener is given a reference to the Store, the Id
 * of the Table that changed, and the Id of the Cell that changed. It is also
 * given a flag to indicate whether the Cell now exists anywhere in the Table
 * (having not done previously), or does not (having done so previously).
 * @param store A reference to the Store that changed.
 * @param tableId The Id of the Table that changed.
 * @param cellId The Id of the Table Cell that changed.
 * @param hasTableCell Whether the Cell now exists anywhere in the Table or not.
 * @category Listener
 * @since v4.4.0
 */
export type HasTableCellListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  cellId: Id,
  hasTableCell: boolean,
) => void;

/**
 * The RowCountListener type describes a function that is used to listen to
 * changes to the number of Row objects in a Table.
 *
 * A RowCountListener is provided when using the addRowCountListener method. See
 * that method for specific examples.
 *
 * When called, a RowCountListener is given a reference to the Store, the Id of
 * the Table whose Row Ids changed, and the number of Row objects in the Table.
 * @param store A reference to the Store that changed.
 * @param tableId The Id of the Table that changed.
 * @param count The number of Row objects in the Table.
 * @category Listener
 * @since v4.1.0
 */
export type RowCountListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  count: number,
) => void;

/**
 * The RowIdsListener type describes a function that is used to listen to
 * changes to the Row Ids in a Table.
 *
 * A RowIdsListener is provided when using the addRowIdsListener method. See
 * that method for specific examples.
 *
 * When called, a RowIdsListener is given a reference to the Store, and the Id
 * of the Table whose Row Ids changed.
 *
 * Since v3.3, the listener is also passed a GetIdChanges function that can be
 * used to query which Ids changed during the transaction.
 * @param store A reference to the Store that changed.
 * @param tableId The Id of the Table that changed.
 * @param getIdChanges A function that returns information about the Id changes,
 * since v3.3.
 * @category Listener
 * @since v1.0.0
 */
export type RowIdsListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  getIdChanges: GetIdChanges | undefined,
) => void;

/**
 * The SortedRowIdsListener type describes a function that is used to listen to
 * changes to sorted Row Ids in a Table.
 *
 * A SortedRowIdsListener is provided when using the addSortedRowIdsListener
 * method. See that method for specific examples.
 *
 * When called, a SortedRowIdsListener is given a reference to the Store, the Id
 * of the Table whose Row Ids sorting changed, the Cell Id being used to sort
 * them, whether descending or not, and the offset and limit of the number of
 * Ids returned, for pagination purposes. 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 getSortedRowIds.
 * @param store A reference to the Store that changed.
 * @param tableId The Id of the Table whose sorted Row Ids changed.
 * @param cellId The Id of the Cell whose values were used for the sorting.
 * @param descending Whether the sorting was in descending order.
 * @param offset The number of Row Ids skipped.
 * @param limit The maximum number of Row Ids returned.
 * @param sortedRowIds The sorted Row Ids themselves.
 * @category Listener
 * @since v2.0.0
 */
export type SortedRowIdsListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  cellId: Id | undefined,
  descending: boolean,
  offset: number,
  limit: number | undefined,
  sortedRowIds: Ids,
) => void;

/**
 * The HasRowListener type describes a function that is used to listen to a Row
 * being added to or removed from the Store.
 *
 * A HasRowListener is provided when using the addHasRowListener method. See
 * that method for specific examples.
 *
 * When called, a HasRowListener is given a reference to the Store, the Id of
 * the Table that changed, and the Id of the Row that changed. It is also given
 * a flag to indicate whether the Row now exists (having not done previously),
 * or does not (having done so previously).
 * @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 hasRow Whether the Row now exists or not.
 * @category Listener
 * @since v4.4.0
 */
export type HasRowListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  rowId: Id,
  hasRow: boolean,
) => void;

/**
 * The RowListener type describes a function that is used to listen to changes
 * to a Row.
 *
 * A RowListener is provided when using the addRowListener method. See that
 * method for specific examples.
 *
 * When called, a RowListener is given a reference to the Store, the Id of the
 * Table that changed, the Id of the Row that changed, and a GetCellChange
 * function that can be used to query Cell values before and after the current
 * transaction.
 *
 * Note that if the listener was manually forced to be called (with the
 * 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
 * @since v1.0.0
 */
export type RowListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  rowId: Id,
  getCellChange: GetCellChange | undefined,
) => void;

/**
 * The CellIdsListener type describes a function that is used to listen to
 * changes to the Cell Ids in a Row.
 *
 * A CellIdsListener is provided when using the addCellIdsListener method. See
 * that method for specific examples.
 *
 * 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.
 *
 * Since v3.3, the listener is also passed a GetIdChanges function that can be
 * used to query which Ids changed during the transaction.
 * @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 getIdChanges A function that returns information about the Id changes,
 * since v3.3.
 * @category Listener
 * @since v1.0.0
 */
export type CellIdsListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  rowId: Id,
  getIdChanges: GetIdChanges | undefined,
) => void;

/**
 * The HasCellListener type describes a function that is used to listen to a
 * Cell being added to or removed from the Store.
 *
 * A HasCellListener is provided when using the addHasCellListener method. See
 * that method for specific examples.
 *
 * When called, a HasCellListener is given a reference to the Store, the Id of
 * the Table that changed, the Id of the Row that changed, and the Id of Cell
 * that changed. It is also given a flag to indicate whether the Cell now exists
 * (having not done previously), or does not (having done so previously).
 * @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 hasCell Whether the Cell now exists or not.
 * @category Listener
 * @since v4.4.0
 */
export type HasCellListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  rowId: Id,
  cellId: Id,
  hasCell: boolean,
) => void;

/**
 * The CellListener type describes a function that is used to listen to changes
 * to a Cell.
 *
 * A CellListener is provided when using the addCellListener method. See that
 * method for specific examples.
 *
 * When called, a CellListener is given a reference to the Store, the Id of the
 * Table that changed, the Id of the Row that changed, and the Id of Cell that
 * changed. It is also given the new value of the Cell, the old value of the
 * Cell, and a GetCellChange function that can be used to query Cell values
 * before and after the current transaction.
 *
 * Note that if the listener was manually forced to be called (with the
 * callListener method rather than due to a real change in the Store), the
 * 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
 * @since v1.0.0
 */
export type CellListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  rowId: Id,
  cellId: Id,
  newCell: Cell,
  oldCell: Cell,
  getCellChange: GetCellChange | undefined,
) => void;

/**
 * The HasValuesListener type describes a function that is used to listen to
 * Values as a whole being added to or removed from the Store.
 *
 * A HasValuesListener is provided when using the addHasValuesListener method.
 * See that method for specific examples.
 *
 * When called, a HasValuesListener is given a reference to the Store. It is
 * also given a flag to indicate whether Values now exist (having not done
 * previously), or do not (having done so previously).
 * @param store A reference to the Store that changed.
 * @param hasValues Whether Values now exist or not.
 * @category Listener
 * @since v4.4.0
 */
export type HasValuesListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  hasValues: boolean,
) => void;

/**
 * The ValuesListener type describes a function that is used to listen to
 * changes to all the Values in a Store.
 *
 * A ValuesListener is provided when using the addValuesListener method. See
 * that method for specific examples.
 *
 * When called, a ValuesListener is given a reference to the Store and a
 * GetValueChange function that can be used to query Values before and after the
 * current transaction.
 *
 * Note that if the listener was manually forced to be called (with the
 * callListener method rather than due to a real change in the Store), the
 * GetValueChange function will not be present.
 * @param store A reference to the Store that changed.
 * @param getValueChange A function that returns information about any Value's
 * changes.
 * @category Listener
 * @since v1.0.0
 */
export type ValuesListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  getValueChange: GetValueChange | undefined,
) => void;

/**
 * The ValueIdsListener type describes a function that is used to listen to
 * changes to the Value Ids in a Store.
 *
 * A ValueIdsListener is provided when using the addValueIdsListener method. See
 * that method for specific examples.
 *
 * When called, a ValueIdsListener is given a reference to the Store.
 *
 * Since v3.3, the listener is also passed a GetIdChanges function that can be
 * used to query which Ids changed during the transaction.
 * @param store A reference to the Store that changed.
 * @param getIdChanges A function that returns information about the Id changes,
 * since v3.3.
 * @category Listener
 * @since v1.0.0
 */
export type ValueIdsListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  getIdChanges: GetIdChanges | undefined,
) => void;

/**
 * The HasValueListener type describes a function that is used to listen to a
 * Value being added to or removed from the Store.
 *
 * A HasValueListener is provided when using the addHasValueListener method. See
 * that method for specific examples.
 *
 * When called, a HasValueListener is given a reference to the Store and the Id
 * of Value that changed. It is also given a flag to indicate whether the Value
 * now exists (having not done previously), or does not (having done so
 * previously).
 * @param store A reference to the Store that changed.
 * @param valueId The Id of the Value that changed.
 * @param hasValue Whether the Value now exists or not.
 * @category Listener
 * @since v4.4.0
 */
export type HasValueListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  valueId: Id,
  hasValue: boolean,
) => void;

/**
 * The ValueListener type describes a function that is used to listen to changes
 * to a Value.
 *
 * A ValueListener is provided when using the addValueListener method. See that
 * method for specific examples.
 *
 * When called, a ValueListener is given a reference to the Store and the Id of
 * Value that changed. It is also given the new value of the Value, the old
 * value of the Value, and a GetValueChange function that can be used to query
 * Values before and after the current transaction.
 *
 * Note that if the listener was manually forced to be called (with the
 * callListener method rather than due to a real change in the Store), the
 * GetValueChange function will not be present and the new and old values of the
 * Value will be the same.
 * @param store A reference to the Store that changed.
 * @param valueId The Id of the Value that changed.
 * @param newValue The new value of the Value that changed.
 * @param oldValue The old value of the Value that changed.
 * @param getValueChange A function that returns information about any Value's
 * changes.
 * @category Listener
 * @since v3.0.0
 */
export type ValueListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  valueId: Id,
  newValue: Value,
  oldValue: Value,
  getValueChange: GetValueChange | undefined,
) => void;

/**
 * The InvalidCellListener type describes a function that is used to listen to
 * attempts to set invalid data to a Cell.
 *
 * An InvalidCellListener is provided when using the addInvalidCellListener
 * method. See that method for specific examples.
 *
 * When called, an InvalidCellListener is given a reference to the Store, the Id
 * of the Table, the Id of the Row, and the Id of Cell that was being attempted
 * to be changed. It is also given the invalid value of the Cell, which could
 * have been of absolutely any type. Since there could have been multiple failed
 * attempts to set the Cell within a single transaction, this is an array
 * containing each attempt, chronologically.
 * @param store A reference to the Store that was being changed.
 * @param tableId The Id of the Table that was being changed.
 * @param rowId The Id of the Row that was being changed.
 * @param cellId The Id of the Cell that was being changed.
 * @param invalidCells An array of the values of the Cell that were invalid.
 * @category Listener
 * @since v1.1.0
 */
export type InvalidCellListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  tableId: Id,
  rowId: Id,
  cellId: Id,
  invalidCells: any[],
) => void;

/**
 * The InvalidValueListener type describes a function that is used to listen to
 * attempts to set invalid data to a Value.
 *
 * An InvalidValueListener is provided when using the addInvalidValueListener
 * method. See that method for specific examples.
 *
 * When called, an InvalidValueListener is given a reference to the Store and
 * the Id of Value that was being attempted to be changed. It is also given the
 * invalid value of the Value, which could have been of absolutely any type.
 * Since there could have been multiple failed attempts to set the Value within
 * a single transaction, this is an array containing each attempt,
 * chronologically.
 * @param store A reference to the Store that was being changed.
 * @param valueId The Id of the Value that was being changed.
 * @param invalidValues An array of the Values that were invalid.
 * @category Listener
 * @since v3.0.0
 */
export type InvalidValueListener<Store extends StoreAlias = StoreAlias> = (
  store: Store,
  valueId: Id,
  invalidValues: any[],
) => void;

/**
 * The GetIdChanges type describes a function that returns information about the
 * changes to a set of Ids during a transaction.
 *
 * A GetIdChanges function is provided to every listener when called due Ids in
 * the Store changing. It returns an object where each key is an Id that
 * changed. The listener can then easily identify which Ids have been added
 * (those with the value `1`), and which have been removed (those with the value
 * `-1`).
 * @returns An object keyed by Id with a numerical value. 1 means the Id was
 * added, and 1 means it was removed.
 * @category Listener
 * @since v3.3.0
 */
export type GetIdChanges = () => {[id: Id]: 1 | -1};

/**
 * 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
 * @since v1.0.0
 */
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
 * @since v1.0.0
 */
export type CellChange = [
  changed: boolean,
  oldCell: CellOrUndefined,
  newCell: CellOrUndefined,
];

/**
 * The GetValueChange type describes a function that returns information about
 * any Value's changes during a transaction.
 *
 * A GetValueChange function is provided to every listener when called due the
 * Store changing. The listener can then fetch the previous value of a Value
 * before the current transaction, the new value after it, and a convenience
 * flag that indicates that the value has changed.
 * @param valueId The Id of the Value to inspect.
 * @returns A ValueChange array containing information about the Value's
 * changes.
 * @category Listener
 * @since v1.0.0
 */
export type GetValueChange = (valueId: Id) => ValueChange;

/**
 * The ValueChange type describes a Value's changes during a transaction.
 *
 * This is returned by the GetValueChange function that is provided to every
 * listener when called. This array contains the previous value of a Value
 * before the current transaction, the new value after it, and a convenience
 * flag that indicates that the value has changed.
 * @category Listener
 * @since v1.0.0
 */
export type ValueChange = [
  changed: boolean,
  oldValue: ValueOrUndefined,
  newValue: ValueOrUndefined,
];

/**
 * The ChangedCells type describes the Cell values that have been changed during
 * a transaction, primarily used so that you can indicate whether the
 * transaction should be rolled back.
 *
 * A ChangedCells object is provided to the `doRollback` callback when using the
 * transaction method and the finishTransaction method. See those methods for
 * specific examples.
 *
 * This type is a nested structure of Table, Row, and Cell objects, much like
 * the Tables object, but one which provides both the old and new Cell values in
 * a two-part array. These are describing the state of each changed Cell in
 * Store at the _start_ of the transaction, and by the _end_ of the transaction.
 *
 * Hence, an `undefined` value for the first item in the array means that the
 * Cell was added during the transaction. An `undefined` value for the second
 * item in the array means that the Cell was removed during the transaction. An
 * array with two different Cell values indicates that it was changed. The
 * two-part array will never contain two items of the same value (including two
 * `undefined` values), even if, during the transaction, a Cell was changed to a
 * different value and then changed back.
 * @category Transaction
 * @since v1.2.0
 */
export type ChangedCells = {
  [tableId: Id]: {[rowId: Id]: {[cellId: Id]: ChangedCell}};
};

/**
 * The ChangedCell type describes a Cell that has been changed during a
 * transaction, primarily used so that you can indicate whether the transaction
 * should be rolled back.
 *
 * It provides both the old and new Cell values in a two-part array. These are
 * describing the state of the changed Cell in the Store at the _start_ of the
 * transaction, and by the _end_ of the transaction.
 *
 * Hence, an `undefined` value for the first item in the array means that the
 * Cell was added during the transaction. An `undefined` value for the second
 * item in the array means that the Cell was removed during the transaction. An
 * array with two different Cell values indicates that it was changed. The
 * two-part array will never contain two items of the same value (including two
 * `undefined` values), even if, during the transaction, a Cell was changed to a
 * different value and then changed back.
 * @category Transaction
 * @since v1.2.0
 */
export type ChangedCell = [oldCell: CellOrUndefined, newCell: CellOrUndefined];

/**
 * The InvalidCells type describes the invalid Cell values that have been
 * attempted during a transaction, primarily used so that you can indicate
 * whether the transaction should be rolled back.
 *
 * An InvalidCells object is provided to the `doRollback` callback when using
 * the transaction method and the finishTransaction method. See those methods
 * for specific examples.
 *
 * This type is a nested structure of Table, Row, and Cell objects, much like
 * the Tables object, but one for which Cell values are listed in array (much
 * like the InvalidCellListener type) so that multiple failed attempts to change
 * a Cell during the transaction are described.
 * @category Transaction
 * @since v1.2.0
 */
export type InvalidCells = {
  [tableId: Id]: {[rowId: Id]: {[cellId: Id]: any[]}};
};

/**
 * The ChangedValues type describes the Values that have been changed during a
 * transaction, primarily used so that you can indicate whether the transaction
 * should be rolled back.
 *
 * A ChangedValues object is provided to the `doRollback` callback when using
 * the transaction method and the finishTransaction method. See those methods
 * for specific examples.
 *
 * This type is an object containing the old and new Values in two-part arrays.
 * These are describing the state of each changed Value in Store at the _start_
 * of the transaction, and by the _end_ of the transaction.
 *
 * Hence, an `undefined` value for the first item in the array means that the
 * Value was added during the transaction. An `undefined` value for the second
 * item in the array means that the Value was removed during the transaction. An
 * array with two different Values indicates that it was changed. The two-part
 * array will never contain two items of the same value (including two
 * `undefined` values), even if, during the transaction, a Value was changed to
 * a different value and then changed back.
 * @category Transaction
 * @since v3.0.0
 */
export type ChangedValues = {
  [valueId: Id]: ChangedValue;
};

/**
 * The ChangedValue type describes a Value that has been changed during a
 * transaction, primarily used so that you can indicate whether the transaction
 * should be rolled back.
 *
 * It provides both the the old and new Values in a two-part array. These
 * describe the state of the changed Value in the Store at the _start_ of the
 * transaction, and by the _end_ of the transaction.
 *
 * Hence, an `undefined` value for the first item in the array means that the
 * Value was added during the transaction. An `undefined` value for the second
 * item in the array means that the Value was removed during the transaction. An
 * array with two different Values indicates that it was changed. The two-part
 * array will never contain two items of the same value (including two
 * `undefined` values), even if, during the transaction, a Value was changed to
 * a different value and then changed back.
 * @category Transaction
 * @since v3.0.0
 */
export type ChangedValue = [
  oldValue: ValueOrUndefined,
  newValue: ValueOrUndefined,
];

/**
 * The InvalidValues type describes the invalid Values that have been attempted
 * during a transaction, primarily used so that you can indicate whether the
 * transaction