remix 3.0.0-beta.3 → 3.0.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remix",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.4",
   "description": "The Remix web framework",
   "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
@@ -529,50 +529,50 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@remix-run/assets": "^0.4.2",
-    "@remix-run/auth": "^0.2.4",
-    "@remix-run/compression-middleware": "^0.1.10",
-    "@remix-run/cop-middleware": "^0.1.5",
-    "@remix-run/csrf-middleware": "^0.1.5",
-    "@remix-run/cors-middleware": "^0.1.5",
+    "@remix-run/assets": "^0.4.3",
+    "@remix-run/auth": "^0.2.5",
+    "@remix-run/async-context-middleware": "^0.3.3",
     "@remix-run/ui": "^0.3.0",
-    "@remix-run/async-context-middleware": "^0.3.2",
-    "@remix-run/auth-middleware": "^0.2.2",
-    "@remix-run/cookie": "^0.5.4",
+    "@remix-run/compression-middleware": "^0.1.11",
+    "@remix-run/auth-middleware": "^0.2.3",
+    "@remix-run/cop-middleware": "^0.1.6",
+    "@remix-run/csrf-middleware": "^0.1.6",
+    "@remix-run/cors-middleware": "^0.1.6",
     "@remix-run/data-schema": "^0.3.0",
+    "@remix-run/data-table": "^0.3.0",
+    "@remix-run/cookie": "^0.5.4",
     "@remix-run/data-table-postgres": "^0.4.0",
-    "@remix-run/data-table-sqlite": "^0.5.1",
     "@remix-run/data-table-mysql": "^0.4.0",
-    "@remix-run/data-table": "^0.3.0",
-    "@remix-run/fetch-router": "^0.19.2",
-    "@remix-run/file-storage": "^0.13.6",
+    "@remix-run/data-table-sqlite": "^0.5.1",
     "@remix-run/fetch-proxy": "^0.8.3",
+    "@remix-run/fetch-router": "^0.20.0",
+    "@remix-run/file-storage": "^0.13.6",
+    "@remix-run/form-data-middleware": "^0.3.3",
     "@remix-run/file-storage-s3": "^0.1.3",
-    "@remix-run/form-data-middleware": "^0.3.2",
-    "@remix-run/form-data-parser": "^0.17.3",
-    "@remix-run/fs": "^0.4.5",
     "@remix-run/headers": "^0.21.1",
-    "@remix-run/lazy-file": "^5.0.5",
+    "@remix-run/fs": "^0.4.5",
+    "@remix-run/form-data-parser": "^0.17.3",
     "@remix-run/html-template": "^0.3.1",
-    "@remix-run/logger-middleware": "^0.3.2",
-    "@remix-run/method-override-middleware": "^0.1.10",
-    "@remix-run/multipart-parser": "^0.16.3",
+    "@remix-run/method-override-middleware": "^0.1.11",
+    "@remix-run/logger-middleware": "^0.3.3",
     "@remix-run/mime": "^0.4.1",
+    "@remix-run/multipart-parser": "^0.16.3",
+    "@remix-run/lazy-file": "^5.0.5",
     "@remix-run/node-fetch-server": "^0.13.3",
-    "@remix-run/response": "^0.3.6",
     "@remix-run/node-tsx": "^0.1.1",
-    "@remix-run/route-pattern": "^0.22.0",
+    "@remix-run/route-pattern": "^0.22.1",
+    "@remix-run/response": "^0.3.6",
     "@remix-run/session": "^0.4.2",
-    "@remix-run/session-middleware": "^0.3.2",
-    "@remix-run/session-storage-memcache": "^0.1.2",
-    "@remix-run/static-middleware": "^0.4.11",
     "@remix-run/session-storage-redis": "^0.1.1",
+    "@remix-run/session-middleware": "^0.3.3",
+    "@remix-run/session-storage-memcache": "^0.1.2",
+    "@remix-run/static-middleware": "^0.4.12",
+    "@remix-run/assert": "^0.3.0",
     "@remix-run/tar-parser": "^0.7.1",
-    "@remix-run/cli": "^0.3.2",
-    "@remix-run/assert": "^0.2.1",
+    "@remix-run/cli": "^0.3.3",
+    "@remix-run/test": "^0.5.0",
     "@remix-run/terminal": "^0.1.1",
