@fullstackunicorn/upload

A tiny universal upload system that works in browser and Node.js.

This package provides:

• Uploader → works in browser (React, Vanilla JS) and Node
• Receiver → works in Node, receives uploaded files and writes them to disk

It is designed for situations where you want a simple, controlled file transfer pipeline, without dealing with form-data, multipart boundaries, or external libraries.

Ideal for:

• sending assets from browser → server
• sending local files from a Node script → server
• multi-file transfer
• custom file processing (thumbnails, metadata, hashing, etc.)

Installation

yarn add @fullstackunicorn/upload

or:

npm install @fullstackunicorn/upload

This installs:

• uploader (module)
• receiver (module)

Both are imported programmatically — not CLI executables.

📦 Using the RECEIVER (Node)

The receiver listens on a port and waits for uploaded files.

import { receiver } from "@fullstackunicorn/upload"

receiver.start({
    port: 4500,
    folder: "./uploads",     // destination folder
    onFile: file => {
        console.log("Received:", file.name, file.size)
    }
})

When a file arrives, it is automatically:

• decoded
• saved into the destination folder
• passed to the onFile callback

The receiver auto-creates directories.

📤 Using the UPLOADER (Browser)

Uploader works directly in React / browser.

Select a file using an <input> and send it:

import { uploader } from "@fullstackunicorn/upload"

async function send(file) {
    await uploader.send({
        file,
        host: "http://localhost:4500",
        path: "/upload"
    })
}

Uploader automatically:

• reads file as ArrayBuffer or Blob
• chunks if needed
• streams to the receiver
• waits for acknowledgment

Works with ANY file type: PNG, JPG, PDF, ZIP, JSON, etc.

📤 Using the UPLOADER in Node

Uploader also works in Node.js (for automation scripts):

import { uploader } from "@fullstackunicorn/upload"
import fs from "node:fs"

const buffer = fs.readFileSync("./image.png")

await uploader.send({
    name: "image.png",
    buffer,
    host: "http://localhost:4500",
    path: "/upload"
})

🔌 Receiver API

receiver.start({
    port: number,
    folder: string,
    onFile: (file) => {},
    onError: (err) => {}
})

Inbound file object:

{
    name: "myfile.png",
    size: 120392,
    type: "image/png",
    buffer: <Buffer ...>
}

🌍 Uploader API (browser + node)

Browser

uploader.send({
    file,      // File object
    host,
    path
})

Node

uploader.send({
    name,
    buffer,
    host,
    path
})

🔐 Why this package?

• Works the same in browser and Node
• No multipart, no FormData hell
• Zero dependencies
• Binary safe
• Customizable
• Perfect for controlled upload pipelines

📁 File Structure (simplified)

/src
  uploader/
  receiver/
  utils/
index.js

📝 License

MIT © fullstackunicorn.dev