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.

License

Apache 2.0