README
hoodie-store-client
Hoodie Client for data persistence & offline sync
Example
var Store = require('@hoodie/store-client')
var store = new Store('mydbname', {
PouchDB: require('pouchdb'),
remote: 'http://localhost:5984/mydbname'
})
// or
var PresetStore = Store.defaults({
PouchDB: require('pouchdb'),
remoteBaseUrl: 'http://localhost:5984'
})
var store = new PresetStore('mydb')
API
- Store.defaults
- Constructor
- store.add(properties)
- store.add(arrayOfProperties)
- store.find(id)
- store.find(doc)
- store.find(idsOrDocs)
- store.findOrAdd(id, doc)
- store.findOrAdd(doc)
- store.findOrAdd(idsOrDocs)
- store.findAll()
- store.update(id, changedProperties)
- store.update(id, updateFunction)
- store.update(doc)
- store.update(arrayOfDocs)
- store.updateOrAdd(id, doc)
- store.updateOrAdd(doc)
- store.updateOrAdd(arrayOfDocs)
- store.updateAll(changedProperties)
- store.updateAll(updateFunction)
- store.remove(id)
- store.remove(doc)
- store.remove(idsOrDocs)
- store.removeAll()
- store.pull()
- store.push()
- store.sync()
- store.connect()
- store.disconnect()
- store.isConnected()
- store.on()
- store.one()
- store.off()
- store.withIdPrefix
- Events
Store.defaults
Store.defaults(options)
Argument | Type | Description | Required |
---|---|---|---|
options.remoteBaseUrl |
String | Base url to CouchDB. Will be used as remote prefix for store instances | No |
options.PouchDB |
Constructor | PouchDB custom builds | Yes |
Returns a custom Store Constructor with passed default options.
Example
var PresetStore = Store.defaults({
remoteBaseUrl: 'http://localhost:5984'
})
var store = new PresetStore('mydb')
store.sync() // will sync with http://localhost:5984/mydb
Constructor
new Store(dbName, options)
Argument | Type | Description | Required |
---|---|---|---|
dbName |
String | name of the database | Yes |
options.remote |
String | name or URL of remote database | Yes (unless remoteBaseUrl is preset, see Store.defaults) |
options.remote |
Object | PouchDB instance | Yes (ignores remoteBaseUrl from Store.defaults) |
options.remote |
Promise | Resolves to either string or PouchDB instance | see above |
options.PouchDB |
Constructor | PouchDB custom builds | Yes (unless preset using Store.defaults)) |
options.validate |
Function(doc) | Validation function to execute before DB operations (Can return promise for async validation) | No |
Returns store
API.
Example
var store = new Store('mydb', {
PouchDB: PouchDB,
remote: 'http://localhost:5984/mydb'
})
store.sync() // will sync with http://localhost:5984/mydb
Example with dynamic remote URL and ajax headers
var loadAccount = require('./load-account')
var store = new Store('mydb', {
PouchDB: PouchDB,
get remote () {
return loadAccount.then(function (account) {
return new PouchDB('http://localhost:5984/' + encodeURIComponent('user/' + account.id), {
ajax: {
headers: {
authorization: 'session ' + account.session.id
}
}
})
})
}
})
store.sync() // will sync with http://localhost:5984/mydb
store.add(properties)
store.add(properties)
Argument | Type | Description | Required |
---|---|---|---|
properties |
Object | properties of document | Yes |
properties.id |
String | If set, the document will be stored at given id | No |
Resolves with properties
and adds id
(unless provided), createdAt
and
updatedAt
properties.
{
"id": "12345678-1234-1234-1234-123456789ABC",
"foo": "bar",
"createdAt": "2016-05-09T12:00:00.000Z",
"updatedAt": "2016-05-09T12:00:00.000Z"
}
Rejects with:
🐕 Add expected Errors: #102
Name | Description |
---|---|
Error | ... |
Example
store.add({foo: 'bar'}).then(function (doc) {
alert(doc.foo) // bar
}).catch(function (error) {
alert(error)
})
store.add(arrayOfProperties)
Argument | Type | Description | Required |
---|---|---|---|
arrayOfProperties |
Array | Array of properties , see store.add(properties) |
Yes |
Resolves with properties
and adds id
(unless provided), createdAt
and
updatedAt
properties. Resolves with array of properties
items if called
with propertiesArray
.
{
"id": "12345678-1234-1234-1234-123456789ABC",
"foo": "bar",
"createdAt": "2016-05-09T12:00:00.000Z",
"updatedAt": "2016-05-09T12:00:00.000Z"
}
Rejects with:
🐕 Add expected Errors: #102
Name | Description |
---|---|
Error | ... |
Example: add single document
store.add({foo: 'bar'}).then(function (doc) {
alert(doc.foo) // bar
}).catch(function (error) {
alert(error)
})
Example: add multiple documents
store.add([{foo: 'bar'}, {bar: 'baz'}]).then(function (docs) {
alert(docs.length) // 2
}).catch(function (error) {
alert(error)
})
store.find(id)
Argument | Type | Description | Required |
---|---|---|---|
id |
String | Unique id of document | Yes |
Resolves with properties
{
"id": "12345678-1234-1234-1234-123456789ABC",
"foo": "bar",
"createdAt": "2016-05-09T12:00:00.000Z",
"updatedAt": "2016-05-09T12:00:00.000Z"
}
Rejects with:
🐕 Add expected Errors: #102
Name | Description |
---|---|
Error | ... |
Example
store.find('12345678-1234-1234-1234-123456789ABC').then(function (doc) {
alert(doc.id)
}).catch(function (error) {
alert(error)
})
store.find(doc)
Argument | Type | Description | Required |
---|---|---|---|
doc |
Object | document with id property |
Yes |
Resolves with properties
{
"id": "12345678-1234-1234-1234-123456789ABC",
"foo": "bar",
"createdAt": "2016-05-09T12:00:00.000Z",
"updatedAt": "2016-05-09T12:00:00.000Z"
}
Rejects with:
🐕 Add expected Errors: #102
Name | Description |
---|---|
Error | ... |
Example
store.find(doc).then(function (doc) {
alert(doc.id)
}).catch(function (error) {
alert(error)
})
store.find(idsOrDocs)
Argument | Type | Description | Required |
---|---|---|---|
idsOrDocs |
Array | Array of id (String) or doc (Object) items |
Yes |
Resolves with array of properties
[{
"id": "12345678-1234-1234-1234-123456789ABC",
"foo": "bar",
"createdAt": "2016-05-09T12:00:00.000Z",
"updatedAt": "2016-05-09T12:00:00.000Z"
}]
Rejects with:
🐕 Add expected Errors: #102
Name | Description |
---|---|
Error | ... |
Example
store.find(doc).then(function (doc) {
alert(doc.id)
}).catch(function (error) {
alert(error)
})
store.findOrAdd(id, doc)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.findOrAdd(doc)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.findOrAdd(idsOrDocs)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.findAll()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.update(id, changedProperties)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.update(id, updateFunction)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.update(doc)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.update(arrayOfDocs)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.updateOrAdd(id, doc)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.updateOrAdd(doc)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.updateOrAdd(arrayOfDocs)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.updateAll(changedProperties)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.updateAll(updateFunction)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.remove(id)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.remove(doc)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.remove(idsOrDocs)
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.removeAll()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.pull()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.push()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.sync()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.connect()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.disconnect()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Resolves with ``:
{
}
Rejects with:
Name | Description |
---|---|
Error | ... |
Example
store.isConnected()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Returns true
/ false
Example
store.on()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Returns store
API.
Example
store.one()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Returns store
API.
Example
store.off()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Returns store
API.
Example
store.withIdPrefix()
🐕 Complete README: #102
Argument | Type | Description | Required |
---|
Returns subset of store
API with _id
property implicitly prefixed by passed string
Example
Events
🐕 Complete README: #102
Event | Description | Arguments |
---|
Testing
Local setup
git clone https://github.com/hoodiehq/hoodie-store-client.git
cd hoodie-store-client
npm install
In Node.js
Run all tests and validate JavaScript Code Style using standard
npm test
To run only the tests
npm run test:node
Run tests in browser
npm run test:browser:local
This will start a local server. All tests and coverage will be run at http://localhost:8080/__zuul
Contributing
Have a look at the Hoodie project's contribution guidelines. If you want to hang out you can join #hoodie-pouch on our Hoodie Community Slack.