DataModel

DataModel

DataModel class extends a JSON data model and performs all data operations (select, insert, update and delete) in MOST Data Applications.

These JSON schemas are in config/models folder: 


 /
 + config
   + models
     - User.json
     - Group.json
     - Account.json
     ...

The following JSON schema presents a typical User model with fields, views, privileges, constraints, listeners, and seeding: 


 {
     "name": "User", "id": 90, "title": "Application Users", "inherits": "Account", "hidden": false, "sealed": false, "abstract": false, "version": "1.4",
     "fields": [
         {
             "name": "id", "title": "Id", "description": "The identifier of the item.",
             "type": "Integer",
             "nullable": false,
             "primary": true
         },
         {
             "name": "accountType",  "title": "Account Type", "description": "Contains a set of flags that define the type and scope of an account object.",
             "type": "Integer",
             "readonly":true,
             "value":"javascript:return 0;"
         },
         {
             "name": "lockoutTime", "title": "Lockout Time", "description": "The date and time that this account was locked out.",
             "type": "DateTime",
             "readonly": true
         },
         {
             "name": "logonCount", "title": "Logon Count", "description": "The number of times the account has successfully logged on.",
             "type": "Integer",
             "value": "javascript:return 0;",
             "readonly": true
         },
         {
             "name": "enabled", "title": "Enabled", "description": "Indicates whether a user is enabled or not.",
             "type": "Boolean",
             "nullable": false,
             "value": "javascript:return true;"
         },
         {
             "name": "lastLogon", "title": "Last Logon", "description": "The last time and date the user logged on.",
             "type": "DateTime",
             "readonly": true
         },
         {
             "name": "groups", "title": "User Groups", "description": "A collection of groups where user belongs.",
             "type": "Group",
             "expandable": true,
             "mapping": {
                 "associationAdapter": "GroupMembers", "parentModel": "Group",
                 "parentField": "id", "childModel": "User", "childField": "id",
                 "associationType": "junction", "cascade": "delete",
                 "select": [
                     "id",
                     "name",
                     "alternateName"
                 ]
             }
         },
         {
             "name": "additionalType",
             "value":"javascript:return this.model.name;",
             "readonly":true
         },
         {
             "name": "accountType",
             "value": "javascript:return 0;"
         }
     ], "privileges":[
         { "mask":1, "type":"self", "filter":"id eq me()" },
         { "mask":15, "type":"global", "account":"*" }
     ],
     "constraints":[
         {
             "description": "User name must be unique across different records.",
             "type":"unique",
             "fields": [ "name" ]
         }
     ],
     "views": [
         {
             "name":"list", "title":"Users", "fields":[
                 { "name":"id", "hidden":true },
                 { "name":"description" },
                 { "name":"name" },
                 { "name":"enabled" , "format":"yesno" },
                 { "name":"dateCreated", "format":"moment : 'LLL'" },
                 { "name":"dateModified", "format":"moment : 'LLL'" }
             ], "order":"dateModified desc"
         }
     ],
     "eventListeners": [
         { "name":"New User Credentials Provider", "type":"/app/controllers/user-credentials-listener" }
     ],
     "seed":[
         {
             "name":"anonymous",
             "description":"Anonymous User",
             "groups":[
                 { "name":"Guests" }
             ]
         },
         {
             "name":"admin@example.com",
             "description":"Site Administrator",
             "groups":[
                 { "name":"Administrators" }
             ]
         }
     ]
 }

Constructor

new DataModel(objopt)

Parameters:
Name Type Attributes Description
obj * <optional>
 An object instance that holds data model attributes. This parameter is optional.
Properties:
Name Type Description
classPath string Gets or sets a string which represents the path of the DataObject subclass associated with this model.
name string Gets or sets a string that represents the name of the model.
id number Gets or sets an integer that represents the internal identifier of the model.
hidden boolean Gets or sets a boolean that indicates whether the current model is hidden or not. The default value is false.
title string Gets or sets a title for this data model.
sealed boolean Gets or sets a boolean that indicates whether current model is sealed or not. A sealed model cannot be migrated.
abstract boolean Gets or sets a boolean that indicates whether current model is an abstract model or not.
version string Gets or sets the version of this data model.
type string Gets or sets an internal type for this model.
caching DataCachingType | string Gets or sets a string that indicates the caching type for this model. The default value is none.
inherits string Gets or sets a string that contains the model that is inherited by the current model.
fields Array.<DataField> Gets or sets an array that represents the collection of model fields.
eventListeners Array.<DataModelEventListener> Gets or sets an array that represents the collection of model listeners.
constraints Array Gets or sets the array of constraints which are defined for this model
views Array.<DataModelView> Gets or sets the array of views which are defined for this model
privileges Array.<DataModelPrivilege> Gets or sets the array of privileges which are defined for this model
source string Gets or sets a string which represents the source database object for this model.
view string Gets or sets a string which represents the view database object for this model.
DataContext | * Gets or sets the data context of this model.
attributes Array.<DataField> Gets an array of DataField objects which represents the collection of model fields (including fields which are inherited from the base model).
seed Array An array of objects which represents a collection of items to be seeded when the model is being generated for the first time
Source:

