@remix-run/file-storage 0.9.0 → 0.11.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

@@ -20,30 +20,30 @@ npm install @remix-run/file-storage
 ## Usage
 
 ```ts
-import { LocalFileStorage } from '@remix-run/file-storage/local';
+import { LocalFileStorage } from '@remix-run/file-storage/local'
 
-let storage = new LocalFileStorage('./user/files');
+let storage = new LocalFileStorage('./user/files')
 
-let file = new File(['hello world'], 'hello.txt', { type: 'text/plain' });
-let key = 'hello-key';
+let file = new File(['hello world'], 'hello.txt', { type: 'text/plain' })
+let key = 'hello-key'
 
 // Put the file in storage.
-await storage.set(key, file);
+await storage.set(key, file)
 
 // Then, sometime later...
-let fileFromStorage = await storage.get(key);
+let fileFromStorage = await storage.get(key)
 // All of the original file's metadata is intact
-fileFromStorage.name; // 'hello.txt'
-fileFromStorage.type; // 'text/plain'
+fileFromStorage.name // 'hello.txt'
+fileFromStorage.type // 'text/plain'
 
 // To remove from storage
-await storage.remove(key);
+await storage.remove(key)
 ```
 
 The `FileStorage` interface allows you to implement your own file storage for custom storage backends:
 
 ```ts
-import { type FileStorage } from '@remix-run/file-storage';
+import { type FileStorage } from '@remix-run/file-storage'
 
 class CustomFileStorage implements FileStorage {
   /**
@@ -75,9 +75,9 @@ class CustomFileStorage implements FileStorage {
 
 ## Related Packages
 
-- [`form-data-parser`](https://github.com/remix-run/remix/tree/v3/packages/form-data-parser) - Pairs well with this library for storing `FileUpload` objects received in `multipart/form-data` requests
-- [`lazy-file`](https://github.com/remix-run/remix/tree/v3/packages/lazy-file) - The streaming `File` implementation used internally to stream files from storage
+- [`form-data-parser`](https://github.com/remix-run/remix/tree/main/packages/form-data-parser) - Pairs well with this library for storing `FileUpload` objects received in `multipart/form-data` requests
+- [`lazy-file`](https://github.com/remix-run/remix/tree/main/packages/lazy-file) - The streaming `File` implementation used internally to stream files from storage
 
 ## License
 
-See [LICENSE](https://github.com/remix-run/remix/blob/v3/LICENSE)
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/{file-storage.d.ts → index.d.ts}

@@ -1,2 +1,2 @@
 export type { FileStorage, FileKey, FileMetadata, ListOptions, ListResult, } from './lib/file-storage.ts';
-//# sourceMappingURL=file-storage.d.ts.map
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,OAAO,EACP,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,uBAAuB,CAAA"}

package/dist/index.js

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

package/dist/lib/file-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-storage.d.ts","sourceRoot":"","sources":["../../src/lib/file-storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAErD;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAEjF;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,OAAO;IAC3C;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,WAAW;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,CAAC,CAAC,SAAS;QAAE,eAAe,EAAE,IAAI,CAAA;KAAE,GAAG,YAAY,GAAG,OAAO,CAAC,EAAE,CAAC;CACzE"}
+{"version":3,"file":"file-storage.d.ts","sourceRoot":"","sources":["../../src/lib/file-storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;IAEpD;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0DG;IACH,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;IAEhF;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElD;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnD;AAED,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,OAAO;IAC3C;;OAEG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,WAAW;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,KAAK,EAAE,CAAC,CAAC,SAAS;QAAE,eAAe,EAAE,IAAI,CAAA;KAAE,GAAG,YAAY,GAAG,OAAO,CAAC,EAAE,CAAA;CACxE"}

package/dist/lib/file-storage.js

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

package/dist/lib/local-file-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-file-storage.d.ts","sourceRoot":"","sources":["../../src/lib/local-file-storage.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAgB,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI5F;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,WAAW;;IAGlD;;OAEG;gBACS,SAAS,EAAE,MAAM;IAkBvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAoBtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWlC,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAgDhE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CA2BlD"}
+{"version":3,"file":"local-file-storage.d.ts","sourceRoot":"","sources":["../../src/lib/local-file-storage.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAgB,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAI3F;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,YAAW,WAAW;;IAGlD;;OAEG;gBACS,SAAS,EAAE,MAAM;IAkBvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAoBtC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWlC,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAgDhE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CA2BlD"}

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/lazy-file/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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-file-storage.d.ts","sourceRoot":"","sources":["../../src/lib/memory-file-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;GAEG;AACH,qBAAa,iBAAkB,YAAW,WAAW;;IAGnD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAwCjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CASlD"}
+{"version":3,"file":"memory-file-storage.d.ts","sourceRoot":"","sources":["../../src/lib/memory-file-storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAE7E;;GAEG;AACH,qBAAa,iBAAkB,YAAW,WAAW;;IAGnD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,IAAI,CAAC,CAAC,SAAS,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAwCjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CASlD"}

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);
+    }
+}

package/dist/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../src/local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../src/local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA"}