@thi.ng/oquery 2.1.46 → 2.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-08-27T11:20:59Z
+- **Last updated**: 2023-09-15T12:33:37Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,21 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/oquery@2.2.0) (2023-09-15)
+
+#### 🚀 Features
+
+- add multi-term query() function ([e35519a](https://github.com/thi-ng/umbrella/commit/e35519a))
+  - add/update types
+- add matchers for use w/ query() ([20e1baf](https://github.com/thi-ng/umbrella/commit/20e1baf))
+  - add matchStrings(), matchPattern(), matchCompare()
+  - add tests
+- add matchMultiple(), refactor ([90a7f0b](https://github.com/thi-ng/umbrella/commit/90a7f0b))
+  - add/extract matchMultiple()
+  - add MatchMultipleOpts()
+  - refactor matchStrings() as syntax sugar
+  - update tests
+
 ## [2.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/oquery@2.1.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -25,9 +25,14 @@ This project is part of the
 
 ## About
 
-Datalog-inspired, optimized pattern/predicate query engine for JS objects & arrays.
+Datalog-inspired, optimized pattern/predicate query engine for JS objects & arrays of objects.
 
-This package provides a single higher-order function `defQuery()`, which takes a
+**IMPORTANT: This README is currently somewhat out-of-date and does not yet
+cover new important features introduced with version 2.2.0 onwards, please
+consult API docs (and/or source code) to view newly added functions and their
+usage...**
+
+This package provides a higher-order function `defQuery()`, which takes a
 number of options to configure query behavior and returns an actual query
 function. This returned function can then be used for pattern matching of
 objects and arrays of objects.
@@ -43,7 +48,6 @@ objects and arrays of objects.
 Some of the below features are already partially addressed by other
 thi.ng/umbrella packages, but would benefit from a more unified approach.
 
-- [ ] query joins (AND queries)
 - [ ] optional queries (OR queries)
 - [ ] result projection
 - [ ] result aggregation/grouping
@@ -75,12 +79,13 @@ For Node.js REPL:
 const oquery = await import("@thi.ng/oquery");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.15 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.66 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
+- [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
 - [@thi.ng/defmulti](https://github.com/thi-ng/umbrella/tree/develop/packages/defmulti)
 - [@thi.ng/equiv](https://github.com/thi-ng/umbrella/tree/develop/packages/equiv)
 
@@ -152,9 +157,9 @@ import { defQuery } from "@thi.ng/oquery";
 
 // create query w/ custom options
 // (options explained further below...)
-const query = defQuery({ partial: true });
+const q = defQuery({ partial: true });
 
-console.log(query(DB, null, "knows", "bob"));
+console.log(q(DB, null, "knows", "bob"));
 // {
 //   alice: { knows: [ 'bob' ] },
 //   charlie: { knows: [ 'bob' ] },
@@ -186,9 +191,9 @@ Further variations:
 key value(s) are matched, using the same logic for the other two terms as in the
 table above.
 
-```ts
+```ts tangle:export/readme.ts
 // Who does Alice know?
-query(DB, "alice", "knows", null)
+q(DB, "alice", "knows", null)
 // { alice: { knows: [ 'bob', 'charlie', 'dori' ] } }
 ```
 
@@ -196,9 +201,9 @@ query(DB, "alice", "knows", null)
 predicate will be matched (again using same rules as above for the other query
 terms).
 
-```ts
+```ts tangle:export/readme.ts
 // Anyone with initial "A" knows Charlie?
-query(DB, (s) => s[0] === "a", "knows", "charlie")
+q(DB, (s) => s[0] === "a", "knows", "charlie")
 // { alice: { knows: [ 'charlie' ] } }
 ```
 
@@ -206,14 +211,16 @@ query(DB, (s) => s[0] === "a", "knows", "charlie")
 this case, only predicate-object patterns are used (**no subject terms**, aka
 array indices in this case).
 
-```ts
-const DBALT = [
+```ts tangle:export/readme.ts
+type Person = { id: string; knows: string[] };
+
+const DBALT: Person[] = [
   { id: "alice", knows: ["bob", "charlie"] },
   { id: "bob", knows: ["alice"] },
   { id: "charlie", knows: ["alice","bob","dori"] },
 ];
 
-defQuery()(DBALT, "knows", "alice")
+defQuery<Person[]>()(DBALT, "knows", "alice")
 // [
 //   { id: 'bob', knows: [ 'alice' ] },
 //   { id: 'charlie', knows: [ 'alice', 'bob', 'dori' ] }
@@ -225,22 +232,22 @@ defQuery()(DBALT, "knows", "alice")
 The following example is using the `DB` object defined [further
 above](#query-patterns)...
 
-```ts
+```ts tangle:export/readme2.ts
 import { defQuery } from "@thi.ng/oquery";
 
 // using partial result objects option for brevity here
-const query = defQuery({ partial: true });
+const q = defQuery({ partial: true });
 
 // find all subjects with `type = "person"` relationship
-query(DB, null, "type", "person");
+q(DB, null, "type", "person");
 // { alice: { type: 'person' }, bob: { type: 'person' } }
 
 // everyone w/ given min age
-query(DB, null, "age", (age) => age >= 33)
+q(DB, null, "age", (age) => age >= 33)
 // { alice: { age: 33 } }
 
 // select only subjects with A/B initials
-query(DB, (id) => id >= "a" && id < "c", null, null)
+q(DB, (id) => id >= "a" && id < "c", null, null)
 // {
 //   alice: { age: 33, knows: [ 'bob', 'charlie', 'dori' ], type: 'person' },
 //   bob: { age: 32, knows: [ 'alice' ], type: 'person', spouse: 'alice' }
@@ -249,7 +256,7 @@ query(DB, (id) => id >= "a" && id < "c", null, null)
 
 Union vs. intersection queries:
 
-```ts
+```ts tangle:export/readme2.ts
 const union = defQuery();
 
 // who knows bob OR charlie?

package/api.d.ts

@@ -1,9 +1,9 @@
-import type { Fn6, IObjectOf, NumOrString, Predicate, Predicate2 } from "@thi.ng/api";
+import type { Fn, Fn6, FnU, Keys, NumOrString, Predicate, Predicate2 } from "@thi.ng/api";
 export type FTerm = Predicate<any>;
 export type OTerm = any | null;
 export type SPTerm = Predicate<string> | NumOrString | null;
 export type SPInputTerm = SPTerm | NumOrString[] | Set<NumOrString>;
-export type QueryObj = IObjectOf<any>;
+export type QueryObj = Record<string, any>;
 /**
  * All 27 possible query types.
  *
@@ -33,7 +33,7 @@ export type QueryImpls = Record<QueryType, QueryImpl>;
  * If `res` is provided, results will be injected in that object. Otherwise
  * a new result object will be created.
  */
-export type ObjQueryFn<T extends QueryObj> = (obj: T, s: SPInputTerm, p: SPInputTerm, o: OTerm, res?: QueryObj) => QueryObj;
+export type ObjQueryFn<T extends QueryObj = QueryObj> = (obj: T, s: SPInputTerm, p: SPInputTerm, o: OTerm, res?: QueryObj) => QueryObj;
 /**
  * Takes a source array of objects with this structure: [{p1: o, p2: ...},
  * ...]`, and matches each item using provided `p`(redicate) and `o`bject terms.
@@ -43,7 +43,7 @@ export type ObjQueryFn<T extends QueryObj> = (obj: T, s: SPInputTerm, p: SPInput
  * If `res` is provided, results will be appended to that array. Otherwise a new
  * result array will be created.
  */
-export type ArrayQueryFn<T extends QueryObj[]> = (src: T, p: SPInputTerm, o: OTerm, res?: QueryObj[]) => QueryObj[];
+export type ArrayQueryFn<T extends QueryObj[]> = (src: T, p: SPInputTerm, o: OTerm, res?: T) => T;
 /**
  * Similar to {@link ObjQueryFn}, but only collects and returns a set of
  * matching `s` keys.
@@ -108,10 +108,10 @@ export interface QueryOpts {
      */
     cwise: boolean;
     /**
-     * Only used if `cwise` is enabled. If false (default), an array or Set
+     * Only used if `cwise` is enabled. If true, ALL of the query elements must
+     * match (aka intersection query). If false (default), an array or Set
      * query term in O(bject) position will succeed if at least ONE of its
-     * elements is matched (aka union query). If true, ALL of the query elements
-     * must matched (aka intersection query).
+     * elements is matched (aka union query). .
      *
      * @defaultValue false
      */
@@ -128,4 +128,34 @@ export interface QueryOpts {
  */
 export interface KeyQueryOpts extends Pick<QueryOpts, "cwise" | "intersect" | "equiv"> {
 }
+export interface QueryTerm<T extends QueryObj = QueryObj> {
+    /**
+     * Actual query expressed as tuple of `[key, value]` tuple. Predicate
+     * functions can be used in either position.
+     */
+    q: [Keys<T> | Predicate<string> | null, any];
+    /**
+     * Optional function to post-process query results.
+     */
+    post?: FnU<T[]>;
+    /**
+     * Query options for this term.
+     */
+    opts?: Partial<QueryOpts>;
+}
+export interface MultiQueryOpts<T extends QueryObj = QueryObj> {
+    /**
+     * Max number of query results. Default: unlimited
+     */
+    limit: number;
+    /**
+     * If given, results are sorted by this key.
+     */
+    sort: Keys<T> | Fn<T, any>;
+    /**
+     * Only used if {@link MultiQueryOpts.sort} is given. If true, reverses sort
+     * order.
+     */
+    reverse: boolean;
+}
 //# sourceMappingURL=api.d.ts.map

package/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./api.js";
+export * from "./match.js";
 export * from "./query.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,2 +1,3 @@
 export * from "./api.js";
+export * from "./match.js";
 export * from "./query.js";

package/match.d.ts

@@ -0,0 +1,120 @@
+import type { Fn, NumOrString, Predicate } from "@thi.ng/api";
+import { type Operator } from "@thi.ng/compare";
+import type { QueryObj, QueryOpts, QueryTerm } from "./api.js";
+export interface MatchMultipleOpts<T> {
+    /**
+     * If true, performs union query. I.e. only one of the provided matches
+     * needs to succeed.
+     */
+    union: boolean;
+    /**
+     * Transformation function to extract an array of values to be matched from
+     * a query item.
+     */
+    value: Fn<any, T[]>;
+}
+/**
+ * Syntax sugar for {@link matchMultiple} using string arrays. Matches set of
+ * given strings against an item's chosen field of strings and by default only
+ * succeeds if all provided strings can be matched.
+ *
+ * @remarks
+ * Any provided string prefixed with `!` is treated as an exclusion and any item
+ * which contains any of these exclusions is automatically rejected, even if
+ * other strings could be matched.
+ *
+ * See {@link matchMultiple} for more details & code example.
+ *
+ * @param key
+ * @param matches
+ * @param opts
+ * @returns
+ */
+export declare const matchStrings: <T extends QueryObj = QueryObj>(key: QueryTerm["q"][0], matches: string[], opts?: Partial<MatchMultipleOpts<string>>) => QueryTerm<T>;
+/**
+ * Returns a {@link QueryTerm} for use with {@link query} to perform set-like
+ * intersection or union queries with optional negation/exclusions. Matches set
+ * of given values against an item's chosen field of values and by default only
+ * succeeds if all provided `includes` can be matched (aka intersection query)
+ * and there're no values from `excludes` present.
+ *
+ * @remarks
+ * If the `union` option is true, only one of the provided values needs to
+ * match. Exclusions _always_ take precedence.
+ *
+ * Note: See {@link matchStrings} for a syntax sugar of this function, aimed at
+ * matching `string[]` options.
+ *
+ * @example
+ * ```ts
+ * const DB = [
+ *   { id: 1, tags: ["a", "b"] },
+ *   { id: 2, tags: ["c", "b"] },
+ *   { id: 3, tags: ["c", "a"] },
+ * ];
+ *
+ * // tag intersection
+ * query(DB, [matchStrings("tags", ["a", "b"])])
+ * // [ { id: 1, tags: ["a", "b"] } ]
+ *
+ * // tag union
+ * query(DB, [matchStrings("tags", ["a", "b"])])
+ * // here returns full DB...
+ * // since each item either has `a` and/or `b` tags
+ *
+ * // tag exclusion (require `a`, disallow `b`)
+ * query(DB, [matchStrings("tags", ["a", "!b"])])
+ * // [ { id: 3, tags: ["c", "a"] } ]
+ * ```
+ *
+ * @param key
+ * @param matches
+ * @param opts
+ */
+export declare const matchMultiple: <T extends QueryObj = QueryObj, V = any>(key: QueryTerm["q"][0], includes: V[], excludes: V[], opts?: Partial<MatchMultipleOpts<V>> | undefined) => QueryTerm<T>;
+/**
+ * Returns a {@link QueryTerm} to match a key's value against a regexp or string
+ * expression.
+ *
+ * @remarks
+ * If `expr` is a regexp it will be used as is, but if given a string the
+ * following rules apply:
+ *
+ * - if `expr` is the sole `*` it will match any non-null value
+ * - if `expr` starts with `=`, `!=`, `<`, `<=`, `>=` or `>`, values will be
+ *   matched using comparators. If the following chars in `expr` are numeric,
+ *   the comparisons will be done as numbers otherwise as strings. Whitespace
+ *   between operator and value are ignored.
+ *
+ * @example
+ * ```ts
+ * const DB = [
+ *   { id: "aaa", score: 32 },
+ *   { id: "bbbb", score: 60 },
+ *   { id: "c", score: 15 },
+ * ];
+ *
+ * query(DB, [matchPattern("id", /[a-z]{4,}/)]);
+ * // [{ id: "bbbb", score: 60 }]
+ * query(DB, [matchPattern("id", ">= c")]);
+ * // [{ id: "c", score: 15 }]
+ *
+ * query(DB, [matchPattern("score", "<50")]);
+ * // [{ id: "a", score: 32 }, { id: "c", score: 15 }]
+ * ```
+ *
+ * @param key
+ * @param expr
+ * @param opts
+ */
+export declare const matchPattern: <T extends QueryObj = QueryObj>(key: QueryTerm["q"][0], expr: string | RegExp, opts?: Partial<QueryOpts>) => QueryTerm<T>;
+/**
+ * Same as the comparison expression case of {@link matchPattern}, only
+ * accepting different args.
+ *
+ * @param key
+ * @param match
+ * @param opts
+ */
+export declare const matchCompare: <T extends QueryObj = QueryObj>(key: QueryTerm["q"][0], op: Operator | Predicate<any>, arg: NumOrString, opts?: Partial<QueryOpts>) => QueryTerm<T>;
+//# sourceMappingURL=match.d.ts.map

package/match.js

@@ -0,0 +1,169 @@
+import { isNumber } from "@thi.ng/checks/is-number";
+import { isString } from "@thi.ng/checks/is-string";
+import { numericOp, stringOp } from "@thi.ng/compare";
+/**
+ * Syntax sugar for {@link matchMultiple} using string arrays. Matches set of
+ * given strings against an item's chosen field of strings and by default only
+ * succeeds if all provided strings can be matched.
+ *
+ * @remarks
+ * Any provided string prefixed with `!` is treated as an exclusion and any item
+ * which contains any of these exclusions is automatically rejected, even if
+ * other strings could be matched.
+ *
+ * See {@link matchMultiple} for more details & code example.
+ *
+ * @param key
+ * @param matches
+ * @param opts
+ * @returns
+ */
+export const matchStrings = (key, matches, opts) => {
+    const [includes, excludes] = matches.reduce((acc, x) => {
+        x[0] === "!" ? acc[1].push(x.substring(1)) : acc[0].push(x);
+        return acc;
+    }, [[], []]);
+    return matchMultiple(key, includes, excludes, opts);
+};
+/**
+ * Returns a {@link QueryTerm} for use with {@link query} to perform set-like
+ * intersection or union queries with optional negation/exclusions. Matches set
+ * of given values against an item's chosen field of values and by default only
+ * succeeds if all provided `includes` can be matched (aka intersection query)
+ * and there're no values from `excludes` present.
+ *
+ * @remarks
+ * If the `union` option is true, only one of the provided values needs to
+ * match. Exclusions _always_ take precedence.
+ *
+ * Note: See {@link matchStrings} for a syntax sugar of this function, aimed at
+ * matching `string[]` options.
+ *
+ * @example
+ * ```ts
+ * const DB = [
+ *   { id: 1, tags: ["a", "b"] },
+ *   { id: 2, tags: ["c", "b"] },
+ *   { id: 3, tags: ["c", "a"] },
+ * ];
+ *
+ * // tag intersection
+ * query(DB, [matchStrings("tags", ["a", "b"])])
+ * // [ { id: 1, tags: ["a", "b"] } ]
+ *
+ * // tag union
+ * query(DB, [matchStrings("tags", ["a", "b"])])
+ * // here returns full DB...
+ * // since each item either has `a` and/or `b` tags
+ *
+ * // tag exclusion (require `a`, disallow `b`)
+ * query(DB, [matchStrings("tags", ["a", "!b"])])
+ * // [ { id: 3, tags: ["c", "a"] } ]
+ * ```
+ *
+ * @param key
+ * @param matches
+ * @param opts
+ */
+export const matchMultiple = (key, includes, excludes, opts) => {
+    const { union, value: valueFn } = { union: false, ...opts };
+    return excludes.length
+        ? {
+            q: [
+                key,
+                (values) => {
+                    const $values = valueFn ? valueFn(values) : values;
+                    for (let x of excludes) {
+                        if ($values.includes(x))
+                            return false;
+                    }
+                    let match = false;
+                    for (let x of includes) {
+                        if ($values.includes(x)) {
+                            match = true;
+                            if (union)
+                                break;
+                        }
+                        else if (!union) {
+                            match = false;
+                            break;
+                        }
+                    }
+                    return match;
+                },
+            ],
+            opts: { cwise: false },
+        }
+        : { q: [key, includes], opts: { intersect: !union } };
+};
+/**
+ * Returns a {@link QueryTerm} to match a key's value against a regexp or string
+ * expression.
+ *
+ * @remarks
+ * If `expr` is a regexp it will be used as is, but if given a string the
+ * following rules apply:
+ *
+ * - if `expr` is the sole `*` it will match any non-null value
+ * - if `expr` starts with `=`, `!=`, `<`, `<=`, `>=` or `>`, values will be
+ *   matched using comparators. If the following chars in `expr` are numeric,
+ *   the comparisons will be done as numbers otherwise as strings. Whitespace
+ *   between operator and value are ignored.
+ *
+ * @example
+ * ```ts
+ * const DB = [
+ *   { id: "aaa", score: 32 },
+ *   { id: "bbbb", score: 60 },
+ *   { id: "c", score: 15 },
+ * ];
+ *
+ * query(DB, [matchPattern("id", /[a-z]{4,}/)]);
+ * // [{ id: "bbbb", score: 60 }]
+ * query(DB, [matchPattern("id", ">= c")]);
+ * // [{ id: "c", score: 15 }]
+ *
+ * query(DB, [matchPattern("score", "<50")]);
+ * // [{ id: "a", score: 32 }, { id: "c", score: 15 }]
+ * ```
+ *
+ * @param key
+ * @param expr
+ * @param opts
+ */
+export const matchPattern = (key, expr, opts) => {
+    let re;
+    if (expr instanceof RegExp) {
+        re = expr;
+    }
+    else {
+        if (expr === "*")
+            return { q: [key, (x) => x != null], opts };
+        if (/^[<>=!]/.test(expr)) {
+            const op = /^[<>=!]+/.exec(expr)[0];
+            const arg = expr.substring(op.length).trim();
+            const argN = parseFloat(arg);
+            return matchCompare(key, op, isNaN(argN) ? arg : argN, opts);
+        }
+        re = new RegExp(expr, "i");
+    }
+    return {
+        q: [
+            key,
+            (x) => (isString(x) || isNumber(x)) && re.test(String(x)),
+        ],
+        opts,
+    };
+};
+/**
+ * Same as the comparison expression case of {@link matchPattern}, only
+ * accepting different args.
+ *
+ * @param key
+ * @param match
+ * @param opts
+ */
+export const matchCompare = (key, op, arg, opts) => ({
+    q: [key, isNumber(arg) ? numericOp(op, arg) : stringOp(op, arg)],
+    opts,
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/oquery",
-  "version": "2.1.46",
-  "description": "Datalog-inspired, optimized pattern/predicate query engine for JS objects & arrays",
+  "version": "2.2.0",
+  "description": "Datalog-inspired, optimized pattern/predicate query engine for JS objects & arrays of objects",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -36,7 +36,8 @@
   "dependencies": {
     "@thi.ng/api": "^8.9.5",
     "@thi.ng/checks": "^3.4.5",
-    "@thi.ng/defmulti": "^2.1.44",
+    "@thi.ng/compare": "^2.2.0",
+    "@thi.ng/defmulti": "^3.0.0",
     "@thi.ng/equiv": "^2.1.30"
   },
   "devDependencies": {
@@ -78,6 +79,9 @@
     "./api": {
       "default": "./api.js"
     },
+    "./match": {
+      "default": "./match.js"
+    },
     "./query": {
       "default": "./query.js"
     }
@@ -91,5 +95,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "5929dd20497668496af13415cdf784a4d6f69aa3\n"
+  "gitHead": "b2ef5a1b8932d067af4ec2fc7da03d59d6868dc7\n"
 }

package/query.d.ts

@@ -1,4 +1,5 @@
-import type { KeyQueryFn, KeyQueryOpts, QueryFn, QueryObj, QueryOpts } from "./api.js";
+import type { Nullable } from "@thi.ng/api";
+import type { KeyQueryFn, KeyQueryOpts, MultiQueryOpts, QueryFn, QueryObj, QueryOpts, QueryTerm } from "./api.js";
 /**
  * Generic Higher-order function to return an actual query function based on
  * given behavior options.
@@ -25,4 +26,21 @@ export declare const defQuery: <T extends QueryObj | QueryObj[] = QueryObj>(opts
  * @param opts -
  */
 export declare const defKeyQuery: <T extends QueryObj | QueryObj[] = QueryObj>(opts?: Partial<KeyQueryOpts>) => KeyQueryFn<T>;
+/**
+ * Multi-term query function for collections (arrays) of {@link QueryObj}ects.
+ * Takes a number of {@link QueryTerm}s and matches each term in succession
+ * against the array of results of the previous terms (i.e. each sub-query is
+ * potentially further narrowing the result set). Returns final results,
+ * possibly post-processed, depending on given options.
+ *
+ * @remarks
+ * Each {@link QueryTerm} can provide its own options and post-processing
+ * function. Furthermore, global post-processing (e.g. limiting number of final
+ * results, sorting by key) can be configured via `opts`.
+ *
+ * @param db
+ * @param terms
+ * @param opts
+ */
+export declare const query: <T extends QueryObj = QueryObj>(db: T[], terms: Nullable<QueryTerm<T>>[], opts?: Partial<MultiQueryOpts<T>>) => T[];
 //# sourceMappingURL=query.d.ts.map

package/query.js

@@ -1,6 +1,9 @@
 import { isArray } from "@thi.ng/checks/is-array";
 import { isFunction } from "@thi.ng/checks/is-function";
 import { isSet } from "@thi.ng/checks/is-set";
+import { compare } from "@thi.ng/compare/compare";
+import { compareByKey } from "@thi.ng/compare/keys";
+import { reverse } from "@thi.ng/compare/reverse";
 import { defmulti } from "@thi.ng/defmulti/defmulti";
 import { equiv } from "@thi.ng/equiv";
 /**
@@ -394,3 +397,37 @@ export const defKeyQuery = (opts) => {
         }
     });
 };
+/**
+ * Multi-term query function for collections (arrays) of {@link QueryObj}ects.
+ * Takes a number of {@link QueryTerm}s and matches each term in succession
+ * against the array of results of the previous terms (i.e. each sub-query is
+ * potentially further narrowing the result set). Returns final results,
+ * possibly post-processed, depending on given options.
+ *
+ * @remarks
+ * Each {@link QueryTerm} can provide its own options and post-processing
+ * function. Furthermore, global post-processing (e.g. limiting number of final
+ * results, sorting by key) can be configured via `opts`.
+ *
+ * @param db
+ * @param terms
+ * @param opts
+ */
+export const query = (db, terms, opts = {}) => {
+    for (let term of terms) {
+        if (!term)
+            continue;
+        db = (defQuery(term.opts)(db, term.q[0], term.q[1]));
+        term.post && (db = term.post(db));
+        if (!db.length)
+            return db;
+    }
+    const limit = opts.limit || 0;
+    if (limit > 0 && limit < db.length) {
+        db.length = limit;
+    }
+    if (opts.sort) {
+        db.sort(compareByKey(opts.sort, opts.reverse ? reverse(compare) : compare));
+    }
+    return db;
+};