js-data

Class: Mapper

Mapper

new Mapper(opts)

import {Mapper} from 'js-data'

The core of JSData's ORM/ODM implementation. Given a minimum amout of meta information about a resource, a Mapper can perform generic CRUD operations against that resource. Apart from its configuration, a Mapper is stateless. The particulars of various persistence layers has been abstracted into adapters, which a Mapper uses to perform its operations.

The term "Mapper" comes from the Data Mapper Pattern described in Martin Fowler's Patterns of Enterprise Application Architecture. A Data Mapper moves data between in-memory object instances and a relational or document-based database. JSData's Mapper can work with any persistence layer you can write an adapter for.

("Model" is a heavily overloaded term and is avoided in this documentation to prevent confusion.)

Parameters:
Name Type Argument Description
opts Object <optional>

Configuration options.
Source:

Members

debug :boolean

Whether to enable debug-level logs.

Type:
  • boolean
Default Value:
  • false
Source:

defaultAdapter :string

The name of the registered adapter that this Mapper should used by default.

Type:
  • string
Default Value:
  • "http"
Source:

idAttribute :string

The field used as the unique identifier on records handled by this Mapper.

Type:
  • string
Default Value:
  • id
Source:

name :string

Minimum amount of meta information required to start operating against a resource.

Type:
  • string
Source:

notify :boolean

Whether this Mapper should emit operational events.

Type:
  • boolean
Default Value:
  • true
Source:

raw :boolean

Whether Mapper#create, Mapper#createMany, Mapper#save, Mapper#update, Mapper#updateAll, Mapper#updateMany, Mapper#find, Mapper#findAll, Mapper#destroy, and Mapper#destroyAll should return a raw result object that contains both the instance data returned by the adapter and metadata about the operation.

The default is to NOT return the result object, and instead return just the instance data.

Type:
  • boolean
Default Value:
  • false
Source:

RecordClass

Set the false to force the Mapper to work with POJO objects only.

import {Mapper, Record} from 'js-data'
const UserMapper = new Mapper({ RecordClass: false })
UserMapper.RecordClass // false
const user = UserMapper#createRecord()
user instanceof Record // false

Set to a custom class to have records wrapped in your custom class.

import {Mapper, Record} from 'js-data'
 // Custom class
class User {
  constructor (props = {}) {
    for (var key in props) {
      if (props.hasOwnProperty(key)) {
        this[key] = props[key]
      }
    }
  }
}
const UserMapper = new Mapper({ RecordClass: User })
UserMapper.RecordClass // function User() {}
const user = UserMapper#createRecord()
user instanceof Record // false
user instanceof User // true

Extend the Record class.

import {Mapper, Record} from 'js-data'
 // Custom class
class User extends Record {
  constructor () {
    super(props)
  }
}
const UserMapper = new Mapper({ RecordClass: User })
UserMapper.RecordClass // function User() {}
const user = UserMapper#createRecord()
user instanceof Record // true
user instanceof User // true
Default Value:
Source:

upsert :boolean

Whether Mapper#create and Mapper#createMany should instead call Mapper#update and Mapper#updateMany if the provided record(s) already contain a primary key.

Type:
  • boolean
Default Value:
  • true
Source:

Methods

<static> extend(props, classProps)

Create a Mapper subclass.

var MyMapper = Mapper.extend({
  foo: function () { return 'bar' }
})
var mapper = new MyMapper()
mapper.foo() // "bar"
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.
Source:
Returns:

Subclass of Mapper.

Type
function

afterCreate(data, opts)

Mapper lifecycle hook called by Mapper#create. If this method returns a promise then Mapper#create will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
data Object

The data return by the adapter.
opts Object

The opts argument passed to Mapper#create.
Source:

afterCreateMany(records, opts)

Mapper lifecycle hook called by Mapper#createMany. If this method returns a promise then Mapper#createMany will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
records Array

The records argument passed to Mapper#createMany.
opts Object

The opts argument passed to Mapper#createMany.
Source:

afterDestroy(id, opts)

Mapper lifecycle hook called by Mapper#destroy. If this method returns a promise then Mapper#destroy will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
id string | number

