tinybase 4.0.0-beta.4 → 4.0.0-beta.5.1

package/lib/types/with-schemas/checkpoints.d.ts

@@ -6,7 +6,6 @@
  * returns a new Checkpoints object. From there, you can create new checkpoints,
  * go forwards or backwards to others, and register listeners for when the list
  * of checkpoints change.
- *
  * @packageDocumentation
  * @module checkpoints
  */
@@ -28,7 +27,6 @@ import {OptionalSchemas, Store} from './store.d';
  * - The 'forward' checkpoint Ids that can be rolled forward to (in other words,
  *   the checkpoints in the redo stack for this Store). They are in
  *   chronological order with the newest checkpoint at the end of the array.
- *
  * @category Identity
  */
 export type CheckpointIds = [Ids, Id | undefined, Ids];
@@ -40,7 +38,6 @@ export type CheckpointIds = [Ids, Id | undefined, Ids];
  * A CheckpointCallback is provided when using the forEachCheckpoint method,
  * so that you can do something based on every Checkpoint in the Checkpoints
  * object. See that method for specific examples.
- *
  * @param checkpointId The Id of the Checkpoint that the callback can operate
  * on.
  * @category Callback
@@ -62,7 +59,6 @@ export type CheckpointCallback = (checkpointId: Id, label?: string) => void;
  *
  * When called, a CheckpointIdsListener is given a reference to the Checkpoints
  * object.
- *
  * @param checkpoints A reference to the Checkpoints object that changed.
  * @category Listener
  */
