tinybase 5.0.0-beta.27 → 5.0.0-beta.28

package/@types/queries/with-schemas/index.d.cts

@@ -49,6 +49,7 @@ import type {GetIdChanges} from '../../store/index.d.cts';
  * };
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultTable = {[rowId: Id]: ResultRow};
 
@@ -67,6 +68,7 @@ export type ResultTable = {[rowId: Id]: ResultRow};
  * export const resultRow: ResultRow = {species: 'dog', color: 'brown'};
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultRow = {[cellId: Id]: ResultCell};
 
@@ -85,6 +87,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * export const resultCell: ResultCell = 'dog';
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultCell = string | number | boolean;
 
@@ -92,6 +95,7 @@ export type ResultCell = string | number | boolean;
  * The ResultCellOrUndefined type is the data structure representing a single
  * cell in the results of a query, or the value `undefined`.
  * @category Result
+ * @since v2.0.0
  */
 export type ResultCellOrUndefined = ResultCell | undefined;
 
@@ -123,7 +127,7 @@ export type Aggregate = (cells: ResultCell[], length: number) => ResultCell;
  * being added, return `undefined` and the aggregation will be completely
  * recalculated.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
+ * When possible, if you are providing a custom Aggregate, seek an
  * implementation of an AggregateAdd function that can reduce the complexity
  * cost of growing the input data set.
  * @param current The current value of the aggregation.
