\nEvery ExpressHappiness project consists of a specific set of files that define the project's routes and behaviour.\nThese files are:\n
\n
Routes Tree Configuration: On this file you'll put / define all\nof the supported routes of your app with all of their details. These details include the method of the route\n(get / post / put / delete), the parameters of the route (parameter type, validation rules) and you can also enable / disable\nthe mock operation. \nFor each route you can define an alias name and also the group(s) that this route belongs to. The \"groups\" that the\nroutes belong to are custom groups, with custom names. The groups that a route belongs to define the middlewares that\nwill be applied to it. More details about grouping and group-specific middlewares will be defined later on.\n
\n
Reusable Params File: There are cases where many routes have the exact same parameter, with the\n exact same type and validation rules. In order to avoid rewriting the same parameter definition again and\n again throughout all of these routes you can define these params once and just reuse them to any of the routes. The file\n that holds the \"reusable params\" definitions is the Reusable Params File.\n These type of parameters are called \"reusable\" params and are defined on the Reusable Fields File
\n
Error Handling Configuration File: At any point of the middlewares chain of any call you can\n trigger errors. Errors of custom types, decorated with custom details. Express Happiness provides an error handling\n mechanism that automatically takes care this errors. The way each custom type's error will be handled is defined on this file.\n The developer has the ability to define whether and what is going to be written to the error.log file,\n what code should be sent back to the client (200, 400, 401, etc) and what data will be served. Finally, on each of these\n error types, the developers can define a set of hook functions to be executed (email send, log to db, whatever). \n All these error handling parameters are defined on the Error Handling Configuration File.
\n
error log: Is just a plain text file holding all logs printed out by the Error Handling mechanism
\n
Controller Functions: This file defines the function that should be executed on each route.\n The main concept here is not to define / write the body of these functions within this file but to have a \"mapper\"\n endpoint though which anyone can easily find out what's going on, on any route. \n The association between routes and controller functions is done by an associative array,\n each key of which is a string, either the full route definition or the route alias and each value the corresponding controller function.\n As mentioned, routes' aliases can be defined on the Routes Tree Configuration File.
\n
\n\n
Starting with it
\nIn order to start, you can just clone this repo to your machine or either follow step\n by step this document.\n
Create your Reusable Params File
\nEach route expects for some params to be passed on call. As mentioned, Express Happiness includes an automatic params\nvalidation mechanism and the only thing you should do is to define the params and the validation rules that apply for\neach route. \nEach parameter, no matter its type, has the following structure: \n
Code Snippet 1. Parameter's basic structure
\n
\nparam: {\n \"key\": \"the-key-name\",\n \"type\": \"one-of-the-supported-types\",\n \"humanReadable\": \"short title of the param\",\n \"description\": \"A human-readable description of the parameter\",\n \"mandatory\": \"boolean-true-or-false\"\n}\n
\n \nNot all of these characteristics are mandatory nor are they all. For each parameter type, special characteristics apply.\nFor example, for type \"int\", the definition object of the param may (optionally) include \"min\" and \"max\" keys, etc. \n The list of the supported parameter types is:\n
Table 1. Supported parameter types
\n
\n
\n
int
\n
Integer
\n
\n
\n
date
\n
Date
\n
\n
\n
oneof
\n
The value must be one of the specified
\n
\n
\n
boolean
\n
Boolean
\n
\n
\n
numeric
\n
any number
\n
\n
\n
string
\n
String
\n
\n
\n
array
\n
Array
\n
\n
\n
object
\n
Object
\n
\n
\n\nThe full list of the supported attributes for each param are listed below:\n
Table 2. Supported param attrs
\n
\n\n
\n
Attribute key
\n
Mandatory
\n
Description
\n
Applies to
\n
\n\n\n
\n
key
\n
yes
\n
the key name of the parameter. For example, if on a route you expect for a param with the name \"x\", then the key\nof this param is \"x\"
\n
all types
\n
\n
\n
type
\n
yes
\n
the type of the parameter. Might be one of: \"int\", \"date\", \"oneof\", \"boolean\", \"numeric\", \"string\", \"array\" and \"object\"
\n
\n
\n
\n
humanReadable
\n
no
\n
a short title of the parameter. This is used by the parameters validator on the error texts that exports on validation failures
\n
all types
\n
\n
\n
description
\n
no
\n
the description of the parameter. It will be used on the auto-generated documentation of your API
\n
all types
\n
\n
\n
mandatory
\n
no
\n
defines whether the parameter is mandatory or not. If it's missing the parameter is not mandatory
\n
all types
\n
\n
\n
validationFailureTexts
\n
no
\n
An object containing the text messages that will sent back to the client for all (or any) cases that the validation fails. For example,\nif a mandatory field is missing the text that will be sent back to the client is defined on the key \"mandatory\" of this object, etc. The\nsupported keys of this object are listed on the very next table that follows.
\n
all types
\n
\n
\n
min
\n
no
\n
the minimum value (including this) that a param can accept
\n
int, numeric
\n
\n
\n
max
\n
no
\n
the maximum value (including this) that a param can accept
\n
int, numeric
\n
\n
\n
minChars
\n
no
\n
the minimum characters that a string's type parameter's value might have
\n
string
\n
\n
\n
maxChars
\n
no
\n
the maximum characters that a string's type parameter's value might have
\n
string
\n
\n
\n
validationString
\n
yes
\n
the format that a date value should have. The formats are identical as on moment.js
\n
date
\n
\n
\n
minLength
\n
no
\n
the minimum length an array-type value should have
\n
array
\n
\n
\n
maxLength
\n
no
\n
the maximum length an array-type value should have
\n
array
\n
\n
\n
acceptedValues
\n
yes
\n
an array listing all the acceptable values for this param
\n
oneof
\n
\n
\n
regexp
\n
no
\n
a regular expression to check the provided value against
\n
string
\n
\n
\n
keys
\n
no
\n
an object that specifies the expected structure of an object type parameter
\n
object
\n
\n\n
\n\nThe supported keys of the validationFailureTexts are:\n
the type of the field's value is not of the defined/expected field's type
\n
\n
\n
mandatory
\n
a mandatory filed is missing
\n
\n
\n
min
\n
the either of type int or numeric field's value is lower than the minimum accepted, according to the min attribute of the field's definition
\n
\n
\n
max
\n
the either of type int or numeric field's value is greater than the maximum accepted, according to the max attribute of the field's definition
\n
\n
\n
minChars
\n
the characters of the provided string are less than the minimum accepted, according to the minChars attribute of the field's definition
\n
\n
\n
maxChars
\n
the characters of the provided string are more than the maximum accepted, according to the maxChars attribute of the field's definition
\n
\n
\n
validationString
\n
the value provided for the field of type date is not compatible with the validationString of the field's definition
\n
\n
\n
minLength
\n
the length of the array passed on the specific field's value is lower than the minimum accepted, according to the minLength attribute of the field's definition
\n
\n
\n
maxLength
\n
the length of the array passed on the specific field's value is greater than the maximum accepted, according to the maxLength attribute of the field's definition
\n
\n
\n
acceptedValues
\n
the value of the, of type oneof, field is not present on the acceptedValues array on the field's definition
\n
\n
\n
regexp
\n
the string provided does not comply with the regular expression from the regexp property of the field's definition
\n
\n\n
\n\nSo, as an example:\n
Code Snippet 2. Parameter's structure including validationFailureTexts object
\n
\nparam: {\n \"key\": \"user_age\",\n \"type\": \"int\",\n \"humanReadable\": \"Age\",\n \"description\": \"The age of the user\",\n \"mandatory\": \"true\",\n \"min\": 18,\n \"validationFailureTexts\": {\n \"mandatory\": \"Please provide your age\",\n \"min\": \"Sorry, you must be at least 18 years old\"\n }\n}\n
\n\nIn such case if the submitted value for the \"age\" is under 18 (let's say 17) then on the \"errors\" array of the response there will be the\ntext \"Sorry, you must be at least 18 years old\". If the key \"min\" was missing from the \"validationFailureTexts\" object (of if\nthe \"validationFailureTexts\" was missing at all on the field's definition), the error text that would be included on the errors array would be the default:\n\"Age must be greater or equal to 18. 17 provided.\" \nFinally, in the case that there was the \"humanReadable\" key missing from the field's definition, then the error text would be:\n\"user_age must be greater or equal to 18. 17 provided.\"\n
\nNow it's time to proceed with your Reusable Params File. \nThe reusable params file is just a module that exports an object. This object has a number of keys. Each\nkey holds another object which represents the definition of a parameter. \nThe name of the key is the way you'll refer to the parameter from the Routes Tree Configuration File. \nSo, let's assume that you want to define two reusable parameters on this file, parameter \"id\" and parameter\n\"cat_id\". Here's a possible / valid definition of these two params in the Reusable Params File:\n
Code Snippet 3. Example of Reusable Params File
\n
\nmodule.exports = {\n id:{\n key:'id',\n type:'int',\n humanReadable: 'organization id',\n description:'The Organization from which data is requested',\n mandatory:true\n },\n category: {\n key:'cat_id',\n type:'oneof',\n humanReadable: 'Product category',\n description:'The category of the product',\n mandatory:false,\n acceptedValues: ['shoes', 'clothes'],\n validationFailureTexts: {\n acceptedValues: 'Sorry, only shoes or clothes categories are supported'\n }\n }\n}\n
\nPay attention that we have a unique name for each parameter defined here, which is the key of the\nexported module. This name will be used in the Routes Tree Configuration File in order to load and\ndefine the parameters that each route will expect for. \nThough, each of these params have a \"key\" attribute. This is the name of the parameter as we expect it\nduring the actual calls that our service will receive.\n\n\n
Defining object type params
\nAs mentioned, one of the supported param types is the \"object\". Also, one of the supported on object-type parameter's attributes\nis \"keys\". \nYou can use the \"keys\" attribute of an object parameter in order to define (to any depth) the expected structure of the object\nand not only this. You can apply / define validation rules of each of them, no matter which depth it is. Here's an example: \nLet's suppose that on a specific call we expect for a parameter with the name \"user_data\" which will hold the user's information\nin a well defined structure. Both the structure of the expected object and the validation rules that apply to it are made\nobvious through the following parameter definition:\n
Code Snippet 4. Example of an object parameter
\n
\nuser:{\n key:'user_data',\n type:'object',\n humanReadable:'User data',\n description:'Full user information',\n mandatory:true,\n keys:{\n gender:{\n type:'oneof',\n mandatory:true,\n acceptedValues: ['male', 'female'],\n validationFailureTexts: {\n mandatory: 'Please specify your gender',\n acceptedValues: 'Please pick between male and female'\n }\n },\n country:{\n type:'oneof',\n acceptedValues:['Greece', 'Sweden', 'Australia', 'Romania']\n },\n name:{\n type:'object',\n keys:{\n first:{\n mandatory:true,\n type:'string'\n },\n last:{\n mandatory:true,\n type:'string',\n validationFailureTexts: {\n mandatory: 'Please specify your last name'\n }\n },\n middle: {\n mandatory: false,\n type: 'string'\n }\n }\n }\n }\n}\n
\nSo, as you can see, not only we define the structure of the expected object but we can define the validation rules that might\napply to any of the keys of the object. Please mention that the \"name\" key is an object itself and it also contains the \"keys\"\nparameter which holds the information regarding the expected keys of it. There's no limit on the depth of the nested objects\nand parameters. \nThe \"keys\" param is an object which holds a set of keys. These keys represent / map the expected keys of the object. \nThe attributes of each one of these keys are identical with the attributes used in plain (not-object) parameters. All attributes\nof table 2 apply just fine to all nested keys of all objects. The only difference between the definition of a plain parameter\nand the definition of an object's key is that on the object key's definition there's no \"key\" attribute. The \"key\", that is\nthe expected name of the key on the provided object during a call, is identical to the name of the key itself. E.g. on the\nspecific example we expect the user_data.name.first to be present. \nThis has been implemented this way for two reasons:\n
\n
There's no need and no way to refer to a nested key from services such as the FieldsLoader (we'll see about that later on)
\n
We wanted to mimic the structure of the object in an one-to-one mapping
\n
\nDuring the parameters validation process, which we'll analyse on following chapter, the full object is been validated according\nto the definition of it. Don't worry this process is 100% asynchronous, so you can go ahead and create as deep, as long and\nas complex object parameter definitions. It won't block your app during validation.\n\n
Routes Tree Configuration File
\nNow that we've defined the parameters that we're going to (re)use on our endpoints, it's time to define\nthese calls. Of course you can always come back to the Reusable Params File and update it with new\nones.\nAll of the supported routes of our application are defined in this very file. \nIn order to be able to reuse the parameters we defined in the Reusable Params File, we need the (built in) FieldsLoader\nmodule. For this the structure / format of our Routes Tree Configuration File should look like this:\n
Code Snippet 5. Basic structure of the Routes Tree Configuration File
\n
\nmodule.exports.conf = function(fieldsLoader){\n return {\n routes:{\n // here go all of the supported routes of the application\n }\n }\n};\n
\n\nYou might have noticed the term \"Tree\" in the name of the \"Routes Tree Configuration File\". Before further analysing the\nway we can define your routes in here, it's good to mention a few things regarding its concept. \nIn an application there might be routes of the same url (e.g. /a/b) but of different types (e.g. GET, POST). Also, in\nan application there might be routes that do something and also subroutes of it that do something else. For example,\nthere might be the route /a/b and also the route /a/b/c. \nThe way the routes are defined on the Routes Tree Definition File respect both of the above facts. On any given path you\ncan separately define the various supported call types and then you can continue deeper defining the supported subroutes of it. \nIn the specific example here's a possible / valid Routes Tree Configuration File:\n
Code Snippet 6. Routes Tree Configuration File including paths and endpoints
\n
\nmodule.exports.conf = function(fieldsLoader){\n return {\n routes:{\n a:{\n subRoutes: {\n b: {\n get: {\n // here goes the GET /a/b route definition\n },\n post: {\n // here goes the POST /a/b route definition\n },\n subRoutes: {\n c: {\n get: {\n // here goes the GET /a/b/c route definition\n }\n }\n }\n }\n }\n }\n }\n }\n};\n
\n\nIn general, the tree that we are defining here consists of paths and endpoints. Everything starts on the \"routes\" parameter\nof the returned object. \"a\" represents a path, the path \"/a\". This path has subRoutes, like \"/a/b\". So, we define these\nsubroutes on the \"subRoutes\" parameter of it. \n\"b\" is a path itself as well. Following the object's structure, is obvious that it represents the path \"/a/b\". A path might\nhave (or might not have) endpoints. For example the path \"/a\" does not have any endpoints. Though, path \"/a/b\" has get and post\nendpoints. \nThe endpoints are defined by the use of the corresponding key (one of \"get\", \"post\", \"put\", \"delete\"). The endpoints are the \"leafs\"\nof this tree while the paths act as the branches. \nA branch can have sub-branches and leafs. A leaf cannot have neither sub-branches nor sub-leafs, and that's we call then \"endpoints\". \nWithin the \"subRoutes\" parameter of any path we can only define paths. \nOn any endpoint we can define the fields that we're expecting. \nHere's a table with all the supported attributes of each element:\n
Table 4. Path's supported attributes
\n
\n\n
\n
Attribute name
\n
Description
\n
\n\n\n
\n
groups
\n
an array containing all the groups the path belongs to
\n
\n
\n
subRoutes
\n
an object which keys will represent the next sub-section of the path
\n
\n
\n
any of the supported call types (one of \"get\", \"post\", \"put\", \"delete\")
\n
defines an endpoint to the specific path. E.g. by placing the \"get\" key on a path it's value must be an object defining\nthe characteristics of the specific endpoint
\n
\n\n
\n\n
Table 5. Endpoints's supported attributes
\n
\n\n
\n
Attribute name
\n
Description
\n
\n\n\n
\n
groups
\n
an array containing all the groups the path belongs to
\n
\n
\n
alias (optional)
\n
a string representation / alias name of the specific endpoint
\n
\n
\n
description (optional)
\n
a human readable description of the endpoint. This will be used on the auto-generated documentation of your API
\n
\n
\n
fields (optional)
\n
an array containing all the fields that are expected on this endpoint. It will be used both by the validator and the\nauto-generated documentation process. If your endpoint does not expect any parameters or you don't want to apply any\nparams validation you can just skip it
\n
\n
\n
mock
\n
in cases you want a specific endpoint to serve mock data just put the mock attribute and set it to true
\n
\n\n
\n\n
Groups
\nBoth on tables 4 and 5 you might have noticed the \"groups\" attribute. The \"groups\" attribute helps us organize / categorize\nall of our endpoints into categories / groups. \nThe grouping mechanism follows a waterfall inheritance mechanism, just like inheritance works on html elements. Every child inherits\nby default the groups of its closest parent. If its closest parent has no group definition then that means it inherits its own\nclosest parent's groups etc. \nFor any element in our tree (either endpoint or path), this inheritance goes all the way up until we have an explicit groups definition. \nSo if you have endpoints / routes defined on /admin/* and all belong to a specially restricted area of your application, where\nadmin authentication should take place, the only thing you have to do is to define on the /admin path the groups equal to ['admin']. All\nof the child paths and endpoints of it will inherit this groups definition. \nAt any point, at any path or endpoint, you can explicitly define the groups attribute. By this way, any inherited value of the\nattribute \"groups\" will be ignored and the explicitly defined will prevail. \nBy organizing the endpoints into groups on the Routs Tree Configuration File gives us the opportunity apply middlewares\nspecially developed for each of these groups. We'll see more details on this later on. \nFinally, as you might have noticed, groups is an array. That means that for an endpoint belonging to more than one groups,\nall middlewares of all groups it belongs to will be applied in the sequence the group names have been placed within the array.\n\n
Alias / Mock operation
\nThe \"alias\" attribute of each endpoint gives us a way to refer to this endpoint from any other part of the Express Happiness\necosystem. The most important usage of this \"alias\" has to do with the mock operation. As mentioned on table 5, along with the\n\"alias\" attribute each endpoint (optionally, default = false) might have a \"mock\" attribute set to true. \nWe will analyse mock operation in details in a following part of this document, though keep just one thing in mind for now.\nIf any of the endpoints has been set to server mock data then a file containing the mock response should be present somewhere in\nyour hard drive. The folder that contains all mock files is defined on ExpressHappiness invocation, though the actual name\nof the file, for each endpoint, should be identical with its alias.\n\n
fields
\nThe fields is an array containing all the fields that the specific endpoint supports / expects. As explained, all of the\nfields / params have a very specific definition pattern that has been analyzed on the Reusable Params File section. \nThe fields array might \"load\" fields from the reusable fields or can either include newly defined params. \nIn order to load a parameter from the params defined on the Reusable Params File you should use the method \"getField\" of the\nFieldsLoader module that comes with the ExpressHappiness framework. \nHere is a complete example, using the fields defined on code snippet 3:\n
Code Snippet 7. Routes Tree Configuration File example with fields loading
\n
\nmodule.exports.conf = function(fieldsLoader){ // mind the \"fieldsLoader\" argument\n return {\n routes:{\n a:{\n subRoutes: {\n b: {\n get: {\n alias: 'a_b_get',\n description: 'a dummy description of a dummy endpoint',\n fields: [\n fieldsLoader.getField('id'),\n fieldsLoader.getField('category', {\n mandatory:true\n }),\n {\n key: 'size',\n mandatory: true,\n type: 'numeric'\n }\n ]\n }\n }\n }\n }\n }\n }\n};\n
\n\nAs you can see, on the GET \"/a/b\" endpoint we have defined three fields:\n
\n
by loading the \"id\" field. The resulting field is identical as the definition of the field on the Reusable Params File (code snippet 3)
\n
by loading the \"category\" field and passing second argument on getField. The \"getField\" method of FieldsLoader takes a second optional\nattribute. This attribute is an object. All own keys of this object that are included in the supported params attrs list (table 2) will overwrite the\nones defined on the Reusable Params File.
\n
A totally new parameter. There are cases where a parameter might appear only once and only in one endpoint. In such cases there's\nabsolutely no need to define it on the Reusable Params File but, instead, you can define it directly on the \"fields\" array of the endpoint.
\n
\n\n
Dynamic routes
\nA question that arises has to do with the dynamic routes (e.g. \"/a/b/:c\"). This is of course supported by ExpressHappiness\nand you can totally use it on your Routes Tree Configuration File. You can access these fields as you would usually do through\nthe req object of express.\nHere's a simple demonstration on how to define routes including dynamic params:\n\n
Code Snippet 8. Dynamic Route Params
\n
\nmodule.exports.conf = function(fieldsLoader){ // mind the \"fieldsLoader\" argument\n return {\n routes:{\n a:{\n subRoutes: {\n \":b\": { // check the \":b\" on the subRoute key\n get: {\n // endpoint definition\n }\n }\n }\n }\n }\n }\n};\n
\n\n
Error Handling and Error Handling Configuration File
\nThe way errors are handled by Express Happiness is centralized and configurable. All errors, including the unknown, are\nhandled by the framework itself and the developer has the ability to configure the behaviour of the app in each error type.\nExpress Happiness also provides the ability to define custom error types, define the behaviour of the app in each of them,\ntrigger such errors from anywhere in your middlewares chain and let the framework take care of them accordingly. \nThe way each error type should be treated by the application is defined on the Error Handling Configuration File.\n The basic structure of this file is the following:\n
\nexports.errors = {\n undefinedError:{\n log:true,\n humanReadable: 'Unresolved error code',\n sendToClient: {\n code:500,\n data: 'ErrCode: 1 - There was an error fulfilling your request at the moment. Please try again in a while'\n },\n hooks:[\n // here you can put whatever you want\n ]\n },\n '404':{\n log:true,\n sendToClient: {\n code:404,\n data:'Invalid route'\n }\n },\n 'my_custom_error_code':{\n log:false,\n sendToClient:{\n code:500,\n data:'There was an error fulfilling your request'\n }\n }\n}\n
\n\nThe Error Handling Configuration File exports an object. Each object key represents the \"type\" of the error. So, in our\nexample, if an undefined error gets triggered by the app, our application will log it, it will write to the log file the\ntext \"Unresolved error code\" and the client will receive a 500 code along with the body \"ErrCode: 1 - There was an error\nfulfilling your request at the moment. Please try again in a while\".\nLet's dive deeper and see which attributes are supported for each error type defined on this file.\n
Table 6. Supported attributes on error configuration
\n
\n\n
\n
Attribute name
\n
Type
\n
Mandatory
\n
Description
\n
\n\n\n
\n
log
\n
boolean
\n
no (default: false)
\n
If log is set to true, this error will be logged to the error.log file
\n
\n
\n
humanReadable
\n
string
\n
no
\n
a human readable description of the error. This is what it will get logged to the error.log file if log is set to true
\n
\n
\n
sendToClient
\n
object with two keys: code and data
\n
no
\n
with the use of this attribute you can define the response code and the response body that will be sent back to the client. If you\nwant to send to the client the details of the error object just put there (in quotes) 'err.details'
\n
\n
\n
hooks
\n
array
\n
no
\n
a list of functions to be executed whenever an error of this type occurs. The hook functions should take 3 arguments:\n
\n
req (the req object)
\n
errorDefinitionObject (the error definition object taken from the Error Handling Configuration File)
\n
err (the actual error triggered during the call stack)
\n
\nThese hook functions get executed before your app responds to the client they are not part of the calls chain (they do not\nact as middlewares)\n
\n
\n\n
\n\n
Triggering Errors
\nOnce you define all of your error on the Error Handling Configuration File you can at any time, from anywhere on your code\ntrigger any of these by the use of this, simple, code:\n
Code Snippet 10. Triggering errors
\n
\nvar err = new Error();\nerr.type = 'my_custom_error';\nerr.details = 'The details of the error. Might be either a string, such as this, or any other data type (object, array etc)';\nreturn next(err);\n
\n\nIn order for this part of code to work you must have the \"next\" function available.\nFot those who are not that familiar with \"next\" function, please have a look here.\n Once you trigger this event the rest is on Express Happiness to take care of, according to the Error Handling Configuration File.\n\n
Predefined Errors
\nExpress Happiness comes with a series of error types predefined. These are:\n
\n
undefinedError It's triggered for errors that don't belong to any of the defined errors. It's default configuration\nis: \n
\n{\n log: true,\n humanReadable: 'There is no mock data available for this route yet',\n sendToClient: {\n code: 404,\n data:'There is no mock data available for this route yet'\n }\n}\n
\n
\n\n
underDevelopment It's triggered in cases there's no controller function defined for a specific route.\nIt's default configuration is: \n
\n{\n log: false,\n humanReadable: 'A call to a route under development has been made',\n sendToClient:{\n code:501,\n data:'This route is currently under development'\n}\n
\n
\n
\nThe default behaviour on any of these errors can be altered by redefining them on the Error Handling Configuration File.\n\n
error.log file
\nAs mentioned earlier in this document, Express Happiness logs errors on an error log file. This file is defined on application\nstart. Express Happiness does not log all the errors but only those which have log:true on their definition on the Error\nHandling Configuration File. \nWhat's been logged on this document, for each error, is:\n
Code Snippet 12. Error Line structure logged on the error log file
\n
\ndate | error code | route | human readable explanation of the error | error details\n
\n\n
Mock Operation
\nFor any endpoint that you define on your Routes Tree Configuration File, you have the chance to put it in mock operation\nstatus. By \"mock operation status\" we mean that whenever a user hits the endpoint a static, predefined, mock response will\nbe served. \nIn order to do that you need two things:\n
\n
Configure the endpoint to serve only mock data
\n
Create a JSON file and put it in you mock files folder
\n
\n\n
How to set mock operation on
\nThere are multiple ways to do that. First of all, in order to enable mock operations you have to set the mockData operation\non during the initialization of your application. We will see more details regarding the initial configuration object\npassed on application start later on, though for now just keep in mind that when we start our application we pass a configuration\nobject which on \"mockData\" key holds an object that defines the folder of your mock files and the flag that set mock operation\non or off. \nHaving our mock folder defined and set mock operation to on we can force an endpoint to serve mock data by:\n
\n
Putting in our mock files folder a file with the name --endpoint-alias--.json, where \"--endpoint-alias--\" is the alias\nof the endpoint defined on the key \"alias\" of the endpoint on the Routes Tree Configuration File
\n
Setting the operation status of the endpoint to mock by setting the \"mock\" attribute of the endpoint on the Routes Tree\nConfiguration File to true
\n
Or by passing the parameter \"mock\" equals to 1 during the call
\n
\nBy this way, whenever you hit the specific endpoint you'll always get back the mock data defined on the specified file on\nthe mock files folder.\n\n
Controller Functions
\nUp to now we've seen almost everything regarding the definition process of an endpoint, the params validation and the error\nhandling mechanisms but we've said nothing regarding the actual controller function. \nAssuming that a call passes all the middlewares, all the checks and it's not on mock operation status it reaches to the point\nwhere something actual needs to take place, a controller function should take care of the call. \nAll controller functions are defined in a single file. As stated in the beginning of this document, the actual aim of this\narchitectural decision is not, of course, to pack all the code within this file but more to have one single point where you\ncan assign responsibilities and define the controllers of all of your routes in a clean and readable way. \nThis single file is called Controller Functions File and it looks like this:\n\n
Code Snippet 12. Example of Controller Functions File
\nIt's just a mapping of all controller functions to the routes. As you can see from the example snippet 12, the Controller\nFunctions File should export an array. An associative array the keys of which are alias name of each route and the values\nthe corresponding controller functions of them. \nThe controller function for each endpoint is in the exact same format as a simple controller function that you would define\nif you used express without Express Happiness. That is:\n
Code Snippet 13. Controller Function format
\n
\nvar my_controller_function = function(req, res, next){\n // do your magic here\n}\n
\nThe third argument (next) is optional though if you want to use the automatic error handling mechanism within these functions\n(that means to create a custom error, trigger it and let the Error Handling mechanism take care of it) you\ncertainly need the next function (see code snippet 10).\n\n
Application Configuration on start
\nHaving the full of your application configured it's now time to fire it up. Express Happiness starts with the command:\n
Code Snippet 15. Starting your Express Happiness Server
\n\nFirst thing to do is to create a new Express Happiness instance. This is done by calling \"new expressHappiness\" function.\nThis function takes three parameters:\n
\n
app: the application initialized by the express() function invocation
\n
router: The Router object provided by express which we can get through express.Router() invocation
\n
configuration: a configuration object that sets the full Express Happiness environment up. Here we define the\npath of each file needed by EH and also the mock operation configuration.
\n
\n\nAfter creating the EH instance we call the \"generate\" function of it. The \"generate\" function takes three parameters:\n
\n
route path: this is the base url that our application will support. For example if we are developing a REST\nAPI that listens to paths under /v1/ then we don't need to define this on the Routes Tree Configuration File. We can\ndefine it here by passing the '/v1' value on the first argument of the generate function
\n
pre-validation middlewares: On the middlewares chain that are been executed on each call on our application,\nEH always includes a middleware that performs the params validation for the given endpoint. The second argument\nof the \"generate\" function provides us the ability to define a series of middlewares we want to get executed before reaching\nthe params validation step. The middlewares defined here, most often have to do with authentication issues. \nThe way we define our middlewares provides us the ability to explicitly define which middlewares should be executed according\nthe group that each route belongs to (see table 5). As mentioned, each endpoint might belong to one or more groups and this\nis defined by the \"groups\" attribute (which holds an array). So, in our example for all endpoints that belong to the 'userAccess' group\nthe middlewareA and middlewareB functions will be executed before the middlewares chain reaches the params validation step. For\nall middlewares that belong to the 'adminAccess' group the middlewareC and middlewareD will be executed before the params\nvalidation middleware gets execute and so on. \nIf we want to define pre-validation middlewares for all of our endpoints, no matter the groups they belong to, we can use\nthe \"eh-allRoutes\" key to define them. All middlewares included on this array are going to be executed, in the order they\nappear within the array, on all of our endpoints.\n
\n
post-validation middlewares: The exact same things stand here. The third argument of the \"generate\" function\nexpects an object that though its keys defines the middlewares to be executed after the params validation process, on\nour routes, depending on the groups they belong to.\n
\n
\n\nThe form of our middlewares should be the typical middleware form of express: function(req, res, next).\n\n
Auto-generated API documentation
\nAfter defining all of your endpoints with types and parameters on the root of your application there will be the documentation\nof your API. So, for example, if you run your app on localhost, port 7000, on http://localhost:7000 you'll find an\nauto-generated REST API documentation page.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"
},
{
"path": "RESTcallsValidator.js",
"content": "var erH, reusableRequiredFields;\nvar validator = require('validator');\nvar moment = require('moment');\nvar restConf = {};\n\nexports.assignConf = function(conf){\n restConf = conf;\n}\n\nexports.init = function(confObj){\n errorHandler = require('./ErrorHandler.js');\n erH = new errorHandler(confObj.errorFile, confObj.errorsConfigurationFile);\n reusableRequiredFields = require(confObj.reusableFieldsFile);\n}\n\nvar validateEmail = function(email){\n var re = /^[a-zA-Z0-9+._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,6}$/;\n return re.test(email);\n}\n\nvar hasTheErrorKey = function(field, errorKey){\n if(field.validationFailureTexts != null && field.validationFailureTexts != undefined){\n if(field.validationFailureTexts[errorKey] != null && field.validationFailureTexts[errorKey] != undefined){\n return field.validationFailureTexts[errorKey]\n }\n }\n return false;\n}\n\nvar unitValidator = {\n int: function(field, value, path, errors, callback){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n if(!validator.isInt(value)){\n var er_message = hasTheErrorKey(field, 'type');\n if(er_message === false){\n errors.push(fieldNameOnResponse + ' must be an integer. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n } else {\n if(!!field.min){\n if(value < field.min){\n var er_message = hasTheErrorKey(field, 'min');\n if(er_message === false){\n errors.push(fieldNameOnResponse + ' must be greater or equal to ' + field.min + '. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n }\n if(!!field.max){\n if(value > field.min){\n var er_message = hasTheErrorKey(field, 'max');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be lower or equal to ' + field.max + '. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n }\n }\n callback();\n },\n\n date: function(field, value, path, errors, callback){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n var momentObj = moment(value, field.validationString);\n if(!momentObj.isValid()){\n var er_message = hasTheErrorKey(field, 'validationString');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be a date in the format: ' + field.validationString + '. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n } else {\n // in case of dates, for easiness we keep the momentObj representation of the passed variable, no matter\n // which is the format of the date that we expect\n //req.filteredParams[path.join('.') + field.key].momentObj = momentObj;\n }\n callback();\n },\n\n oneof: function(field, value, path, errors, callback){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n if(field.acceptedValues.indexOf(value) == -1){\n var er_message = hasTheErrorKey(field, 'acceptedValues');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be one of ' + field.acceptedValues.join(', ') + '. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n callback();\n },\n\n boolean: function(field, value, path, errors, callback){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n if(value !== true && value !== false && value !== 'true' && value !== 'false'){\n var er_message = hasTheErrorKey(field, 'type');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be a boolean. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n callback();\n },\n\n numeric: function(field, value, path, errors, callback){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n if(!validator.isFloat(value)){\n var er_message = hasTheErrorKey(field, 'type');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be a number. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n callback();\n },\n\n email: function(field, value, path, errors, callback){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n if(!validateEmail(value)){\n var er_message = hasTheErrorKey(field, 'type');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be a valid email address. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n callback();\n },\n\n string: function(field, value, path, errors, callback){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n if(!!field.minChars){\n if(value.length < field.minChars){\n var er_message = hasTheErrorKey(field, 'minChars');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be of at least ' + field.minChars + ' long. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n }\n if(!!field.maxChars){\n if(value.length > field.maxChars){\n var er_message = hasTheErrorKey(field, 'maxChars');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be of at max ' + field.maxChars + ' long. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n }\n if(!!field.regexp){\n var er_message = hasTheErrorKey(field, 'type');\n try{\n var passes = field.regexp.test(value);\n if(!passes){\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' do not match the provided regular expression');\n } else {\n errors.push(er_message);\n }\n }\n } catch(err){\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' do not match the provided regular expression');\n } else {\n errors.push(er_message);\n }\n }\n }\n callback();\n },\n\n array: function(field, value, path, errors){\n var fieldNameOnResponse = field.humanReadable || path.join('.');\n\n if(!(variable.constructor === Array)){\n var er_message = hasTheErrorKey(field, 'type');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be of type array. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n if(!!field.minLength){\n if(value.length < field.minLength){\n var er_message = hasTheErrorKey(field, 'minLength');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be of at least of ' + field.minLength + ' length. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n }\n if(!!field.maxLength){\n if(value.length > field.maxLength){\n var er_message = hasTheErrorKey(field, 'maxLength');\n if(er_message === false) {\n errors.push(fieldNameOnResponse + ' must be of max length ' + field.maxLength + '. ' + value + ' provided.');\n } else {\n errors.push(er_message);\n }\n }\n }\n callback();\n }\n\n};\n\n\nvar firstLevelIterator = function(fields, errors, req, func, callback){\n var index = 0;\n var done = false;\n var iterations = fields.length;\n var loop = {\n next: function(){\n if(done){\n return;\n }\n\n if(index < iterations){\n var self = this;\n var theField = fields[index];\n unitValidate(theField, errors, req, [theField.key],\n function(){\n index++;\n func(self);\n }\n );\n } else {\n done = true;\n callback();\n }\n }\n }\n\n loop.next();\n return loop;\n}\n\n\nvar validate = function(obj, errors, req, path, func, callback) {\n var index = 0;\n var done = false;\n var iterations = Object.keys(obj.keys).length;\n var objKeys = Object.keys(obj.keys);\n var loop = {\n next: function() {\n if (done) {\n return;\n }\n\n if (index < iterations) {\n var newPath = path.slice();\n newPath.push(objKeys[index]);\n var self = this;\n unitValidate(obj.keys[objKeys[index]], errors, req, newPath, function(){\n index++;\n func(self);\n });\n\n } else {\n done = true;\n callback();\n }\n }\n };\n\n loop.next();\n return loop;\n};\n\n/*\n @unit: the unit to be validated taken from the signature\n @req: the request object\n @path: the base path of the current unit. It's an array\n @isRoot: a boolean indicating whether the passed unit is the root definition object or not\n @unitValidator: an instance of the unitValidator object defined above\n @callback: the callback to be called after the validation process\n */\nvar unitValidate = function(unit, errors, req, path, callback){\n var get = req.expressHappiness.get;\n var set = req.expressHappiness.set;\n\n // step 1: check if the parameter is present if it's mandatory according to the signature\n var mandatoryIssue = false;\n if(path.length > 0){\n if(unit.mandatory){\n try{\n var test_var = get(path[0]);\n for(var i=1; i 0) {\n var err = new Error();\n err.type = 'invalidAttrs';\n err.details = errors;\n return next(err);\n } else {\n return next();\n }\n });\n }\n}\n\nvar turnToFiltered = function(params){\n var filtered = {};\n for(k in params){\n filtered[k] = {\n value: params[k]\n };\n }\n return filtered;\n}"
},
{
"path": "conf/conf.js",
"content": "var path = require('path');\n\nexports.conf = {\n errorLogFile: path.resolve(__dirname, '../') + '/logs/error.log',\n mockOperations:{\n \"get:/kpis/traffic\":false,\n \"get:/kpis/traffic/powerHours\": false,\n \"get:/kpis/traffic/entrances\":false,\n \"get:/kpis/dwellTime\":false,\n \"get:/kpis/loyalty\":false,\n \"get:/kpis/grossShoppingHours\":false,\n \"get:/kpis/shoppersVsTravellers\":true,\n \"get:/kpis/mallUse\":true,\n \"get:/kpis/areaUse\":true,\n \"get:/kpis/visitFrequency\":true,\n \"get:/kpis/abandonmentRate\":false,\n \"get:/kpis/drawRate\":false,\n \"get:/kpis/opportunity\":false,\n \"get:/kpis/hierarchy\": true,\n \"get:/sites/:site_id/locations\": false\n },\n jwtSecret: 'N##$%W$&SFGHY$$^#W#%YLK\"HBH4l5hjhbkdsljly5%$elawkjgy3%Y4foijfAWT$QTJQALDGKSDJFY$%L^KJ%^'\n};\n"
},
{
"path": "conf/errors.js",
"content": "exports.errors = {\n undefinedError:{\n log:false,\n humanReadable: 'Unresolved error code',\n sendToClient: {\n code:200,\n data: 'ErrCode: 1 - There was an error fulfilling your request at the moment. Please try again in a while'\n },\n hooks:[\n // here you can put whatever you want\n ]\n }\n}"
},
{
"path": "conf/restConf.js",
"content": "/*\nAll routes might belong to none, one or more groups.\nGrouping routes helps us apply middlewares targeting only specific sets of routes\nGrouping routes follows waterfall inheritance model. A group assigned to a route is been inherited by default by\n all of its subroutes. For example:\n routes:{\n routeA:{\n groups:['groupA'],\n subRoutes:{\n routeB:{\n // routeB by default belongs to 'groupA'\n }\n }\n }\n }\n we can always change the groups that groupB (or any other sub-route) belongs to by redefining the groups attribute\n for example if want routeB not to belong on groupA but to belong on groupB then we can do it by:\n routes:{\n routeA:{\n groups:['groupA'],\n subRoutes:{\n routeB:{\n groups:['groupB']\n }\n }\n }\n }\n and if want groupB to belong on groups at all then an empty groups attribute would do it:\n routes:{\n routeA:{\n groups:[],\n subRoutes:{\n routeB:{\n // routeB by default belongs to 'groupA'\n }\n }\n }\n }\n */\n\n\nmodule.exports.conf = function(fieldsLoader){\n return {\n // API routes signatures\n routes:{\n kpis:{\n groups:['userAccess'],\n subRoutes:{\n traffic:\n {\n get:{\n description:'Get the traffic',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('locationId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate'),\n fieldsLoader.getField('compareEndDate'),\n fieldsLoader.getField('groupBy'),\n fieldsLoader.getField('countType'),\n fieldsLoader.getField('includeUnique'),\n fieldsLoader.getField('includeReturning')\n ]\n },\n subRoutes:{\n powerHours: {\n get:{\n description:'Get the traffic power hours',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('countType'),\n fieldsLoader.getField('basePercentage')\n ]\n }\n }\n ,entrances:{\n get:{\n description:'Get the traffic monitoring point / quarter hour data',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('countType'),\n fieldsLoader.getField('groupBy', {mandatory:true})\n ]\n }\n }\n }\n }\n ,\n dwellTime:{\n get:{\n description:'Get dwell time',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('locationId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate'),\n fieldsLoader.getField('compareEndDate'),\n fieldsLoader.getField('groupBy'),\n fieldsLoader.getField('includeDist'),\n {\n key:'allLocations',\n type:'boolean',\n humanReadable: 'get massive report for all locations',\n description:'Get data for all locations of a given site but for each location separately',\n mandatory:false,\n default:false\n }\n ]\n }\n },\n loyalty:{\n get:{\n description:'Get loyalty',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('locationId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate', {mandatory:true}),\n fieldsLoader.getField('compareEndDate', {mandatory:true}),\n fieldsLoader.getField('type')\n ]\n }\n },\n grossShoppingHours:{\n get:{\n description:'Get gross shopping hours',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('locationId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate'),\n fieldsLoader.getField('compareEndDate'),\n fieldsLoader.getField('groupBy'),\n fieldsLoader.getField('includeUnique'),\n fieldsLoader.getField('includeReturning')\n ]\n }\n },\n shoppersVsTravellers:{\n get:{\n description:'Get shoppers vs travellers',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate'),\n fieldsLoader.getField('compareEndDate'),\n fieldsLoader.getField('groupBy')\n ]\n }\n },\n abandonmentRate:{\n get:{\n description:'Get abandonment rates',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('locationId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate'),\n fieldsLoader.getField('compareEndDate'),\n fieldsLoader.getField('groupBy')\n ]\n }\n },\n drawRate:{\n get:{\n description:'Get draw rate',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('locationId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate'),\n fieldsLoader.getField('compareEndDate'),\n fieldsLoader.getField('groupBy')\n ]\n }\n },\n opportunity:{\n get:{\n description:'Get opportunity',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('locationId'),\n fieldsLoader.getField('reportStartDate'),\n fieldsLoader.getField('reportEndDate'),\n fieldsLoader.getField('compareStartDate'),\n fieldsLoader.getField('compareEndDate'),\n fieldsLoader.getField('groupBy')\n ]\n }\n }\n }\n },\n auth: {\n post: {\n description:'Authenticate user',\n fields:[\n fieldsLoader.getField('username'),\n fieldsLoader.getField('user_password')\n ]\n }\n },\n users:{\n groups:['superUserAccess'],\n get:{\n description:'Get users',\n fields:[]\n },\n post:{\n description:'Post new user',\n fields:[\n fieldsLoader.getField('username'),\n fieldsLoader.getField('user_password')\n ]\n },\n subRoutes:{\n ':user_id':{\n get:{\n description:'Get a specific user info',\n fields:[]\n },\n put:{\n description: 'Edit user\\'s info',\n fields:[\n fieldsLoader.getField('user_password', {mandatory: false}),\n fieldsLoader.getField('expired'),\n fieldsLoader.getField('accessMap')\n ]\n },\n delete:{\n description: 'Delete user',\n fields:[]\n }\n }\n }\n },\n organizations:{\n groups:['userAccess'],\n get:{\n groups:[], // the endpoint will check access to filter down org list\n description:'Get organizations list',\n fields:[]\n },\n post:{\n groups:['superUserAccess'],\n description:'Create a new organization',\n fields:[\n fieldsLoader.getField('orgId'),\n fieldsLoader.getField('name')\n ]\n },\n subRoutes:{\n ':orgId':{\n get:{\n description: 'Organization\\'s details',\n fields:[]\n },\n put:{\n\n description:'Edit organization\\'s data',\n fields:[\n fieldsLoader.getField('name'),\n fieldsLoader.getField('expired')\n ]\n },\n delete:{\n\n description: 'Delete organization',\n fields:[]\n },\n subRoutes:{\n users:{\n groups:['orgAdmin'],\n get:{\n description:'Get all users for which current user is an org admin',\n fields:[]\n },\n post:{\n description:'Add user to the current organization. Create user if it does not exist.',\n fields:[\n fieldsLoader.getField('username'),\n fieldsLoader.getField('user_password', {mandatory: false})\n ]\n },\n subRoutes:{\n ':user_id':{\n get:{\n description:'get the user data, including access map. if user does not exist OR is not in org, return not found',\n fields:[]\n },\n put:{\n description:'update user data, including access map. if user does not exist OR is not in org, return not found',\n fields:[\n fieldsLoader.getField('user_password', {mandatory: false}),\n fieldsLoader.getField('expired'),\n fieldsLoader.getField('accessMap')\n ]\n },\n delete:{\n description:'remove user from organization. Never removes the user completely',\n fields:[]\n }\n }\n }\n },\n sites:{\n get:{\n description:'Get sites list',\n fields:[]\n },\n post:{\n\n description:'Create a new site',\n fields:[\n fieldsLoader.getField('siteId'),\n fieldsLoader.getField('name', {\n description:'Site name',\n humanReadable: 'Site name'\n }),\n fieldsLoader.getField('name', {\n key:'organization_name'\n }),\n fieldsLoader.getField('geo')\n ]\n },\n subRoutes:{\n ':siteId':{\n get:{\n description: 'Site\\'s details',\n fields:[]\n },\n put:{\n\n description:'Edit site\\'s data',\n fields:[\n fieldsLoader.getField('name', {\n description:'Site name',\n humanReadable: 'Site name'\n }),\n fieldsLoader.getField('name', {\n key:'organization_name'\n }),\n fieldsLoader.getField('geo'),\n fieldsLoader.getField('expired')\n ]\n },\n delete:{\n\n description: 'Delete site',\n fields:[]\n },\n subRoutes:{\n locations:{\n get:{\n description: 'Get site\\'s locations',\n fields:[]\n },\n post:{\n\n description:'Create a new location',\n fields:[\n fieldsLoader.getField('location_id'),\n fieldsLoader.getField('location_type'),\n fieldsLoader.getField('name', {\n key:'site_name',\n description:'Site name',\n humanReadable: 'Site name'\n }),\n fieldsLoader.getField('name', {\n key:'organization_name',\n description:'Organization name',\n humanReadable: 'Organization name'\n }),\n fieldsLoader.getField('description'),\n fieldsLoader.getField('beacon_id'),\n fieldsLoader.getField('generic_other', {\n key:'nested_set_left'\n }),\n fieldsLoader.getField('generic_other', {\n key:'nested_set_right'\n }),\n fieldsLoader.getField('generic_other', {\n key:'nested_set_depth'\n }),\n fieldsLoader.getField('traffic_monitoring_point_entrance_id'),\n fieldsLoader.getField('traffic_monitoring_point_description')\n ]\n },\n subRoutes:{\n ':locationId':{\n get:{\n description: 'locations\\'s details',\n fields:[]\n },\n put:{\n\n description:'Edit locations\\'s data',\n fields:[\n fieldsLoader.getField('location_type'),\n fieldsLoader.getField('name', {\n key:'site_name',\n description:'Site name',\n humanReadable: 'Site name'\n }),\n fieldsLoader.getField('name', {\n key:'organization_name',\n description:'Organization name',\n humanReadable: 'Organization name'\n }),\n fieldsLoader.getField('description'),\n fieldsLoader.getField('beacon_id'),\n fieldsLoader.getField('generic_other', {\n key:'nested_set_left'\n }),\n fieldsLoader.getField('generic_other', {\n key:'nested_set_right'\n }),\n fieldsLoader.getField('generic_other', {\n key:'nested_set_depth'\n }),\n fieldsLoader.getField('traffic_monitoring_point_entrance_id'),\n fieldsLoader.getField('traffic_monitoring_point_description'),\n fieldsLoader.getField('expired')\n ]\n },\n delete:{\n\n description: 'Delete locations',\n fields:[]\n }\n }\n }\n }\n }\n }\n }\n }\n }\n }\n }\n }\n }\n }\n};"
},
{
"path": "expressHappiness.js",
"content": "var restConf = {\n routes:[]\n}\nvar kpis\n ,rcv;\nvar fs = require('fs');\nvar colors = require('colors');\nvar flatSignature = [];\nvar app, router, confObj;\n\n\nvar eh = function(p_app, p_router, conf){\n app = p_app;\n router = p_router;\n var path = require('path');\n var appDir = path.dirname(require.main.filename);\n this.generate = successGenerate;\n\n confObj = {\n mockData:{\n enable: true,\n folder: appDir + '/mockJSONs',\n global:false\n },\n reusableFieldsFile: appDir + '/expressHappiness/reusableFields.js',\n errorFile:appDir + '/expressHappiness/errors.log',\n errorsConfigurationFile:appDir + '/expressHappiness/conf/errors.js',\n apiConfigurationFile:appDir + '/expressHappiness/conf/restConf.js',\n controllersFile:appDir + '/expressHappiness/controllerFunctions.js'\n };\n\n if(!conf){\n conf = {};\n }\n for(var propertyName in conf) {\n if(conf.hasOwnProperty(propertyName)){\n confObj[propertyName] = conf[propertyName];\n }\n }\n\n var errorOccurred = false;\n if(!fs.existsSync(confObj.reusableFieldsFile)){\n errorOccurred = true;\n var msg = \"Reusable fields file (\" + confObj.reusableFieldsFile + \") does not exist. Please create it according the documentation\";\n console.log(msg.red.bgWhite);\n }\n if(!fs.existsSync(confObj.errorFile)){\n errorOccurred = true;\n var msg = \"Error log file (\" + confObj.errorFile + \") does not exist. Please create it according the documentation\";\n console.log(msg.red.bgWhite);\n }\n if(!fs.existsSync(confObj.errorsConfigurationFile)){\n errorOccurred = true;\n var msg = \"Errors configuration file (\" + confObj.errorsConfigurationFile + \") does not exist. Please create it according the documentation\"\n console.log(msg.red.bgWhite);\n }\n if(!fs.existsSync(confObj.apiConfigurationFile)){\n errorOccurred = true;\n var msg = \"REST API configuration file (\" + confObj.apiConfigurationFile + \") does not exist. Please create it according the documentation\"\n console.log(msg.red.bgWhite);\n }\n if(!fs.existsSync(confObj.controllersFile)){\n errorOccurred = true;\n var msg = \"Controller functions definition file (\" + confObj.controllersFile + \") does not exist. Please create it according the documentation\"\n console.log(msg.red.bgWhite);\n }\n if(confObj.mockData.enable && !fs.existsSync(confObj.mockData.folder)){\n errorOccurred = true;\n var msg = \"Mock data folder (\" + confObj.mockData.folder + \") does not exist. Please create it according the documentation\"\n console.log(msg.red.bgWhite);\n }\n\n if(errorOccurred){\n this.generate = failureGenerate;\n } else {\n // Rest validation initialization\n var FL = require('./fieldsLoader.js');\n var fieldsLoader = new FL(confObj.reusableFieldsFile);\n restConf = require(confObj.apiConfigurationFile).conf(fieldsLoader);\n\n global.expressHappiness = {\n confObj: confObj\n };\n // TODO change the folder\n rcv = require('./RESTcallsValidator.js');\n rcv.init(confObj);\n rcv.assignConf(restConf);\n kpis = require(confObj.controllersFile);\n }\n\n this.start = function(port){\n if(!port){\n var msg = \"Please enter the port number for the app to run. Exiting.\";\n console.log(msg.red.bgWhite);\n process.exit(1);\n } else {\n isPortTaken(port, function(err, taken){\n if(taken) {\n var msg = 'Port ' + port + ' is been used by another application. Exiting.';\n console.log(msg.red.bgWhite);\n process.exit(1);\n } else {\n p_app.listen(port);\n var msg = 'The application is listening on port ' + port + ' for connections.';\n console.log(msg.green);\n }\n });\n }\n }\n\n}\n\n/*\nchecks if the port is taken\n */\nvar isPortTaken = function(port, fn) {\n var net = require('net')\n var tester = net.createServer()\n .once('error', function (err) {\n if (err.code != 'EADDRINUSE') return fn(err)\n fn(null, true)\n })\n .once('listening', function() {\n tester.once('close', function() { fn(null, false) })\n .close()\n })\n .listen(port)\n}\n\n\n/* Reads the restConf and generates all available routes according to it.\n Also, it acts as debugger. For each of the generated routes the generate function checks if there is\n a corresponding method defined on the kpi controller, if there is mock data file available and it logs everything\n to the console.\n Missing methods are replaced by a generic one which handles their absence.\n Also, routes that do not provide mock data are configured so noMockAvailable function will be called whenever\n mock operation is on for them. For routes that actually have corresponding mock data files available the\n makeMockQuery function will be invoked for mock operation cases. Also, for efficiency reasons the makeMockQuery function\n for each of the routes that actually provide mock data is been generated once here (by reading the corresponding file)\n and it's been passed, so only one file read occurs for each route, only once, only at the kick off.\n It takes three parameters:\n @ router [object]: express framework router object\n @ baseUrl [string]: the base url of the routes to create\n @ preValidationMiddlewares [array][array]: holds all the middlewares that should be applied to the specific routes. These middlewares are been applied before validation\n it is an associative array. On restConf.js file each route might belong to one or more groups. For each group there might be different middlewares applied.\n This is achieved by using the group names as the first level keys of the array. Each key will hold another array which actual holds\n all the middlewares to be applied to the specific groups. Example:\n preValidationMiddlewares ~=\n [\n 'userAccess':[middlewareName1, middleware2],\n 'adminAccess':[middlewareName3, middleware4]\n ]\n if we want to apply a middleware to all of the routes, no matter what then we can define this by including it on the key \"eh-allRoutes\".\n Example:\n preValidationMiddlewares ~=\n [\n 'groupNameOne':[middlewareName1, middleware2],\n 'groupNameTwo':[middlewareName3, middleware4],\n 'eh-allRoutes':[middlewareToBeAppliedToAllRoutes1, middlewareToBeAppliedToAllRoutes2]\n ]\n @ postValidationMiddlewares [array][array]: holds all the middlewares that should be applied after the validation process and before the controller function invocation\n it is an associative array. On restConf.js file each route might belong to one or more groups. For each group there might be different middlewares applied.\n This is achieved by using the group names as the first level keys of the array. Each key will hold another array which actual holds\n all the middlewares to be applied to the specific groups. Example:\n postValidationMiddlewares ~=\n [\n 'groupNameOne':[middlewareName1, middleware2],\n 'groupNameTwo':[middlewareName3, middleware4]\n ]\n if we want to apply a middleware to all of the routes, no matter what then we can define this by including it on the key \"eh-allRoutes\".\n Example:\n postValidationMiddlewares ~=\n [\n 'groupNameOne':[middlewareName1, middleware2],\n 'groupNameTwo':[middlewareName3, middleware4],\n 'eh-allRoutes':[middlewareToBeAppliedToAllRoutes1, middlewareToBeAppliedToAllRoutes2]\n ]\n */\nvar successGenerate = function(baseUrl, preValidationMiddlewares, postValidationMiddlewares){\n var theRoute = router.route(baseUrl + '/');\n theRoute.get(putMethodsOnReq('get'));\n theRoute.get(putApipathToReq([], ''));\n theRoute.get(function(req, res, next){\n req.isRoot = true;\n return next();\n });\n for(var i=0; i\",\n \"license\": \"BSD-2-Clause\",\n \"bugs\": {\n \"url\": \"https://github.com/andreas-trad/express-happiness/issues\"\n }\n}"
},
{
"path": "views/index.html",
"content": "\n\n\n\n \n \n \n \n \n\n KPIS documentation\n\n \n \n\n\n\n\n