lunr-mutable-indexes - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

lunr-mutable.js

@@ -219,2 +219,84 @@ (function() {
 }
+/*
+ * Copyright 2018 Rob Hoelz <rob AT hoelz.ro>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/**
+ * A convenience function for configuring and constructing
+ * a new mutable lunr Index.
+ *
+ * A lunr.MutableBuilder instance is created and the pipeline setup
+ * with a trimmer, stop word filter and stemmer.
+ *
+ * This mutable builder object is yielded to the configuration function
+ * that is passed as a parameter, allowing the list of fields
+ * and other builder parameters to be customised.
+ *
+ * All documents _must_ be added within the passed config function, but
+ * you can always update the index later. ;)
+ *
+ * @example
+ * var idx = lunrMutable(function () {
+ *   this.field('title')
+ *   this.field('body')
+ *   this.ref('id')
+ *
+ *   documents.forEach(function (doc) {
+ *     this.add(doc)
+ *   }, this)
+ * })
+ *
+ * index.add({
+ *     "title": "new title",
+ *     "body": "new body",
+ *     "id": "2"
+ * })
+ *
+ * index.remove({ id: "1" });
+ *
+ * index.update({
+ *   "body": "change",
+ *   "id": "2"
+ * })
+ */
+
+var lunrMutable = function (config) {
+  var builder = new MutableBuilder();
+
+  builder.pipeline.add(
+    lunr.trimmer,
+    lunr.stopWordFilter,
+    lunr.stemmer
+  )
+
+  builder.searchPipeline.add(
+    lunr.stemmer
+  )
+
+  config.call(builder, builder)
+  return builder.build()
+}
+
+lunrMutable.version = "0.2.0"
+
+lunrMutable.Builder = MutableBuilder
+lunrMutable.Index = MutableIndex
   /**
@@ -245,7 +327,4 @@ * export the module via AMD, CommonJS or as a browser global
      */
-    return {
-        MutableBuilder: MutableBuilder,
-        MutableIndex: MutableIndex
-    }
+    return lunrMutable
   }))
 })();

package.json

 {
   "name": "lunr-mutable-indexes",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Mutable indexes for lunr.js 2.1.x",
@@ -29,3 +29,6 @@ "main": "lunr-mutable.js",
     "lunr": "~2.1.5"
+  },
+  "scripts": {
+      "prepare": "make lunr-mutable.js"
   }
 }

README.md

@@ -10,27 +10,13 @@ # Lunr Mutable Indexes - Mutable indexes for lunr.js 2.1.x
 
+A simple search index can be created with the familiar `lunr` syntax; just substitute `lunr-mutable` for `lunr`.
+
 ```js
 
-var lunr = require('lunr');
-var { MutableBuilder, MutableIndex } = require('lunr-mutable');
+var lunrMutable = require('lunr-mutable-indexes');
 
-var builder = new MutableBuilder();
+var index = lunrMutable(function () {
+  this.field('title')
+  this.field('body')
 
-// Add default pipeline and searchPipeline components - sorry,
-// no sugary builder function yet!
-builder.pipeline.add(
-  lunr.trimmer,
-  lunr.stopWordFilter,
-  expandQuery,
-  lunr.stemmer
-);
-
-builder.searchPipeline.add(
-  lunr.stemmer
-);
-
-// Define the fields of documents
-builder.field('title');
-builder.field('body');
-
-builder.add({
+  this.add({
     "title": "Twelfth-Night",
@@ -40,8 +26,9 @@ "body": "If music be the food of love, play on: Give me excess of it…",
     "id": "1"
-});
+  })
+})
+```
 
-// Works just like lunr.js
-var index = builder.build();
+Now, with a mutable index, we can add...
 
-// But now you can add...
+```js
 index.add({
@@ -53,7 +40,13 @@ "title": "Merchant of Venice",
 });
+```
 
-// remove...
+Remove...
+
+```js
 index.remove({ id: "1" });
+```
 
-// or update existing documents.
+Or update existing documents.
+
+```js
 index.update({
@@ -63,8 +56,29 @@ "body": "With mirth and laughter let old wrinkles come.",
 });
+```
 
-// You can also serialize an index:
+Index serialization also works, with the Index namespace accessible through the `lunr-mutable-indexes` object.
+
+```js
+// Serialize an index:
 var serialized = JSON.stringify(index);
 
 // ...and deserialize it later:
-var sameIndex = MutableIndex.load(JSON.parse(serialized));
+var sameIndex = lunrMutable.Index.load(JSON.parse(serialized));
 ```
+
+# Caveats
+
+The main tradeoffs with `lunr-mutable-index` were originally discussed in [this PR](https://github.com/olivernn/lunr.js/pull/315) in `lunr`.
+* Mutable indexes work by having a handle to their original builder - this inflates the index size a bit.
+* Changing a builder's tokenizer won't persist across serialization boundaries.
+* Gaps in builder.termIndex may build up when documents are deleted.
+* The index is completely rebuilt when a document is added/updated/removed
+
+Work is ongoing to make improvements with these potential drawbacks, but please feel free to contribute fixes!
+
+# Thanks
+
+I wrote a simple extension to lunr.js - I would like to thank the following people for helping to make my life easier:
+
+  * Oliver Nightingale (@olivernn) for writing lunr.js in the first place!
+  * John Kupko (@k00p) for making the library easier to use and helping with some of the NPM plumbing!

test/mutable_serialization_test.js

 var lunr = require('lunr');
 var assert = require('chai').assert;
-var { MutableBuilder, MutableIndex } = require('../lunr-mutable.js');
+var lunrMutable = require('../lunr-mutable.js');
 
@@ -24,3 +24,3 @@ suite('mutable serialization', function () {
 
-    var builder = new MutableBuilder
+    var builder = new lunrMutable.Builder
 
@@ -59,3 +59,3 @@ builder.pipeline.add(
     this.serializedIdx = JSON.stringify(this.idx)
-    this.loadedIdx = MutableIndex.load(JSON.parse(this.serializedIdx))
+    this.loadedIdx = lunrMutable.Index.load(JSON.parse(this.serializedIdx))
   })
@@ -62,0 +62,0 @@

test/mutable_test.js

 var lunr = require('lunr');
 var assert = require('chai').assert;
-var { MutableBuilder } = require('../lunr-mutable.js');
+var lunrMutable = require('../lunr-mutable.js');
 
@@ -24,3 +24,3 @@ suite('mutable indexes', function () {
 
-    var builder = new MutableBuilder
+    var builder = new lunrMutable.Builder
 
@@ -27,0 +27,0 @@ builder.pipeline.add(

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

32688

increased by38.81%

Number of package files

14

increased by40%

Lines of code

769

increased by37.81%

Number of lines in readme file

81

increased by20.9%

No dependency changes