Node.js v1.x.x migration guide

You can now use the algoliasearch-client-js in all JavaScript environments, using the same unified API.

The new API is not backward compatible with the previous Node.js client, we made a few changes.

If you have any issue, please contact our team at support@algolia.com.

Table of contents

1. Migrate your code
2. Installation
3. Initialization
4. Callback convention
5. New function signatures
6. Default timeout
7. New features

• Node.js 0.10, 0.12 & iojs compatibility
• Isomorphic module
• Promises
• Automatic keepalive
• Proxy support

1. Can I still use V1?

Migrate your code

Installation

The JavaScript client can be installed with:

npm install algoliasearch --save

The previous Node.js-only package algolia-search is deprecated.

Initialization

Before

new AlgoliaSearch(applicationID, apiKey/*, httpsAgent, hostsArray*/);

After

algoliasearch(applicationID, apiKey/*, opts*/);

Calling algoliasearch(..) without an applicationID or apiKey will now throw an Error.

Most of the time, you do not need to pass any opts to get a client.

Hosts are computed automatically and every client is already using keepalive connections.

httpsAgent and hostsArray were removed.

See the list of available client opts.

Callback convention

Before

index.search(query, function(error, content) {
  // error `true` or `false`
  // content is either the results or an error message
}, params);

After

index.search(query, params, function(err, content) {
  // err `null` or `Error` object (with a `message` property)
  // content contains the results if no error
});

All asynchronous methods are now using these two conventions:

• callback is always the last parameter
• callback is called with cb(err, content) to comply to the popular asynchronous JavaScript convention

You can also use promises.

Changed function signatures

Due to the change in the callback convention, we modified these functions:

• index.search

  • Before: index.search(query, callback[, params, ClassToDerive])
  • After, any of the following:
    • index.search(query[, cb])
    • index.search(query[, params, cb])
    • index.search(params[, cb]) where params.query is filled
    • We removed the ClassToDerive, if you need to instantiate a class on every hit, please do it on your side.
    • index.search is an important function, we made it so it can be used in multiple ways

• client.getLogs

  • Before: client.getLogs(cb[, offset, length])
  • After: client.getLogs([offset, length, cb])

• client.listIndexes

  • Before: client.listIndexes(cb[, page])
  • After: client.listIndexes([page, cb])

• Managing keys:

  • We removed client|index.addUserKeyWithValidityAndIndexes(), client|index.updateUserKeyWithValidity(), client|index.updateUserKeyWithValidityAndIndexes()
  • You can now use client|index.addUserKey(acls[, params, callback]) and client|index.updateUserKey(key, acls[, params, callback]). Where params: {validity: val, maxQueriesPerIPPerHour: val, maxHitsPerQuery:val, indexes: val}

• client.multipleQueries was renamed and reworked to client.search, usage:

    client.search([{
      indexName: 'some-index',
      query: 'hello world',
      params: {
        // query parameters
        hitsPerPage: 200
      }
    }, {
      indexName: 'some-other-index',
      query: 'HI!',
      params: {
        // query parameters
        hitsPerPage: 10
      }
    }], callback)

  • query can also be given as params.query

• index.addObject

  • Before: index.addObject(content[, callback, objectID])
  • After: index.addObject(content[, objectID, callback])

• index.getObject

  • Before: index.getObject(objectID[, callback, attributes, ClassToDerive])
  • After: index.getObject(objectID[, attributes, callback])
  • We removed the ClassToDerive option. Same reason as for search.

• index.browse

  • Before: index.browse(page, cb[, hitsPerPage])
  • After: index.browse(page[, hitsPerPage, cb])

• index.searchDisjunctiveFaceting() was removed, you can now use the algoliasearch-helper-js

Default timeout

The default timeout is now 15s (30s in V1).

It is an inactivity timeout which means that as long as there are some bytes transferring from you to our servers every 15s you are good.

If you are still experimenting timeouts, makes sure your are not overloading your connection with too much requests.

New features

Isomorphic module

This new JavaScript module is now usable on the browser and on the server with the same API.

Promises

The JavaScript client now supports both promises and callbacks for asynchronous calls.

var algoliasearch = require('algoliasearch');
var client = algoliasearch('applicationID', 'apiKey');
var index = client.initIndex('indexName');

index.search('something')
  .then(function success(content) {
    console.log('Success', content);
  })
  .catch(function failure(err) {
    console.log('Failure', err);
  });

The promise implementation is the native Promise from the environment or jakearchibald/es6-promise for other unsupported environments the Promise object.

When using the parse.com build, you get Parse promises.

callback AND promise?

No.

If you pass a callback, you won't get a promise. If no callback passed, you get a promise.

Node.js 0.10, 0.12, iojs compatibility

We are now compatible with major Node.js versions (0.10, 0.12) and iojs.

Our code is automatically tested on all of them.

Automatic keepalive

In V1, it was up to the user to activate keepalive (by giving an http Agent), it is now activated by default.

The Node.js client now automatically use keepalived connections to our servers.

We also provide a client.destroy() method to terminate all connections. This is useful when you are finished working with the AlogliaSearch client and want your program to exit properly.

Proxy support

In V1, proxy support was left to the user. It is now supported by default.

If you are behind a proxy, just set HTTP_PROXY or HTTPS_PROXY environment variables before starting your Node.js program.

HTTP_PROXY=http://someproxy.com:9320 node main.js

You can also use a specific Node.js httpAgent by providing it when initializing your client:

var client = algoliasearch(applicationId, apiKey, {
  httpAgent: yourOwnHttpAgent
});

Can I still use V1?

Yes. If you are using the V1 of our Node.js client and do not want to upgrade then you can stick to V1.

We have a V1 branch where we will publish critical updates.