LoopBack models can manipulate data via the DataSource object. Attaching a DataSource to a Model adds instance methods and static methods to the Model.

Define a data source to persist model data. To create a DataSource programmatically, call createDataSource() on the LoopBack object; for example:

var oracle = loopback.createDataSource({
  connector: 'oracle',
  host: '111.22.333.44',
  database: 'MYDB',
  username: 'username',
  password: 'password'
});

All classes in single dataSource share same the connector type and one database connection.

For example, the following creates a DataSource, and waits for a connection callback.

var dataSource = new DataSource('mysql', { database: 'myapp_test' });
dataSource.define(...);
dataSource.on('connected', function () {
    // work with database
});

Define readonly property on object

Define a hidden property It is an utility to define a property to the Object with info flags

Attach an existing model to a data source. This will mixin all of the data access object functions (DAO) into your modelClass definition.

Drop schema objects such as tables, indexes, views, triggers, etc that correspond to model definitions attached to this DataSource instance, specified by the models parameter.

WARNING: In many situations, this will destroy data! autoupdate() will attempt to preserve data while updating the schema on your target DataSource, but this is not guaranteed to be safe.

Please check the documentation for your specific connector(s) for a detailed breakdown of behaviors for automigrate!

Update existing database tables. This method applies only to database connectors.

WARNING: autoupdate() will attempt to preserve data while updating the schema on your target DataSource, but this is not guaranteed to be safe.

Please check the documentation for your specific connector(s) for a detailed breakdown of behaviors for automigrate!*

Introspect a JSON object and build a model class

Return column metadata for specified modelName and propertyName

Return column name for specified modelName and propertyName

Return column names for specified modelName

Connect to the data source. If no callback is provided, it will return a Promise. Emits the 'connect' event.

Define a model class. Returns newly created model object. The first (String) argument specifying the model name is required. You can provide one or two JSON object arguments, to provide configuration options. See Model definition reference for details.

Simple example:

var User = dataSource.createModel('User', {
    email: String,
    password: String,
    birthDate: Date,
    activated: Boolean
});

More advanced example

var User = dataSource.createModel('User', {
    email: { type: String, limit: 150, index: true },
    password: { type: String, limit: 50 },
    birthDate: Date,
    registrationDate: {type: Date, default: function () { return new Date }},
    activated: { type: Boolean, default: false }
});

You can also define an ACL when you create a new data source with the DataSource.create() method. For example:

var Customer = ds.createModel('Customer', {
      name: {
        type: String,
        acls: [
          {principalType: ACL.USER, principalId: 'u001', accessType: ACL.WRITE, permission: ACL.DENY},
          {principalType: ACL.USER, principalId: 'u001', accessType: ACL.ALL, permission: ACL.ALLOW}
        ]
      }
    }, {
      acls: [
        {principalType: ACL.USER, principalId: 'u001', accessType: ACL.ALL, permission: ACL.ALLOW}
      ]
    });

Define foreign key to another model

Define an operation to the data source

Define a property with name prop on a target model. See Properties for more information regarding valid options for params.

Disable remote access to a data source operation. Each connector has its own set of set enabled and disabled operations. To list the operations, call dataSource.operations().

var oracle = loopback.createDataSource({
  connector: require('loopback-connector-oracle'),
  host: '...',
  ...
});
oracle.disableRemote('destroyAll');

Notes:

• Disabled operations will not be added to attached models.
• Disabling the remoting for a method only affects client access (it will still be available from server models).
• Data sources must enable / disable operations before attaching or creating models.

Close connection to the DataSource.

Discover and build models from the specified owner/modelName.

Discover and build models from the given owner/modelName synchronously.

Retrieves a description of the foreign key columns that reference the given table's primary key columns (the foreign keys exported by a table), ordered by fkTableOwner, fkTableName, and keySeq.

Callback function return value is an object that can have the following properties:

See Relations for more information.

The synchronous version of discoverExportedForeignKeys

Discover foreign keys for a given owner/modelName

Callback function return value is an object that can have the following properties:

See Relations for more information.

The synchronous version of discoverForeignKeys

Discover existing database tables. This method returns an array of model objects, including {type, name, onwer}

The synchronous version of discoverModelDefinitions.

