var app = loopback()

LoopBackApplication

The App object represents a Loopback application.

The App object extends Express and supports Express / Connect middleware. See Express documentation for details.

var loopback = require('loopback');
var app = loopback();

app.get('/', function(req, res){
  res.send('hello world');
});

app.listen(3000);

Class: LoopBackApplication Static Methods

app.boot([options])

Initialize an application from an options object or a set of JSON and JavaScript files.

This function takes an optional argument that is either a string or an object.

If the argument is a string, then it sets the application root directory based on the string value. Then it:

  1. Creates DataSources from the datasources.json file in the application root directory.
  2. Creates Models from the models.json file in the application root directory.

If the argument is an object, then it looks for model, dataSources, and appRootDir properties of the object. If the object has no appRootDir property then it sets the current working directory as the application root directory. Then it:

  1. Creates DataSources from the options.dataSources object.
  2. Creates Models from the options.models object.

In both cases, the function loads JavaScript files in the /models and /boot subdirectories of the application root directory with require().

NOTE: mixing app.boot() and app.model(name, config) in multiple files may result in models being undefined due to race conditions. To avoid this when using app.boot() make sure all models are passed as part of the models definition.

Throws an error if the config object is not valid or if boot fails.

Model Definitions

The following is example JSON for two Model definitions: "dealership" and "location".

{
  "dealership": {
    // a reference, by name, to a dataSource definition
    "dataSource": "my-db",
    // the options passed to Model.extend(name, properties, options)
    "options": {
      "relations": {
        "cars": {
          "type": "hasMany",
          "model": "Car",
          "foreignKey": "dealerId"  
        }
      }
    },
    // the properties passed to Model.extend(name, properties, options)
    "properties": {
      "id": {"id": true},
      "name": "String",
      "zip": "Number",
      "address": "String"
    }
  },
  "car": {
    "dataSource": "my-db"
    "properties": {
      "id": {
        "type": "String",
        "required": true,
        "id": true
      },
      "make": {
        "type": "String",
        "required": true
      },
      "model": {
        "type": "String",
        "required": true
      }
    }
  }
}
Arguments
Name Type Description
options String or Object

Boot options; If String, this is the application root directory; if object, has below properties.

options
Name Type Description
appRootDir String

Directory to use when loading JSON and JavaScript files (optional). Defaults to the current directory (process.cwd()).

models Object

Object containing Model definitions (optional).

dataSources Object

Object containing DataSource definitions (optional).

app.connector(name, connector)

Register a connector.

When a new data-source is being added via app.dataSource, the connector name is looked up in the registered connectors first.

Connectors are required to be explicitly registered only for applications using browserify, because browserify does not support dynamic require, which is used by LoopBack to automatically load the connector module.

Arguments
Name Type Description
name String

Name of the connector, e.g. 'mysql'.

connector Object

Connector object as returned by require('loopback-connector-{name}').

app.dataSource(name, config)

Define a DataSource.

Arguments
Name Type Description
name String

The data source name

config Object

The data source config

app.docs()

Enable swagger REST API documentation.

Note: This method is deprecated. Use loopback-explorer instead.

Options

Example

// enable docs
app.docs({basePath: 'http://localhost:3000'});

Run your app then navigate to the API explorer. Enter your API basepath to view your generated docs.

app.enableAuth()

Enable app wide authentication.

app.listen(cb)

Listen for connections and update the configured port.

When there are no parameters or there is only one callback parameter, the server will listen on app.get('host') and app.get('port').

// listen on host/port configured in app config
app.listen();

Otherwise all arguments are forwarded to http.Server.listen.

// listen on the specified port and all hosts, ignore app config
app.listen(80);

The function also installs a listening callback that calls app.set('port') with the value returned by server.address().port. This way the port param contains always the real port number, even when listen was called with port number 0.

Arguments
Name Type Description
cb Function

If specified, the callback is added as a listener for the server's "listening" event.

Returns
Name Type Description
result http.Server

A node http.Server with this application configured as the request handler.

app.model(Model, config)

Attach a model to the app. The Model will be available on the app.models object.

// Attach an existing model
var User = loopback.User;
app.model(User);

