Skip to content

hoodiehq/hoodie-store-client

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

190 Commits
.github
.github
 
 
lib
lib
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
.travis.yml
.travis.yml
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
index.js
index.js
 
 
package.json
package.json
 
 
zuul.config.js
zuul.config.js
 
 

Repository files navigation

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:

Name Status Description Why
bad_request 400 Document must be a JSON object properties isn't an object.
Conflict 409 Object with id "id" already exists An object with this _id already exists.
ValidationError - Message you provided in validate The object didn't pass your validate function

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

Note that store.add(arrayOfProperties) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object properties isn't an object.
Conflict 409 Object with id "id" already exists An object with this _id already exists.
ValidationError - Message you provided in validate The object didn't pass your validate function

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:

Name Status Description Why
Not found 404 Object with id "id" is missing There is no object with this _id.

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:

Name Status Description Why
Not found 404 Object with id "id" is missing There is no object with this _id.

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"
}]

Note that store.find(idsOrDocs) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
Not found 404 Object with id "id" is missing There is no object with this _id.

Example

store.find(doc).then(function (doc) {
  alert(doc.id)
}).catch(function (error) {
  alert(error)
})

store.findOrAdd(id, doc)

Argument Type Description Required
id String Unique id of document Yes
doc Object document with _id property Yes

Resolves with the found document or creates a new document and returns it:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z"
  }
}

Rejects with:

Name Status Description Why
missing_id 412 _id is required for puts doc needs to contain at least an _id property.

Example

store.findOrAdd(
  '12345678-1234-1234-1234-123456789ABC',
  { foo: 'bar' }
).then(function (doc) {
  alert(doc)
}).catch(function (error) {
  alert(error)
})

store.findOrAdd(doc)

Argument Type Description Required
doc Object document with _id property Yes

Resolves with the found document or creates a new document and returns it:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z"
  }
}

Rejects with:

Name Status Description Why
missing_id 412 _id is required for puts doc needs to contain at least an _id property.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.findOrAdd({
  _id: '12345678-1234-1234-1234-123456789ABC'
}).then(function (doc) {
  alert(doc)
}).catch(function (error) {
  alert(error)
})

store.findOrAdd(idsOrDocs)

Argument Type Description Required
idsOrDocs Array Array of doc (Object) items Yes

Resolves with an Array containing all found and/or added documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z"
  }
}]

Note that store.findOrAdd(idsOrDocs) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
missing_id 412 _id is required for puts doc needs to contain at least an _id property.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.findOrAdd([
  { _id: '12345678-1234-1234-1234-123456789ABC' }
]).then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.findAll(filter)

Argument Type Description Required
filter Function Return only documents for which this function returns true No

Resolves with an Array containing all found documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z"
  }
}]

Rejects with:

findAll doesn't have expected errors. If nothing is found, then an empty array is resolved.

Example:

store.findAll().then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

Example: with filter function

function filterDocs(doc) {
  return doc.foo === 'bar'
}

store.findAll(filterDocs).then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.update(id, properties)

Argument Type Description Required
id String The id of the document Yes
properties Object Properties which should be changed or added if not existent Yes

Resolves with the updated document:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "updated-bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object properties isn't an object.
Not found 404 Object with id "unknown" is missing There is no object with this _id.
- - Must provide change properties isn't an object or function.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.update(
  '12345678-1234-1234-1234-123456789ABC',
  { foo: 'updated-bar' }
).then(function (doc) {
  alert(doc)
}).catch(function (err) {
  alert(err)
})

store.update(id, updateFunction)

Argument Type Description Required
id String The id of the document Yes
updateFunction Function A function which mutates the document Yes

Resolves with the updated document:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "updated-bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}

Rejects with:

Name Status Description Why
unauthorized 401 Name or password is incorrect. This plugin wasn't unlocked yet.
bad_request 400 Document must be a JSON object updateFunction isn't an object or function.
Not found 404 missing There is no object with this _id.
- - Must provide change updateFunction isn't an object or function.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

function updateFn(doc) {
  return Object.assign(doc, { foo: 'updated-bar' })
}

store.update(
  '12345678-1234-1234-1234-123456789ABC',
  updateFn
).then(function (doc) {
  alert(doc)
}).catch(function (err) {
  alert(err)
})

store.update(doc)

Argument Type Description Required
doc Object document with _id property Yes

