loopback-datasource-juggler/lib/model-builder.js

712 lines
21 KiB
JavaScript

/*!
* Module dependencies
*/
var inflection = require('inflection');
var EventEmitter = require('events').EventEmitter;
var util = require('util');
var assert = require('assert');
var DefaultModelBaseClass = require('./model.js');
var List = require('./list.js');
var ModelDefinition = require('./model-definition.js');
var mergeSettings = require('./utils').mergeSettings;
var MixinProvider = require('./mixins');
// Set up types
require('./types')(ModelBuilder);
var introspect = require('./introspection')(ModelBuilder);
/*!
* Export public API
*/
exports.ModelBuilder = exports.Schema = ModelBuilder;
/*!
* Helpers
*/
var slice = Array.prototype.slice;
/**
* ModelBuilder - A builder to define data models.
*
* @property {Object} definitions Definitions of the models.
* @property {Object} models Model constructors
* @class
*/
function ModelBuilder() {
// create blank models pool
this.models = {};
this.definitions = {};
this.mixins = new MixinProvider(this);
this.defaultModelBaseClass = DefaultModelBaseClass;
}
// Inherit from EventEmitter
util.inherits(ModelBuilder, EventEmitter);
// Create a default instance
ModelBuilder.defaultInstance = new ModelBuilder();
function isModelClass(cls) {
if (!cls) {
return false;
}
return cls.prototype instanceof DefaultModelBaseClass;
}
/**
* Get a model by name.
*
* @param {String} name The model name
* @param {Boolean} forceCreate Whether the create a stub for the given name if a model doesn't exist.
* @returns {*} The model class
*/
ModelBuilder.prototype.getModel = function (name, forceCreate) {
var model = this.models[name];
if (!model && forceCreate) {
model = this.define(name, {}, {unresolved: true});
}
return model;
};
/**
* Get the model definition by name
* @param {String} name The model name
* @returns {ModelDefinition} The model definition
*/
ModelBuilder.prototype.getModelDefinition = function (name) {
return this.definitions[name];
};
/**
* 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 }
* });
* ```
*
* @param {String} className Name of class
* @param {Object} properties Hash of class properties in format `{property: Type, property2: Type2, ...}` or `{property: {type: Type}, property2: {type: Type2}, ...}`
* @param {Object} settings Other configuration of class
* @return newly created class
*
*/
ModelBuilder.prototype.define = function defineClass(className, properties, settings, parent) {
var modelBuilder = this;
var args = slice.call(arguments);
var pluralName = (settings && settings.plural) ||
inflection.pluralize(className);
var httpOptions = (settings && settings.http) || {};
var pathName = httpOptions.path || pluralName;
if (!className) {
throw new Error('Class name required');
}
if (args.length === 1) {
properties = {};
args.push(properties);
}
if (args.length === 2) {
settings = {};
args.push(settings);
}
properties = properties || {};
settings = settings || {};
// Set the strict mode to be false by default
if (settings.strict === undefined || settings.strict === null) {
settings.strict = false;
}
// Set up the base model class
var ModelBaseClass = parent || this.defaultModelBaseClass;
var baseClass = settings.base || settings['super'];
if (baseClass) {
// Normalize base model property
settings.base = baseClass;
delete settings['super'];
if (isModelClass(baseClass)) {
ModelBaseClass = baseClass;
} else {
ModelBaseClass = this.models[baseClass];
assert(ModelBaseClass, 'Base model is not found: ' + baseClass);
}
}
// Check if there is a unresolved model with the same name
var ModelClass = this.models[className];
// Create the ModelClass if it doesn't exist or it's resolved (override)
// TODO: [rfeng] We need to decide what names to use for built-in models such as User.
if (!ModelClass || !ModelClass.settings.unresolved) {
// every class can receive hash of data as optional param
ModelClass = function ModelConstructor(data, options) {
if (!(this instanceof ModelConstructor)) {
return new ModelConstructor(data, options);
}
if (ModelClass.settings.unresolved) {
throw new Error('Model ' + ModelClass.modelName + ' is not defined.');
}
ModelBaseClass.apply(this, arguments);
};
// mix in EventEmitter (don't inherit from)
var events = new EventEmitter();
// The model can have more than 10 listeners for lazy relationship setup
// See https://github.com/strongloop/loopback/issues/404
events.setMaxListeners(32);
for (var f in EventEmitter.prototype) {
if (typeof EventEmitter.prototype[f] === 'function') {
ModelClass[f] = EventEmitter.prototype[f].bind(events);
}
}
hiddenProperty(ModelClass, 'modelName', className);
}
util.inherits(ModelClass, ModelBaseClass);
// store class in model pool
this.models[className] = ModelClass;
// Return the unresolved model
if (settings.unresolved) {
ModelClass.settings = {unresolved: true};
return ModelClass;
}
// Add metadata to the ModelClass
hiddenProperty(ModelClass, 'modelBuilder', modelBuilder);
hiddenProperty(ModelClass, 'dataSource', null); // Keep for back-compatibility
hiddenProperty(ModelClass, 'pluralModelName', pluralName);
hiddenProperty(ModelClass, 'relations', {});
hiddenProperty(ModelClass, 'http', { path: '/' + pathName });
hiddenProperty(ModelClass, 'base', ModelBaseClass);
// inherit ModelBaseClass static methods
for (var i in ModelBaseClass) {
// We need to skip properties that are already in the subclass, for example, the event emitter methods
if (i !== '_mixins' && !(i in ModelClass)) {
ModelClass[i] = ModelBaseClass[i];
}
}
// Load and inject the model classes
if (settings.models) {
Object.keys(settings.models).forEach(function (m) {
var model = settings.models[m];
ModelClass[m] = typeof model === 'string' ? modelBuilder.getModel(model, true) : model;
});
}
ModelClass.getter = {};
ModelClass.setter = {};
var modelDefinition = new ModelDefinition(this, className, properties, settings);
this.definitions[className] = modelDefinition;
// expose properties on the ModelClass
ModelClass.definition = modelDefinition;
// keep a pointer to settings as models can use it for configuration
ModelClass.settings = modelDefinition.settings;
var idInjection = settings.idInjection;
if (idInjection !== false) {
// Default to true if undefined
idInjection = true;
}
var idNames = modelDefinition.idNames();
if (idNames.length > 0) {
// id already exists
idInjection = false;
}
// Add the id property
if (idInjection) {
// Set up the id property
ModelClass.definition.defineProperty('id', { type: Number, id: 1, generated: true });
}
idNames = modelDefinition.idNames(); // Reload it after rebuild
// Create a virtual property 'id'
if (idNames.length === 1) {
var idProp = idNames[0];
if (idProp !== 'id') {
Object.defineProperty(ModelClass.prototype, 'id', {
get: function () {
var idProp = ModelClass.definition.idNames[0];
return this.__data[idProp];
},
configurable: true,
enumerable: false
});
}
} else {
// Now the id property is an object that consists of multiple keys
Object.defineProperty(ModelClass.prototype, 'id', {
get: function () {
var compositeId = {};
var idNames = ModelClass.definition.idNames();
for (var p in idNames) {
compositeId[p] = this.__data[p];
}
return compositeId;
},
configurable: true,
enumerable: false
});
}
// A function to loop through the properties
ModelClass.forEachProperty = function (cb) {
var props = ModelClass.definition.properties;
var keys = Object.keys(props);
for (var i = 0, n = keys.length; i < n; i++) {
cb(keys[i], props[keys[i]]);
}
};
// A function to attach the model class to a data source
ModelClass.attachTo = function (dataSource) {
dataSource.attach(this);
};
/** Extend the model with the specified model, properties, and other settings.
* For example, to extend an existing model, for example, a built-in model:
*
* ```js
* var Customer = User.extend('customer', {
* accountId: String,
* vip: Boolean
* });
* ```
*
* To extend the base model, essentially creating a new model:
* ```js
* var user = loopback.Model.extend('user', properties, options);
* ```
*
* @param {String} className Name of the new model being defined.
* @options {Object} properties Properties to define for the model, added to properties of model being extended.
* @options {Object} settings Model settings, such as relations and acls.
*
*/
ModelClass.extend = function (className, subclassProperties, subclassSettings) {
var properties = ModelClass.definition.properties;
var settings = ModelClass.definition.settings;
subclassProperties = subclassProperties || {};
subclassSettings = subclassSettings || {};
// Check if subclass redefines the ids
var idFound = false;
for (var k in subclassProperties) {
if (subclassProperties[k].id) {
idFound = true;
break;
}
}
// Merging the properties
var keys = Object.keys(properties);
for (var i = 0, n = keys.length; i < n; i++) {
var key = keys[i];
if (idFound && properties[key].id) {
// don't inherit id properties
continue;
}
if (subclassProperties[key] === undefined) {
subclassProperties[key] = properties[key];
}
}
// Merge the settings
var originalSubclassSettings = subclassSettings;
subclassSettings = mergeSettings(settings, subclassSettings);
// Ensure 'base' is not inherited. Note we don't have to delete 'super'
// as that is removed from settings by modelBuilder.define and thus
// it is never inherited
if (!originalSubclassSettings.base)
delete subclassSettings.base;
// Define the subclass
var subClass = modelBuilder.define(className, subclassProperties, subclassSettings, ModelClass);
// Calling the setup function
if (typeof subClass.setup === 'function') {
subClass.setup.call(subClass);
}
return subClass;
};
/**
* Register a property for the model class
* @param {String} propertyName Name of the property.
*/
ModelClass.registerProperty = function (propertyName) {
var properties = modelDefinition.build();
var prop = properties[propertyName];
var DataType = prop.type;
if (!DataType) {
throw new Error('Invalid type for property ' + propertyName);
}
if (prop.required) {
var requiredOptions = typeof prop.required === 'object' ? prop.required : undefined;
ModelClass.validatesPresenceOf(propertyName, requiredOptions);
}
Object.defineProperty(ModelClass.prototype, propertyName, {
get: function () {
if (ModelClass.getter[propertyName]) {
return ModelClass.getter[propertyName].call(this); // Try getter first
} else {
return this.__data && this.__data[propertyName]; // Try __data
}
},
set: function (value) {
var DataType = ModelClass.definition.properties[propertyName].type;
if (Array.isArray(DataType) || DataType === Array) {
DataType = List;
} else if (DataType === Date) {
DataType = DateType;
} else if (typeof DataType === 'string') {
DataType = modelBuilder.resolveType(DataType);
}
if (ModelClass.setter[propertyName]) {
ModelClass.setter[propertyName].call(this, value); // Try setter first
} else {
this.__data = this.__data || {};
if (value === null || value === undefined) {
this.__data[propertyName] = value;
} else {
if (DataType === List) {
this.__data[propertyName] = DataType(value, properties[propertyName].type, this.__data);
} else {
// Assume the type constructor handles Constructor() call
// If not, we should call new DataType(value).valueOf();
this.__data[propertyName] = (value instanceof DataType) ? value : DataType(value);
}
}
}
},
configurable: true,
enumerable: true
});
// FIXME: [rfeng] Do we need to keep the raw data?
// Use $ as the prefix to avoid conflicts with properties such as _id
Object.defineProperty(ModelClass.prototype, '$' + propertyName, {
get: function () {
return this.__data && this.__data[propertyName];
},
set: function (value) {
if (!this.__data) {
this.__data = {};
}
this.__data[propertyName] = value;
},
configurable: true,
enumerable: false
});
};
var props = ModelClass.definition.properties;
var keys = Object.keys(props);
var size = keys.length;
for (i = 0; i < size; i++) {
var propertyName = keys[i];
ModelClass.registerProperty(propertyName);
}
var mixinSettings = settings.mixins || {};
keys = Object.keys(mixinSettings);
size = keys.length;
for (i = 0; i < size; i++) {
var name = keys[i];
var mixin = mixinSettings[name];
if (mixin === true) {
mixin = {};
}
if (Array.isArray(mixin)) {
mixin.forEach(function(m) {
if (m === true) m = {};
if (typeof m === 'object') {
modelBuilder.mixins.applyMixin(ModelClass, name, m);
}
});
} else if (typeof mixin === 'object') {
modelBuilder.mixins.applyMixin(ModelClass, name, mixin);
}
}
ModelClass.emit('defined', ModelClass);
return ModelClass;
};
// DataType for Date
function DateType(arg) {
return new Date(arg);
}
/**
* Define single property named `propertyName` on `model`
*
* @param {String} model Name of model
* @param {String} propertyName Name of property
* @param {Object} propertyDefinition Property settings
*/
ModelBuilder.prototype.defineProperty = function (model, propertyName, propertyDefinition) {
this.definitions[model].defineProperty(propertyName, propertyDefinition);
this.models[model].registerProperty(propertyName);
};
/**
* Define a new value type that can be used in model schemas as a property type.
* @param {function()} type Type constructor.
* @param {string[]=} aliases Optional list of alternative names for this type.
*/
ModelBuilder.prototype.defineValueType = function(type, aliases) {
ModelBuilder.registerType(type, aliases);
};
/**
* Extend existing model with specified properties
*
* Example:
* Instead of extending a model with attributes like this (for example):
*
* ```js
* 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):
* ```js
* db.extendModel('Content', {
* competitionType: String,
* expiryDate: { type: Date, index: true },
* isExpired: { type: Boolean, index: true }
* });
*```
*
* @param {String} model Name of model
* @options {Object} properties JSON object specifying properties. Each property is a key whos value is
* either the [type](http://docs.strongloop.com/display/LB/LoopBack+types) or `propertyName: {options}`
* where the options are described below.
* @property {String} type Datatype of property: Must be an [LDL type](http://docs.strongloop.com/display/LB/LoopBack+types).
* @property {Boolean} index True if the property is an index; false otherwise.
*/
ModelBuilder.prototype.extendModel = function (model, props) {
var t = this;
var keys = Object.keys(props);
for (var i = 0; i < keys.length; i++) {
var definition = props[keys[i]];
t.defineProperty(model, keys[i], definition);
}
};
ModelBuilder.prototype.copyModel = function copyModel(Master) {
var modelBuilder = this;
var className = Master.modelName;
var md = Master.modelBuilder.definitions[className];
var Slave = function SlaveModel() {
Master.apply(this, [].slice.call(arguments));
};
util.inherits(Slave, Master);
Slave.__proto__ = Master;
hiddenProperty(Slave, 'modelBuilder', modelBuilder);
hiddenProperty(Slave, 'modelName', className);
hiddenProperty(Slave, 'relations', Master.relations);
if (!(className in modelBuilder.models)) {
// store class in model pool
modelBuilder.models[className] = Slave;
modelBuilder.definitions[className] = {
properties: md.properties,
settings: md.settings
};
}
return Slave;
};
/*!
* Define hidden property
*/
function hiddenProperty(where, property, value) {
Object.defineProperty(where, property, {
writable: true,
enumerable: false,
configurable: true,
value: value
});
}
/**
* Get the schema name
*/
ModelBuilder.prototype.getSchemaName = function (name) {
if (name) {
return name;
}
if (typeof this._nameCount !== 'number') {
this._nameCount = 0;
} else {
this._nameCount++;
}
return 'AnonymousModel_' + this._nameCount;
};
/**
* Resolve the type string to be a function, for example, 'String' to String.
* Returns {Function} if the type is resolved
* @param {String} type The type string, such as 'number', 'Number', 'boolean', or 'String'. It's case insensitive
*/
ModelBuilder.prototype.resolveType = function (type) {
if (!type) {
return type;
}
if (Array.isArray(type) && type.length > 0) {
// For array types, the first item should be the type string
var itemType = this.resolveType(type[0]);
if (typeof itemType === 'function') {
return [itemType];
}
else {
return itemType; // Not resolved, return the type string
}
}
if (typeof type === 'string') {
var schemaType = ModelBuilder.schemaTypes[type.toLowerCase()] || this.models[type];
if (schemaType) {
return schemaType;
} else {
// The type cannot be resolved, let's create a place holder
type = this.define(type, {}, {unresolved: true});
return type;
}
} else if (type.constructor.name === 'Object') {
// We also support the syntax {type: 'string', ...}
if (type.type) {
return this.resolveType(type.type);
} else {
return this.define(this.getSchemaName(null),
type, {anonymous: true, idInjection: false});
}
} else if ('function' === typeof type) {
return type;
}
return type;
};
/**
* 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)
*
* @param {*} schemas The schemas
* @returns {Object} A map of model constructors keyed by model name
*/
ModelBuilder.prototype.buildModels = function (schemas, createModel) {
var models = {};
// Normalize the schemas to be an array of the schema objects {name: <name>, properties: {}, options: {}}
if (!Array.isArray(schemas)) {
if (schemas.properties && schemas.name) {
// Only one item
schemas = [schemas];
} else {
// Anonymous schema
schemas = [
{
name: this.getSchemaName(),
properties: schemas,
options: {anonymous: true}
}
];
}
}
var relations = [];
for (var s in schemas) {
var name = this.getSchemaName(schemas[s].name);
schemas[s].name = name;
var model;
if(typeof createModel === 'function') {
model = createModel(schemas[s].name, schemas[s].properties, schemas[s].options);
} else {
model = this.define(schemas[s].name, schemas[s].properties, schemas[s].options);
}
models[name] = model;
relations = relations.concat(model.definition.relations);
}
// Connect the models based on the relations
for (var i = 0; i < relations.length; i++) {
var relation = relations[i];
var sourceModel = models[relation.source];
var targetModel = models[relation.target];
if (sourceModel && targetModel) {
if (typeof sourceModel[relation.type] === 'function') {
sourceModel[relation.type](targetModel, {as: relation.as});
}
}
}
return models;
};
/**
* Introspect the JSON document to build a corresponding model.
* @param {String} name The model name
* @param {Object} json The JSON object
* @param {Object} options The options
* @returns {}
*/
ModelBuilder.prototype.buildModelFromInstance = function (name, json, options) {
// Introspect the JSON document to generate a schema
var schema = introspect(json);
// Create a model for the generated schema
return this.define(name, schema, options);
};