onionoo-node-client/README.md

# onionoo-node-client

> Node.js client library for the Tor Onionoo API

[![Build Status](https://travis-ci.org/lukechilds/onionoo-node-client.svg?branch=master)](https://travis-ci.org/lukechilds/onionoo-node-client) [![Coverage Status](https://coveralls.io/repos/github/lukechilds/onionoo-node-client/badge.svg?branch=master)](https://coveralls.io/github/lukechilds/onionoo-node-client?branch=master)

Promise based client library for the Tor Onionoo API. Includes DB agnostic caching.

## Install

```shell
npm install --save onionoo
```

## Usage

```js
const Onionoo = require('onionoo');
const onionoo = new Onionoo();

// Get top 10 relays
const query = {
  limit: 10,
  running: true,
  order: '-consensus_weight'
};

onionoo.summary(query).then(response => {
    console.log(response.body)
    // {
    //   version:'3.1',
    //   relays_published:'2016-12-23 09:00:00',
    //   relays:[
    //     [Object],
    //     [Object],
    //     [Object],
    //     [Object],
    //     [Object],
    //     [Object],
    //     [Object],
    //     [Object],
    //     [Object],
    //     [Object]
    //   ],
    //   bridges_published:'2016-12-23 07:41:03',
    //   bridges:[]
    // }
});
```

You can override the default options when instantiating a new `Onionoo` instance:

```js
const Onionoo = require('onionoo');
const onionoo = new Onionoo({
  baseUrl: 'https://onionoo.torproject.org',
  endpoints: [
    'summary',
    'details',
    'bandwidth',
    'weights',
    'clients',
    'uptime'
  ],
  cache: {
    store: 'memory',
    max: 500
  }
});
```

## Cache Stores

This module makes use of [`node-cache-manager`](https://github.com/BryanDonovan/node-cache-manager) to support multiple cache stores. By default we store cached responses in memory. You can easily disable the cache or use a more scalable cache store such as Redis by using `node-cache-manager`'s [store engine](https://github.com/BryanDonovan/node-cache-manager#store-engines) modules.

Disable cache:

```js
const Onionoo = require('onionoo');
const onionoo = new Onionoo({
  cache: false
});
```

Use persistent Redis cache:

```js
const Onionoo = require('onionoo');
const redisStore = require('cache-manager-redis');
const onionoo = new Onionoo({
  cache: {
    store: redisStore
  }
});
```

## License

MIT © Luke Childs