js-data

Class: Record

Record

new Record(props, opts)

js-data's Record class. An instance of Record corresponds to an in-memory representation of a single row or document in a database, Firebase, localstorage, etc. Basically, a Record instance represents whatever kind of entity in your persistence layer that has a primary key.

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

The initial properties of the new Record instance.
opts Object <optional>

Configuration options.

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

Whether to skip validation on the initial properties.
Details
Since Source
3.0.0 Record.js, line 17
Examples 

// Normally you would do: import {Record} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Record} = JSData
console.log('Using JSData v' + JSData.version.full)

// Instantiate a plain record
let record = new Record()
console.log('record: ' + JSON.stringify(record))

// You can supply properties on instantiation
record = new Record({ name: 'John' })
console.log('record: ' + JSON.stringify(record))

// Normally you would do: import {Mapper} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Mapper} = JSData
console.log('Using JSData v' + JSData.version.full)

// Instantiate a record that's associated with a Mapper:
const UserMapper = new Mapper({ name: 'user' })
const User = UserMapper.recordClass
const user = UserMapper.createRecord({ name: 'John' })
const user2 = new User({ name: 'Sally' })
console.log('user: ' + JSON.stringify(user))
console.log('user2: ' + JSON.stringify(user2))

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)

const store = new Container()
store.defineMapper('user')

// Instantiate a record that's associated with a store's Mapper
const user = store.createRecord('user', { name: 'John' })
console.log('user: ' + JSON.stringify(user))

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)

const store = new Container()
store.defineMapper('user', {
  schema: {
    properties: {
      name: { type: 'string' }
    }
  }
})

// Validate on instantiation
const user = store.createRecord('user', { name: 1234 })
console.log('user: ' + JSON.stringify(user))

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)

const store = new Container()
store.defineMapper('user', {
  schema: {
    properties: {
      name: { type: 'string' }
    }
  }
})

// Skip validation on instantiation
const user = store.createRecord('user', { name: 1234 }, { noValidate: true })
console.log('user: ' + JSON.stringify(user))
console.log('user.isValid(): ' + user.isValid())

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

debug

Whether to enable debug-level logs for this component. Anything that extends Component inherits this option and the corresponding logging functionality.

Details
Type Since Default value Source
Boolean 3.0.0 
false
 Component.js, line 28
Inherited From:
Example 

// Normally you would do: import {Component} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Component} = JSData
console.log('Using JSData v' + JSData.version.full)

const component = new Component()
component.log('debug', 'some message') // nothing gets logged
// Display debug logs:
component.debug = true
component.log('debug', 'other message') // this DOES get logged

Methods

<static> extend(props, classProps)

Create a subclass of this Record:

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

Properties to add to the prototype of the subclass.

Properties
Name Type Argument Description
constructor Object <optional>

Provide a custom constructor function to be used as the subclass itself.
classProps Object <optional>
 {}

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

Subclass of this Record class.
Details
Since Source
3.0.0 Record.js, line 800
Example 

// Normally you would do: import {Record} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Record} = JSData
console.log('Using JSData v' + JSData.version.full)

// Extend the class using ES2015 class syntax.
class CustomRecordClass extends Record {
  foo () { return 'bar' }
  static beep () { return 'boop' }
}
const customRecord = new CustomRecordClass()
console.log(customRecord.foo())
console.log(CustomRecordClass.beep())

// Extend the class using alternate method.
const OtherRecordClass = Record.extend({
  foo () { return 'bar' }
}, {
  beep () { return 'boop' }
})
const otherRecord = new OtherRecordClass()
console.log(otherRecord.foo())
console.log(OtherRecordClass.beep())

// Extend the class, providing a custom constructor.
function AnotherRecordClass () {
  Record.call(this)
  this.created_at = new Date().getTime()
}
Record.extend({
  constructor: AnotherRecordClass,
  foo () { return 'bar' }
}, {
  beep () { return 'boop' }
})
const anotherRecord = new AnotherRecordClass()
console.log(anotherRecord.created_at)
console.log(anotherRecord.foo())
console.log(AnotherRecordClass.beep())

_mapper()

Returns the Mapper paired with this record's class, if any.

Return value:
Type Description
Mapper

The Mapper paired with this record's class, if any.
Details
Since Source
3.0.0 Record.js, line 135

