Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMike Gerwitz <gerwitm@lovullo.com>2016-04-12 16:39:20 -0400
committerMike Gerwitz <gerwitm@lovullo.com>2016-04-12 16:39:53 -0400
commitcbfd42a26458e5a1b6164bb3a6763ddc54c8f3ff (patch)
tree4357d605181390806d6cd5d6f4ed9aa60eb54e96
parent8cc73a4ca81aace65fdef4a43fc3b1bd2bf96b12 (diff)
parent9dfc7c04ff15642dbb960f1fe47db04c4b11b9d2 (diff)
downloadliza-cbfd42a26458e5a1b6164bb3a6763ddc54c8f3ff.tar.gz
liza-cbfd42a26458e5a1b6164bb3a6763ddc54c8f3ff.tar.bz2
liza-cbfd42a26458e5a1b6164bb3a6763ddc54c8f3ff.zip
ValidStateMonitor added
This supercedes ClientFieldValidator; callers should handle validations and notify this new class. * src/validate/BucketDataValidator.js: Added * src/validate/ValidStateMonitor.js: New * test/validate/ValidStateMonitorTest.js: New
-rw-r--r--src/validate/BucketDataValidator.js281
-rw-r--r--src/validate/ValidStateMonitor.js220
-rw-r--r--test/validate/ValidStateMonitorTest.js228
3 files changed, 729 insertions, 0 deletions
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 <http://www.gnu.org/licenses/>.
+ */
+
+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.<Array>} 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.<Array.<string>>} 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.<Array>} data data to validate/format
+ * @param {boolean=} inplace alter data object rather than returning
+ * a new object containing formatted data
+ *
+ * @return {Array.<string>} 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.<string>} 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.<string>} 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.<string>} values values to validate and format
+ * @param {string} name field name
+ * @param {string} type field type
+ *
+ * @return {Array.<string>} 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.<string>} 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.<string>} 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/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 <http://www.gnu.org/licenses/>.
+ */
+
+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 <http://www.gnu.org/licenses/>.
+ */
+
+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;
+ } );
+ } );
+} );