// Attach an existing model, alter some aspects of the model
var User = loopback.User;
app.model(User, { dataSource: 'db' });

// The old way: create and attach a new model (deprecated)
var Widget = app.model('Widget', {
  dataSource: 'db',
  properties: {
    name: 'string'
  }
});
Arguments
Name Type Description
Model Object or String

The model to attach.

config Object

The model's configuration.

config
Name Type Description
dataSource String or DataSource

The DataSource to which to attach the model.

[public] Boolean

whether the model should be exposed via REST API

[relations] Object

relations to add/update

Returns
Name Type Description
result ModelConstructor

the model class

app.models()

Get the models exported by the app. Returns only models defined using app.model()

Deprecated. Use the package loopback-boot instead.

There are two ways to access models:

  1. Call app.models() to get a list of all models.
var models = app.models();

models.forEach(function (Model) {
 console.log(Model.modelName); // color
});

**2. Use app.model to access a model by name. app.model has properties for all defined models.

The following example illustrates accessing the Product and CustomerReceipt models using the models object.

var loopback = require('loopback');
 var app = loopback();
 app.boot({
  dataSources: {
    db: {connector: 'memory'}
  }
});

app.model('product', {dataSource: 'db'});
app.model('customer-receipt', {dataSource: 'db'});

// available based on the given name
var Product = app.models.Product;

// also available as camelCase
var product = app.models.product;

// multi-word models are avaiable as pascal cased
var CustomerReceipt = app.models.CustomerReceipt;

// also available as camelCase
var customerReceipt = app.models.customerReceipt;
Returns
Name Type Description
result Array

Array of model classes.

app.remoteObjects()

Get all remote objects.

Returns
Name Type Description
result Object

Remote objects.

app.remotes()

Lazily load a set of remote objects.

NOTE: Calling app.remotes() more than once returns only a single set of remote objects.

Returns
Name Type Description
result RemoteObjects

Class: loopback

loopback

Main entry for LoopBack core module. It provides static properties and methods to create models and data sources. The module itself is a function that creates loopback app. For example,

var loopback = require('loopback');
var app = loopback();

Class: loopback Static Methods

loopback.remoteMethod(fn, options)

Add a remote method to a model.

Arguments
Name Type Description
fn Function
options Object

(optional)

loopback.template(path)

Create a template helper.

var render = loopback.template('foo.ejs');
var html = render({foo: 'bar'});
Arguments
Name Type Description
path String

Path to the template file.

Returns
Name Type Description
result Function

loopback.isBrowser

True if running in a browser environment; false otherwise.

loopback.isServer

True if running in a server environment; false otherwise.

loopback.createModel

Create a named vanilla JavaScript class constructor with an attached set of properties and options.

This function comes with two variants:

  • loopback.createModel(name, properties, options)
  • loopback.createModel(config)

In the second variant, the parameters name, properties and options are provided in the config object. Any additional config entries are interpreted as options, i.e. the following two configs are identical:

{ name: 'Customer', base: 'User' }
{ name: 'Customer', options: { base: 'User' } }

Example

Create an Author model using the three-parameter variant:

loopback.createModel(
  'Author',
  {
    firstName: 'string',
    lastName: 'string
  },
  {
    relations: {
      books: {
        model: 'Book',
        type: 'hasAndBelongsToMany'
      }
    }
  }
);

Create the same model using a config object:

loopback.createModel({
  name: 'Author',
  properties: {
    firstName: 'string',
    lastName: 'string
  },
  relations: {
    books: {
      model: 'Book',
      type: 'hasAndBelongsToMany'
    }
  }
});
Arguments
Name Type Description
name String

Unique name.

properties Object
options Object

(optional)

loopback.configureModel(ModelCtor, config)

Alter an existing Model class.

Arguments
Name Type Description
ModelCtor Model

The model constructor to alter.

config Object

Additional configuration to apply

config
Name Type Description
dataSource DataSource

Attach the model to a dataSource.

[relations] Object

Model relations to add/update.

loopback.getModel(modelName)

Look up a model class by name from all models created by loopback.createModel()

