js-data

Class: DataStore

DataStore

new DataStore(opts)

The DataStore class is an extension of Container. Not only does DataStore manage mappers, but also collections. DataStore implements the asynchronous Mapper methods, such as Mapper#find and Mapper#create. If you use the asynchronous DataStore methods instead of calling them directly on the mappers, then the results of the method calls will be inserted into the store's collections. You can think of a DataStore as an Identity Map for the ORM (the Mappers).

import {DataStore} from 'js-data'
Method parameters:
Name Type Argument Description
opts Object <optional>

Configuration options. See Container.
Return value:
Type Description
DataStore Unspecified
Details
Since Source Tutorials See
3.0.0 DataStore.js, line 887
Example 
import {DataStore} from 'js-data'
import HttpAdapter from 'js-data-http'
const store = new DataStore()

// DataStore#defineMapper returns a direct reference to the newly created
// Mapper.
const UserMapper = store.defineMapper('user')

// DataStore#as returns the store scoped to a particular Mapper.
const UserStore = store.as('user')

// Call "find" on "UserMapper" (Stateless ORM)
UserMapper.find(1).then((user) => {
  // retrieved a "user" record via the http adapter, but that's it

  // Call "find" on "store" targeting "user" (Stateful DataStore)
  return store.find('user', 1) // same as "UserStore.find(1)"
}).then((user) => {
  // not only was a "user" record retrieved, but it was added to the
  // store's "user" collection
  const cachedUser = store.getCollection('user').get(1)
  console.log(user === cachedUser) // true
})

Extends

This class extends the Container class.

Members

_listeners

Event listeners attached to this Component. Do not modify. Use Component#on and Component#off instead.

Details
Type Since Source
Object 3.0.0 Component.js, line 7
Inherited From:

mapperClass

Constructor function to use in Container#defineMapper to create a new mapper.

Mapper

Details
Type Since Source
Constructor 3.0.0 Container.js, line 467
Inherited From:

mapperDefaults

Defaults options to pass to Container#mapperClass when creating a new Mapper.

Details
Type Since Default value Source
Object 3.0.0 
{}
 Container.js, line 456
Inherited From:

Methods

<static> extend(props, classProps)

Create a subclass of this DataStore.

Method parameters:
Name Type Argument Default Description
props Object <optional>
 {}

Properties to add to the prototype of the subclass.
classProps Object <optional>
 {}

Static properties to add to the subclass.
Return value:
Type Description
Constructor

Subclass of this DataStore.
Details
Since Source
3.0.0 DataStore.js, line 939
Examples

Extend the class in a cross-browser manner.

import {DataStore} from 'js-data'
const CustomDataStoreClass = DataStore.extend({
  foo () { return 'bar' }
})
const customDataStore = new CustomDataStoreClass()
console.log(customDataStore.foo()) // "bar"

Extend the class using ES2015 class syntax.

class CustomDataStoreClass extends DataStore {
  foo () { return 'bar' }
}
const customDataStore = new CustomDataStoreClass()
console.log(customDataStore.foo()) // "bar"