Extends

  • EventEmitter2

Members

attributeNames :Array

Gets an array that contains model attribute names
Type:
  • Array
Source:

attributes :Array|*

Gets an array that contains all model attributes
Type:
  • Array | *
Source:

primaryKey :String

Gets the primary key name
Type:
  • String
Source:

(inner) attributes :Array

Type:
  • Array
Source:

Methods

all(callback)

Returns all data items.
Parameters:
Name Type Description
callback function A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result, if any.
Source:

asQueryable() → {DataQueryable}

Returns a DataQueryable instance of the current model
Source:
Returns:
Type
DataQueryable

base() → {DataModel}

Gets a DataModel instance which represents the inherited data model of this item, if any.
Source:
Returns:
Type
DataModel

cast(obj, stateopt) → {*}

Casts the given object and returns an object that is going to be used against the underlying database.
Parameters:
Name Type Attributes Description
obj * The source object which is going to be cast
state number <optional>
 The state of the source object.
Source:
Returns:
- Returns an object which is going to be against the underlying database.
Type
*

clone(contextopt) → {DataModel}

Clones the current data model
Parameters:
Name Type Attributes Description
context DataContext <optional>
 An instance of DataContext class which represents the current data context.
Source:
Returns:
Returns a new DataModel instance
Type
DataModel

convert(obj, typeConvertopt) → {DataObject|Array|*}

Converts an object or a collection of objects to the corresponding data object instance
Parameters:
Name Type Attributes Description
obj Array | *
typeConvert boolean <optional>
 Forces property value conversion for each property based on field type.
Source:
Returns:
- Returns an instance of DataObject (or an array of DataObject instances)

This conversion of an anonymous object through DataModel.convert() may be overriden by subclassing DataObject and place this class in app/models folder of a MOST Data Appllication: 


 /
 + app
   + models
     + user-model.js

An example of user model subclassing (user-model.js): 


 var util = require('util'),
 md = require('most-data'),
 web = require('most-web');

 function UserModel(obj) {
    UserModel.super_.call(this, 'User', obj);
}
 util.inherits(UserModel, md.classes.DataObject);

 UserModel.prototype.person = function (callback) {
    var self = this, context = self.context;
    try {
        //search person by user name
        return context.model('Person').where('user/name').equal(self.name).first(callback);
    }
    catch (err) {
        callback(err);
    }
};
 if (typeof module !== 'undefined') module.exports = UserModel;
Type
DataObject | Array | *
Example
//get User model
 var users = context.model('User');
 users.where('name').equal(context.user.name).first().then(function(result) {
    if (md.common.isNullOrUndefined(result)) {
        return done(new Error('User cannot be found'));
    }
    //convert result
    var user = users.convert(result);
    //get user's person
    user.person(function(err, result) {
        if (err) { return done(err); }
        if (md.common.isNullOrUndefined(result)) {
            return done(new Error('Person cannot be found'));
        }
        console.log('Person: ' + JSON.stringify(result));
        done(null, result);
    });
}).catch(function(err) {
   done(err);
});

dataviews(name) → {DataModelView|undefined}

Gets an instance of DataModelView class which represents a model view with the given name.
Parameters:
Name Type Description
name string A string that represents the name of the view.
Source:
Returns:
Type
DataModelView | undefined
Example
var view = context.model('Person').dataviews('summary');

field(name) → {DataField|*}

Gets an instance of DataField class based on the given name.
Parameters:
Name Type Description
name String The name of the field.
Source:
Returns:
- Returns a data field if exists. Otherwise returns null.
Type
DataField | *

fieldOf(attr, aliasopt) → {DataQueryable|QueryField|*}

Parameters:
Name Type Attributes Description
attr string | *
alias string <optional>
Source:
Returns:
Type
DataQueryable | QueryField | *

filter(params, callback)

Applies open data filter, ordering, grouping and paging params and returns a data queryable object
Parameters:
Name Type Description
params String | Object A string that represents an open data filter or an object with open data parameters
callback function A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain an instance of DataQueryable class.
Source:
Example
context.model('Order').filter(context.params, function(err,q) {
    if (err) { return callback(err); }
    q.take(10, function(err, result) {
        if (err) { return callback(err); }
        callback(null, result);
    });
 });