Arguments
Name Type Description
modelName String

The model name

Returns
Name Type Description
result Model

The model class

loopback.getModelByType(modelType)

Look up a model class by the base model class. The method can be used by LoopBack to find configured models in models.json over the base model.

Arguments
Name Type Description
modelType Model

The base model class

Returns
Name Type Description
result Model

The subclass if found or the base class

loopback.createDataSource(name, options)

Create a data source with passing the provided options to the connector.

Arguments
Name Type Description
name String

Optional name.

options Object

Data Source options

options
Name Type Description
connector Object

LoopBack connector.

[*]

Other connector properties. See the relevant connector documentation.

loopback.memory()

Get an in-memory data source. Use one if it already exists.

Arguments
Name Type Description
[name] String

The name of the data source. If not provided, the 'default' is used.

loopback.setDefaultDataSourceForType(type, dataSource)

Set the default dataSource for a given type.

Arguments
Name Type Description
type String

The datasource type

dataSource Object or DataSource

The data source settings or instance

Returns
Name Type Description
result DataSource

The data source instance

loopback.getDefaultDataSourceForType()

Get the default dataSource for a given type.

Arguments
Name Type Description
type String

The datasource type

Returns
Name Type Description
result DataSource

The data source instance

loopback.autoAttach()

Attach any model that does not have a dataSource to the default dataSource for the type the Model requests

Base model

Class: Model(data)

The built in loopback.Model.

Arguments
Name Type Description
data Object

Class: Model Static Methods

Model.checkAccess(token, modelId, sharedMethod, callback)

Check if the given access token can invoke the method

Arguments
Name Type Description
token AccessToken

The access token

modelId

The model ID.

sharedMethod SharedMethod

The method in question

callback Function

The callback function

Callback
Name Type Description
err String or Error

The error object

allowed Boolean

True if the request is allowed; false otherwise.

Model.getApp(callback)

Get the Application the Model is attached to.

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error
app Application

Model.remotes(callback)

Get the Model's RemoteObjects.

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error
remoteObjects RemoteObjects

Class: DataModel

DataModel

Extends Model with basic query and CRUD support.

Change Event

Listen for model changes using the change event.

MyDataModel.on('changed', function(obj) {
   console.log(obj) // => the changed model
});
Arguments
Name Type Description
data Object
data.id Number

The default id property

Class: DataModel Static Methods

DataModel.count(where, cb)

Return count of matched records

Arguments
Name Type Description
where Object

search conditions (optional)

cb Function

callback, called with (err, count)

DataModel.create([data], callback)

Create new instance of Model class, saved in database.

Arguments
Name Type Description
[data] Object

Object containing model instance data.

callback Function

Callback function; see below.

Callback
Name Type Description
err Error

Error object

Model Model

instance

DataModel.exists(id, cb)

Check whether a model instance exists in database.

Arguments
Name Type Description
id id

identifier of object (primary key value)

cb Function

callbacl called with (err, exists: Bool)

DataModel.find(params, callback)

Find all instances of Model, matched by query make sure you have marked as index: true fields for filter or sort

Arguments
Name Type Description
params Object

(optional)

  • where: Object { key: val, key2: {gt: 'val2'}}
  • include: String, Object or Array. See DataModel.include documentation.
  • order: String
  • limit: Number
  • skip: Number
callback Function

(required) called with arguments:

  • err (null or Error)
  • Array of instances

DataModel.findById(id, cb)

Find object by id

Arguments
Name Type Description
id

primary key value

cb Function

callback called with (err, instance)

DataModel.findOne(params, cb)

Find one record, same as all, limited by 1 and return object, not collection

Arguments
Name Type Description
params Object

search conditions: {where: {test: 'me'}}

cb Function

callback called with (err, instance)

DataModel.findOrCreate(query, data, cb)

Find one record instance, same as all, limited by one and return object, not collection. If not found, create the record using data provided as second argument.

Arguments
Name Type Description
query Object

search conditions: {where: {test: 'me'}}.

data Object

object to create.

cb Function

callback called with (err, instance)

DataModel.getIdName()

Get the id property name

DataModel.remove([where], [cb])

