🐶 Client API for the Hoodie server
JavaScript

README.md

hoodie-client

Client API for the Hoodie server

Build Status Coverage Status Dependency Status devDependency Status

@hoodie/client 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: 'pat@Example.com',
  password: 'secret'
}).then(function (accountAttributes) {
  hoodie.log.info('Signed up as %s', accountAttributes.username)
}).catch(function (error) {
  hoodie.log.error(error)
})

API

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.ready

Read-only

hoodie.ready

Promise that resolves once the hoodie API is fully initialised.

Things like the the username or session ID are persisted in the local store and have to be loaded before APIs like hoodie.account.id can be used. It’s therefore necessary to wait until the hoodie API is ready before using it

hoodie.ready.then(function () {
  if (hoodie.account.isSignedIn()) {
    alert('Welcome, ' + hoodie.account.username)
  }
})

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
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

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
plugin 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.reset


🐕 TO BE DONE: #12


Reset hoodie client and emit reset event so plugins can reset as well.

hoodie.reset()

Resolves without argument.

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

reset triggered when hoodie.reset() succeeded
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

Contributing

Have a look at the Hoodie project's contribution guidelines. If you want to hang out you can join our Hoodie Community Chat.

License

Apache 2.0