Easy, promise-like typed Busboy wrapper (works with firebase cloud functions)

Latest change:

• fix support for firebase cloud functions,
• reduced package size

Built with:

Multipart/form-data uploads with one-liner

• use one-liner instead of event listeners to consume Busboy functionality, no other dependencies,
• based on Busboy,
• to be used with Express (4 & 5) and Koa or as a part of firebase cloud function,
• [WIP] option to specify the way file stream gets processed to Buffer ('memory' | 'storage'),
• typed and covered with tests,

Standard usage (using await syntax)

import { easyBusboy } from 'easy-busboy';

// Express 4 or 5 (the same for firebase cloud function)
app.post<{ fields: IFields; files: IFiles }>(
  '/upload-file',
  async (req, res) => {
    const { fields, files } = await easyBusboy(req);
    res.send({ fields, files });
  }
);

// Koa
app.use(async (ctx) => {
  const { fields, files } = await easyBusboy(ctx.req);
  ctx.body = { fields, files };
});

Response format

No data is being lost while parsing, below is the response interface:

{
  files: Record<
    string,
    {
      buffer: Buffer;
      info: FileInfo; // imported from Busboy
    }
  >;
  fields: Record<
    string,
    {
      value: string;
      info: FieldInfo; // imported from Busboy
    }
  >;
}

Providing Busboy config

import { easyBusboy } from 'easy-busboy';

...
const { fields, files } = await easyBusboy(req, {
      processStreamsMethod: 'memory' | 'storage', // [WIP] default 'memory'
      limits: cfg.limits, // see busboy config limits
      headers,
      conType, // content type
      highWaterMark: ...,
      fileHwm: ...,
      defCharset: ...,
      defParamCharset: ...,
      preservePath: ...,
    });
...

How it works?

It is just a simple method which encapsules Busboy onFile/onField (and other) events in a promise then creates key/value pairs for found fields/files

Small note - if multiple fields with the same name are provided in request then response is going to contain all fields indexed accordingly (no duplicates boss, sorry)

[WIP] Specify files processing method

You can specify processStreamsMethod in config, it may be:

• storage - so that file streams will be converted into Buffers using temporary directory,
• memory - above will be achieved without saving temporary file

In first case file will be returned as a Buffer, in second it is a URI pointing temporary file path

Examples (see github repository)

Before implementing package in your project you can check out functionality using attached examples you can find there Express servers already utilizing easyBusboy method as well as example client (axios)

To be able to work with examples install dependencies in root folder first

• pnpm i,

then take a look at folders mentioned above and package.json scripts:

• pnpm run examples:servers:install (this one installs deps for servers examples),
• pnpm run examples:servers:express4:start {PORT} (run Express 4 server) (you can replace express4 here with 'express5' or 'koa'), note PORT is optional and by default equals 3000,
• pnpm run examples:servers:clean (this one removes deps for servers examples),

Finally when server is listening either launch some example client (look at package.json scripts) providing correct {PORT} as an argument (the same way as with server script) or launch Postman Postman and play with requests to localhost:{PORT}/upload-file !

Tests

• pnpm test to run,
• lib/*test.ts contains some positive/negative test scenarios clearly explaining functionality,

Coverage

| File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Lines | | --------- | ------- | -------- | ------- | ------- | --------------- | | All files | 88.4 | 70 | 70 | 94.91 | | index.ts | 86 | 50 | 64.28 | 93.33 | 122-123,128 | | utils.ts | 94.73 | 100 | 83.33 | 100 |