tinybase 7.2.0-beta.2 → 7.2.0

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

@@ -34,8 +34,9 @@ import type {
  * 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.
+ * A ParamValue is a JavaScript string, number, boolean, null - or an array of
+ * strings, numbers, or booleans. Arrays are useful for filtering by multiple
+ * values, such as checking if a cell value is included in a list of options.
  * @example
  * ```js
  * import type {ParamValue} from 'tinybase';
@@ -44,11 +45,21 @@ import type {
  * export const paramValue2: ParamValue = 5;
  * export const paramValue3: ParamValue = true;
  * export const paramValue4: ParamValue = null;
+ * export const paramValue5: ParamValue = ['Ford', 'Toyota', 'Honda'];
+ * export const paramValue6: ParamValue = [1970, 1975, 1980];
+ * export const paramValue7: ParamValue = [true, false];
  * ```
  * @category Params
  * @since v7.2.0
  */
-export type ParamValue = string | number | boolean | null;
+export type ParamValue =
+  | string
+  | number
+  | boolean
+  | null
+  | string[]
+  | number[]
+  | boolean[];
 
 /**
  * The ParamValues type describes an object of param values, keyed by param Id,
@@ -331,6 +342,70 @@ export type QueryIdsListener<Schemas extends OptionalSchemas> = (
   queries: Queries<Schemas>,
 ) => void;
 
+/**
+ * The ParamValuesListener type describes a function that is used to listen to
+ * changes to the param values of a parameterized query.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   queries: Queries,
+ *   queryId: Id,
+ *   paramValues: ParamValues,
+ * ) => void;
+ * ```
+ *
+ * A ParamValuesListener is provided when using the addParamValuesListener
+ * method. See that method for specific examples.
+ *
+ * When called, a ParamValuesListener is given a reference to the Queries
+ * object, and the Id of the query whose param values changed.
+ * @param queries A reference to the Queries object that changed.
+ * @param queryId The Id of the query whose param values changed.
+ * @category Listener
+ * @since v7.2.0
+ */
+export type ParamValuesListener<Schemas extends OptionalSchemas> = (
+  queries: Queries<Schemas>,
+  queryId: Id,
+  paramValues: ParamValues,
+) => void;
+
+/**
+ * The ParamValueListener type describes a function that is used to listen to
+ * changes to a single param value of a parameterized query.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * (
+ *   queries: Queries,
+ *   queryId: Id,
+ *   paramId: Id,
+ *   paramValue: ParamValue,
+ * ) => void;
+ * ```
+ *
+ * A ParamValueListener is provided when using the addParamValueListener method.
+ * See that method for specific examples.
+ *
+ * When called, a ParamValueListener is given a reference to the Queries object,
+ * the Id of the query whose param value changed, and the Id of the param whose
+ * value changed.
+ * @param queries A reference to the Queries object that changed.
+ * @param queryId The Id of the query whose param value changed.
+ * @param paramId The Id of the param whose value changed.
+ * @category Listener
+ * @since v7.2.0
+ */
+export type ParamValueListener<Schemas extends OptionalSchemas> = (
+  queries: Queries<Schemas>,
+  queryId: Id,
+  paramId: Id,
+  paramValue: ParamValue,
+) => void;
+
 /**
  * The ResultTableListener type describes a function that is used to listen to
  * changes to a query's ResultTable.
@@ -824,7 +899,8 @@ export type GetTableCell<
  *
  * 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.
+ * redefining the entire query. Param values can be primitives (string, number,
+ * boolean, null) or arrays of those types.
  * @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
@@ -857,6 +933,40 @@ export type GetTableCell<
  * console.log(queries.getResultTable('query'));
  * // -> {felix: {color: 'black'}}
  * ```
+ * @example
+ * This example shows a query that uses an array param to filter by multiple
+ * values.
+ *
+ * ```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'},
+ *   rex: {species: 'dog', color: 'gold'},
+ * });
+ *
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'query',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where((getTableCell) =>
+ *       (param('colors') as string[])?.includes(getTableCell('color')),
+ *     );
+ *   },
+ *   {colors: ['brown', 'gold']},
+ * );
+ *
+ * console.log(queries.getResultTable('query'));
+ * // -> {fido: {species: 'dog'}, rex: {species: 'dog'}}
+ *
+ * queries.setParamValue('query', 'colors', ['black']);
+ * console.log(queries.getResultTable('query'));
+ * // -> {felix: {species: 'cat'}, cujo: {species: 'dog'}}
+ * ```
  * @category Definition
  * @since v7.2.0
  */
@@ -2123,6 +2233,91 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    */
   delQueryDefinition(queryId: Id): Queries<Schemas>;
 
+  /**
+   * The getParamValues method returns all the param values currently set for a
+   * parameterized query.
+   * @param queryId The Id of the query to get the params for.
+   * @returns An object containing all param Ids and their values, or an empty
+   * object if the query doesn't exist.
+   * @example
+   * This example creates a parameterized query and retrieves its param values.
+   *
+   * ```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'));
+   *     where((getTableCell) => getTableCell('age') >= param('minAge'));
+   *   },
+   *   {species: 'dog', minAge: 5},
+   * );
+   *
+   * console.log(queries.getParamValues('query'));
+   * // -> {species: 'dog', minAge: 5}
+   *
+   * queries.setParamValue('query', 'species', 'cat');
+   * console.log(queries.getParamValues('query'));
+   * // -> {species: 'cat', minAge: 5}
+   * ```
+   * @category Getter
+   * @since v7.2.0
+   */
+  getParamValues(queryId: Id): ParamValues;
+
+  /**
+   * The getParamValue method returns a single param value currently set for a
+   * parameterized query.
+   * @param queryId The Id of the query to get the param for.
+   * @param paramId The Id of the param to get.
+   * @returns The value of the param, or `undefined` if the query or param
+   * doesn't exist.
+   * @example
+   * This example creates a parameterized query and retrieves one of its param
+   * values.
+   *
+   * ```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.getParamValue('query', 'species'));
+   * // -> 'dog'
+   *
+   * queries.setParamValue('query', 'species', 'cat');
+   * console.log(queries.getParamValue('query', 'species'));
+   * // -> 'cat'
+   * ```
+   * @category Getter
+   * @since v7.2.0
+   */
+  getParamValue(queryId: Id, paramId: Id): ParamValue | undefined;
+
   /**
    * The setParamValues method sets multiple param values for a parameterized
    * query at once, causing the query to re-evaluate with the new param values.
@@ -3079,6 +3274,166 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
    */
   addQueryIdsListener(listener: QueryIdsListener<Schemas>): Id;
 
+  /**
+   * The addParamValuesListener method registers a listener function with the
+   * Queries object that will be called whenever the param values of a query
+   * change.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addParamValuesListener(queryId: IdOrNull, listener: ParamValuesListener): Id;
+   * ```
+   *
+   * You can either listen to a single query (by specifying a query Id as the
+   * method's first parameter) or changes to any query (by providing a `null`
+   * wildcard).
+   *
+   * The provided listener is a ParamValuesListener function, and will be called
+   * with a reference to the Queries object, the Id of the query whose param
+   * values changed, and an object containing the new param values.
+   * @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 param values
+   * of the query change.
+   * @example
+   * This example registers two listeners that respond to changes to the param
+   * values of a specific query, or any query respectively.
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   // store data
+   * });
+   *
+   * const queries = createQueries(store).setQueryDefinition(
+   *   'petsByColor',
+   *   'pets',
+   *   () => {
+   *     // query definition
+   *   },
+   *   {color: 'white'},
+   * );
+   *
+   * const listenerId1 = queries.addParamValuesListener(
+   *   'petsByColor',
+   *   (queries, queryId, paramValues) => {
+   *     console.log(
+   *       `Params for specific query changed: ${JSON.stringify(paramValues)}`,
+   *     );
+   *   },
+   * );
+   * const listenerId2 = queries.addParamValuesListener(
+   *   null,
+   *   (queries, queryId, paramValues) => {
+   *     console.log(
+   *       `Params for "${queryId}" changed: ${JSON.stringify(paramValues)}`,
+   *     );
+   *   },
+   * );
+   *
+   * queries.setParamValues('petsByColor', {color: 'black'});
+   * // -> 'Params for specific query changed: {"color":"black"}'
+   * // -> 'Params for "petsByColor" changed: {"color":"black"}'
+   * queries.setParamValues('petsByColor', {color: 'brown'});
+   * // -> 'Params for specific query changed: {"color":"brown"}'
+   * // -> 'Params for "petsByColor" changed: {"color":"brown"}'
+   *
+   * queries.delListener(listenerId1);
+   * queries.delListener(listenerId2);
+   * ```
+   * @category Listener
+   * @since v7.2.0
+   */
+  addParamValuesListener(
+    queryId: IdOrNull,
+    listener: ParamValuesListener<Schemas>,
+  ): Id;
+
+  /**
+   * The addParamValueListener method registers a listener function with the
+   * Queries object that will be called whenever a specific param value of a
+   * query changes.
+   *
+   * This has schema-based typing. The following is a simplified representation:
+   *
+   * ```ts override
+   * addParamValueListener(
+   *   queryId: IdOrNull,
+   *   paramId: IdOrNull,
+   *   listener: ParamValueListener,
+   * ): Id;
+   * ```
+   *
+   * You can either listen to a single query (by specifying a query Id as the
+   * method's first parameter) or changes to any query (by providing a `null`
+   * wildcard). Additionally, you can either listen to a specific param (by
+   * specifying a param Id as the second parameter) or changes to any param (by
+   * providing a `null` wildcard).
+   *
+   * The provided listener is a ParamValueListener function, and will be called
+   * with a reference to the Queries object, the Id of the query whose param
+   * value changed, the Id of the param whose value changed, and the new value
+   * of the param.
+   * @param queryId The Id of the query to listen to, or `null` as a wildcard.
+   * @param paramId The Id of the param to listen to, or `null` as a wildcard.
+   * @param listener The function that will be called whenever the specific
+   * param value of the query changes.
+   * @example
+   * This example registers two listeners that respond to changes to a specific
+   * param value of a specific query, or any param value of any query
+   * respectively.
+   *
+   * ```js
+   * import {createQueries, createStore} from 'tinybase';
+   *
+   * const store = createStore().setTable('pets', {
+   *   // store data
+   * });
+   *
+   * const queries = createQueries(store).setQueryDefinition(
+   *   'petsByColor',
+   *   'pets',
+   *   () => {
+   *     // query definition
+   *   },
+   *   {color: 'white'},
+   * );
+   *
+   * const listenerId1 = queries.addParamValueListener(
+   *   'petsByColor',
+   *   'color',
+   *   (queries, queryId, paramId, value) => {
+   *     console.log(`Specific param for specific query changed: "${value}"`);
+   *   },
+   * );
+   * const listenerId2 = queries.addParamValueListener(
+   *   null,
+   *   null,
+   *   (queries, queryId, paramId, value) => {
+   *     console.log(`Param "${paramId}" for "${queryId}" changed: "${value}"`);
+   *   },
+   * );
+   *
+   * queries.setParamValue('petsByColor', 'color', 'black');
+   * // -> 'Specific param for specific query changed: "black"'
+   * // -> 'Param "color" for "petsByColor" changed: "black"'
+   * queries.setParamValue('petsByColor', 'color', 'brown');
+   * // -> 'Specific param for specific query changed: "brown"'
+   * // -> 'Param "color" for "petsByColor" changed: "brown"'
+   *
+   * queries.delListener(listenerId1);
+   * queries.delListener(listenerId2);
+   * ```
+   * @category Listener
+   * @since v7.2.0
+   */
+  addParamValueListener(
+    queryId: IdOrNull,
+    paramId: IdOrNull,
+    listener: ParamValueListener<Schemas>,
+  ): Id;
+
   /**
    * The addResultTableListener method registers a listener function with the
    * Queries object that will be called whenever data in a ResultTable changes.