Destroy all matching records

Arguments
Name Type Description
[where] Object

An object that defines the criteria

[cb] Function

callback called with (err)

DataModel.removeById(id, cb)

Destroy a record by id

Arguments
Name Type Description
id

The id value

cb Function

callback called with (err)

DataModel.upsert(data, [callback])

Update or insert a model instance

Arguments
Name Type Description
data Object

The model instance data

[callback] Function

The callback function

Class: DataModel Instance Methods

dataModel.getIdName()

Get the id property name of the constructor.

dataModel.isNewRecord()

Determine if the data model is new.

Returns
Name Type Description
result Boolean

True if data model is new.

dataModel.reload(callback)

Reload object from persistence

Arguments
Name Type Description
callback Function

Callback function

Callback
Name Type Description
err Error
instance Object

dataModel.save(Options, callback)

Save instance. When instance does not have an ID, create method instead. Triggers: validate, save, update or create.

Arguments
Name Type Description
Options [options]
callback Function

Callback function.

Options
Name Type Description
validate Boolean

Whether to validate.

throws Boolean
Callback
Name Type Description
err Error

Error object

Object

dataModel.setId(val)

Set the corret id property for the DataModel. If a Connector defines a setId method it will be used. Otherwise the default lookup is used. You should override this method to handle complex ids.

Arguments
Name Type Description
val

The id value. Will be converted to the type the id property specifies.

dataModel.updateAttribute(name, value, callback)

Update single attribute. Equivalent to updateAttributes({name: value}, cb)

Arguments
Name Type Description
name String

name of property

value Mixed

value of property

callback Function

callback called with (err, instance)

dataModel.updateAttributes(data, callback)

Update set of attributes

Performs validation before updating

Arguments
Name Type Description
data Object

data to update

callback Function

callback called with (err, instance)

Middleware

loopback.rest()

Expose models over REST.

For example:

app.use(loopback.rest());

For more information, see Exposing models over a REST API.

loopback.status()

Return HTTP response with basic application status information: date the application was started and uptime, in JSON format. For example:

{
 "started": "2014-06-05T00:26:49.750Z",
 "uptime": 9.394
}

loopback.token([options])

Check for an access token in cookies, headers, and query string parameters. This function always checks for the following:

  • access_token
  • X-Access-Token
  • authorization

It checks for these values in cookies, headers, and query string parameters in addition to the items specified in the options parameter.

NOTE: This function only checks for signed cookies.

The following example illustrates how to check for an accessToken in a custom cookie, query string parameter and header called foo-auth.

app.use(loopback.token({
  cookies: ['foo-auth'],
  headers: ['foo-auth', 'X-Foo-Auth'],
  params: ['foo-auth', 'foo_auth']
}));
Arguments
Name Type Description
[options] Object

Each option array is used to add additional keys to find an accessToken for a request.

[options]
Name Type Description
[cookies] Array

Array of cookie names.

[headers] Array

Array of header names.

[params] Array

Array of param names.

[model] Array

An AccessToken object to use.

loopback.urlNotFound()

Convert any request not handled so far to a 404 error to be handled by error-handling middleware.

Built-in models

Class: AccessToken

Token based authentication and access control.

Class Properties
Name Type Description
id

{String} Generated token ID

ttl

{Number} Time to live

created

{Date} When the token was created Default ACLs

  • DENY EVERYONE *
  • ALLOW EVERYONE create

Class: AccessToken Static Methods

AccessToken.createAccessTokenId(callback)

Create a cryptographically random access token id.

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error
token String

AccessToken.findForRequest(req, [options], callback)

Find a token for the given ServerRequest.

Arguments
Name Type Description
req ServerRequest
[options] Object

Options for finding the token

callback Function
Callback
Name Type Description
err Error
token AccessToken

Class: AccessToken Instance Methods

accessToken.validate(callback)

Validate the token.

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error
isValid Boolean

accessType

Name of the access type - READ/WRITE/EXEC

Class Properties
Name Type Description
accessType

{String} Name of the access type - READ/WRITE/EXEC

permission