-    "@remix-run/test": "^0.4.2",
-    "@remix-run/render-middleware": "^0.1.2"
+    "@remix-run/render-middleware": "^0.1.3"
   },
   "bin": {
     "remix": "./dist/cli-entry.js"
@@ -600,6 +600,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "git clean -fdX",
+    "sync-readmes": "node ../../scripts/sync-remix-readmes.ts",
     "test": "remix-test",
     "typecheck": "tsc --noEmit"
   }

package/src/assert/README.md

@@ -2,14 +2,14 @@
 
 A compatible subset of `node:assert/strict` that works in any JavaScript environment, including browsers — plus a vitest-/jest-style `expect` API for tests that prefer chainable matchers.
 
-Uses strict equality (`===`) for all comparisons — no type coercion.
+Uses strict equality (`Object.is`) for all comparisons — no type coercion.
 
 ## Features
 
 - `AssertionError` — compatible with `node:assert.AssertionError` (`actual`, `expected`, `operator`, `name`)
 - `assert.ok` — truthy check
-- `assert.equal` / `assert.notEqual` — strict equality (`===` / `!==`)
-- `assert.deepEqual` / `assert.notDeepEqual` — recursive strict deep equality
+- `assert.equal` / `assert.notEqual` — strict equality (`Object.is` / `!Object.is`)
+- `assert.deepEqual` / `assert.partialDeepEqual` / `assert.notDeepEqual` — recursive strict deep equality
 - `assert.match` — string matches a regexp
 - `assert.fail` — unconditional failure
 - `assert.throws` — synchronous throw assertion with optional error validation
@@ -24,17 +24,20 @@ npm i remix
 
 ## Usage
 
-Mirrors `node:assert/strict` — uses strict equality (`===`), so `1 !== '1'` and `null !== undefined`.
+Mirrors `node:assert/strict` — uses strict equality (`Object.is`), so `1 !== '1'`, `null !== undefined`, `NaN` equals `NaN`, and `0` does not equal `-0`.
 
 ```ts
 import assert from 'remix/assert'
 
 assert.ok(true)
+assert(true)
 assert.equal(1, 1)
 assert.equal(1, '1') // throws — different types
+assert.equal(NaN, NaN)
 assert.notEqual('a', 'b')
 assert.deepEqual({ a: 1 }, { a: 1 })
 assert.deepEqual({ a: 1 }, { a: '1' }) // throws — different types
+assert.partialDeepEqual({ a: 1, b: 2 }, { a: 1 })
 assert.match('hello world', /world/)
 assert.fail('should not reach here')
 
@@ -64,11 +67,15 @@ import {
   equal,
   notEqual,
   deepEqual,
+  partialDeepEqual,
   notDeepEqual,
   match,
+  doesNotMatch,
   fail,
   throws,
+  doesNotThrow,
   rejects,
+  doesNotReject,
 } from 'remix/assert'
 ```
 

package/src/fetch-router/README.md

