Merge pull request #5 from HP4k1h5/v0.0.4

V0.0.4

Author: hp4k1h5

.github/CONTRIBUTING.md

@@ -27,9 +27,19 @@ When contributing code, please:
 and should be the only version branch available. Don't hesitate to ask if it
 is unclear.
 4) make changes
-5) add tests; currently using mochai/chai
-  run tests with e.g. `yarn test tests/glob`
-6) add comments to your functions, and if possible, in the
+5) add tests; using mochai/chai
+  run tests with e.g. `yarn test tests/glob`  
+  or  
+  `yarn tests` to run the suite
+  see [testing](#testing) for more information.
+6) add comments, and if possible, in the
 [typedoc](https://github.com/TypeStrong/typedoc) style
 7) submit a merge request from your forked branch into the
-latest HP4k1h5/ephemeris `v.X.X.X` branch.
+latest HP4k1h5/AQLqueryBuilder `v.X.X.X` branch.
+
+
+### testing
+
+all tests that require a live arango instance are run with root:"" no
+permissions on `localhost:8529`. This can be modified in test files that
+require db access.

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": false,
+  "singleQuote": true,
+}

README.md

@@ -12,43 +12,57 @@ all available Arango Search View capabilities, including, `PHRASE` and
 multi-lingual and language-specific, complex phrase, (proximity... TBD) and tokenized
 search terms.
 
-For example, passing a search phrase like: `+mandatory -exclude ?"optional
-phrase"` to `buildAQL`'s query object as the `term` key, will produce a query
-like the following:
-
-```aql
-FOR doc IN search_view
-  SEARCH
-    MIN_MATCH(
-      ANALYZER(
-        TOKENS(@value0, @value1)
-        ALL IN doc.@value2, @value1),
-    @value3) OR (MIN_MATCH(
-      ANALYZER(
-        TOKENS(@value0, @value1)
-        ALL IN doc.@value2, @value1),
-    @value3) AND (PHRASE(doc.@value2, @value4, @value1)))
-
-     AND  
-
-     MIN_MATCH(
-      ANALYZER(
-        TOKENS(@value5, @value1)
-        NONE IN doc.@value2, @value1),
-    @value3)
-
-    OPTIONS @value6
-      SORT TFIDF(doc) DESC
-
-      LIMIT @value7, @value8
-  RETURN doc
+For example, passing a search phrase like: `some +words -not +"phrase search"
+-"not these" ?"could have"` to `buildAQL`'s query object as the `term` key,
+will produce a query like the following:
+
+```c
+  FOR doc IN view
+
+SEARCH
+  (PHRASE(doc.text, "phrase search", analyzer)) AND MIN_MATCH(
+    ANALYZER(
+      TOKENS("words", analyzer)
+      ALL IN doc.text, analyzer),
+  1) OR ((PHRASE(doc.text, "phrase search", analyzer)) AND MIN_MATCH(
+    ANALYZER(
+      TOKENS("words", analyzer)
+      ALL IN doc.text, analyzer),
+  1) AND (PHRASE(doc.text, "could have", analyzer)) OR MIN_MATCH(
+    ANALYZER(
+      TOKENS(other, analyzer)
+      ANY IN doc.text, analyzer),
+  1))
+  
+   AND  
+   NOT  (PHRASE(doc.text, "not these", analyzer))
+   AND  MIN_MATCH(
+    ANALYZER(
+      TOKENS("nor", analyzer)
+      NONE IN doc.text, analyzer),
+  1)
+  
+  OPTIONS {"collections": ["col"]}
+    SORT TFIDF(doc) DESC
+
+    LIMIT "phrase search"0, "phrase search"1
+  RETURN doc`
 ```
+n.b. the above code block is sytled with c but is .aql compatible.
+
 This query will retrieve all documents that __include__ the term "mandatory"
 AND __do not include__ the term "exclude", AND whose ranking will be boosted by the
 presence of the phrase "optional phrase". If no mandatory or exclude terms are
 provided, optional terms are considered required, so as not to retrieve all
 documents.
 