afterLoadRelations(relations, opts)

Lifecycle hook.

Method parameters:
Name Type Description
relations Array.<String>

The relations argument passed to Record#loadRelations.
opts Object

The opts argument passed to Record#loadRelations.
Details
Since Source
3.0.0 Record.js, line 150

beforeLoadRelations(relations, opts)

Lifecycle hook.

Method parameters:
Name Type Description
relations Array.<String>

The relations argument passed to Record#loadRelations.
opts Object

The opts argument passed to Record#loadRelations.
Details
Since Source
3.0.0 Record.js, line 160

changes(opts)

Return changes to this record since it was instantiated or Record#commit was called.

Method parameters:
Name Type Argument Description
opts <optional>

Configuration options.

Properties
Name Type Argument Default Description
equalsFn Function <optional>
 utils.deepEqual

Equality function.
ignore Array <optional>
 []

Array of strings or RegExp of fields to ignore.
Return value:
Type Description
Object

Object describing the changes to this record since it was instantiated or its Record#commit method was last called.
Details
Since Source
3.0.0 Record.js, line 170
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)

const store = new Container()
store.defineMapper('user')
const user = store.createRecord('user')
console.log('user changes: ' + JSON.stringify(user.changes()))
user.name = 'John'
console.log('user changes: ' + JSON.stringify(user.changes()))

commit()

Make the record's current in-memory state it's only state, with any previous property values being set to current values.

Details
Since Source
3.0.0 Record.js, line 200
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)

const store = new Container()
store.defineMapper('user')
const user = store.createRecord('user')
console.log('user hasChanges: ' + user.hasChanges())
user.name = 'John'
console.log('user hasChanges: ' + user.hasChanges())
user.commit()
console.log('user hasChanges: ' + user.hasChanges())

dbg(args)

Log the provided values at the "debug" level. Debug-level logs are only logged if Component#debug is true.

.dbg(...) is shorthand for .log('debug', ...).

Method parameters:
Name Type Argument Description
args * <optional>
<repeatable>

Values to log.
Details
Since Source
3.0.0 Component.js, line 123
Inherited From:

destroy(opts)

Call Mapper#destroy using this record's primary key.

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

Configuration options passed to Mapper#destroy.
Return value:
Type Description
Promise

The result of calling Mapper#destroy with the primary key of this record.
Details
Since Source
3.0.0 Record.js, line 227
Example 
import {Container} from 'js-data'
import {RethinkDBAdapter} from 'js-data-rethinkdb'

const store = new Container()
store.registerAdapter('rethink', new RethinkDBAdapter(), { default: true })
store.defineMapper('user')
store.find('user', 1234).then((user) => {
  console.log(user.id) // 1234

  // Destroy this user from the database
  return user.destroy()
})

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 201
Inherited From:
Example 

// import {Collection, DataStore} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Collection, DataStore} = JSData

const collection = new Collection()
collection.on('foo', (msg) => {
  console.log(msg)
})
collection.emit('foo', 'bar')

const store = new DataStore()
store.on('beep', (msg) => {
  console.log(msg)
})
store.emit('beep', 'boop')

get(key)

Return the value at the given path for this instance.

Method parameters:
Name Type Description
key String

Path of value to retrieve.
Return value:
Type Description
*

Value at path.
Details
Since Source
3.0.0 Record.js, line 256
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user')

const user = store.createRecord('user', { name: 'Bob' })
console.log('user.get("name"): ' + user.get('name'))

hasChanges(opts)

Return whether this record has changed since it was instantiated or Record#commit was called.

Method parameters:
Name Type Argument Description
opts <optional>

Configuration options.

Properties
Name Type Argument Default Description
equalsFn Function <optional>
 utils.deepEqual

Equality function.
ignore Array <optional>
 []

Array of strings or RegExp of fields to ignore.
Return value:
Type Description
Boolean

Return whether the record has changed since it was instantiated or since its Record#commit method was called.
Details
Since Source
3.0.0 Record.js, line 279
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user')
const user = store.createRecord('user')
console.log('user hasChanges: ' + user.hasChanges())
user.name = 'John'
console.log('user hasChanges: ' + user.hasChanges())
user.commit()
console.log('user hasChanges: ' + user.hasChanges())

isValid(opts)