Resolves with the updated document:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "updated-bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object doc isn't an object with an _id field.
Not found 404 missing There is no object with this _id.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.update({
  _id: '12345678-1234-1234-1234-123456789ABC',
  foo: 'updated-bar'
}).then(function (doc) {
  alert(doc)
}).catch(function (err) {
  alert(err)
})

store.update(arrayOfDocs)

Argument Type Description Required
arrayOfDocs Array Array of doc (Object) items Yes

Resolves with an Array of updated documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "updated-bar",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}]

Note that store.update(arrayOfDocs) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object This element in the array isn't an object with an _id field.
Not found 404 missing There is no object with this _id.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.update([
  { _id: '12345678-1234-1234-1234-123456789ABC', foo: 'updated-bar' },
  { _id: '87654321-4321-4321-4321-987654321DEF', bar: 'updated-foo' },
]).then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.updateOrAdd(id, properties)

Argument Type Description Required
id String The id of the document Yes
properties Object Properties which should be changed or added if not existent Yes

Resolves with the updated or, if not yet existing, added document:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object properties isn't an object.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.updateOrAdd(
  '12345678-1234-1234-1234-123456789ABC',
  { foo: 'baz' }
).then(function (doc) {
  alert(doc)
}).catch(function (err) {
  alert(err)
})

store.updateOrAdd(doc)

Argument Type Description Required
doc Object document with _id property Yes

Resolves with the updated or, if not yet existing, added document:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object properties isn't an object.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.updateOrAdd({
  _id: '12345678-1234-1234-1234-123456789ABC',
  foo: 'baz'
}).then(function (doc) {
  alert(doc)
}).catch(function (err) {
  alert(err)
})

store.updateOrAdd(arrayOfDocs)

Argument Type Description Required
arrayOfDocs Array Array of doc (Object) items Yes

Resolves with an Array of updated or, if not yet existing, added documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}]

Note that store.updateOrAdd(arrayOfDocs) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object This element in the array isn't an object with an _id field.
ValidationError - Message you provided in validate The object didn't pass your validate function

Example

store.updateOrAdd([
  { _id: '12345678-1234-1234-1234-123456789ABC', foo: 'updated-bar' },
  { _id: '87654321-4321-4321-4321-987654321DEF', bar: 'updated-foo' },
]).then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.updateAll(changedProperties)

Argument Type Description Required
changedProperties Object Properties which should be changed or added if not existent Yes

Resolves with an Array of all updated documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}]

Note that store.updateAll(changedProperties) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
- - Must provide object or function changedProperties isn't an object or a function.
ValidationError - Message you provided in validate The updated object didn't pass your validate function

Example

store.updateAll({ foo: '_baz' }).then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.updateAll(updateFunction)

Argument Type Description Required
updateFunction Function A function which will be called for every document to update Yes

Resolves with an Array of all updated documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}]

Note that store.updateAll(updateFunction) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
- - Must provide object or function updateFunction isn't an object or a function.
ValidationError - Message you provided in validate The updated object didn't pass your validate function

Example

function updateFn(doc) {
  return Object.assign(doc, { foo: '_baz' })
}

store.updateAll(updateFn).then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.remove(id)

Argument Type Description Required
id String The id of the document Yes

Resolves with the deleted document:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z",
    "deletedAt": "2017-07-23T12:00:00.000Z"
  },
  "_deleted": true
}

Rejects with:

Name Status Description Why
Not found 404 Object with id "unknown" is missing There is no object with this _id.
ValidationError - Message you provided in validate The updated object didn't pass your validate function

Example

store.remove('12345678-1234-1234-1234-123456789ABC').then(function (doc) {
  alert(doc)
}).catch(function (err) {
  alert(err)
})

store.remove(doc)

Argument Type Description Required
doc Object A doc (Object) with _id property Yes

Resolves with ``:

{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z",
    "deletedAt": "2017-07-23T12:00:00.000Z"
  },
  "_deleted": true
}

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object doc isn't an object with an _id field.
Not found 404 missing There is no object with this _id.
ValidationError - Message you provided in validate The updated object didn't pass your validate function

Example

store.remove({ _id: '12345678-1234-1234-1234-123456789ABC' }).then(function (doc) {
  alert(doc)
}).catch(function (err) {
  alert(err)
})

store.remove(idsOrDocs)

Argument Type Description Required
idsOrDocs Array Array of id (String) or doc (Object) items Yes