addToCache(name, data, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
data *

Data from which data should be selected for add.
opts Object <optional>

Configuration options.
Details
Source
DataStore.js, line 115

as(name)

Return a store scoped to a particular mapper/collection pair.

Method parameters:
Name Type Description
name String

Name of the Mapper.
Return value:
Type Description
Object

A store scoped to a particular mapper/collection pair.
Details
Since Source Overrides
3.0.0 DataStore.js, line 128 Container#as
Example 
import {DataStore} from 'js-data'
const store = new DataStore()
const UserMapper = store.defineMapper('user')
const UserStore = store.as('user')

const user1 = store.createRecord('user', { name: 'John' })
const user2 = UserStore.createRecord({ name: 'John' })
const user3 = UserMapper.createRecord({ name: 'John' })
assert.deepEqual(user1, user2)
assert.deepEqual(user2, user3)
assert.deepEqual(user1, user3)

cachedFind(name, id, opts)

Retrieve a cached find result, if any.

Method parameters:
Name Type Description
name String

The name argument passed to DataStore#find.
id String | Number

The id argument passed to DataStore#find.
opts Object

The opts argument passed to DataStore#find.
Details
Source
DataStore.js, line 186

cachedFindAll(name, hash, opts)

Retrieve a cached findAll result, if any.

Method parameters:
Name Type Description
name String

The name argument passed to DataStore#findAll.
hash String

The result of calling DataStore#hashQuery on the query argument passed to DataStore#findAll.
opts Object

The opts argument passed to DataStore#findAll.
Details
Source
DataStore.js, line 197

cacheFind(name, data, id, opts)

Cache a find result. The default implementation does the following:

// Find and return the record from the data store
return this.get(name, id)

Override this method to customize.

Method parameters:
Name Type Description
name String

The name argument passed to DataStore#find.
data *

The result to cache.
id String | Number

The id argument passed to DataStore#find.
opts Object

The opts argument passed to DataStore#find.
Details
Source
DataStore.js, line 209

cacheFindAll(name, data, hash, opts)

Cache a findAll result. The default implementation does the following:

// Find and return the records from the data store
return this.filter(name, utils.fromJson(hash))

Override this method to customize.

Method parameters:
Name Type Description
name String

The name argument passed to DataStore#findAll.
data *

The result to cache.
hash String

The result of calling DataStore#hashQuery on the query argument passed to DataStore#findAll.
opts Object

The opts argument passed to DataStore#findAll.
Details
Source
DataStore.js, line 230

count(name, query, opts)

Wrapper for Mapper#count.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
query Object <optional>

See Mapper#count.
opts Object <optional>

See Mapper#count.
Return value:
Type Description
Promise

See Mapper#count.
Details
Since Source See
3.0.0 Container.js, line 13
Inherited From:
Example

Get the number of published blog posts

import {Container} from 'js-data'
import RethinkDBAdapter from 'js-data-rethinkdb'
const store = new Container()
store.registerAdapter('rethinkdb', new RethinkDBAdapter(), { default: true })
store.defineMapper('post')

store.count('post', { status: 'published' }).then((numPublished) => {
  console.log(numPublished) // e.g. 45
})

create(name, record, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
record Object

Passed to Mapper#create.
opts Object <optional>

Passed to Mapper#create. See Mapper#create for more configuration options.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 260 Container#create

createMany(name, records, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
records Array

Passed to Mapper#createMany.
opts Object <optional>

Passed to Mapper#createMany. See Mapper#createMany for more configuration options.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 277 Container#createMany

createRecord(name, props, opts)

Wrapper for Mapper#createRecord.

Note: This method does not interact with any adapter, and does not save any data. It only creates new objects in memory.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
props Object | Array.<Object>

See Mapper#createRecord.
opts Object <optional>

See Mapper#createRecord.
Return value:
Type Description
Promise

See Mapper#createRecord.
Details
Since Source See
3.0.0 Container.js, line 95
Inherited From:
Example

Create empty unsaved record instance

import {Container} from 'js-data'
const store = new Container()
store.defineMapper('post')
const post = PostService.createRecord()

dbg(name, args)

Wrapper for Mapper#dbg.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
args * <repeatable>

See Mapper#dbg.
Details
Since Source See
3.0.0 Container.js, line 117
Inherited From:

defineMapper(name, opts)

Create a new mapper and register it in this container.

Method parameters:
Name Type Argument Description
name String

Name under which to register the new Mapper. Mapper#name will be set to this value.
opts Object <optional>

Configuration options. Passed to Container#mapperClass when creating the new Mapper.
Return value:
Type Description
Mapper

The newly created instance of Mapper.
Details
Since Source See
3.0.0 Container.js, line 545
Inherited From:
Example 
import {Container} from 'js-data'
const store = new Container({
  mapperDefaults: { foo: 'bar' }
})
// Container#defineMapper returns a direct reference to the newly created
// Mapper.
const UserMapper = store.defineMapper('user')
UserMapper === store.getMapper('user') // true
UserMapper === store.as('user').getMapper() // true
UserMapper.foo // "bar"

destroy(name, id, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
id String | Number

Passed to Mapper#destroy.
opts Object <optional>

Passed to Mapper#destroy. See Mapper#destroy for more configuration options.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 605 Container#destroy

destroyAll(name, query, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
query Object <optional>

Passed to Mapper#destroyAll.
opts Object <optional>

Passed to Mapper#destroyAll. See Mapper#destroyAll for more configuration options.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 630 Container#destroyAll

emit(event, args)

Trigger an event on this Component.

Method parameters:
Name Type Argument Description
event String

Name of event to emit.
args * <optional>
<repeatable>

Arguments to pass to any listeners.
Details
Since Source
3.0.0 Component.js, line 98
Inherited From:
Examples 
collection.on('foo', (msg) => {
  console.log(msg) // "bar"
})
collection.emit('foo', 'bar')
store.on('foo', (msg, val1, val2) => {
  console.log(msg, val1, val2) // "bar" "beep" "boop"
})
store.emit('foo', 'bar', 'beep', 'boop')

find(name, id, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
id String | Number

Passed to Mapper#find.
opts Object <optional>

Passed to Mapper#find.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 666 Container#find

findAll(name, query, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
query Object <optional>

Passed to Model.findAll.
opts Object <optional>

Passed to Model.findAll.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 704 Container#findAll

getAdapter(name)

Return the registered adapter with the given name or the default adapter if no name is provided.

Method parameters:
Name Type Argument Description
name String <optional>

The name of the adapter to retrieve.
Return value:
Type Description
Adapter

The adapter.
Details
Since Source
3.0.0 Container.js, line 633
Inherited From:

getAdapterName(opts)

Return the name of a registered adapter based on the given name or options, or the name of the default adapter if no name provided.

Method parameters:
Name Type Argument Description
opts Object | String <optional>

The name of an adapter or options, if any.
Return value:
Type Description
String

The name of the adapter.
Details
Since Source
3.0.0 Container.js, line 650
Inherited From:

getAdapters()

Return the registered adapters of this container.

Return value:
Type Description
Adapter Unspecified
Details
Since Source
3.0.0 Container.js, line 667
Inherited From:

getCollection(name)

TODO

Method parameters:
Name Type Description
name String

Name of the LinkedCollection to retrieve.
Return value:
Type Description
LinkedCollection Unspecified
Details
Source
DataStore.js, line 744

getMapper(name)

Return the mapper registered under the specified name.

Method parameters:
Name Type Description
name String

Mapper#name.
Return value:
Type Description
Mapper Unspecified
Details
Since Source
3.0.0 Container.js, line 678
Inherited From:
Example 
import {Container} from 'js-data'
const container = new Container()
// Container#defineMapper returns a direct reference to the newly created
// Mapper.
const UserMapper = container.defineMapper('user')
UserMapper === container.getMapper('user') // true
UserMapper === container.as('user').getMapper() // true

getSchema(name)

Wrapper for Mapper#getSchema.

Method parameters:
Name Type Description
name String

Name of the Mapper to target.
Return value:
Type Description
Schema

See Mapper#getSchema.
Details
Since Source See
3.0.0 Container.js, line 224
Inherited From:

is(name, record)

Wrapper for Mapper#is.

Method parameters:
Name Type Description
name String

Name of the Mapper to target.
record Object | Record

See Mapper#is.
Return value:
Type Description
Boolean

See Mapper#is.
Details
Since Source See
3.0.0 Container.js, line 235
Inherited From:
Example 
import {Container} from 'js-data'
const store = new Container()
store.defineMapper('post')
const post = store.createRecord()

console.log(store.is('post', post)) // true
// Equivalent to what's above
console.log(post instanceof store.getMapper('post').recordClass) // true

log(name, args)

Wrapper for Mapper#log.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
args * <repeatable>

See Mapper#log.
Details
Since Source See
3.0.0 Container.js, line 257
Inherited From:

off(event, listener)

Remove an event listener from this Component. If no listener is provided, then all listeners for the specified event will be removed. If no event is specified then all listeners for all events will be removed.

Method parameters:
Name Type Argument Description
event String <optional>

Name of event to unsubsribe to.
listener Function <optional>

Listener to remove.
Details
Since Source
3.0.0 Component.js, line 79
Inherited From:
Examples

Remove a listener to a single event

collection.off('add', handler)

Remove all listeners to a single event

record.off('change')

Remove all listeners to all events

store.off()

on(event, listener, ctx)

Register a new event listener on this DataStore.

Proxy for Container#on. If an event was emitted by a Mapper or Collection in the DataStore, then the name of the Mapper or Collection will be prepended to the arugments passed to the provided event handler.

Method parameters:
Name Type Argument Description
event String

Name of event to subsribe to.
listener Function

Listener function to handle the event.
ctx * <optional>

Optional content in which to invoke the listener.
Details
Source Overrides
DataStore.js, line 87 Container#on

registerAdapter(name, adapter, opts)

Register an adapter on this container under the given name. Adapters registered on a container are shared by all mappers in the container.

Method parameters:
Name Type Argument Description
name String

The name of the adapter to register.
adapter Adapter

The adapter to register.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
default Boolean <optional>
 false

Whether to make the adapter the default adapter for all Mappers in this container.
Details
Since Source Tutorials
3.0.0 Container.js, line 703
Inherited From:
Example 
import {Container} from 'js-data'
import HttpAdapter from 'js-data-http'
const container = new Container()
container.registerAdapter('http', new HttpAdapter, { default: true })

sum(name, field, query, opts)

Wrapper for Mapper#sum.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
field String

See Mapper#sum.
query Object <optional>

See Mapper#sum.
opts Object <optional>

See Mapper#sum.
Return value:
Type Description
Promise

See Mapper#sum.
Details
Since Source See
3.0.0 Container.js, line 268
Inherited From:
Example 
import {Container} from 'js-data'
import RethinkDBAdapter from 'js-data-rethinkdb'
const store = new Container()
store.registerAdapter('rethinkdb', new RethinkDBAdapter(), { default: true })
store.defineMapper('purchase_order')

store.sum('purchase_order', 'amount', { status: 'paid' }).then((amountPaid) => {
  console.log(amountPaid) // e.g. 451125.34
})

toJSON(name, records, opts)

Wrapper for Mapper#toJSON.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
records Record | Array.<Record>

See Mapper#toJSON.
opts Object <optional>

See Mapper#toJSON.
Return value:
Type Description
Object | Array.<Object>

See Mapper#toJSON.
Details
Since Source See
3.0.0 Container.js, line 293
Inherited From:
Example 
import {Container} from 'js-data'
import RethinkDBAdapter from 'js-data-rethinkdb'
const store = new Container()
store.registerAdapter('rethinkdb', new RethinkDBAdapter(), { default: true })
store.defineMapper('person', {
  schema: {
    properties: {
      name: { type: 'string' },
      id: { type: 'string' }
    }
  }
})
const person = store.createRecord('person', { id: 1, name: 'John', foo: 'bar' })
console.log(store.toJSON('person', person)) // {"id":1,"name":"John","foo":"bar"}
console.log(store.toJSON('person', person), { strict: true }) // {"id":1,"name":"John"}

update(name, id, record, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
id String | Number

Passed to Mapper#update.
record Object

Passed to Mapper#update.
opts Object <optional>

Passed to Mapper#update. See Mapper#update for more configuration options.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 827 Container#update

updateAll(name, props, query, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
props Object

Passed to Mapper#updateAll.
query Object <optional>

Passed to Mapper#updateAll.
opts Object <optional>

Passed to Mapper#updateAll. See Mapper#updateAll for more configuration options.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 845 Container#updateAll

updateMany(name, records, opts)

TODO

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
records Array.<Object> | Array.<Record>

Passed to Mapper#updateMany.
opts Object <optional>

Passed to Mapper#updateMany. See Mapper#updateMany for more configuration options.
Return value:
Type Description
Promise Unspecified
Details
Source Overrides
DataStore.js, line 863 Container#updateMany

validate(name, records, opts)

Wrapper for Mapper#validate.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
records Array.<Object> | Array.<Record>

See Mapper#validate.
opts Object <optional>

See Mapper#validate.
Return value:
Type Description
Promise

See Mapper#validate.
Details
Since Source See
3.0.0 Container.js, line 406
Inherited From:
Example 
import {Container} from 'js-data'
const store = new Container()
store.defineMapper('post', {
  schema: {
    properties: {
      name: { type: 'string' },
      id: { type: 'string' }
    }
  }
})
let errors = store.validate('post', { name: 'John' })
console.log(errors) // undefined
errors = store.validate('post', { name: 123 })
console.log(errors) // [{ expected: 'one of (string)', actual: 'number', path: 'name' }]