Return whether the record in its current state passes validation.

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

Configuration options. Passed to Mapper#validate.
Return value:
Type Description
Boolean

Whether the record in its current state passes validation.
Details
Since Source
3.0.0 Record.js, line 310
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user', {
  schema: {
    properties: {
      name: { type: 'string' }
    }
  }
})
const user = store.createRecord('user', {
  name: 1234
}, {
  noValidate: true // this allows us to put the record into an invalid state
})
console.log('user isValid: ' + user.isValid())
user.name = 'John'
console.log('user isValid: ' + user.isValid())

loadRelations(relations, opts)

Lazy load relations of this record, to be attached to the record once their loaded.

Method parameters:
Name Type Argument Description
relations Array.<String> <optional>

List of relations to load. Can use localField names or Mapper names to pick relations.
opts Object <optional>

Configuration options.
Return value:
Type Description
Promise

Resolves with the record, with the loaded relations now attached.
Details
Since Source
3.0.0 Record.js, line 345
Example 
import {Container} from 'js-data'
import {RethinkDBAdapter} from 'js-data-rethinkdb'

const store = new Container()
store.registerAdapter('rethink', new RethinkDBAdapter(), { default: true })
store.defineMapper('user', {
  relations: {
    hasMany: {
      post: {
        localField: 'posts',
        foreignKey: 'user_id'
      }
    }
  }
})
store.defineMapper('post', {
  relations: {
    belongsTo: {
      user: {
        localField: 'user',
        foreignKey: 'user_id'
      }
    }
  }
})
store.find('user', 1234).then((user) => {
  console.log(user.id) // 1234

  // Load the user's post relations
  return user.loadRelations(['post'])
}).then((user) => {
  console.log(user.posts) // [{...}, {...}, ...]
})

log(level, args)

Log the provided values. By default sends values to console[level]. Debug-level logs are only logged if Component#debug is true.

Will attempt to use appropriate console methods if they are available.

Method parameters:
Name Type Argument Description
level String

Log level.
args * <optional>
<repeatable>

Values to log.
Details
Since Source
3.0.0 Component.js, line 133
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 179
Inherited From:
Examples 
// Remove a particular listener for a particular event
collection.off('add', handler)
// Remove all listeners for a particular event
record.off('change')
// Remove all listeners to all events
store.off()

on(event, listener, ctx)

Register a new event listener on this Component.

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
3.0.0 Component.js, line 146
Inherited From:
Examples 
// Listen for all "afterCreate" events in a DataStore
store.on('afterCreate', (mapperName, props, opts, result) => {
  console.log(mapperName) // "post"
  console.log(props.id) // undefined
  console.log(result.id) // 1234
})
store.create('post', { title: 'Modeling your data' }).then((post) => {
  console.log(post.id) // 1234
})
// Listen for the "add" event on a collection
collection.on('add', (records) => {
  console.log(records) // [...]
})
// Listen for "change" events on a record
post.on('change', (record, changes) => {
  console.log(changes) // { changed: { title: 'Modeling your data' } }
})
post.title = 'Modeling your data'

previous(key)

Return the properties with which this record was instantiated.

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

If specified, return just the initial value of the given key.
Return value:
Type Description
Object

The initial properties of this record.
Details
Since Source
3.0.0 Record.js, line 469
Example 

// import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user')
const user = store.createRecord('user', {
  name: 'William'
})
console.log('user previous: ' + JSON.stringify(user.previous()))
user.name = 'Bob'
console.log('user previous: ' + JSON.stringify(user.previous()))
user.commit()
console.log('user previous: ' + JSON.stringify(user.previous()))

revert(opts)

Revert changes to this record back to the properties it had when it was instantiated.

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

Configuration options.

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

Array of strings or Regular Expressions denoting properties that should not be reverted.
Details
Since Source
3.0.0 Record.js, line 501
Example 

// import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user')
const user = store.createRecord('user', {
  name: 'William'
})
console.log('user: ' + JSON.stringify(user))
user.name = 'Bob'
console.log('user: ' + JSON.stringify(user))
user.revert()
console.log('user: ' + JSON.stringify(user))

save(opts)

Delegates to Mapper#create or Mapper#update.

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

Configuration options. See Mapper#create and Mapper#update.

Properties
Name Type Argument Description
changesOnly Boolean <optional>

