C class

Record

A model class for handling data persistence and relationships. Record provides ActiveRecord-like functionality including a rich API for querying, persistence, attribute changes tracking, validations, and associations.

It includes support for:

  • Type coercion through attribute schema definitions
  • Relationship management (hasOne, hasMany, belongsTo, etc.)
  • Change tracking and dirty checking
  • RESTful API integration
  • Event system for lifecycle hooks
  • Single-table inheritance

This is an extension of the original Backbone.Model concept, adding enhanced functionality to work seamlessly with Ruby on Rails backends and modern JavaScript applications.

Constructor

new Record()

Instance Properties

P   bindedObjects: Object.<string, Object>

Object containing references to objects this instance is listening to

P   eventListeners: Object.<string, Array>

Object containing all event listeners

P   listenerId: string

Unique identifier for this event bus instance

Instance Methods

F   addEventListener(name, callback, options) → EventBus

Bind an event to a callback function. Passing "*" will bind the callback to all events fired.

If the options.once is true, the event will only be triggered a single time. After the first time the callback is invoked, its listener will be removed. If multiple events are passed in as an array, the handler will fire once for each event, not once for a combination of all events.

Parameters

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

listener : object optional

The listener object

Returns

EventBus

Returns this for chaining

F   addEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to listen to an event in another object, while keeping track of what it's listening to for easier unbinding later.

Parameters

obj : object | NodeList

The object to listen to events on

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

Returns

EventBus

Returns this for chaining

F   asJSON() → Object

Returns the record's attributes as a JSON-compatible object

Returns

Object

JSON representation of the record

F   association(name) → Object

Gets the association object for a given association name

Parameters

name : string

The name of the association

Returns

Object

The association object

F   attributesForSave(options) → Object

Prepares attributes for saving to the server

Parameters

options : Object optional

Options for saving

Returns

Object

Attributes ready for saving

F   changedAttributes() → Array.<string>

Returns names of all attributes that have changed

Returns

Array.<string>

Array of attribute names that have changed

F   changes() → Object

Returns all changes made to this record since it was last persisted

Returns

Object

Object containing changed attributes with [oldValue, newValue] pairs

F   clone() → Record

Creates a clone of this record

Returns

Record

A new instance with the same attributes and state

F   destroy(options) → Promise

Destroys the record on the server

Parameters

options : DestroyOptions optional

Options for destroying

Returns

Promise

Promise that resolves when the record is destroyed

F   destroyed() → boolean

Checks if this record has been destroyed

Returns

boolean

True if the record has been destroyed

F   dispatchEvent(name, args) → EventBus

