file-chunkify

file-chunkify

A lightweight file chunking utility for splitting and merging large files across different environments.

Features

• Efficiently splits large files into smaller chunks.
• Supports progressive chunk uploading.
• Merges chunks back into a single file upon completion.
• Compatible with various runtime environments.

Installation

Install via npm:

npm install file-chunkify

Usage

File Splitting

Use splitFile to break a large file into chunks before processing:

import { splitFile } from "file-chunkify";

const fileInput = document.querySelector("input[type='file']");
fileInput.addEventListener("change", async (event) => {
  const file = event.target.files[0];
  for await (const chunkInfo of splitFile({
    file,
    chunkSize: 5 * 1024 * 1024,
  })) {
    console.log("Processing chunk", chunkInfo);
    // Send chunkInfo.chunk to the storage or processing pipeline
  }
});

Chunk Storage & Merging

Use saveChunk to store received chunks and merge them when all are received:

import { saveChunk } from "file-chunkify";
import express from "express";
import multer from "multer";

const app = express();
const upload = multer();

app.post("/upload", upload.single("chunk"), async (req, res) => {
  const { chunkNumber, totalChunks } = req.body;
  const result = await saveChunk({
    file: req.file,
    chunkNumber: Number(chunkNumber),
    totalChunks: Number(totalChunks),
    options: { debugMode: true }, // Example usage of debugger
  });
  res.json(result);
});

app.listen(3000, () => console.log("Server running on port 3000"));

API Reference

splitFile(options)

Splits a file into chunks.

Parameters:

Name	Type	Default	Description
file	File	Required	The file to be split.
chunkSize	number	5MB	The size of each chunk.
options	object	Optional	Additional options, including debugMode.

Returns:

An async generator yielding objects with:

• chunk: A file slice (File)
• chunkNumber: The current chunk number
• totalChunks: Total number of chunks
• fileName: A generated UUID-based file name
• progress: Split progress in %

saveChunk(options)

Saves uploaded chunks and merges them when all are received.

Parameters:

Name	Type	Default	Description
file	Express.Multer.File	Required	The uploaded chunk file.
chunkNumber	number	Required	The current chunk number.
totalChunks	number	Required	The total number of chunks.
outputDir	string	./uploads	Directory to store merged files.
chunkDir	string	./uploads/chunks	Directory to store chunk files.
options	object	Optional	Additional options, including debugMode.

Returns:

Name	Type	Description
success	boolean	Indicates if the operation was successful.
message	string	A status message.
mergedFilePath	string?	The path of the merged file (if applicable).

License

MIT License © 2025 Ahmad Al-Zein