The id argument passed to Mapper#destroy.
opts Object

The opts argument passed to Mapper#destroy.
Source:

afterDestroyAll(data, query, opts)

Mapper lifecycle hook called by Mapper#destroyAll. If this method returns a promise then Mapper#destroyAll will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
data *

The data returned by the adapter.
query query

The query argument passed to Mapper#destroyAll.
opts Object

The opts argument passed to Mapper#destroyAll.
Source:

afterFind(id, opts)

Mapper lifecycle hook called by Mapper#find. If this method returns a promise then Mapper#find will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
id string | number

The id argument passed to Mapper#find.
opts Object

The opts argument passed to Mapper#find.
Source:

afterFindAll(data, query, opts)

Mapper lifecycle hook called by Mapper#findAll. If this method returns a promise then Mapper#findAll will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
data Object

The data returned by the adapter.
query Object

The query argument passed to Mapper#findAll.
opts Object

The opts argument passed to Mapper#findAll.
Source:

afterUpdate(id, props, opts)

Mapper lifecycle hook called by Mapper#update. If this method returns a promise then Mapper#update will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
id string | number

The id argument passed to Mapper#update.
props props

The props argument passed to Mapper#update.
opts Object

The opts argument passed to Mapper#update.
Source:

afterUpdateAll(query, props, opts)

Mapper lifecycle hook called by Mapper#updateAll. If this method returns a promise then Mapper#updateAll will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
query Object

The query argument passed to Mapper#updateAll.
props Object

The props argument passed to Mapper#updateAll.
opts Object

The opts argument passed to Mapper#updateAll.
Source:

afterUpdateMany(records, opts)

Mapper lifecycle hook called by Mapper#updateMany. If this method returns a promise then Mapper#updateMany will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
records Array

The records argument passed to Mapper#updateMany.
opts Object

The opts argument passed to Mapper#updateMany.
Source:

beforeCreate(props, opts)

Mapper lifecycle hook called by Mapper#create. If this method returns a promise then Mapper#create will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
props Object

The props argument passed to Mapper#create.
opts Object

The opts argument passed to Mapper#create.
Source:

beforeCreateMany(records, opts)

Mapper lifecycle hook called by Mapper#createMany. If this method returns a promise then Mapper#createMany will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
records Array

The records argument passed to Mapper#createMany.
opts Object

The opts argument passed to Mapper#createMany.
Source:

beforeDestroy(id, opts)

Mapper lifecycle hook called by Mapper#destroy. If this method returns a promise then Mapper#destroy will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
id string | number

The id argument passed to Mapper#destroy.
opts Object

The opts argument passed to Mapper#destroy.
Source:

beforeDestroyAll(query, opts)

Mapper lifecycle hook called by Mapper#destroyAll. If this method returns a promise then Mapper#destroyAll will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
query query

The query argument passed to Mapper#destroyAll.
opts Object

The opts argument passed to Mapper#destroyAll.
Source:

beforeFind(id, opts)

Mappers lifecycle hook called by Mapper#find. If this method returns a promise then Mapper#find will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
id string | number

The id argument passed to Mapper#find.
opts Object

The opts argument passed to Mapper#find.
Source:

beforeFindAll(query, opts)

Mapper lifecycle hook called by Mapper#findAll. If this method returns a promise then Mapper#findAll will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
query Object

The query argument passed to Mapper#findAll.
opts Object

The opts argument passed to Mapper#findAll.
Source:

beforeUpdate(id, props, opts)

Mapper lifecycle hook called by Mapper#update. If this method returns a promise then Mapper#update will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
id string | number

The id argument passed to Mapper#update.
props props

The props argument passed to Mapper#update.
opts Object

The opts argument passed to Mapper#update.
Source:

beforeUpdateAll(query, props, opts)

Mapper lifecycle hook called by Mapper#updateAll. If this method returns a promise then Mapper#updateAll will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
query Object

The query argument passed to Mapper#updateAll.
props Object

The props argument passed to Mapper#updateAll.
opts Object

The opts argument passed to Mapper#updateAll.
Source:

