AbstractClass

Abstract class - base class for all persist objects +provides common API to access any database adapter. +This class describes only abstract behavior layer, refer to lib/adapters/*.js +to learn more about specific adapter implementations

+ +

AbstractClass mixes Validatable and Hookable classes methods

+ +

constructor +
param Object data - initial object data

Source code

function AbstractClass(data) {
+    var self = this;
+    var ds = this.constructor.schema.definitions[this.constructor.modelName];
+    var properties = ds.properties;
+    var settings = ds.setings;
+    data = data || {};
+
+    if (data.id) {
+        defineReadonlyProp(this, 'id', data.id);
+    }
+
+    Object.defineProperty(this, 'cachedRelations', {
+        writable: true,
+        enumerable: false,
+        configurable: true,
+        value: {}
+    });
+
+    Object.keys(properties).forEach(function (attr) {
+        var _attr    = '_' + attr,
+            attr_was = attr + '_was';
+
+        // Hidden property to store currrent value
+        Object.defineProperty(this, _attr, {
+            writable: true,
+            enumerable: false,
+            configurable: true,
+            value: isdef(data[attr]) ? data[attr] :
+            (isdef(this[attr]) ? this[attr] : (
+                getDefault(attr)
+            ))
+        });
+
+        // Public setters and getters
+        Object.defineProperty(this, attr, {
+            get: function () {
+                if (this.constructor.getter[attr]) {
+                    return this.constructor.getter[attr].call(this);
+                } else {
+                    return this[_attr];
+                }
+            },
+            set: function (value) {
+                if (this.constructor.setter[attr]) {
+                    this.constructor.setter[attr].call(this, value);
+                } else {
+                    this[_attr] = value;
+                }
+            },
+            configurable: true,
+            enumerable: true
+        });
+
+        if (data.hasOwnProperty(attr)) {
+            // Getter for initial property
+            Object.defineProperty(this, attr_was, {
+                writable: true,
+                value: data[attr],
+                configurable: true,
+                enumerable: false
+            });
+        }
+
+    }.bind(this));
+
+    function getDefault(attr) {
+        var def = properties[attr]['default']
+        if (isdef(def)) {
+            if (typeof def === 'function') {
+                return def();
+            } else {
+                return def;
+            }
+        } else {
+            return null;
+        }
+    }
+
+    this.trigger("initialize");
+};
+

Class methods Instance methods Helper methods

AbstractClass.defineProperty

Declared as function (prop, params)

param String prop - property name +
param Object params - various property configuration

Source code

function (prop, params) {
+    this.schema.defineProperty(this.modelName, prop, params);
+};
+

AbstractClass.create

Declared as function (data, callback)

Create new instance of Model class, saved in database

+ +

param data [optional] +
param callback(err, obj) +callback called with arguments:

+ +

err (null or Error)
instance (null or Model)

Source code

function (data, callback) {
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    var modelName = this.modelName;
+
+    if (typeof data === 'function') {
+        callback = data;
+        data = {};
+    }
+
+    if (typeof callback !== 'function') {
+        callback = function () {};
+    }
+
+    var obj = null;
+    // if we come from save
+    if (data instanceof AbstractClass && !data.id) {
+        obj = data;
+        data = obj.toObject(true);
+        // recall constructor to update _was property states (maybe bad idea)
+        this.call(obj, data);
+        create();
+    } else {
+        obj = new this(data);
+        data = obj.toObject(true);
+
+        // validation required
+        obj.isValid(function (valid) {
+            if (!valid) {
+                callback(new Error('Validation error'), obj);
+            } else {
+                create();
+            }
+        });
+    }
+
+    function create() {
+        obj.trigger('create', function (done) {
+            this._adapter().create(modelName, data, function (err, id) {
+                if (id) {
+                    defineReadonlyProp(obj, 'id', id);
+                    addToCache(this.constructor, obj);
+                }
+                done.call(this, function () {
+                    if (callback) {
+                        callback(err, obj);
+                    }
+                });
+            }.bind(this));
+        });
+    }
+};
+

AbstractClass.upsert

Declared as AbstractClass.updateOrCreate

Update or insert

Source code

AbstractClass.updateOrCreate{
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    var Model = this;
+    if (!data.id) return this.create(data, callback);
+    if (this.schema.adapter.updateOrCreate) {
+        this.schema.adapter.updateOrCreate(Model.modelName, data, function (err, data) {
+            var obj = data ? new Model(data) : null;
+            if (obj) {
+                addToCache(Model, obj);
+            }
+            callback(err, obj);
+        });
+    } else {
+        this.find(data.id, function (err, inst) {
+            if (err) return callback(err);
+            if (inst) {
+                inst.updateAttributes(data, callback);
+            } else {
+                var obj = new Model(data);
+                obj.save(data, callback);
+            }
+        });
+    }
+};
+

AbstractClass.exists

Declared as function exists(id, cb)

Check whether object exitst in database

+ +

param id id - identifier of object (primary key value) +
param Function cb - callbacl called with (err, exists: Bool)

Source code

function exists(id, cb) {
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    if (id) {
+        this.schema.adapter.exists(this.modelName, id, cb);
+    } else {
+        cb(new Error('Model::exists requires positive id argument'));
+    }
+};
+

AbstractClass.find

Declared as function find(id, cb)

Find object by id

+ +

param id id - primary key value +
param Function cb - callback called with (err, instance)

Source code

function find(id, cb) {
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    this.schema.adapter.find(this.modelName, id, function (err, data) {
+        var obj = null;
+        if (data) {
+            var cached = getCached(this, data.id);
+            if (cached) {
+                obj = cached;
+                substractDirtyAttributes(obj, data);
+                this.call(obj, data);
+            } else {
+                data.id = id;
+                obj = new this(data);
+                addToCache(this, id);
+            }
+        }
+        cb(err, obj);
+    }.bind(this));
+};
+

AbstractClass.all

Declared as function all(params, cb)

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

+ +

param Object params (optional)

+ +

where: Object { key: val, key2: {gt: 'val2'}}
order: String
limit: Number
skip: Number

+ +

param Function callback (required) called with arguments:

+ +

err (null or Error)
Array of instances

Source code

function all(params, cb) {
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    if (arguments.length === 1) {
+        cb = params;
+        params = null;
+    }
+    var constr = this;
+    this.schema.adapter.all(this.modelName, params, function (err, data) {
+        var collection = null;
+        if (data && data.map) {
+            collection = data.map(function (d) {
+                var obj = null;
+                // do not create different instances for the same object
+                var cached = getCached(constr, d.id);
+                if (cached) {
+                    obj = cached;
+                    // keep dirty attributes untouthed (remove from dataset)
+                    substractDirtyAttributes(obj, d);
+                    constr.call(obj, d);
+                } else {
+                    obj = new constr(d);
+                    if (obj.id) addToCache(constr, obj);
+                }
+                return obj;
+            });
+            cb(err, collection);
+        }
+    });
+};
+

AbstractClass.findOne

Declared as function findOne(params, cb)

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

+ +

param Object params - search conditions +
param Function cb - callback called with (err, instance)

Source code

function findOne(params, cb) {
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    if (typeof params === 'function') {
+        cb = params;
+        params = {};
+    }
+    params.limit = 1;
+    this.all(params, function (err, collection) {
+        if (err || !collection || !collection.length > 0) return cb(err);
+        cb(err, collection[0]);
+    });
+};
+

AbstractClass.destroyAll

Declared as function destroyAll(cb)

Destroy all records +
param Function cb - callback called with (err)

Source code

function destroyAll(cb) {
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    this.schema.adapter.destroyAll(this.modelName, function (err) {
+        clearCache(this);
+        cb(err);
+    }.bind(this));
+};
+

AbstractClass.count

Declared as function (where, cb)

Return count of matched records

+ +

param Object where - search conditions (optional) +
param Function cb - callback, called with (err, count)

Source code

function (where, cb) {
+    if (stillConnecting(this.schema, this, arguments)) return;
+
+    if (typeof where === 'function') {
+        cb = where;
+        where = null;
+    }
+    this.schema.adapter.count(this.modelName, cb, where);
+};
+

AbstractClass.toString

Declared as function ()

Return string representation of class

+ +

override default toString method

Source code

function () {
+    return '[Model ' + this.modelName + ']';
+}
+

AbstractClass.hasMany

Declared as function hasMany(anotherClass, params)

Declare hasMany relation

+ +

param Class anotherClass - class to has many +
param Object params - configuration {as:, foreignKey:} +
example User.hasMany(Post, {as: 'posts', foreignKey: 'authorId'});

Source code

function hasMany(anotherClass, params) {
+    var methodName = params.as; // or pluralize(anotherClass.modelName)
+    var fk = params.foreignKey;
+    // each instance of this class should have method named
+    // pluralize(anotherClass.modelName)
+    // which is actually just anotherClass.all({where: {thisModelNameId: this.id}}, cb);
+    defineScope(this.prototype, anotherClass, methodName, function () {
+        var x = {};
+        x[fk] = this.id;
+        return {where: x};
+    }, {
+        find: find,
+        destroy: destroy
+    });
+
+    // obviously, anotherClass should have attribute called `fk`
+    anotherClass.schema.defineForeignKey(anotherClass.modelName, fk);
+
+    function find(id, cb) {
+        anotherClass.find(id, function (err, inst) {
+            if (err) return cb(err);
+            if (inst[fk] === this.id) {
+                cb(null, inst);
+            } else {
+                cb(new Error('Permission denied'));
+            }
+        }.bind(this));
+    }
+
+    function destroy(id, cb) {
+        this.find(id, function (err, inst) {
+            if (err) return cb(err);
+            if (inst) {
+                inst.destroy(cb);
+            } else {
+                cb(new Error('Not found'));
+            }
+        });
+    }
+
+};
+

AbstractClass.belongsTo

Declared as function (anotherClass, params)

Declare belongsTo relation

+ +

param Class anotherClass - class to belong +
param Object params - configuration {as: 'propertyName', foreignKey: 'keyName'}

Source code

function (anotherClass, params) {
+    var methodName = params.as;
+    var fk = params.foreignKey;
+
+    this.schema.defineForeignKey(this.modelName, fk);
+    this.prototype['__finders__'] = this.prototype['__finders__'] || {}
+
+    this.prototype['__finders__'][methodName] = function (id, cb) {
+        anotherClass.find(id, function (err,inst) {
+            if (err) return cb(err);
+            if (inst[fk] === this.id) {
+                cb(null, inst);
+            } else {
+                cb(new Error('Permission denied'));
+            }
+        }.bind(this));
+    }
+
+    this.prototype[methodName] = function (p) {
+        if (p instanceof AbstractClass) { // acts as setter
+            this[fk] = p.id;
+            this.cachedRelations[methodName] = p;
+        } else if (typeof p === 'function') { // acts as async getter
+            this.__finders__[methodName](this[fk], p);
+            return this[fk];
+        } else if (typeof p === 'undefined') { // acts as sync getter
+            return this[fk];
+        } else { // setter
+            this[fk] = p;
+        }
+    };
+
+};
+

AbstractClass.scope

Declared as function (name, params)

Define scope +TODO: describe behavior and usage examples

Source code

function (name, params) {
+    defineScope(this, this, name, params);
+};
+

AbstractClass.prototype.save

Declared as function (options, callback)

Save instance. When instance haven't id, create method called instead. +Triggers: validate, save, update | create +
param options {validate: true, throws: false} [optional] +
param callback(err, obj)

Source code

function (options, callback) {
+    if (stillConnecting(this.constructor.schema, this, arguments)) return;
+
+    if (typeof options == 'function') {
+        callback = options;
+        options = {};
+    }
+
+    callback = callback || function () {};
+    options = options || {};
+
+    if (!('validate' in options)) {
+        options.validate = true;
+    }
+    if (!('throws' in options)) {
+        options.throws = false;
+    }
+
+    if (options.validate) {
+        this.isValid(function (valid) {
+            if (valid) {
+                save.call(this);
+            } else {
+                var err = new Error('Validation error');
+                // throws option is dangerous for async usage
+                if (options.throws) {
+                    throw err;
+                }
+                callback(err, this);
+            }
+        }.bind(this));
+    } else {
+        save.call(this);
+    }
+
+    function save() {
+        this.trigger('save', function (saveDone) {
+            var modelName = this.constructor.modelName;
+            var data = this.toObject(true);
+            var inst = this;
+            if (inst.id) {
+                inst.trigger('update', function (updateDone) {
+                    inst._adapter().save(modelName, data, function (err) {
+                        if (err) {
+                            console.log(err);
+                        } else {
+                            inst.constructor.call(inst, data);
+                        }
+                        updateDone.call(inst, function () {
+                            saveDone.call(inst, function () {
+                                callback(err, inst);
+                            });
+                        });
+                    });
+                });
+            } else {
+                inst.constructor.create(inst, function (err) {
+                    saveDone.call(inst, function () {
+                        callback(err, inst);
+                    });
+                });
+            }
+
+        });
+    }
+};
+

AbstractClass.prototype._adapter

Declared as function ()

Return adapter of current record +
private

Source code

function () {
+    return this.constructor.schema.adapter;
+};
+

AbstractClass.prototype.toObject

Declared as function (onlySchema)

Convert instance to Object

+ +

param Boolean onlySchema - restrict properties to schema only, default false +when onlySchema == true, only properties defined in schema returned, +otherwise all enumerable properties returned +
returns Object - canonical object representation (no getters and setters)

Source code

function (onlySchema) {
+    var data = {};
+    var ds = this.constructor.schema.definitions[this.constructor.modelName];
+    var properties = ds.properties;
+    // weird
+    Object.keys(onlySchema ? properties : this).concat(['id']).forEach(function (property) {
+        data[property] = this[property];
+    }.bind(this));
+    return data;
+};
+

AbstractClass.prototype.destroy

Declared as function (cb)

Delete object from persistence

+ +

triggers destroy hook (async) before and after destroying object

Source code

function (cb) {
+    if (stillConnecting(this.constructor.schema, this, arguments)) return;
+
+    this.trigger('destroy', function (destroyed) {
+        this._adapter().destroy(this.constructor.modelName, this.id, function (err) {
+            removeFromCache(this.constructor, this.id);
+            destroyed(function () {
+                cb && cb(err);
+            });
+        }.bind(this));
+    });
+};
+

AbstractClass.prototype.updateAttribute

Declared as function updateAttribute(name, value, callback)

Update single attribute

+ +

equals to `updateAttributes({name: value}, cb)

+ +

param String name - name of property +
param Mixed value - value of property +
param Function callback - callback called with (err, instance)

Source code

function updateAttribute(name, value, callback) {
+    data = {};
+    data[name] = value;
+    this.updateAttributes(data, callback);
+};
+

AbstractClass.prototype.updateAttributes

Declared as function updateAttributes(data, cb)

Update set of attributes

+ +

this method performs validation before updating

+ +

trigger validation, save and update hooks +
param Object data - data to update +
param Function callback - callback called with (err, instance)

Source code

function updateAttributes(data, cb) {
+    if (stillConnecting(this.constructor.schema, this, arguments)) return;
+
+    var inst = this;
+    var model = this.constructor.modelName;
+
+    // update instance's properties
+    Object.keys(data).forEach(function (key) {
+        inst[key] = data[key];
+    });
+
+    inst.isValid(function (valid) {
+        if (!valid) {
+            if (cb) {
+                cb(new Error('Validation error'));
+            }
+        } else {
+            update();
+        }
+    });
+
+    function update() {
+        inst.trigger('save', function (saveDone) {
+            inst.trigger('update', function (done) {
+
+                Object.keys(data).forEach(function (key) {
+                    data[key] = inst[key];
+                });
+
+                inst._adapter().updateAttributes(model, inst.id, data, function (err) {
+                    if (!err) {
+                        inst.constructor.call(inst, data);
+                        /*
+                        Object.keys(data).forEach(function (key) {
+                            inst[key] = data[key];
+                            Object.defineProperty(inst, key + '_was', {
+                                writable:     false,
+                                configurable: true,
+                                enumerable:   false,
+                                value:        data[key]
+                            });
+                        });
+                        */
+                    }
+                    done.call(inst, function () {
+                        saveDone.call(inst, function () {
+                            cb(err, inst);
+                        });
+                    });
+                });
+            });
+        });
+    }
+};
+