@@ -8,7 +8,7 @@ A minimal, composable router built on the [web Fetch API](https://developer.mozi
 - **Type-Safe Routing**: Leverage TypeScript for compile-time route validation and parameter inference
 - **Typed Request Context**: Carry request-scoped context through routers, controllers, and actions
 - **Declarative Route Maps**: Define your route structure upfront with type-safe route names and request methods
-- **Flexible Middleware**: Apply middleware globally, per-route, or to controllers
+- **Flexible Middleware**: Use router, controller, and action middleware for each request boundary
 - **Easy Testing**: Use standard `fetch()` to test your routes - no special test harness required
 
 ## Installation
@@ -237,6 +237,85 @@ router.map(routes.contact, {
 })
 ```
 
+### Composing Route Groups
+
+As applications grow, it is useful to let one file own the routes for a specific area of the app while the top-level router decides where that area is mounted. Use `router.mount()` with a route installer to register a group of routes under a route pattern prefix.
+
+A route installer receives a `RouteBuilder`, not a full `Router`, so it can register routes but cannot dispatch requests. The parent router remains the only router that owns request dispatch, the matcher, and the default handler.
+
+```ts
+import { createRouter, type RouteBuilder } from 'remix/router'
+import { get, route } from 'remix/routes'
+
+const adminRouteDefs = {
+  index: get('/'),
+  users: {
+    show: get('/users/:id'),
+  },
+}
+
+// Use relative route groups inside installers. These routes are registered below
+// the mount prefix when `installAdminRoutes()` runs.
+const adminRouteGroup = route(adminRouteDefs)
+
+// Use full app routes for links and redirects.
+const routes = {
+  admin: route('/admin', adminRouteDefs),
+}
+
+function installAdminRoutes<context extends AppContext>(router: RouteBuilder<context>) {
+  router.map(adminRouteGroup, {
+    actions: {
+      index() {
+        return new Response('Admin')
+      },
+    },
+  })
+
+  router.map(adminRouteGroup.users, {
+    actions: {
+      show({ params, currentUser }) {
+        return new Response(`User ${params.id} for ${currentUser.id}`)
+      },
+    },
+  })
+}
+
+let router = createRouter<AppContext>({ middleware })
+
+router.mount('/admin', installAdminRoutes)
+```
+
+Mount prefixes are route patterns. They compose with routes registered inside the installer using `joinPatterns()`, so params from the mount prefix are available to mounted handlers:
+
+```ts
+router.mount('/orgs/:orgId', (org) => {
+  org.get('/users/:userId', ({ params }) => {
+    // params is { orgId: string, userId: string }
+    return new Response(`${params.orgId}:${params.userId}`)
+  })
+})
+```
+
+When a mount prefix and child route use the same param name, the right-most route param wins, matching `route-pattern` behavior.
+
+Middleware stays on routers, controllers, and actions. If an entire route group needs auth or another boundary, put that middleware on the controllers or actions owned by the installer:
+
+```ts
+function installAdminRoutes<context extends AppContext>(router: RouteBuilder<context>) {
+  router.map(adminRouteGroup, {
+    middleware: [requireAdmin()],
+    actions: {
+      index({ admin }) {
+        return new Response(admin.id)
+      },
+    },
+  })
+}
+```
+
+Unknown paths below a mounted prefix fall through to the parent router's default handler. If a route group needs its own catch-all response, register one explicitly inside the installer.
+
 ### Declaring Routes
 
 In addition to the `{ method, pattern }` syntax shown above, the router provides a few shorthand methods that help eliminate some of the boilerplate when building complex route maps:
@@ -504,10 +583,12 @@ type Routes = typeof routes
 
 Middleware functions run code before and/or after actions. They are a powerful way to add functionality to your app.
 
+Every middleware must either return a `Response`, return the response from `next()`, or call `await next()` before it returns. Middleware that returns without calling `next()` throws at runtime.
+
 A basic logging middleware might look like this:
 
 ```ts
-import type { Middleware } from 'remix/router'
+import { type Middleware } from 'remix/router'
 
 // You can use the `Middleware` type to type middleware functions.
 function logger(): Middleware {
@@ -567,8 +648,9 @@ function loadDatabase(): Middleware<{
   value: Database
   property: 'db'
 }> {
-  return async (context) => {
+  return async (context, next) => {
     context.set(Database, await connectDatabase(), { property: 'db' })
+    return next()
   }
 }
 
@@ -580,13 +662,13 @@ router.get('/books', async (context) => {
 
 Use `context.db` (or `context.get(Database)`). If two values use the same property name, the router throws.
 
-Middleware may be used at three levels: globally on the router, on a controller, or inline on an individual action.
+Middleware has three API-owned forms: router middleware, controller middleware, and action middleware.
 
-Global middleware is added to the router when it is created using the `createRouter({ middleware })` option. This middleware runs before any routes are matched and is useful for doing things like logging, serving static files, profiling, and a variety of other things. Global middleware runs on every request, so it's important to keep them lightweight and fast.
+Router middleware is added to the router when it is created using the `createRouter({ middleware })` option. This middleware runs before any routes are matched and is useful for doing things like logging, serving static files, profiling, and a variety of other things. Router middleware runs on every request, so it's important to keep it lightweight and fast.
 
-Controller middleware runs for every direct action in a controller. Action middleware runs only for one action, whether that action is registered in a controller or directly with `router.map()` or one of the method-specific helpers like `router.get()`, `router.post()`, `router.put()`, `router.delete()`, etc. The object form for actions is `{ handler, middleware? }`, so you can omit `middleware` entirely when you do not need it.
+Controller middleware runs for every direct action in a controller. Action middleware runs only for one action, whether that action is created with `createAction()`, registered in a controller, or registered directly with `router.map()` or one of the method-specific helpers like `router.get()`, `router.post()`, `router.put()`, `router.delete()`, etc. The object form for actions is `{ handler, middleware? }`, so you can omit `middleware` entirely when you do not need it.
 
-A controller's `middleware` applies only to the direct route actions in that controller, and its `actions` object may not include nested route-map keys. Map nested route maps explicitly so each controller owns the direct route actions for one route map.
+A controller's `middleware` applies only to the direct route actions in that controller, and its `actions` object may not include nested route-map keys. This is the router's scoped middleware model: map nested route maps explicitly so each controller owns the direct route actions for one route map, and share middleware arrays between controllers that need the same boundary.
 
 ```tsx
 let routes = route({
@@ -598,21 +680,21 @@ let routes = route({
 })
 
 let router = createRouter({
-  // This middleware runs on all requests.
+  // Router middleware runs on all requests.
   middleware: [staticFiles('./public')],
 })
 
 router.map(routes.home, () => new Response('Home'))
 
 router.map(routes.admin, {
-  // This middleware applies to all actions in this controller.
+  // Controller middleware applies to all direct actions in this controller.
   middleware: [auth({ token: 'secret' })],
   actions: {
     dashboard() {
       return new Response('Dashboard')
     },
     settings: {
-      // This middleware applies only to this action.
+      // Action middleware applies only to this action.
       middleware: [requireAdmin()],
       handler() {
         return new Response('Settings')
@@ -655,17 +737,11 @@ router.get('/posts/:id', (context) => {
 
 Route params are only half of a handler's type contract. In many apps, handlers also depend on values that middleware loads into request context, like sessions, database connections, or authenticated users.
 
-`fetch-router` lets you carry that context contract through the router and into stored controllers and actions. A common pattern is to derive one app-local context type from your router middleware, augment `RouterTypes.context` with it, then use `createAction()` and `createController()` to type stored handlers.
+`fetch-router` lets you carry that context contract through the router and into direct route registration, stored controllers, and stored actions. A common pattern is to derive one application context type from your middleware, augment `RouterTypes.context` with it, then use `createAction()` and `createController()` to type stored handlers.
 
 ```ts
 import { Auth, requireAuth } from 'remix/middleware/auth'
-import {
-  createAction,
-  createController,
-  type AnyParams,
-  type ContextWithParams,
-  type MiddlewareContext,
-} from 'remix/router'
+import { createAction, createController, createRouter, type RouterContext } from 'remix/router'
 import { route } from 'remix/routes'
 import { loadDatabase } from './middleware/database.ts'
 import { loadSession } from './middleware/session.ts'
@@ -675,12 +751,12 @@ let routes = route({
 })
 
 type AuthIdentity = { id: string }
-type RootMiddleware = [ReturnType<typeof loadSession>, ReturnType<typeof loadDatabase>]
 
-type AppContext<params extends AnyParams = {}> = ContextWithParams<
-  MiddlewareContext<RootMiddleware>,
-  params
->
+export const router = createRouter({
+  middleware: [loadSession(), loadDatabase()],
+})
+
+type AppContext = RouterContext<typeof router>
 
 declare module 'remix/router' {
   interface RouterTypes {
@@ -688,19 +764,16 @@ declare module 'remix/router' {
   }
 }
 
-let accountMiddleware = [requireAuth<AuthIdentity>()] as const
-type AccountContext = MiddlewareContext<typeof accountMiddleware, AppContext>
-
-let accountAction = createAction<typeof routes.account, AccountContext>(routes.account, {
-  middleware: accountMiddleware,
+let accountAction = createAction(routes.account, {
+  middleware: [requireAuth<AuthIdentity>()],
   handler(context) {
     let auth = context.get(Auth)
     return Response.json({ id: auth.identity.id })
   },
 })
 
-let accountController = createController<typeof routes, AccountContext>(routes, {
-  middleware: accountMiddleware,
+let accountController = createController(routes, {
+  middleware: [requireAuth<AuthIdentity>()],
   actions: {
     account(context) {
       let auth = context.get(Auth)
@@ -710,11 +783,13 @@ let accountController = createController<typeof routes, AccountContext>(routes,
 })
 ```
 
-In this example, `RootMiddleware` is the middleware tuple that defines the app context contract. It should include middleware instances. When a middleware is created by a factory function like `loadSession()`, use `ReturnType<typeof loadSession>` so the type describes the middleware value that actually runs. `AccountContext` applies local account middleware on top of that base context before the handler runs.
+In this example, the router's inline middleware array defines the app context contract. `RouterContext<typeof router>` extracts the request context that the router provides, so `RouterTypes.context` can use that context without storing the middleware chain separately.
+
+Prefer plain inline arrays for `middleware` options on routers, controllers, actions, and route helpers. Inline arrays already give TypeScript enough information to infer middleware-provided context for downstream handlers, so `createAction()` and direct action objects see action middleware context, and `createController()` sees controller middleware context without `createMiddleware()`.
 
-For small apps with a stable tuple-typed runtime array, `MiddlewareContext<typeof middleware>` is a fine shortcut. For larger apps, prefer the named `RootMiddleware` and `AppContext` pattern so runtime middleware assembly and context typing can evolve independently.
+Use `createMiddleware()` only when a middleware chain is stored somewhere and its exact tuple type needs to survive that boundary. The common cases are deriving `MiddlewareContext<typeof rootMiddleware>` without a router value, exporting a reusable chain, or returning a chain from a factory. A standalone array like `let middleware = [loadSession(), loadDatabase()]` widens to a normal array, so `MiddlewareContext<typeof middleware>` cannot derive the ordered middleware context.
 
-When manually annotating stored handlers, use `Action<typeof route, Context>` for values that may be either a plain handler function or an action object with optional middleware.
+When manually annotating stored handlers with `Action<typeof route, Context>` or `Controller<typeof routes, Context>`, compose any action or controller middleware chain into `Context` with `MiddlewareContext<typeof actionOrControllerMiddleware, AppContext>`.
 
 #### Middleware Provider Guidance
 
@@ -729,7 +804,12 @@ If you're authoring a middleware package that stores values in request context,
 Apps can derive request context from the middleware tuple with `MiddlewareContext`. If they need to describe a context shape without a middleware tuple, they can use the core `ContextWithEntry` and `ContextWithEntries` helpers directly.
 
 ```ts
-import { createContextKey, type Middleware, type MiddlewareContext } from 'remix/router'
+import {
+  createContextKey,
+  createMiddleware,
+  type Middleware,
+  type MiddlewareContext,
+} from 'remix/router'
 
 // The context key that consumers will need to read from `context.get(...)`
 export const CurrentUser = createContextKey<User | null>()
@@ -747,7 +827,7 @@ export function loadCurrentUser(): Middleware<{
   }
 }
 
-let middleware = [loadCurrentUser()] as const
+let middleware = createMiddleware(loadCurrentUser())
 type AppContext = MiddlewareContext<typeof middleware>
 
 // Use context.currentUser (or context.get(CurrentUser)).

package/src/test/README.md

@@ -9,6 +9,7 @@ A test framework for JavaScript and TypeScript projects.
 - Playwright E2E testing via `t.serve`
 - In-browser component testing (pair with `render` from `remix/ui/test`)
 - Mock functions and method spies via `t.mock.fn` / `t.mock.method`
+- Per-test and hook timeouts with `t.signal` abort support
 - Unified code coverage reporting across unit and E2E tests
 - Watch mode
 - Config file support (`remix-test.config.ts`)
@@ -193,6 +194,11 @@ describe('My Test Suite', () => {
   afterEach(() => {})
 
   it('tests something', () => {})
+  it('skips with a reason', { skip: 'requires API credentials' }, () => {})
+  it('tracks planned work', { todo: 'add retry coverage' }, () => {})
+  it('fails if it takes too long', { timeout: 5_000 }, async (t) => {
+    await fetchSomething({ signal: t.signal })
+  })
   it('tests something else', () => {})
 })
 ```
@@ -229,6 +235,9 @@ Each test callback receives a `TestContext` (`t`) as its first argument with hel
 ```ts
 // from 'remix/test'
 interface TestContext {
+  // Aborts when the test times out or when the user-provided test signal aborts
+  signal: AbortSignal
+
   // Register a cleanup function to run after the test completes
   after(fn: () => void): void
 
@@ -284,6 +293,24 @@ it('cleanup', (t) => {
 })
 ```
 
+#### Timeouts and Signals
+
+Pass `{ timeout: ms }` to `it()` or after any lifecycle hook callback to fail that work if it takes too long. Timed-out tests abort `t.signal`, so async code that accepts an `AbortSignal` can cancel promptly.
+
+```ts
+it('loads data', { timeout: 5_000 }, async (t) => {
+  let response = await fetch('/api/data', { signal: t.signal })
+  assert.equal(response.status, 200)
+})
+
+beforeEach(
+  async () => {
+    await resetDatabase()
+  },
+  { timeout: 1_000 },
+)
+```
+
 #### Fake Timers
 
 `t.useFakeTimers()` replaces the global timer functions (`setTimeout`, `setInterval`, etc.) with controllable fakes that are automatically restored after the test. It works in any test environment — server unit tests, browser tests, or E2E setup code.