setup workflow and initial code

See README.md for more information

Author: bas080

.eslintrc.json

@@ -0,0 +1,41 @@
+{
+  "env"          : {
+    "es6" : true,
+    "node": true
+  },
+  "extends"      : "eslint:recommended",
+  "parserOptions": {
+    "sourceType": "module"
+  },
+  "globals": {
+    "window": true,
+    "describe": true,
+    "xit": true,
+    "it": true
+  },
+  "rules"        : {
+    "no-var"         : "error",
+    "key-spacing"    : [
+      "error",
+      {
+        "align": "colon"
+      }
+    ],
+    "indent"         : [
+      "error",
+      2
+    ],
+    "linebreak-style": [
+      "error",
+      "unix"
+    ],
+    "quotes"         : [
+      "error",
+      "single"
+    ],
+    "semi"           : [
+      "error",
+      "always"
+    ]
+  }
+}

.gitignore

@@ -0,0 +1,2 @@
+dist
+node_modules

README.md

@@ -0,0 +1,108 @@
+# Lucene Query String Builder
+
+More easily build your lucene string queries small and pure functions.
+
+See the usage section to see how you can leverage this lib for your purposes.
+
+## Use cases
+
+Imagine having an API that leverages lucene for performing queries on the
+(indexed) database. In that case you might want to generate lucene query strings on
+the client/front end.
+
+## Installation
+
+```bash
+bower install lucene-query-builder --save
+
+# or
+
+npm install lucene-query-builder --save
+```
+
+## Usage
+
+Let's see how you can use lucene query string builder to define lucene query
+strings with simple JavaScript functions.
+
+Assuming that the lucene global variable contains the lucene functions. This
+would be the default when loaded into a browser.
+
+```JavaScript
+
+var findUserLuceneQueryString = lucene.builder(function(data){
+
+  // just to make the example more readable;
+  var _ = lucene;
+
+  _.group(_.and(
+    _.field('eye-color', _.term(data.eye.color)),
+    _.field('age', _.range(data.age.min, data.age.max))
+  ));
+
+});
+
+var luceneQueryString = findUserLuceneQueryString({
+  eye: { color: 'brown'},
+  age: {
+    min: 10,
+    max: 20
+  }
+});
+
+luceneQueryString == "( eye-color: "brown" AND age:{ 10 TO 20 } )" // => true
+
+```
+The list of all the functions available are. They are based on the
+specifications which can be found here:
+
+https://lucene.apache.org/core/2_9_4/queryparsersyntax.html#Terms
+
+- terms
+- term
+
+- field
+
+- or
+- and
+- not
+
+- group
+- range;
+
+- fuzzy;
+- proximity
+- required
+
+- builder
+
+## Contributing
+
+- Make sure your dependencies are installed by running: `npm run-script setup`
+
+- Then start editing the index.js
+
+- You should add and/or edit the tests in test/index.js
+
+- Run your tests and see what happens
+
+When performing pull request make sure to not add the **dist** files. This is left
+to the maintainers(s) of the library. They are responsible to version and avoid
+code breakages.
+
+You can perform your own build with npm run-script build to make a lucine.js and
+a lucine.min.js
+
+**notice**
+I am currently not using this repository in any of my projects. Therefore I am looking
+for people that are able to make LQSB more useful for them and others.
+
+## Road map
+
+- split all functions into separate files
+- escaping lucene query syntax characters in the term(s) function
+- tasks for running tests on dist/lucene.js and dist/lucene.min.js
+
+## LICENSE
+
+The MIT License (MIT)

