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

package/@types/queries/index.d.cts

@@ -38,6 +38,7 @@ import type {Id, IdOrNull, Ids} from '../common/index.d.cts';
  * };
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultTable = {[rowId: Id]: ResultRow};
 
@@ -56,6 +57,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};
 
@@ -74,6 +76,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * export const resultCell: ResultCell = 'dog';
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultCell = string | number | boolean;
 
@@ -81,6 +84,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;
 
@@ -112,7 +116,7 @@ export type Aggregate = (cells: Cell[], 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.
@@ -144,7 +148,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.
@@ -174,7 +178,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.
@@ -215,6 +219,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,
@@ -232,6 +237,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,
@@ -248,6 +254,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;
 
@@ -262,6 +269,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 = (queries: Queries) => void;
 
@@ -518,6 +526,7 @@ export type ResultCellListener = (
  * @returns A ResultCellChange array containing information about the
  * ResultCell's changes.
  * @category Listener
+ * @since v2.0.0
  */
 export type GetResultCellChange = (
   tableId: Id,
@@ -534,6 +543,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,
@@ -553,41 +563,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;
 };
@@ -609,6 +635,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
    */
   (cellId: Id): CellOrUndefined;
   /**
@@ -620,6 +648,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: Id, joinedCellId: Id): CellOrUndefined;
 };
@@ -733,6 +763,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
    */
   (cellId: Id): SelectedAs;
   /**
@@ -745,6 +777,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: Id, joinedCellId: Id): SelectedAs;
   /**
@@ -756,6 +790,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: (getTableCell: GetTableCell, rowId: Id) => ResultCellOrUndefined,
@@ -813,6 +849,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;
 };
@@ -1000,6 +1038,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: Id, on: Id): JoinedAs;
   /**
@@ -1012,6 +1052,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: Id,
@@ -1029,6 +1071,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
    */
   (joinedTableId: Id, fromIntermediateJoinedTableId: Id, on: Id): JoinedAs;
   /**
@@ -1045,6 +1089,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: Id,
@@ -1108,6 +1154,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;
 };
@@ -1241,6 +1289,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
    */
   (cellId: Id, equals: Cell): void;
   /**
@@ -1252,6 +1302,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: Id, joinedCellId: Id, equals: Cell): void;
   /**
@@ -1260,6 +1312,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) => boolean): void;
 };
@@ -1446,6 +1500,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;
 };
@@ -1549,6 +1605,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: Cell): void;
   /**
@@ -1556,6 +1614,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: GetCell) => boolean): void;
 };
@@ -1652,7 +1712,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/index.d.ts

@@ -38,6 +38,7 @@ import type {Id, IdOrNull, Ids} from '../common/index.d.ts';
  * };
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultTable = {[rowId: Id]: ResultRow};
 
@@ -56,6 +57,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};
 
@@ -74,6 +76,7 @@ export type ResultRow = {[cellId: Id]: ResultCell};
  * export const resultCell: ResultCell = 'dog';
  * ```
  * @category Result
+ * @since v2.0.0
  */
 export type ResultCell = string | number | boolean;
 
@@ -81,6 +84,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;
 
@@ -112,7 +116,7 @@ export type Aggregate = (cells: Cell[], 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.
@@ -144,7 +148,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.
@@ -174,7 +178,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.
@@ -215,6 +219,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,
@@ -232,6 +237,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,
@@ -248,6 +254,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;
 
@@ -262,6 +269,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 = (queries: Queries) => void;
 
@@ -518,6 +526,7 @@ export type ResultCellListener = (
  * @returns A ResultCellChange array containing information about the
  * ResultCell's changes.
  * @category Listener
+ * @since v2.0.0
  */
 export type GetResultCellChange = (
   tableId: Id,
@@ -534,6 +543,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,
@@ -553,41 +563,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;
 };
@@ -609,6 +635,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
    */
   (cellId: Id): CellOrUndefined;
   /**
@@ -620,6 +648,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: Id, joinedCellId: Id): CellOrUndefined;
 };
@@ -733,6 +763,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
    */
   (cellId: Id): SelectedAs;
   /**
@@ -745,6 +777,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: Id, joinedCellId: Id): SelectedAs;
   /**
@@ -756,6 +790,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: (getTableCell: GetTableCell, rowId: Id) => ResultCellOrUndefined,
@@ -813,6 +849,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;
 };
@@ -1000,6 +1038,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: Id, on: Id): JoinedAs;
   /**
@@ -1012,6 +1052,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: Id,
@@ -1029,6 +1071,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
    */
   (joinedTableId: Id, fromIntermediateJoinedTableId: Id, on: Id): JoinedAs;
   /**
@@ -1045,6 +1089,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: Id,
@@ -1108,6 +1154,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;
 };
@@ -1241,6 +1289,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
    */
   (cellId: Id, equals: Cell): void;
   /**
@@ -1252,6 +1302,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: Id, joinedCellId: Id, equals: Cell): void;
   /**
@@ -1260,6 +1312,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) => boolean): void;
 };
@@ -1446,6 +1500,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;
 };
@@ -1549,6 +1605,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: Cell): void;
   /**
@@ -1556,6 +1614,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: GetCell) => boolean): void;
 };
@@ -1652,7 +1712,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