[params] Array params

Author: jamesgpearce

src/@types/queries/docs.js

@@ -15,8 +15,9 @@
  * 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';
@@ -25,6 +26,9 @@
  * 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
@@ -597,7 +601,8 @@
  *
  * 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
@@ -630,6 +635,40 @@
  * 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
  */

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

@@ -9,7 +9,14 @@ import type {
 } from '../store/index.d.ts';
 
 /// ParamValue
-export type ParamValue = string | number | boolean | null;
+export type ParamValue =
+  | string
+  | number
+  | boolean
+  | null
+  | string[]
+  | number[]
+  | boolean[];
 
 /// ParamValues
 export type ParamValues = {[paramId: Id]: ParamValue};

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

@@ -20,7 +20,14 @@ import type {
 } from '../../store/with-schemas/index.d.ts';
 
 /// ParamValue
-export type ParamValue = string | number | boolean | null;
+export type ParamValue =
+  | string
+  | number
+  | boolean
+  | null
+  | string[]
+  | number[]
+  | boolean[];
 
 /// ParamValues
 export type ParamValues = {[paramId: Id]: ParamValue};

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

@@ -1,6 +1,6 @@
 import {beforeEach, describe, expect, test, vi} from 'vitest';
 
-import type {Id, Queries, Store} from 'tinybase';
+import type {Cell, Id, Queries, Store} from 'tinybase';
 import {createQueries, createStore} from 'tinybase';
 import {expectChanges, expectNoChanges} from '../../common/expect.ts';
 import {createQueriesListener} from '../../common/listeners.ts';
@@ -4551,7 +4551,7 @@ describe('Parameterized', () => {
         't1',
         ({select, where, param}) => {
           select('c2');
-          where('c2', param('p2') ?? '');
+          where('c2', param('p2') as Cell);
         },
         {p2: 'odd'},
       );
@@ -4663,6 +4663,110 @@ describe('Parameterized', () => {
 
       expect(queries.getResultTable('q1')).toEqual({r1: {c4: true}});
     });
+
+    test('param with string array value', () => {
+      queries.setQueryDefinition(
+        'q1',
+        't1',
+        ({select, where, param}) => {
+          select('c1');
+          select('c2');
+          where((getTableCell) =>
+            (param('colors') as string[])?.includes(
+              getTableCell('c2') as string,
+            ),
+          );
+        },
+        {colors: ['odd', 'even']},
+      );
+
+      expect(queries.getResultTable('q1')).toEqual({
+        r1: {c1: 'a', c2: 'odd'},
+        r2: {c1: 'b', c2: 'even'},
+        r3: {c1: 'c', c2: 'odd'},
+        r4: {c1: 'd', c2: 'even'},
+        r5: {c1: 'e', c2: 'odd'},
+      });
+
+      queries.setParamValue('q1', 'colors', ['odd']);
+      expect(queries.getResultTable('q1')).toEqual({
+        r1: {c1: 'a', c2: 'odd'},
+        r3: {c1: 'c', c2: 'odd'},
+        r5: {c1: 'e', c2: 'odd'},
+      });
+
+      queries.setParamValue('q1', 'colors', ['even']);
+      expect(queries.getResultTable('q1')).toEqual({
+        r2: {c1: 'b', c2: 'even'},
+        r4: {c1: 'd', c2: 'even'},
+      });
+    });
+
+    test('param with number array value', () => {
+      queries.setQueryDefinition(
+        'q1',
+        't1',
+        ({select, where, param}) => {
+          select('c1');
+          select('c3');
+          where((getTableCell) =>
+            (param('values') as number[])?.includes(
+              getTableCell('c3') as number,
+            ),
+          );
+        },
+        {values: [1, 3, 5]},
+      );
+
+      expect(queries.getResultTable('q1')).toEqual({
+        r1: {c1: 'a', c3: 1},
+        r3: {c1: 'c', c3: 3},
+        r5: {c1: 'e', c3: 5},
+      });
+
+      queries.setParamValue('q1', 'values', [2, 4]);
+      expect(queries.getResultTable('q1')).toEqual({
+        r2: {c1: 'b', c3: 2},
+        r4: {c1: 'd', c3: 4},
+      });
+    });
+
+    test('param with boolean array value', () => {
+      store.setCell('t1', 'r1', 'c4', true);
+      store.setCell('t1', 'r2', 'c4', false);
+      store.setCell('t1', 'r3', 'c4', true);
+      queries.setQueryDefinition(
+        'q1',
+        't1',
+        ({select, where, param}) => {
+          select('c1');
+          select('c4');
+          where((getTableCell) =>
+            (param('flags') as boolean[])?.includes(
+              getTableCell('c4') as boolean,
+            ),
+          );
+        },
+        {flags: [true]},
+      );
+
+      expect(queries.getResultTable('q1')).toEqual({
+        r1: {c1: 'a', c4: true},
+        r3: {c1: 'c', c4: true},
+      });
+
+      queries.setParamValue('q1', 'flags', [false]);
+      expect(queries.getResultTable('q1')).toEqual({
+        r2: {c1: 'b', c4: false},
+      });
+
+      queries.setParamValue('q1', 'flags', [true, false]);
+      expect(queries.getResultTable('q1')).toEqual({
+        r1: {c1: 'a', c4: true},
+        r2: {c1: 'b', c4: false},
+        r3: {c1: 'c', c4: true},
+      });
+    });
   });
 
   describe('Select', () => {
@@ -4737,7 +4841,7 @@ describe('Parameterized', () => {
         ({select, where, group, param}) => {
           select('c2');
           select('c3');
-          where('c2', param('p2') ?? '');
+          where('c2', param('p2') as Cell);
           group('c3', 'avg').as('a');
         },
         {p2: 'odd'},