@@ -88,7 +84,6 @@ export type CheckpointIdsListener<Schemas extends OptionalSchemas> = (
  *
  * When called, a CheckpointListener is given a reference to the Checkpoints
  * object, and the Id of the checkpoint whose label changed.
- *
  * @param checkpoints A reference to the Checkpoints object that changed.
  * @param checkpointId The Id of the checkpoint that changed.
  * @category Listener
@@ -105,7 +100,6 @@ export type CheckpointListener<Schemas extends OptionalSchemas> = (
  *
  * A CheckpointsListenerStats object is returned from the getListenerStats
  * method, and is only populated in a debug build.
- *
  * @category Development
  */
 export type CheckpointsListenerStats = {
@@ -137,9 +131,6 @@ export type CheckpointsListenerStats = {
  * Every checkpoint can be given a label which can be used to describe the
  * actions that changed the Store before this checkpoint. This can be useful for
  * interfaces that let users 'Undo [last action]'.
- *
- * You
- *
  * @example
  * This example shows a simple lifecycle of a Checkpoints object: from creation,
  * to adding a checkpoint, getting the list of available checkpoints, and then
@@ -209,7 +200,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * pruned to make room for more recent ones.
    *
    * The default size for a newly-created Checkpoints object is 100.
-   *
    * @param size The number of checkpoints that this Checkpoints object should
    * hold.
    * @returns A reference to the Checkpoints object.
@@ -255,7 +245,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * The optional `label` parameter can be used to describe the actions that
    * changed the Store before this checkpoint. This can be useful for interfaces
    * that let users 'Undo [last action]'.
-   *
    * @param label An optional label to describe the actions leading up to this
    * checkpoint.
    * @returns The Id of the newly-created checkpoint.
@@ -309,7 +298,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * change the label at a later point.
    *
    * You cannot add a label to a checkpoint that does not yet exist.
-   *
    * @param checkpointId The Id of the checkpoint to set the label for.
    * @param label A label to describe the actions leading up to this checkpoint
    * or left undefined if you want to clear the current label.
@@ -354,6 +342,11 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
   /**
    * The getStore method returns a reference to the underlying Store that is
    * backing this Checkpoints object.
+   * @returns A reference to the Store.
+   * @example
+   * This example creates a Checkpoints object against a newly-created Store
+   * and then gets its reference in order to update its data and set a
+   * checkpoint.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -361,12 +354,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * getStore(): Store;
    * ```
    *
-   * @returns A reference to the Store.
-   * @example
-   * This example creates a Checkpoints object against a newly-created Store
-   * and then gets its reference in order to update its data and set a
-   * checkpoint.
-   *
    * ```js
    * const checkpoints = createCheckpoints(createStore());
    * checkpoints.getStore().setCell('pets', 'fido', 'species', 'dog');
@@ -387,7 +374,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * Together, these are sufficient to understand the state of the Checkpoints
    * object and what movement is possible backward or forward through the
    * checkpoint stack.
-   *
    * @returns A CheckpointIds array, containing the checkpoint Ids managed by
    * this Checkpoints object.
    * @example
@@ -426,7 +412,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * object in a functional style. The `checkpointCallback` parameter is a
    * CheckpointCallback function that will be called with the Id of each
    * Checkpoint.
-   *
    * @param checkpointCallback The function that should be called for every
    * Checkpoint.
    * @example
@@ -451,7 +436,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
   /**
    * The hasCheckpoint method returns a boolean indicating whether a given
    * Checkpoint exists in the Checkpoints object.
-   *
    * @param checkpointId The Id of a possible Checkpoint in the Checkpoints
    * object.
    * @returns Whether a Checkpoint with that Id exists.
@@ -477,7 +461,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    *
    * If the checkpoint has had no label provided, this method will return an
    * empty string.
-   *
    * @param checkpointId The Id of the checkpoint to get the label for.
    * @returns A string label for the requested checkpoint, an empty string if it
    * was never set, or `undefined` if the checkpoint does not exist.
@@ -534,7 +517,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    *
    * The provided listener is a CheckpointIdsListener function, and will be
    * called with a reference to the Checkpoints object.
-   *
    * @param listener The function that will be called whenever the checkpoints
    * change.
    * @returns A unique Id for the listener that can later be used to remove it.
@@ -598,7 +580,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * The provided listener is a CheckpointListener function, and will be called
    * with a reference to the Checkpoints object, and the Id of the checkpoint
    * whose label changed.
-   *
    * @param checkpointId The Id of the checkpoint to listen to, or `null` as a
    * wildcard.
    * @param listener The function that will be called whenever the checkpoint
@@ -661,7 +642,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    *
    * Use the Id returned by the addCheckpointIdsListener method. Note that the
    * Checkpoints 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 Checkpoints object.
    * @example
@@ -706,7 +686,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * ```
    *
    * If there is no previous checkpoint to return to, this method has no effect.
-   *
    * @returns A reference to the Checkpoints object.
    * @example
    * This example creates a Store, a Checkpoints object, makes a change and then
@@ -750,7 +729,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * changes, the forwards 'redo' stack will only exist while you do not make
    * changes to the Store. In general the goForward method is expected to be
    * used to redo changes that were just undone.
-   *
    * @returns A reference to the Checkpoints object.
    * @example
    * This example creates a Store, a Checkpoints object, makes a change and then
@@ -831,7 +809,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * ```
    *
    * If there is no checkpoint with the Id specified, this method has no effect.
-   *
    * @param checkpointId The Id of the checkpoint to move to.
    * @returns A reference to the Checkpoints object.
    * @example
@@ -897,7 +874,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * that is the baseline from which all subsequent changes are tracked.
    *
    * If you are listening to
-   *
    * @returns A reference to the Checkpoints object.
    * @example
    * This example creates a Store, a Checkpoints object, adds a listener, makes
@@ -946,7 +922,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    *
    * 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 a Checkpoints object (that registers a
    * CellListener with the underlying Store), and then destroys it again,
@@ -980,7 +955,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
    * 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 CheckpointsListenerStats object containing Checkpoints listener
    * statistics.
    * @example
@@ -1017,7 +991,6 @@ export interface Checkpoints<in out Schemas extends OptionalSchemas> {
  * A given Store can only have one Checkpoints object associated with it. If you
  * call this function twice on the same Store, your second call will return a
  * reference to the Checkpoints object created by the first.
- *
  * @param store The Store for which to set Checkpoints.
  * @returns A reference to the new Checkpoints object.
  * @example

package/lib/types/with-schemas/common.d.ts

@@ -1,7 +1,6 @@
 /**
  * The common module of the TinyBase project provides a small collection of
  * common types used across other modules.
- *
  * @packageDocumentation
  * @module common
  */
@@ -9,7 +8,6 @@
 /**
  * The Json type is a simple alias for a string, but is used to indicate that
  * the string should be considered to be a JSON serialization of an object.
- *
  * @category General
  */
 export type Json = string;
@@ -18,7 +16,6 @@ export type Json = string;
  * The Ids type is a simple alias for an array of strings, but is used to
  * indicate that the strings should be considered to be the keys of objects
  * (such as the Row Id strings used in a Table).
- *
  * @category Identity
  */
 export type Ids = Id[];
@@ -27,7 +24,6 @@ export type Ids = Id[];
  * The Id type is a simple alias for a string, but is used to indicate that the
  * string should be considered to be the key of an object (such as a Row Id
  * string used in a Table).
- *
  * @category Identity
  */
 export type Id = string;
@@ -37,7 +33,6 @@ export type Id = string;
  * where the string should be considered to be the key of an objects (such as a
  * Row Id string used in a Table), and typically `null` indicates a wildcard -
  * such as when used in the Store addRowListener method.
- *
  * @category Identity
  */
 export type IdOrNull = Id | null;
@@ -45,7 +40,6 @@ export type IdOrNull = Id | null;
 /**
  * The ParameterizedCallback type represents a generic function that will take
  * an optional parameter - such as the handler of a DOM event.
- *
  * @category Callback
  */
 export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
@@ -53,14 +47,12 @@ export type ParameterizedCallback<Parameter> = (parameter?: Parameter) => void;
 /**
  * The Callback type represents a function that is used as a callback and which
  * does not take a parameter.
- *
  * @category Callback
  */
 export type Callback = () => void;
 
 /**
  * The SortKey type represents a value that can be used by a sort function.
- *
  * @category Parameter
  */
 export type SortKey = string | number | boolean;
@@ -70,7 +62,6 @@ export type SortKey = string | number | boolean;
  * alphanumerically, and can be provided to the `sliceIdSorter` and
  * `rowIdSorter` parameters of the setIndexDefinition method in the indexes
  * module, for example.
- *
  * @param sortKey1 The first item of the pair to compare.
  * @param sortKey2 The second item of the pair to compare.
  * @returns A number indicating how to sort the pair.

package/lib/types/with-schemas/indexes.d.ts

@@ -6,7 +6,6 @@
  * 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
  */
@@ -31,7 +30,6 @@ import {Id, IdOrNull, Ids, SortKey} from './common.d';
  * 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};
@@ -45,7 +43,6 @@ export type Index = {[sliceId: Id]: Slice};
  *
  * 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;
@@ -66,7 +63,6 @@ export type Slice = Ids;
  * A IndexCallback is provided when using the forEachIndex method, so that you
  * can do something based on every Index in the Indexes object. See that method
  * for specific examples.
- *
  * @param indexId The Id of the Index that the callback can operate on.
  * @param forEachRow A function that will let you iterate over the Slice objects
  * in this Index.
@@ -93,7 +89,6 @@ export type IndexCallback<Schema extends OptionalTablesSchema> = (
  * A SliceCallback is provided when using the forEachSlice method, so that you
  * can do something based on every Slice in an Index. See that method for
  * specific examples.
- *
  * @param sliceId The Id of the Slice that the callback can operate on.
  * @param forEachRow A function that will let you iterate over the Row objects
  * in this Slice.
@@ -119,7 +114,6 @@ export type SliceCallback<Schema extends OptionalTablesSchema> = (
  *
  * 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
@@ -149,7 +143,6 @@ export type SliceIdsListener<Schemas extends OptionalSchemas> = (
  * 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.
@@ -167,7 +160,6 @@ export type SliceRowIdsListener<Schemas extends OptionalSchemas> = (
  *
  * A IndexesListenerStats object is returned from the getListenerStats method,
  * and is only populated in a debug build.
- *
  * @category Development
  */
 export type IndexesListenerStats = {
@@ -198,7 +190,6 @@ export type IndexesListenerStats = {
  *
  * 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
@@ -297,7 +288,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * 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 getSliceIdOrIds Either the Id of the Cell containing, or a function
@@ -420,6 +410,11 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
 
   /**
    * 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.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -427,12 +422,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * delIndexDefinition(indexId: Id): Indexes;
    * ```
    *
-   * @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'},
@@ -456,6 +445,10 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
   /**
    * 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.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -463,11 +456,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * getStore(): Store;
    * ```
    *
-   * @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');
@@ -482,7 +470,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
   /**
    * 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
@@ -515,7 +502,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * IndexCallback function that will be called with the Id of each Index, and
    * with a function that can then be used to iterate over each Slice of the
    * Index, should you wish.
-   *
    * @param indexCallback The function that should be called for every Index.
    * @example
    * This example iterates over each Index in an Indexes object, and lists each
@@ -560,7 +546,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * in a functional style. The `rowCallback` parameter is a RowCallback
    * function that will be called with the Id and value of each Row in the
    * Slice.
-   *
    * @param indexId The Id of the Index to iterate over.
    * @param sliceCallback The function that should be called for every Slice.
    * @example
@@ -592,7 +577,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
   /**
    * The hasIndex method returns a boolean indicating whether a given Index
    * exists in the Indexes object.
-   *
    * @param indexId The Id of a possible Index in the Indexes object.
    * @returns Whether an Index with that Id exists.
    * @example
@@ -613,7 +597,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
   /**
    * The hasSlice method returns a boolean indicating whether a given Slice
    * exists in the Indexes object.
-   *
    * @param indexId The Id of a possible Index in the Indexes object.
    * @param sliceId The Id of a possible Slice in the Index.
    * @returns Whether a Slice with that Id exists.
@@ -648,7 +631,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * ```
    *
    * 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
@@ -675,7 +657,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    *
    * 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
@@ -708,7 +689,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    *
    * 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.
@@ -756,7 +736,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * 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.
@@ -853,7 +832,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * 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
@@ -943,7 +921,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * 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
@@ -986,7 +963,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    *
    * 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),
@@ -1025,7 +1001,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
    * 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
@@ -1062,7 +1037,6 @@ export interface Indexes<in out Schemas extends OptionalSchemas> {
  * 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