morgan.express.txt

                                  ┏━━━━━━━━━━━━┓
                                  ┃   MORGAN   ┃
                                  ┗━━━━━━━━━━━━┛

ALTERNATIVES ==>              #See express-winston

VERSION ==>                   #1.10.0

                                  ┌──────────┐
                                  │   CORE   │
                                  └──────────┘

morgan                        #Express MDWR that logs each request to OPTS.stream (def: process.stdout)
 ('FORMAT'|TEMPLATE[, OPTS])  #What's logged is 'FORMAT'|TEMPLATE
 ->MDWR                       #OPTS:
                              #  - immediate BOOL:
                              #     - if true, done when MDWR is called
                              #     - if false (def), done when request ends (using ON-FINISHED, see its doc)
                              #  - skip(REQ, RES)->BOOL:
                              #     - do not log request if false
                              #     - can also return undefined|null with TEMPLATE_FUNC

                                  ┌──────────────┐
                                  │   TEMPLATE   │
                                  └──────────────┘

TEMPLATE                      #'TEMPLATE'|TEMPLATE_FUNC
'TEMPLATE'                    #Template string with :TOKEN placeholders.
TEMPLATE_FUNC                 #FUNC(TOKENS, REQ, RES)->STR
compile('TEMPLATE')
 ->TEMPLATE_FUNC              #Replaces :TOKEN placeholders inside 'TEMPLATE'

                                  ┌────────────┐
                                  │   FORMAT   │
                                  └────────────┘

'FORMAT'                      #Predefined TEMPLATE
format('FORMAT', TEMPLATE)    #Register a 'FORMAT'

BUILT-IN FORMATS ==>          #
combined                      #':remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length]                     ":referrer" ":user-agent"'
common                        #':remote-addr - :remote-user [:date[clf]] ":method :url HTTP/:http-version" :status :res[content-length]'
short                         #':remote-addr   :remote-user               :method :url HTTP/:http-version  :status :res[content-length] - :response-time ms'
tiny                          #'                                          :method :url                     :status :res[content-length] - :response-time ms'
dev                           #Like tiny but with colors

                                  ┌────────────┐
                                  │   TOKENS   │
                                  └────────────┘

TOKEN(REQ, RES, ARG)->STR     #Placeholder template function.
                              #If returns falsy, replaced by '-' instead
:TOKEN                        #Replaced by TOKEN()->STR inside 'TEMPLATE'
:TOKEN[ARG]                   #[ARG] use actual square brackets.
                              #TOKEN is [:alnum:]_-
TOKENS                        #{ TOKEN(), ... }
token('TOKEN', TOKEN())       #Register a :TOKEN

BUILT-IN TOKENS ==>           #
:http-version                 #'REQ.httpVersionMajor.REQ.httpVersionMinor'
:method                       #REQ.method
:url                          #REQ.originalUrl|url
:status                       #RES.statusCode
:req|res['HEADER']            #REQ|RES.headers.HEADER
:referrer                     #REQ.headers.refer[r]er
:user-agent                   #REQ.headers.user-agent
:remote-user                  #USERNAME from Authorization: Basic ... [C] (using BASIC-AUTH, see its doc)
:remote-addr                  #REQ.ip|connection.remoteAddress
:date[[TYPE]]                 #Current date. TYPE can be:
                              #  - 'web' (UTC) (def): Thu, DD Oct YYYY HH:MM:SS Z
                              #  - 'iso' (ISO 8601): YYYY-MM-DDTHH:MM:SS.NNNZ
                              #  - 'clf' (Common log format): DD/Oct/YYY:HH:MM:SS +Z
:response-time[[NUM]]         #Time spent between morgan MDWR called, and RES sending headers (using ON-HEADERS, see its doc)
                              #Uses process.hrtime()
                              #Stringifies with MS.toFixed(NUM) (def NUM: 3) (see MS doc)
:total-time[[NUM]]            #Same but until RES body sent