[params] Getters

Author: jamesgpearce

src/@types/queries/docs.js

@@ -1816,6 +1816,89 @@
    * @since v2.0.0
    */
   /// Queries.delQueryDefinition
+  /**
+   * 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
+   * `undefined` 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
+   */
+  /// Queries.getParamValues
+  /**
+   * 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
+   */
+  /// Queries.getParamValue
   /**
    * The setParamValues method sets multiple param values for a parameterized
    * query at once, causing the query to re-evaluate with the new param values.

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

@@ -290,6 +290,12 @@ export interface Queries {
   /// Queries.delQueryDefinition
   delQueryDefinition(queryId: Id): Queries;
 
+  /// Queries.getParamValues
+  getParamValues(queryId: Id): ParamValues | undefined;
+
+  /// Queries.getParamValue
+  getParamValue(queryId: Id, paramId: Id): ParamValue | undefined;
+
   /// Queries.setParamValues
   setParamValues(queryId: Id, paramValues: ParamValues): Queries;
 

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

@@ -376,6 +376,12 @@ export interface Queries<in out Schemas extends OptionalSchemas> {
   /// Queries.delQueryDefinition
   delQueryDefinition(queryId: Id): Queries<Schemas>;
 
+  /// Queries.getParamValues
+  getParamValues(queryId: Id): ParamValues | undefined;
+
+  /// Queries.getParamValue
+  getParamValue(queryId: Id, paramId: Id): ParamValue | undefined;
+
   /// Queries.setParamValues
   setParamValues(queryId: Id, paramValues: ParamValues): Queries<Schemas>;
 

src/queries/index.ts

@@ -615,6 +615,12 @@ export const createQueries = getCreateFunction((store: Store): Queries => {
       [paramId]: value,
     });
 
+  const getParamValues = (queryId: Id): ParamValues | undefined =>
+    ifNotUndefined(getQueryArgs(queryId)?.[1], mapToObj);
+
+  const getParamValue = (queryId: Id, paramId: Id): ParamValue | undefined =>
+    mapGet(getQueryArgs(queryId)?.[1], paramId);
+
   const addQueryIdsListener = (listener: QueryIdsListener) =>
     addQueryIdsListenerImpl(() => listener(queries));
 
@@ -636,6 +642,8 @@ export const createQueries = getCreateFunction((store: Store): Queries => {
   const queries: any = {
     setQueryDefinition,
     delQueryDefinition,
+    getParamValues,
+    getParamValue,
     setParamValues,
     setParamValue,
 

test/unit/core/other/queries.test.ts

@@ -4767,6 +4767,45 @@ describe('Parameterized', () => {
         r3: {c1: 'c', c4: true},
       });
     });
+
+    test('getParamValues', () => {
+      queries.setQueryDefinition(
+        'q1',
+        't1',
+        ({select, where, param}) => {
+          select('c1');
+          where('c2', param('p2') as Cell);
+        },
+        {p2: 'odd', p3: 5},
+      );
+
+      expect(queries.getParamValues('q1')).toEqual({p2: 'odd', p3: 5});
+
+      queries.setParamValue('q1', 'p2', 'even');
+      expect(queries.getParamValues('q1')).toEqual({p2: 'even', p3: 5});
+
+      expect(queries.getParamValues('nonexistent')).toBeUndefined();
+    });
+
+    test('getParamValue', () => {
+      queries.setQueryDefinition(
+        'q1',
+        't1',
+        ({select, where, param}) => {
+          select('c1');
+          where('c2', param('p2') as Cell);
+        },
+        {p2: 'odd', p3: 5},
+      );
+
+      expect(queries.getParamValue('q1', 'p2')).toBe('odd');
+      expect(queries.getParamValue('q1', 'p3')).toBe(5);
+      expect(queries.getParamValue('q1', 'nonexistent')).toBeUndefined();
+      expect(queries.getParamValue('nonexistent', 'p2')).toBeUndefined();
+
+      queries.setParamValue('q1', 'p2', 'even');
+      expect(queries.getParamValue('q1', 'p2')).toBe('even');
+    });
   });
 
   describe('Select', () => {