base-search

base-search

Base plugin that adds methods for creating, updating and using search indexes.

Install

Install with npm:

$ npm install --save base-search

Usage

var search = require('base-search');

API

.search

Plugin for base applications like generate, assemble, verb, and update to add methods for creating search indexices using indexers.

Params

• config {Object}: Configuration object used to specify default indexer to use.
• returns {Function}: Plugin function passed to app.use methods.

Example

var app = assemble();
app.use(search());

Search

Search 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".

Example

// plugin adds `.search` property to `app` which is an instance of `Search`
app.use(search())
console.log(app.search);

.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}: Search instance when setting, indexer instance when getting.

Example

// set
app.search.indexer('foo', foo);
// get
var foo = app.search.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(app.search.collect())
  // or specify a registred indexer to use
  .pipe(app.search.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.
• 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
app.search.index(function(err) {
  if (err) return console.error(err);
  console.log('indexing finished');
});

// use registered indexer
app.search.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 app.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

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 document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && 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.1, on January 30, 2017.