Equality function. Default uses ===.
equalsFn Function <optional>

Passed to Record#changes when opts.changesOnly is true.
ignore Array <optional>

Passed to Record#changes when opts.changesOnly is true.
Return value:
Type Description
Promise

The result of calling Mapper#create or Mapper#update.
Details
Since Source
3.0.0 Record.js, line 544
Example 
import {Container} from 'js-data'
import {RethinkDBAdapter} from 'js-data-rethinkdb'

const store = new Container()
store.registerAdapter('rethink', new RethinkDBAdapter(), { default: true })
store.defineMapper('session')
const session = store.createRecord('session', { topic: 'Node.js' })

// Create a new record in the database
session.save().then(() => {
  console.log(session.id) // 1234

  session.skill_level = 'beginner'

  // Update the record in the database
  return user.save()
})

set(key, value, opts)

Set the value for a given key, or the values for the given keys if "key" is an object. Triggers change events on those properties that have track: true in Mapper#schema.

Method parameters:
Name Type Argument Description
key String | Object

Key to set or hash of key-value pairs to set.
value * <optional>

Value to set for the given key.
opts Object <optional>

Configuration options.

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

Whether to trigger change events.
Fires:
Details
Since Source
3.0.0 Record.js, line 602
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user')

const user = store.createRecord('user')
console.log('user: ' + JSON.stringify(user))

user.set('name', 'Bob')
console.log('user: ' + JSON.stringify(user))

user.set({ age: 30, role: 'admin' })
console.log('user: ' + JSON.stringify(user))

toJSON(opts)

Return a plain object representation of this record. If the class from which this record was created has a Mapper, then Mapper#toJSON will be called with this record instead.

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

Configuration options.

Properties
Name Type Argument Description
strict Boolean <optional>

Whether to exclude properties that are not defined in Mapper#schema.
with Array.<String> <optional>

Array of relation names or relation fields to include in the representation. Only available as an option if the class from which this record was created has a Mapper and this record resides in an instance of DataStore.
Return value:
Type Description
Object

Plain object representation of this record.
Details
Since Source
3.0.0 Record.js, line 646
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user', {
  schema: {
    properties: {
      name: { type: 'string' }
    }
  }
})

const user = store.createRecord('user', {
  name: 'John',
  $$hashKey: '1234'
})
console.log('user: ' + JSON.stringify(user.toJSON()))
console.log('user: ' + JSON.stringify(user.toJSON({ strict: true })))

unset(key, opts)

Unset the value for a given key. Triggers change events on those properties that have track: true in Mapper#schema.

Method parameters:
Name Type Argument Description
key String

Key to unset.
opts Object <optional>

Configuration options.

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

Whether to trigger change events.
Details
Since Source
3.0.0 Record.js, line 696
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user')

const user = store.createRecord('user', {
  name: 'John'
})
console.log('user: ' + JSON.stringify(user))

user.unset('name')
console.log('user: ' + JSON.stringify(user))

validate(opts)

Validate this record based on its current properties.

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

Configuration options. Passed to Mapper#validate.
Return value:
Type Description
*

Array of errors or undefined if no errors.
Details
Since Source
3.0.0 Record.js, line 726
Example 

// Normally you would do: import {Container} from 'js-data'
const JSData = require('js-data@3.0.0-beta.7')
const {Container} = JSData
console.log('Using JSData v' + JSData.version.full)
const store = new Container()
store.defineMapper('user', {
  schema: {
    properties: {
      name: { type: 'string' }
    }
  }
})
const user = store.createRecord('user', {
  name: 1234
}, {
  noValidate: true // this allows us to put the record into an invalid state
})
console.log('user validation: ' + JSON.stringify(user.validate()))
user.name = 'John'
console.log('user validation: ' + user.validate())

Type Definitions

changeListener(The, The)

Callback signature for the Record#event:change event.

Method parameters:
Name Type Description
The Record

Record that changed.
The Object

changes.
Details
Type Since Source See
Function 3.0.0 Record.js, line 784
Example 
function onChange (mapperName, record, changes) {
  // do something
}
store.on('change', onChange)

Events

change

Fired when a record changes. Only works for records that have tracked fields. See Record~changeListener on how to listen for this event.

Details
Source See
Record.js, line 776