AbstractClass.prototype.propertyChanged

Declared as function propertyChanged(attr)

Checks is property changed based on current property and initial value

+ +

param String attr - property name +
return Boolean

Source code

function propertyChanged(attr) {
+    return this['_' + attr] !== this[attr + '_was'];
+};
+

AbstractClass.prototype.reload

Declared as function reload(callback)

Reload object from persistence

+ +

requires id member of object to be able to call find +
param Function callback - called with (err, instance) arguments

Source code

function reload(callback) {
+    if (stillConnecting(this.constructor.schema, this, arguments)) return;
+
+    var obj = getCached(this.constructor, this.id);
+    if (obj) obj.reset();
+    this.constructor.find(this.id, callback);
+};
+

AbstractClass.prototype.reset

Declared as function ()

Reset dirty attributes

+ +

this method does not perform any database operation it just reset object to it's +initial state

Source code

function () {
+    var obj = this;
+    Object.keys(obj).forEach(function (k) {
+        if (k !== 'id' && !obj.constructor.schema.definitions[obj.constructor.modelName].properties[k]) {
+            delete obj[k];
+        }
+        if (obj.propertyChanged(k)) {
+            obj[k] = obj[k + '_was'];
+        }
+    });
+};
+

isdef

Declared as function isdef(s)

