From 6f17e704a6e944fb4b2d6242f90cabc8a30f44d3 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 11 Apr 2016 11:15:46 -0400 Subject: [PATCH 1/6] Liberate {ClientField,BucketData}Validator * src/validate/BucketDataValidator.js: Added * src/validate/ClientFieldValidator.js: Added --- src/validate/BucketDataValidator.js | 281 +++++++++++++++++++++++++ src/validate/ClientFieldValidator.js | 293 +++++++++++++++++++++++++++ 2 files changed, 574 insertions(+) create mode 100644 src/validate/BucketDataValidator.js create mode 100644 src/validate/ClientFieldValidator.js diff --git a/src/validate/BucketDataValidator.js b/src/validate/BucketDataValidator.js new file mode 100644 index 0000000..6a88db5 --- /dev/null +++ b/src/validate/BucketDataValidator.js @@ -0,0 +1,281 @@ +/** + * Validate bucket data by type + * + * Copyright (C) 2016 LoVullo Associates, Inc. + * + * This file is part of liza. + * + * liza is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +var Class = require( 'easejs' ).Class; + + +/** + * Validates and formats bucket data + */ +module.exports = Class( 'BucketDataValidator', +{ + /** + * VFormat instances for each type + * @type {Object} + */ + 'private _fmts': {}, + + /** + * Map fields to their types + * + * File names as the properties, type as the value. + * + * @type {Object} + */ + 'private _type_map': {}, + + + /** + * Initializes bucket data validator + * + * Bucket data is validated using VFormat patterns. Each field will be + * formatted according to their type as specified in the type_map and the + * rules for the given type as provided in format_set. + * + * @param {Object} type_map maps fields to their types + * @param {Object} format_set VFormat objects for each type in + * type_map + */ + __construct: function( type_map, format_set ) + { + this._type_map = type_map || {}; + this._fmts = format_set || {}; + }, + + + /** + * Validate the given data, returning another object consisting of the + * formatted results + * + * Unrecognized fields will be ignored (and copied as-is to the resulting + * object). Each value for the given data is expected to be an array; + * otherwise, an empty array will be returned in its place. + * + * @param {Object.} data data to validate/format + * + * @param {function(name,value,i,e)} err callback for validation errors + * + * @param {boolean=} inplace alter data object rather than returning a new + * object containing formatted data + * + * @return {Object.>} formatted data + */ + 'public validate': function( data, err, inplace ) + { + err = err || function() {}; + inplace = !!inplace; + + var formatted = ( inplace ) ? data : {}; + + // validate and format each item + for ( var name in data ) + { + var type = this._getFieldType( name ), + value = data[ name ]; + + // ignore unknown types (if it should be kicked out, then the server + // will take care of it; we store a lot of random shit client-side + // for calculated values, etc) + if ( !type ) + { + formatted[ name ] = value; + continue; + } + + // we expect that the bucket data will always consist of an array of + // values + formatted[ name ] = this._validateEach( value, name, type, err ); + } + + return formatted; + }, + + + /** + * Format each provided bucket value for display to the user + * + * The data stored in the bucket may not necessarily be the best + * representation for the user. For example, dates may be styled in a + * familiar locale. + * + * Optionally, the data can be modified in place rather than returning a new + * object. + * + * @param {Object.} data data to validate/format + * @param {boolean=} inplace alter data object rather than returning + * a new object containing formatted data + * + * @return {Array.} formatted data + */ + 'public format': function( data, inplace ) + { + inplace = !!inplace; + + var formatted = ( inplace ) ? data : {}; + + for ( var name in data ) + { + var type = this._getFieldType( name ), + value = data[ name ]; + + if ( !type ) + { + formatted[ name ] = value; + continue; + } + + formatted[ name ] = this._formatEach( value, name, type ); + } + + return formatted; + }, + + + /** + * Determine field type + * + * This maintains BC: the old data format used a string to represent + * the type, whereas the new system uses an object describing additional + * details. + * + * @param {string} name type name + * + * @return {string|undefined} type of field NAME + */ + 'private _getFieldType': function( name ) + { + var type_data = this._type_map[ name ]; + + return ( type_data ) + ? type_data.type || type_data + : undefined; + }, + + + /** + * Validate and format each element of the given array + * + * @param {Array.} values values to validate and format + * @param {string} name field name + * @param {string} type field type + * + * @param {function(name,value,i,e)} err callback for validation errors + * + * @return {Array.} formatted data + */ + 'private _validateEach': function( values, name, type, err ) + { + return this._forEach( values, name, type, 'parse', err ); + }, + + + /** + * Format each value in the given array + * + * @param {Array.} values values to validate and format + * @param {string} name field name + * @param {string} type field type + * + * @return {Array.} formatted data + */ + 'private _formatEach': function( values, name, type ) + { + return this._forEach( values, name, type, 'retrieve' ); + }, + + + /** + * Iterate over each value, perform the requested action and return the + * result set + * + * @param {Array.} values values to validate and format + * @param {string} name field name + * @param {string} type field type + * @param {string} method parse/retrieve + * + * @param {function(string,string,number,Error)} err error handler + * + * @return {Array.} formatted data + */ + 'private _forEach': function( values, name, type, method, err ) + { + // formatted return values + var ret = [], + fmt = this._fmts[ type ]; + + if ( fmt === null ) + { + // if the formatter is null, then perform no formatting + return values; + } + else if ( fmt === undefined ) + { + throw Error( + "No formatter for type " + type + ); + } + + for ( var i in values ) + { + var value = values[ i ]; + + // trim the data + if ( typeof value === 'string' ) + { + value = value.trim(); + } + + // ignore empty/undefined/null values (explicitly; avoid casting + // magic) + if ( ( value === '' ) + || ( value === undefined ) + || ( value === null ) + ) + { + ret[ i ] = value; + continue; + } + + // format return values for display + try + { + ret[ i ] = fmt[ method ].call( fmt, value ); + } + catch ( e ) + { + if ( err ) + { + // the caller wishes to handle errors + err( name, value, i, e ); + } + else + { + // there was a problem formatting (or the formatter doesn't + // exist); return the raw value so as not to wipe out their + // data + ret[ i ] = value; + } + } + } + + return ret; + } +} ); diff --git a/src/validate/ClientFieldValidator.js b/src/validate/ClientFieldValidator.js new file mode 100644 index 0000000..c2a73bb --- /dev/null +++ b/src/validate/ClientFieldValidator.js @@ -0,0 +1,293 @@ +/** + * Field validator + * + * Copyright (C) 2016 LoVullo Associates, Inc. + * + * This file is part of liza. + * + * liza is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + * + * @needsLove + * - Liberate QuoteClient + * @end needsLove + */ + +var Class = require( 'easejs' ).Class, + QuoteClient = require( 'program/QuoteClient' ), + EventEmitter = require( 'events' ).EventEmitter; + + +/** + * Passively monitors quote data, validating and formatting any fields that are + * altered for the given QuoteClient + * + * In the event of a validation failure, the data will not be added to the + * bucket and the caller may be notified via a failure callback. This way, you + * may forget that the monitoring is even occuring unless there is a problem to + * handle. + */ +module.exports = Class( 'ClientFieldValidator' ) + .extend( EventEmitter, +{ + /** + * Validation/formatting object + * @type {BucketDataValidator} + */ + 'private _validator': null, + + + /** + * Initializes monitor with a validator + * + * @param {BucketDataValidator} validator validation object + */ + __construct: function( validator ) + { + this._validator = validator; + }, + + + /** + * Monitors the given quote_client for field changes, performing validations + * and formatting automatically + * + * The failure callback will be called only if there are errors to report, + * in which case the object will contain each field that has errors with an + * array of their failed indexes. + * + * This validator will keep track of failures *per client* and can report on + * when the failure has been resolved. This feature is useful for clearing + * any error indicators. + * + * @param {QuoteClient} quote_client quote client to validate against + * + * @param {function(Object)} failure_callback function to call with errors + * @param {function(Object)} fixcallback function to call with indexes + * of fields that have previously + * failed, but have since been + * resolved + * + * @return {ClientFieldValidator} self + */ + 'public monitor': function( quote_client, failure_callback, fix_callback ) + { + // minor overhead for default definition and invocation (likely to be + // optimized away by most modern engines) for the sake of code clarity + // further down + failure_callback = failure_callback || function() {}; + fix_callback = fix_callback || function() {}; + + var _self = this; + + // past failure are stored per-quote in order to call the fix callback + // once they are resolved + var past_fail = {}; + + // catch problems *before* the data is staged, altering the data + // directly if need be + quote_client.on( 'preDataUpdate', function( data ) + { + var validator = _self._validator, + failures = {}; + + // assert the correctness of the data, formatting it in-place for + // storage in the bucket + try + { + validator.validate( data, function( name, value, i, e ) + { + // set failures to undefined, which will cause the staging + // bucket to ignore the value entirely (we don't want crap + // data to be staged) + data[ name ][ i ] = undefined; + + // these failures will be returned (return as an object + // rather than an array, even though our indexes are + // numeric, to make debugging easier, since some values may + // be undefined) + ( failures[ name ] = failures[ name ] || {} )[ i ] = value; + }, true ); + } + catch ( e ) + { + _self.emit( 'error', e ); + } + + // allow others to add to the list of failures if needed + _self.emit( 'validate', data, failures ); + + var fixed = _self._detectFixes( past_fail, data, failures ); + + // quick pre-ES5 means of detecting object keys + var has_fail = false; + for ( var _ in failures ) + { + has_fail = true; + break; + } + + // it's important to do this *after* retrieving the fixed indexes, + // but we should do it *before* calling the callbacks just in case + // they themselves trigger the preDataUpdate event + _self._mergeFailures( past_fail, failures ); + + // if we have failures, notify the caller via the callback so that + // they do not have to loop through each field to determine what + // failed based on their undefined values + if ( has_fail ) + { + failure_callback( failures ); + } + + // will be null if no fixes have been made + if ( fixed !== null ) + { + fix_callback( fixed, _self._hasFailures( past_fail ) ); + } + } ); + + return this; + }, + + + /** + * Detects fixes based on previous failures + * + * This method will also clear fixed failures from the past failures object + * by directly modifying it (for performance reasons). + * + * Note that this does not entirely remove the field from the past failures + * object; this is because the memory consumption is negligable when + * compared with the rest of the software and it would only muddy up the + * code (counting the number of checks vs the number of fixes). Cleanup is + * handled by _hasFailures(). + * + * @param {Object} past past failures to merge with + * @param {Object} data validated data + * @param {Object} failures new failures + * + * @return {!Object} fixed list of fixed indexes for each fixed field + */ + 'private _detectFixes': function( past, data, failures ) + { + var fixed = {}, + has_fixed = false; + + for ( var name in past ) + { + // we're only interested in detecting fixes on the data that has + // been set + if ( !( data[ name ] ) ) + { + continue; + } + + var field = data[ name ], + past_fail = past[ name ], + fail = failures[ name ]; + + // we must check each individual index because it is possible that + // not every index was modified or fixed (we must loop through like + // this because this is treated as a hash table, not an array) + for ( var i in past_fail ) + { + // to be marked as fixed, there must both me no failure and + // there must be data for this index for the field in question + // (if the field wasn't touched, then of course there's no + // failure!) + if ( ( fail === undefined ) + || ( !( fail[ i ] ) && ( field[ i ] !== undefined ) ) + ) + { + // looks like it has been resolved + ( fixed[ name ] = fixed[ name ] || {} )[ i ] = + data[ name ][ i ]; + + has_fixed = true; + + delete past_fail[ i ]; + } + } + } + + return ( has_fixed ) + ? fixed + : null; + }, + + + /** + * Determine whether or not there are additional failures that must be fixed + * + * This runs fastest if there are failures or if there are no failures and + * the object is entriely clean. Will clean up fixed fields as it goes, + * speeding up future runs. Will return true on the first failure it + * encounters, but in order to determine if there are no failures, it must + * loop through all past failures (unless they have bene cleaned). + * + * Assuming a failure, this will run in *at best* O(2) time (check first + * field, check first field index). If it must check a few fields, it will + * run in O(n + 1) time, where n is the number of fields until the first + * failure, yielding O(2) on subsequent calls assuming no changes in past + * failures. Assuming no failures and a clean object, O(1). Worst case is + * O(n). I'm not going to bother working out the average run time. + * + * Essentially --- it's not that bad. + * + * @param {Object} past past failures cache + * + * @return {boolean} true if errors exist, otherwise false + */ + 'private _hasFailures': function( past ) + { + for ( var field in past ) + { + for ( var i in past[ field ] ) + { + return true; + } + + // clean up as we go + delete past[ field ]; + } + + return false; + }, + + + /** + * Merges a new set of failures into the past failures table + * + * This will merge each individual index of each field. Note that it is not + * responsible for clearing failures that are no longer present. + * + * @param {Object} past past failures to merge with + * @param {Object} failures new failures + * + * @return {undefined} + */ + 'private _mergeFailures': function( past, failures ) + { + for ( var name in failures ) + { + var cur = ( past[ name ] = past[ name ] || [] ); + + // copy each failure into the past failures table + for ( var i in failures[ name ] ) + { + cur[ i ] = true; + } + } + } +} ); From 0ac16a35056606deb81a31d6f55fd2ad21b28a7e Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 11 Apr 2016 11:29:34 -0400 Subject: [PATCH 2/6] Add ClientFieldValidator#validate * src/validate/ClientFieldValidator (validate): Added Extracted logic that previously was exclusive to #monitor; that method will now simply invoke #validate. --- src/validate/ClientFieldValidator.js | 162 +++++++++++++++------------ 1 file changed, 91 insertions(+), 71 deletions(-) diff --git a/src/validate/ClientFieldValidator.js b/src/validate/ClientFieldValidator.js index c2a73bb..5d048df 100644 --- a/src/validate/ClientFieldValidator.js +++ b/src/validate/ClientFieldValidator.js @@ -46,6 +46,12 @@ module.exports = Class( 'ClientFieldValidator' ) */ 'private _validator': null, + /** + * Past validation failures + * @type {Object} + */ + 'private _past_fail': {}, + /** * Initializes monitor with a validator @@ -59,28 +65,54 @@ module.exports = Class( 'ClientFieldValidator' ) /** - * Monitors the given quote_client for field changes, performing validations - * and formatting automatically + * Monitor the given QUOTE_CLIENT for field changes and trigger validation * + * + * @param {QuoteClient} quote_client quote client to validate against + * + * @param {function(Object)} failure_callback function to call with errors + * @param {function(Object)} fix_callback function to call with indexes + * of fields that have previously + * failed, but have since been + * resolved + * + * @return {ClientFieldValidator} self + */ + 'public monitor': function( quote_client, failure_callback, fix_callback ) + { + var _self = this; + + // catch problems *before* the data is staged, altering the data + // directly if need be + quote_client.on( 'preDataUpdate', function( data ) + { + _self.validate( data, failure_callback, fix_callback ); + } ); + + return this; + }, + + + /** + * Perform field validation * * The failure callback will be called only if there are errors to report, * in which case the object will contain each field that has errors with an * array of their failed indexes. * - * This validator will keep track of failures *per client* and can report on - * when the failure has been resolved. This feature is useful for clearing - * any error indicators. + * This validator will keep track of failures and can report on when the + * failure has been resolved. This feature is useful for clearing any + * error indicators. * - * @param {QuoteClient} quote_client quote client to validate against - * - * @param {function(Object)} failure_callback function to call with errors - * @param {function(Object)} fixcallback function to call with indexes - * of fields that have previously - * failed, but have since been - * resolved + * @param {Object} data bucket data diff + * @param {function(Object)} failure_callback function to call with errors + * @param {function(Object)} fix_callback function to call with indexes + * of fields that have previously + * failed, but have since been + * resolved * * @return {ClientFieldValidator} self */ - 'public monitor': function( quote_client, failure_callback, fix_callback ) + 'public validate': function( data, failure_callback, fix_callback ) { // minor overhead for default definition and invocation (likely to be // optimized away by most modern engines) for the sake of code clarity @@ -88,74 +120,62 @@ module.exports = Class( 'ClientFieldValidator' ) failure_callback = failure_callback || function() {}; fix_callback = fix_callback || function() {}; - var _self = this; + var failures = {}; - // past failure are stored per-quote in order to call the fix callback - // once they are resolved - var past_fail = {}; - - // catch problems *before* the data is staged, altering the data - // directly if need be - quote_client.on( 'preDataUpdate', function( data ) + // assert the correctness of the data, formatting it in-place for + // storage in the bucket + try { - var validator = _self._validator, - failures = {}; - - // assert the correctness of the data, formatting it in-place for - // storage in the bucket - try + this._validator.validate( data, function( name, value, i, e ) { - validator.validate( data, function( name, value, i, e ) - { - // set failures to undefined, which will cause the staging - // bucket to ignore the value entirely (we don't want crap - // data to be staged) - data[ name ][ i ] = undefined; + // set failures to undefined, which will cause the staging + // bucket to ignore the value entirely (we don't want crap + // data to be staged) + data[ name ][ i ] = undefined; - // these failures will be returned (return as an object - // rather than an array, even though our indexes are - // numeric, to make debugging easier, since some values may - // be undefined) - ( failures[ name ] = failures[ name ] || {} )[ i ] = value; - }, true ); - } - catch ( e ) - { - _self.emit( 'error', e ); - } + // these failures will be returned (return as an object + // rather than an array, even though our indexes are + // numeric, to make debugging easier, since some values may + // be undefined) + ( failures[ name ] = failures[ name ] || {} )[ i ] = value; + }, true ); + } + catch ( e ) + { + this.emit( 'error', e ); + } - // allow others to add to the list of failures if needed - _self.emit( 'validate', data, failures ); + // allow others to add to the list of failures if needed + this.emit( 'validate', data, failures ); - var fixed = _self._detectFixes( past_fail, data, failures ); + var fixed = this._detectFixes( this._past_fail, data, failures ); - // quick pre-ES5 means of detecting object keys - var has_fail = false; - for ( var _ in failures ) - { - has_fail = true; - break; - } + // quick pre-ES5 means of detecting object keys + var has_fail = false; + for ( var _ in failures ) + { + has_fail = true; + break; + } - // it's important to do this *after* retrieving the fixed indexes, - // but we should do it *before* calling the callbacks just in case - // they themselves trigger the preDataUpdate event - _self._mergeFailures( past_fail, failures ); + // it's important to do this *after* retrieving the fixed indexes, + // but we should do it *before* calling the callbacks just in case + // they themselves trigger the preDataUpdate event + this._mergeFailures( this._past_fail, failures ); - // if we have failures, notify the caller via the callback so that - // they do not have to loop through each field to determine what - // failed based on their undefined values - if ( has_fail ) - { - failure_callback( failures ); - } + // if we have failures, notify the caller via the callback so that + // they do not have to loop through each field to determine what + // failed based on their undefined values + if ( has_fail ) + { + failure_callback( failures ); + } - // will be null if no fixes have been made - if ( fixed !== null ) - { - fix_callback( fixed, _self._hasFailures( past_fail ) ); - } - } ); + // will be null if no fixes have been made + if ( fixed !== null ) + { + fix_callback( fixed, this._hasFailures( this._past_fail ) ); + } return this; }, From fefe2dae4117b06960186349d65c62dac2d458a7 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 11 Apr 2016 11:48:58 -0400 Subject: [PATCH 3/6] Remove ClientFieldValidator#monitor * src/validate/ClientFieldValidator.js (monitor): Remove This just concerns itself with something that it should be concerned about; let the caller handle monitoring, now that we have a #validate method. --- src/validate/ClientFieldValidator.js | 36 +--------------------------- 1 file changed, 1 insertion(+), 35 deletions(-) diff --git a/src/validate/ClientFieldValidator.js b/src/validate/ClientFieldValidator.js index 5d048df..d14afb3 100644 --- a/src/validate/ClientFieldValidator.js +++ b/src/validate/ClientFieldValidator.js @@ -17,20 +17,14 @@ * * You should have received a copy of the GNU General Public License * along with this program. If not, see . - * - * @needsLove - * - Liberate QuoteClient - * @end needsLove */ var Class = require( 'easejs' ).Class, - QuoteClient = require( 'program/QuoteClient' ), EventEmitter = require( 'events' ).EventEmitter; /** - * Passively monitors quote data, validating and formatting any fields that are - * altered for the given QuoteClient + * Validate and format altered fields * * In the event of a validation failure, the data will not be added to the * bucket and the caller may be notified via a failure callback. This way, you @@ -64,34 +58,6 @@ module.exports = Class( 'ClientFieldValidator' ) }, - /** - * Monitor the given QUOTE_CLIENT for field changes and trigger validation * - * - * @param {QuoteClient} quote_client quote client to validate against - * - * @param {function(Object)} failure_callback function to call with errors - * @param {function(Object)} fix_callback function to call with indexes - * of fields that have previously - * failed, but have since been - * resolved - * - * @return {ClientFieldValidator} self - */ - 'public monitor': function( quote_client, failure_callback, fix_callback ) - { - var _self = this; - - // catch problems *before* the data is staged, altering the data - // directly if need be - quote_client.on( 'preDataUpdate', function( data ) - { - _self.validate( data, failure_callback, fix_callback ); - } ); - - return this; - }, - - /** * Perform field validation * From 88313c016e25c1ef502f7ba26e4397597d5d0fc7 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Mon, 11 Apr 2016 11:50:36 -0400 Subject: [PATCH 4/6] Accept full bucket data for ClientFieldValidator#validate This allows #validate to be used generically for any type of validation, not just change events. * src/validate/ClientFieldValidator.js (validate): Accept and propagate all bucket data to `validate` event listeners. --- src/validate/ClientFieldValidator.js | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/src/validate/ClientFieldValidator.js b/src/validate/ClientFieldValidator.js index d14afb3..9b42904 100644 --- a/src/validate/ClientFieldValidator.js +++ b/src/validate/ClientFieldValidator.js @@ -17,6 +17,10 @@ * * You should have received a copy of the GNU General Public License * along with this program. If not, see . + * + * @needsLove + * - Liberate Bucket + * @end needsLove */ var Class = require( 'easejs' ).Class, @@ -69,7 +73,8 @@ module.exports = Class( 'ClientFieldValidator' ) * failure has been resolved. This feature is useful for clearing any * error indicators. * - * @param {Object} data bucket data diff + * @param {Bucket} data complete bucket data + * @param {Object} diff bucket data diff * @param {function(Object)} failure_callback function to call with errors * @param {function(Object)} fix_callback function to call with indexes * of fields that have previously @@ -78,7 +83,7 @@ module.exports = Class( 'ClientFieldValidator' ) * * @return {ClientFieldValidator} self */ - 'public validate': function( data, failure_callback, fix_callback ) + 'public validate': function( data, diff, failure_callback, fix_callback ) { // minor overhead for default definition and invocation (likely to be // optimized away by most modern engines) for the sake of code clarity @@ -92,12 +97,12 @@ module.exports = Class( 'ClientFieldValidator' ) // storage in the bucket try { - this._validator.validate( data, function( name, value, i, e ) + this._validator.validate( diff, function( name, value, i, e ) { // set failures to undefined, which will cause the staging // bucket to ignore the value entirely (we don't want crap // data to be staged) - data[ name ][ i ] = undefined; + diff[ name ][ i ] = undefined; // these failures will be returned (return as an object // rather than an array, even though our indexes are @@ -112,9 +117,9 @@ module.exports = Class( 'ClientFieldValidator' ) } // allow others to add to the list of failures if needed - this.emit( 'validate', data, failures ); + this.emit( 'validate', data, diff, failures ); - var fixed = this._detectFixes( this._past_fail, data, failures ); + var fixed = this._detectFixes( this._past_fail, diff, failures ); // quick pre-ES5 means of detecting object keys var has_fail = false; @@ -126,7 +131,7 @@ module.exports = Class( 'ClientFieldValidator' ) // it's important to do this *after* retrieving the fixed indexes, // but we should do it *before* calling the callbacks just in case - // they themselves trigger the preDataUpdate event + // they themselves trigger the preDiffUpdate event this._mergeFailures( this._past_fail, failures ); // if we have failures, notify the caller via the callback so that From 659c820eb634066efef46ce0fb9f2b3495fd1b28 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 12 Apr 2016 12:02:00 -0400 Subject: [PATCH 5/6] Add ValidStateMonitor The intent is to ultimately replace ClientFieldValidator with this and individual validators that interact with it. * src/validate/ValidStateMonitor.js: Added * test/validate/ValidStateMonitorTest.js: Added --- src/validate/ValidStateMonitor.js | 220 ++++++++++++++++++++++++ test/validate/ValidStateMonitorTest.js | 228 +++++++++++++++++++++++++ 2 files changed, 448 insertions(+) create mode 100644 src/validate/ValidStateMonitor.js create mode 100644 test/validate/ValidStateMonitorTest.js diff --git a/src/validate/ValidStateMonitor.js b/src/validate/ValidStateMonitor.js new file mode 100644 index 0000000..9e4f6d0 --- /dev/null +++ b/src/validate/ValidStateMonitor.js @@ -0,0 +1,220 @@ +/** + * Field validity monitor + * + * Copyright (C) 2016 LoVullo Associates, Inc. + * + * This file is part of liza. + * + * liza is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +var Class = require( 'easejs' ).Class, + EventEmitter = require( 'events' ).EventEmitter; + + +/** + * Monitor field state and emit fix/failure events + */ +module.exports = Class( 'ValidStateMonitor' ) + .extend( EventEmitter, +{ + /** + * Past validation failures + * @type {Object} + */ + 'private _failures': {}, + + + /** + * Mark fields as updated and detect failures and fixes + * + * The field data DATA should be a key-value store with an array as the + * value for each key. If the data are not present, then it is assumed + * to have been left unchanged, and will not contribute to a + * fix. Otherwise, any field in FAILURES but not in DATA will count as + * a fix. + * + * FAILURES should follow the same structure as DATA. Indexes should + * omitted from the value if they are not failures. + * + * @param {Object} data key-value field data + * @param {Object} failures key-value field errors + * + * @return {ValidStateMonitor} self + */ + 'public update': function( data, failures ) + { + var fixed = this.detectFixes( data, this._failures, failures ); + + this.mergeFailures( this._failures, failures ); + + if ( this.hasFailures() ) + { + this.emit( 'failure', this._failures ); + } + + if ( fixed !== null ) + { + this.emit( 'fix', fixed ); + } + + return this; + }, + + + /** + * Retrieve current validation errors + * + * @return {Object} key-value object where key is field name and + * value is an array with each failure index and + * the value that caused the failure + */ + 'public getFailures': function() + { + return this._failures; + }, + + + /** + * Determine whether or not there are additional failures that must be fixed + * + * This runs fastest if there are failures or if there are no failures and + * the object is entriely clean. Will clean up fixed fields as it goes, + * speeding up future runs. Will return true on the first failure it + * encounters, but in order to determine if there are no failures, it must + * loop through all past failures (unless they have bene cleaned). + * + * Assuming a failure, this will run in *at best* O(1) time (check first + * field, check first field index). If it must check a few fields, it will + * run in O(n) time, where n is the number of fields until the first + * failure, yielding O(1) on subsequent calls assuming no changes in past + * failures. Assuming no failures and a clean object, O(1). Worst case is + * O(n). I'm not going to bother working out the average run time. + * + * Essentially---it's not that bad. + * + * @param {Object} past past failures cache + * + * @return {boolean} true if errors exist, otherwise false + */ + 'virtual public hasFailures': function() + { + var past = this._failures; + + for ( var field in past ) + { + for ( var i in past[ field ] ) + { + return true; + } + + // clean up as we go + delete past[ field ]; + } + + return false; + }, + + + /** + * Merges a new set of failures into the past failures table + * + * This will merge each individual index of each field. Note that it is not + * responsible for clearing failures that are no longer present. + * + * @param {Object} past past failures to merge with + * @param {Object} failures new failures + * + * @return {undefined} + */ + 'virtual protected mergeFailures': function( past, failures ) + { + for ( var name in failures ) + { + past[ name ] = past[ name ] || []; + + // copy each failure into the past failures table + for ( var i in failures[ name ] ) + { + past[ name ][ i ] = failures[ name ][ i ]; + } + } + }, + + + /** + * Detects fixes based on previous failures + * + * This method will also clear fixed failures from the past failures object + * by directly modifying it (for performance reasons). + * + * Note that this does not entirely remove the field from the past failures + * object; this is because the memory consumption is negligable when + * compared with the rest of the software and it would only muddy up the + * code (counting the number of checks vs the number of fixes). Cleanup is + * handled by _hasFailures(). + * + * @param {Object} past past failures to merge with + * @param {Object} data validated data + * @param {Object} failures new failures + * + * @return {!Object} fixed list of fixed indexes for each fixed field + */ + 'virtual protected detectFixes': function( data, past, failures ) + { + var fixed = {}, + has_fixed = false; + + for ( var name in past ) + { + // we're only interested in detecting fixes on the data that has + // been set + if ( !( data[ name ] ) ) + { + continue; + } + + var field = data[ name ], + past_fail = past[ name ], + fail = failures[ name ]; + + // we must check each individual index because it is possible that + // not every index was modified or fixed (we must loop through like + // this because this is treated as a hash table, not an array) + for ( var i in past_fail ) + { + // to be marked as fixed, there must both me no failure and + // there must be data for this index for the field in question + // (if the field wasn't touched, then of course there's no + // failure!) + if ( ( fail === undefined ) + || ( !( fail[ i ] ) && ( field[ i ] !== undefined ) ) + ) + { + // looks like it has been resolved + ( fixed[ name ] = fixed[ name ] || [] )[ i ] = + data[ name ][ i ]; + + has_fixed = true; + + delete past_fail[ i ]; + } + } + } + + return ( has_fixed ) + ? fixed + : null; + }, +} ); diff --git a/test/validate/ValidStateMonitorTest.js b/test/validate/ValidStateMonitorTest.js new file mode 100644 index 0000000..ea743d0 --- /dev/null +++ b/test/validate/ValidStateMonitorTest.js @@ -0,0 +1,228 @@ +/** + * Test field validity monitor + * + * Copyright (C) 2016 LoVullo Associates, Inc. + * + * This file is part of liza. + * + * liza is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +var Sut = require( '../../' ).validate.ValidStateMonitor, + expect = require( 'chai' ).expect; + +var nocall = function( type ) +{ + return function() + { + throw Error( type + ' should not be called' ); + }; +}; + + +describe( 'ValidStateMonitor', function() +{ + describe( '#update', function() + { + it( 'does nothing with no data or failures', function() + { + Sut() + .on( 'failure', nocall( 'failure' ) ) + .on( 'fix', nocall( 'fix' ) ) + .update( {}, {} ); + } ); + + + it( 'does nothing with data but no failures', function() + { + Sut() + .on( 'failure', nocall( 'failure' ) ) + .on( 'fix', nocall( 'fix' ) ) + .update( { foo: [ 'bar' ] }, {} ); + } ); + + + // the failure should contain the value that caused it, so we do not + // need the data + describe( 'given failures', function() + { + it( 'marks failures even when given no data', function( done ) + { + Sut() + .on( 'failure', function( failures ) + { + expect( failures ) + .to.deep.equal( { foo: [ 'bar', 'baz' ] } ); + done(); + } ) + .on( 'fix', nocall( 'fix' ) ) + .update( {}, { foo: [ 'bar', 'baz' ] } ); + } ); + + + it( 'marks failures with index gaps', function( done ) + { + Sut() + .on( 'failure', function( failures ) + { + expect( failures ) + .to.deep.equal( { foo: [ undefined, 'baz' ] } ); + done(); + } ) + .on( 'fix', nocall( 'fix' ) ) + .update( {}, { foo: [ undefined, 'baz' ] } ); + } ); + + + it( 'retains past failures when setting new', function( done ) + { + var sut = Sut(); + + var test_first = function( failures ) + { + expect( failures ) + .to.deep.equal( { foo: [ undefined, 'baz' ] } ); + + sut.once( 'failure', test_second ); + }; + + var test_second = function( failures ) + { + expect( failures ) + .to.deep.equal( { foo: [ 'bar', 'baz' ] } ); + + done(); + }; + + sut + .once( 'failure', test_first ) + .on( 'fix', nocall( 'fix' ) ) + .update( {}, { foo: [ undefined, 'baz' ] } ) + .update( {}, { foo: [ 'bar' ] } ); + } ); + } ); + + + describe( 'given data with absence of failure', function() + { + it( 'removes non-failures if field is present', function( done ) + { + var data = { foo: [ 'bardata', 'baz' ] }; + + Sut() + .on( 'fix', function( fixed ) + { + expect( fixed ) + .to.deep.equal( { foo: [ 'bardata' ] } ); + done(); + } ) + .update( data, { foo: [ 'bar', 'baz' ] } ) + .update( data, { foo: [ '', 'baz' ] } ); + } ); + + + it( 'keeps failures if field is missing', function( done ) + { + var data = { + bar: [ 'baz', 'quux' ], + }; + + Sut() + .on( 'fix', function( fixed ) + { + expect( fixed ) + .to.deep.equal( { bar: [ 'baz', 'quux' ] } ); + done(); + } ) + .update( data, { + foo: [ 'bar', 'baz' ], // does not exist in data + bar: [ 'moo', 'cow' ], + } ) + .update( data, {} ); + } ); + } ); + + + it( 'can emit both failure and fix', function( done ) + { + var data = { + bar: [ 'baz', 'quux' ], + }; + + Sut() + .update( data, { + bar: [ 'moo', 'cow' ] // fail + } ) + .on( 'failure', function( failed ) + { + expect( failed ) + .to.deep.equal( { + foo: [ 'bar' ], + } ); + } ) + .on( 'fix', function( fixed ) + { + expect( fixed ) + .to.deep.equal( { bar: [ 'baz', 'quux' ] } ); + done(); + } ) + .update( data, { + foo: [ 'bar' ], // fail + // fixes bar + } ); + } ); + } ); + + + describe( '#getFailures', function() + { + it( 'is empty when no failures exist', function() + { + expect( + Sut() + .getFailures() + ).to.deep.equal( {} ); + } ); + + + it( 'retrieves current failures', function() + { + expect( + Sut() + .update( {}, { foo: [ 'fail' ] } ) + .getFailures() + ).to.deep.equal( { foo: [ 'fail' ] } ); + } ); + } ); + + + describe( '#hasFailures', function() + { + it( 'is false when no failures exist', function() + { + expect( Sut().hasFailures() ) + .to.be.false; + } ); + + + it( 'is true when failures exist', function() + { + expect( + Sut() + .update( {}, { foo: [ 'fail' ] } ) + .hasFailures() + ).to.be.true; + } ); + } ); +} ); From 9dfc7c04ff15642dbb960f1fe47db04c4b11b9d2 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 12 Apr 2016 14:06:57 -0400 Subject: [PATCH 6/6] Remove ClientFieldValidator Use ValidStateMonitor instead. * src/validate/ClientFieldValidator.js: Deleted --- src/validate/ClientFieldValidator.js | 284 --------------------------- 1 file changed, 284 deletions(-) delete mode 100644 src/validate/ClientFieldValidator.js diff --git a/src/validate/ClientFieldValidator.js b/src/validate/ClientFieldValidator.js deleted file mode 100644 index 9b42904..0000000 --- a/src/validate/ClientFieldValidator.js +++ /dev/null @@ -1,284 +0,0 @@ -/** - * Field validator - * - * Copyright (C) 2016 LoVullo Associates, Inc. - * - * This file is part of liza. - * - * liza is free software: you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation, either version 3 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program. If not, see . - * - * @needsLove - * - Liberate Bucket - * @end needsLove - */ - -var Class = require( 'easejs' ).Class, - EventEmitter = require( 'events' ).EventEmitter; - - -/** - * Validate and format altered fields - * - * In the event of a validation failure, the data will not be added to the - * bucket and the caller may be notified via a failure callback. This way, you - * may forget that the monitoring is even occuring unless there is a problem to - * handle. - */ -module.exports = Class( 'ClientFieldValidator' ) - .extend( EventEmitter, -{ - /** - * Validation/formatting object - * @type {BucketDataValidator} - */ - 'private _validator': null, - - /** - * Past validation failures - * @type {Object} - */ - 'private _past_fail': {}, - - - /** - * Initializes monitor with a validator - * - * @param {BucketDataValidator} validator validation object - */ - __construct: function( validator ) - { - this._validator = validator; - }, - - - /** - * Perform field validation - * - * The failure callback will be called only if there are errors to report, - * in which case the object will contain each field that has errors with an - * array of their failed indexes. - * - * This validator will keep track of failures and can report on when the - * failure has been resolved. This feature is useful for clearing any - * error indicators. - * - * @param {Bucket} data complete bucket data - * @param {Object} diff bucket data diff - * @param {function(Object)} failure_callback function to call with errors - * @param {function(Object)} fix_callback function to call with indexes - * of fields that have previously - * failed, but have since been - * resolved - * - * @return {ClientFieldValidator} self - */ - 'public validate': function( data, diff, failure_callback, fix_callback ) - { - // minor overhead for default definition and invocation (likely to be - // optimized away by most modern engines) for the sake of code clarity - // further down - failure_callback = failure_callback || function() {}; - fix_callback = fix_callback || function() {}; - - var failures = {}; - - // assert the correctness of the data, formatting it in-place for - // storage in the bucket - try - { - this._validator.validate( diff, function( name, value, i, e ) - { - // set failures to undefined, which will cause the staging - // bucket to ignore the value entirely (we don't want crap - // data to be staged) - diff[ name ][ i ] = undefined; - - // these failures will be returned (return as an object - // rather than an array, even though our indexes are - // numeric, to make debugging easier, since some values may - // be undefined) - ( failures[ name ] = failures[ name ] || {} )[ i ] = value; - }, true ); - } - catch ( e ) - { - this.emit( 'error', e ); - } - - // allow others to add to the list of failures if needed - this.emit( 'validate', data, diff, failures ); - - var fixed = this._detectFixes( this._past_fail, diff, failures ); - - // quick pre-ES5 means of detecting object keys - var has_fail = false; - for ( var _ in failures ) - { - has_fail = true; - break; - } - - // it's important to do this *after* retrieving the fixed indexes, - // but we should do it *before* calling the callbacks just in case - // they themselves trigger the preDiffUpdate event - this._mergeFailures( this._past_fail, failures ); - - // if we have failures, notify the caller via the callback so that - // they do not have to loop through each field to determine what - // failed based on their undefined values - if ( has_fail ) - { - failure_callback( failures ); - } - - // will be null if no fixes have been made - if ( fixed !== null ) - { - fix_callback( fixed, this._hasFailures( this._past_fail ) ); - } - - return this; - }, - - - /** - * Detects fixes based on previous failures - * - * This method will also clear fixed failures from the past failures object - * by directly modifying it (for performance reasons). - * - * Note that this does not entirely remove the field from the past failures - * object; this is because the memory consumption is negligable when - * compared with the rest of the software and it would only muddy up the - * code (counting the number of checks vs the number of fixes). Cleanup is - * handled by _hasFailures(). - * - * @param {Object} past past failures to merge with - * @param {Object} data validated data - * @param {Object} failures new failures - * - * @return {!Object} fixed list of fixed indexes for each fixed field - */ - 'private _detectFixes': function( past, data, failures ) - { - var fixed = {}, - has_fixed = false; - - for ( var name in past ) - { - // we're only interested in detecting fixes on the data that has - // been set - if ( !( data[ name ] ) ) - { - continue; - } - - var field = data[ name ], - past_fail = past[ name ], - fail = failures[ name ]; - - // we must check each individual index because it is possible that - // not every index was modified or fixed (we must loop through like - // this because this is treated as a hash table, not an array) - for ( var i in past_fail ) - { - // to be marked as fixed, there must both me no failure and - // there must be data for this index for the field in question - // (if the field wasn't touched, then of course there's no - // failure!) - if ( ( fail === undefined ) - || ( !( fail[ i ] ) && ( field[ i ] !== undefined ) ) - ) - { - // looks like it has been resolved - ( fixed[ name ] = fixed[ name ] || {} )[ i ] = - data[ name ][ i ]; - - has_fixed = true; - - delete past_fail[ i ]; - } - } - } - - return ( has_fixed ) - ? fixed - : null; - }, - - - /** - * Determine whether or not there are additional failures that must be fixed - * - * This runs fastest if there are failures or if there are no failures and - * the object is entriely clean. Will clean up fixed fields as it goes, - * speeding up future runs. Will return true on the first failure it - * encounters, but in order to determine if there are no failures, it must - * loop through all past failures (unless they have bene cleaned). - * - * Assuming a failure, this will run in *at best* O(2) time (check first - * field, check first field index). If it must check a few fields, it will - * run in O(n + 1) time, where n is the number of fields until the first - * failure, yielding O(2) on subsequent calls assuming no changes in past - * failures. Assuming no failures and a clean object, O(1). Worst case is - * O(n). I'm not going to bother working out the average run time. - * - * Essentially --- it's not that bad. - * - * @param {Object} past past failures cache - * - * @return {boolean} true if errors exist, otherwise false - */ - 'private _hasFailures': function( past ) - { - for ( var field in past ) - { - for ( var i in past[ field ] ) - { - return true; - } - - // clean up as we go - delete past[ field ]; - } - - return false; - }, - - - /** - * Merges a new set of failures into the past failures table - * - * This will merge each individual index of each field. Note that it is not - * responsible for clearing failures that are no longer present. - * - * @param {Object} past past failures to merge with - * @param {Object} failures new failures - * - * @return {undefined} - */ - 'private _mergeFailures': function( past, failures ) - { - for ( var name in failures ) - { - var cur = ( past[ name ] = past[ name ] || [] ); - - // copy each failure into the past failures table - for ( var i in failures[ name ] ) - { - cur[ i ] = true; - } - } - } -} );