tinybase 7.2.0-beta.0 → 7.2.0-beta.1

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

@@ -19,6 +19,47 @@ import type {
   Store,
 } from '../store/index.d.ts';
 
+/**
+ * The ParamValue type describes a single param value that can be used in a
+ * parameterized query.
+ *
+ * A ParamValue is similar to a Cell, but params cannot be `undefined`. They
+ * must be a JavaScript string, number, boolean, or null.
+ * @example
+ * ```js
+ * import type {ParamValue} from 'tinybase';
+ *
+ * export const paramValue1: ParamValue = 'dog';
+ * export const paramValue2: ParamValue = 5;
+ * export const paramValue3: ParamValue = true;
+ * export const paramValue4: ParamValue = null;
+ * ```
+ * @category Params
+ * @since v7.2.0
+ */
+export type ParamValue = string | number | boolean | null;
+
+/**
+ * The ParamValues type describes an object of param values, keyed by param Id,
+ * used to provide values for a parameterized query.
+ *
+ * A ParamValues object is provided when setting a query definition with params,
+ * or when updating params with the setParamValues method.
+ * @example
+ * ```js
+ * import type {ParamValues} from 'tinybase';
+ *
+ * export const paramValues: ParamValues = {
+ *   species: 'dog',
+ *   minAge: 5,
+ *   active: true,
+ * };
+ * ```
+ * @category Params
+ * @since v7.2.0
+ */
+export type ParamValues = {[paramId: Id]: ParamValue};
+
 /**
  * The ResultTable type is the data structure representing the results of a
  * query.
@@ -258,14 +299,13 @@ export type ResultRowCallback = (
 export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
 
 /**
- * The QueryIdsListener type describes a function that is used to listen
- * to Query definitions being added or removed.
+ * The QueryIdsListener type describes a function that is used to listen to
+ * Query definitions being added or removed.
  *
- * A QueryIdsListener is provided when using the
- * addQueryIdsListener method. See that method for specific examples.
+ * A QueryIdsListener is provided when using the addQueryIdsListener method. See
+ * that method for specific examples.
  *
- * When called, a QueryIdsListener is given a reference to the
- * Queries object.
+ * When called, a QueryIdsListener is given a reference to the Queries object.
  * @param queries A reference to the Queries object that changed.
  * @category Listener
  * @since v2.0.0
@@ -629,9 +669,9 @@ export type QueriesListenerStats = {
  */
 export type GetTableCell = {
   /**
-   * When called with one parameter, this function will return the value of
-   * the specified Cell from the query's root Table for the Row being selected
-   * or filtered.
+   * When called with one parameter, this function will return the value of the
+   * specified Cell from the query's root Table for the Row being selected or
+   * filtered.
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A Cell value or `undefined`.
    * @category Callback
@@ -639,9 +679,9 @@ export type GetTableCell = {
    */
   (cellId: Id): CellOrUndefined;
   /**
-   * When called with two parameters, this function will return the value of
-   * the specified Cell from a Table that has been joined in the query, for
-   * the Row being selected or filtered.
+   * When called with two parameters, this function will return the value of the
+   * specified Cell from a Table that has been joined in the query, for the Row
+   * being selected or filtered.
    * @param joinedTableId The Id of the Table to fetch the value from. If the
    * underlying Table was joined 'as' a different Id, that should instead be
    * used.
@@ -653,6 +693,50 @@ export type GetTableCell = {
   (joinedTableId: Id, joinedCellId: Id): CellOrUndefined;
 };
 
+/**
+ * The Param type describes a function that takes a param Id and returns its
+ * value within a parameterized query.
+ *
+ * A Param function is provided when setting parameterized query definitions,
+ * and allows you to reference dynamic param values that can be updated without
+ * redefining the entire query.
+ * @param paramId The Id of the param to fetch the value for.
+ * @returns A Cell value or `undefined` if the param is not set.
+ * @example
+ * This example shows a query that uses a param to filter results.
+ *
+ * ```js
+ * import {createQueries, createStore} from 'tinybase';
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog', color: 'brown'},
+ *   felix: {species: 'cat', color: 'black'},
+ *   cujo: {species: 'dog', color: 'black'},
+ * });
+ *
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'query',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('color');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * console.log(queries.getResultTable('query'));
+ * // -> {fido: {color: 'brown'}, cujo: {color: 'black'}}
+ *
+ * queries.setParamValue('query', 'species', 'cat');
+ * console.log(queries.getResultTable('query'));
+ * // -> {felix: {color: 'black'}}
+ * ```
+ * @category Definition
+ * @since v7.2.0
+ */
+export type Param = (paramId: Id) => ParamValue | undefined;
+
 /**
  * The Select type describes a function that lets you specify a Cell or
  * calculated value for including into the query's result.
@@ -1732,8 +1816,8 @@ export interface Queries {
    * The third `query` parameter is a callback that you provide to define the
    * query. That callback is provided with a `keywords` object that contains the
    * functions you use to define the query, like `select`, `join`, and so on.
-   * You can see how that is used in the simple example below. The following
-   * five clause types are supported:
+   * You can see how that is used in the simple example below. The following six
+   * clause types are supported:
    *
    * - The Select type describes a function that lets you specify a Cell or
    *   calculated value for including into the query's result.
@@ -1746,6 +1830,8 @@ export interface Queries {
    *   of a Cell in multiple ResultRows should be aggregated together.
    * - The Having type describes a function that lets you specify conditions to
    *   filter results, based on the grouped Cells resulting from a Group clause.
+   * - The Param type (since v7.2) describes a function that lets you specify
+   *   parameters for a parameterized query.
    *
    * Full documentation and examples are provided in the sections for each of
    * those clause types.
@@ -1764,7 +1850,7 @@ export interface Queries {
    *
    * ```js
    * import {createQueries, createStore} from 'tinybase';
-   * 
+   *
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', color: 'brown'},
    *   felix: {species: 'cat', color: 'black'},
@@ -1792,7 +1878,9 @@ export interface Queries {
       where: Where;
       group: Group;
       having: Having;
+      param: Param;
     }) => void,
+    paramValues?: ParamValues,
   ): Queries;
 
   /**
@@ -1829,6 +1917,92 @@ export interface Queries {
    */
   delQueryDefinition(queryId: Id): Queries;
 
+  /**
+   * The setParamValues method sets multiple param values for a parameterized
+   * query at once, causing the query to re-evaluate with the new param values.
+   * @param queryId The Id of the query to update the params for.
+   * @param paramValues An object containing the param Ids and values to set.
+   * @returns A reference to the Queries object for convenient chaining.
+   * @example
+   * This example creates a parameterized query and then updates multiple
+   * parameters at once.
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown', age: 5},
+   *   felix: {species: 'cat', color: 'black', age: 3},
+   *   cujo: {species: 'dog', color: 'black', age: 7},
+   * });
+   *
+   * const queries = createQueries(store);
+   * queries.setQueryDefinition(
+   *   'query',
+   *   'pets',
+   *   ({select, where, param}) => {
+   *     select('color');
+   *     where('species', param('species'));
+   *     where((getTableCell) => getTableCell('age') >= param('minAge'));
+   *   },
+   *   {species: 'dog', minAge: 5},
+   * );
+   *
+   * console.log(queries.getResultTable('query'));
+   * // -> {fido: {color: 'brown'}, cujo: {color: 'black'}}
+   *
+   * queries.setParamValues('query', {species: 'cat', minAge: 2});
+   * console.log(queries.getResultTable('query'));
+   * // -> {felix: {color: 'black'}}
+   * ```
+   * @category Configuration
+   * @since v7.2.0
+   */
+  setParamValues(queryId: Id, paramValues: ParamValues): Queries;
+
+  /**
+   * The setParamValue method sets a single param value for a parameterized
+   * query, causing the query to re-evaluate with the new param value.
+   * @param queryId The Id of the query to update the param  for.
+   * @param paramId The Id of the param to set.
+   * @param value The value to set for the param.
+   * @returns A reference to the Queries object for convenient chaining.
+   * @example
+   * This example creates a parameterized query and then updates one of its
+   * params.
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   *
+   * const queries = createQueries(store);
+   * queries.setQueryDefinition(
+   *   'query',
+   *   'pets',
+   *   ({select, where, param}) => {
+   *     select('color');
+   *     where('species', param('species'));
+   *   },
+   *   {species: 'dog'},
+   * );
+   *
+   * console.log(queries.getResultTable('query'));
+   * // -> {fido: {color: 'brown'}, cujo: {color: 'black'}}
+   *
+   * queries.setParamValue('query', 'species', 'cat');
+   * console.log(queries.getResultTable('query'));
+   * // -> {felix: {color: 'black'}}
+   * ```
+   * @category Configuration
+   * @since v7.2.0
+   */
+  setParamValue(queryId: Id, paramId: Id, value: ParamValue): Queries;
+
   /**
    * The getStore method returns a reference to the underlying Store that is
    * backing this Queries object.
@@ -2763,23 +2937,23 @@ export interface Queries {
 
   /**
    * The addResultTableCellIdsListener method registers a listener function with
-   * the Queries object that will be called whenever the Cell Ids that
-   * appear anywhere in a ResultTable change.
+   * the Queries object that will be called whenever the Cell Ids that appear
+   * anywhere in a ResultTable change.
    *
    * The provided listener is a ResultTableCellIdsListener function, and will be
    * called with a reference to the Queries object and the Id of the ResultTable
    * that changed (which is also the query Id).
    *
-   * By default, such a listener is only called when a Cell Id is added
-   * to, or removed from, the ResultTable. To listen to all changes in the
-   * ResultTable, use the addResultTableListener method.
+   * By default, such a listener is only called when a Cell Id is added to, or
+   * removed from, the ResultTable. To listen to all changes in the ResultTable,
+   * use the addResultTableListener method.
    *
    * You can either listen to a single ResultTable (by specifying a query Id as
    * the method's first parameter) or changes to any ResultTable (by providing a
    * `null` wildcard).
    * @param queryId The Id of the query to listen to, or `null` as a wildcard.
-   * @param listener The function that will be called whenever the Cell
-   * Ids that appear anywhere in the ResultTable change.
+   * @param listener The function that will be called whenever the Cell Ids that
+   * appear anywhere in the ResultTable change.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that responds to any change to the

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

@@ -30,6 +30,47 @@ import type {
   Store,
 } from '../../store/with-schemas/index.d.ts';
 
+/**
+ * The ParamValue type describes a single param value that can be used in a
+ * parameterized query.
+ *
+ * A ParamValue is similar to a Cell, but params cannot be `undefined`. They
+ * must be a JavaScript string, number, boolean, or null.
+ * @example
+ * ```js
+ * import type {ParamValue} from 'tinybase';
+ *
+ * export const paramValue1: ParamValue = 'dog';
+ * export const paramValue2: ParamValue = 5;
+ * export const paramValue3: ParamValue = true;
+ * export const paramValue4: ParamValue = null;
+ * ```
+ * @category Params
+ * @since v7.2.0
+ */
+export type ParamValue = string | number | boolean | null;
+
+/**
+ * The ParamValues type describes an object of param values, keyed by param Id,
+ * used to provide values for a parameterized query.
+ *
+ * A ParamValues object is provided when setting a query definition with params,
+ * or when updating params with the setParamValues method.
+ * @example
+ * ```js
+ * import type {ParamValues} from 'tinybase';
+ *
+ * export const paramValues: ParamValues = {
+ *   species: 'dog',
+ *   minAge: 5,
+ *   active: true,
+ * };
+ * ```
+ * @category Params
+ * @since v7.2.0
+ */
+export type ParamValues = {[paramId: Id]: ParamValue};
+
 /**
  * The ResultTable type is the data structure representing the results of a
  * query.
@@ -269,8 +310,8 @@ export type ResultRowCallback = (
 export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
 
 /**
- * The QueryIdsListener type describes a function that is used to listen
- * to Query definitions being added or removed.
+ * The QueryIdsListener type describes a function that is used to listen to
+ * Query definitions being added or removed.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -278,11 +319,10 @@ export type ResultCellCallback = (cellId: Id, cell: ResultCell) => void;
  * (queries: Queries) => void;
  * ```
  *
- * A QueryIdsListener is provided when using the
- * addQueryIdsListener method. See that method for specific examples.
+ * A QueryIdsListener is provided when using the addQueryIdsListener method. See
+ * that method for specific examples.
  *
- * When called, a QueryIdsListener is given a reference to the
- * Queries object.
+ * When called, a QueryIdsListener is given a reference to the Queries object.
  * @param queries A reference to the Queries object that changed.
  * @category Listener
  * @since v2.0.0
@@ -741,9 +781,9 @@ export type GetTableCell<
   RootTableId extends TableIdFromSchema<Schema>,
 > = {
   /**
-   * When called with one parameter, this function will return the value of
-   * the specified Cell from the query's root Table for the Row being selected
-   * or filtered.
+   * When called with one parameter, this function will return the value of the
+   * specified Cell from the query's root Table for the Row being selected or
+   * filtered.
    * @param cellId The Id of the Cell to fetch the value for.
    * @returns A Cell value or `undefined`.
    * @category Callback
@@ -753,9 +793,9 @@ export type GetTableCell<
     cellId: RootCellId,
   ): CellOrUndefined<Schema, RootTableId, RootCellId>;
   /**
-   * When called with two parameters, this function will return the value of
-   * the specified Cell from a Table that has been joined in the query, for
-   * the Row being selected or filtered.
+   * When called with two parameters, this function will return the value of the
+   * specified Cell from a Table that has been joined in the query, for the Row
+   * being selected or filtered.
    * @param joinedTableId The Id of the Table to fetch the value from. If the
    * underlying Table was joined 'as' a different Id, that should instead be
    * used.
@@ -778,6 +818,50 @@ export type GetTableCell<
     | undefined;
 };
 
+/**
+ * The Param type describes a function that takes a param Id and returns its
+ * value within a parameterized query.
+ *
+ * A Param function is provided when setting parameterized query definitions,
+ * and allows you to reference dynamic param values that can be updated without
+ * redefining the entire query.
+ * @param paramId The Id of the param to fetch the value for.
+ * @returns A Cell value or `undefined` if the param is not set.
+ * @example
+ * This example shows a query that uses a param to filter results.
+ *
+ * ```js
+ * import {createQueries, createStore} from 'tinybase';
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog', color: 'brown'},
+ *   felix: {species: 'cat', color: 'black'},
+ *   cujo: {species: 'dog', color: 'black'},
+ * });
+ *
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'query',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('color');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * console.log(queries.getResultTable('query'));
+ * // -> {fido: {color: 'brown'}, cujo: {color: 'black'}}
+ *
+ * queries.setParamValue('query', 'species', 'cat');
+ * console.log(queries.getResultTable('query'));
+ * // -> {felix: {color: 'black'}}
+ * ```
+ * @category Definition
+ * @since v7.2.0
+ */
+export type Param = (paramId: Id) => ParamValue | undefined;
+
 /**
  * The Select type describes a function that lets you specify a Cell or
  * calculated value for including into the query's result.
@@ -1916,7 +2000,9 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    *     where: Where;
    *     group: Group;
    *     having: Having;
+   *     param: Param;
    *   }) => void,
+   *   paramValues?: ParamValues,
    * ): Queries;
    * ```
    *
@@ -1930,8 +2016,8 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * The third `query` parameter is a callback that you provide to define the
    * query. That callback is provided with a `keywords` object that contains the
    * functions you use to define the query, like `select`, `join`, and so on.
-   * You can see how that is used in the simple example below. The following
-   * five clause types are supported:
+   * You can see how that is used in the simple example below. The following six
+   * clause types are supported:
    *
    * - The Select type describes a function that lets you specify a Cell or
    *   calculated value for including into the query's result.
@@ -1944,6 +2030,8 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    *   of a Cell in multiple ResultRows should be aggregated together.
    * - The Having type describes a function that lets you specify conditions to
    *   filter results, based on the grouped Cells resulting from a Group clause.
+   * - The Param type (since v7.2) describes a function that lets you specify
+   *   parameters for a parameterized query.
    *
    * Full documentation and examples are provided in the sections for each of
    * those clause types.
@@ -1962,7 +2050,7 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    *
    * ```js
    * import {createQueries, createStore} from 'tinybase';
-   * 
+   *
    * const store = createStore().setTable('pets', {
    *   fido: {species: 'dog', color: 'brown'},
    *   felix: {species: 'cat', color: 'black'},
@@ -1990,7 +2078,9 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
       where: Where<Schemas[0], RootTableId>;
       group: Group;
       having: Having;
+      param: Param;
     }) => void,
+    paramValues?: ParamValues,
   ): Queries<Schemas>;
 
   /**
@@ -2033,6 +2123,104 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    */
   delQueryDefinition(queryId: Id): Queries<Schemas>;
 
+  /**
+   * The setParamValues method sets multiple param values for a parameterized
+   * query at once, causing the query to re-evaluate with the new param values.
+   * @param queryId The Id of the query to update the params for.
+   * @param paramValues An object containing the param Ids and values to set.
+   * @returns A reference to the Queries object for convenient chaining.
+   * @example
+   * This example creates a parameterized query and then updates multiple
+   * parameters at once.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * setParamValues(queryId: Id, paramValues: ParamValues): Queries;
+   * ```
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown', age: 5},
+   *   felix: {species: 'cat', color: 'black', age: 3},
+   *   cujo: {species: 'dog', color: 'black', age: 7},
+   * });
+   *
+   * const queries = createQueries(store);
+   * queries.setQueryDefinition(
+   *   'query',
+   *   'pets',
+   *   ({select, where, param}) => {
+   *     select('color');
+   *     where('species', param('species'));
+   *     where((getTableCell) => getTableCell('age') >= param('minAge'));
+   *   },
+   *   {species: 'dog', minAge: 5},
+   * );
+   *
+   * console.log(queries.getResultTable('query'));
+   * // -> {fido: {color: 'brown'}, cujo: {color: 'black'}}
+   *
+   * queries.setParamValues('query', {species: 'cat', minAge: 2});
+   * console.log(queries.getResultTable('query'));
+   * // -> {felix: {color: 'black'}}
+   * ```
+   * @category Configuration
+   * @since v7.2.0
+   */
+  setParamValues(queryId: Id, paramValues: ParamValues): Queries<Schemas>;
+
+  /**
+   * The setParamValue method sets a single param value for a parameterized
+   * query, causing the query to re-evaluate with the new param value.
+   * @param queryId The Id of the query to update the param  for.
+   * @param paramId The Id of the param to set.
+   * @param value The value to set for the param.
+   * @returns A reference to the Queries object for convenient chaining.
+   * @example
+   * This example creates a parameterized query and then updates one of its
+   * params.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * setParamValue(queryId: Id, paramId: Id, value: ParamValue): Queries;
+   * ```
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   *
+   * const queries = createQueries(store);
+   * queries.setQueryDefinition(
+   *   'query',
+   *   'pets',
+   *   ({select, where, param}) => {
+   *     select('color');
+   *     where('species', param('species'));
+   *   },
+   *   {species: 'dog'},
+   * );
+   *
+   * console.log(queries.getResultTable('query'));
+   * // -> {fido: {color: 'brown'}, cujo: {color: 'black'}}
+   *
+   * queries.setParamValue('query', 'species', 'cat');
+   * console.log(queries.getResultTable('query'));
+   * // -> {felix: {color: 'black'}}
+   * ```
+   * @category Configuration
+   * @since v7.2.0
+   */
+  setParamValue(queryId: Id, paramId: Id, value: ParamValue): Queries<Schemas>;
+
   /**
    * The getStore method returns a reference to the underlying Store that is
    * backing this Queries object.
@@ -2996,8 +3184,8 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
 
   /**
    * The addResultTableCellIdsListener method registers a listener function with
-   * the Queries object that will be called whenever the Cell Ids that
-   * appear anywhere in a ResultTable change.
+   * the Queries object that will be called whenever the Cell Ids that appear
+   * anywhere in a ResultTable change.
    *
    * This has schema-based typing. The following is a simplified representation:
    *
@@ -3012,16 +3200,16 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    * called with a reference to the Queries object and the Id of the ResultTable
    * that changed (which is also the query Id).
    *
-   * By default, such a listener is only called when a Cell Id is added
-   * to, or removed from, the ResultTable. To listen to all changes in the
-   * ResultTable, use the addResultTableListener method.
+   * By default, such a listener is only called when a Cell Id is added to, or
+   * removed from, the ResultTable. To listen to all changes in the ResultTable,
+   * use the addResultTableListener method.
    *
    * You can either listen to a single ResultTable (by specifying a query Id as
    * the method's first parameter) or changes to any ResultTable (by providing a
    * `null` wildcard).
    * @param queryId The Id of the query to listen to, or `null` as a wildcard.
-   * @param listener The function that will be called whenever the Cell
-   * Ids that appear anywhere in the ResultTable change.
+   * @param listener The function that will be called whenever the Cell Ids that
+   * appear anywhere in the ResultTable change.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that responds to any change to the