@goa/busboy

@goa/busboy is a fork of A Streaming Parser For HTML Form Data For Node.JS Written In ES6 And Optimised With JavaScript Compiler.

yarn add @goa/busboy

Table Of Contents

• Table Of Contents
• API
• class Busboy
  • File Event
  • Field Event
• constructor(conf=: !BusBoyConfig)
  • BusBoyConfig
  • BusBoyLimits
• Copyright

API

The package is available by importing its default function:

import Busboy from '@goa/busboy'

class Busboy

Busboy is a Writable stream. Emits the following events:

| Event | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | file | Emitted for each new file form field found. transferEncoding contains the 'Content-Transfer-Encoding' value for the file stream. mimeType contains the 'Content-Type' value for the file stream. | | field | Emitted for each new non-file field found. | | partsLimit | Emitted when specified parts limit has been reached. No more 'file' or 'field' events will be emitted. | | filesLimit | Emitted when specified files limit has been reached. No more 'file' events will be emitted. | | fieldsLimit | Emitted when specified fields limit has been reached. No more 'field' events will be emitted. |

File Event

busboy.on('file',
  <string> fieldname,
  <ReadableStream> stream,
  <string> filename,
  <string> transferEncoding,
  <string> mimeType
)

• Note: if you listen for this event, you should always handle the stream no matter if you care about the file contents or not (e.g. you can simply just do stream.resume(); if you want to discard the contents), otherwise the 'finish' event will never fire on the Busboy instance. However, if you don't care about any incoming files, you can simply not listen for the 'file' event at all and any/all files will be automatically and safely discarded (these discarded files do still count towards files and parts limits).
• If a configured file size limit was reached, stream will both have a boolean property truncated (best checked at the end of the stream) and emit a 'limit' event to notify you when this happens.

Field Event

busboy.on('field',
  <string> fieldname,
  <string> value,
  <boolean> fieldnameTruncated,
  <boolean> valueTruncated,
  <string> transferEncoding,
  <string> mimeType
)

constructor(  conf=: !BusBoyConfig,): BusBoy

• conf !BusBoyConfig (optional): The configuration.

BusBoyConfig: Options for the program.

| Name | Type | Description | Default | | ------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------- | | headers | !Object | These are the HTTP headers of the incoming request, which are used by individual parsers. | - | | highWaterMark | number | The highWaterMark to use for this Busboy instance (Default: WritableStream default). | - | | fileHwm | number | The highWaterMark to use for file streams (Default: ReadableStream default). | - | | defCharset | string | The default character set to use when one isn't defined. | utf8 | | preservePath | boolean | If paths in the multipart 'filename' field shall be preserved. | false | | limits | BusBoyLimits | Various limits on incoming data. | - |

BusBoyLimits: Various limits on incoming data.

| Name | Type | Description | Default | | ------------- | --------------- | ---------------------------------------------------------------------------- | ---------- | | fieldNameSize | number | Max field name size in bytes. | 100 | | fieldSize | number | Max field value size in bytes. | 1024 | | fields | number | Max number of non-file fields. | Infinity | | fileSize | number | For multipart forms, the max file size in bytes. | Infinity | | files | number | For multipart forms, the max number of file fields. | Infinity | | parts | number | For multipart forms, the max number of parts (fields + files). | Infinity | | headerPairs | number | For multipart forms, the max number of header key=> value pairs to parse. | 2000 |

The constructor can throw errors:

• Unsupported content type: $type - The Content-Type isn't one Busboy can parse.
• Missing Content-Type - The provided headers don't include Content-Type at all.

import idio from '@idio/idio'
import render from '@depack/render'
import Busboy from '@goa/busboy'

(async () => {
  const { app, url } = await idio({
    async post(ctx, next) {
      if (ctx.request.method != 'POST') {
        return await next()
      }
      const busboy = new Busboy({ headers: ctx.request.headers })

      busboy.on('file', function(fieldname, file, filename, encoding, mimetype) {
        console.log(
          'File [%s]: filename: %s, encoding: %s, mimetype: %s',
          fieldname, filename, encoding, mimetype)
        file.on('data', (data) => {
          console.log('File [%s] got %s bytes', fieldname, data.length)
        })
        file.on('end', () => {
          console.log('File [%s] Finished', fieldname)
        })
      })

      busboy.on('field', (
        fieldname, val, fieldnameTruncated, valTruncated, encoding, mimetype,
      ) => {
        console.log('Field [%s]: value: %O', fieldname, val)
      })

      ctx.req.pipe(busboy)

      await new Promise((r, j) => {
        busboy.on('finish', () => {
          console.log('Done parsing form!')
          r()
        }).on('error', j)
      })
      ctx.status = 303
      ctx.body = 'OK'
      exitExample(app)
    },
    get(ctx) {
      ctx.body = render(<html>
        <body>
          <form method="POST" encType="multipart/form-data">
            <input type="text" name="textfield" /><br />
            <input type="file" name="filefield" /><br />
            <input type="submit" />
          </form>
        </body>
      </html>)
    },
  })
  console.log(url)
})()

http://localhost:5000
Field [textfield]: value: ''
File [filefield]: filename: hi, encoding: 7bit, mimetype: application/octet-stream
File [filefield] got 12 bytes
File [filefield] Finished
Done parsing form!

Copyright

GNU Affero General Public License v3.0

Original Work by Brian White aka mscdex under MIT License found in COPYING.