hoodie-client
Client API for the Hoodie server
@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)
<tr>
<th align="left">Argument</th>
<th align="left">Type</th>
<th align="left">Description</th>
<th align="left">Required</th>
</tr>
<th align="left">options.PouchDB</th>
<td>Constructor</td>
<td>
PouchDB constructor, see also <a href="https://pouchdb.com/custom.html">PouchDB custom builds</a>
</td>
<td>Yes</td>
<th align="left">options.url</th>
<td>String</td>
<td>
Set to hostname where Hoodie server runs, if your app runs on
a different host
</td>
<td>Yes</td>
<th align="left">options.account</th>
<td>String</td>
<td>
<a href="https://github.com/hoodiehq/hoodie-account-client#constructor">account options</a>.
<code>options.url</code> is always set to <code>hoodie.url</code> + '/account/api'
</td>
<td>No</td>
<th align="left">options.store</th>
<td>String</td>
<td>
<a href="https://github.com/hoodiehq/hoodie-store#constructor">store options</a>.
<code>options.PouchDB</code> is always set to <a href="#constructor">Hoodie Client’s constructor</a>’s <code>options.PouchDB</code>.
<code>options.dbName</code> is always set to <code>'store'</code>.
<code>options.remote</code> is always set to <code>hoodie.url + '/store/api/user%2f' + account id</code>.
</td>
<td>No</td>
<th align="left">options.task</th>
<td>String</td>
<td>
<a href="https://github.com/hoodiehq/hoodie-client-task#constructor">task options</a>.
<code>options.userId</code> is always set to <code>account id</code>.
<code>options.remote</code> is always set to <code>hoodie.url</code> + '/task/api'
</td>
<td>No</td>
<th align="left">options.connectionStatus</th>
<td>String</td>
<td>
<a href="https://github.com/hoodiehq/hoodie-connection-status#constructor">connectionStatus options</a>.
<code>options.url</code> is always set to <code>hoodie.url</code> + '/connection-status/api'.
<code>options.method</code> is always set to <code>HEAD</code>
</td>
<td>No</td>
hoodie.url
Read-onlyhoodie.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 APIhoodie.store
hoodie.store
is an instance of
hoodie-store.
See
store APIhoodie.connectionStatus
hoodie.connectionStatus
is an instance of
hoodie-connection-status.
See
connectionStatus APIhoodie.log
hoodie.log
is an instance of
hoodie-log.
See
log APIhoodie.request
Sends an http request
hoodie.request(url)
// or
hoodie.request(options)
<tr>
<th align="left">Argument</th>
<th align="left">Type</th>
<th align="left">Description</th>
<th align="left">Required</th>
</tr>
<th align="left">url</th>
<td>String</td>
<td>
Relative path or full URL. A path must start with <code>/</code> and sends a <code>GET</code>
request to the path, prefixed by <code>hoodie.url</code>. In case a full URL is passed,
a <code>GET</code> request to the url is sent.
</td>
<td>Yes</td>
<th align="left">options.url</th>
<td>String</td>
<td>
Relative path or full URL. A path must start with <code>/</code> and sends a <code>GET</code>
request to the path, prefixed by <code>hoodie.url</code>. In case a full URL is passed,
a <code>GET</code> request to the url is sent.
</td>
<td>Yes</td>
<th align="left">options.method</th>
<td>String</td>
<td>
<em>Defaults to <code>GET</code></em>. One of <code>GET</code>,
<code>HEAD</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>.
</td>
<td>No</td>
<th align="left">options.data</th>
<td>Object, Array, String or Number</td>
<td>
For <code>PUT</code> and <code>POST</code> requests, an optional payload
can be sent. It will be stringified before sending the request.
</td>
<td>No</td>
<th align="left">options.headers</th>
<td>Object</td>
<td>
Map of Headers to be sent with the request.
</td>
<td>No</td>
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)
<tr>
<th align="left">Argument</th>
<th align="left">Type</th>
<th align="left">Description</th>
<th align="left">Required</th>
</tr>
<th align="left">methods</th>
<td>Object</td>
<td>
Method names as keys, functions as values. Methods get directly set on
<code>hoodie</code>, e.g. <code>hoodie.plugin({foo: function () {}})</code>
sets <code>hoodie.foo</code> to <code>function () {}</code>
</td>
<td>Yes</td>
<th align="left">plugin</th>
<td>Function</td>
<td>
The passed function gets called with `hoodie` as first argument, and
can directly set new methods / properties on it.
</td>
<td>Yes</td>
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
<th align="left"><code>account:*</code></th>
<td>events, see <a href="https://github.com/hoodiehq/hoodie-account-client#events">account events</a></td>
<th align="left"><code>store:*</code></th>
<td>events, see <a href="https://github.com/hoodiehq/hoodie-store#events">store events</a></td>
<th align="left"><code>connectionStatus:*</code></th>
<td>events, see <a href="https://github.com/hoodiehq/hoodie-connection-status#events">connectionStatus events</a></td>
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