sarge

Register and use custom search indexers to create, update and use search indices.

Install

Install with npm:

$ npm install --save sarge

Usage

var Search = require('sarge');

API

Sarge

Sarge object used to register indexers and execute the collect and index methods on indexers.

Params

• options {Object}: Options to control defaults.
• options.indexer {String}: Set a default indexer to use when one isn't specified in .collect or .index. Defaults to "default".
• options.indexers {Object}: Optionally set an object of indexers when creating the new instance.
• returns {Object}: Instance of Sarge

Example

var sarge = new Sarge();

.indexer

Get or set an indexer by name. This throws an error if only name is passed and the indexer is not found.

Params

• name {String}: Name of indexer to get or set.
• indexer {Object}: Instance of an indexer. See indexers for more information.
• returns {Object}: Sarge instance when setting, indexer instance when getting.

Example

// set
sarge.indexer('foo', foo);
// get
var foo = sarge.indexer('foo');

.collect

Creates a through stream that will execute .collect method on specified indexer for each file passing through the stream. The .collect method passes an object to the callback that will be collected and then indexed when .index is called.

Params

• options {Object}: Options used to specify the indexer to use.
• returns {Stream}: Through stream that's used to collect files to index.

Example

app.src('*.md')
  // use default set on instance or "default" indexer
  .pipe(sarge.collect())
  // or specify a registred indexer to use
  .pipe(sarge.collect({indexer: 'foo'}));

.index

Executes the .index method on the specified indexer passing the collected files and options along with a callback to indicate when indexing is finished.

Params

• options {Object}: Options to specify the indexer to use and to pass into the .index method.
• options.indexer {String}: Indexer to use. Defaults to 'default'
• options.clear {Boolean}: Optionally clear the stored files object. This is useful for incremental indexing in a continuous stream.
• cb {Function}: Callback function passed into the indexer's .index method to specify when indexing is finished.

Example

// use default indexer specified when adding the plugin
sarge.index(function(err) {
  if (err) return console.error(err);
  console.log('indexing finished');
});

// use registered indexer
sarge.index({indexer: 'foo'}, function(err) {
  if (err) return console.error(err);
  console.log('indexing finished');
});

Indexers

Indexers are objects that have collect and index methods that will be executed when collect or index are called on search.

The indexer objects may be plain objects or instances created with those methods. See the examples to see what indexers may look like.

Simple object to be used in examples below.

var indexer = {};

.collect

The collect method on an indexer will be passed a file object and a next callback. The collect method should create an object to pass back to next that will be added to the .files collection on the search instance.

If file is a view from assemble, we can collect information about the file that we want to index:

indexer.collect = function(file, next) {
  var obj = {
    key: file.key,
    title: file.data.title,
    category: file.data.category,
    url: file.data.url,
    body: file.content
  };
  // return the object
  next(null, obj);
};

.index

The index method on an indexer will be passed a files object containing all fo the collected files, an options object which is the same as the options passed into the search.index method, and a callback function to call when indexing is complete. The callback function is the same as the one passed into the search.index method so users may choose to return additional information if necessary.

indexer.index = function(files, options, cb) {
  for (var key in files) {
    if (files.hasOwnProperty(key)) {
      console.log(key);
      console.log(files[key]);
      console.log();
    }
  }
  cb();
};

About

Related projects

• base-search: Base plugin that adds methods for creating, updating and using search indices. | homepage
• search-indexer-algolia: base-search indexer to enable collecting and adding records to an algolia search index | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Building docs

(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

To generate the readme, run the following command:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Brian Woodward

• github/doowb
• twitter/doowb

License

Copyright © 2017, Brian Woodward. Released under the MIT License.

This file was generated by verb-generate-readme, v0.4.3, on April 04, 2017.