C class

Model

An in-memory data object with typed, change-tracked attributes.

Model provides the attribute layer shared by all data objects: schema-driven getters/setters, type coercion, default values, and dirty-state tracking. It is suitable for memory-level objects that are never queried or persisted.

{@link Record} extends Model to add querying, persistence, and associations.

It includes support for:

Type coercion through attribute schema definitions
Change tracking and dirty checking
Single-table inheritance naming (modelName/baseClass)
Event system for attribute changes

Constructor


new Model()

Instance Properties


bindedObjects: 
            
                Object.<string, Object>

Object containing references to objects this instance is listening to


eventListeners: 
            
                Object.<string, Array>

Object containing all event listeners


listenerId: 
            
                string

Unique identifier for this event bus instance


schema

The attribute schema this record uses for its accessors, defaults, type coercion and serialization. Defaults to the class's static schema; override the getter in a subclass to give a record a different schema. It is read during construction, before subclass fields are initialized.

Returns


                        
                            IModelSchema
                            |
                        
                            undefined

Instance Methods


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 :

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


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 :

The object to listen to events on

name :


            
                string
                |
            
                Array.<string>
                |
            
                object

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

callback :

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


changedAttributes()
    
    
    
        →
        
            
                
                    Array.<string>

Returns names of all attributes that have changed

Returns


                        
                            Array.<string>

Array of attribute names that have changed

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

Returns


                        
                            Object

Object containing changed attributes with [oldValue, newValue] pairs

Creates a clone of this record

Returns


                        
                            Model

A new instance with the same attributes and change state


declareProperties(attributes, options)

Hook for subclasses to declare and set up instance properties they need in place before attributes are applied (e.g. {@link Record} sets up its persistence flags and attaches associations here, since setAttributes may reference them). Called after the attribute accessors are defined and before setDefaultAttributes/setAttributes. Blank by default.

Parameters

attributes :


            
                Object

The attributes about to be applied

options :


            
                Object

Construction options


defineProperty(key)

Defines a getter/setter for an attribute on this instance, reading through {@link Model#readAttribute} and writing through {@link Model#setAttributes}. The constructor calls it for each key in {@link Model#schema}. A model whose schema depends on the record's own data can set that schema up in {@link Model#declareProperties} and call it for the keys it adds.

Parameters

key :


            
                string

The attribute name

Examples

class Product extends Model {
    static schema = { category_id: { type: 'integer' } };

    get schema() {
        return this._schema ?? super.schema;
    }

    declareProperties(attributes, options) {
        super.declareProperties(attributes, options);
        const fields = fieldsFor(attributes.category_id);
        this._schema = { ...super.schema, ...fields };
        Object.keys(fields).forEach(key => this.defineProperty(key));
    }
}


dispatchAttributeChange(key, oldValue, newValue, eventParameters)

Dispatches the change event for a single attribute, then notifies each collection tracking this model.

Parameters

key :


            
                string

The attribute that changed

oldValue :

The previous value of the attribute

newValue :

The new value of the attribute

eventParameters :


            
                Object

optional

Passed as the last argument to the events


dispatchChange(changes, eventParameters)

Dispatches the record-level change event for a batch of attribute changes, then notifies each collection tracking this model.

Parameters

changes :


            
                Object

The changes made, with [oldValue, newValue] pairs

eventParameters :


            
                Object

optional

Passed as the last argument to the events


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


flushChanges()
    
    
    
        →
        
            
                
                    Model

Clears the tracked changes, marking the current attributes as the clean baseline. This is the in-memory analog of persisting — {@link Record#persist} builds on it — without any notion of being saved to a server.

Returns


                        
                            Model

This instance for chaining


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


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


initialize(attributes, options)

Hook for the consuming stack to run custom setup after a record is fully constructed and its attributes applied. Blank by default; override without calling super.

Parameters

attributes :


            
                Object

The attributes the record was built with

options :


            
                Object

Construction options


readAttribute(attributeName)
    
    
    
        →
        
            
                
                    *

Get the value of an attribute

Parameters

attributeName :


            
                string

The name of the attribute to read

Returns

The attribute value


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 :

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


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 :

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


revertChanges(options)
    
    
    
        →
        
            
                
                    Model

Reverts all tracked changes, restoring attributes to the values they had before they were changed.

Parameters

options :


            
                Object

optional

eventParameters :


            
                Object

optional

Passed as the last argument to the dispatched change events

Returns


                        
                            Model

This instance for chaining


setAttribute(attribute, value, options)
    
    
    
        →
        
            
                
                    Model

Sets a single attribute value

Parameters

attribute :


            
                string

The attribute name to set

value :

The value to set

options :


            
                Object

optional

Options passed to {@link Model#setAttributes}, including eventParameters for the dispatched change events

Returns


                        
                            Model

This record instance for chaining


setAttributes(attributes, options)
    
    
    
        →
        
            
                
                    Model

Sets multiple attribute values at once

Parameters

attributes :


            
                Object

Object containing attribute name/value pairs to set

options :


            
                Object

optional

coerced :


            
                boolean

optional

Whether the attributes have already been coerced

dirty :


            
                boolean

optional

Whether the changes should be tracked as dirty

eventParameters :


            
                Object

optional

Passed as the last argument to the dispatched change events, e.g. setAttributes({status: 'active'}, {eventParameters: {silentNotification: true}})

Returns


                        
                            Model

This record instance for chaining


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

Returns a copy of the record's attributes for JSON serialization, so JSON.stringify(record) emits the attributes rather than internal state. Attribute values serialize themselves (e.g. Date via Date#toJSON).

Returns


                        
                            Object

A copy of the record's attributes

Static Methods


baseClass()
    
    
    
        →
        
            
                
                    Class.

<Model>

Gets the base class in the inheritance hierarchy for this model

Returns


                        
                            Class.<Model>

The base class of this model


coerceAttributes(attributes, record)
    
    
    
        →
        
            
                
                    Object

Coerces attribute values according to their type definitions in the schema

Parameters

attributes :


            
                Object

The attribute to coerce

record :


            
                Model

The record for which the attributes are being applied; when given, its {@link Model#schema} is used instead of the class schema

Returns


                        
                            Object

The coerced attributes


getInheritanceAttribute()
    
    
    
        →
        
            
                
                    string
                    |
                
                    boolean

Gets the inheritance attribute for this model

Returns

The inheritance attribute or default 'type'


modelName()
    
    
    
        →
        
            
                
                    Name

Gets the model name object for this model

Returns


                        
                            Name

Events


changed

Fired when attributes on a record are changed

Parameters

record :


            
                Model

The record that was changed

changes :


            
                Object

The changes made, with [oldValue, newValue] pairs

eventParameters :


            
                Object

The eventParameters option passed to {@link Model#setAttributes}


changed:{attribute}

Fired when a specific attribute on a record is changed

Parameters

record :


            
                Model

The record that was changed

oldValue :

The previous value of the attribute

newValue :

The new value of the attribute

eventParameters :


            
                Object

The eventParameters option passed to {@link Model#setAttributes}