Discover properties for a given model.

Callback function return value is an object that can have the following properties:

See Properties for more details on the Property return type.

The synchronous version of discoverModelProperties

Discover primary keys for a given owner/modelName. Callback function return value is an object that can have the following properties:

See ID Properties for more information.

The synchronous version of discoverPrimaryKeys

Discover one schema from the given model without following the relations. *Example schema from oracle connector:**

    {
      "name": "Product",
      "options": {
        "idInjection": false,
        "oracle": {
          "schema": "BLACKPOOL",
          "table": "PRODUCT"
        }
      },
      "properties": {
        "id": {
          "type": "String",
          "required": true,
          "length": 20,
          "id": 1,
          "oracle": {
            "columnName": "ID",
            "dataType": "VARCHAR2",
            "dataLength": 20,
            "nullable": "N"
          }
        },
        "name": {
          "type": "String",
          "required": false,
          "length": 64,
          "oracle": {
            "columnName": "NAME",
            "dataType": "VARCHAR2",
            "dataLength": 64,
            "nullable": "Y"
          }
        },
...
        "fireModes": {
          "type": "String",
          "required": false,
          "length": 64,
          "oracle": {
            "columnName": "FIRE_MODES",
            "dataType": "VARCHAR2",
            "dataLength": 64,
            "nullable": "Y"
          }
        }
      }
    }

Discover schema from a given tableName/viewName.

Discover schema from a given table/view synchronously

Enable remote access to a data source operation. Each connector has its own set of set remotely enabled and disabled operations. To list the operations, call dataSource.operations().

Freeze dataSource. Behavior depends on connector To continuously add artifacts to datasource until it is frozen, but it is not really used in loopback.

See ModelBuilder.getModel for details.

See ModelBuilder.getModelDefinition See ModelBuilder.getModelDefinition for details.

Get an operation's metadata.

Get the data source types collection.

Find the ID column name

Find the ID property name

Find the ID property names sorted by the index

Find the id property definition

Check whether or not migrations are required for the database schema to match the Model definitions attached to the DataSource. Note: This method applies only to SQL connectors.

Check if the backend is a relational DB

Return JSON object describing all operations.

Example return value:

{
 find: {
   remoteEnabled: true,
   accepts: [...],
   returns: [...]
   enabled: true
},
 save: {
   remoteEnabled: true,
   prototype: true,
   accepts: [...],
   returns: [...],
   enabled: true
 },
 ...
}

Ping the underlying connector to test the connections

Check if the data source is ready. Returns a Boolean value.

Check the data source supports the specified types.

Return table name for specified modelName.

Run a transaction against the DataSource.

This method can be used in different ways based on the passed arguments and type of underlying data source:

If no execute() function is provided and the underlying DataSource is a database that supports transactions, a Promise is returned that resolves to an EventEmitter representing the transaction once it is ready. transaction.models can be used to receive versions of the DataSource's model classes which are bound to the created transaction, so that all their database methods automatically use the transaction. At the end of all database transactions, transaction.commit() can be called to commit the transactions, or transaction.rollback() to roll them back.

If no execute() function is provided on a transient or memory DataSource, the EventEmitter representing the transaction is returned immediately. For backward compatibility, this object also supports transaction.exec() instead of transaction.commit(), and calling transaction.rollback() is not required on such transient and memory DataSource instances.

If an execute() function is provided, then it is called as soon as the transaction is ready, receiving transaction.models as its first argument. transaction.commit() and transaction.rollback() are then automatically called at the end of execute(), based on whether exceptions happen during execution or not. If no callback is provided to be called at the end of the execution, a Promise object is returned that is resolved or rejected as soon as the execution is completed, and the transaction is committed or rolled back.

Model class: base class for all persistent objects.

ModelBaseClass mixes Validatable and Hookable classes methods

Define a property on the model.

getMergePolicy() provides model merge policies to apply when extending a child model from a base model. Such a policy drives the way parent/child model properties/settings are merged/mixed-in together.

Below is presented the expected merge behaviour for each option. NOTE: This applies to top-level settings properties

• Any

  • {replace: true} (default): child replaces the value from parent
  • assignin null on child setting deletes the inherited setting

