js-data

Class: Container

Container

new Container(opts)

import {Container} from 'js-data'

The Container class is a place to store Mapper instances.

Without a container, you need to manage mappers yourself, including resolving circular dependencies among relations. All mappers in a container share the same adapters, so you don't have to add each adapter to all of your mappers.

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

Configuration options.

Properties
Name Type Argument Description
mapperClass Function <optional>

Constructor function to use in Container#defineMapper to create a new mapper.
mapperDefaults Object <optional>

Defaults options to pass to Container#mapperClass when creating a new mapper.
Return value:
Type Description
Container Unspecified
Details
Since Source Tutorials
3.0.0 Container.js, line 741
Examples

Without Container

import {Mapper} from 'js-data'
import HttpAdapter from 'js-data-http'
const adapter = new HttpAdapter()
const userMapper = new Mapper({ name: 'user' })
userMapper.registerAdapter('http', adapter, { default: true })
const commentMapper = new Mapper({ name: 'comment' })
commentMapper.registerAdapter('http', adapter, { default: true })

// This might be more difficult if the mappers were defined in different
// modules.
userMapper.hasMany(commentMapper, {
  localField: 'comments',
  foreignKey: 'userId'
})
commentMapper.belongsTo(userMapper, {
  localField: 'user',
  foreignKey: 'userId'
})

With Container

import {Container} from 'js-data'
import HttpAdapter from 'js-data-http'
const container = new Container()
// All mappers in container share adapters
container.registerAdapter('http', new HttpAdapter(), { default: true })

// These could be defined in separate modules without a problem.
container.defineMapper('user', {
  relations: {
    hasMany: {
      comment: {
        localField: 'comments',
        foreignKey: 'userId'
      }
    }
  }
})
container.defineMapper('comment', {
  relations: {
    belongsTo: {
      user: {
        localField: 'user',
        foreignKey: 'userId'
      }
    }
  }
})

Extends

This class extends the Component 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

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

Methods

<static> extend(props, classProps)

Create a subclass of this Container.

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 Container.
Details
Since Source
3.0.0 Container.js, line 816
Examples

Extend the class in a cross-browser manner.

import {Container} from 'js-data'
const CustomContainerClass = Container.extend({
  foo () { return 'bar' }
})
const customContainer = new CustomContainerClass()
console.log(customContainer.foo()) // "bar"

Extend the class using ES2015 class syntax.

class CustomContainerClass extends Container {
  foo () { return 'bar' }
}
const customContainer = new CustomContainerClass()
console.log(customContainer.foo()) // "bar"

as(name)

Return a container scoped to a particular mapper.

Method parameters:
Name Type Description
name String

Name of the Mapper.
Return value:
Type Description
Object

A container scoped to a particular mapper.
Details
Since Source
3.0.0 Container.js, line 507
Example 
import {Container} from 'js-data'
const store = new Container()
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)

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
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, props, opts)

Wrapper for Mapper#create.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
props Object

See Mapper#create.
opts Object <optional>

See Mapper#create.
Return value:
Type Description
Promise

See Mapper#create.
Details
Since Source See
3.0.0 Container.js, line 37
Example

Create and save a new blog post

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.create('post', {
  title: 'Modeling your data',
  status: 'draft'
}).then((post) => {
  console.log(post) // { id: 1234, status: 'draft', ... }
})

createMany(name, records, opts)

Wrapper for Mapper#createMany.

Method parameters:
Name Type Argument Description
name String

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

See Mapper#createMany.
opts Object <optional>

See Mapper#createMany.
Return value:
Type Description
Promise

See Mapper#createMany.
Details
Since Source See
3.0.0 Container.js, line 64
Example

Create and save several new 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.createMany('post', [{
  title: 'Modeling your data',
  status: 'draft'
}, {
  title: 'Reading data',
  status: 'draft'
}]).then((posts) => {
  console.log(posts[0]) // { id: 1234, status: 'draft', ... }
  console.log(posts[1]) // { id: 1235, status: 'draft', ... }
})

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
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 Overrides See
3.0.0 Container.js, line 117 Component#dbg

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

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
id String | Number

