meadow-endpoints 3.0.7 → 4.0.2

package/source/controller/utility/Meadow-Endpoints-Filter-Parser.js

@@ -0,0 +1,225 @@
+/**
+* Meadow Endpoint Utility Class - Parse a Filter String and put it into a Query.
+*
+* @license MIT
+*
+* @author Steven Velozo <steven@velozo.com>
+* @module Meadow
+*/
+/**
+* Parse GET-passed Filter Strings, turn the results into proper Meadow query stanzas
+
+ Take the filter and return an array of filter instructions
+ Basic instruction anatomy:
+       INSTRUCTION~FIELD~OPERATOR~VALUE
+ FOP - Filter Open Paren
+       FOP~0~(~0
+ FCP - Filter Close Paren
+       FCP~0~)~0
+ FBV - Filter By Value (left-side AND connected)
+       FBV~Category~EQ~Books
+       Possible comparisons:
+       * EQ - Equals To (=)
+       * NE - Not Equals To (!=)
+       * GT - Greater Than (>)
+       * GE - Greater Than or Equals To (>=)
+       * LT - Less Than (<)
+       * LE - Less Than or Equals To (<=)
+       * LK - Like (Like)
+       * IN - Is NULL
+       * NN - Is NOT NULL
+       * INN - IN list
+ FBVOR - Filter By Value (left-side OR connected)
+ FBL - Filter By List (value list, separated by commas)
+       FBL~Category~EQ~Books,Movies
+ FBD - Filter by Date (exclude time)
+       FBD~UpdateDate~EQ~2015-10-01
+ FSF - Filter Sort Field
+       FSF~Category~ASC~0
+       FSF~Category~DESC~0
+ FDST - Filter by Distinct (adds distinct keyword to Read and Count queries)
+       FDST~0~0~0~
+
+ This means: FBV~Category~EQ~Books~FBV~PublishedYear~GT~2000~FSF~PublishedYear~DESC~0
+             Filters down to ALL BOOKS PUBLUSHED AFTER 2000 IN DESCENDING ORDER
+*/
+
+class MeadowEndpointsFilterParser
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+    // Get the comparison operator for use in a query stanza
+    getFilterComparisonOperator(pFilterOperator)
+    {
+        let tmpOperator = '=';
+        switch(pFilterOperator)
+        {
+            case 'EQ':
+                tmpOperator = '=';
+                break;
+            case 'NE':
+                tmpOperator = '!=';
+                break;
+            case 'GT':
+                tmpOperator = '>';
+                break;
+            case 'GE':
+                tmpOperator = '>=';
+                break;
+            case 'LT':
+                tmpOperator = '<';
+                break;
+            case 'LE':
+                tmpOperator = '<=';
+                break;
+            case 'LK':
+                tmpOperator = 'LIKE';
+                break;
+            case 'NLK':
+                tmpOperator = 'NOT LIKE';
+                break;
+            case 'IN':
+                tmpOperator = 'IS NULL';
+                break;
+            case 'NN':
+                tmpOperator = 'IS NOT NULL';
+                break;
+            case 'INN':
+                tmpOperator = 'IN';
+                break;
+            case 'FOP':
+                tmpOperator = '(';
+                break;
+            case 'FCP':
+                tmpOperator = ')';
+                break;
+        }
+        return tmpOperator;
+    }
+
+    addFilterStanzaToQuery(pFilterStanza, pQuery)
+    {
+        if (!pFilterStanza.Instruction)
+        {
+            return false;
+        }
+
+        switch(pFilterStanza.Instruction)
+        {
+            case 'FBV':   // Filter by Value (left-side AND)
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value, this.getFilterComparisonOperator(pFilterStanza.Operator), 'AND');
+                break;
+
+            case 'FBVOR': // Filter by Value (left-side OR)
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value, this.getFilterComparisonOperator(pFilterStanza.Operator), 'OR');
+                break;
+
+            case 'FBL':   // Filter by List (left-side AND)
+                // Just split the value by comma for now.  May want to revisit better characters or techniques later.
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'AND');
+                break;
+
+            case 'FBLOR': // Filter by List (left-side OR)
+                // Just split the value by comma for now.  May want to revisit better characters or techniques later.
+                pQuery.addFilter(pFilterStanza.Field, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'OR');
+                break;
+
+            case 'FBD': // Filter by Date (exclude time)
+                pQuery.addFilter(`DATE(${pFilterStanza.Field})`, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'AND', pFilterStanza.Field);
+                break;
+
+            case 'FBDOR': // Filter by Date (exclude time)
+                pQuery.addFilter(`DATE(${pFilterStanza.Field})`, pFilterStanza.Value.split(','), this.getFilterComparisonOperator(pFilterStanza.Operator), 'OR', pFilterStanza.Field);
+                break;
+
+            case 'FSF':   // Filter Sort Field
+                const tmpSortDirection = (pFilterStanza.Operator === 'DESC') ? 'Descending' : 'Ascending';
+                pQuery.addSort({ Column: pFilterStanza.Field, Direction: tmpSortDirection });
+                break;
+
+            case 'FOP':   // Filter Open Paren
+                pQuery.addFilter('', '', '(');
+                break;
+
+            case 'FCP':   // Filter Close Paren
+                pQuery.addFilter('', '', ')');
+                break;
+
+            case 'FDST':   // Filter Distinct
+                // ensure we don't break if using an older foxhound version
+                if (pQuery.setDistinct)
+                {
+                    pQuery.setDistinct(true);
+                }
+                break;
+
+            default:
+                //console.log('Unparsable filter stanza.');
+                return false;
+                break;
+        }
+
+        // Be paranoid about the instruction
+        pFilterStanza.Instruction = false;
+        return true;
+    };
+
+    parseFilter(pFilterString, pQuery)
+    {
+        if (typeof(pFilterString) !== 'string')
+        {
+            return false;
+        }
+
+        const tmpFilterTerms = pFilterString.split('~');
+
+        if (tmpFilterTerms.length < 4)
+        {
+            return true;
+        }
+
+        let tmpFilterStanza = { Instruction: false };
+
+        for (let i = 0; i < tmpFilterTerms.length; i++)
+        {
+            switch(i % 4)
+            {
+                case 0:  // INSTRUCTION
+                    this.addFilterStanzaToQuery(tmpFilterStanza, pQuery);
+                    //console.log(i+' Instruction: '+tmpFilterTerms[i]);
+                    tmpFilterStanza = (
+                    {
+                        Instruction: tmpFilterTerms[i],
+                        Field: '',
+                        Operator: '',
+                        Value: ''
+                    });
+                    break;
+
+                case 1:  // FIELD
+                    //console.log(i+' Field:       '+tmpFilterTerms[i]);
+                    tmpFilterStanza.Field = tmpFilterTerms[i];
+                    break;
+
+                case 2:  // OPERATOR
+                    //console.log(i+' Operator:    '+tmpFilterTerms[i]);
+                    tmpFilterStanza.Operator = tmpFilterTerms[i];
+                    break;
+
+                case 3:  // VALUE
+                    //console.log(i+' Value:       '+tmpFilterTerms[i]);
+                    tmpFilterStanza.Value = tmpFilterTerms[i];
+                    break;
+            }
+        }
+
+        this.addFilterStanzaToQuery(tmpFilterStanza, pQuery);
+
+        return true;
+    };
+}
+
+module.exports = MeadowEndpointsFilterParser;