Resolves with an Array of all deleted documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z",
    "deletedAt": "2017-07-23T12:00:00.000Z"
  },
  "_deleted": true
}]

Note that store.remove(idsOrDocs) behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object That element of the array isn't an object with an _id field or a string.
Not found 404 missing There is no object with this _id.
ValidationError - Message you provided in validate The updated object didn't pass your validate function

Example

store.remove([
  '12345678-1234-1234-1234-123456789ABC',
  '87654321-4321-4321-4321-987654321DEF'
]).then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.removeAll()

Resolves with an Array of all deleted documents:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z",
    "deletedAt": "2017-07-23T12:00:00.000Z"
  },
  "_deleted": true
}]

Note that store.removeAll() behaves like the new Promise.allSettled()! It resolves with an Array that contains the resulting object or an error for that object.

Rejects with:

Name Status Description Why
ValidationError - Message you provided in validate The updated object didn't pass your validate function

Example

store.removeAll().then(function (docs) {
  alert(docs)
}).catch(function (err) {
  alert(err)
})

store.pull()

Pulls one or multiple objects from remote to local database. If idOrObjectOrObjects is undefined, then all changes will be pulled.

Argument Type Description Required
idOrObjectOrObjects string or object or array Docs that should be pulled from remote No

Resolves with Array of changed objects in idOrObjectOrObjects or all changed docs:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}]

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object That element of the array isn't an object with an _id field or a string.
unauthorized 401 Name or password is incorrect. You don't have permission to access remote db
not_found 404 Database not found The remote db doesn't exist.

Example

store.pull('critical_data').then(function (docs) {
  if (docs.length === 1) {
    // Doc 'critical_data' did change
  }
}).catch(function (error) {
  // do you have access to the db?
})

store.push()

Pushes one or multiple objects from local to remote database. If idOrObjectOrObjects is undefined, then all changes will be pushed.

Argument Type Description Required
idOrObjectOrObjects string or object or array Docs that should be pulled from remote No

Resolves with Array of pushed docs:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}]

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object That element of the array isn't an object with an _id field or a string.
unauthorized 401 Name or password is incorrect. You don't have permission to access remote db
forbidden 403 Forbidden by design doc validate_doc_update function A validate_doc_update in a design doc on the remote db did reject the update. More about validate_doc_update at the CouchDB docs
not_found 404 Database not found The remote db doesn't exist.

Example

store.push(['booking_23499', { _id: 'foo' }]).then(function (docs) {
  docs.forEach(function (doc) {
    // handle that doc was pushed to remote
  })
}).catch(function (error) {
  // push couldn't be completed
})

store.sync()

Syncs one or multiple objects between local and remote database. If idOrObjectOrObjects is undefined, then all changes will be synced.

Argument Type Description Required
idOrObjectOrObjects string or object or array Docs that should be synced between local and remote database. No

Resolves with Array of synced objects:

[{
  "_id": "12345678-1234-1234-1234-123456789ABC",
  "foo": "baz",
  "hoodie": {
    "createdAt": "2017-08-22T22:00:00.000Z",
    "updatedAt": "2017-07-23T10:00:00.000Z"
  }
}]

Rejects with:

Name Status Description Why
bad_request 400 Document must be a JSON object That element of the array isn't an object with an _id field or a string.
unauthorized 401 Name or password is incorrect. You don't have permission to access remote db
forbidden 403 Forbidden by design doc validate_doc_update function A validate_doc_update in a design doc on the remote db did reject the update. More about validate_doc_update at the CouchDB docs
not_found 404 Database not found The remote db doesn't exist.

Example

store.sync('foo').then(function (docs) {
  // 'foo' is now in sync with remote
}).catch(function (error) {
  // sync did fail.
})

store.connect()

Connects local and remote database and starts an automatic sync process that keeps local and remote database in sync.

Argument Type Description Required

Resolves without a value. But it emits an events.

It doesn't Reject. All errors are events.

Example

store.connect()
  .then(function () {
    // the store now syncs between local and remote.
  })

store.disconnect()

Disconnects local and remote database and stops the automatic sync process. This does not include pull, push and sync.

Argument Type Description Required

Resolves without a value. But it emits an events.

It does not Reject.

Example

store.disconnect()
  .then(function () {
    // the store stopped syncing.
  })

store.isConnected()

Checks if database connection is open and working.

Argument Type Description Required

Returns true / false.

Example