+See [default query syntax](#default-query-syntax) and this schematic
+[example](#example) for more details.
+
+If multiple collections are passed, the above queried is essentially
+replicated across all collections, see examples in 'tests/cols.ts'. In the
+future this will also accommodate multiple key searches.
+
 ## setup
 
 1) running generated AQL queries will require a working arangodb instance. In
@@ -107,7 +121,7 @@ const queryObject = {
 }
 const aqlQuery = buildAQL(queryObject)
 // ... const cursor = await db.query(aqlQuery)
-// ... const cursor = await db.query(aqlQuery, {start:20, end:40})
+// ... const cursor = await db.query(buildAQL(queryObject, {start:20, end:40})
 ```
 `collections` is an array of `collection` objects. This allows searching and
 filtering across collections impacted by the search.
@@ -159,24 +173,33 @@ Example:
 ```
 
 ### boolean search logic
+
 Quoting [mit's Database Search Tips](https://libguides.mit.edu/c.php?g=175963&p=1158594):
+
 > Boolean operators form the basis of mathematical sets and database logic.
     They connect your search words together to either narrow or broaden your
     set of results.  The three basic boolean operators are: AND, OR, and NOT.
 
 #### `+` AND
+
 * Mandatory terms and phrases. All results MUST INCLUDE these terms and
   phrases.
+
 #### `?` OR
+
 * Optional terms and phrases. If there are ANDS or NOTS, these serve as match
   score "boosters". If there are no ANDS or NOTS, ORS become required in
   results.
+
 #### `-` NOT
+
 * Search results MUST NOT INCLUDE these terms and phrases. If a result that
   would otherwise have matched, contains one or more terms or phrases, it will
-  not be included in the result set.
+  not be included in the result set. If there are no required or optional
+  terms, all results that do NOT match these terms will be returned.
 
 ### default query syntax
+
 for more information on boolean search logic see
   [above](#boolean-search-logic)
 
@@ -190,7 +213,7 @@ by one of the following symbols `+ ? -`, or the plus-sign, the question-mark,
 and the minus-sign. If a word has no operator prefix, it is considered
 optional and is counted as an `OR`.
 
-Example:
+#### Example
 input `one +two -"buckle my shoe"` and the queryParser will interpret as
 follows:
 
@@ -204,7 +227,26 @@ The generated AQL query, when run, will bring back only results that contain
 contain "one". In this case, documents that contain "one" will be likely to
 score higher than those that do not.
 
+When the above phrase `one +two -"buckle my shoe"` is run against the
+following documents:
+
+```boxcar
+┏━━━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━━━┓  ┏━━━━━━━━━━━━━━━━━━┓
+┃ Document A       ┃  ┃  Document B      ┃  ┃ Document C       ┃
+┃ ----------       ┃  ┃                  ┃  ┃                  ┃
+┃                  ┃  ┃ three four       ┃  ┃ one              ┃
+┃  one    two      ┃  ┃                  ┃  ┃                  ┃
+┃                  ┃  ┃ and two          ┃  ┃                  ┃
+┃    buckle my shoe┃  ┃                  ┃  ┃                  ┃
+┗━━━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━━━┛  ┗━━━━━━━━━━━━━━━━━━┛
+```
+
+only Document B is returned;  
+Document A is excluded by the phrase "buckle my shoe"  
+Document C does not contain the mandatory word "two"
+
 ## bugs
 plase see [bugs](https://github.com/HP4k1h5/AQLqueryBuilder.js/issues/new?assignees=HP4k1h5&labels=bug&template=bug_report.md&title=basic)
 ## contributing
 plase see [./.github/CONTRIBUTING.md]
+

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hp4k1h5/aqlquerybuilder.js",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "license": "MIT",
   "main": "./built/index.d.ts",
   "scripts": {

src/index.ts

@@ -4,9 +4,13 @@ import { buildSearch } from './search'
 import { buildFilters } from './filter'
 
 /** @returns an AQL query object. See @param query for details on required
- * values. @parm query .terms accepts either a string to be parsed or an array of @param term
+ * values. @parm query .terms accepts either a string to be parsed or an array
+ * of @param term
  * */
-export function buildAQL(query: query, limit: any = { start: 0, end: 20 }): any {
+export function buildAQL(
+  query: query,
+  limit: any = { start: 0, end: 20 },
+): any {
   validateQuery(query)
 
   const SEARCH = buildSearch(query)
@@ -22,6 +26,8 @@ export function buildAQL(query: query, limit: any = { start: 0, end: 20 }): any
 }
 
 function validateQuery(query: query) {
-  if (!query.view.length) throw Error('query.view must be a valid ArangoSearch View name')
-  if (!query.collections.length) throw new Error('query.collections must have at least one name')
+  if (!query.view.length)
+    throw new Error('query.view must be a valid ArangoSearch View name')
+  if (!query.collections.length)
+    throw new Error('query.collections must have at least one name')
 }

src/parse.ts

@@ -1,4 +1,4 @@
-import {term} from './lib/structs'
+import { term } from './lib/structs'
 
 export function parseQuery(queryString: string): term[] {
   const queryRgx: RegExp = /[+?-]?(["'(]).+?(\1|\))|[^"'()\s]+/g
@@ -9,12 +9,12 @@ export function parseQuery(queryString: string): term[] {
   return matches.map(match => {
     /* strip op */
     let op = '?'
-    if (/[+?-]/.test(match[0])) {
-      op = match[0]
+    if (/[+?-]/.test(match[ 0 ])) {
+      op = match[ 0 ]
       match = match.substring(1)
     }
 
-    if (match[0] == '"' || match[0] == "'") {
+    if (match[ 0 ] == '"' || match[ 0 ] == "'") {
       return {
         type: 'phr',
         val: match,

src/search.ts

@@ -2,12 +2,10 @@ import { aql } from 'arangojs'
 import { query, collection, term } from './lib/structs'
 import { parseQuery } from './parse'
 
-
 export function buildSearch(query: query): any {
   /* parse string query */
-  query.terms = typeof query.terms == 'string'
-    ? parseQuery(query.terms)
-    : query.terms
+  query.terms =
+    typeof query.terms == 'string' ? parseQuery(query.terms) : query.terms
 
   /* build boolean pieces */
   let ANDS = buildOPS(query.collections, query.terms, '+', query.key)
@@ -22,7 +20,9 @@ export function buildSearch(query: query): any {
   if (!!NOTS) {
     NOTS = aql`${ANDS || ORS ? aql.literal(' AND ') : undefined} 
     ${NOTS.phrases ? aql.literal(' NOT ') : undefined} ${NOTS.phrases}
-    ${NOTS.phrases && NOTS.tokens ? aql.literal(' AND ') : undefined} ${NOTS.tokens}`
+    ${NOTS.phrases && NOTS.tokens ? aql.literal(' AND ') : undefined} ${
+      NOTS.tokens
+      }`
   }
 
   /* if an empty query.terms string or array is passed, SEARCH true, bringing
@@ -33,25 +33,24 @@ export function buildSearch(query: query): any {
     ${ORS}
     ${NOTS}
     ${(!ANDS && !ORS && !NOTS) || undefined}
-    OPTIONS ${{ collections: query.collections.map(c => c.name) }}
+    OPTIONS ${{ collections: query.collections.map((c) => c.name) }}
       SORT TFIDF(doc) DESC`
 }
 
-function buildOPS(collections: collection[], terms: term[], op: string, key:
-  string = 'text'): any {
+function buildOPS(
+  collections: collection[],
+  terms: term[],
+  op: string,
+  key: string = 'text',
+): any {
   const opWord: string = op == '+' ? ' AND ' : ' OR '
 
   let queryTerms: any = terms.filter((t: term) => t.op == op)
   if (!queryTerms.length) return
 
   /* phrases */
   let phrases = queryTerms.filter((qT: term) => qT.type == 'phr')
-    .map((phrase: any) => buildPhrase(phrase, collections, key))
-  if (!phrases.length) {
-    phrases = undefined
-  } else {
-    phrases = aql.join(phrases, opWord)
-  }
+  phrases = buildPhrases(phrases, collections, key, opWord)
 
   /* tokens */
   let tokens = queryTerms.filter((qT: { type: string }) => qT.type === 'tok')
@@ -60,17 +59,39 @@ function buildOPS(collections: collection[], terms: term[], op: string, key:
   if (!phrases && !tokens) return
   if (op == '-') return { phrases, tokens }
   if (phrases && tokens) return aql.join([ phrases, tokens ], opWord)
-  return (tokens || phrases)
+  return tokens || phrases
+}
+
+function buildPhrases(
+  phrases: term[],
+  collections: collection[],
+  key: string,
+  opWord: string,
+): any {
+  if (!phrases.length) return undefined
+
+  return aql.join(
+    phrases.map((phrase: any) => buildPhrase(phrase, collections, key)),
+    opWord,
+  )
 }
 
-function buildPhrase(phrase: term, collections: collection[], key: string): any {
-  const phrases = collections.map(coll => {
+function buildPhrase(
+  phrase: term,
+  collections: collection[],
+  key: string,
+): any {
+  const phrases = collections.map((coll) => {
     return aql`PHRASE(doc.${key}, ${phrase.val.slice(1, -1)}, ${coll.analyzer})`
   })
   return aql`(${aql.join(phrases, ' OR ')})`
 }
 
-function buildTokens(tokens: term[], collections: collection[], key: string): any {
+function buildTokens(
+  tokens: term[],
+  collections: collection[],
+  key: string,
+): any {
   if (!tokens.length) return
 
   const opWordMap = {
@@ -85,19 +106,24 @@ function buildTokens(tokens: term[], collections: collection[], key: string): an
     return a
   }, {})
 
-  const makeTokenAnalyzers = (tokens: term[], op: string, analyzer: string,
-    key: string) => {
+  const makeTokenAnalyzers = (
+    tokens: term[],
+    op: string,
+    analyzer: string,
+    key: string,
+  ) => {
     return aql`
       ANALYZER(
         TOKENS(${tokens}, ${analyzer})
         ${aql.literal(op)} IN doc.${key}, ${analyzer})`
   }
 
   let remapped = []
-  collections.forEach(coll => {
+  collections.forEach((coll) => {
     remapped.push(
-      ...Object.keys(mapped).map(op => makeTokenAnalyzers(mapped[ op ], op,
-        coll.analyzer, key))
+      ...Object.keys(mapped).map((op) =>
+        makeTokenAnalyzers(mapped[ op ], op, coll.analyzer, key),
+      ),
     )
   })