package/source/controller/utility/Meadow-Endpoints-Session-Marshaler.js

@@ -0,0 +1,48 @@
+class MeadowEndpointsSessionMarshaler
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+    getSessionData(pRequest)
+    {
+        let tmpSession = Object.assign({}, this._Controller.settings.MeadowEndpointsDefaultSessionObject);
+
+        switch (this._Controller.settings.MeadowEndpointsSessionDataSource || 'Request')
+        {
+            default:
+                this._LogController.warn(`Unknown session source configured: ${_SessionDataSource} - defaulting to Request for backward compatibility`);
+            case 'Request':
+                // noop - already set by orator-session
+                tmpSession = this._Controller.extend(tmpSession, pRequest.UserSession);
+                break;
+            case 'None':
+                break;
+            case 'Header':
+                try
+                {
+                    const tmpHeaderSessionString = pRequest.headers['x-trusted-session'];
+                    if (!tmpHeaderSessionString)
+                    {
+                        break;
+                    }
+                    tmpHeaderSession = JSON.parse(tmpHeaderSessionString);
+                    tmpSession = this._Controller.extend(tmpSession, pRequest.tmpHeaderSession);
+                }
+                catch (pError)
+                {
+                    this._LogController.error(`Meadow Endpoints attempted to process a Header Session String with value [${tmpHeaderSessionString}] and failed -- likely culprit is bad JSON.`)
+                }
+                break;
+        }
+
+        // Do we keep this here for backwards compatibility?
+        // Yes this makes sense here.
+        pRequest.UserSession = tmpSession;
+
+        return tmpSession;
+    }
+}
+
+module.exports = MeadowEndpointsSessionMarshaler;