beforeUpdateMany(records, opts)

Mapper lifecycle hook called by Mapper#updateMany. If this method returns a promise then Mapper#updateMany will wait for the promise to resolve before continuing.

Parameters:
Name Type Description
records Array

The records argument passed to Mapper#updateMany.
opts Object

The opts argument passed to Mapper#updateMany.
Source:

belongsTo()

Usage:

Post.belongsTo(User, { localKey: 'myUserId' })

Comment.belongsTo(User) Comment.belongsTo(Post, { localField: '_post' })

Source:

create(props, opts)

Create and save a new the record using the provided props.

Mapper#beforeCreate will be called before calling the adapter. Mapper#afterCreate will be called after calling the adapter.

Parameters:
Name Type Argument Description
props Object

The properties for the new record.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the created data. If true return a response object that includes the created data and metadata about the operation.
with Array.<string> <optional>
 []

Relations to create in a cascading create if props contains nested relations. NOT performed in a transaction.
Source:
Returns:
Type
Promise

createMany(records, opts)

Given an array of records, batch create them via an adapter.

Mapper#beforeCreateMany will be called before calling the adapter. Mapper#afterCreateMany will be called after calling the adapter.

Parameters:
Name Type Argument Description
records Array

Array of records to be created in one batch.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the updated data. If true return a response object that includes the updated data and metadata about the operation.
with Array.<string> <optional>
 []

Relations to create in a cascading create if the records to be created have linked/nested relations. NOT performed in a transaction.
Source:
Returns:
Type
Promise

createRecord(props, opts)

Create an unsaved, uncached instance of this Mapper's Mapper#RecordClass.

Returns props if props is already an instance of Mapper#RecordClass.

Parameters:
Name Type Argument Description
props Object

The initial properties of the new unsaved record.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
noValidate boolean <optional>
 false

Whether to skip validation on the initial properties.
Source:
Returns:

The unsaved record.

Type
Object

dbg()

Source:

destroy(id, opts)

Using an adapter, destroy the record with the primary key specified by the id argument.

Mapper#beforeDestroy will be called before destroying the record. Mapper#afterDestroy will be called after destroying the record.

Parameters:
Name Type Argument Description
id string | number

The primary key of the record to destroy.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the ejected data (if any). If true return a response object that includes the ejected data (if any) and metadata about the operation.
with Array.<string> <optional>
 []

Relations to destroy in a cascading delete. NOT performed in a transaction.
Source:
Returns:
Type
Promise

destroyAll(query, opts)

Using the query argument, destroy the selected records via an adapter. If no query is provided then all records will be destroyed.

Mapper#beforeDestroyAll will be called before destroying the records. Mapper#afterDestroyAll will be called after destroying the records.

Parameters:
Name Type Argument Default Description
query Object <optional>
 {}

Selection query.

Properties
Name Type Argument Description
where Object <optional>

Filtering criteria.
skip number <optional>

Number to skip.
limit number <optional>

Number to limit to.
orderBy Array <optional>

Sorting criteria.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the ejected data (if any). If true return a response object that includes the ejected data (if any) and metadata about the operation.
with Array.<string> <optional>
 []

Relations to destroy in a cascading delete. NOT performed in a transaction.
Source:
Returns:
Type
Promise

emit(event)

Trigger an event on this Mapper.

Parameters:
Name Type Description
event string

Name of event to emit.
Source:

end()

TODO

Source:

find(id, opts)

Retrieve via an adapter the record with the given primary key.

Mapper#beforeFind will be called before calling the adapter. Mapper#afterFind will be called after calling the adapter.

Parameters:
Name Type Argument Description
id string | number

The primary key of the record to retrieve.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the updated data. If true return a response object that includes the updated data and metadata about the operation.
with Array.<string> <optional>
 []

Relations to eager load in the request.
Source:
Returns:
Type
Promise

findAll(query, opts)

Using the query argument, select records to pull from an adapter. Expects back from the adapter the array of selected records.

Mapper#beforeFindAll will be called before calling the adapter. Mapper#afterFindAll will be called after calling the adapter.