find(obj)

Prepares a data query with the given object as parameters and returns the equivalent DataQueryable instance
Parameters:
Name Type Description
obj * An object which represents the query parameters
Source:
Returns:
DataQueryable - An instance of DataQueryable class that represents a data query based on the given parameters.
Example
context.model('Order').find({ "paymentMethod":1 }).orderBy('dateCreated').take(10, function(err,result) {
    if (err) { return callback(err); }
    return callback(null, result);
 });

first(callbackopt) → {Promise.<T>|*}

Returns the first item of the current model.
Parameters:
Name Type Attributes Description
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Deprecated:
  • Use DataModel.asQueryable().first().
Source:
Returns:
If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *
Example
context.model('User').first(function(err, result) {
    if (err) { return done(err); }
    return done(null, result);
 });

get(key, callback) → {Deferred|*}

A helper function for getting an object based on the given primary key value
Parameters:
Name Type Description
key String | * The primary key value to search for.
callback function A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result, if any.
Source:
Returns:
If callback parameter is missing then returns a Deferred object.
Type
Deferred | *
Example
context.model('User').get(1).then(function(result) {
    return done(null, result);
}).catch(function(err) {
    return done(err);
});

getDataView(name) → {DataModelView|undefined}

Gets an instance of DataModelView class which represents a model view with the given name.
Parameters:
Name Type Description
name string A string that represents the name of the view.
Source:
Returns:
Type
DataModelView | undefined
Example
var view = context.model('Person').getDataView('summary');

getSuperTypes() → {Array}

Gets an array of strings which contains the super types of this model e.g. User model may have ['Account','Thing'] as super types
Source:
Returns:
Type
Array

idOf(obj) → {*|undefined}

Extracts an identifier from the given parameter. If the parameter is an object then gets the identifier property, otherwise tries to convert the given parameter to an identifier suitable for this model.
Parameters:
Name Type Description
obj *
Source:
Returns:
Type
* | undefined
Example
var id = context.model('User').idOf({ id:1, "name":"anonymous"});

inferMapping(name) → {DataAssociationMapping|undefined}

Gets a field association mapping based on field attributes, if any. Otherwise returns null.
Parameters:
Name Type Description
name string The name of the field
Source:
Returns:
Type
DataAssociationMapping | undefined

inferState(obj, callback)

Infers the state of the given object.
Parameters:
Name Type Description
obj DataObject | * The source object
callback function A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Source:
See:
  • DataObjectState

initialize()

Initializes the current data model. This method is used for extending the behaviour of an install of DataModel class.
Source:

insert(obj, callbackopt) → {Promise.<T>|*}

Inserts an item or an array of items
Parameters:
Name Type Attributes Description
obj * | Array The item or the array of items to update
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise.
Source:
Returns:
- If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *

key() → {DataField|*}

Gets an instance of DataField class which represents the primary key of this model.
Source:
Returns:
Type
DataField | *

last(callbackopt) → {Promise.<T>|*}

Returns the last item of the current model based.
Parameters:
Name Type Attributes Description
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Source:
Returns:
If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *
Example
context.model('User').last(function(err, result) {
    if (err) { return done(err); }
    return done(null, result);
 });

levels(valueopt) → {DataQueryable}

Sets the number of levels of the expandable attributes. The default value is 1 which means that any expandable attribute will be flat (without any other nested attribute). If the value is greater than 1 then the nested objects may contain other nested objects and so on.
Parameters:
Name Type Attributes Description
value Number <optional>
 A number which represents the number of levels which are going to be used in expandable attributes.
