Plaster

Source: schema.js

  1. const _ = require('lodash');
  2. const clone = require('clone');
  4. import { normalizeProperties } from './normalize'
  6. export class Schema {
  7.   /**
  8.    * @classdesc Schema class represents the schema definition. It includes properties, methods, static methods, and any
  9.    * middleware we want to define.
  10.    *
  11.    * @description Creates an object schema
  12.    * @class
  13.    * @api public
  14.    * @param {Object} descriptor
  15.    * @param {Object} options
  16.    * @param {Boolean} options.strict - By default (<code>true</code>), allow only values in the schema to be set.
  17.    *                                   When this is <code>false</code>, setting new fields will dynamically add the field
  18.    *                                   to the schema as type "any".
  19.    * @param {Boolean} options.dotNotation - Allow fields to be set via dot notation. Default: <code>true</code>.
  20.    *                                      <code>obj['user.name'] = 'Joe'; -> obj: { user: 'Joe' }<code>
  21.    *
  22.    * @param {Boolean} options.minimize - "minimize" schemas by removing empty objects. Default: <code>true</code>
  23.    * @param {Object} options.toObject - <code>toObject</code> method options.
  24.    * @param {Boolean} options.toObject.minimize - "minimize" schemas by removing empty objects. Default: <code>true</code>
  25.    * @param {Function} options.toObject.transform - transform function
  26.    * @param {Boolean} options.toObject.virtuals - whether to include virtual properties. Default: <code>false</code>
  27.    * @param {Boolean} options.toObject.dateToISO - convert dates to string in ISO format using <code>Date.toISOString()</code>. Default:  <code>false</code>
  28.    * @param {Object} options.toJSON - options for <code>toJSON</code> method options, similar to above
  29.    * @param {Boolean} options.strict - ensures that value passed in ot assigned that were not specified in our
  30.    *                                   schema do not get saved
  31.    * @param {Function} options.onBeforeValueSet - function called when write operations on an object takes place. Currently,
  32.    * it will only notify of write operations on the object itself and will not notify you when child objects are written to.
  33.    * If you return false or throw an error within the onBeforeValueSet handler, the write operation will be cancelled.
  34.    * Throwing an error will add the error to the error stack.
  35.    * @param {Function} options.onValueSet - Similar to <code>onBeforeValueSet</code>, but called after we've set a value on the key,
  36.    *
  37.    * @example
  38.    * var schema = new plaster.Schema({ name: String });
  39.    * @example <caption>with <code>onBeforeValueSet</code></caption>
  40.    * var User = plaster.schema({ name: String }, {
  41.    *   onBeforeValueSet: function(key, value) {
  42.    *     if(key === 'name' && value.indexOf('Joe') >= 0) {
  43.    *       return false;
  44.    *     });
  45.    *   }
  46.    * });
  47.    *
  48.    * var User = plaster.model('User', schema);
  49.    * var user = new User();
  50.    * user.name = 'Bill'; // name not set
  51.    * user.name = 'Joe Smith'; //  { name: 'Joe Smith' }
  52.    */
  53.   constructor(descriptor, options = {}) {
  54.     // Create object for options if doesn't exist and merge with defaults.
  55.     this.options = _.extend({
  56.       strict: true,
  57.       dotNotation: true
  58.     }, options);
  60.     this.methods = {};
  61.     this.statics = {};
  62.     this.callQueue = [];
  64.     this.add(descriptor);
  65.   }
  67.   /**
  68.    * Creates a instance method for the created model.
  69.    * An object of function names and functions can also be passed in.
  70.    *
  71.    * @api public
  72.    * @param {String} name the name of the method
  73.    * @param {Function} func the actual function implementation
  74.    *
  75.    * @example
  76.    * var userSchema = plaster.schema({
  77.    *   firstName: String,
  78.    *   lastName: String
  79.    * });
  80.    *
  81.    * userSchema.method('getFullName', function () {
  82.    *   return this.firstName + ' ' + this.lastName
  83.    * });
  84.    *
  85.    * var User = plaster.model('User', userSchema);
  86.    * var user = new User({
  87.    *   firstName: 'Joe',
  88.    *   lastName: 'Smith'
  89.    * });
  90.    *
  91.    * console.log(user.getFullName()); // Joe Smith
  92.    *
  93.    */
  94.   method(name, func) {
  95.     if (_.isPlainObject(name)) {
  96.       for (func in name) {
  97.         this.method(func, name[func]);
  98.       }
  99.     }
  100.     else {
  101.       if (!_.isString(name)) throw new TypeError('Schema#method expects a string identifier as a function name');
  102.       else if (!_.isFunction(func)) throw new TypeError('Schema#method expects a function as a handle');
  104.       this.methods[name] = func;
  105.     }
  106.   }
  108.   /**
  109.    * Creates a static function for the created model.
  110.    * An object of function names and functions can also be passed in.
  111.    *
  112.    * @api public
  113.    * @param {String} name name of the statuc function
  114.    * @param {Function} func the actual function
  115.    *
  116.    * * @example
  117.    * var userSchema = plaster.schema({ name: String });
  118.    *
  119.    * userSchema.static('foo', function () {
  120.    *   return 'bar';
  121.    * });
  122.    *
  123.    * var User = plaster.model('User', userSchema);
  124.    *
  125.    * console.log(User.foo()); // 'bar'
  126.    *
  127.    */
  128.   static(name, func) {
  129.     if (_.isPlainObject(name)) {
  130.       for (func in name) {
  131.         this.statics(func, name[func]);
  132.       }
  133.     }
  134.     else {
  135.       if (!_.isString(name)) throw new TypeError('Schema#statics expects a string identifier as a function name');
  136.       else if (!_.isFunction(func)) throw new TypeError('Schema#statics expects a function as a handle');
  138.       this.statics[name] = func;
  139.     }
  140.   }
  142.   /**
  143.    * Creates a virtual property for the created model with the given object
  144.    * specifying the get and optionally set function
  145.    *
  146.    * @api public
  147.    * @param {String} name name of the virtual property
  148.    * @param {String|Function|Object} type optional type to be used for the virtual property. If not provided default is
  149.    *                                      'any' type.
  150.    * @param {Object} options virtual options
  151.    * @param {Function} options.get - the virtual getter function
  152.    * @param {Function} options.set - the virtual setter function. If not provided the virtual becomes read-only.
  153.    *
  154.    * @example
  155.    * var userSchema = plaster.schema({firstName: String, lastName: String});
  156.    *
  157.    * userSchema.virtual('fullName', String, {
  158.    *   get: function () {
  159.    *     return this.firstName + ' ' + this.lastName;
  160.    *   },
  161.    *   set: function (v) {
  162.    *     if (v !== undefined) {
  163.    *       var parts = v.split(' ');
  164.    *       this.firstName = parts[0];
  165.    *       this.lastName = parts[1];
  166.    *     }
  167.    *   }
  168.    * });
  169.    *
  170.    * var User = plaster.model('User', userSchema);
  171.    *
  172.    * var user = new User({firstName: 'Joe', lastName: 'Smith'});
  173.    * console.log(user.fullName); // Joe Smith
  174.    * user.fullName = 'Bill Jones';
  175.    * console.log(user.firstName); // Bill
  176.    * console.log(user.lastName); // Jones
  177.    * console.log(user.fullName); // Bill Jones
  178.    */
  179.   virtual(name, type, options) {
  180.     if (!_.isString(name)) throw new TypeError('Schema#virtual expects a string identifier as a property name');
  182.     if (_.isPlainObject(type) && !options) {
  183.       options = type;
  184.       type = 'any';
  185.     }
  187.     else if (!_.isPlainObject(options)) throw new TypeError('Schema#virtual expects an object as a handle');
  188.     else if (!_.isFunction(options.get)) throw new TypeError('Schema#virtual expects an object with a get function');
  190.     var virtualType = {
  191.       type: type,
  192.       virtual: true,
  193.       get: options.get,
  194.       invisible: true
  195.     };
  197.     if (options.set) {
  198.       virtualType.set = options.set;
  199.     }
  200.     else {
  201.       virtualType.readOnly = true;
  202.     }
  204.     this.descriptor[name] = virtualType;
  205.   }
  207.   /**
  208.    * Sets/gets a schema option.
  209.    *
  210.    * @param {String} key option name
  211.    * @param {Object} [value] if not passed, the current option value is returned
  212.    * @api public
  213.    */
  214.   set(key, value) {
  215.     if (1 === arguments.length) {
  216.       return this.options[key];
  217.     }
  219.     this.options[key] = value;
  221.     return this;
  222.   }
  224.   /**
  225.    * Gets a schema option.
  226.    *
  227.    * @api public
  228.    * @param {String} key option name
  229.    * @return {*} the option value
  230.    */
  231.   get(key) {
  232.     return this.options[key];
  233.   }
  235.   /**
  236.    * Defines a pre hook for the schema.
  237.    * See {@link https://www.npmjs.com/package/hooks-fixed hooks-fixed}.
  238.    */
  239.   pre() {
  240.     return this.queue('pre', arguments);
  241.   }
  243.   /**
  244.    * Defines a post hook for the schema.
  245.    * See {@link https://www.npmjs.com/package/hooks-fixed hooks-fixed}.
  246.    */
  247.   post() {
  248.     return this.queue('post', arguments);
  249.   }
  251.   /**
  252.    * Adds a method call to the queue.
  253.    *
  254.    * @param {String} name name of the document method to call later
  255.    * @param {Array} args arguments to pass to the method
  256.    * @api private
  257.    */
  258.   queue(name, args) {
  259.     var q = {hook: name, args: args};
  260.     if (args[0] && typeof args[0] === 'string') {
  261.       q.hooked = args[0];
  262.     }
  264.     this.callQueue.push(q);
  265.   }
  267.   /**
  268.    * Adds the descriptor to the schema at the given key
  269.    * @param key the property key
  270.    * @param descriptor the property descriptor
  271.    *
  272.    * @example
  273.    * var userSchema = plaster.schema({firstName: String });
  274.    * userSchema.add('lastName', String);
  275.    */
  276.   add(key, descriptor) {
  277.     if (!this.descriptor) {
  278.       this.descriptor = {};
  279.     }
  281.     // adjust our descriptor
  282.     if (key && descriptor) {
  283.       this.descriptor[key] = normalizeProperties.call(this, descriptor, key)
  284.     }
  285.     else if (typeof key === 'object' && !descriptor) {
  286.       if (!this.descriptor) {
  287.         this.descriptor = {};
  288.       }
  290.       _.each(key, (properties, index) => {
  291.         this.descriptor[index] = normalizeProperties.call(this, properties, index);
  292.       });
  293.     }
  294.   }
  296.   /**
  297.    * Clones property from other to us
  298.    * @param {Schema} other - other schema
  299.    * @param {String} prop - property name
  300.    * @param {Boolean} add - whether to add() or assign. if true will do deep clone.
  301.    * @private
  302.    */
  303.   _cloneProp(other, prop, add) {
  304.     if (other && other[prop]) {
  305.       let p;
  306.       for (p in other[prop]) {
  307.         if (other[prop].hasOwnProperty(p) && !this[prop][p]) {
  308.           if (add) {
  309.             this.add(p, clone(other.descriptor[p]));
  310.           }
  311.           else {
  312.             this[prop][p] = other[prop][p];
  313.           }
  314.         }
  315.       }
  316.     }
  317.   }
  319.   /**
  320.    * Extends other schema. Copies descriptor properties, methods, statics, virtuals and middleware.
  321.    * If this schema has a named property already, the property is not copied.
  322.    * @param {Schema} other the schema to extend.
  323.    */
  324.   extend(other) {
  325.     if (other && other instanceof Schema) {
  326.       this._cloneProp(other, 'descriptor', true);
  327.       this._cloneProp(other, 'statics');
  328.       this._cloneProp(other, 'methods');
  330.       var self = this;
  331.       other.callQueue.forEach(function (e) {
  332.         self.callQueue.unshift(e);
  333.       });
  334.     }
  336.     return this;
  337.   }
  338. }