Parameters:
Name Type Argument Default Description
query Object <optional>
 {}

Selection query.

Properties
Name Type Argument Description
where Object <optional>

Filtering criteria.
skip number <optional>

Number to skip.
limit number <optional>

Number to limit to.
orderBy Array <optional>

Sorting criteria.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the resulting data. If true return a response object that includes the resulting data and metadata about the operation.
with Array.<string> <optional>
 []

Relations to eager load in the request.
Source:
Returns:
Type
Promise

getAdapter(name)

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

Parameters:
Name Type Argument Description
name string <optional>

The name of the adapter to retrieve.
Source:
Returns:

The adapter.

Type
Adapter

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.

Parameters:
Name Type Argument Description
opts Object | string <optional>

The name of an adapter or options, if any.
Source:
Returns:

The name of the adapter.

Type
string

getAdapters()

Source:

hasMany()

Usage:

User.hasMany(Post, { localField: 'my_posts' })

Source:

hasOne()

Usage:

User.hasOne(Profile, { localField: '_profile' })

Source:

is(record)

Return whether record is an instance of this Mappers's RecordClass.

Parameters:
Name Type Description
record Object

The record to check.
Source:
Returns:

Whether record is an instance of this Mappers's {@ link Mapper#RecordClass}.

Type
boolean

log()

Source:

off()

Remove an event listener from this Mapper.

Source:

on()

Register a new event listener on this Mapper.

Source:

registerAdapter(name, adapter, opts)

Register an adapter on this mapper under the given name.

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 this Mapper.
Source:

toJSON(record, opts)

Return a plain object representation of the given record.

Parameters:
Name Type Argument Description
record Object

Record from which to create a plain object representation.
opts Object <optional>

Configuration options.

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

Array of relation names or relation fields to include in the representation.
Source:
Returns:

Plain object representation of the record.

Type
Object

update(id, props, opts)

Using an adapter, update the record with the primary key specified by the id argument.

Mapper#beforeUpdate will be called before updating the record. Mapper#afterUpdate will be called after updating the record.

Parameters:
Name Type Argument Description
id string | number

The primary key of the record to update.
props Object

The update to apply to the record.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the updated data. If true return a response object that includes the updated data and metadata about the operation.
with Array.<string> <optional>
 []

Relations to update in a cascading update if props contains nested updates to relations. NOT performed in a transaction.
Source:
Returns:
Type
Promise

updateAll(query, props, opts)

Using the query argument, perform the a single updated to the selected records. Expects back from the adapter an array of the updated records.

Mapper#beforeUpdateAll will be called before making the update. Mapper#afterUpdateAll will be called after making the update.

Parameters:
Name Type Argument Default Description
query Object <optional>
 {}

Selection query.

Properties
Name Type Argument Description
where Object <optional>

Filtering criteria.
skip number <optional>

Number to skip.
limit number <optional>

Number to limit to.
orderBy Array <optional>

Sorting criteria.
props Object

Update to apply to selected records.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the updated data. If true return a response object that includes the updated data and metadata about the operation.
with Array.<string> <optional>
 []

Relations to update in a cascading update if props contains nested updates to relations. NOT performed in a transaction.
Source:
Returns:
Type
Promise

updateMany(records, opts)

Given an array of updates, perform each of the updates via an adapter. Each "update" is a hash of properties with which to update an record. Each update must contain the primary key to be updated.

Mapper#beforeUpdateMany will be called before making the update. Mapper#afterUpdateMany will be called after making the update.

Parameters:
Name Type Argument Description
records Array

Array up record updates.
opts Object <optional>

Configuration options.

Properties
Name Type Argument Default Description
adapter boolean <optional>
 Mapper#defaultAdapter

Name of the adapter to use.
notify boolean <optional>
 Mapper#notify

Whether to emit lifecycle events.
raw boolean <optional>
 Mapper#raw

If false, return the updated data. If true return a response object that includes the updated data and metadata about the operation.
with Array.<string> <optional>
 []

Relations to update in a cascading update if each record update contains nested updates for relations. NOT performed in a transaction.
Source:
Returns:
Type
Promise