connect-roles.express.txt

                                  ┏━━━━━━━━━━━━━━━━━━━┓
                                  ┃   CONNECT-ROLES   ┃
                                  ┗━━━━━━━━━━━━━━━━━━━┛

new CONNECT-ROLES([OPT_OBJ])  #Express MIDWR (3.0.3) for authorization:
                              #  - while Passport deals with authentication (filling REQ.user), this gives permission 
                              #    according to REQ.user.
                              #  - this is like using REQ.isAuthenticated(), but more structured.
                              #Returns ROLES.
                              #OPT_OBJ:
                              #  - async true: 
                              #     - let ROLES.use() FUNC return PROMISE, on top of NORMAL_VAL
                              #     - REQ|RES.locals.userCan() will return PROMISE2 instead of BOOL:
                              #        - resolved with VAL if NORMAL_VAL
                              #        - resolve|rejected according to PROMISE otherwise
                              #     - ROLES.can() will consider:
                              #        - resolve(true) or reject() as true
                              #        - reject(VAL) as false
                              #        - resolve() as null|undefined
APP.use(ROLES.middleware())   #Initializes (can be done anywhere).

ROLES.use                     #Fired by REQ.userCan(ACTION) and gives it its return value:
(FUNC(REQ, ACTION)->BOOL)     #  - can return true|false, but also undefined|null:
                              #     - pass control to next ROLES.use()
                              #     - if last one, return false
                              #  - should probably use REQ.isAuthenticated() and REQ.user (e.g. REQ.user.role STR)
ROLES.use(ACTION[, PATH],     #Same but:
FUNC(REQ)->BOOL)              #  - only applies when using ACTION
                              #  - if PATH (same as APP.METHOD(PATH)), when choosing this PATH.
                              #    REQ.params will be filled if there are some PARAM

REQ.userCan(ACTION)           #Returns BOOL (see ROLES.use())
RES.locals.userCan(ACTION)    #Same but for templates
ROLES.can(ACTION)[.here]      #Express MIDWR that if REQ.userCan(ACTION) false:
                              #  - without here: calls OPT_OBJ.failureHandler(REQ, RES, ACTION): default one do RES.send(403)
                              #  - with here: do next('route')

RES.locals.user               #Filled by REQ.user (or any OPT_OBJ.userProperty)
RES.locals.isAuthenticated    #Filled by REQ.isAuthenticated()