README

Transmit

An alternative to Multer for handling multipart/form-data

Why?

Multer and many other multipart/form-data parsers don't remove uploaded files if the request is aborted. This can be a problem if a user uploads large files and abruptly aborts the request, leaving the partially uploaded (and potentially large) file on your system. Transmit automatically deletes uploaded files if it detects that the request has been aborted.

In addition, Transmit offers a modern API, making use of promises. It also allows you to process and transform incoming files with the use of transformer functions.

Prerequisites

Node.js >= v12.21.0

Installation

$ npm install @quicksend/transmit
$ npm install -D @types/busboy

Usage

By default, all files are saved within the os.tmpdir() folder. You can change this by specifying the directory in the options of DiskManager.

Example with Express using a custom upload destination:

const { DiskManager, Transmit } = require("@quicksend/transmit");

const express = require("express");

const app = express();

// Implement transmit as an express middleware
const upload = (options = {}) => (req, _res, next) => {
  return new Transmit(options)
    .parseAsync(req)
    .then((results) => {
      req.fields = results.fields;
      req.files = results.files;

      next();
    })
    .catch((error) => next(error));
};

const manager = new DiskManager({
  directory: "./uploads"
});

app.post("/upload", upload({ manager }), (req, res) => {
  res.send({
    fields: req.fields,
    files: req.files
  });
});

app.listen(3000, () => {
  console.log("Listening on port 3000");
});

Example with Node.js http module:

const { Transmit } = require("@quicksend/transmit");

const http = require("http");

const server = http.createServer(async (req, res) => {
  if (req.url !== "/upload" || req.method.toLowerCase() !== "post") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "Not Found." }));

    return;
  }

  try {
    const results = await new Transmit().parseAsync(req);

    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(results, null, 2));
  } catch (error) {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(error));
  }
});

server.listen(3000, () => {
  console.log("Listening on port 3000");
});

NestJS

Transmit can be used with NestJS. Install nestjs-transmit and follow the instructions on the README.

$ npm install @quicksend/nestjs-transmit

Transformers

Files can be transformed before it is written to the storage medium. A use case would be resizing uploaded images.

A transformer must be a function that returns a readable stream.

Transformers will run sequentially in the order that they were placed.

Example with sharp as a resize transformer:

const { DiskManager, Transmit } = require("@quicksend/transmit");

const express = require("express");
const sharp = require("sharp");

const app = express();

// Implement transmit as an express middleware
const upload = (options = {}) => (req, _res, next) => {
  return new Transmit(options)
    .parseAsync(req)
    .then((results) => {
      req.fields = results.fields;
      req.files = results.files;

      next();
    })
    .catch((error) => next(error));
};

const manager = new DiskManager({
  directory: "./uploads"
});

app.post(
  "/upload",
  upload({
    filter: (file) => /^image/.test(file.mimetype), // ignore any files that are not images
    manager,
    transformers: [() => sharp().resize(128, 128).png()], // resize any incoming image to 128x128 and save it as a png
  }),
  (req, res) => {
    res.send({
      fields: req.fields,
      files: req.files
    });
  }
);

app.listen(3000, () => {
  console.log("Listening on port 3000");
});

Custom transmit managers

You can create your own transmit managers. All managers must implement the TransmitManager interface.

import { IncomingFile, TransmitManager } from "@quicksend/transmit";

export class CustomTransmitManager implements TransmitManager {
  handleFile(file: IncomingFile): Promise<NodeJS.WritableStream> | NodeJS.WritableStream {}
  removeFile(file: IncomingFile): Promise<void> | void {}
}

Documentation

Detailed documentation can be found here

You can build the documentation by running:

$ npm run docs

Tests

Run tests using the following commands:

$ npm run test
$ npm run test:watch # run jest in watch mode during development

Generate coverage reports by running:

$ npm run coverage

Usage no npm install needed!