ALARM - Generate an alarm, in a system dependent way, the access specified in the permissions component of the ACL entry. ALLOW - Explicitly grants access to the resource. AUDIT - Log, in a system dependent way, the access specified in the permissions component of the ACL entry. DENY - Explicitly denies access to the resource.

principalType

Type of the principal - Application/User/Role

principalId

Id of the principal - such as appId, userId or roleId

Class: ACL

A Model for access control meta data.

Class: ACL Static Methods

ACL.checkAccessForContext(context, callback)

Check if the request has the permission to access.

Arguments
Name Type Description
context Object

See below.

callback Function

Callback function

context
Name Type Description
principals Array.<Object>

An array of principals.

model String or Model

The model name or model class.

id

The model instance ID.

property String

The property/method/relation name.

accessType String

The access type: READE, WRITE, or EXEC.

ACL.checkAccessForToken(token, model, modelId, method, callback)

Check if the given access token can invoke the method

Arguments
Name Type Description
token AccessToken

The access token

model String

The model name

modelId

The model id

method String

The method name

callback Function

Callback function

Callback
Name Type Description
err String or Error

The error object

allowed Boolean

is the request allowed

ACL.checkPermission(principalType, principalId, model, property, accessType, callback)

Check if the given principal is allowed to access the model/property

Arguments
Name Type Description
principalType String

The principal type.

principalId String

The principal ID.

model String

The model name.

property String

The property/method/relation name.

accessType String

The access type.

callback Function

Callback function.

Callback
Name Type Description
err String or Error

The error object

result AccessRequest

The access permission

ACL.getMatchingScore(rule, req)

Calculate the matching score for the given rule and request

Arguments
Name Type Description
rule ACL

The ACL entry

req AccessRequest

The request

Returns
Name Type Description
result Number

Class: ACL Instance Methods

aCL.score(req)

Get matching score for the given AccessRequest.

Arguments
Name Type Description
req AccessRequest

The request

Returns
Name Type Description
result Number

score

Class: Scope

Resource owner grants/delegates permissions to client applications

For a protected resource, does the client application have the authorization from the resource owner (user or system)?

Scope has many resource access entries

Class: Scope Static Methods

Scope.checkPermission(scope, model, property, accessType, callback)

Check if the given scope is allowed to access the model/property

Arguments
Name Type Description
scope String

The scope name

model String

The model name

property String

The property/method/relation name

accessType String

The access type

callback Function
Callback
Name Type Description
err String or Error

The error object

result AccessRequest

The access permission

production

production or development mode. It denotes what default APNS servers to be used to send notifications

  • true (production mode)
    • push: gateway.push.apple.com:2195
    • feedback: feedback.push.apple.com:2196
  • false (development mode, the default)
    • push: gateway.sandbox.push.apple.com:2195
    • feedback: feedback.sandbox.push.apple.com:2196

Class: Application

Manage client applications and organize their users.

Class: Application Static Methods

Application.authenticate(appId, key, callback)

Authenticate the application id and key.

matched parameter is one of:

  • clientKey
  • javaScriptKey
  • restApiKey
  • windowsKey
  • masterKey
Arguments
Name Type Description
appId Any
key String
callback Function
Callback
Name Type Description
err Error
matched String

The matching key

Application.register(owner, name, options, callback)

Register a new application

Arguments
Name Type Description
owner String

Owner's user ID.

name String

Name of the application

options Object

Other options

callback Function

Callback function

Application.resetKeys(appId, callback)

Reset keys for a given application by the appId

Arguments
Name Type Description
appId Any
callback Function
Callback
Name Type Description
err Error

Class: Application Instance Methods

application.resetKeys(callback)

Reset keys for the application instance

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error

Class: Email

The Email Model.

Properties

  • to - String (required)
  • from - String (required)
  • subject - String (required)
  • text - String
  • html - String

Class: Email Instance Methods

email.send(options, callback)

Send an email with the given options.

Example Options:

{
  from: "Fred Foo <foo@blurdybloop.com>", // sender address
  to: "bar@blurdybloop.com, baz@blurdybloop.com", // list of receivers
  subject: "Hello", // Subject line
  text: "Hello world", // plaintext body
  html: "<b>Hello world</b>" // html body
}