package/source/controller/utility/Meadow-Endpoints-Stream-RecordArray.js

@@ -0,0 +1,66 @@
+/**
+* Meadow Endpoint Streamer - Stream an array of recods as JSON to an output stream.
+*/
+const libAsyncEachSeries = require('async/eachSeries');
+const JSONStream = require('JSONStream');
+
+class MeadowEndpointsStreamRecordArray
+{
+    constructor(pController)
+	{
+        this._Controller = pController;
+    }
+
+	chunk(pInput, pChunkSize, pChunkCache)
+	{
+		let tmpInputArray = [...pInput];
+		// Note lodash defaults to 1, underscore defaults to 0
+		let tmpChunkSize = (typeof(pChunkSize) == 'number') ? pChunkSize : 0;
+		let tmpChunkCache = (typeof(pChunkCache) != 'undefined') ? pChunkCache : [];
+
+		if (tmpChunkSize <= 0)
+		{
+			return tmpChunkCache;
+		}
+
+		while (tmpInputArray.length)
+		{
+			tmpChunkCache.push(tmpInputArray.splice(0, tmpChunkSize));
+		}
+
+		return tmpChunkCache;
+	}
+
+	streamRecordArray(pResponse, pRecords, fCallback)
+	{
+		// for meadow invoke, writeHead isn't provided, so just call send(), which is the shim it uses...
+		// also, for small arrays, don't bother with the async serialization; this threshold could use tuning
+		if (!pResponse.writeHead || !Array.isArray(pRecords) || pRecords.length < 2500)
+		{
+			pResponse.send(pRecords);
+			return fCallback();
+		}
+
+		pResponse.writeHead(200,
+		{
+			'content-type': 'application/json',
+		});
+
+		const recordJsonMarshaller = JSONStream.stringify();
+		recordJsonMarshaller.pipe(pResponse);
+
+		// we write the records in chunks; doing one per loop is very inefficient, doing all is the same as not doing this at all
+		libAsyncEachSeries(this.chunk(pRecords, 1000), (pRecordChunk, fNext) =>
+		{
+			pRecordChunk.forEach(recordJsonMarshaller.write);
+			setImmediate(fNext);
+		},
+		(error) =>
+		{
+			recordJsonMarshaller.end();
+			fCallback(error);
+		});
+	}
+}
+
+module.exports = MeadowEndpointsStreamRecordArray;

package/source/endpoints/count/Meadow-Endpoint-Count.js

