multiparty.express.txt

              
   MULTIPARTY  
              



ALTERNATIVES ==>              #  - multiparty
                              #  - multer

VERSION ==>                   #4.2.3

GOAL ==>                      #"multipart/form-data|related" body parsing
                              #Can use Content-Transfer-Encoding: "binary|base64"

new MULTIPARTY.Form([OPTS])   #OPTS:
                              #  - encoding STR (def: 'utf8'): of the input
                              #  - maxFields NUM (def: 1000): max numbers of FIELD|FILEs
                              #  - maxFieldsSize NUM (def: 2MB): max size of all FIELDs together
                              #  - maxFilesSize NUM (def: Infinity): max size of all FILEs together
                              #  - autoFields|autoFiles BOOL:
                              #     - if false:
                              #        - fires FORM.on('part') instead of FORM.on('file|field')
                              #        - does not enforce maxFields|FilesSize
                              #     - def: true if using FORM.parse() FUNC or FORM.on('file|field')
                              #  - uploadDir (def: OS.tmpDir())
FORM.parse(REQ                #FUNC() is called on FORM.on('error|close')
[, FUNC(ERROR, FIELDS,FILES)])#FIELDS is { NAME: 'FIELD'_ARR }
                              #FILES is { NAME: FILE_ARR }

FORM.on                       #When parsing a part with filename. FILE:
 ('file', FUNC("NAME", FILE)) #  - fieldName "NAME" (from Content-Disposition: ...; name="NAME")
                              #  - originalFilename "FILENAME" (from Content-Disposition: ...; filename="FILENAME")
                              #  - headers OBJ: names are lowercased
                              #  - path "DIR/RANDOM_ID.EXT"
                              #     - where file is persisted (not cleaned up except on error)
                              #     - EXT is from "FILENAME"
                              #     - DIR is OPTs.uploadDir
                              #  - size NUM
FORM.on('field',
 FUNC("NAME", 'FIELD'))       #When parsing a part without filename.
FORM.on('part', FUNC(ISTREAM))#When parsing a part and OPTS.autoFields|Fields false
                              #ISTREAM has also:
                              #  - name "NAME", filename, headers: like above
                              #  - byteOffset|Count NUM
                              #Should call ISTREAM.resume() after handling

FORM.on("close", FUNC())      #End without error.
FORM.on("error", FUNC(ERROR)) #End with error.
                              #Also sets FORM.error ERROR
                              #Use HTTP-ERRORS (see its doc):
                              #  - 400: parsing ended unexpectedly
                              #  - 400: wrong request payload syntax
                              #  - 400: missing ;boundary in 'multipart/form-data|related;boundary'
                              #  - 413: above OPTS.maxFields|maxFieldsSize|maxFilesSize
                              #  - 415: missing Content-Type [C]
                              #  - 415: Content-Type [C] not 'multipart/form-data|related[;...]'
                              #Any 'error' event on REQ is forwarded to FORM.
FORM.on("aborted", FUNC())    #REQ was aborted.
                              #Also emits FUNC.on('error')

FORM.on("progress",
 FUNC(FORM.bytesReceived,
 FORM.bytesExpected))         #
FORM.bytesExpected            #Total amount of bytes, using Content-Length [C]
                              #0 if Transfer-Encoding [C]
                              #null if neither
FORM.bytesReceived            #Currently parsed amount of bytes
FORM.totalField|FileSize      #Currently parsed amounf of bytes, by type
FORM.totalFieldCount          #NUM of FIELD|FILEs