file-storage

file-storage is a key/value interface for storing File objects in JavaScript. Similar to how localStorage allows you to store key/value pairs of strings in the browser, file-storage allows you to store key/value pairs of files on the server.

Features

• Simple, intuitive key/value API (like Web Storage, but for Files instead of strings)
• A generic FileStorage interface that works for various large object storage backends (can be adapted to AWS S3, Cloudflare R2, etc.)
• Support streaming file content to and from storage
• Preserves all File metadata including file.name, file.type, and file.lastModified

Installation

Install from npm:

1npm install @mjackson/file-storage

Usage

1import { LocalFileStorage } from '@mjackson/file-storage/local';
2
3let storage = new LocalFileStorage('./user/files');
4
5let file = new File(['hello world'], 'hello.txt', { type: 'text/plain' });
6let key = 'hello-key';
7
8// Put the file in storage.
9await storage.set(key, file);
10
11// Then, sometime later...
12let fileFromStorage = await storage.get(key);
13// All of the original file's metadata is intact
14fileFromStorage.name; // 'hello.txt'
15fileFromStorage.type; // 'text/plain'
16
17// To remove from storage
18await storage.remove(key);

The FileStorage interface allows you to implement your own file storage for custom storage backends:

1import { type FileStorage } from '@mjackson/file-storage';
2
3class CustomFileStorage implements FileStorage {
4  /**
5   * Returns `true` if a file with the given key exists, `false` otherwise.
6   */
7  has(key: string): boolean | Promise<boolean> {
8    // ...
9  }
10  /**
11   * Puts a file in storage at the given key.
12   */
13  set(key: string, file: File): void | Promise<void> {
14    // ...
15  }
16  /**
17   * Returns the file with the given key, or `null` if no such key exists.
18   */
19  get(key: string): File | null | Promise<File | null> {
20    // ...
21  }
22  /**
23   * Removes the file with the given key from storage.
24   */
25  remove(key: string): void | Promise<void> {
26    // ...
27  }
28}

Related Packages

• form-data-parser - Pairs well with this library for storing FileUpload objects received in multipart/form-data requests
• lazy-file - The streaming File implementation used internally to stream files from storage

License

See LICENSE