tinybase 0.0.0 → 0.9.3

package/lib/indexes.d.ts

@@ -0,0 +1,829 @@
+/**
+ * The indexes module of the TinyBase project provides the ability to create
+ * 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
+ * listeners for when they change.
+ *
+ * @packageDocumentation
+ * @module indexes
+ */
+
+import {GetCell, Store} from './store.d';
+import {Id, IdOrNull, Ids} from './common.d';
+
+/**
+ * The Index type represents the concept of a map of Slice objects, keyed by Id.
+ *
+ * The Ids in a Slice represent Row objects from a Table that all have a derived
+ * string value in common, as described by the setIndexDefinition method. Those
+ * values are used as the key for each Slice in the overall Index object.
+ *
+ * Note that the Index type is not actually used in the API, and you instead
+ * enumerate and access its structure with the getSliceIds method and
+ * getSliceRowIds method.
+ *
+ * @category Concept
+ */
+export type Index = {[sliceId: Id]: Slice};
+
+/**
+ * The Slice type represents the concept of a set of Row objects that comprise
+ * part of an Index.
+ *
+ * The Ids in a Slice represent Row objects from a Table that all have a derived
+ * string value in common, as described by the setIndexDefinition method.
+ *
+ * Note that the Slice type is not actually used in the API, and you instead get
+ * Row Ids directly with the getSliceRowIds method.
+ *
+ * @category Concept
+ */
+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.
+ *
+ * A SliceIdsListener is provided when using the addSliceIdsListener method. See
+ * that method for specific examples.
+ *
+ * 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;
+
+/**
+ * The SliceRowIdsListener type describes a function that is used to listen to
+ * changes to the Row Ids in a Slice.
+ *
+ * A SliceRowIdsListener is provided when using the addSliceRowIdsListener
+ * method. See that method for specific examples.
+ *
+ * When called, a SliceRowIdsListener is given a reference to the Indexes
+ * 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 = (
+  indexes: Indexes,
+  indexId: Id,
+  sliceId: Id,
+) => void;
+
+/**
+ * The IndexesListenerStats type describes the number of listeners registered
+ * with the Indexes object, and can be used for debugging purposes.
+ *
+ * A IndexesListenerStats object is returned from the getListenerStats method,
+ * and is only populated in a debug build.
+ *
+ * @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;
+};
+
+/**
+ * An Indexes object lets you look up all the Row objects in a Table that have a
+ * certain Cell value.
+ *
+ * This is useful for creating filtered views of a Table, or simple search
+ * functionality.
+ *
+ * Create an Indexes object easily with the createIndexes function. From there,
+ * you can add new Index definitions (with the setIndexDefinition method), query
+ * their contents (with the getSliceIds method and getSliceRowIds method), and
+ * add listeners for when they change (with the addSliceIdsListener method and
+ * addSliceRowIdsListener method).
+ *
+ * This module defaults to indexing Row objects by one of their Cell values.
+ * However, far more complex indexes can be configured with a custom function.
+ *
+ * @example
+ * This example shows a very simple lifecycle of an Indexes object: from
+ * creation, to adding a definition, getting its contents, and then registering
+ * and removing a listener for it.
+ *
+ * ```js
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ *
+ * const indexes = createIndexes(store);
+ * indexes.setIndexDefinition(
+ *   'bySpecies', // indexId
+ *   'pets', //      tableId to index
+ *   'species', //   cellId to index
+ * );
+ *
+ * console.log(indexes.getSliceIds('bySpecies'));
+ * // -> ['dog', 'cat']
+ * console.log(indexes.getSliceRowIds('bySpecies', 'dog'));
+ * // -> ['fido', 'cujo']
+ *
+ * const listenerId = indexes.addSliceIdsListener('bySpecies', () => {
+ *   console.log(indexes.getSliceIds('bySpecies'));
+ * });
+ * store.setRow('pets', 'lowly', {species: 'worm'});
+ * // -> ['dog', 'cat', 'worm']
+ *
+ * indexes.delListener(listenerId);
+ * indexes.destroy();
+ * ```
+ * @category Indexes
+ */
+export interface Indexes {
+  /**
+   * The setIndexDefinition method lets you set the definition of an Index.
+   *
+   * Every Index definition is identified by a unique Id, and if you re-use an
+   * existing Id with this method, the previous definition is overwritten.
+   *
+   * An Index is a keyed map of Slice objects, each of which is a list of Row
+   * Ids from a given Table. Therefore the definition must specify the Table (by
+   * its Id) to be indexed.
+   *
+   * The Ids in a Slice represent Row objects from a Table that all have a
+   * derived string value in common, as described by this method. Those values
+   * are used as the key for each Slice in the overall Index object.
+   *
+   * Without the third `getSliceId` parameter, the Index will simply have a
+   * single Slice, keyed by an empty string. But more often you will specify a
+   * Cell value containing the Slice Id that the Row should belong to.
+   * Alternatively, a custom function can be provided that produces your own
+   * Slice Id from the local Row as a whole.
+   *
+   * The fourth `getSortKey` parameter specifies a Cell Id to get a value (or a
+   * function that processes a whole Row to get a value) that is used to sort
+   * the Row Ids within each Slice in the Index.
+   *
+   * The fifth parameter, `sliceIdSorter`, lets you specify a way to sort the
+   * Slice Ids when you access the Index, which may be useful if you are trying
+   * to create an alphabetic Index of Row entries. If not specified, the order
+   * of the Slice Ids will match the order of Row insertion.
+   *
+   * The final parameter, `rowIdSorter`, lets you specify a way to sort the Row
+   * Ids within each Slice, based on the `getSortKey` parameter. This may be
+   * useful if you are trying to keep Rows in a determined order relative to
+   * each other in the Index. If omitted, the Row Ids are sorted alphabetically,
+   * based on the `getSortKey` parameter.
+   *
+   * The two 'sorter' parameters, `sliceIdSorter` and `rowIdSorter`, are
+   * functions that take two values and return a positive or negative number for
+   * when they are in the wrong or right order, respectively. This is exactly
+   * the same as the 'compareFunction' that is used in the standard JavaScript
+   * array `sort` method, with the addition that `rowIdSorter` also takes the
+   * Slice Id parameter, in case you want to sort Row Ids differently in each
+   * Slice. You can use the convenient defaultSorter function to default this to
+   * be alphanumeric.
+   *
+   * @param indexId The Id of the Index to define.
+   * @param tableId The Id of the Table the Index will be generated from.
+   * @param getSliceId Either the Id of the Cell containing, or a function that
+   * produces, the Id that is used to indicate which Slice in the Index the Row
+   * Id should be in. Defaults to a function that returns `''` (meaning that if
+   * this `getSliceId` parameter is omitted, the Index will simply contain a
+   * single Slice containing all the Row Ids in the Table).
+   * @param getSortKey Either the Id of the Cell containing, or a function that
+   * produces, the value that is used to sort the Row Ids in each Slice.
+   * @param sliceIdSorter A function that takes two Slice Id values and returns
+   * a positive or negative number to indicate how they should be sorted.
+   * @param rowIdSorter A function that takes two Row Id values (and a slice Id)
+   * and returns a positive or negative number to indicate how they should be
+   * sorted.
+   * @returns A reference to the Indexes object.
+   * @example
+   * This example creates a Store, creates an Indexes object, and defines a
+   * simple Index based on the values in the `species` Cell.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * console.log(indexes.getSliceIds('bySpecies'));
+   * // -> ['dog', 'cat']
+   * console.log(indexes.getSliceRowIds('bySpecies', 'dog'));
+   * // -> ['fido', 'cujo']
+   * ```
+   * @example
+   * This example creates a Store, creates an Indexes object, and defines an
+   * Index based on the first letter of the pets' names.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('byFirst', 'pets', (_, rowId) => rowId[0]);
+   *
+   * console.log(indexes.getSliceIds('byFirst'));
+   * // -> ['f', 'c']
+   * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+   * // -> ['fido', 'felix']
+   * ```
+   * @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.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition(
+   *   'byFirst', //              indexId
+   *   'pets', //                 tableId
+   *   (_, rowId) => rowId[0], // each Row's sliceId
+   *   (_, rowId) => rowId, //    each Row's sort key
+   *   defaultSorter, //          sort Slice Ids
+   *   defaultSorter, //          sort Row Ids
+   * );
+   *
+   * console.log(indexes.getSliceIds('byFirst'));
+   * // -> ['c', 'f']
+   * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+   * // -> ['felix', 'fido']
+   * ```
+   * @category Configuration
+   */
+  setIndexDefinition(
+    indexId: Id,
+    tableId: Id,
+    getSliceId?: Id | ((getCell: GetCell, rowId: Id) => Id),
+    getSortKey?: Id | ((getCell: GetCell, rowId: Id) => SortKey),
+    sliceIdSorter?: (sliceId1: Id, sliceId2: Id) => number,
+    rowIdSorter?: (sortKey1: SortKey, sortKey2: SortKey, sliceId: Id) => number,
+  ): Indexes;
+
+  /**
+   * The delIndexDefinition method removes an existing Index definition.
+   *
+   * @param indexId The Id of the Index to remove.
+   * @returns A reference to the Indexes object.
+   * @example
+   * This example creates a Store, creates an Indexes object, defines a simple
+   * Index, and then removes it.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   * console.log(indexes.getIndexIds());
+   * // -> ['bySpecies']
+   *
+   * indexes.delIndexDefinition('bySpecies');
+   * console.log(indexes.getIndexIds());
+   * // -> []
+   * ```
+   * @category Configuration
+   */
+  delIndexDefinition(indexId: Id): Indexes;
+
+  /**
+   * The getStore method returns a reference to the underlying Store that is
+   * backing this Indexes object.
+   *
+   * @returns A reference to the Store.
+   * @example
+   * This example creates an Indexes object against a newly-created Store and
+   * then gets its reference in order to update its data.
+   *
+   * ```js
+   * const indexes = createIndexes(createStore());
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   * indexes.getStore().setCell('pets', 'fido', 'species', 'dog');
+   * console.log(indexes.getSliceIds('bySpecies'));
+   * // -> ['dog']
+   * ```
+   * @category Getter
+   */
+  getStore(): Store;
+
+  /**
+   * The getIndexIds method returns an array of the Index Ids registered with
+   * this Indexes object.
+   *
+   * @returns An array of Ids.
+   * @example
+   * This example creates an Indexes object with two definitions, and then gets
+   * the Ids of the definitions.
+   *
+   * ```js
+   * const indexes = createIndexes(createStore())
+   *   .setIndexDefinition('bySpecies', 'pets', 'species')
+   *   .setIndexDefinition('byColor', 'pets', 'color');
+   *
+   * console.log(indexes.getIndexIds());
+   * // -> ['bySpecies', 'byColor']
+   * ```
+   * @category Getter
+   */
+  getIndexIds(): Ids;
+
+  /**
+   * The getTableId method returns the Id of the underlying Table that is
+   * backing an Index.
+   *
+   * If the Index Id is invalid, the method returns `undefined`.
+   *
+   * @param indexId The Id of an Index.
+   * @returns The Id of the Table backing the Index, or `undefined`.
+   * @example
+   * 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.
+   *
+   * ```js
+   * const indexes = createIndexes(createStore());
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * console.log(indexes.getTableId('bySpecies'));
+   * // -> 'pets'
+   * console.log(indexes.getTableId('byColor'));
+   * // -> undefined
+   * ```
+   * @category Getter
+   */
+  getTableId(indexId: Id): Id;
+
+  /**
+   * The getSliceIds method gets the list of Slice Ids in an Index.
+   *
+   * If the identified Index does not exist (or if the definition references a
+   * Table that does not exist) then an empty array is returned.
+   *
+   * @param indexId The Id of the Index.
+   * @returns The Slice Ids in the Index, or an empty array.
+   * @example
+   * This example creates a Store, creates an Indexes object, and defines a
+   * 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).
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * console.log(indexes.getSliceIds('bySpecies'));
+   * // -> ['dog', 'cat']
+   * console.log(indexes.getSliceIds('byColor'));
+   * // -> []
+   * ```
+   * @category Getter
+   */
+  getSliceIds(indexId: Id): Ids;
+
+  /**
+   * The getSliceRowIds method gets the list of Row Ids in a given Slice, within
+   * a given Index.
+   *
+   * If the identified Index or Slice do not exist (or if the definition
+   * references a Table that does not exist) then an empty array is returned.
+   *
+   * @param indexId The Id of the Index.
+   * @param sliceId The Id of the Slice in the Index.
+   * @returns The Row Ids in the Slice, or an empty array.
+   * @example
+   * This example creates a Store, creates an Indexes object, and defines a
+   * 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).
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * console.log(indexes.getSliceRowIds('bySpecies', 'dog'));
+   * // -> ['fido', 'cujo']
+   * console.log(indexes.getSliceRowIds('bySpecies', 'worm'));
+   * // -> []
+   * console.log(indexes.getSliceRowIds('byColor', 'brown'));
+   * // -> []
+   * ```
+   * @category Getter
+   */
+  getSliceRowIds(indexId: Id, sliceId: Id): Ids;
+
+  /**
+   * The addSliceIdsListener method registers a listener function with the
+   * Indexes object that will be called whenever the Slice Ids in an Index
+   * change.
+   *
+   * You can either listen to a single Index (by specifying the Index Id as the
+   * method's first parameter), or changes to any Index (by providing a `null`
+   * wildcard).
+   *
+   * The provided listener is a SliceIdsListener function, and will be called
+   * with a reference to the Indexes object, and the Id of the Index that
+   * changed.
+   *
+   * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the Slice Ids in
+   * the Index change.
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @example
+   * This example creates a Store, a Indexes object, and then registers a
+   * listener that responds to any changes to a specific Index.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * const listenerId = indexes.addSliceIdsListener(
+   *   'bySpecies',
+   *   (indexes, indexId) => {
+   *     console.log('Slice Ids for bySpecies index changed');
+   *     console.log(indexes.getSliceIds('bySpecies'));
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'lowly', {species: 'worm'});
+   * // -> 'Slice Ids for bySpecies index changed'
+   * // -> ['dog', 'cat', 'worm']
+   *
+   * indexes.delListener(listenerId);
+   * ```
+   * @example
+   * This example creates a Store, a Indexes object, and then registers a
+   * listener that responds to any changes to any Index.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'brown'},
+   * });
+   *
+   * const indexes = createIndexes(store)
+   *   .setIndexDefinition('bySpecies', 'pets', 'species')
+   *   .setIndexDefinition('byColor', 'pets', 'color');
+   *
+   * const listenerId = indexes.addSliceIdsListener(
+   *   null,
+   *   (indexes, indexId) => {
+   *     console.log(`Slice Ids for ${indexId} index changed`);
+   *     console.log(indexes.getSliceIds(indexId));
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'lowly', {species: 'worm', color: 'pink'});
+   * // -> 'Slice Ids for bySpecies index changed'
+   * // -> ['dog', 'cat', 'worm']
+   * // -> 'Slice Ids for byColor index changed'
+   * // -> ['brown', 'black', 'pink']
+   *
+   * indexes.delListener(listenerId);
+   * ```
+   * @category Listener
+   */
+  addSliceIdsListener(indexId: IdOrNull, listener: SliceIdsListener): Id;
+
+  /**
+   * The addSliceRowIdsListener method registers a listener function with the
+   * Indexes object that will be called whenever the Row Ids in a Slice change.
+   *
+   * You can either listen to a single Slice (by specifying the Index Id and
+   * Slice Id as the method's first two parameters), or changes to any Slice (by
+   * providing `null` wildcards).
+   *
+   * Both, either, or neither of the `indexId` and `sliceId` parameters can be
+   * wildcarded with `null`. You can listen to a specific Slice in a specific
+   * Index, any Slice in a specific Index, a specific Slice in any Index, or any
+   * Slice in any Index.
+   *
+   * The provided listener is a SliceRowIdsListener function, and will be called
+   * with a reference to the Indexes object, the Id of the Index, and the Id of
+   * the Slice that changed.
+   *
+   * @param indexId The Id of the Index to listen to, or `null` as a wildcard.
+   * @param sliceId The Id of the Slice to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the Row Ids in
+   * the Slice change.
+   * @returns A unique Id for the listener that can later be used to remove it.
+   * @example
+   * This example creates a Store, a Indexes object, and then registers a
+   * listener that responds to any changes to a specific Slice.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * const listenerId = indexes.addSliceRowIdsListener(
+   *   'bySpecies',
+   *   'dog',
+   *   (indexes, indexId, sliceId) => {
+   *     console.log('Row Ids for dog slice in bySpecies index changed');
+   *     console.log(indexes.getSliceRowIds('bySpecies', 'dog'));
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'toto', {species: 'dog'});
+   * // -> 'Row Ids for dog slice in bySpecies index changed'
+   * // -> ['fido', 'cujo', 'toto']
+   *
+   * indexes.delListener(listenerId);
+   * ```
+   * @example
+   * This example creates a Store, a Indexes object, and then registers a
+   * listener that responds to any changes to any Slice.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   *
+   * const indexes = createIndexes(store)
+   *   .setIndexDefinition('bySpecies', 'pets', 'species')
+   *   .setIndexDefinition('byColor', 'pets', 'color');
+   *
+   * const listenerId = indexes.addSliceRowIdsListener(
+   *   null,
+   *   null,
+   *   (indexes, indexId, sliceId) => {
+   *     console.log(
+   *       `Row Ids for ${sliceId} slice in ${indexId} index changed`,
+   *     );
+   *     console.log(indexes.getSliceRowIds(indexId, sliceId));
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'toto', {species: 'dog', color: 'brown'});
+   * // -> 'Row Ids for dog slice in bySpecies index changed'
+   * // -> ['fido', 'cujo', 'toto']
+   * // -> 'Row Ids for brown slice in byColor index changed'
+   * // -> ['fido', 'toto']
+   *
+   * indexes.delListener(listenerId);
+   * ```
+   * @category Listener
+   */
+  addSliceRowIdsListener(
+    indexId: IdOrNull,
+    sliceId: IdOrNull,
+    listener: SliceRowIdsListener,
+  ): Id;
+
+  /**
+   * The delListener method removes a listener that was previously added to the
+   * Indexes object.
+   *
+   * Use the Id returned by whichever method was used to add the listener. Note
+   * that the Indexes object may re-use this Id for future listeners added to
+   * it.
+   *
+   * @param listenerId The Id of the listener to remove.
+   * @returns A reference to the Indexes object.
+   * @example
+   * This example creates a Store, a Indexes object, registers a listener, and
+   * then removes it.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * const listenerId = indexes.addSliceIdsListener(
+   *   'bySpecies',
+   *   (indexes, indexId) => {
+   *     console.log('Slice Ids for bySpecies index changed');
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'lowly', {species: 'worm'});
+   * // -> 'Slice Ids for bySpecies index changed'
+   *
+   * indexes.delListener(listenerId);
+   *
+   * store.setRow('pets', 'toto', {species: 'dog'});
+   * // -> undefined
+   * // The listener is not called.
+   * ```
+   * @category Listener
+   */
+  delListener(listenerId: Id): Indexes;
+
+  /**
+   * The destroy method should be called when this Indexes object is no longer
+   * used.
+   *
+   * This guarantees that all of the listeners that the object registered with
+   * the underlying Store are removed and it can be correctly garbage collected.
+   *
+   * @example
+   * This example creates a Store, adds an Indexes object with a
+   * definition (that registers a RowListener with the underlying Store),
+   * and then destroys it again, removing the listener.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   *
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   * console.log(store.getListenerStats().row);
+   * // -> 1
+   *
+   * indexes.destroy();
+   *
+   * console.log(store.getListenerStats().row);
+   * // -> 0
+   * ```
+   * @category Lifecycle
+   */
+  destroy(): void;
+
+  /**
+   * The getListenerStats method provides a set of statistics about the
+   * listeners registered with the Indexes object, and is used for debugging
+   * purposes.
+   *
+   * The IndexesListenerStats object contains a breakdown of the different types
+   * of listener.
+   *
+   * The statistics are only populated in a debug build: production builds
+   * return an empty object. The method is intended to be used during
+   * development to ensure your application is not leaking listener
+   * registrations, for example.
+   *
+   * @returns A IndexesListenerStats object containing Indexes listener
+   * statistics.
+   * @example
+   * This example gets the listener statistics of an Indexes object.
+   *
+   * ```js
+   * const store = createStore();
+   * const indexes = createIndexes(store);
+   * indexes.addSliceIdsListener(null, () => {
+   *   console.log('Slice Ids changed');
+   * });
+   * indexes.addSliceRowIdsListener(null, null, () => {
+   *   console.log('Slice Row Ids changed');
+   * });
+   *
+   * console.log(indexes.getListenerStats());
+   * // -> {sliceIds: 1, sliceRowIds: 1}
+   * ```
+   * @category Development
+   */
+  getListenerStats(): IndexesListenerStats;
+}
+
+/**
+ * The createIndexes function creates an Indexes object, and is the main entry
+ * point into the indexes module.
+ *
+ * It is trivially simple.
+ *
+ * A given Store can only have one Indexes object associated with it. If you
+ * call this function twice on the same Store, your second call will return a
+ * reference to the Indexes object created by the first.
+ *
+ * @param store The Store for which to register Index definitions.
+ * @returns A reference to the new Indexes object.
+ * @example
+ * This example creates an Indexes object.
+ *
+ * ```js
+ * const store = createStore();
+ * const indexes = createIndexes(store);
+ * console.log(indexes.getIndexIds());
+ * // -> []
+ * ```
+ * @example
+ * This example creates an Indexes object, and calls the method a second time
+ * for the same Store to return the same object.
+ *
+ * ```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.
+ *
+ * ```js
+ * const store = createStore();
+ * const indexes = createIndexes(store);
+ * console.log(indexes.getIndexIds());
+ * // -> []
+ * ```
+ * @example
+ * This example creates a Store, creates an Indexes object, and defines an
+ * Index based on the first letter of the pets' names. The Slice Ids (and Row
+ * Ids within them) are alphabetically sorted using the defaultSorter function.
+ *
+ * ```js
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ *
+ * const indexes = createIndexes(store);
+ * indexes.setIndexDefinition(
+ *   'byFirst', //              indexId
+ *   'pets', //                 tableId
+ *   (_, rowId) => rowId[0], // each Row's Slice Id
+ *   (_, rowId) => rowId, //    each Row's sort key
+ *   defaultSorter, //          sort Slice Ids
+ *   defaultSorter, //          sort Row Ids by sort key
+ * );
+ *
+ * console.log(indexes.getSliceIds('byFirst'));
+ * // -> ['c', 'f']
+ * console.log(indexes.getSliceRowIds('byFirst', 'f'));
+ * // -> ['felix', 'fido']
+ * ```
+ * @category Convenience
+ */
+export function defaultSorter(sortKey1: SortKey, sortKey2: SortKey): number;