From 659c820eb634066efef46ce0fb9f2b3495fd1b28 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 12 Apr 2016 12:02:00 -0400 Subject: [PATCH] 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; + } ); + } ); +} );