Check whether s is not undefined +
param Mixed s +
return Boolean s is undefined

Source code

function isdef(s) {
+    var undef;
+    return s !== undef;
+}
+

merge

Declared as function merge(base, update)

Merge base and update params +
param Object base - base object (updating this object) +
param Object update - object with new data to update base +
returns Object base

Source code

function merge(base, update) {
+    base = base || {};
+    if (update) {
+        Object.keys(update).forEach(function (key) {
+            base[key] = update[key];
+        });
+    }
+    return base;
+}
+

defineReadonlyProp

Declared as function defineReadonlyProp(obj, key, value)

Define readonly property on object

+ +

param Object obj +
param String key +
param Mixed value

Source code

function defineReadonlyProp(obj, key, value) {
+    Object.defineProperty(obj, key, {
+        writable: false,
+        enumerable: true,
+        configurable: true,
+        value: value
+    });
+}
+

addToCache

Declared as function addToCache(constr, obj)

Add object to cache

Source code

function addToCache(constr, obj) {
+    touchCache(constr, obj.id);
+    constr.cache[obj.id] = obj;
+}
+

touchCache

Declared as function touchCache(constr, id)

Renew object position in LRU cache index

Source code

function touchCache(constr, id) {
+    var cacheLimit = constr.CACHE_LIMIT || DEFAULT_CACHE_LIMIT;
+
+    var ind = constr.mru.indexOf(id);
+    if (~ind) constr.mru.splice(ind, 1);
+    if (constr.mru.length >= cacheLimit * 2) {
+        for (var i = 0; i < cacheLimit;i += 1) {
+            delete constr.cache[constr.mru[i]];
+        }
+        constr.mru.splice(0, cacheLimit);
+    }
+}
+