@@ -0,0 +1,49 @@
+/**
+* Meadow Endpoint - Count a Record
+*/
+const doAPIEndpointCount = function(pRequest, pResponse, fNext)
+{
+	let tmpRequestState = this.initializeRequestState(pRequest, 'Count');
+	let fBehaviorInjector = (pBehaviorHash) => { return (fStageComplete) => { this.BehaviorInjection.runBehavior(pBehaviorHash, this, pRequest, tmpRequestState, fStageComplete); }; };
+
+	this.waterfall(
+		[
+			(fStageComplete) =>
+			{
+				tmpRequestState.Query = this.DAL.query;
+				if (typeof(pRequest.params.Filter) === 'string')
+				{
+					// If a filter has been passed in, parse it and add the values to the query.
+					this.parseFilter(pRequest.params.Filter, tmpRequestState.Query);
+				}
+				else if (pRequest.params.Filter)
+				{
+					tmpRequestState.Query.setFilter(pRequest.params.Filter);
+				}
+				return fStageComplete();
+			},
+			fBehaviorInjector(`Count-QueryConfiguration`),
+			(fStageComplete) =>
+			{
+				this.DAL.doCount(tmpRequestState.Query,
+					(pError, pQuery, pCount) =>
+					{
+						tmpRequestState.Result = {Count:pCount};
+						return fStageComplete(pError);
+					});
+			},
+			(fStageComplete) =>
+			{
+				pResponse.send(tmpRequestState.Result);
+				this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, `Delivered recordset count of ${tmpRequestState.Result.Count} for ${this.DAL.scope}.`);
+				return fStageComplete();
+			}
+		],
+		(pError) =>
+		{
+			return this.ErrorHandler.handleErrorIfSet(pRequest, tmpRequestState, pResponse, pError, fNext);
+		}
+	);
+};
+
+module.exports = doAPIEndpointCount;

package/source/endpoints/count/Meadow-Endpoint-CountBy.js

@@ -0,0 +1,40 @@
+/**
+* Meadow Endpoint - Count a Record filtered by a single value
+*/
+const doAPIEndpointCountBy = function(pRequest, pResponse, fNext)
+{
+	let tmpRequestState = this.initializeRequestState(pRequest, 'CountBy');
+	let fBehaviorInjector = (pBehaviorHash) => { return (fStageComplete) => { this.BehaviorInjection.runBehavior(pBehaviorHash, this, pRequest, tmpRequestState, fStageComplete); }; };
+
+	this.waterfall(
+		[
+			(fStageComplete) =>
+			{
+				tmpRequestState.Query = this.DAL.query;
+				tmpRequestState.Query.addFilter(pRequest.params.ByField, pRequest.params.ByValue, '=', 'AND', 'RequestByField');
+				return fStageComplete();
+			},
+			fBehaviorInjector(`CountBy-QueryConfiguration`),
+			(fStageComplete) =>
+			{
+				this.DAL.doCount(tmpRequestState.Query,
+					(pError, pQuery, pCount) =>
+					{
+						tmpRequestState.Result = {Count:pCount};
+						return fStageComplete(pError);
+					});
+			},
+			(fStageComplete) =>
+			{
+				this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, 'Delivered recordset count of '+tmpRequestState.Result.Count+'.');
+				pResponse.send(tmpRequestState.Result);
+				return fStageComplete();
+			}
+		],
+		(pError) =>
+		{
+			return this.ErrorHandler.handleErrorIfSet(pRequest, tmpRequestState, pResponse, pError, fNext);
+		});
+};
+
+module.exports = doAPIEndpointCountBy;

package/source/endpoints/create/Meadow-Endpoint-BulkCreate.js

