omulti v0.0.17

Omulti - Node.js HTTP file uploads

Getting started

Omulti is a Node.js library that handles HTTP file uploads.

• Fast
• Easy to use
• Written in Typescript
• It has very few dependencies

To install it run:

npm i omulti

How to use it

Basic usage with Node.js HTTP server

To use it with a Node.js HTTP server simply create a new HTTP server an pass the request object into the Omulti constructor like so:

import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req);

    for await (const file of omulti.getFiles()) {
        await file.saveToDisk("/path/where/to/save/file");
    }
});

httpServer.listen(3000);

As you can see the omulti.getFiles() function returns an async generator that allows you to iterate over evey file.

Alternatively, you can also use events if you want:

import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req);

    omulti.on("file", (file) => {
        console.log(file.filename);
    });
});

httpServer.listen(3000);

Since Omulti handles multipart/form-data this means that besides files we might also receive input data from form fields.

To get just the fields do:

import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req);

    for await (const field of omulti.getFields()) {
        console.log(field.name);
    }
});

httpServer.listen(3000);

To get both files and fields you can use the getAll() method. However you need to distinguish between these two types when working with them:

import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req);

    for await (const part of omulti.getAll()) {
        if (part.isFile()) {
            // it's a file
        } else {
            // it's a field
        }
    }
});

httpServer.listen(3000);

As before you can use events here instead, so to get the fields listen on the field event.

import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req);

    omulti.on("field", (field) => {
        console.log(file.name);
    });
});

httpServer.listen(3000);

Or to get both files and fields, use the part event:

import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req);

    omulti.on("part", (part) => {
        if (part.isFile()) {
            // it's a file
        } else {
            // it's a field
        }
    });
});

httpServer.listen(3000);

Options

Omulti allows several options to be passed to the constructor when creating a new instance. All the options are optional.

const omulti = new Omulti(req, {
    maxTotalSize: Number,
    maxFileSize: Number,
    maxFieldSize: Number,
    maxNumberOfFiles: Number,
    maxNumberOfFields: Number,
    maxBufferSize: Number,
});

Files and Fields

Properties

A Field has the following properties:

• name: string | undefined
• contentType: string | undefined

and a File has the same properties plus:

• filename: string | undefined

Both entities have a stream property that is a Readable stream.

E.g. you can use this to pipe to a writable stream:

import { createWriteStream } from "fs";
import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req);
    for await (const file of omulti.getFiles()) {
        const writeStream = createWriteStream("/some/path/to/a/dir");
        file.stream.pipe(writeStream);
    }
});

httpServer.listen(3000);

Methods

Field

• getContents()

File

• getContents()
• saveToDisk(path: string)

getContents()

Both entities have a getContents() method that returns a Promise<Buffer> with the entire contents of the Field/File. Be careful when using this, make sure to explicitly set the maxFieldSize and/or the maxFileSize, to prevent the host machine from being starved of memory.

import { createServer } from "http";
import { Omulti } from "omulti";

const httpServer = createServer(async (req, res) => {
    const omulti = new Omulti(req, {
        maxFileSize: 2 * 1024 * 1024, /// max 2MB
    });
    for await (const file of omulti.getFiles()) {
        const contents = (await file.getContents()).toString("utf-8");
        /// do something with the contents
    }
});

httpServer.listen(3000);

saveToDisk(path: string)

The File object also has a saveToDisk('path/to/save/file') method that will save the file to a provided path on the disk.