getCached

Declared as function getCached(constr, id)

Retrieve cached object

Source code

function getCached(constr, id) {
+    if (id) touchCache(constr, id);
+    return id && constr.cache[id];
+}
+

clearCache

Declared as function clearCache(constr)

Clear cache (fully)

+ +

removes both cache and LRU index

+ +

param Class constr - class constructor

Source code

function clearCache(constr) {
+    constr.cache = {};
+    constr.mru = [];
+}
+

removeFromCache

Declared as function removeFromCache(constr, id)

Remove object from cache

+ +

param Class constr +
param id id

Source code

function removeFromCache(constr, id) {
+    var ind = constr.mru.indexOf(id);
+    if (!~ind) constr.mru.splice(ind, 1);
+    delete constr.cache[id];
+}
+

+ +

+ + + + + diff --git a/schema.html b/schema.html new file mode 100644 index 00000000..61b0794b --- /dev/null +++ b/schema.html @@ -0,0 +1,287 @@ + + + + Schema | JugglingDB API docs + + + + + + +

Schema

Schema - adapter-specific classes factory.

+ +

All classes in single schema shares same adapter type and +one database connection

+ +

param name - type of schema adapter (mysql, mongoose, sequelize, redis) +
param settings - any database-specific settings which we need to +establish connection (of course it depends on specific adapter)