• Arrays:

  • {replace: false}: unique elements of parent and child cumulate
  • {rank: true} adds the model inheritance rank to array elements of type Object {} as internal property __rank

• Object {}:

  • {replace: false}: deep merges parent and child objects
  • {patch: true}: child replaces inner properties from parent

The recommended built-in merge policy is as follows. It is returned by getMergePolicy() when calling the method with option {configureModelMerge: true}.

{
  description: {replace: true}, // string or array
  options: {patch: true}, // object
  hidden: {replace: false}, // array
  protected: {replace: false}, // array
  indexes: {patch: true}, // object
  methods: {patch: true}, // object
  mixins: {patch: true}, // object
  relations: {patch: true}, // object
  scope: {replace: true}, // object
  scopes: {patch: true}, // object
  acls: {rank: true}, // array
  // this setting controls which child model property's value allows deleting
  // a base model's property
  __delete: null,
  // this setting controls the default merge behaviour for settings not defined
  // in the mergePolicy specification
  __default: {replace: true},
}

The legacy built-in merge policy is as follows, it is retuned by getMergePolicy() when avoiding option configureModelMerge. NOTE: it also provides the ACLs ranking in addition to the legacy behaviour, as well as fixes for settings 'description' and 'relations': matching relations from child replace relations from parents.

{
  description: {replace: true}, // string or array
  properties: {patch: true}, // object
  hidden: {replace: false}, // array
  protected: {replace: false}, // array
  relations: {acls: true}, // object
  acls: {rank: true}, // array
}

getMergePolicy() can be customized using model's setting configureModelMerge as follows:

{
// ..
options: {
  configureModelMerge: {
    // merge options
  }
}
// ..
}

NOTE: mergePolicy parameter can also defined at JSON model definition root

getMergePolicy() method can also be extended programmatically as follows:

myModel.getMergePolicy = function(options) {
  const origin = myModel.base.getMergePolicy(options);
  return Object.assign({}, origin, {
    // new/overriding options
  });
};

Get model property type.

Gets properties defined with 'updateOnly' flag set to true from the model. This flag is also set to true internally for the id property, if this property is generated and IdInjection is true.

Checks if property is hidden.

Checks if property is protected.

Return string representation of class This overrides the default toString() method

Get model property type.

Reset dirty attributes. This method does not perform any database operations; it just resets the object to its initial state.

Convert model instance to a plain JSON object. Returns a canonical object representation (no getters and setters).

A String whose value is a valid representation of a Date. Use this type if you need to preserve the format of the value and still check if it's valid. Example:

var loopback = require('loopback');
var dt = new loopback.DateString('2001-01-01');

dt.toString();
// '2001-01-01'
dt._date.toISOString();
// '2001-01-01T00:00:00.000Z'

You can use this definition on your models as well:

{
  "name": "Person",
  "base": "PersistedModel",
  "properties": {
    "name": {
      "type": "string"
    },
    "dob": {
      "type": "DateString",
      "required": true
    },
  },
  "validations": [],
  "relations": {},
  "acls": [],
  "methods": {}
}

Returns the JSON representation of the DateString object.

Returns the value of DateString in its original form.

The GeoPoint object represents a physical location.

For example:

var loopback = require(‘loopback’);
var here = new loopback.GeoPoint({lat: 10.32424, lng: 5.84978});

Embed a latitude / longitude point in a model.

var CoffeeShop = loopback.createModel('coffee-shop', {
  location: 'GeoPoint'
});

You can query LoopBack models with a GeoPoint property and an attached data source using geo-spatial filters and sorting. For example, the following code finds the three nearest coffee shops.

CoffeeShop.attachTo(oracle);
var here = new GeoPoint({lat: 10.32424, lng: 5.84978});
CoffeeShop.find( {where: {location: {near: here}}, limit:3}, function(err, nearbyShops) {
  console.info(nearbyShops); // [CoffeeShop, ...]
});

Determine the spherical distance between two GeoPoints.

Determine the spherical distance to the given point. Example:

var loopback = require(‘loopback’);

var here = new loopback.GeoPoint({lat: 10, lng: 10});
var there = new loopback.GeoPoint({lat: 5, lng: 5});

loopback.GeoPoint.distanceBetween(here, there, {type: 'miles'}) // 438

