@visulima/storage

Two surfaces, one library

• Files — one-liner API for ad-hoc storage operations. Web-standard body types (Blob, Uint8Array, ReadableStream), bulk-array overloads, per-call retry/timeout/abort, lifecycle hooks, and a .raw escape hatch. Use this when you just need to put files somewhere.
• BaseStorage adapters (S3Storage, DiskStorage, BunnyStorage, …) — the full upload-server framework. TUS / multipart / REST handlers, lifecycle hooks, validators, image / video / audio transformers, OpenAPI export. Use this when you're hosting an upload service.

Both surfaces wrap the same adapters — swap providers without touching call sites.

Install

npm install @visulima/storage
# or yarn add / pnpm add

Each provider has its own peer dependency (e.g. @aws-sdk/client-s3 for S3, @azure/storage-blob for Azure). See the relevant service page for the exact install command.

Quick start with Files

import { Files } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";

const files = new Files({
    adapter: new S3Storage({ bucket: "uploads", region: "us-east-1" }),
});

await files.upload("avatars/abc.png", buffer, { contentType: "image/png" });

const url = await files.url("avatars/abc.png", { expiresIn: 900 });
const { body } = await files.download("avatars/abc.png");

// Stream large objects without buffering the whole payload in memory:
const { body: stream } = await files.downloadStream("avatars/abc.png");

Swap the adapter to change provider — everything else stays the same:

import { Files, DiskStorage } from "@visulima/storage";
import { BunnyStorage } from "@visulima/storage/provider/bunny";

new Files({ adapter: new DiskStorage({ directory: "./uploads" }) });
new Files({ adapter: new BunnyStorage({ zone, accessKey, region: "de" }) });

→ See the Files facade reference for the full method surface (upload, download, downloadStream, head, exists, delete, copy, move, list, listAll, url, signedUploadUrl, .raw) and body-type matrix. list({ delimiter: "/" }) returns directory-style { files, prefixes }; pass { readonly: true } (or call files.readonly()) for a locked view, and read files.capabilities to branch on adapter support. Top-level transfer(source, destination) streams whole buckets between adapters; sync(source, destination) does an incremental, optionally-pruning mirror (with dryRun).

Building an upload server?

If you're handling client uploads from a browser — large files, resumable transfers, form posts — use the adapter directly with one of the HTTP handlers.

import { DiskStorage } from "@visulima/storage";
import { Multipart, Rest } from "@visulima/storage/handler/http/node";

const storage = new DiskStorage({ directory: "./uploads" });

const multipart = new Multipart({ storage });
// `upload` (unlike `handle`) accepts Express's `next`: once an upload completes it
// writes the stored file metadata to `req.body` and calls the next middleware.
app.post("/upload", multipart.upload, (req, res) => {
    res.json(req.body);
});
app.use("/upload", multipart.handle); // GET / DELETE / OPTIONS

const rest = new Rest({ storage });
app.use("/files", rest.handle);

Three handlers cover the common upload patterns:

• Multipart — multipart/form-data from HTML forms.
• REST — direct binary POST / PUT. Optional client-side chunking for large files.
• TUS — resumable uploads (tus.io) for unreliable networks and very large files.

→ Runtime adapters live under @visulima/storage/handler/http/{node,fetch,hono,nextjs,solid-start,bun,cloudflare,edge}. See framework integrations.

Choosing your surface

Providers

Object storage (service credentials, presigned URLs, S3-style):

• AWS S3 · Azure Blob · Google Cloud Storage · Vercel Blob · Netlify Blobs · Local disk

S3-compatible (branded client configs under provider/aws/s3/clients):

• Cloudflare R2 · DigitalOcean Spaces · MinIO · Hetzner · Storj · Backblaze B2 · Tigris · Wasabi · Akamai · Scaleway · Vultr · Exoscale · Filebase · iDrive e2 · IBM Cloud Object Storage · Oracle Cloud (OCI) · OVHcloud · Alibaba Cloud OSS · Tencent Cloud COS · Yandex Object Storage

Consumer providers (user OAuth or service-credential, all peer-dep gated):

• Dropbox · Google Drive · Microsoft OneDrive · SharePoint · Box · Supabase · UploadThing · Bunny Storage · Cloudinary · Firebase Storage · PocketBase

→ See the capability matrix for what each provider supports (presign, copy, list, signed uploads, …).

AI tool integrations

The package ships four optional subpaths that expose Files as tools an LLM can call — same eight canonical operations wrapped in each SDK's native tool format, with per-tool approval gating.

import { Files } from "@visulima/storage";
import { S3Storage } from "@visulima/storage/provider/aws";
import { createFileTools } from "@visulima/storage/ai/sdk";

const files = new Files({ adapter: new S3Storage({ bucket: "uploads", region: "us-east-1" }) });
const tools = createFileTools({ files });

Subpaths: @visulima/storage/ai/{sdk,openai,claude,tanstack} — Vercel AI SDK, OpenAI Responses + Agents (both under /openai), Claude Agent SDK, and TanStack AI.

Documentation

• Introduction — the two surfaces, when to use each
• Files facade — the eight-method reference
• Services — per-provider configuration and capability matrix
• Framework integrations — Node, Fetch, Hono, Next.js, SolidStart, Bun, Cloudflare
• Custom storage — write your own adapter against BaseStorage
• Transformers — image / video / audio pipelines, caching
• TUS handler · Chunked uploads · Authenticated uploads
• Batch operations · Retry mechanism · Caching
• Error handling — UploadError, ERRORS enum, wrapStorageError
• Observability — metrics, OpenTelemetry (@visulima/storage/metrics), structured logs
• OpenAPI export
• Migration guide — upgrade notes, including the security fix that makes HTTP file listing opt-in (allowList)

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

• Daniel Bannert
• All Contributors

Made with ❤️ at Anolilab

This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Anolilab is a Development and AI Studio. Contact us at hello@anolilab.com if you need any help with these technologies or just want to say hi!

License

The visulima storage is open-sourced software licensed under the MIT