@remix-run/file-storage 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Michael Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# 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.
+
+## 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`
+
+## Installation
+
+Install from [npm](https://www.npmjs.com/):
+
+```sh
+npm install @remix-run/file-storage
+```
+
+## Usage
+
+```ts
+import { LocalFileStorage } from '@remix-run/file-storage/local';
+
+let storage = new LocalFileStorage('./user/files');
+
+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);
+
+// Then, sometime later...
+let fileFromStorage = await storage.get(key);
+// All of the original file's metadata is intact
+fileFromStorage.name; // 'hello.txt'
+fileFromStorage.type; // 'text/plain'
+
+// To remove from storage
+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';
+
+class CustomFileStorage implements FileStorage {
+  /**
+   * Returns `true` if a file with the given key exists, `false` otherwise.
+   */
+  has(key: string): boolean | Promise<boolean> {
+    // ...
+  }
+  /**
+   * Puts a file in storage at the given key.
+   */
+  set(key: string, file: File): void | Promise<void> {
+    // ...
+  }
+  /**
+   * Returns the file with the given key, or `null` if no such key exists.
+   */
+  get(key: string): File | null | Promise<File | null> {
+    // ...
+  }
+  /**
+   * Removes the file with the given key from storage.
+   */
+  remove(key: string): void | Promise<void> {
+    // ...
+  }
+}
+```
+
+## 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
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/v3/LICENSE)

package/dist/file-storage.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/file-storage.ts
+var file_storage_exports = {};
+module.exports = __toCommonJS(file_storage_exports);
+//# sourceMappingURL=file-storage.cjs.map

package/dist/file-storage.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/file-storage.ts"],
+  "sourcesContent": ["export type {\n  FileStorage,\n  FileKey,\n  FileMetadata,\n  ListOptions,\n  ListResult,\n} from './lib/file-storage.ts';\n"],
+  "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}

package/dist/file-storage.d.ts

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

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

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

package/dist/file-storage.js

@@ -0,0 +1 @@
+//# sourceMappingURL=file-storage.js.map

package/dist/file-storage.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

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