+ +

host
port
username
password
database
debug Boolean = false

+ +

example Schema creation, waiting for connection callback

+ +

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

Source code

function Schema(name, settings) {
+    var schema = this;
+    // just save everything we get
+    this.name = name;
+    this.settings = settings;
+
+    // create blank models pool
+    this.models = {};
+    this.definitions = {};
+
+    // and initialize schema using adapter
+    // this is only one initialization entry point of adapter
+    // this module should define `adapter` member of `this` (schema)
+    var adapter;
+    if (path.existsSync(__dirname + '/adapters/' + name + '.js')) {
+        adapter = require('./adapters/' + name);
+    } else {
+        try {
+            adapter = require(name);
+        } catch (e) {
+            throw new Error('Adapter ' + name + ' is not defined, try\n  npm install ' + name);
+        }
+    }
+
+    adapter.initialize(this, function () {
+
+        // we have an adaper now?
+        if (!this.adapter) {
+            throw new Error('Adapter is not defined correctly: it should create `adapter` member of schema');
+        }
+
+        this.adapter.log = function (query, start) {
+            schema.log(query, start);
+        };
+
+        this.adapter.logger = function (query) {
+            var t1 = Date.now();
+            var log = this.log;
+            return function (q) {
+                log(q || query, t1);
+            };
+        };
+
+        this.connected = true;
+        this.emit('connected');
+
+    }.bind(this));
+};
+

Instance methods Helper methods

Schema.prototype.define

Declared as function defineClass(className, properties, settings)

Define class

+ +

param String className +
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

+ +

example simple case

+ +

var User = schema.defind('User', {
+    email: String,
+    password: String,
+    birthDate: Date,
+    activated: Boolean
+});
+

+ +

example more advanced case

+ +

var User = schema.defind('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 }
+});
+

Source code

function defineClass(className, properties, settings) {
+    var schema = this;
+    var args = slice.call(arguments);
+
+    if (!className) throw new Error('Class name required');
+    if (args.length == 1) properties = {}, args.push(properties);
+    if (args.length == 2) settings   = {}, args.push(settings);
+
+    standartize(properties, settings);
+
+    // every class can receive hash of data as optional param
+    var newClass = function ModelConstructor(data) {
+        if (!(this instanceof ModelConstructor)) {
+            return new ModelConstructor(data);
+        }
+        AbstractClass.call(this, data);
+    };
+
+    hiddenProperty(newClass, 'schema', schema);
+    hiddenProperty(newClass, 'modelName', className);
+    hiddenProperty(newClass, 'cache', {});
+    hiddenProperty(newClass, 'mru', []);
+
+    // setup inheritance
+    newClass.__proto__ = AbstractClass;
+    util.inherits(newClass, AbstractClass);
+
+    // store class in model pool
+    this.models[className] = newClass;
+    this.definitions[className] = {
+        properties: properties,
+        settings: settings
+    };
+
+    // pass controll to adapter
+    this.adapter.define({
+        model:      newClass,
+        properties: properties,
+        settings:   settings
+    });
+
+    return newClass;
+
+    function standartize(properties, settings) {
+        Object.keys(properties).forEach(function (key) {
+            var v = properties[key];
+            if (typeof v === 'function') {
+                properties[key] = { type: v };
+            }
+        });
+        // TODO: add timestamps fields
+        // when present in settings: {timestamps: true}
+        // or {timestamps: {created: 'created_at', updated: false}}
+        // by default property names: createdAt, updatedAt
+    }
+
+};
+