@@ -0,0 +1,53 @@
+/**
+* Meadow Endpoint - Create a set of Record in Bulk
+*/
+
+const doCreate = require('./Meadow-Operation-Create.js');
+
+const doAPIEndpointBulkCreate = function(pRequest, pResponse, fNext)
+{
+	let tmpRequestState = this.initializeRequestState(pRequest, 'CreateBulk');
+	let fBehaviorInjector = (pBehaviorHash) => { return (fStageComplete) => { this.BehaviorInjection.runBehavior(pBehaviorHash, this, pRequest, tmpRequestState, fStageComplete); }; };
+
+	tmpRequestState.CreatedRecords = [];
+
+	this.waterfall(
+	[
+		(fStageComplete) =>
+		{
+			if (!Array.isArray(pRequest.body))
+			{
+				return fStageComplete(this.ErrorHandler.getError('Bulk record create failure - a valid array of records to create is required.', 500));
+			}
+			pRequest.RecordsToBulkCreate = pRequest.body;
+
+			return fStageComplete();
+		},
+		fBehaviorInjector(`CreateBulk-PreOperation`),
+		(fStageComplete) =>
+		{
+			// TODO: Research parallelism opportunities from custom routes
+			this.eachLimit(pRequest.RecordsToBulkCreate, 1,
+				(pRecord, fCallback) =>
+				{
+					doCreate.call(this, pRecord, pRequest, tmpRequestState, pResponse, fCallback);
+				}, fStageComplete);
+		},
+		fBehaviorInjector(`CreateBulk-PostOperation`),
+		(fStageComplete) =>
+		{
+			return this.doStreamRecordArray(pResponse, tmpRequestState.CreatedRecords, fStageComplete);
+		},
+		(fStageComplete) =>
+		{
+			this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, `Bulk created ${tmpRequestState.CreatedRecords.length} records`);
+			return fStageComplete();
+		}
+	],
+	(pError) =>
+	{
+		return this.ErrorHandler.handleErrorIfSet(pRequest, tmpRequestState, pResponse, pError, fNext);
+	});
+};
+
+module.exports = doAPIEndpointBulkCreate;

package/source/endpoints/create/Meadow-Endpoint-Create.js

@@ -0,0 +1,58 @@
+/**
+* Meadow Endpoint - Create a Record
+*/
+const doCreate = require('./Meadow-Operation-Create.js');
+
+const doAPIEndpointCreate = function(pRequest, pResponse, fNext)
+{
+	let tmpRequestState = this.initializeRequestState(pRequest, 'Create');
+	let fBehaviorInjector = (pBehaviorHash) => { return (fStageComplete) => { this.BehaviorInjection.runBehavior(pBehaviorHash, this, pRequest, tmpRequestState, fStageComplete); }; };
+
+	this.waterfall(
+	[
+		(fStageComplete) =>
+		{
+			if (typeof(pRequest.body) !== 'object')
+			{
+				return fStageComplete(this.ErrorHandler.getError('Record create failure - a valid record is required.', 500));
+			}
+
+			return fStageComplete();
+		},
+		(fStageComplete) =>
+		{
+			doCreate.call(this, pRequest.body, pRequest, tmpRequestState, pResponse, fStageComplete);
+		},
+		(fStageComplete) =>
+		{
+			if (tmpRequestState.RecordCreateError)
+			{
+				return fStageComplete(tmpRequestState.RecordCreateErrorObject);
+			}
+			if (tmpRequestState.CreatedRecords.length < 1)
+			{
+				return fStageComplete(this.ErrorHandler.getError('Unknown record create failure - no created records returned.', 500));
+			}
+
+			tmpRequestState.Record = tmpRequestState.CreatedRecords[0];
+
+			return fStageComplete();
+		},
+		(fStageComplete) =>
+		{
+			pResponse.send(tmpRequestState.Record);
+			return fStageComplete();
+		},
+		(fStageComplete) =>
+		{
+			this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, `Created a ${this.DAL.scope} record ID ${tmpRequestState.Record[this.DAL.defaultIdentifier]}`);
+			return fStageComplete();
+		}
+	],
+	(pError) =>
+	{
+		return this.ErrorHandler.handleErrorIfSet(pRequest, tmpRequestState, pResponse, pError, fNext);
+	});
+};
+
+module.exports = doAPIEndpointCreate;