@@ -0,0 +1,158 @@
+/**
+ * A key/value interface for storing `File` objects.
+ */
+export interface FileStorage {
+    /**
+     * Get a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) at the given key.
+     * @param key The key to look up
+     * @returns The file with the given key, or `null` if no such key exists
+     */
+    get(key: string): File | null | Promise<File | null>;
+    /**
+     * Check if a file with the given key exists.
+     * @param key The key to look up
+     * @returns `true` if a file with the given key exists, `false` otherwise
+     */
+    has(key: string): boolean | Promise<boolean>;
+    /**
+     * List the files in storage.
+     *
+     * The following `options` are available:
+     *
+     * - `cursor`: An opaque string that allows you to paginate over the keys in storage
+     * - `includeMetadata`: If `true`, include file metadata in the result
+     * - `limit`: The maximum number of files to return
+     * - `prefix`: Only return keys that start with this string
+     *
+     * For example, to list all files under keys that start with `user123/`:
+     *
+     * ```ts
+     * let result = await storage.list({ prefix: 'user123/' });
+     * console.log(result.files);
+     * // [
+     * //   { key: "user123/..." },
+     * //   { key: "user123/..." },
+     * //   ...
+     * // ]
+     * ```
+     *
+     * `result.files` will be an array of `{ key: string }` objects. To include metadata about each
+     * file, use `includeMetadata: true`.
+     *
+     * ```ts
+     * let result = await storage.list({ prefix: 'user123/', includeMetadata: true });
+     * console.log(result.files);
+     * // [
+     * //   {
+     * //     key: "user123/...",
+     * //     lastModified: 1737955705270,
+     * //     name: "hello.txt",
+     * //     size: 16,
+     * //     type: "text/plain"
+     * //   },
+     * //   ...
+     * // ]
+     * ```
+     *
+     * Pagination is done via an opaque `cursor` property in the list result object. If it is not
+     * `undefined`, there are more files to list. You can list them by passing the `cursor` back in
+     * the `options` object on the next call.
+     *
+     * ```ts
+     * let result = await storage.list();
+     *
+     * console.log(result.files);
+     *
+     * if (result.cursor !== undefined) {
+     *   let result2 = await storage.list({ cursor: result.cursor });
+     * }
+     * ```
+     *
+     * Use the `limit` option to limit how many results you get back in the `files` array.
+     *
+     * @param options Options for the list operation
+     * @returns An object with an array of `files` and an optional `cursor` property
+     */
+    list<T extends ListOptions>(options?: T): ListResult<T> | Promise<ListResult<T>>;
+    /**
+     * Put a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) in storage and return
+     * a new file backed by this storage.
+     * @param key The key to store the file under
+     * @param file The file to store
+     * @returns A new File object backed by this storage
+     */
+    put(key: string, file: File): File | Promise<File>;
+    /**
+     * Remove the file with the given key from storage.
+     * @param key The key to remove
+     * @returns A promise that resolves when the file has been removed
+     */
+    remove(key: string): void | Promise<void>;
+    /**
+     * Put a [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) in storage at the given
+     * key.
+     * @param key The key to store the file under
+     * @param file The file to store
+     * @returns A promise that resolves when the file has been stored
+     */
+    set(key: string, file: File): void | Promise<void>;
+}
+export interface FileKey {
+    /**
+     * The key of the file in storage.
+     */
+    key: string;
+}
+/**
+ * Metadata about a file in storage.
+ */
+export interface FileMetadata extends FileKey {
+    /**
+     * The last modified time of the file (in ms since the Unix epoch).
+     */
+    lastModified: number;
+    /**
+     * The name of the file.
+     */
+    name: string;
+    /**
+     * The size of the file in bytes.
+     */
+    size: number;
+    /**
+     * The MIME type of the file.
+     */
+    type: string;
+}
+export interface ListOptions {
+    /**
+     * An opaque string that allows you to paginate over the keys in storage.
+     */
+    cursor?: string;
+    /**
+     * If `true`, include file metadata in the result.
+     */
+    includeMetadata?: boolean;
+    /**
+     * The maximum number of files to return.
+     */
+    limit?: number;
+    /**
+     * Only return files with keys that start with this prefix.
+     */
+    prefix?: string;
+}
+export interface ListResult<T extends ListOptions> {
+    /**
+     * An opaque string that allows you to paginate over the keys in storage. Pass this back in the
+     * `options` object on the next `list()` call to get the next page of results.
+     */
+    cursor?: string;
+    /**
+     * A list of the files in storage.
+     */
+    files: (T extends {
+        includeMetadata: true;
+    } ? FileMetadata : FileKey)[];
+}
+//# sourceMappingURL=file-storage.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,26 @@
+import type { FileStorage, ListOptions, ListResult } from './file-storage.ts';
+/**
+ * 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 declare class LocalFileStorage implements FileStorage {
+    #private;
+    /**
+     * @param directory The directory where files are stored
+     */
+    constructor(directory: string);
+    get(key: string): Promise<File | null>;
+    has(key: string): Promise<boolean>;
+    list<T extends ListOptions>(options?: T): Promise<ListResult<T>>;
+    put(key: string, file: File): Promise<File>;
+    remove(key: string): Promise<void>;
+    set(key: string, file: File): Promise<void>;
+}
+//# sourceMappingURL=local-file-storage.d.ts.map

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

@@ -0,0 +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;IAYlC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CA2BlD"}

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

@@ -0,0 +1,17 @@
+import type { FileStorage, ListOptions, ListResult } from './file-storage.ts';
+/**
+ * A simple, in-memory implementation of the `FileStorage` interface.
+ *
+ * Note: Any files you put in storage will have their entire contents buffered in memory, so this is not suitable for large files
+ * in production scenarios.
+ */
+export declare class MemoryFileStorage implements FileStorage {
+    #private;
+    get(key: string): File | null;
+    has(key: string): boolean;
+    list<T extends ListOptions>(options?: T): ListResult<T>;
+    put(key: string, file: File): Promise<File>;
+    remove(key: string): void;
+    set(key: string, file: File): Promise<void>;
+}
+//# sourceMappingURL=memory-file-storage.d.ts.map

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

@@ -0,0 +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;;;;;GAKG;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"}