See https://github.com/andris9/Nodemailer for other supported options.

Arguments
Name Type Description
options Object

See below

callback Function

Called after the e-mail is sent or the sending failed

options
Name Type Description
from String

Senders's email address

to String

List of one or more recipient email addresses (comma-delimited)

subject String

Subject line

text String

Body text

html String

Body HTML (optional)

Class: Role

The Role Model

Class: Role Static Methods

Role.getRoles(context, callback, callback)

List roles for a given principal

Arguments
Name Type Description
context Object

The security context

callback Function
callback Function
Callback
Name Type Description
err
An Array.<String>

array of role ids

Role.isAuthenticated(context, callback)

Check if the user id is authenticated

Arguments
Name Type Description
context Object

The security context

callback Function
Callback
Name Type Description
err Error
isAuthenticated Boolean

Role.isInRole(role, context, callback)

Check if a given principal is in the role

Arguments
Name Type Description
role String

The role name

context Object

The context object

callback Function
Callback
Name Type Description
err Error
isInRole Boolean

Role.isOwner(modelClass, modelId, {*) userId The user id, callback)

Check if a given userId is the owner the model instance

Arguments
Name Type Description
modelClass Function

The model class

modelId

The model id

{*) userId The user id
callback Function

Role.registerResolver(role, resolver)

Add custom handler for roles

Arguments
Name Type Description
role
resolver

The resolver function decides if a principal is in the role dynamically

function(role, context, callback)

Class: RoleMapping

The RoleMapping model extends from the built in loopback.Model type.

Class: RoleMapping Instance Methods

roleMapping.application(callback)

Get the application principal

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error
application Application

roleMapping.childRole(callback)

Get the child role principal

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error
childUser User

roleMapping.user(callback)

Get the user principal

Arguments
Name Type Description
callback Function
Callback
Name Type Description
err Error
user User

status

factors: [ 'AuthenticationFactor' ],

Class: User

Extends from the built in loopback.Model type.

Default User ACLs.

  • DENY EVERYONE *
  • ALLOW EVERYONE create
  • ALLOW OWNER removeById
  • ALLOW EVERYONE login
  • ALLOW EVERYONE logout
  • ALLOW EVERYONE findById
  • ALLOW OWNER updateAttributes

Class: User Static Methods

User.confirm(userId, token, redirect, callback)

Confirm the user's identity.

Arguments
Name Type Description
userId Any
token String

The validation token

redirect String

URL to redirect the user to once confirmed

callback Function
Callback
Name Type Description
err Error

User.login(credentials, callback)

Login a user by with the given credentials.

   User.login({username: 'foo', password: 'bar'}, function (err, token) {
     console.log(token.id);
   });
Arguments
Name Type Description
credentials Object
callback Function
Callback
Name Type Description
err Error
token AccessToken

User.logout(accessTokenID, callback)

Logout a user with the given accessToken id.

   User.logout('asd0a9f8dsj9s0s3223mk', function (err) {
     console.log(err || 'Logged out');
   });
Arguments
Name Type Description
accessTokenID String
callback Function
Callback
Name Type Description
err Error

User.resetPassword(options, callback)

Create a short lived acess token for temporary login. Allows users to change passwords if forgotten.

Arguments
Name Type Description
options Object
callback Function
options
Name Type Description
email String

The user's email address

Callback
Name Type Description
err Error

Class: User Instance Methods

user.createAccessToken([Number} ttl The requested ttl, err, token)

Create access token for the logged in user. This method can be overridden to customize how access tokens are generated

Arguments
Name Type Description
[Number} ttl The requested ttl
err String or Error

The error string or object

token AccessToken

The generated access token object

user.hasPassword(password)

Compare the given password with the users hashed password.

Arguments
Name Type Description
password String

The plain text password

Returns
Name Type Description
result Boolean

user.verify(options)

Verify a user's identity by sending them a confirmation email.

   var options = {
     type: 'email',
     to: user.email,
     template: 'verify.ejs',
     redirect: '/'
   };

   user.verify(options, next);
Arguments
Name Type Description
options Object