store.connect().then(function () {
  store.isConnected() // true - the local and remote databases are syncing

  return store.disconnect()
}).then(function () {
  store.isConnected() // false - the local and remote databases are not syncing
})

store.isPersistent()

Checks if local database stores objects.

Argument Type Description Required

Returns true / false. true: Data is stored on the users machine. false: Data is not stored on the users machine. If a tab is closed all data is gone and must be pulled from the remote database.

Example

store.isPersistent()

store.reset()

Destroy the local database and creates a new one. All changes that are not synced to remote database will be lost!

Argument Type Description Required

Resolves with no value.

Example

store.remove('important_data')
  .then(function () {
    // destroy local database
    return store.reset()
  })
  .then(function () {
    // re download all data
    return store.pull()
  })

store.on()

Add an event handler, to handel store events.

Argument Type Description Required
event_name string Name of the event that should be listen to. Possible events. Yes
handler function Event handler function. Yes

Returns store API.

Example

store
  .on('change', function (eventName, doc) {
    // handle doc update.
  })
  .on('disconnect', function () {
    // store did disconnect.
  })
  .on('error', function (error) {
    // handle sync error.
  })

store.one()

Add an event handler, to handle one store events. This handler will be removed after one event.

Argument Type Description Required
event_name string Name of the event that should be listen to. Possible events. Yes
handler function Event handler function. Yes

Returns store API.

Example

store.once('reset', function () {
  // store was reset.
})

store.off()

Remove an event handler.

Argument Type Description Required
event_name string Name of the event. One of the possible events. Yes
handler function The event handler function that is listening. Yes

Returns store API.

Example

var changeHandler = function (eventName, doc) {}
store.on('change', changeHandler)

account.once('signout', function () {
  store.off('change', changeHandler)
})

store.withIdPrefix()

Get a subset API with all CRUD methods and events scoped to an id prefix.

Argument Type Description Required
id-prefix string ID-prefix that should implicitly be added to all objects ID. Yes

Returns subset of store API with _id property implicitly prefixed by passed string.

The subset is:

Method Change
add Add the prefix to the id.
find Find only objects that start with prefix.
findOrAdd Find only objects that start with prefix. Or add one with prefix.
findAll Find all objects that start with prefix.
update Only update objects with an id that starts with prefix
updateOrAdd Only update objects with an id that starts with prefix. If none exist it adds one with that prefix.
updateAll Updates all objects which have an id that starts with prefix.
remove Remove an object with an id that starts with prefix
removeAll Remove all objects which have an id that starts with prefix.
on Only allows object events (change, add, update and remove). Event handler is only called for objects which have an id that starts with prefix
one Only allows object events (change, add, update and remove). Event handler is only called for objects which have an id that starts with prefix
off Can only remove an event handler that was added to this instance of store subset.
withIdPrefix It extends the prefix.

Example

var prefixed = store.withIdPrefix('foo:')

prefixed.add({ _id: 'bar', value: 42 }) // will add the object with id 'foo:bar'
  .then(function (doc) {
    // update documents with id 'foo:other' and 'foo:bar'
    return prefixed.update(['other', 'foo:bar'], { other: 'baz' })
  })

// Finds all objects which id start with 'foo:'
prefixed.findAll().then(function (docs) {})

// Handle all changes to objects which id start with 'foo:'
prefixed.on('change', function (eventName, doc) {})

var moarPrefixed = prefixed.withIdPrefix('moarPrefix:') // prefix is now 'foo:moarPrefix:'

Events

Event Description Arguments
add An object was added (this can be local or remote database) object that was added
update An object was updated (this can be local or remote database) object that was updated
remove An object was removed (this can be local or remote database) object that was removed
change An object was changed on local or remote database. A change an be an object was added, updated or removed. event-name (add, update or remove), object that was changed
push Objects where pushed to remote. sync also emits this event. pushed-objects; An Array with all objects pushed to remote.
pull Objects where pulled from remote. sync also emits this event. pulled-objects; An Array with all objects pulled from remote.
connect Local database was connected to remote database. No arguments
disconnect Local database was disconnect from remote database. No arguments
reset The local database was reset. No 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

About

🐶 Hoodie Client for data persistence & offline sync

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

39 stars

Watchers

41 watching

Forks

16 forks
Report repository

Releases 36

v8.3.0 Latest
Nov 26, 2017
+ 35 releases

Packages

No packages published

Contributors 17

+ 3 contributors

Languages