See Mapper#destroy.
opts Object <optional>

See Mapper#destroy.
Return value:
Type Description
Promise

See Mapper#destroy.
Details
Since Source See
3.0.0 Container.js, line 128
Example

Destroy a specific blog post

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.destroy('post', 1234).then(() => {
  // Blog post #1234 has been destroyed
})

destroyAll(name, query, opts)

Wrapper for Mapper#destroyAll.

Method parameters:
Name Type Argument Description
name String

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

See Mapper#destroyAll.
opts Object <optional>

See Mapper#destroyAll.
Return value:
Type Description
Promise

See Mapper#destroyAll.
Details
Since Source See
3.0.0 Container.js, line 152
Example

Destroy all "draft" 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.destroyAll('post', { status: 'draft' }).then(() => {
  // All "draft" blog posts have been destroyed
})

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)

Wrapper for Mapper#find.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
id String | Number

See Mapper#find.
opts Object <optional>

See Mapper#find.
Return value:
Type Description
Promise

See Mapper#find.
Details
Since Source See
3.0.0 Container.js, line 176
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('post')

store.find('post', 1).then((post) => {
  console.log(post) // { id: 1, ...}
})

findAll(name, query, opts)

Wrapper for Mapper#createRecord.

Method parameters:
Name Type Argument Description
name String

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

See Mapper#findAll.
opts Object <optional>

See Mapper#findAll.
Return value:
Type Description
Promise

See Mapper#findAll.
Details
Since Source See
3.0.0 Container.js, line 200
Example

Find all "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.findAll('post', { status: 'published' }).then((posts) => {
  console.log(posts) // [{ id: 1, ...}, ...]
})

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

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

getAdapters()

Return the registered adapters of this container.

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

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

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
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 Overrides See
3.0.0 Container.js, line 257 Component#log

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

Proxy for Component#on. If an event was emitted by a Mapper in the Container, then the name of the Mapper will be prepended to the arugments passed to the listener.

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
Since Source Overrides
3.0.0 Container.js, line 479 Component#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
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
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
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.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
id String | Number

See Mapper#update.
record Object

See Mapper#update.
opts Object <optional>

See Mapper#update.
Return value:
Type Description
Promise

See Mapper#update.
Details
Since Source Tutorials See
3.0.0 Container.js, line 323
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('post')

store.update('post', 1234, {
  status: 'published',
  published_at: new Date()
}).then((post) => {
  console.log(post) // { id: 1234, status: 'published', ... }
})

updateAll(name, update, query, opts)

Wrapper for Mapper#updateAll.

Method parameters:
Name Type Argument Description
name String

Name of the Mapper to target.
update Object

See Mapper#updateAll.
query Object <optional>

See Mapper#updateAll.
opts Object <optional>

See Mapper#updateAll.
Return value:
Type Description
Promise

See Mapper#updateAll.
Details
Since Source See
3.0.0 Container.js, line 352
Example

Turn all of John's blog posts into drafts.

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

const update = { status: draft: published_at: null }
const query = { userId: 1234 }
store.updateAll('post', update, query).then((posts) => {
  console.log(posts) // [...]
})

updateMany(name, records, opts)

Wrapper for Mapper#updateMany.

Method parameters:
Name Type Argument Description
name String

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

See Mapper#updateMany.
opts Object <optional>

See Mapper#updateMany.
Return value:
Type Description
Promise

See Mapper#updateMany.
Details
Since Source See
3.0.0 Container.js, line 379
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('post')

store.updateMany('post', [
  { id: 1234, status: 'draft' },
  { id: 2468, status: 'published', published_at: new Date() }
]).then((posts) => {
  console.log(posts) // [...]
})

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