Source:
Returns:
Type
DataQueryable
Example
//get orders, expand customer and get customer's nested objects if any.
 context.model('Order')
 .levels(2)
 .orderByDescending('dateCreated)
 .expand('customer')
 .getItems().then(function(result) {
        done(null, result);
    }).catch(function(err) {
        done(err);
    });

list(callbackopt) → {Promise.<T>|*}

Returns an instance of DataResultSet of the current model.
Parameters:
Name Type Attributes Description
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Deprecated:
  • Use DataModel.asQueryable().list().
Source:
Returns:
If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *
Example
context.model('User').list(function(err, result) {
    if (err) { return done(err); }
    return done(null, result);
 });

max(attr, callbackopt) → {Promise.<T>|*}

Returns the maximum value for a field.
Parameters:
Name Type Attributes Description
attr string A string that represents the name of the field.
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Source:
Returns:
If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *

migrate(callback)

Performing an automatic migration of current data model based on the current model's definition.
Parameters:
Name Type Description
callback function A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Source:

min(attr, callbackopt) → {Promise.<T>|*}

Returns the minimum value for a field.
Parameters:
Name Type Attributes Description
attr string A string that represents the name of the field.
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Source:
Returns:
If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *

new(obj) → {*}

Casts the given object and returns an object that was prepared for insert.
Parameters:
Name Type Description
obj * The object to be cast
Source:
Returns:
Type
*

orderBy(attr)

Prepares an ascending order by expression and returns an instance of DataQueryable class.
Parameters:
Name Type Description
attr string | * A string that is going to be used in this expression.
Source:
Returns:
DataQueryable
Example
context.model('Person').orderBy('givenName').list().then(function(result) {
    done(null, result);
 }).catch(function(err) {
    done(err);
 });

orderByDescending(attr)

Prepares an descending order by expression and returns an instance of DataQueryable class.
Parameters:
Name Type Description
attr string | * A string that is going to be used in this expression.
Source:
Returns:
DataQueryable
Example
context.model('Person').orderByDescending('givenName').list().then(function(result) {
    done(null, result);
 }).catch(function(err) {
    done(err);
 });

recast(dest, src, callback)

Casts the given source object and returns a data object based on the current model.
Parameters:
Name Type Description
dest * The destination object
src * The source object
callback function A callback function where the first argument will contain the Error object if an error occured, or null otherwise.
Source:

remove(obj, callbackopt) → {Promise.<T>|*}

Deletes the given object or array of objects
Parameters:
Name Type Attributes Description
obj * | Array The item or the array of items to delete
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise.
Source:
Returns:
- If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *
Example
//remove group (Sales)
 var group = { "name":"Sales" };
 context.model("Group").remove(group).then(function() {
        done();
    }).catch(function(err) {
        done(err);
    });

save(obj, callbackopt) → {Promise.<T>|*}

Saves the given object or array of objects
Parameters:
Name Type Attributes Description
obj * | Array
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise.
Source:
Returns:
- If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *
Example
//save a new group (Sales)
 var group = { "description":"Sales Users", "name":"Sales" };
 context.model("Group").save(group).then(function() {
        console.log('A new group was created with ID ' + group.id);
        done();
    }).catch(function(err) {
        done(err);
    });
Initializes a full-text search statement and returns an instance of DataQueryable class.
Parameters:
Name Type Description
text String A string that represents the text to search for
Source:
Returns:
DataQueryable

select(…attr) → {DataQueryable}

Selects the given attribute or attributes and return an instance of DataQueryable class
Parameters:
Name Type Attributes Description
attr string <repeatable>
 An array of fields, a field or a view name
Source:
Returns:
Type
DataQueryable

silent(valueopt)

Prepares a silent data operation (for query, update, insert, delete etc). In a silent execution, permission check will be omitted. Any other listeners which are prepared for using silent execution will use this parameter.
Parameters:
Name Type Attributes Description
value Boolean <optional>
Source:
Returns:
DataModel

skip(n)

Bypasses a number of items based on the given parameter. This method is used in data paging operations.
Parameters:
Name Type Description
n Number The number of items to skip.
Source:
Returns:
DataQueryable

take(n, callbackopt)

Takes an array of maximum [n] items.
Parameters:
Name Type Attributes Description
n Number The maximum number of items that is going to be retrieved
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise. The second argument will contain the result.
Source:
Returns:
DataQueryable|undefined If callback parameter is missing then returns a DataQueryable object.

update(obj, callbackopt) → {Promise.<T>|*}

Updates an item or an array of items
Parameters:
Name Type Attributes Description
obj * | Array The item or the array of items to update
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise.
Source:
Returns:
- If callback parameter is missing then returns a Promise object.
Type
Promise.<T> | *

validateForInsert(obj, callbackopt) → {Promise|*}

Validates the given object against validation rules which are defined either by the data type or the definition of each attribute

Read more about data validation here.

Parameters:
Name Type Attributes Description
obj * The data object which is going to be validated
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise.
Source:
Returns:
- If callback parameter is missing then returns a Promise object.

Read more about data validation here

Type
Promise | *

validateForUpdate(obj, callbackopt) → {Promise|*}

Validates the given object against validation rules which are defined either by the data type or the definition of each attribute

Read more about data validation here.

Parameters:
Name Type Attributes Description
obj * The data object which is going to be validated
callback function <optional>
 A callback function where the first argument will contain the Error object if an error occured, or null otherwise.
Source:
Returns:
- If callback parameter is missing then returns a Promise object.
Type
Promise | *

where(attr)

Initializes a where statement and returns an instance of DataQueryable class.
Parameters:
Name Type Description
attr String | * A string that represents the name of a field
Source:
Returns:
DataQueryable