Schema.prototype.defineProperty

Declared as function (model, prop, params)

Define single property named prop on model

+ +

param String model - name of model +
param String prop - name of propery +
param Object params - property settings

Source code

function (model, prop, params) {
+    this.definitions[model].properties[prop] = params;
+    if (this.adapter.defineProperty) {
+        this.adapter.defineProperty(model, prop, params);
+    }
+};
+

Schema.prototype.automigrate

Declared as function (cb)

Drop each model table and re-create. +This method make sense only for sql adapters.

+ +

Warning! All data will be lost! Use autoupdate if you need your data.

Source code

function (cb) {
+    this.freeze();
+    if (this.adapter.automigrate) {
+        this.adapter.automigrate(cb);
+    } else if (cb) {
+        cb();
+    }
+};
+

Schema.prototype.autoupdate

Declared as function (cb)

Update existing database tables. +This method make sense only for sql adapters.

Source code

function (cb) {
+    this.freeze();
+    if (this.adapter.autoupdate) {
+        this.adapter.autoupdate(cb);
+    } else if (cb) {
+        cb();
+    }
+};
+

Schema.prototype.isActual

Declared as function (cb)

Check whether migrations needed +This method make sense only for sql adapters.

Source code

function (cb) {
+    this.freeze();
+    if (this.adapter.isActual) {
+        this.adapter.isActual(cb);
+    } else if (cb) {
+        cb(null, true);
+    }
+};
+

Schema.prototype.log

Declared as function (sql, t)

Log benchmarked message. Do not redefine this method, if you need to grab +chema logs, use schema.on('log', ...) emitter event

+ +

private used by adapters

Source code

function (sql, t) {
+    this.emit('log', sql, t);
+};
+

Schema.prototype.freeze

Declared as function freeze()

Freeze schema. Behavior depends on adapter

Source code

function freeze() {
+    if (this.adapter.freezeSchema) {
+        this.adapter.freezeSchema();
+    }
+}
+

Schema.prototype.tableName

Declared as function (modelName)

Return table name for specified modelName +
param String modelName

Source code

function (modelName) {
+    return this.definitions[modelName].settings.table = this.definitions[modelName].settings.table || modelName
+};
+

Schema.prototype.defineForeignKey

Declared as function defineForeignKey(className, key)

Define foreign key +
param String className +
param String key - name of key field

Source code

function defineForeignKey(className, key) {
+    // return if already defined
+    if (this.definitions[className].properties[key]) return;
+
+    if (this.adapter.defineForeignKey) {
+        this.adapter.defineForeignKey(className, key, function (err, keyType) {
+            if (err) throw err;
+            this.definitions[className].properties[key] = {type: keyType};
+        }.bind(this));
+    } else {
+        this.definitions[className].properties[key] = {type: Number};
+    }
+};
+

Schema.prototype.disconnect

Declared as function disconnect()

Close database connection

Source code

function disconnect() {
+    if (typeof this.adapter.disconnect === 'function') {
+        this.adapter.disconnect();
+    }
+};
+

hiddenProperty

hiddenProperty

Declared as function hiddenProperty(where, property, value)

Define hidden property

Source code

function hiddenProperty(where, property, value) {
+    Object.defineProperty(where, property, {
+        writable: false,
+        enumerable: false,
+        configurable: false,
+        value: value
+    });
+}
+

+ +

+ + + + + diff --git a/validatable.html b/validatable.html new file mode 100644 index 00000000..030fd420 --- /dev/null +++ b/validatable.html @@ -0,0 +1,286 @@ + + + + Validatable | JugglingDB API docs + + + + + + +

Validatable

Validation encapsulated in this abstract class.

+ +

Basically validation configurators is just class methods, which adds validations +configs to AbstractClass._validations. Each of this validations run when +obj.isValid() method called.

+ +

Each configurator can accept n params (n-1 field names and one config). Config +is Object depends on specific validation, but all of them has one common part: +message member. It can be just string, when only one situation possible, +e.g. Post.validatesPresenceOf('title', { message: 'can not be blank' });

+ +