Trigger one or many events, firing all bound callbacks. Callbacks are passed the same arguments as dispatchEvent is, apart from the event name (unless you're listening on "*", which will cause your callback to receive the true name of the event as the first argument).

Parameters

name : string | Array.<string>

Event name or array of event names

args : *

Arguments to pass to the event handlers

Returns

EventBus

Returns this for chaining

F   dumpAttributes(attributes) → Object

Converts attributes to their serialized form using type definitions

Parameters

attributes : Object

Attributes to convert

Returns

Object

Converted attributes

F   errorsOn(attribute) → boolean

Checks if there are errors on a specific attribute

Parameters

attribute : string

The attribute to check for errors

Returns

boolean

True if the attribute has errors

F   hasAttribute(attributeName) → boolean

Returns true if the given attribute is in the attributes hash, otherwise false

Parameters

attributeName : string

The name of the attribute to check

Returns

boolean

True if the attribute exists

F   hasChanged(attributeName) → boolean

Checks if the record or a specific attribute has changed

Parameters

attributeName : string optional

Optional attribute name to check

Returns

boolean

True if the record or specified attribute has changed

F   isNewRecord() → boolean

Checks if this record is new (not yet persisted to the database)

Returns

boolean

True if the record is new

F   isPersisted() → boolean

Determines if the record has been persisted to the database

Returns

boolean

True if the record is persisted

F   isSaving() → boolean

Checks if the record is currently being saved

Returns

boolean

True if the record is currently being saved

F   needsSaved() → boolean

Checks if this record needs to be saved

Returns

boolean

True if the record is new, has changes, or has associations that need saving

F   optionsForSync(event, options) → SyncOptions

Prepares options for syncing with the server

Parameters

event : string

The event type (e.g., 'save', 'destroy')

options : SyncOptions optional

Additional options

Returns

SyncOptions

Modified options with success and error handlers

F   paramRoot() → string | undefined

Returns string to use for params names. This is the key attributes from the model will be namespaced under when saving to the server

Returns

string | undefined

The parameter root key name

F   persist() → Record

Marks the record as persisted (not new) and clears change tracking

Returns

Record

This record instance for chaining

F   primaryKey() → *

Gets the primary key value for this record

Returns

*

The primary key value

F   readAttribute(attributeName) → *

Get the value of an attribute

Parameters

attributeName : string

The name of the attribute to read

Returns

*

The attribute value

F   reload(options) → Promise

Reloads the record from the server

Parameters

options : ReloadOptions optional

Options for reloading

Returns

Promise

Promise that resolves with the reloaded record

F   removeEventListener(name, callback, options) → EventBus

Remove one or many callbacks that match the arguments. If called with no arguments, removes all callbacks for all events.

Parameters

name : string | Array.<string> | object | null optional

Event name(s) or object of event/callback pairs

callback : function | object | null optional

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

listener : object optional

Match only events bound by this listener

Returns

EventBus

Returns this for chaining

F   removeEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to stop listening to either specific events or to every object it's currently listening to.

Parameters

obj : object | NodeList optional

The object to stop listening to; if omitted, stops listening to all objects

name : string | Array.<string> | object optional

Event name(s) or object of event/callback pairs

callback : function optional

Callback function to remove

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

Returns

EventBus

Returns this for chaining

F   save(options) → Promise

Saves the record to the server. If a save request has already been made they will be chained.

Parameters

options : SaveOptions optional

Options for saving

Returns

Promise

Promise that resolves when save is complete

F   save$(args) → Promise.<void>

Saves the record and throws an error if it fails

Parameters

args : *

Arguments to pass to save

Returns

Promise.<void>
F   setAttribute(attribute, value) → Record

Sets a single attribute value

Parameters

attribute : string

The attribute name to set

value : *

The value to set

Returns

Record

This record instance for chaining

F   setAttributes(attributes, coerced) → Record

Sets multiple attribute values at once

Parameters

attributes : Object

Object containing attribute name/value pairs to set

coerced : boolean optional

Whether the attributes have already been coerced

Returns

Record

This record instance for chaining

F   setAttributesAndAssociations(attributes, dirty) → Record

Sets both attributes and associations at once

Parameters

attributes : Object

Object containing attributes and associations to set

dirty : boolean optional

Whether to mark associations as dirty

Returns

Record

This record instance for chaining

F   setDefaultAttributes() → Object

Returns an object containing the default values for this record type based on the schema definition

Returns

Object

Default values for this record

F   toParam() → string

Returns a string representing the object's key suitable for use in URLs

Returns

string

The key for use in URLs

F   url() → string

Default URL for the model's representation on the server

Returns

string

The URL for this record

F   urlRoot() → string

Returns the base URL for the model's records on the server

Returns

string

The URL root for this record type

Static Methods

F   all() → Relation

Creates a relation for querying all records of this type

Returns

Relation

A relation for querying all records

F   baseClass() → Class.<Record>

Gets the base class in the inheritance hierarchy for this model

Returns

Class.<Record>

The base class of this model

F   coerceAttributes(attributes, record) → Object

Coerces attribute values according to their type definitions in the schema

Parameters

attributes : Object

The attribute to coerce

record : Record

The record for which the attributes are being applied

Returns

Object

The coerced attributes

F   count(args) → Relation

Creates a relation that counts records matching the criteria

Parameters

args : string

Optional attributes to count by

Returns

Relation

A relation with the count operation

F   create(attributes, options) → Promise.<Record>

Creates and saves a new record with the given attributes

Parameters

attributes : Object

Attributes for the new model

options : SaveOptions optional

Options for saving

Returns

Promise.<Record>

Promise that resolves with the created model

F   create$(attributes, options) → Promise.<Record>

Creates and saves a new record, throwing an error if it fails

Parameters

attributes : Object

Attributes for the new model

options : SaveOptions optional

Options for saving

Returns

Promise.<Record>

Promise that resolves with the created model

F   find(id) → Promise.<Record>

Find a record by its primary key

Parameters

id : *

The primary key to search for

Returns

Promise.<Record>

Promise that resolves with the found record

F   first() → Promise.<Record>

Gets the first record of this model from the database

Returns

Promise.<Record>

Promise that resolves with the first record

F   forEach(callback) → Promise.<Array>

Iterates over all records of this model from the database

Parameters

callback : function

Function to call for each record

Returns

Promise.<Array>

Promise that resolves with the results of the callback

F   getInheritanceAttribute() → string | boolean

Gets the inheritance attribute for this model

Returns

string | boolean

The inheritance attribute or default 'type'

F   groupBy(args) → Relation

Creates a relation for grouping records by specified attributes

Parameters

args : string

The attributes to group by

Returns

Relation

A relation with the specified grouping

F   includes(args) → Relation

Eager-loads specified associations with records of this model

Parameters

args : string

The associations to include

Returns

Relation

A relation with the includes operation

F   initializeAssociations()

Initializes associations for this model type

F   instantiate(attributes) → Record

Instantiate a new instance of the appropriate class.

For example, Post.all() may return Comments, Messages, and Emails by storing the record's subclass in a +type+ attribute. By calling instantiate instead of new, finder methods ensure they get new instances of the appropriate class for each record.

See ActiveRecord::Inheritance#discriminate_class_for_record to see how this "single-table" inheritance mapping is implemented.

Parameters

attributes : Object

The attributes for the new record

Returns

Record

A new record with the given attributes

F   last() → Promise.<Record>

Gets the last record of this model from the database

Returns

Promise.<Record>

Promise that resolves with the last record

F   limit(limit) → Relation

Gets a limited number of records of this model from the database

Parameters

limit : number

The maximum number of records to return

Returns

Relation

A relation with the limit operation

F   limit(limit) → Relation

Gets a limited number of records of this model from the database

Parameters

limit : number

The maximum number of records to return

Returns

Relation

A relation with the limit operation

F   modelName() → Name

Gets the model name object for this model

Returns

Name
F   reflectOnAllAssociations() → Array.<Association>

Gets all reflection objects for this model's associations

Returns

Array.<Association>
F   reflectOnAssociation(name) → Association

Gets the reflection object for a specific association

Parameters

name : string

The name of the association

Returns

F   sum(args) → Relation

Creates a relation that calculates the sum of the specified attribute

Parameters

args : string

The attributes to sum

Returns

Relation

A relation with the sum calculation

F   urlRoot() → string

Returns the defined URL root or generates the URL root based off of the class name

Returns

string
F   where(query) → Relation

Creates a relation for querying records with specific criteria

Parameters

query : Object

The query criteria for filtering records

Returns

Relation

A relation with the specified criteria

Events

E   afterCreate

Fired after a new record has been created

Parameters

savedChanges : Object

The attributes that were saved

options : Object

Options for the save operation

E   afterDestroy

Fired after a record has been successfully destroyed

Parameters

record : Record

The record that was destroyed

options : Object

Options for the destroy operation

E   afterSave

Fired after a record has been successfully saved

Parameters

savedChanges : Object

The attributes that were saved

options : Object

Options for the save operation

E   afterSync

Fired after a record has been synced with the server

Parameters

savedChanges : Object

The changes that were synced

options : Object

Options for the sync operation

E   afterSync:{attribute}

Fired after a specific attribute has been synced with the server

Parameters

oldValue : *

The previous value of the attribute

newValue : *

The new value of the attribute

E   beforeCreate

Fired before a new record is created

Parameters

changes : Object

The attributes that will be saved

options : Object

Options for the save operation

E   beforeDestroy

Fired before a record is destroyed

Parameters

record : Record

The record being destroyed

options : Object

Options for the destroy operation

E   beforeSave

Fired before a record is saved

Parameters

changes : Object

The attributes that will be saved

options : Object

Options for the save operation

E   beforeSync

Fired before a record is synced with the server

Parameters

options : Object

Options for the sync operation

E   changed

Fired when attributes on a record are changed

Parameters

record : Record

The record that was changed

changes : Object

The changes made, with [oldValue, newValue] pairs

E   changed:{attribute}

Fired when a specific attribute on a record is changed

Parameters

record : Record

The record that was changed

oldValue : *

The previous value of the attribute

newValue : *

The new value of the attribute

E   error

Fired when there's a server error

Parameters

response : Object

The error response from the server

E   invalid

Fired when a record has failed to save because it is invalid

Parameters

response : Object

The server response

E   invalid

Fired when a record has failed to save because it is invalid

Parameters

response : Object

The server response