@remix-run/file-storage 0.10.0 → 0.12.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Michael Jackson
+Copyright (c) 2025 Shopify Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,13 +1,17 @@
 # file-storage
 
-`file-storage` is a key/value interface for storing [`File` objects](https://developer.mozilla.org/en-US/docs/Web/API/File) 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.
+`file-storage` is a key/value interface for storing [`File` objects](https://developer.mozilla.org/en-US/docs/Web/API/File) in JavaScript.
+
+Handling file uploads and storage is a common requirement in web applications, but each storage backend (local disk, AWS S3, Cloudflare R2, etc.) has its own API and conventions. This fragmentation makes it difficult to write portable code that can easily switch between storage providers or support multiple backends simultaneously.
+
+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 with a consistent interface regardless of the underlying storage mechanism.
 
 ## Features
 
-- Simple, intuitive key/value API (like [Web Storage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API), but for `File`s 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`
+- **Simple API** - Intuitive key/value API (like [Web Storage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API), but for `File`s instead of strings)
+- **Generic Interface** - `FileStorage` interface that works for various large object storage backends (can be adapted to AWS S3, Cloudflare R2, etc.)
+- **Streaming Support** - Stream file content to and from storage
+- **Metadata Preservation** - Preserves all `File` metadata including `file.name`, `file.type`, and `file.lastModified`
 
 ## Installation
 

package/dist/index.js

@@ -1 +1 @@
-//# sourceMappingURL=index.js.map
+export {};

package/dist/lib/file-storage.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/local-file-storage.js

@@ -0,0 +1,158 @@
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { openFile, writeFile } from '@remix-run/fs';
+/**
+ * A `FileStorage` that is backed by a directory on the local filesystem.
+ *
+ * Important: No attempt is made to avoid overwriting existing files, so the directory used should
+ * be a new directory solely dedicated to this storage object.
+ *
+ * Note: Keys have no correlation to file names on disk, so they may be any string including
+ * characters that are not valid in file names. Additionally, individual `File` names have no
+ * correlation to names of files on disk, so multiple files with the same name may be stored in the
+ * same storage object.
+ */
+export class LocalFileStorage {
+    #dirname;
+    /**
+     * @param directory The directory where files are stored
+     */
+    constructor(directory) {
+        this.#dirname = path.resolve(directory);
+        try {
+            let stats = fs.statSync(this.#dirname);
+            if (!stats.isDirectory()) {
+                throw new Error(`Path "${this.#dirname}" is not a directory`);
+            }
+        }
+        catch (error) {
+            if (!isNoEntityError(error)) {
+                throw error;
+            }
+            fs.mkdirSync(this.#dirname, { recursive: true });
+        }
+    }
+    async get(key) {
+        let { filePath, metaPath } = await this.#getPaths(key);
+        try {
+            let meta = await readMetadata(metaPath);
+            return openFile(filePath, {
+                lastModified: meta.lastModified,
+                name: meta.name,
+                type: meta.type,
+            });
+        }
+        catch (error) {
+            if (!isNoEntityError(error)) {
+                throw error;
+            }
+            return null;
+        }
+    }
+    async has(key) {
+        let { metaPath } = await this.#getPaths(key);
+        try {
+            await fsp.access(metaPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async list(options) {
+        let { cursor, includeMetadata = false, limit = 32, prefix } = options ?? {};
+        let files = [];
+        let foundCursor = cursor === undefined;
+        let nextCursor;
+        let lastHash;
+        outerLoop: for await (let subdir of await fsp.opendir(this.#dirname)) {
+            if (!subdir.isDirectory())
+                continue;
+            for await (let file of await fsp.opendir(path.join(this.#dirname, subdir.name))) {
+                if (!file.isFile() || !file.name.endsWith('.meta.json'))
+                    continue;
+                let hash = file.name.slice(0, -10); // Remove ".meta.json"
+                if (foundCursor) {
+                    let meta = await readMetadata(path.join(this.#dirname, subdir.name, file.name));
+                    if (prefix != null && !meta.key.startsWith(prefix)) {
+                        continue;
+                    }
+                    if (files.length >= limit) {
+                        nextCursor = lastHash;
+                        break outerLoop;
+                    }
+                    if (includeMetadata) {
+                        let size = (await fsp.stat(path.join(this.#dirname, subdir.name, `${hash}.dat`))).size;
+                        files.push({ ...meta, size });
+                    }
+                    else {
+                        files.push({ key: meta.key });
+                    }
+                }
+                else if (hash === cursor) {
+                    foundCursor = true;
+                }
+                lastHash = hash;
+            }
+        }
+        return {
+            cursor: nextCursor,
+            files,
+        };
+    }
+    async put(key, file) {
+        await this.set(key, file);
+        return (await this.get(key));
+    }
+    async remove(key) {
+        let { directory, filePath, metaPath } = await this.#getPaths(key);
+        try {
+            await Promise.all([fsp.unlink(filePath), fsp.unlink(metaPath)]);
+            // Check if directory is empty and remove it if so
+            let files = await fsp.readdir(directory);
+            if (files.length === 0) {
+                await fsp.rmdir(directory);
+            }
+        }
+        catch (error) {
+            if (!isNoEntityError(error)) {
+                throw error;
+            }
+        }
+    }
+    async set(key, file) {
+        let { directory, filePath, metaPath } = await this.#getPaths(key);
+        // Ensure directory exists
+        await fsp.mkdir(directory, { recursive: true });
+        await writeFile(filePath, file);
+        let meta = {
+            key,
+            lastModified: file.lastModified,
+            name: file.name,
+            type: file.type,
+        };
+        await fsp.writeFile(metaPath, JSON.stringify(meta));
+    }
+    async #getPaths(key) {
+        let hash = await computeHash(key);
+        let directory = path.join(this.#dirname, hash.slice(0, 2));
+        return {
+            directory,
+            filePath: path.join(directory, `${hash}.dat`),
+            metaPath: path.join(directory, `${hash}.meta.json`),
+        };
+    }
+}
+async function readMetadata(metaPath) {
+    return JSON.parse(await fsp.readFile(metaPath, 'utf-8'));
+}
+async function computeHash(key, algorithm = 'SHA-256') {
+    let digest = await crypto.subtle.digest(algorithm, new TextEncoder().encode(key));
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function isNoEntityError(obj) {
+    return obj instanceof Error && 'code' in obj && obj.code === 'ENOENT';
+}

package/dist/lib/memory-file-storage.js

@@ -0,0 +1,63 @@
+/**
+ * A simple, in-memory implementation of the `FileStorage` interface.
+ */
+export class MemoryFileStorage {
+    #map = new Map();
+    get(key) {
+        return this.#map.get(key) ?? null;
+    }
+    has(key) {
+        return this.#map.has(key);
+    }
+    list(options) {
+        let { cursor, includeMetadata = false, limit = Infinity, prefix } = options ?? {};
+        let files = [];
+        let foundCursor = cursor === undefined;
+        let nextCursor;
+        for (let [key, file] of this.#map.entries()) {
+            if (foundCursor) {
+                if (prefix != null && !key.startsWith(prefix)) {
+                    continue;
+                }
+                if (files.length >= limit) {
+                    nextCursor = files[files.length - 1]?.key;
+                    break;
+                }
+                if (includeMetadata) {
+                    files.push({
+                        key,
+                        lastModified: file.lastModified,
+                        name: file.name,
+                        size: file.size,
+                        type: file.type,
+                    });
+                }
+                else {
+                    files.push({ key });
+                }
+            }
+            else if (key === cursor) {
+                foundCursor = true;
+            }
+        }
+        return {
+            cursor: nextCursor,
+            files,
+        };
+    }
+    async put(key, file) {
+        await this.set(key, file);
+        return this.get(key);
+    }
+    remove(key) {
+        this.#map.delete(key);
+    }
+    async set(key, file) {
+        let buffer = await file.arrayBuffer();
+        let newFile = new File([buffer], file.name, {
+            lastModified: file.lastModified,
+            type: file.type,
+        });
+        this.#map.set(key, newFile);
+    }
+}