path-to-regexp.node.txt

                                  ┏━━━━━━━━━━━━━━━━━━━━┓
                                  ┃   PATH-TO-REGEXP   ┃
                                  ┗━━━━━━━━━━━━━━━━━━━━┛

ALTERNATIVES ==>                  #  - URLPattern (preferred if browser|Deno): standard DOM
                                  #  - path-to-regexp (preferred if Node): more features
                                  #  - @middy/http-router (preferred if Middy)

VERSION ==>                       #8.2.0

                                  ┌─────────────┐
                                  │   PATTERN   │
                                  └─────────────┘

'PATH'                            #URI path without template variables

PATH_PATTERN                      #URI path with template variables
                                  #Can contain:
                                  #  - :VAR
                                  #     - VAR name is same as valid JavaScript identifiers
                                  #        - can use other chars with :"VAR" or \-escaping
                                  #     - matches anything until DELIM
                                  #  - *VAR
                                  #     - same but matches 1+ times, split by DELIM
                                  #  - {...}: optional part
                                  #  - RAW: anything else
                                  #Can \-escape any special char: {} * \
                                  #Reserved chars that must be \-escaped: () [] ? + ! @ ,

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

new TokenData(TOKEN|'RAW'_ARR
 [, 'SEPARATOR'])                 #TOKENS
TOKENS.tokens                     #TOKEN|'RAW'_ARR

TOKEN                             #OBJ representation of PATH_PATTERN's part
TOKEN.type                        #Can be:
                                  #  - 'param': :VAR
                                  #  - 'wildcard': *
                                  #  - 'group': {...}
                                  #  - 'text': 'RAW'
TOKEN.name                        #Can be 'VAR' (if :VAR) or '*' (if *)
TOKEN.tokens                      #'...' (if {...})

PATH_REGEXP                       #REGEXP where each parenthesis group matches a :VAR

PARAMS                            #Template variables (:VAR) as { TOKEN.name: STR|ARR, ... }
                                  #  - ARR if *VAR

                                  ┌─────────────┐
                                  │   OPTIONS   │
                                  └─────────────┘

OPTS.sensitive                    #BOOL. If false (def), case-insensitive

OPTS|TOKENS.delimiter             #'DELIM' (def: '/')
                                  #Multiple DELIMs in a row are counted as separate
OPTS.trailing                     #BOOL (def: true). End must match:
                                  #  - OPTS.trailing false + OPTS.end true: $
                                  #  - OPTS.trailing false + OPTS.end false: $ or DELIM
                                  #  - OPTS.trailing true + OPTS.end true: $ or DELIM$
                                  #  - OPTS.trailing true + OPTS.end false: $ or DELIM or DELIM$
OPTS.end                          #BOOL (def: true). Must match until end
                                  #Always matches from beginning

OPTS.encodePath                   #FUNC('RAW')->STR (def: identity)
                                  #Transform 'RAW' during parse|compile()
                                  #Should use encodeURI() if PATH_PATTERN might contain non-URI-encoded characters
OPTS.encode                       #FUNC(VAL)->STR or false (same as identity function)
                                  #Transform PARAMS.* during compile()
                                  #Def: encodeURIComponent()
OPTS.decode                       #FUNC(STR)->STR or false (same as identity function)
                                  #Transform PARAMS.* during match()
                                  #Def: decodeURIComponent()

                                  ┌─────────┐
                                  │   API   │
                                  └─────────┘

parse(PATH_PATTERN[, OPTS])       #PATH_PATTERN -> TOKENS
 ->TOKENS                         #OPTS: encodePath

stringify(TOKENS)->PATH_PATTERN   #TOKENS -> PATH_PATTERN

pathToRegexp                      #PATH_PATTERN|TOKENS -> PATH_REGEXP
 (PATH_PATTERN|TOKENS[_ARR]       #If ARR: alternatives
 [, OPTS])->OBJ                   #OPTS: sensitive|delimiter|trailing|end
OBJ.regexp                        #PATH_REGEXP
OBJ.keys                          #TOKEN_ARR of all :VAR

match(PATH_PATTERN|TOKENS[_ARR]   #PATH_PATTERN|TOKENS + 'PATH' -> PARAMS
 [, OPTS])->FUNC('PATH')          #OPTS: sensitive|delimiter|trailing|end|decode
 ->MATCH_RESULT|false             #For better matching, it is recommended to 'PATH'.normalize()
MATCH_RESULT.params               #PARAMS
MATCH_RESULT.path                 #STR. Whole part of 'PATH' that matched

compile                           #PATH_PATTERN|TOKENS + PARAMS -> 'PATH'
 (PATH_PATTERN|TOKENS[, OPTS])    #Replaces:
 ->FUNC([PARAMS])                 #  - :VAR by PARAMS.VAR
 ->'PATH'                         #  - (...) by PARAMS[NUM]
                                  #OPTS: delimiter|encode|encodePath