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


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 461
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 450
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 1007
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 164

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 176 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
Since Source
3.0.0 DataStore.js, line 234

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
Since Source
3.0.0 DataStore.js, line 245

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
Since Source
3.0.0 DataStore.js, line 257

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
Since Source
3.0.0 DataStore.js, line 278

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 8
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)

Wrapper for Mapper#create. Adds the created to the store.

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

Resolves with the result of the create.

Details
Since Source Overrides
3.0.0 DataStore.js, line 308 Container#create

createMany(name, records, opts)

Wrapper for Mapper#createMany. Adds the created records to the store.

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

Resolves with the result of the create.

Details
Since Source Overrides
3.0.0 DataStore.js, line 325 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 90
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 112
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 542
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)

Wrapper for Mapper#destroy. Removes any destroyed record from the store.

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

Resolves when the delete completes.

Details
Since Source Overrides
3.0.0 DataStore.js, line 655 Container#destroy

destroyAll(name, query, opts)

Wrapper for Mapper#destroyAll. Removes any destroyed records from the store.

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

Resolves when the delete completes.

Details
Since Source Overrides
3.0.0 DataStore.js, line 681 Container#destroyAll

find(name, id, opts)

Wrapper for Mapper#find. Adds any found record to the store.

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

Resolves with the result, if any.

Details
Since Source Overrides
3.0.0 DataStore.js, line 718 Container#find

findAll(name, query, opts)

Wrapper for Mapper#findAll. Adds any found records to the store.

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

Resolves with the result, if any.

Details
Since Source Overrides
3.0.0 DataStore.js, line 756 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 610
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 627
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 644
Inherited From:

getCollection(name)

Return the LinkedCollection with the given name.

Method parameters:
Name Type Description
name String

Name of the LinkedCollection to retrieve.

Throws:

Thrown if the specified LinkedCollection does not exist.

Type
Error
Return value:
Type Description
LinkedCollection Unspecified
Details
Since Source
3.0.0 DataStore.js, line 796

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 655
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
container.getMapper('profile') // throws Error, there is no mapper with name "profile"

getMapperByName(name)

Return the mapper registered under the specified name. Doesn't throw error if mapper doesn't exist.

Method parameters:
Name Type Description
name String

Mapper#name.

Return value:
Type Description
Mapper Unspecified
Details
Since Source
3.0.0 Container.js, line 681
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.getMapperByName('user') // true
container.getMapperByName('profile') // undefined

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 219
Inherited From:

hashQuery(name, query)

Hashing function used to cache DataStore#find and DataStore#findAll requests. This method simply JSONifies the query argument passed to DataStore#find or DataStore#findAll.

Override this method for custom hashing behavior.

Method parameters:
Name Type Description
name String

The name argument passed to DataStore#find or DataStore#findAll.

query Object

The query argument passed to DataStore#find or DataStore#findAll.

Return value:
Type Description
String

The JSONified query.

Details
Since Source
3.0.0 DataStore.js, line 814

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 230
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 252
Inherited From:

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 138 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 })

remove(name, id, opts)

Wrapper for LinkedCollection#remove. Removes the specified Record from the store.

Method parameters:
Name Type Argument Description
name String

The name of the LinkedCollection to target.

id String | Number

The primary key of the Record to remove.

opts Object <optional>

Configuration options.

Properties
Name Type Argument Description
with Array.<String> <optional>

Relations of the Record to also remove from the store.

Return value:
Type Description
Record

The removed Record, if any.

Details
Since Source
3.0.0 DataStore.js, line 838

removeAll(name, query, opts)

Wrapper for LinkedCollection#removeAll. Removes the selected Records from the store.

Method parameters:
Name Type Argument Default Description
name String

The name of the LinkedCollection to target.

query Object <optional>
{}

Selection query. See query.

Properties
Name Type Argument Description
where Object <optional>

See query.where.

offset Number <optional>

See query.offset.

limit Number <optional>

See query.limit.

orderBy String | Array.<Array> <optional>

See query.orderBy.

opts Object <optional>

Configuration options.

Properties
Name Type Argument Description
with Array.<String> <optional>

Relations of the Record to also remove from the store.

Return value:
Type Description
Record

The removed Records, if any.

Details
Since Source
3.0.0 DataStore.js, line 859

removeRelated(name, records, opts)

Remove from the store Records that are related to the provided Record(s).

Method parameters:
Name Type Argument Description
name String

The name of the LinkedCollection to target.

records Record | Array.<Record>

Records whose relations are to be removed.

opts Object <optional>

Configuration options.

Properties
Name Type Argument Description
with Array.<String> <optional>

Relations of the Record(s) to remove from the store.

Details
Since Source
3.0.0 DataStore.js, line 884

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 263
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 288
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)

Wrapper for Mapper#update. Adds the updated Record to the store.

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

Resolves with the result of the update.

Details
Since Source Overrides
3.0.0 DataStore.js, line 942 Container#update

updateAll(name, props, query, opts)

Wrapper for Mapper#updateAll. Adds the updated Records to the store.

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

Resolves with the result of the update.

Details
Since Source Overrides
3.0.0 DataStore.js, line 961 Container#updateAll

updateMany(name, records, opts)

Wrapper for Mapper#updateMany. Adds the updated Records to the store.

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

Resolves with the result of the update.

Details
Since Source Overrides
3.0.0 DataStore.js, line 980 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 401
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' }]