remix 3.0.0-beta.0 → 3.0.0-beta.2

package/src/fetch-router.ts

@@ -1,2 +1,9 @@
 // IMPORTANT: This file is auto-generated, please do not edit manually.
 export * from '@remix-run/fetch-router'
+
+export interface RouterTypes {}
+type RemixRouterTypes = RouterTypes
+
+declare module '@remix-run/fetch-router' {
+  interface RouterTypes extends RemixRouterTypes {}
+}

package/src/file-storage/README.md

@@ -0,0 +1,57 @@
+# file-storage
+
+Key/value storage interfaces for server-side [`File` objects](https://developer.mozilla.org/en-US/docs/Web/API/File). `file-storage` gives Remix apps one consistent API across local disk and memory backends.
+
+## Features
+
+- **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)
+- **Multiple Backends** - Built-in filesystem and memory backends
+- **Streaming Support** - Stream file content to and from storage
+- **Metadata Preservation** - Preserves all `File` metadata including `file.name`, `file.type`, `file.size`, and `file.lastModified`
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+### File System
+
+```ts
+import { createFsFileStorage } from 'remix/file-storage/fs'
+
+let storage = createFsFileStorage('./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)
+
+if (fileFromStorage != null) {
+  // All of the original file's metadata is intact
+  fileFromStorage.name // 'hello.txt'
+  fileFromStorage.type // 'text/plain'
+
+  // The filesystem backend returns a LazyFile, so you can stream it directly.
+  let response = new Response(fileFromStorage.stream())
+}
+
+// To remove from storage
+await storage.remove(key)
+```
+
+## Related Packages
+
+- [`file-storage-s3`](https://github.com/remix-run/remix/tree/main/packages/file-storage-s3) - S3 backend for `file-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/main/LICENSE)

package/src/file-storage-s3/README.md

@@ -0,0 +1,47 @@
+# file-storage-s3
+
+S3 backend for [`remix/file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage).
+Use this package when you want the `FileStorage` API backed by AWS S3 or an S3-compatible provider.
+
+## Features
+
+- **S3-Compatible API** - Works with AWS S3 and S3-compatible APIs (e.g. MinIO, LocalStack)
+- **Metadata Preservation** - Preserves `File` metadata (`name`, `type`, `size`, `lastModified`)
+- **Runtime-Agnostic Signing** - Uses [`aws4fetch`](https://github.com/mhart/aws4fetch) for SigV4 signing
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+```ts
+import { createS3FileStorage } from 'remix/file-storage/s3'
+
+let storage = createS3FileStorage({
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  bucket: 'my-app-uploads',
+  region: 'us-east-1',
+})
+
+await storage.set(
+  'uploads/hello.txt',
+  new File(['hello world'], 'hello.txt', { type: 'text/plain' }),
+)
+let file = await storage.get('uploads/hello.txt')
+await storage.remove('uploads/hello.txt')
+```
+
+For S3-compatible providers such as MinIO and LocalStack, set `endpoint` and `forcePathStyle: true`.
+
+## Related Packages
+
+- [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) - Core `FileStorage` interface and filesystem/memory backends
+- [`form-data-parser`](https://github.com/remix-run/remix/tree/main/packages/form-data-parser) - Parses `multipart/form-data` uploads into `FileUpload` objects
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/form-data-middleware/README.md

@@ -0,0 +1,109 @@
+# form-data-middleware
+
+Form body parsing middleware for Remix. It parses incoming [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and exposes it via `context.formData` (or `context.get(FormData)`).
+
+## Features
+
+- **Request Form Parsing** - Parses request body form data once per request
+- **File Access** - Uploaded files are available from `context.formData` (or `context.get(FormData)`)
+- **Custom Upload Handling** - Supports pluggable upload handlers for file processing
+- **Error Control** - Optional suppression for malformed form data
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+Use the `formData()` middleware at the router level to parse `FormData` from the request body and make it available as `context.formData` (or `context.get(FormData)`).
+
+When `formData()` runs successfully it always provides a `FormData` value. Requests that do not contain a form body, including `GET` and `HEAD` requests, receive an empty `FormData`.
+
+Uploaded files are available in the parsed `FormData` object. For a single file field, use `formData.get(name)`. For repeated file fields, use `formData.getAll(name)`.
+
+```ts
+import { createRouter } from 'remix/router'
+import { formData } from 'remix/middleware/form-data'
+
+let router = createRouter({
+  middleware: [formData()],
+})
+
+router.post('/users', async (context) => {
+  let formData = context.formData
+  let name = formData.get('name')
+  let email = formData.get('email')
+
+  // Handle file uploads
+  let avatar = formData.get('avatar')
+
+  return Response.json({ name, email, hasAvatar: avatar instanceof File })
+})
+```
+
+Use `context.formData` (or `context.get(FormData)`).
+
+### Custom File Upload Handler
+
+You can use a custom upload handler to customize how file uploads are handled. The return value of the upload handler will be used as the value of the form field in the `FormData` object.
+
+```ts
+import { formData } from 'remix/middleware/form-data'
+import { writeFile } from 'node:fs/promises'
+
+let router = createRouter({
+  middleware: [
+    formData({
+      async uploadHandler(upload) {
+        // Save to disk and return path
+        let path = `./uploads/${upload.name}`
+        await writeFile(path, Buffer.from(await upload.arrayBuffer()))
+        return path
+      },
+    }),
+  ],
+})
+```
+
+### Limit Multipart Growth
+
+`formData()` forwards multipart limit options to `parseFormData()`, so you can cap uploads with
+`maxHeaderSize`, `maxFiles`, `maxFileSize`, `maxParts`, and `maxTotalSize`.
+
+```ts
+let router = createRouter({
+  middleware: [
+    formData({
+      maxFiles: 5,
+      maxFileSize: 10 * 1024 * 1024,
+      maxParts: 25,
+      maxTotalSize: 12 * 1024 * 1024,
+    }),
+  ],
+})
+```
+
+### Suppress Parse Errors
+
+Some requests may contain invalid form data that cannot be parsed. You can suppress those malformed-body parse errors by setting `suppressErrors` to `true`. In these cases, `context.formData` will be an empty `FormData` object. Multipart limit violations from `maxHeaderSize`, `maxFiles`, `maxFileSize`, `maxParts`, or `maxTotalSize` are never suppressed.
+
+```ts
+let router = createRouter({
+  middleware: [
+    formData({
+      suppressErrors: true, // Invalid form data won't throw
+    }),
+  ],
+})
+```
+
+## Related Packages
+
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - Router for the web Fetch API
+- [`form-data-parser`](https://github.com/remix-run/remix/tree/main/packages/form-data-parser) - The underlying form data parser
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/form-data-parser/README.md

@@ -0,0 +1,160 @@
+# form-data-parser
+
+A streaming `multipart/form-data` parser that solves memory issues with file uploads in server environments. Built as an enhanced replacement for the native `request.formData()` API, it enables efficient handling of large file uploads by streaming directly to disk or cloud storage services like [AWS S3](https://aws.amazon.com/s3/) or [Cloudflare R2](https://www.cloudflare.com/developer-platform/r2/), preventing server crashes from memory exhaustion.
+
+## Features
+
+- **Drop-in replacement** for `request.formData()` with streaming file upload support
+- **Minimal buffering** - processes file upload streams with minimal memory footprint
+- **Standards-based** - built on the [web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) and [File API](https://developer.mozilla.org/en-US/docs/Web/API/File)
+- **Smart fallback** - automatically uses native `request.formData()` for non-`multipart/form-data` requests
+- **Storage agnostic** - works with any storage backend (local disk, S3, R2, etc.)
+
+## Why You Need This
+
+The native [`request.formData()` method](https://developer.mozilla.org/en-US/docs/Web/API/Request/formData) has a few major flaws in server environments:
+
+- It buffers all file uploads in memory
+- It does not provide fine-grained control over file upload handling
+- It does not prevent DoS attacks from malicious requests
+
+In normal usage, this makes it difficult to process requests with large file uploads because they can exhaust your server's RAM and crash the application.
+
+For attackers, this creates an attack vector where malicious actors can overwhelm your server's memory by sending large payloads with many files.
+
+`form-data-parser` solves this by handling file uploads as they arrive in the request body stream, allowing you to safely store files and use either a) the `File` directly or b) a unique identifier for that file in the returned `FormData` object.
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+The `parseFormData` interface allows you to define an "upload handler" function for fine-grained control of handling file uploads.
+
+```ts
+import * as fsp from 'node:fs/promises'
+import type { FileUpload } from 'remix/form-data-parser'
+import { parseFormData } from 'remix/form-data-parser'
+
+// Define how to handle incoming file uploads
+async function uploadHandler(fileUpload: FileUpload) {
+  // Is this file upload from the <input type="file" name="user-avatar"> field?
+  if (fileUpload.fieldName === 'user-avatar') {
+    let filename = `/uploads/user-${user.id}-avatar.bin`
+
+    // Store the file safely on disk
+    await fsp.writeFile(filename, fileUpload.bytes)
+
+    // Return the file name to use in the FormData object so we don't
+    // keep the file contents around in memory.
+    return filename
+  }
+
+  // Ignore unrecognized fields
+}
+
+// Handle form submissions with file uploads
+async function requestHandler(request: Request) {
+  // Parse the form data from the request.body stream, passing any files
+  // through your upload handler as they are parsed from the stream
+  let formData = await parseFormData(request, uploadHandler)
+
+  let avatarFilename = formData.get('user-avatar')
+
+  if (avatarFilename != null) {
+    console.log(`User avatar uploaded to ${avatarFilename}`)
+  } else {
+    console.log(`No user avatar file was uploaded`)
+  }
+}
+```
+
+To validate the resulting `FormData` object with `remix/data-schema`, use the
+`remix/data-schema/form-data` helpers.
+
+To limit the overall shape of multipart requests, use the `maxHeaderSize`, `maxFileSize`, `maxFiles`, `maxParts`, and `maxTotalSize` options. By default, `parseFormData()` uses `maxFiles = 20`, `maxParts = 1000`, and `maxTotalSize = maxFiles * maxFileSize + 1 MiB`.
+
+Known limit errors are thrown directly so you can handle them with `instanceof` checks. Other failures while parsing the request body are wrapped in `FormDataParseError`, with the original error available as `error.cause`. Errors thrown or rejected by your `uploadHandler` are not wrapped.
+
+```ts
+import {
+  FormDataParseError,
+  MaxFilesExceededError,
+  MaxFileSizeExceededError,
+  MaxHeaderSizeExceededError,
+  MaxPartsExceededError,
+  MaxTotalSizeExceededError,
+} from 'remix/form-data-parser'
+
+const oneKb = 1024
+const oneMb = 1024 * oneKb
+
+try {
+  let formData = await parseFormData(request, {
+    maxFiles: 5,
+    maxFileSize: 10 * oneMb,
+    maxParts: 25,
+    maxTotalSize: 12 * oneMb,
+  })
+} catch (error) {
+  if (error instanceof MaxFilesExceededError) {
+    console.error(`Request may not contain more than 5 files`)
+  } else if (error instanceof MaxHeaderSizeExceededError) {
+    console.error(`Multipart headers may not exceed the configured size limit`)
+  } else if (error instanceof MaxFileSizeExceededError) {
+    console.error(`Files may not be larger than 10 MiB`)
+  } else if (error instanceof MaxPartsExceededError) {
+    console.error(`Request may not contain more than 25 multipart parts`)
+  } else if (error instanceof MaxTotalSizeExceededError) {
+    console.error(`Multipart request may not exceed 12 MiB of total content`)
+  } else if (error instanceof FormDataParseError) {
+    console.error(`Could not parse form data:`, error.cause ?? error)
+  } else {
+    throw error
+  }
+}
+```
+
+If you're looking for a more flexible storage solution for `FileUpload` objects, this library pairs really well with [the `file-storage` library](https://github.com/remix-run/remix/tree/main/packages/file-storage) for keeping files in various storage backends.
+
+```ts
+import { createFsFileStorage } from 'remix/file-storage/fs'
+import type { FileUpload } from 'remix/form-data-parser'
+import { parseFormData } from 'remix/form-data-parser'
+
+// Set up storage for uploaded files
+const fileStorage = createFsFileStorage('/uploads/user-avatars')
+
+// Define how to handle incoming file uploads
+async function uploadHandler(fileUpload: FileUpload) {
+  // Is this file upload from the <input type="file" name="user-avatar"> field?
+  if (fileUpload.fieldName === 'user-avatar') {
+    let storageKey = `user-${user.id}-avatar`
+
+    // Put the file in storage and return the stored LazyFile
+    return fileStorage.put(storageKey, fileUpload)
+  }
+
+  // Ignore unrecognized fields
+}
+```
+
+## Demos
+
+The [`demos` directory](https://github.com/remix-run/remix/tree/main/packages/form-data-parser/demos) contains working demos:
+
+- [`demos/node`](https://github.com/remix-run/remix/tree/main/packages/form-data-parser/demos/node) - using form-data-parser with file-storage in Node.js
+
+## Related Packages
+
+- [`data-schema`](https://github.com/remix-run/remix/tree/main/packages/data-schema) - Tiny,
+  standards-aligned validation with a `form-data` export for `FormData` and `URLSearchParams`
+- [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) - A simple key/value interface for storing `FileUpload` objects you get from the parser
+- [`multipart-parser`](https://github.com/remix-run/remix/tree/main/packages/multipart-parser) - The parser used internally for parsing `multipart/form-data` HTTP messages
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/src/fs/README.md

@@ -0,0 +1,60 @@
+# fs
+
+Lazy, streaming filesystem utilities for JavaScript. This package provides utilities for working with files on the local filesystem using the [`LazyFile`](https://github.com/remix-run/remix/tree/main/packages/lazy-file)/ native [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) API.
+
+## Features
+
+- **Web Standards** - Uses [`LazyFile`](https://github.com/remix-run/remix/tree/main/packages/lazy-file) which matches the native [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) API and provides `.stream()`, `.toFile()`, and `.toBlob()` for converting to native types.
+- **Seamless Node.js Compat** - Works seamlessly with Node.js file descriptors and handles
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+### Opening Lazy Files
+
+```ts
+import { openLazyFile } from 'remix/fs'
+
+// Open a file from the filesystem
+let lazyFile = openLazyFile('./path/to/file.json')
+
+// The file is lazy - no data is read until you call lazyFile.text(), lazyFile.bytes(), etc.
+let json = JSON.parse(await lazyFile.text())
+
+// You can override file metadata
+let customLazyFile = openLazyFile('./image.jpg', {
+  name: 'custom-name.jpg',
+  type: 'image/jpeg',
+  lastModified: Date.now(),
+})
+```
+
+### Writing Files
+
+```ts
+import { openLazyFile, writeFile } from 'remix/fs'
+
+// Read a file and write it elsewhere
+let lazyFile = openLazyFile('./source.txt')
+await writeFile('./destination.txt', lazyFile)
+
+// Write to an open file handle
+import * as fsp from 'node:fs/promises'
+let handle = await fsp.open('./destination.txt', 'w')
+await writeFile(handle, lazyFile)
+await handle.close()
+```
+
+## Related Packages
+
+- [`lazy-file`](https://github.com/remix-run/remix/tree/main/packages/lazy-file) - Lazy, streaming `Blob`/`File` implementation
+- [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) - Storage abstraction for files
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)