OpenSearch JavaScript client

The full documentation is available here.

Setup

To install the client framework perform the following steps:

npm install opensearch-browser

Usage

The easiest way to use the library is by using the discover function, which takes a single parameter, the URL of the OpenSearch service:

import { discover } from 'opensearch-browser';
// or: var discover = require('opensearch-browser').discover;

discover('http://example.com/search').then((service) => {
  service.search({ searchTerms: 'Test', startIndex: 1 }).then((results) => {
    // your results:
  });
});

This OpenSearch library requires Promises. If you are not sure whether you have it available use the following polyfill:

require('es6-promise').polyfill();

Configuration

This library uses a global configuration interface, provided by the config function, which is used for getting and setting configuration values:

import { config } from 'opensearch-browser';

// getting the config
const { useXHR } = config();

// setting the config
config({
  useXHR: true,
});

Currently supported are the following config values:

• useXHR: Whether to use the XMLHttpRequest or the fetch API. The former has the advantage that the requests can be aborted. This is exposed when a Promise type is used that supports cancelling, like the great bluebird library.

Request parameters

Request parameters are supplied as an object whose attribute names shall either be the URL parameter names or their types. For example, if the OpenSearch service provides a URL like the following example:

<Url type="text/html"
  template="http://example.com/search?q={searchTerms}&pw={startPage?}"
/>

then the the following request parameters are possible:

// Using the types
service.search({ searchTerms: 'Test', startPage: 1 }).then( ... );

// Using the parameter names
service.search({ q: 'Test', pw: 1 }).then( ... );

// Omitting the optional parameter 'startPage'
service.search({ searchTerms: 'Test' }).then( ... );

An exception will be raised when mandatory parameters are not supplied.

Some parameter types will be automatically translated from their object to their string representation:

Search Results

By default, the library is able to parse RSS, Atom and GeoJSON responses. They are parsed to a structure based upon the GeoJSON format.

It is possible to extend the supported formats by adding additional format handlers:

import { registerFormat } from 'opensearch/formats/index';

var format = {
  parse: function(response) {
    return response.text().then(function(text) {
      // ...
      return ...;
    });
  }
};

// register the format under the given mime-type
registerFormat('application/vnd.special+xml', format);

When a search URL is used with that mime-type, the response is now parsed with the registered handler.

Alternatively, raw responses can be used, and parsing be performed outside of this library:

var mimeType = null;
var raw = true;
service.search({ searchTerms: 'Test', startIndex: 1 }, mimeType, raw)
  .then(function(response) {
    // do something with the response
  });

For both cases, the response is a Response object from the fetch API.

Suggestions

This library also supports the Suggestions extension of OpenSearch. This is implemented on the Service via the getSuggestions method:

service.getSuggestions({ searchTerms: 'someth' })
  .then(function(suggestions) {
    for (let i = 0; i < suggestions.length; ++i) {
      console.log(
        suggestion.completion,
        suggestion.description,
        suggestion.url
      );
    }
  });

For this to work, the server must have a search url with the type application/x-suggestions+json defined.

Testing

To run the unit tests do

npm test

To run the unit tests continuously, run the following command:

npm run test:watch

Documentation

To generate the API documentation run:

npm run docs

Notes

This library aims to provide a broad support of the most common OpenSearch functionality and exchange formats. It also supports the Geo, Time, EO Products, Parameters, and Suggestions extensions and adheres to various points of the CEOS OpenSearch best practice paper.