package/source/endpoints/create/Meadow-Operation-Create.js

@@ -0,0 +1,83 @@
+/**
+* Meadow Operation - Create a record function
+*/
+const doCreate = function(pRecord, pRequest, pRequestState, pResponse, fCallback)
+{
+	// This is a virtual operation
+	let tmpRequestState = this.cloneAsyncSafeRequestState(pRequestState, 'doCreate');
+	let fBehaviorInjector = (pBehaviorHash) => { return (fStageComplete) => { this.BehaviorInjection.runBehavior(pBehaviorHash, this, pRequest, tmpRequestState, fStageComplete); }; };
+
+	if (!Array.isArray(tmpRequestState.ParentRequestState.CreatedRecords))
+	{
+		tmpRequestState.ParentRequestState.CreatedRecords = [];
+	}
+
+	this.waterfall(
+	[
+		(fStageComplete) =>
+		{
+			tmpRequestState.RecordToCreate = pRecord;
+
+			//Make sure record gets created with a customerID
+			if (!tmpRequestState.RecordToCreate.hasOwnProperty('IDCustomer') && this.DAL.jsonSchema.properties.hasOwnProperty('IDCustomer'))
+			{
+				tmpRequestState.RecordToCreate.IDCustomer = tmpRequestState.SessionData.CustomerID || 0;
+			}
+
+			return fStageComplete();
+		},
+		(fStageComplete) => { this.BehaviorInjection.runBehavior(`Create-PreOperation`, this, pRequest, tmpRequestState, fStageComplete); },
+		(fStageComplete) =>
+		{
+			// Prepare create query
+			tmpRequestState.Query = this.DAL.query;
+			tmpRequestState.Query.setIDUser(tmpRequestState.SessionData.UserID);
+			tmpRequestState.Query.addRecord(tmpRequestState.RecordToCreate);
+			return fStageComplete();
+		},
+		(fStageComplete) => { this.BehaviorInjection.runBehavior(`Create-QueryConfiguration`, this, pRequest, tmpRequestState, fStageComplete); },
+		(fStageComplete) =>
+		{
+			// Do the actual create operation with the DAL
+			this.DAL.doCreate(tmpRequestState.Query,
+				(pError, pQuery, pReadQuery, pNewRecord) =>
+				{
+					if (pError)
+					{
+						return fStageComplete(pError);
+					}
+					if (!pNewRecord)
+					{
+						return fStageComplete(this.ErrorHandler.getError(`Error in DAL Create: No record returned from persistence engine.`, 500));
+					}
+
+					tmpRequestState.Record = pNewRecord;
+
+					return fStageComplete();
+				});
+		},
+		(fStageComplete) => { return this.BehaviorInjection.runBehavior(`Create-PostOperation`, this, pRequest, tmpRequestState, fStageComplete); },
+		(fStageComplete) =>
+		{
+			tmpRequestState.ParentRequestState.CreatedRecords.push(tmpRequestState.Record);
+			this.log.requestCompletedSuccessfully(pRequest, tmpRequestState, `Created a record with ${this.DAL.defaultIdentifier} = ${tmpRequestState.Record[this.DAL.defaultIdentifier]}`);
+			return fStageComplete();
+		}
+	],
+	(pError) =>
+	{
+		if (pError)
+		{
+			tmpRequestState.RecordToCreate.Error = pError;
+
+			tmpRequestState.ParentRequestState.RecordCreateError = true;
+			tmpRequestState.ParentRequestState.RecordCreateErrorObject = pError;
+
+			tmpRequestState.ParentRequestState.CreatedRecords.push(tmpRequestState.RecordToCreate);
+		}
+
+		return fCallback();
+	});
+};
+
+module.exports = doCreate;