In more complicated cases it can be Hash of messages (for each case): +User.validatesLengthOf('password', { min: 6, max: 20, message: {min: 'too short', max: 'too long'}});

Source code

function Validatable() {
+    // validatable class
+};
+

Class methods Instance methods Helper methods

Validatable.validatesPresenceOf

Declared as getConfigurator('presence');

Validate presence. This validation fails when validated field is blank.

+ +

Default error message "can't be blank"

+ +

example Post.validatesPresenceOf('title') +
example Post.validatesPresenceOf('title', {message: 'Can not be blank'}) +
sync

+ +

see helper/validatePresence

Source code

getConfigurator('presence');

Validatable.validatesLengthOf

Declared as getConfigurator('length');

Validate length. Three kinds of validations: min, max, is.

+ +

Default error messages:

+ +

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

+ +

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

+ +

see helper/validateLength

Source code

getConfigurator('length');

Validatable.validatesNumericalityOf

Declared as getConfigurator('numericality');

Validate numericality.

+ +

example User.validatesNumericalityOf('age', { message: { number: '...' }}); +
example User.validatesNumericalityOf('age', {int: true, message: { int: '...' }});

+ +

Default error messages:

+ +

number: is not a number
int: is not an integer

+ +

sync

+ +

see helper/validateNumericality

Source code

getConfigurator('numericality');

Validatable.validatesInclusionOf

Declared as getConfigurator('inclusion');

Validate inclusion in set

+ +

example User.validatesInclusionOf('gender', {in: ['male', 'female']});

+ +

Default error message: is not included in the list

+ +

see helper/validateInclusion

Source code

getConfigurator('inclusion');

Validatable.validatesExclusionOf

Declared as getConfigurator('exclusion');

Validate exclusion

+ +

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

+ +

Default error message: is reserved

+ +

see helper/validateExclusion

Source code

getConfigurator('exclusion');

Validatable.validatesFormatOf

Declared as getConfigurator('format');

Validate format

+ +

Default error message: is invalid

+ +

see helper/validateFormat

Source code

getConfigurator('format');

Validatable.validate

Declared as getConfigurator('custom');

Validate using custom validator

+ +

Default error message: is invalid

+ +

see helper/validateCustom

Source code

getConfigurator('custom');

Validatable.validateAsync