index.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const values     = require('object-values');
+const existy     = require('existy');
+const complement = require('complement');
+
+/**
+ * Lucene Query Builder
+ *
+ * Lucene query syntax docs (specs)
+ * https://lucene.apache.org/core/2_9_4/queryparsersyntax.html#Terms
+ */
+
+const NAMESPACE = 'lucene';
+
+let lucene = {};
+
+lucene.terms = terms;
+lucene.term  = terms; //alias
+
+lucene.field = field;
+
+lucene.or  = surrounded('OR');
+lucene.and = surrounded('AND');
+lucene.not = surrounded('NOT');
+
+lucene.group = surrounder('(', ')');
+lucene.range = range;
+
+lucene.fuzzy     = fuzzy;
+lucene.proximity = proximity;
+lucene.required  = required;
+
+lucene.builder = builder;
+
+if (typeof module.exports === 'undefined')
+  window[NAMESPACE] = lucene;
+else
+  module.exports = lucene;
+
+/**
+ * Used for defining a query builder
+ *
+ * @param {function} fn
+ * @returns {function}
+ *
+ * @example
+ *
+ * userLuceneQuery = lucene.builder((data) => {
+ *   return lucene.field(
+ *     lucene.term('user-name', data.user.name)
+ *   );
+ * });
+ *
+ * userLuceneQuery({user: {name: 'Dolly'}}) // => 'user-name: 'Dolly''
+ */
+function builder(fn) {
+  return (data) => fn(data);
+}
+
+/**
+ * Basicly add double quotes around the string
+ *
+ * @param {string} words
+ *
+ * @returns {string}
+ *
+ * @todo make sure lucene query characters are escaped with a \
+ */
+function terms(words) {
+  return `"${words}"`;
+}
+
+/**
+ * @param {string} field
+ * @param {string} query
+ *
+ * @returns {string} the format is <field>: <term(s)>
+ *
+ * @example
+ * lucene.field('prop-name', lucene.term('value')) // => 'prop-name: "value"'
+ */
+function field(field, query) {
+  return `${field}: ${query}`;
+}
+
+/**
+ * The value is between 0 and 1, with a value closer to 1 only terms with a
+ * higher similarity will be matched.
+ *
+ * Fuzzy search can only be applied to a single term
+ *
+ * @param {string} str
+ * @param {number} [similarity=undefined]
+ *
+ */
+function fuzzy(termStr, similarity) {
+
+  if ((complement(existy)(similarity)))
+    return `${termStr}~`;
+
+  let isValidSimilarity = within(0,1);
+
+  if (!isValidSimilarity(similarity))
+    throw new RangeError('Similarity must be between 0 and 1. It was ' + similarity);
+
+  return `${termStr}~${similarity}`;
+}
+
+/**
+ * Lucene supports finding words are a within a specific distance away.
+ *
+ * @param {string} first
+ * @param {string} second
+ *
+ * @param {number} distance
+ *
+ * @returns {string}
+ */
+function proximity(first, second, distance) {
+  return `"${first} ${second}"~${distance}`;
+}
+
+/**
+ * Range Queries allow one to match documents whose field(s) values are
+ * between the lower and upper bound specified by the Range Query. Range
+ * Queries can be inclusive or exclusive of the upper and lower bounds.
+ *
+ * @param {string}
+ * @param {string}
+ * @param {boolean} [includeLeft=true]
+ * @param {boolean} [includeRight=true]
+ *
+ * @returns {string}
+ */
+function range(from, to, includeLeft, includeRight) {
+  return surrounder(
+    includeLeft  ? '[' : '{',
+    includeRight ? ']' : '}'
+  )(`${from} TO ${to}`);
+}
+
+//banana banana banana
+function required(termStr) {
+  return `+${termStr}`;
+}
+
+/**
+ * Higher order function for building strings that always have the same string
+ * between two other strings
+ *
+ * @param {string} patty
+ *
+ * @returns {string}
+ *
+ * @example
+ * surrounded('OR')('hello', 'world') // -> "hello OR world"
+ */
+function surrounded(middle) {
+  return function(){
+    return values(arguments).join(` ${middle} `);
+  };
+}
+
+/**
+ * Higher order function for building strings that are surrounderd on both
+ * sides of a string
+ *
+ * @param {string} open
+ * @param {string} close
+ *
+ * @returns {function}
+ */
+function surrounder(open, close){
+  return function(){
+    let middle = values(arguments).join(' ');
+    return `${open} ${middle} ${close}`;
+  };
+}
+
+/**
+ * @param {number} left
+ * @param {number} right
+ *
+ * @returns {function}
+ *
+ * @example
+ *
+ * within(0,1)(0.5) // => true
+ *
+ * within(100, 300)(40) // => false
+ */
+function within(left, right) {
+  return function within(value) {
+    return ((value >= left) && (value <= right));
+  };
+}

package.json

@@ -0,0 +1,41 @@
+{
+  "name": "LuceneJS",
+  "version": "0.0.1",
+  "description": "Build Lucene queries by defining lucene query builders",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bas080/lucene-query-string-builder.git"
+  },
+  "scripts": {
+    "setup": "npm install",
+    "lint": "eslint index.js test/spec.js",
+    "test": "mocha -b",
+    "clean": "npm prune && rimraf dist",
+    "build": "npm run lint && npm run test && npm run setup && npm run clean && mkdir -p dist && npm run buildjs",
+    "buildjs": "browserify index.js -o dist/lucene.js -t [ babelify --presets [ es2015 ] ] && npm run minify",
+    "minify": "uglifyjs dist/lucene.js -c -m -o dist/lucene.min.js"
+  },
+  "keywords": [
+    "lucene",
+    "query",
+    "builder"
+  ],
+  "author": "Bas Huis <[email protected]>",
+  "license": "MIT",
+  "devDependencies": {
+    "babel-preset-es2015": "^6.6.0",
+    "babelify": "^7.3.0",
+    "browserify": "^13.0.0",
+    "chai": "~3.5.0",
+    "eslint": "~2.8.0",
+    "mocha": "~2.4.5",
+    "rimraf": "^2.5.2",
+    "uglifyjs": "^2.4.10"
+  },
+  "dependencies": {
+    "complement": "^1.1.0",
+    "existy": "^1.0.1",
+    "object-values": "^1.0.0"
+  }
+}