What is Torrin?

Torrin is a modular, TypeScript-first upload engine for large files with resumable, chunked uploads. It provides a robust client-server protocol that solves the common problems developers face when handling large file uploads in web applications.

Key Features

🔄 Resumable Uploads - Automatically resume interrupted uploads from where they left off. Network failures don't mean starting over.

⚡ Chunked Transfer - Split large files into manageable chunks for reliable uploads with granular progress tracking.

🚀 Concurrent Uploads - Upload multiple chunks in parallel for faster transfers. Configurable concurrency levels.

🎯 TypeScript First - Full TypeScript support with strict types, autocomplete, and comprehensive type definitions.

🔌 Storage Agnostic - Local filesystem, S3-compatible storage, or build your own custom storage driver.

🏗️ Framework Integrations - Built-in support for Express.js and NestJS. Works with any frontend framework.

📦 Tiny Bundle Size - Only 5.6 KB gzipped (core + client). Minimal dependencies, tree-shakeable ESM builds.

🛡️ Production Ready - TTL-based cleanup, automatic retries, error handling, and lifecycle hooks for complete control.

🌐 Cross Platform - Works in browsers (File/Blob) and Node.js (Buffer/Stream). Universal JavaScript support.

Why Torrin?

Traditional file uploads struggle with large files. Network interruptions mean starting over, and users have no control or visibility. Torrin solves these problems:

• Network resilience: Only retry failed chunks, not entire files
• User experience: Clear progress tracking and ability to pause/resume
• Developer control: Configure chunk size, concurrency, retries, and more
• Production ready: Built-in TTL, cleanup, authentication hooks, and error handling

Quick Example

npm

npm install @torrin-kit/client @torrin-kit/server @torrin-kit/server-express

yarn

yarn add @torrin-kit/client @torrin-kit/server @torrin-kit/server-express

pnpm

pnpm add @torrin-kit/client @torrin-kit/server @torrin-kit/server-express

bun

bun add @torrin-kit/client @torrin-kit/server @torrin-kit/server-express

Server (Express.js):

import express from 'express';
import { createTorrinExpressRouter } from '@torrin-kit/server-express';
import { createLocalStorageDriver } from '@torrin-kit/storage-local';
import { createInMemoryStore } from '@torrin-kit/server';

const app = express();
app.use(express.json());

app.use('/torrin/uploads', createTorrinExpressRouter({
  storage: createLocalStorageDriver({ baseDir: './uploads' }),
  store: createInMemoryStore(),
}));

app.listen(3000);

Client (Browser):

import { createTorrinClient } from '@torrin-kit/client';

const torrin = createTorrinClient({
  endpoint: '/torrin/uploads',
});

const upload = torrin.createUpload({ file: myFile });

upload.on('progress', (p) => {
  console.log(`${p.percentage}% uploaded`);
});

const result = await upload.start();
console.log('Uploaded to:', result.location);

How It Works

1. Initialize: Client sends file metadata. Server returns an uploadId and chunk configuration
2. Chunk: Client splits the file into chunks based on configured size
3. Upload: Chunks are uploaded (with configurable concurrency and retries)
4. Track: Server marks received chunks, allowing resume from any point
5. Complete: Once all chunks arrive, server assembles the final file

Package Ecosystem

Package	Description	Size
@torrin-kit/core	Shared types, errors, utilities	1.8 KB
@torrin-kit/client	Client-side upload library	3.8 KB
@torrin-kit/server	Core server logic	2.0 KB
@torrin-kit/server-express	Express.js integration	1.0 KB
@torrin-kit/server-nestjs	NestJS integration	1.9 KB
@torrin-kit/storage-local	Local filesystem driver	1.1 KB
@torrin-kit/storage-s3	S3-compatible driver	1.4 KB

Sizes are gzipped. Total client bundle: ~5.6 KB