Declared as getConfigurator('custom',

Validate using custom async validator

+ +

Default error message: is invalid

+ +

async +
see helper/validateCustom

Source code

getConfigurator('custom',

Validatable.validatesUniquenessOf

Declared as getConfigurator('uniqueness',

Validate uniqueness

+ +

Default error message: is not unique

+ +

async +
see helper/validateUniqueness

Source code

getConfigurator('uniqueness',

isValid

Validatable.prototype.isValid

Declared as function (callback)

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

+ +

Warning! This method can be called as sync only when no async validation configured. It's strongly recommended to run all validations as asyncronous.

+ +

param Function callback called with (valid) +
return Boolean true if no async validation configured and all passed

+ +

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');
+});
+

Source code

function (callback) {
+    var valid = true, inst = this, wait = 0, async = false;
+
+    // exit with success when no errors
+    if (!this.constructor._validations) {
+        cleanErrors(this);
+        if (callback) {
+            callback(valid);
+        }
+        return valid;
+    }
+
+    Object.defineProperty(this, 'errors', {
+        enumerable: false,
+        configurable: true,
+        value: new Errors
+    });
+
+    this.trigger('validation', function (validationsDone) {
+        var inst = this;
+        this.constructor._validations.forEach(function (v) {
+            if (v[2] && v[2].async) {
+                async = true;
+                wait += 1;
+                validationFailed(inst, v, done);
+            } else {
+                if (validationFailed(inst, v)) {
+                    valid = false;
+                }
+            }
+
+        });
+
+        if (!async) {
+            validationsDone();
+        }
+
+        var asyncFail = false;
+        function done(fail) {
+            asyncFail = asyncFail || fail;
+            if (--wait === 0 && callback) {
+                validationsDone.call(inst, function () {
+                    if( valid && !asyncFail ) cleanErrors(inst);
+                    callback(valid && !asyncFail);
+                });
+            }
+        }
+
+    });
+
+    if (!async) {
+        if (valid) cleanErrors(this);
+        if (callback) callback(valid);
+        return valid;
+    } else {
+        // in case of async validation we should return undefined here,
+        // because not all validations are finished yet
+        return;
+    }
+
+};
+

validatePresence

Declared as function validatePresence(attr, conf, err)

Presence validator

Source code

function validatePresence(attr, conf, err) {
+    if (blank(this[attr])) {
+        err();
+    }
+}
+

validateLength

Declared as function validateLength(attr, conf, err)

Length validator

Source code

function validateLength(attr, conf, err) {
+    if (nullCheck.call(this, attr, conf, err)) return;
+
+    var len = this[attr].length;
+    if (conf.min && len < conf.min) {
+        err('min');
+    }
+    if (conf.max && len > conf.max) {
+        err('max');
+    }
+    if (conf.is && len !== conf.is) {
+        err('is');
+    }
+}
+

validateNumericality

Declared as function validateNumericality(attr, conf, err)

Numericality validator

Source code

function validateNumericality(attr, conf, err) {
+    if (nullCheck.call(this, attr, conf, err)) return;
+
+    if (typeof this[attr] !== 'number') {
+        return err('number');
+    }
+    if (conf.int && this[attr] !== Math.round(this[attr])) {
+        return err('int');
+    }
+}
+

validateInclusion

Declared as function validateInclusion(attr, conf, err)

Inclusion validator

Source code

function validateInclusion(attr, conf, err) {
+    if (nullCheck.call(this, attr, conf, err)) return;
+
+    if (!~conf.in.indexOf(this[attr])) {
+        err()
+    }
+}
+

validateExclusion

Declared as function validateExclusion(attr, conf, err)

Exclusion validator

Source code

function validateExclusion(attr, conf, err) {
+    if (nullCheck.call(this, attr, conf, err)) return;
+
+    if (~conf.in.indexOf(this[attr])) {
+        err()
+    }
+}
+

validateFormat

Declared as function validateFormat(attr, conf, err)

Format validator

Source code

function validateFormat(attr, conf, err) {
+    if (nullCheck.call(this, attr, conf, err)) return;
+
+    if (typeof this[attr] === 'string') {
+        if (!this[attr].match(conf['with'])) {
+            err();
+        }
+    } else {
+        err();
+    }
+}
+

validateCustom

Declared as function validateCustom(attr, conf, err, done)

Custom validator

Source code

function validateCustom(attr, conf, err, done) {
+    conf.customValidator.call(this, err, done);
+}
+

validateUniqueness

Declared as function validateUniqueness(attr, conf, err, done)

Uniqueness validator

Source code

function validateUniqueness(attr, conf, err, done) {
+    var cond = {where: {}};
+    cond.where[attr] = this[attr];
+    this.constructor.all(cond, function (error, found) {
+        if (found.length > 1) {
+            err();
+        } else if (found.length === 1 && found[0].id !== this.id) {
+            err();
+        }
+        done();
+    }.bind(this));
+}
+

blank

Declared as function blank(v)

Return true when v is undefined, blank array, null or empty string +otherwise returns false

+ +

param Mix v +
returns Boolean whether v blank or not

Source code

function blank(v) {
+    if (typeof v === 'undefined') return true;
+    if (v instanceof Array && v.length === 0) return true;
+    if (v === null) return true;
+    if (typeof v == 'string' && v === '') return true;
+    return false;
+}
+

+ +

+ + + + +

AbstractClass

AbstractClass - class methods

AbstractClass.defineProperty

AbstractClass.create

AbstractClass.upsert

AbstractClass.exists

AbstractClass.find

AbstractClass.all

AbstractClass.findOne

AbstractClass.destroyAll

AbstractClass.count

AbstractClass.toString

AbstractClass.hasMany

AbstractClass.belongsTo

AbstractClass.scope

AbstractClass - instance methods

AbstractClass.prototype.save

AbstractClass.prototype._adapter

AbstractClass.prototype.toObject

AbstractClass.prototype.destroy

AbstractClass.prototype.updateAttribute

AbstractClass.prototype.updateAttributes

AbstractClass.prototype.propertyChanged

AbstractClass.prototype.reload

AbstractClass.prototype.reset

AbstractClass - helper methods

isdef

merge

defineReadonlyProp

addToCache

touchCache

getCached

clearCache

removeFromCache

Schema

Schema - instance methods

Schema.prototype.define

Schema.prototype.defineProperty

Schema.prototype.automigrate

Schema.prototype.autoupdate

Schema.prototype.isActual

Schema.prototype.log

Schema.prototype.freeze

Schema.prototype.tableName

Schema.prototype.defineForeignKey

Schema.prototype.disconnect

Schema - helper methods

hiddenProperty

Validatable

Validatable - class methods

Validatable.validatesPresenceOf

Validatable.validatesLengthOf

Validatable.validatesNumericalityOf

Validatable.validatesInclusionOf

Validatable.validatesExclusionOf

Validatable.validatesFormatOf

Validatable.validate

Validatable.validateAsync

Validatable.validatesUniquenessOf

Validatable - instance methods

Validatable.prototype.isValid

Validatable - helper methods

validatePresence

validateLength

validateNumericality

validateInclusion

validateExclusion

validateFormat

validateCustom

validateUniqueness

blank