@hoodie/store-client

Hoodie Client for data persistence & offline sync

Usage no npm install needed!

<script type="module">
  import hoodieStoreClient from 'https://cdn.skypack.dev/@hoodie/store-client';
</script>

README

hoodie-store-client

Hoodie Client for data persistence & offline sync

Build Status Coverage Status Dependency Status devDependency Status

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

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