@@ -155,7 +159,7 @@ export type AggregateAdd = (
  * values, and the previous minimum is being removed. The whole of the rest of
  * the list will need to be re-scanned to find a new minimum.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
+ * When possible, if you are providing a custom Aggregate, seek an
  * implementation of an AggregateRemove function that can reduce the complexity
  * cost of shrinking the input data set.
  * @param current The current value of the aggregation.
@@ -185,7 +189,7 @@ export type AggregateRemove = (
  * changing, return `undefined` and the aggregation will be completely
  * recalculated.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
+ * When possible, if you are providing a custom Aggregate, seek an
  * implementation of an AggregateReplace function that can reduce the complexity
  * cost of changing the input data set in place.
  * @param current The current value of the aggregation.
@@ -226,6 +230,7 @@ export type QueryCallback = (queryId: Id) => void;
  * @param forEachRow A function that will let you iterate over the ResultRow
  * objects in this ResultTable.
  * @category Callback
+ * @since v2.0.0
  */
 export type ResultTableCallback = (
   tableId: Id,
@@ -243,6 +248,7 @@ export type ResultTableCallback = (
  * @param forEachRow A function that will let you iterate over the ResultCell
  * values in this ResultRow.
  * @category Callback
+ * @since v2.0.0
  */
 export type ResultRowCallback = (
   rowId: Id,
@@ -259,6 +265,7 @@ export type ResultRowCallback = (
  * @param cellId The Id of the ResultCell that the callback can operate on.
  * @param cell The value of the ResultCell.
  * @category Callback
+ * @since v2.0.0
  */
 export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
 
@@ -279,6 +286,7 @@ export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
  * Queries object.
  * @param queries A reference to the Queries object that changed.
  * @category Listener
+ * @since v2.0.0
  */
 export type QueryIdsListener<Schemas extends OptionalSchemas> = (
   queries: Queries<Schemas>,
@@ -627,6 +635,7 @@ export type ResultCellListener<Schemas extends OptionalSchemas> = (
  * @returns A ResultCellChange array containing information about the
  * ResultCell's changes.
  * @category Listener
+ * @since v2.0.0
  */
 export type GetResultCellChange = (
   tableId: Id,
@@ -643,6 +652,7 @@ export type GetResultCellChange = (
  * ResultCell before the current transaction, the new value after it, and a
  * convenience flag that indicates that the value has changed.
  * @category Listener
+ * @since v2.0.0
  */
 export type ResultCellChange = [
   changed: boolean,
@@ -662,41 +672,57 @@ export type QueriesListenerStats = {
   /**
    * The number of ResultTableListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   table: number;
   /**
    * The number of ResultTableCellIdsListener functions registered with the
    * Queries object, since v3.3.
+   * @category Stat
+   * @since v2.0.0
    */
   tableCellIds: number;
   /**
    * The number of ResultRowCountListener functions registered with the Queries
    * object, since v4.1.
+   * @category Stat
+   * @since v2.0.0
    */
   rowCount: number;
   /**
    * The number of ResultRowIdsListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   rowIds: number;
   /**
    * The number of SortedRowIdsListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   sortedRowIds: number;
   /**
    * The number of ResultRowListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   row: number;
   /**
    * The number of ResultCellIdsListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   cellIds: number;
   /**
    * The number of ResultCellListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   cell: number;
 };
@@ -721,6 +747,8 @@ export type GetTableCell<
    * or filtered.
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A Cell value or `undefined`.
+   * @category Callback
+   * @since v2.0.0
    */
   <RootCellId extends CellIdFromSchema<Schema, RootTableId>>(
     cellId: RootCellId,
@@ -734,6 +762,8 @@ export type GetTableCell<
    * used.
    * @param joinedCellId The Id of the Cell to fetch the value for.
    * @returns A Cell value or `undefined`.
+   * @category Callback
+   * @since v2.0.0
    */
   <
     JoinedTableId extends TableIdFromSchema<Schema> | Id,
@@ -863,6 +893,8 @@ export type Select<
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A SelectedAs object so that the selected Cell Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <RootCellId extends CellIdFromSchema<Schema, RootTableId>>(
     cellId: RootCellId,
@@ -877,6 +909,8 @@ export type Select<
    * @param joinedCellId The Id of the Cell to fetch the value for.
    * @returns A SelectedAs object so that the selected Cell Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <JoinedTableId extends TableIdFromSchema<Schema> | Id>(
     joinedTableId: JoinedTableId,
@@ -891,6 +925,8 @@ export type Select<
    * value from multiple Cell values and the Row Id.
    * @returns A SelectedAs object so that the selected Cell Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     getCell: (
@@ -951,6 +987,8 @@ export type Select<
 export type SelectedAs = {
   /**
    * A function that lets you specify an alias for the Cell Id.
+   * @category Definition
+   * @since v2.0.0
    */
   as: (selectedCellId: Id) => void;
 };
@@ -1141,6 +1179,8 @@ export type Join<
    * Table's Row Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     joinedTableId: TableIdFromSchema<Schema>,
@@ -1156,6 +1196,8 @@ export type Join<
    * Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     joinedTableId: TableIdFromSchema<Schema>,
@@ -1173,6 +1215,8 @@ export type Join<
    * joined Table's Row Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <
     IntermediateJoinedTableId extends TableIdFromSchema<Schema> | Id =
@@ -1201,6 +1245,8 @@ export type Join<
    * Table's Row Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <
     IntermediateJoinedTableId extends TableIdFromSchema<Schema> | Id =
@@ -1272,6 +1318,8 @@ export type Join<
 export type JoinedAs = {
   /**
  * A function that lets you specify an alias for the joined Table Id.
+ * @category Definition
+ * @since v2.0.0
  */
   as: (joinedTableId: Id) => void;
 };
@@ -1408,6 +1456,8 @@ export type Where<
    * @param cellId The Id of the Cell in the query's root Table to test.
    * @param equals The value that the Cell has to have for the Row to be
    * included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   <RootCellId extends CellIdFromSchema<Schema, RootTableId>>(
     cellId: RootCellId,
@@ -1422,6 +1472,8 @@ export type Where<
    * @param joinedCellId The Id of the Cell in the joined Table to test.
    * @param equals The value that the Cell has to have for the Row to be
    * included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   <
     JoinedTableId extends TableIdFromSchema<Schema> | Id,
@@ -1445,6 +1497,8 @@ export type Where<
    * the main and (optionally) joined Tables.
    * @param condition A callback that takes a GetTableCell function and that
    * should return `true` for the Row to be included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     condition: (getTableCell: GetTableCell<Schema, RootTableId>) => boolean,
@@ -1633,6 +1687,8 @@ export type Group = (
 export type GroupedAs = {
   /**
  * A function that lets you specify an alias for the grouped Cell Id.
+ * @category Definition
+ * @since v2.0.0
  */
   as: (groupedCellId: Id) => void;
 };
@@ -1736,6 +1792,8 @@ export type Having = {
    * @param selectedOrGroupedCellId The Id of the Cell in the query to test.
    * @param equals The value that the Cell has to have for the Row to be
    * included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   (selectedOrGroupedCellId: Id, equals: ResultCell): void;
   /**
@@ -1743,6 +1801,8 @@ export type Having = {
    * those Rows which meet a calculated boolean condition.
    * @param condition A callback that takes a GetCell function and that should
    * return `true` for the Row to be included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   (condition: (getSelectedOrGroupedCell: GetResultCell) => boolean): void;
 };
@@ -1839,7 +1899,7 @@ export type Having = {
  * queries.delListener(listenerId);
  * queries.destroy();
  * ```
- * @see Making Queries guides
+ * @see Using Queries guides
  * @see Car Analysis demo
  * @see Movie Database demo
  * @category Queries

package/@types/queries/with-schemas/index.d.ts

@@ -49,6 +49,7 @@ import type {GetIdChanges} from '../../store/index.d.ts';
  * };
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultTable = {[rowId: Id]: ResultRow};
 
@@ -67,6 +68,7 @@ export type ResultTable = {[rowId: Id]: ResultRow};
  * export const resultRow: ResultRow = {species: 'dog', color: 'brown'};
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultRow = {[cellId: Id]: ResultCell};
 
@@ -85,6 +87,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * export const resultCell: ResultCell = 'dog';
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultCell = string | number | boolean;
 
@@ -92,6 +95,7 @@ export type ResultCell = string | number | boolean;
  * The ResultCellOrUndefined type is the data structure representing a single
  * cell in the results of a query, or the value `undefined`.
  * @category Result
+ * @since v2.0.0
  */
 export type ResultCellOrUndefined = ResultCell | undefined;
 
@@ -123,7 +127,7 @@ export type Aggregate = (cells: ResultCell[], length: number) => ResultCell;
  * being added, return `undefined` and the aggregation will be completely
  * recalculated.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
+ * When possible, if you are providing a custom Aggregate, seek an
  * implementation of an AggregateAdd function that can reduce the complexity
  * cost of growing the input data set.
  * @param current The current value of the aggregation.
@@ -155,7 +159,7 @@ export type AggregateAdd = (
  * values, and the previous minimum is being removed. The whole of the rest of
  * the list will need to be re-scanned to find a new minimum.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
+ * When possible, if you are providing a custom Aggregate, seek an
  * implementation of an AggregateRemove function that can reduce the complexity
  * cost of shrinking the input data set.
  * @param current The current value of the aggregation.
@@ -185,7 +189,7 @@ export type AggregateRemove = (
  * changing, return `undefined` and the aggregation will be completely
  * recalculated.
  *
- * Where possible, if you are providing a custom Aggregate, seek an
+ * When possible, if you are providing a custom Aggregate, seek an
  * implementation of an AggregateReplace function that can reduce the complexity
  * cost of changing the input data set in place.
  * @param current The current value of the aggregation.
@@ -226,6 +230,7 @@ export type QueryCallback = (queryId: Id) => void;
  * @param forEachRow A function that will let you iterate over the ResultRow
  * objects in this ResultTable.
  * @category Callback
+ * @since v2.0.0
  */
 export type ResultTableCallback = (
   tableId: Id,
@@ -243,6 +248,7 @@ export type ResultTableCallback = (
  * @param forEachRow A function that will let you iterate over the ResultCell
  * values in this ResultRow.
  * @category Callback
+ * @since v2.0.0
  */
 export type ResultRowCallback = (
   rowId: Id,
@@ -259,6 +265,7 @@ export type ResultRowCallback = (
  * @param cellId The Id of the ResultCell that the callback can operate on.
  * @param cell The value of the ResultCell.
  * @category Callback
+ * @since v2.0.0
  */
 export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
 
@@ -279,6 +286,7 @@ export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
  * Queries object.
  * @param queries A reference to the Queries object that changed.
  * @category Listener
+ * @since v2.0.0
  */
 export type QueryIdsListener<Schemas extends OptionalSchemas> = (
   queries: Queries<Schemas>,
@@ -627,6 +635,7 @@ export type ResultCellListener<Schemas extends OptionalSchemas> = (
  * @returns A ResultCellChange array containing information about the
  * ResultCell's changes.
  * @category Listener
+ * @since v2.0.0
  */
 export type GetResultCellChange = (
   tableId: Id,
@@ -643,6 +652,7 @@ export type GetResultCellChange = (
  * ResultCell before the current transaction, the new value after it, and a
  * convenience flag that indicates that the value has changed.
  * @category Listener
+ * @since v2.0.0
  */
 export type ResultCellChange = [
   changed: boolean,
@@ -662,41 +672,57 @@ export type QueriesListenerStats = {
   /**
    * The number of ResultTableListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   table: number;
   /**
    * The number of ResultTableCellIdsListener functions registered with the
    * Queries object, since v3.3.
+   * @category Stat
+   * @since v2.0.0
    */
   tableCellIds: number;
   /**
    * The number of ResultRowCountListener functions registered with the Queries
    * object, since v4.1.
+   * @category Stat
+   * @since v2.0.0
    */
   rowCount: number;
   /**
    * The number of ResultRowIdsListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   rowIds: number;
   /**
    * The number of SortedRowIdsListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   sortedRowIds: number;
   /**
    * The number of ResultRowListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   row: number;
   /**
    * The number of ResultCellIdsListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   cellIds: number;
   /**
    * The number of ResultCellListener functions registered with the Queries
    * object.
+   * @category Stat
+   * @since v2.0.0
    */
   cell: number;
 };
@@ -721,6 +747,8 @@ export type GetTableCell<
    * or filtered.
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A Cell value or `undefined`.
+   * @category Callback
+   * @since v2.0.0
    */
   <RootCellId extends CellIdFromSchema<Schema, RootTableId>>(
     cellId: RootCellId,
@@ -734,6 +762,8 @@ export type GetTableCell<
    * used.
    * @param joinedCellId The Id of the Cell to fetch the value for.
    * @returns A Cell value or `undefined`.
+   * @category Callback
+   * @since v2.0.0
    */
   <
     JoinedTableId extends TableIdFromSchema<Schema> | Id,
@@ -863,6 +893,8 @@ export type Select<
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A SelectedAs object so that the selected Cell Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <RootCellId extends CellIdFromSchema<Schema, RootTableId>>(
     cellId: RootCellId,
@@ -877,6 +909,8 @@ export type Select<
    * @param joinedCellId The Id of the Cell to fetch the value for.
    * @returns A SelectedAs object so that the selected Cell Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <JoinedTableId extends TableIdFromSchema<Schema> | Id>(
     joinedTableId: JoinedTableId,
@@ -891,6 +925,8 @@ export type Select<
    * value from multiple Cell values and the Row Id.
    * @returns A SelectedAs object so that the selected Cell Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     getCell: (
@@ -951,6 +987,8 @@ export type Select<
 export type SelectedAs = {
   /**
    * A function that lets you specify an alias for the Cell Id.
+   * @category Definition
+   * @since v2.0.0
    */
   as: (selectedCellId: Id) => void;
 };
@@ -1141,6 +1179,8 @@ export type Join<
    * Table's Row Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     joinedTableId: TableIdFromSchema<Schema>,
@@ -1156,6 +1196,8 @@ export type Join<
    * Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     joinedTableId: TableIdFromSchema<Schema>,
@@ -1173,6 +1215,8 @@ export type Join<
    * joined Table's Row Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <
     IntermediateJoinedTableId extends TableIdFromSchema<Schema> | Id =
@@ -1201,6 +1245,8 @@ export type Join<
    * Table's Row Id.
    * @returns A JoinedAs object so that the joined Table Id can be optionally
    * aliased.
+   * @category Definition
+   * @since v2.0.0
    */
   <
     IntermediateJoinedTableId extends TableIdFromSchema<Schema> | Id =
@@ -1272,6 +1318,8 @@ export type Join<
 export type JoinedAs = {
   /**
  * A function that lets you specify an alias for the joined Table Id.
+ * @category Definition
+ * @since v2.0.0
  */
   as: (joinedTableId: Id) => void;
 };
@@ -1408,6 +1456,8 @@ export type Where<
    * @param cellId The Id of the Cell in the query's root Table to test.
    * @param equals The value that the Cell has to have for the Row to be
    * included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   <RootCellId extends CellIdFromSchema<Schema, RootTableId>>(
     cellId: RootCellId,
@@ -1422,6 +1472,8 @@ export type Where<
    * @param joinedCellId The Id of the Cell in the joined Table to test.
    * @param equals The value that the Cell has to have for the Row to be
    * included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   <
     JoinedTableId extends TableIdFromSchema<Schema> | Id,
@@ -1445,6 +1497,8 @@ export type Where<
    * the main and (optionally) joined Tables.
    * @param condition A callback that takes a GetTableCell function and that
    * should return `true` for the Row to be included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   (
     condition: (getTableCell: GetTableCell<Schema, RootTableId>) => boolean,
@@ -1633,6 +1687,8 @@ export type Group = (
 export type GroupedAs = {
   /**
  * A function that lets you specify an alias for the grouped Cell Id.
+ * @category Definition
+ * @since v2.0.0
  */
   as: (groupedCellId: Id) => void;
 };
@@ -1736,6 +1792,8 @@ export type Having = {
    * @param selectedOrGroupedCellId The Id of the Cell in the query to test.
    * @param equals The value that the Cell has to have for the Row to be
    * included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   (selectedOrGroupedCellId: Id, equals: ResultCell): void;
   /**
@@ -1743,6 +1801,8 @@ export type Having = {
    * those Rows which meet a calculated boolean condition.
    * @param condition A callback that takes a GetCell function and that should
    * return `true` for the Row to be included in the result.
+   * @category Definition
+   * @since v2.0.0
    */
   (condition: (getSelectedOrGroupedCell: GetResultCell) => boolean): void;
 };
@@ -1839,7 +1899,7 @@ export type Having = {
  * queries.delListener(listenerId);
  * queries.destroy();
  * ```
- * @see Making Queries guides
+ * @see Using Queries guides
  * @see Car Analysis demo
  * @see Movie Database demo
  * @category Queries