Simple serialization.

Hooks object.

Utility Function to allow interleave before and after high computation tasks

Inclusion - Model mixin.

Make the DB Call, fetch all target objects

Find related items with an array of foreign keys by page

Enables you to load relations of several objects and optimize numbers of requests.

Examples:

Load all users' posts with only one additional request: User.include(users, 'posts', function() {}); Or User.include(users, ['posts'], function() {});

Load all users posts and passports with two additional requests: User.include(users, ['posts', 'passports'], function() {});

Load all passports owner (users), and all posts of each owner loaded: Passport.include(passports, {owner: 'posts'}, function() {}); Passport.include(passports, {owner: ['posts', 'passports']}); ` Passport.include(passports, {owner: [{posts: 'images'}, 'passports']});

Handle Inclusion of EmbedsMany/EmbedsManyWithBelongsTo/EmbedsOne Relations. Since Embedded docs are part of parents, no need to make db calls. Let the related function be called for each object to fetch the results from cache.

TODO: Optimize EmbedsManyWithBelongsTo relation DB Calls

Handle inclusion of HasMany relation

Handle inclusion of HasMany relation

Handle inclusion of HasManyThrough/HasAndBelongsToMany/Polymorphic HasManyThrough relations

Handle Inclusion of BelongsTo/HasOne relation

Handle Inclusion of Polymorphic BelongsTo relation

Handle Inclusion of Polymorphic HasOne relation

Handle inclusion of ReferencesMany relation

Process Polymorphic objects of each type (modelType)

Process Each Model Object and make sure specified relations are included

Sets the related objects as a property of Parent Object

Handle the fetched target objects

Process fetched related objects

Process fetched related objects

Process fetched related objects

Process fetched related objects

Handle the results of Through model objects and fetch the modelTo items

ModelBuilder - A builder to define data models.

Extend the model with the specified model, properties, and other settings. For example, to extend an existing model, for example, a built-in model:

var Customer = User.extend('customer', {
  accountId: String,
  vip: Boolean
});

To extend the base model, essentially creating a new model:

var user = loopback.Model.extend('user', properties, options);

Merge parent and child model settings according to the provided merge policy.

Below is presented the expected merge behaviour for each option of the policy. NOTE: This applies to top-level settings properties

• Any

  • {replace: true} (default): child replaces the value from parent
  • assigning null on child setting deletes the inherited setting

• Arrays:

  • {replace: false}: unique elements of parent and child cumulate
  • {rank: true} adds the model inheritance rank to array elements of type Object {} as internal property __rank

• Object {}:

  • {replace: false}: deep merges parent and child objects
  • {patch: true}: child replaces inner properties from parent

Here is an example of merge policy:

{
  description: {replace: true}, // string or array
  properties: {patch: true}, // object
  hidden: {replace: false}, // array
  protected: {replace: false}, // array
  relations: {acls: true}, // object
  acls: {rank: true}, // array
}

Register a property for the model class

Introspect the JSON document to build a corresponding model.

Build models from schema definitions

schemas can be one of the following:

1. An array of named schema definition JSON objects
2. A schema definition JSON object
3. A list of property definitions (anonymous)

Define a model class. Simple example:

var User = modelBuilder.define('User', {
    email: String,
    password: String,
    birthDate: Date,
    activated: Boolean
});

More advanced example:

var User = modelBuilder.define('User', {
    email: { type: String, limit: 150, index: true },
    password: { type: String, limit: 50 },
    birthDate: Date,
    registrationDate: {type: Date, default: function () { return new Date }},
    activated: { type: Boolean, default: false }
});

Define single property named propertyName on model

Define a new value type that can be used in model schemas as a property type.

Extend existing model with specified properties

Example: Instead of extending a model with attributes like this (for example):

    db.defineProperty('Content', 'competitionType',
      { type: String });
    db.defineProperty('Content', 'expiryDate',
      { type: Date, index: true });
    db.defineProperty('Content', 'isExpired',
      { type: Boolean, index: true });

This method enables you to extend a model as follows (for example):

    db.extendModel('Content', {
      competitionType: String,
      expiryDate: { type: Date, index: true },
      isExpired: { type: Boolean, index: true }
    });

Get a model by name.

Get the model definition by name

Get the schema name. If no parameter is given, then an anonymous model name is generated and returned.

Resolve the type string to be a function, for example, 'String' to String. Returns {Function} if the type is resolved

RelationMixin class. Use to define relationships between models.

Declare "belongsTo" relation that sets up a one-to-one connection with another model, such that each instance of the declaring model "belongs to" one instance of the other model.

For example, if an application includes users and posts, and each post can be written by exactly one user. The following code specifies that Post has a reference called author to the User model via the userId property of Post as the foreign key.

Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});

You can then access the author in one of the following styles. Get the User object for the post author asynchronously:

post.author(callback);

Get the User object for the post author synchronously:

post.author();

Set the author to be the given user:

post.author(user)

Examples:

Suppose the model Post has a belongsTo relationship with User (the author of the post). You could declare it this way:

Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});

When a post is loaded, you can load the related author with:

post.author(function(err, user) {
    // the user variable is your user object
});

The related object is cached, so if later you try to get again the author, no additional request will be made. But there is an optional boolean parameter in first position that set whether or not you want to reload the cache:

post.author(true, function(err, user) {
    // The user is reloaded, even if it was already cached.
});

This optional parameter default value is false, so the related object will be loaded from cache if available.

Represent a model that can embed many instances of another model.

For example, a Customer can have multiple email addresses and each email address is a complex object that contains label and address.

Define the relation code in bootscript:

  Customer.embedsMany(EmailAddress, {
    as: 'emails', // default to the relation name - emailAddresses
    property: 'emailList' // default to emailAddressItems
  });

OR, define the relation in the model definition:

• Definition of Customer model:

  {
  "name": "Customer",
  "base": "PersistedModel",
  "idInjection": true,
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  },
  "validations": [],
  "relations": {
    "emails": {
      "type": "embedsMany",
      "model": "EmailAddress",
      "property": "emailList",
      "options": {
        "validate": true,
        "forceId": false
      }
    }
  },
  "acls": [],
  "methods": {}
  }
  

• Definition of EmailAddress model:

  {
  "name": "EmailAddress",
  "base": "Model",
  "idInjection": true,
  "properties": {
    "label": {
      "type": "string"
    },
    "address": {
      "type": "string"
    }
  },
  "validations": [],
  "relations": {},
  "acls": [],
  "methods": {}
  }
  

Sample embedded model data:

{
  id: 1,
  name: 'John Smith',
  emails: [{
    label: 'work',
    address: 'john@xyz.com'
  }, {
    label: 'home',
    address: 'john@gmail.com'
  }]
}

Supported helper methods:

• customer.emails()
• customer.emails.create()
• customer.emails.build()
• customer.emails.findById()
• customer.emails.destroyById()
• customer.emails.updateById()
• customer.emails.exists()
• customer.emails.add()
• customer.emails.remove()
• customer.emails.at()
• customer.emails.value()

Represent a model that embeds another model.

For example, a Customer embeds one billingAddress from the Address model.

• Define the relation in bootscript:

  Customer.embedsOne(Address, {
  as: 'address', // default to the relation name - address
  property: 'billingAddress' // default to addressItem
  });
  

OR, define the relation in the model definition:

• Definition of Customer model:

  {
  "name": "Customer",
  "base": "PersistedModel",
  "idInjection": true,
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  },
  "validations": [],
  "relations": {
    "address": {
      "type": "embedsOne",
      "model": "Address",
      "property": "billingAddress",
      "options": {
        "validate": true,
        "forceId": false
      }
    }
  },
  "acls": [],
  "methods": {}
  }
  

• Definition of Address model:

  {
  "name": "Address",
  "base": "Model",
  "idInjection": true,
  "properties": {
    "street": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "state": {
      "type": "string"
    },
    "zipCode": {
      "type": "string"
    }
  },
  "validations": [],
  "relations": {},
  "acls": [],
  "methods": {}
  }
  

Sample embedded model data:

{
  id: 1,
  name: 'John Smith',
  billingAddress: {
    street: '123 Main St',
    city: 'San Jose',
    state: 'CA',
    zipCode: '95124'
  }
}

Supported helper methods:

• customer.address()
• customer.address.build()
• customer.address.create()
• customer.address.update()
• customer.address.destroy()
• customer.address.value()

A hasAndBelongsToMany relation creates a direct many-to-many connection with another model, with no intervening model.

For example, if your application includes users and groups, with each group having many users and each user appearing in many groups, you could declare the models this way:

 User.hasAndBelongsToMany('groups', {model: Group, foreignKey: 'groupId'});

Then, to get the groups to which the user belongs:

 user.groups(callback);

Create a new group and connect it with the user:

 user.groups.create(data, callback);

Connect an existing group with the user:

 user.groups.add(group, callback);

Remove the user from the group:

 user.groups.remove(group, callback);

Define a "one to many" relationship by specifying the model name.

Examples:

User.hasMany(Post, {as: 'posts', foreignKey: 'authorId'});

Book.hasMany(Chapter);

Or, equivalently:

Book.hasMany('chapters', {model: Chapter});

Query and create related models:

Book.create(function(err, book) {

  // Create a chapter instance ready to be saved in the data source.
  var chapter = book.chapters.build({name: 'Chapter 1'});

  // Save the new chapter
  chapter.save();

 // you can also call the Chapter.create method with the `chapters` property which will build a chapter
 // instance and save the it in the data source.
 book.chapters.create({name: 'Chapter 2'}, function(err, savedChapter) {
   // this callback is optional
 });

  // Query chapters for the book
  book.chapters(function(err, chapters) {
    // all chapters with bookId = book.id
    console.log(chapters);
  });

  // Query chapters for the book with a filter
  book.chapters({where: {name: 'test'}, function(err, chapters) {
   // All chapters with bookId = book.id and name = 'test'
    console.log(chapters);
  });
});

Define a "one to one" relationship by specifying the model name.

Examples:

Supplier.hasOne(Account, {as: 'account', foreignKey: 'supplierId'});

If the target model doesn’t have a foreign key property, LoopBack will add a property with the same name.

The type of the property will be the same as the type of the target model’s id property.

Please note the foreign key property is defined on the target model (in this example, Account).

If you don’t specify them, then LoopBack derives the relation name and foreign key as follows:

• Relation name: Camel case of the model name, for example, for the “supplier” model the relation is “supplier”.
• Foreign key: The relation name appended with Id, for example, for relation name “supplier” the default foreign key is “supplierId”.

Build a new account for the supplier with the supplierId to be set to the id of the supplier.

 var supplier = supplier.account.build(data);

Create a new account for the supplier. If there is already an account, an error will be reported.

supplier.account.create(data, function(err, account) {
 ...
});

Find the supplier's account model.

supplier.account(function(err, account) {
 ...
});

Update the associated account.

supplier.account.update({balance: 100}, function(err, account) {
 ...
});

Remove the account for the supplier.

supplier.account.destroy(function(err) {
 ...
});

References one or more instances of the target model.

For example, a Customer model references one or more instances of the Account model.

Define the relation in the model definition:

• Definition of Customer model:

  {
  "name": "Customer",
  "base": "PersistedModel",
  "idInjection": true,
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  },
  "validations": [],
  "relations": {
    "accounts": {
      "type": "referencesMany",
      "model": "Account",
      "foreignKey": "accountIds",
      "options": {
        "validate": true,
        "forceId": false
      }
    }
  },
  "acls": [],
  "methods": {}
  }
  

• Definition of Account model:

  {
  "name": "Account",
  "base": "PersistedModel",
  "idInjection": true,
  "properties": {
    "name": {
      "type": "string"
    },
    "balance": {
      "type": "number"
    }
  },
  "validations": [],
  "relations": {},
  "acls": [],
  "methods": {}
  }
  

On the bootscript, create a customer instance and for that customer instance reference many account instances.

For example:

var Customer = app.models.Customer;
  var accounts = [
    {
      name: 'Checking',
      balance: 5000
    },
    {
      name: 'Saving',
      balance: 2000
    }
  ];
  Customer.create({name: 'Mary Smith'}, function(err, customer) {
    console.log('Customer:', customer);
    async.each(accounts, function(account, done) {
      customer.accounts.create(account, done);
    }, function(err) {
      console.log('Customer with accounts:', customer);
      customer.accounts(console.log);
      cb(err);
    });
  });

Sample referencesMany model data:

{
  id: 1,
  name: 'John Smith',
  accounts: [
    "saving-01", "checking-01",
  ]
}

Supported helper methods:

• customer.accounts()
• customer.accounts.create()
• customer.accounts.build()
• customer.accounts.findById()
• customer.accounts.destroy()
• customer.accounts.updateById()
• customer.accounts.exists()
• customer.accounts.add()
• customer.accounts.remove()
• customer.accounts.at()

ObserverMixin class. Use to add observe/notifyObserversOf APIs to other classes.

Unregister all asynchronous observers for the given operation (event).

Example:

Remove all observers connected to the before save operation.

MyModel.clearObservers('before save');

Run the given function with before/after observers.

It's done in three serial asynchronous steps:

• Notify the registered observers under 'before ' + operation
• Execute the function
• Notify the registered observers under 'after ' + operation

If an error happens, it fails first and calls the callback with err.

Example:

var context = {
    Model: Model,
    instance: obj,
    isNewInstance: true,
    hookState: hookState,
    options: options,
 };
function work(done) {
   process.nextTick(function() {
      done(null, 1);
    });
  }
Model.notifyObserversAround('execute', context, work, function(err) {
    if (err) return cb(err);
    // user can specify the logic after the observers have been notified
 });

Invoke all async observers for the given operation(s).

Example:

Notify all async observers for the before save operation.

var context = {
    Model: Model,
    instance: obj,
    isNewInstance: true,
    hookState: hookState,
    options: options,
 };
Model.notifyObserversOf('before save', context, function(err) {
    if (err) return cb(err);
    // user can specify the logic after the observers have been notified
 });

Register an asynchronous observer for the given operation (event).

Example:

Registers a before save observer for a given model.

MyModel.observe('before save', function filterProperties(ctx, next) {
  if (ctx.options && ctx.options.skipPropertyFilter) return next();
  if (ctx.instance) {
    FILTERED_PROPERTIES.forEach(function(p) {
      ctx.instance.unsetAttribute(p);
    });
  } else {
    FILTERED_PROPERTIES.forEach(function(p) {
      delete ctx.data[p];
    });
  }
  next();
});

Unregister an asynchronous observer for the given operation (event).

Example:

MyModel.removeObserver('before save', function removedObserver(ctx, next) {
    // some logic user want to apply to the removed observer...
    next();
 });

TransactionMixin class. Use to add transaction APIs to a model class.

Begin a new transaction.

A transaction can be committed or rolled back. If timeout happens, the transaction will be rolled back. Please note a transaction is typically associated with a pooled connection. Committing or rolling back a transaction will release the connection back to the pool.

Once the transaction is committed or rolled back, the connection property will be set to null to mark the transaction to be inactive. Trying to commit or rollback an inactive transaction will receive an error from the callback.

Please also note that the transaction is only honored with the same data source/connector instance. CRUD methods will not join the current transaction if its model is not attached the same data source.

Example:

To pass the transaction context to one of the CRUD methods, use the options argument with transaction property, for example,

MyModel.beginTransaction('READ COMMITTED', function(err, tx) {
  MyModel.create({x: 1, y: 'a'}, {transaction: tx}, function(err, inst) {
    MyModel.find({x: 1}, {transaction: tx}, function(err, results) {
      // ...
      tx.commit(function(err) {...});
    });
  });
});

Commit a transaction and release it back to the pool.

Example:

MyModel.beginTransaction('READ COMMITTED', function(err, tx) {
  // some crud operation of your choice
  tx.commit(function(err) {
    // release the connection pool upon committing
    tx.close(err);
  });
});

Rollback a transaction and release it back to the pool.

Example:

MyModel.beginTransaction('READ COMMITTED', function(err, tx) {
  // some crud operation of your choice
  tx.rollback(function(err) {
    // release the connection pool upon committing
    tx.close(err);
  });
});

This class provides methods that add validation cababilities to models. Each of the validations runs when the obj.isValid() method is called.

All of the methods have an options object parameter that has a message property. When there is only a single error message, this property is just a string; for example: Post.validatesPresenceOf('title', { message: 'can not be blank' });

In more complicated cases it can be a set of messages, for each possible error condition; for example: User.validatesLengthOf('password', { min: 6, max: 20, message: {min: 'too short', max: 'too long'}});

Validate using custom validation function.

Example:

    User.validate('name', customValidator, {message: 'Bad name'});
    function customValidator(err) {
        if (this.name === 'bad') err();
    });
    var user = new User({name: 'Peter'});
    user.isValid(); // true
    user.name = 'bad';
    user.isValid(); // false

Validate using custom asynchronous validation function.

Example:

    User.validateAsync('name', customValidator, {message: 'Bad name'});
    function customValidator(err, done) {
        process.nextTick(function () {
            if (this.name === 'bad') err();
            done();
        });
    });
    var user = new User({name: 'Peter'});
    user.isValid(); // false (because async validation setup)
    user.isValid(function (isValid) {
        isValid; // true
    })
    user.name = 'bad';
    user.isValid(); // false
    user.isValid(function (isValid) {
        isValid; // false
    })

Validate absence of one or more specified properties.

A model should not include a property to be considered valid; fails when validated field is not blank.

For example, validate absence of reserved

Post.validatesAbsenceOf('reserved', { unless: 'special' });

Validate if a value for a property is a Date.

Example

User.validatesDateOf('today', {message: 'today is not a date!'});

Validate exclusion in a set.

Require a property value not be in the specified array.

Example: Company.validatesExclusionOf('domain', {in: ['www', 'admin']});

Validate format.

Require a model to include a property that matches the given format.

Example: User.validatesFormatOf('name', {with: /\w+/});

Validate inclusion in set.

Require a value for property to be in the specified array.

Example:

User.validatesInclusionOf('gender', {in: ['male', 'female']});
User.validatesInclusionOf('role', {
    in: ['admin', 'moderator', 'user'], message: 'is not allowed'
});

Validate length.

Require a property length to be within a specified range.

There are three kinds of validations: min, max, is.

Default error messages:

• min: too short
• max: too long
• is: length is wrong

Example: length validations

User.validatesLengthOf('password', {min: 7});
User.validatesLengthOf('email', {max: 100});
User.validatesLengthOf('state', {is: 2});
User.validatesLengthOf('nick', {min: 3, max: 15});

Example: length validations with custom error messages

User.validatesLengthOf('password', {min: 7, message: {min: 'too weak'}});
User.validatesLengthOf('state', {is: 2, message: {is: 'is not valid state name'}});

Validate numericality.

Requires a value for property to be either an integer or number.

Example

User.validatesNumericalityOf('age', { message: { number: 'is not a number' }});
User.validatesNumericalityOf('age', {int: true, message: { int: 'is not an integer' }});

Validate presence of one or more specified properties.

Requires a model to include a property to be considered valid; fails when validated field is blank.

For example, validate presence of title

Post.validatesPresenceOf('title');

Validate that model has first, last, and age properties:

User.validatesPresenceOf('first', 'last', 'age');

Example with custom message

Post.validatesPresenceOf('title', {message: 'Cannot be blank'});

Validate uniqueness of the value for a property in the collection of models.

Not available for all connectors. Currently supported with these connectors:

• In Memory
• Oracle
• MongoDB

// The login must be unique across all User instances.
User.validatesUniquenessOf('login');

// Assuming SiteUser.belongsTo(Site)
// The login must be unique within each Site.
SiteUser.validateUniquenessOf('login', { scopedTo: ['siteId'] });

This method performs validation and triggers validation hooks. Before validation the obj.errors collection is cleaned. Each validation can add errors to obj.errors collection. If collection is not blank, validation failed.

NOTE: This method can be called as synchronous only when no asynchronous validation is configured. It's strongly recommended to run all validations as asyncronous.

Example: ExpressJS controller - render user if valid, show flash otherwise

user.isValid(function (valid) {
    if (valid) res.render({user: user});
    else res.flash('error', 'User is not valid'), console.log(user.errors), res.redirect('/users');
});

Another example:

user.isValid(function (valid) {
    if (!valid) {
          console.log(user.errors);
        // => hash of errors
        // => {
        // => username: [errmessage, errmessage, ...],
        // => email: ...
        // => }
    }
});