alchemymvc 1.3.21 → 1.4.0-alpha.1

package/lib/class/field.js

@@ -1,15 +1,17 @@
+const CASTER = Symbol('caster');
+
 /**
  * Field instances are created on boot,
  * so they are shared between Schema & Model instances.
  *
  * @constructor
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.3.6
  *
  * @param    {Schema}   schema      The schema this field is added to
- * @param    {String}   name        The name of the field
+ * @param    {string}   name        The name of the field
  * @param    {Object}   options     Field options
  */
 Blast.Globals.Field = Function.inherits('Alchemy.Base', 'Alchemy.Field', function Field(schema, name, options) {
@@ -42,7 +44,7 @@ Field.startNewGroup();
 /**
  * Defer casting when processing data?
  *
- * @type   {Boolean}
+ * @type     {boolean}
  */
 Field.setProperty('deferCast', false);
 
@@ -55,18 +57,31 @@ Field.setDeprecatedProperty('isArray',               'is_array');
 /**
  * All children will be stored here
  *
- * @type   {Object}
+ * @type     {Object}
  */
 Field.setStatic('types', {});
 
+/**
+ * Set the main cast function
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.0
+ * @version  1.4.0
+ *
+ * @param    {Function}   fnc
+ */
+Field.setStatic(function setCastFunction(fnc) {
+	this.setMethod(CASTER, fnc);
+});
+
 /**
  * Set the datatype of this field
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @param    {String}
+ * @param    {string}
  */
 Field.setStatic(function setDatatype(type) {
 	this.setProperty('datatype', type);
@@ -75,11 +90,11 @@ Field.setStatic(function setDatatype(type) {
 /**
  * Set if the value of this field is self-contained
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @param    {Boolean}   value
+ * @param    {boolean}   value
  */
 Field.setStatic(function setSelfContained(value) {
 
@@ -93,7 +108,7 @@ Field.setStatic(function setSelfContained(value) {
 /**
  * Create a PathEvaluator
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
@@ -106,11 +121,11 @@ Field.setStatic(function createPathEvaluator(path) {
 /**
  * Get the description of the field
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.0
  * @version  1.3.0
  *
- * @type     {String}
+ * @type     {string}
  */
 Field.setProperty(function description() {
 	return this.options?.description || this.options?.options?.description || null;
@@ -119,11 +134,11 @@ Field.setProperty(function description() {
 /**
  * Is this a private field?
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.0.0
  * @version  1.2.4
  *
- * @type     {Boolean}
+ * @type     {boolean}
  */
 Field.setProperty(function is_private() {
 
@@ -137,11 +152,11 @@ Field.setProperty(function is_private() {
 /**
  * Does this field have a default value?
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @type     {Boolean}
+ * @type     {boolean}
  */
 Field.prepareProperty(function has_default() {
 	return Object.hasProperty(this.options, 'default');
@@ -151,11 +166,11 @@ Field.prepareProperty(function has_default() {
  * Is this field translatable, meaning:
  * it is an object with the locales as keys.
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @type     {Boolean}
+ * @type     {boolean}
  */
 Field.setProperty(function is_translatable() {
 	return !!this.options.translatable;
@@ -164,11 +179,11 @@ Field.setProperty(function is_translatable() {
 /**
  * Does this field need to be translated in some way?
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.4
  * @version  1.1.4
  *
- * @type     {Boolean}
+ * @type     {boolean}
  */
 Field.setProperty(function requires_translating() {
 	return this.is_translatable;
@@ -177,11 +192,11 @@ Field.setProperty(function requires_translating() {
 /**
  * Is this field an object?
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @type     {Boolean}
+ * @type     {boolean}
  */
 Field.setProperty(function is_object() {
 	return this.is_translatable;
@@ -190,11 +205,11 @@ Field.setProperty(function is_object() {
 /**
  * Is this field an array?
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @type     {Boolean}
+ * @type     {boolean}
  */
 Field.setProperty(function is_array() {
 
@@ -210,20 +225,33 @@ Field.setProperty(function is_array() {
 /**
  * Does this field have a computed value?
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.21
  * @version  1.3.21
  *
- * @type     {Boolean}
+ * @type     {boolean}
  */
 Field.setProperty(function is_computed() {
 	return !!this.options.is_computed;
 });
 
+/**
+ * Should this field allow null values?
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.0
+ * @version  1.4.0
+ *
+ * @type     {boolean}
+ */
+Field.setProperty(function is_nullable() {
+	return !(this.options.is_nullable === false);
+});
+
 /**
  * Get the required related fields
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.21
  * @version  1.3.21
  *
@@ -241,7 +269,7 @@ Field.enforceProperty(function required_fields(new_value) {
 /**
  * Get the optional related fields
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.21
  * @version  1.3.21
  *
@@ -259,7 +287,7 @@ Field.enforceProperty(function optional_fields(new_value) {
 /**
  * Get all the dependency fields
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.21
  * @version  1.3.21
  *
@@ -288,7 +316,7 @@ Field.enforceProperty(function dependency_fields(new_value) {
 /**
  * Resolve a field path to a field instance
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.21
  * @version  1.3.21
  */
@@ -320,7 +348,7 @@ function resolveFieldPaths(field, field_paths) {
 /**
  * The datasource this field is used in
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.0.7
  * @version  1.1.0
  *
@@ -345,11 +373,11 @@ Field.setProperty(function datasource() {
  * Get the path to this field in the main record
  * (Without name of the model)
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @type     {String}
+ * @type     {string}
  */
 Field.setProperty(function path() {
 	return this.schema.getPath(this.name, false);
@@ -359,11 +387,11 @@ Field.setProperty(function path() {
  * Get the path to this field in the document
  * (WITH the name of the model)
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
- * @type     {String}
+ * @type     {string}
  */
 Field.setProperty(function path_in_document() {
 	return this.schema.getPath(this.name, true);
@@ -372,7 +400,7 @@ Field.setProperty(function path_in_document() {
 /**
  * Set basic behaviour
  *
- * @author   Jelle De Loecker <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.3
  * @version  1.1.0
  */
@@ -396,7 +424,7 @@ Field.constitute(function setTitle() {
 /**
  * Revive a dried field
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
@@ -412,7 +440,7 @@ Field.setStatic(function unDry(value) {
 /**
  * Convert to JSON
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.3.1
  *
@@ -432,7 +460,7 @@ Field.setMethod(function toDry() {
 /**
  * Prepare the title property
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  0.4.0
  *
@@ -456,11 +484,11 @@ Field.setProperty(function title() {
 /**
  * Get a property by name
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.4.0
  * @version  0.4.0
  *
- * @param    {String}  property_name
+ * @param    {string}  property_name
  *
  * @return   {Mixed}
  */
@@ -474,13 +502,13 @@ Field.setMethod(function get(property_name) {
  *
  * @deprecated
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  0.2.0
  *
- * @param    {Boolean}  with_top_schema  Add top schema name, defaults to true
+ * @param    {boolean}  with_top_schema  Add top schema name, defaults to true
  *
- * @return   {String}
+ * @return   {string}
  */
 Field.decorateMethod('deprecate', function getPath(with_top_schema) {
 	return this.schema.getPath(this.name, with_top_schema);
@@ -489,7 +517,7 @@ Field.decorateMethod('deprecate', function getPath(with_top_schema) {
 /**
  * Get all the fields that lead to this field
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
@@ -503,7 +531,7 @@ Field.setMethod(function getFieldChain() {
  * Get all the values for the current field in the given document
  * as an array of FieldValue instances
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
@@ -525,12 +553,12 @@ Field.setMethod(function getDocumentValues(document) {
 /**
  * Get the database value from the given record
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.1.0
  *
  * @param    {Object}   record
- * @param    {String}   path_to_value_hint
+ * @param    {string}   path_to_value_hint
  *
  * @return   {Mixed}
  */
@@ -635,30 +663,89 @@ Field.setMethod(function getRecordValue(record, path_to_value_hint) {
 });
 
 /**
- * Cast the given value to this field's type
+ * Cast the value (could be in a container)
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.0
+ * @version  1.4.0
+ *
+ * @param    {*}         value
+ * @param    {boolean}   to_datasource   Is this meant for the datasource?
+ *
+ * @return   {*}
+ */
+Field.setMethod(function castContainedValues(value, to_datasource) {
+
+	if (this.is_translatable && value && this.is_translatable) {
+		let prefix;
+
+		for (prefix in value) {
+			value[prefix] = this.cast(value[prefix], to_datasource);
+		}
+	} else if (this.is_array && value) {
+		let i;
+
+		for (i = 0; i < value.length; i++) {
+			value[i] = this.cast(value[i], to_datasource);
+		}
+	} else {
+		value = this.cast(value, to_datasource);
+	}
+
+	return value;
+});
+
+/**
+ * Cast the given value to this field's type.
+ * Containers should not be passed (like the array or translation object container)
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
- * @version  1.0.7
+ * @version  1.4.0
  *
- * @param    {Mixed}     value
- * @param    {Boolean}   to_datasource   Is this meant for the datasource?
+ * @param    {*}         value
+ * @param    {boolean}   to_datasource   Is this meant for the datasource?
  *
- * @return   {Mixed}
+ * @return   {*}
  */
 Field.setMethod(function cast(value, to_datasource) {
+
+	if (value === '' && this.datatype !== 'string') {
+		value = null;
+	}
+
+	if (value == null && this.is_nullable) {
+		return null;
+	}
+
+	return this[CASTER](value, to_datasource);
+});
+
+/**
+ * Default cast function
+ *
+ * @author   Jelle De Loecker <jelle@elevenways.be>
+ * @since    1.4.0
+ * @version  1.4.0
+ *
+ * @param    {*}         value
+ * @param    {boolean}   to_datasource   Is this meant for the datasource?
+ *
+ * @return   {*}
+ */
+Field.setCastFunction(function defaultCast(value, to_datasource) {
 	return value;
 });
 
 /**
  * Cast the given value if it doesn't need to be deferred
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.5
  * @version  1.1.5
  *
  * @param    {Mixed}     value
- * @param    {Boolean}   to_datasource   Is this meant for the datasource?
+ * @param    {boolean}   to_datasource   Is this meant for the datasource?
  *
  * @return   {Mixed}
  */
@@ -676,7 +763,7 @@ Field.setMethod(function _initialValueCast(value, to_datasource) {
  * Allows an array of values.
  * Calls `castCondition` to do the actual casting per-value.
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  0.5.0
  *
@@ -708,7 +795,7 @@ Field.setMethod(function castForQuery(value, field_paths) {
 /**
  * Cast the given value to this field's type for search in a db
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.1.0
  *
@@ -724,7 +811,7 @@ Field.setMethod(function castCondition(value, field_paths) {
 /**
  * Cast the given value to this field's type for search in a db
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.5.0
  * @version  1.2.0
  *
@@ -746,7 +833,7 @@ Field.setMethod(function _castCondition(value, field_paths) {
 /**
  * Prepare the value to be saved in the database
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  0.2.0
  *
@@ -775,7 +862,7 @@ Field.setMethod(function toDatasource(value, data, datasource, callback) {
  * The actual toDatasource method inherited Field's can modify.
  * These won't get passed a null or undefined value.
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.1.0
  *
@@ -796,7 +883,7 @@ Field.setMethod(function _toDatasource(value, data, datasource, callback) {
 /**
  * Prepare regular values to be returned
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.3.1
  *
@@ -830,7 +917,7 @@ Field.setMethod(function regularToDatasource(value, data, datasource, callback)
 /**
  * Prepare the translatable values to be returned
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  0.2.0
  *
@@ -853,9 +940,9 @@ Field.setMethod(function translatableToDatasource(value, data, datasource, callb
 /**
  * Prepare the value to be returned to node
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
- * @version  0.2.0
+ * @version  1.4.0
  *
  * @param    {Object}   query     The original query
  * @param    {Object}   options   The original query options
@@ -863,14 +950,6 @@ Field.setMethod(function translatableToDatasource(value, data, datasource, callb
  * @param    {Function} callback
  */
 Field.setMethod(function toApp(query, options, value, callback) {
-
-	var that = this,
-	    tasks;
-
-	if (value == null) {
-		return callback(null, null);
-	}
-
 	if (this.is_translatable) {
 		this.fromTranslatableToApp(query, options, value, callback);
 	} else {
@@ -881,7 +960,7 @@ Field.setMethod(function toApp(query, options, value, callback) {
 /**
  * Prepare regular values to be returned
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  0.2.0
  *
@@ -889,21 +968,20 @@ Field.setMethod(function toApp(query, options, value, callback) {
  */
 Field.setMethod(function fromRegularToApp(query, options, value, callback) {
 
-	var that = this,
-	    tasks;
-
 	// Non-arrayable fields need only 1 call to _toApp
 	if (!this.is_array) {
 		return this._toApp(query, options, value, callback);
 	}
 
+	const that = this;
+
 	// If it is an arrayable field, make sure the value is actually an array
 	if (!Array.isArray(value)) {
 		value = Array.cast(value);
 	}
 
 	// Call _toApp for every value inside the array
-	tasks = value.map(function eachValue(entry) {
+	let tasks = value.map(function eachValue(entry) {
 		return function eachValueToApp(next) {
 			that._toApp(query, options, entry, next);
 		};
@@ -916,7 +994,7 @@ Field.setMethod(function fromRegularToApp(query, options, value, callback) {
 /**
  * Prepare the translatable values to be returned
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.1.0
  *
@@ -956,7 +1034,7 @@ Field.setMethod(function fromTranslatableToApp(query, options, value, callback)
  * The actual toApp method inherited Field's can modify.
  * These won't get passed a null or undefined value.
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.0.7
  *
@@ -972,7 +1050,7 @@ Field.setMethod(function _toApp(query, options, value, callback) {
 /**
  * Get the default value out of the options
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.1.0
  *
@@ -1002,7 +1080,7 @@ Field.setMethod(function getDefault() {
 /**
  * Get the value to store, using the given value
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.1.5
  *
@@ -1037,11 +1115,11 @@ Field.setMethod(function getValue(value) {
 /**
  * Get the value to store, using the given value
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    0.2.0
  * @version  1.1.5
  *
- * @param   {Array}   wrapped
+ * @param    {Array}   wrapped
  */
 Field.setMethod(function _getValue(wrapped, done_translation) {
 
@@ -1087,7 +1165,7 @@ Field.setMethod(function _getValue(wrapped, done_translation) {
 /**
  * See if we need to apply any indexes
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.3.6
  */
@@ -1120,7 +1198,7 @@ Field.setMethod(function checkIndexes() {
 /**
  * Make a client-side safe clone of this field
  *
- * @author   Jelle De Loecker <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
@@ -1139,7 +1217,7 @@ Field.setMethod(function toHawkejs(wm) {
 /**
  * Get the client-side options
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
@@ -1154,7 +1232,7 @@ Field.setMethod(function getClientConfigOptions(wm) {
 /**
  * Get the options that can be used for drying
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.1
  * @version  1.3.1
  *
@@ -1167,7 +1245,7 @@ Field.setMethod(function getOptionsForDrying() {
 /**
  * Get all the rules for this field
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.0
  * @version  1.1.0
  *
@@ -1191,13 +1269,13 @@ Field.setMethod(function getRules() {
 /**
  * See if the given vlaue is considered not-empty for this field
  *
- * @author   Jelle De Loecker   <jelle@elevenways.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.3.7
  * @version  1.3.7
  *
  * @param    {Mixed}   value
  *
- * @return   {Boolean}
+ * @return   {boolean}
  */
 Field.setMethod(function valueHasContent(value) {
 
@@ -1221,7 +1299,7 @@ Field.setMethod(function valueHasContent(value) {
 /**
  * Translate the given value
  *
- * @author   Jelle De Loecker   <jelle@develry.be>
+ * @author   Jelle De Loecker <jelle@elevenways.be>
  * @since    1.1.4
  * @version  1.2.5
  */