edit: updated dependencies, compatabilities

arangojs: ~~v6.14.1~~ → 7.6.1
arangodb: ~~v3.6.5~~ → 3.8.4

Author: hp4k1h5

.eslintrc.js

@@ -0,0 +1,15 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    ecmaFeatures: {},
+  },
+
+  settings: {},
+
+  extends: ['plugin:@typescript-eslint/recommended', 'plugin:prettier/recommended'],
+
+  rules: {},
+}

CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+- v0.1.3
+  - updated dependencies
+    - arangojs: ~~v6.14.1~~ → 7.6.1
+  - updated compatabilities
+    - arangodb: ~~v3.6.5~~ → 3.8.4  
+
 - v0.1.2
   - 📓 Updated docs to properly reflect key names. Prior versions of this
       README were not up to date with the current functionality. Package

README.md

@@ -1,66 +1,50 @@
 # AQLqueryBuilder.js
 > a typescript query builder for [arangodb](https://www.arangodb.com)'s [ArangoSearch](https://www.arangodb.com/docs/stable/arangosearch.html)
 
-See working demo at [hp4k1h5.github.io](https://hp4k1h5.github.io/#search-box).
-
-**!Note** AQLqueryBuilder.js does NOT contain any code for the search bar, only the
-query string parser and AQL builder. Unabstracted code for the searchbar is
-located [here](https://github.com/HP4k1h5/hp4k1h5.github.io/tree/main/demos/src/components/search).
-
-![search bar demonstration with schematic query
-interface](./img/searchbar_demo.png)
-
-- [Patch Notes](#patch-notes)
-- [overview](#overview)
-- [setup](#setup)
-- [installation](#installation)
-- [usage](#usage)
-  - [`buildAQL()`](#buildaql())
-  - [boolean search logic](#boolean-search-logic)
-  - [default query syntax](#default-query-syntax)
-    - [Example](#example)
-- [bugs](#bugs)
-- [contributing](#contributing)
+[![search bar demonstration with schematic query
+interface](./img/searchbar_demo.png)](https://hp4k1h5.github.io/#search-box)
+> See working demo at [hp4k1h5.github.io](https://hp4k1h5.github.io/#search-box).
+
+<!-- vim-markdown-toc GFM -->
+
+* [Patch Notes](#patch-notes)
+* [Compatabilities](#compatabilities)
+* [overview](#overview)
+* [setup](#setup)
+* [installation](#installation)
+* [usage](#usage)
+  * [`buildAQL()`](#buildaql)
+    * [query](#query)
+    * [limit](#limit)
+    * [`query` example](#query-example)
+  * [boolean search logic](#boolean-search-logic)
+    * [`+` AND](#-and)
+    * [`?` OR](#-or)
+    * [`-` NOT](#--not)
+  * [default query syntax](#default-query-syntax)
+    * [Example](#example)
+* [bugs](#bugs)
+* [contributing](#contributing)
+
+<!-- vim-markdown-toc -->
 
 ## Patch Notes
-- v0.1.2
-  - 📓 Updated docs to properly reflect key names. Prior versions of this
-      README were not up to date with the current functionality. Package
-      functionality remains the same. Current and more accurate
-      documentation can be generated by running `yarn doc && serve docs/`.
-
-- v0.1.1
-  - ❌ Breaking change!  
-      `buildAQL()`'s `limit` parameter no longer accepts key
-      `end`, which has been renamed, per Arango spec, to `count`. The functionality
-      remains the same, which is why the patch bump. Please accept my apologies.
-  - 🔑🗝 multi-key search  
-      this can be useful if you
-      have multiple fields with textual information. Theoretically, each
-      chapter of a book could be stored on its own key. Or a document could
-      have be translated into several languages, each stored on its own key.
-      - **There are two ways to provide multiple keys to relevant functions.**
-      1) `query.key` now accepts in addition to a string value, an array of
-      strings over which the query is to be run. All keys listed here will be
-      run combined with all collections provided to `query.collections`
-      **unless** a collection has a `keys` property of its own, in which case
-      **only** those keys are searched against.
-      2) `query.collections[].keys` is an optional array of key names that are
-      indexed by `query.collections[].analyzer`. **Note** It is important that
-      any key listed in `query.collections[].keys` be indexed by the analyzer
-      as it will impact results if such a key does not exist.  
 
+- aqlQueryBuilder.js v0.1.3
+  - updated compatabilities
+    - arangodb: ~~v3.6.5~~ → 3.8.4  
+  - updated dependencies
+    - arangojs: ~~v6.14.1~~ → 7.6.1
 
+## Compatabilities
+
+This package is test against the following versions: 
+- arangojs: 7.6.1
+- arangodb: 3.8.4  
 
 ## overview
 
-ArangoSearch provides a low-level API for interacting with Arango Search Views
-through the Arango Query Language (AQL). This library aims to provide a query
-parser and AQL query builder to enable full boolean search operations across
-all available Arango Search View capabilities, including, `PHRASE` and
-`TOKENS` operations. With minimal syntax overhead the user can generate
-multi-lingual and language-specific, complex phrase, (proximity... TBD) and
-tokenized search terms.
+ArangoSearch provides a low-level API for interacting with Arango Search Views through the Arango Query Language (AQL). This library aims to provide a query parser and AQL query builder to enable full boolean search operations across all available Arango Search View capabilities, including, `PHRASE` and `TOKENS` operations. With minimal syntax overhead the user can generate multi-lingual and language-specific, complex phrase, (proximity... TBD) and tokenized search terms.
 
 For example, passing a search phrase like:
 ```txt
@@ -119,8 +103,7 @@ also accommodate multiple key searches.
 ___
 ## setup
 
-1) running generated AQL queries will require a running ArangoDB v3.6+
-instance. This package is tested against v3.6.5 🥑
+1) running generated AQL queries will require a running ArangoDB v3.8+ instance. This package is tested against arangodb v3.8.4 🥑
 
 ## installation
 currently there is only support for server-side use.

built/filter.d.ts

@@ -1,2 +1,2 @@
 import { filter } from './lib/structs';
-export declare function buildFilters(filters: filter[]): import("arangojs/lib/cjs/aql-query").GeneratedAqlQuery;
+export declare function buildFilters(filters: filter[]): import("arangojs/aql").GeneratedAqlQuery;

built/filter.js

@@ -9,8 +9,8 @@ var arangojs_1 = require("arangojs");
 function buildFilters(filters) {
     if (!filters.length)
         return;
-    var _filters = filters.map(function (f) { return arangojs_1.aql(templateObject_1 || (templateObject_1 = __makeTemplateObject(["doc.", " ", " ", ""], ["doc.", " ", " ", ""])), f.field, arangojs_1.aql.literal(f.op), f.val); });
-    return arangojs_1.aql(templateObject_2 || (templateObject_2 = __makeTemplateObject(["FILTER ", ""], ["FILTER ", ""])), arangojs_1.aql.join(_filters, ' && '));
+    var _filters = filters.map(function (f) { return (0, arangojs_1.aql)(templateObject_1 || (templateObject_1 = __makeTemplateObject(["doc.", " ", " ", ""], ["doc.", " ", " ", ""])), f.field, arangojs_1.aql.literal(f.op), f.val); });
+    return (0, arangojs_1.aql)(templateObject_2 || (templateObject_2 = __makeTemplateObject(["FILTER ", ""], ["FILTER ", ""])), arangojs_1.aql.join(_filters, ' && '));
 }
 exports.buildFilters = buildFilters;
 var templateObject_1, templateObject_2;

built/index.d.ts

@@ -1,8 +1,12 @@
 import { query } from './lib/structs';
 export { buildFilters } from './filter';
 export { parseQuery } from './parse';
-/** @returns an AQL query object. See @param query for
- * details on required values. @param query.terms accepts
- * either a string to be parsed or an array of terms. @param limit is an object with keys `start` default 0, and `end` default 20.
- * */
+/** @returns an AQL query object. See @param query for details on required
+ * values. @param query.terms accepts either a string to be parsed or an array
+ * of terms.
+ *
+ * ! NOTE: v0.1.1 introduced a breaking change to adhere to the ArangoSearch
+ * spec. Please refer to
+ * <https://www.arangodb.com/docs/stable/aql/operations-limit.html> @param
+ * limit is an object with keys `start` @default 0, and `count` @default 20 */
 export declare function buildAQL(query: query, limit?: any): any;

built/index.js

@@ -11,25 +11,30 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     o[k2] = m[k];
 }));
 exports.__esModule = true;
-exports.buildAQL = void 0;
+exports.buildAQL = exports.parseQuery = exports.buildFilters = void 0;
 var arangojs_1 = require("arangojs");
 var search_1 = require("./search");
 var filter_1 = require("./filter");
 var filter_2 = require("./filter");
 __createBinding(exports, filter_2, "buildFilters");
 var parse_1 = require("./parse");
 __createBinding(exports, parse_1, "parseQuery");
-/** @returns an AQL query object. See @param query for
- * details on required values. @param query.terms accepts
- * either a string to be parsed or an array of terms. @param limit is an object with keys `start` default 0, and `end` default 20.
- * */
+/** @returns an AQL query object. See @param query for details on required
+ * values. @param query.terms accepts either a string to be parsed or an array
+ * of terms.
+ *
+ * ! NOTE: v0.1.1 introduced a breaking change to adhere to the ArangoSearch
+ * spec. Please refer to
+ * <https://www.arangodb.com/docs/stable/aql/operations-limit.html> @param
+ * limit is an object with keys `start` @default 0, and `count` @default 20 */
 function buildAQL(query, limit) {
-    if (limit === void 0) { limit = { start: 0, end: 20 }; }
+    if (limit === void 0) { limit = { start: 0, count: 20 }; }
     validateQuery(query);
-    var SEARCH = search_1.buildSearch(query);
-    var FILTER = query.filters && filter_1.buildFilters(query.filters);
+    collectKeys(query);
+    var SEARCH = (0, search_1.buildSearch)(query);
+    var FILTER = query.filters && (0, filter_1.buildFilters)(query.filters);
     /* FOR doc IN ${query.view} */
-    return arangojs_1.aql(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n    FOR doc IN ", "\n      ", "\n      ", "\n      LIMIT ", ", ", "\n    RETURN doc"], ["\n    FOR doc IN ", "\n      ", "\n      ", "\n      LIMIT ", ", ", "\n    RETURN doc"])), arangojs_1.aql.literal(query.view), SEARCH, FILTER, limit.start, limit.end);
+    return (0, arangojs_1.aql)(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n    FOR doc IN ", "\n      ", "\n      ", "\n      LIMIT ", ", ", "\n    RETURN doc"], ["\n    FOR doc IN ", "\n      ", "\n      ", "\n      LIMIT ", ", ", "\n    RETURN doc"])), arangojs_1.aql.literal(query.view), SEARCH, FILTER, limit.start, limit.count);
 }
 exports.buildAQL = buildAQL;
 function validateQuery(query) {
@@ -38,4 +43,21 @@ function validateQuery(query) {
     if (!query.collections.length)
         throw new Error('query.collections must have at least one name');
 }
+function collectKeys(query) {
+    /* unify query.key */
+    var _keys;
+    if (typeof query.key == 'string') {
+        _keys = [query.key];
+    }
+    else if (!query.key) {
+        _keys = ['text'];
+    }
+    else
+        _keys = query.key;
+    query.collections = query.collections.map(function (c) {
+        if (!c.keys)
+            c.keys = _keys;
+        return c;
+    });
+}
 var templateObject_1;

built/lib/structs.d.ts

@@ -1,83 +1,84 @@
 /**
-* passed to buildAQL, i.e. `let generatedAQL = buildAQL(query)`. Properties
-* mimic or match those familiar to AQL.
-* */
+ * passed to buildAQL, i.e. `let generatedAQL = buildAQL(query)`. Properties
+ * mimic or match those familiar to AQL.
+ * */
 export interface query {
     /**
-    * the name of the ArangoSearch View the query will be run against
-    * */
+     * the name of the ArangoSearch View the query will be run against
+     * */
     view: string;
     /**
-    * the names of the collections indexed by @param view to query
-    * */
+     * the names and analyzers  of the collections indexed by @param
+     * view to query
+     * */
     collections: collection[];
     /**
-    * either an array of @param term interfaces or a string to be parsed by `parseQuery()`
-    * */
+     * either an array of @param term interfaces or a string to be parsed by `parseQuery()`
+     * */
     terms: term[] | string;
     /**
-    * the name of the document key to search, currently must be the same across
-    * all documents. @default "text"
-    * */
-    key?: string;
+     * the name(s) of the document key to search. @default "text"
+     * */
+    key?: string[] | string;
     /**
-    * a list of @filter interfaces. All filters are implicitly AND'ed together.
-    * */
+     * a list of @filter interfaces. All filters are implicitly AND'ed together.
+     * */
     filters?: filter[];
 }
 /**
-* Each collection referenced by the ArangoSearch that the user wishes to
-* include in the query must be listed as a collection of the following shape.
-*
-* A collection can be referenced by several analyzers and each must have its
-* own entry in `query.collections` in order to be included in the search.
-*
-* Alternatively, a document can be stored in several collections.
-*
-* In either case all desired collection/analyzer combinations must be
-* specified.
-* */
+ * Each collection referenced by the ArangoSearch that the user wishes to
+ * include in the query must be listed as a collection of the following shape.
+ *
+ * A collection can be referenced by several analyzers and each must have its
+ * own entry in `query.collections` in order to be included in the search. If
+ * a collection does not have a `keys` key, the search will be performed
+ * across ALL keys listed in `query.key`.
+ *
+ * Alternatively, a document can be stored in several collections.
+ *
+ * In either case all desired collection/analyzer combinations must be
+ * specified.
+ * */
 export interface collection {
-    /**
-    * the name of the collection
-    * */
+    /** the name of the collection */
     name: string;
-    /**
-    * the name of the text analyzer
-    * */
+    /** the name of the text analyzer */
     analyzer: string;
+    keys?: string[];
 }
 /**
-* A piece of search query text. Can be a phrase or an individual word, and will
-* belong to one cell or other of the following grid:
-* ```
-*                       **ops**
-*             |        | ANDS | ORS | NOTS  |
-*             | -----  | ---- | --- | ----- |
-*  **types**  | PHRASE |      |     |       |
-*             | TOKENS |      |     |       |
-*             | PROXIM | TODO | TODO| TODO  |
-* ```
-* */
+ * A piece of search query text. Can be a phrase or an individual word, and will
+ * belong to one cell or other of the following grid:
+ * ```
+ *                       **ops**
+ *             |        | ANDS | ORS | NOTS  |
+ *             | -----  | ---- | --- | ----- |
+ *  **types**  | PHRASE |  ✅  | ✅  |  ✅   |
+ *             | TOKENS |  ✅  | ✅  |  ✅   |
+ *             | PROXIM | TODO | TODO| TODO  |
+ *             | NGRAM  | TODO | TODO| TODO  |
+ *             | LEVENS | TODO | TODO| TODO  |
+ * ```
+ * */
 export interface term {
     /**
-    * must be one of [ 'phr', 'tok' ], corresponding to `PHRASE` and
-    * `TOKENS` respectively.
-    **/
+     * must be one of [ 'phr', 'tok' ], corresponding to `PHRASE` and
+     * `TOKENS` respectively.
+     **/
     type: string;
     /**
-    * the search string
-    * */
+     * the search string
+     * */
     val: string;
     /**
-    * must be one of [ '+', '?', '-' ] corresponding to `ANDS`, `ORS`, and
-    * `NOTS`, respectively.
-    * */
+     * must be one of [ '+', '?', '-' ] corresponding to `ANDS`, `ORS`, and
+     * `NOTS`, respectively.
+     * */
     op: string;
 }
 /**
-* passed to AQL `FILTER`
-* */
+ * passed to AQL `FILTER`
+ * */
 export interface filter {
     /** the arango document field name to filter on */
     field: string;