hoodie

Introduction

This document describes the functionality of the hoodie base object. It provides a number of helper methods dealing with event handling and connectivity, as well as a unique id generator and a means to set the endpoint which Hoodie communicates with.

Initialisation

The Hoodie Client persists state in the browser, like the current user’s id, session or the connection status to the backend.

hoodie.account.get('session').then(function (session) {
  if (session) {
    // user is signed in
  } else {
    // user is signed out
  }
})

Hoodie integrates Hoodie’s client core modules:

Example

var Hoodie = require('@hoodie/client')
var hoodie = new Hoodie({
  url: 'https://myhoodieapp.com',
  PouchDB: require('pouchdb')
})

hoodie.account.signUp({
  username: '[email protected]',
  password: 'secret'
}).then(function (accountAttributes) {
  hoodie.log.info('Signed up as %s', accountAttributes.username)
}).catch(function (error) {
  hoodie.log.error(error)
})

Constructor

new Hoodie(options)
Argument Type Description Required
options.PouchDB Constructor PouchDB constructor, see also PouchDB custom builds Yes
options.url String Set to hostname where Hoodie server runs, if your app runs on a different host Yes
options.account String account options. options.url is always set to hoodie.url + ‘/account/api’ No
options.store String store options. options.PouchDB is always set to Hoodie Client’s constructor’s options.PouchDB. options.dbName is always set to hoodie.account.id. options.remote is always set to hoodie.url + ‘/store/api’. No
options.task String task options. options.userId is always set to hoodie.account.id. options.remote is always set to hoodie.url + ‘/task/api’ No
options.connectionStatus String connectionStatus options. options.url is always set to hoodie.url + ‘/connection-status/api’. options.method is always set to HEAD No

hoodie.url

Read-only

hoodie.url

full url to the hoodie server, e.g. http://example.com/hoodie

hoodie.account

hoodie.account is an instance of hoodie-account-client. See account API

hoodie.store

hoodie.store is an instance of hoodie-store. See store API

hoodie.connectionStatus

hoodie.connectionStatus is an instance of hoodie-connection-status. See connectionStatus API

hoodie.log

hoodie.log is an instance of hoodie-log. See log API

hoodie.request

Sends an http request

hoodie.request(url)
// or
hoodie.request(options)
Argument Type Description Required
url String Relative path or full URL. A path must start with / and sends a GET request to the path, prefixed by hoodie.url. In case a full URL is passed, a GET request to the url is sent. Yes
options.url String Relative path or full URL. A path must start with / and sends a GET request to the path, prefixed by hoodie.url. In case a full URL is passed, a GET request to the url is sent. Yes
options.method String Defaults to GET. One of GET, HEAD, POST, PUT, DELETE. No
options.data Object, Array, String or Number For PUT and POST requests, an optional payload can be sent. It will be stringified before sending the request. No
options.headers Object Map of Headers to be sent with the request. No

Examples

// sends a GET request to hoodie.url + '/foo/api/bar'
hoodie.request('/foo/api/bar')
// sends a GET request to another host
hoodie.request('https://example.com/foo/bar')
// sends a PATCH request to /foo/api/bar
hoodie.request({
  method: 'PATCH',
  url: '/foo/api/bar',
  headers: {
    'x-my-header': 'my value'
  },
  data: {
    foo: 'bar'
  }
})

hoodie.plugin

Initialise hoodie plugin

hoodie.plugin(methods)
hoodie.plugin(plugin)
Argument Type Description Required
methods Object Method names as keys, functions as values. Methods get directly set on hoodie, e.g. hoodie.plugin({foo: function () {}}) sets hoodie.foo to function () {} Yes
plugins Function The passed function gets called with hoodie as first argument, and can directly set new methods / properties on it. Yes

Examples

hoodie.plugin({
  sayHi: function () { alert('hi') }
})
hoodie.plugin(function (hoodie) {
  hoodie.sayHi = function () { alert('hi') }
})

hoodie.on

Subscribe to event.

hoodie.on(eventName, handler)

Example

hoodie.on('account:signin', function (accountProperties) {
  alert('Hello there, ' + accountProperties.username)
})

hoodie.one

Call function once at given event.

hoodie.one(eventName, handler)

Example

hoodie.one('mycustomevent', function (options) {
  console.log('foo is %s', options.bar)
})
hoodie.trigger('mycustomevent', { foo: 'bar' })
hoodie.trigger('mycustomevent', { foo: 'baz' })
// logs "foo is bar"
// DOES NOT log "foo is baz"

hoodie.off

Removes event handler that has been added before

hoodie.off(eventName, handler)

Example

hoodie.off('connectionstatus:disconnect', showNotification)

hoodie.trigger

Trigger custom events

hoodie.trigger(eventName[, option1, option2, ...])

Example

hoodie.trigger('mycustomevent', { foo: 'bar' })

Events

Event Decription
account:* events, see account events
store:* events, see store events
connectionStatus:* events, see connectionStatus events

Testing

Local setup

git clone https://github.com/hoodiehq/hoodie-client.git
cd hoodie-client
npm install

Run all tests

npm test

Run test from one file only

node tests/specs/id