@avelonjs/next 0.1.0 → 0.3.0

package/README.md

@@ -86,15 +86,17 @@ Writes become server actions in `framework/routing/actions.generated.ts`. `.api(
 | `getAdapter`                | `() => NextAdapter`                                                          | Returns the bound adapter or throws.                                                 |
 | `setRuntimeBoot`            | `(boot \| undefined) => void`                                                | Registers a boot function `page` and `dispatch` call when unbound.                   |
 | `ensureAdapter`             | `() => Promise<NextAdapter>`                                                 | Returns the bound adapter, booting first when needed.                                |
-| `page`                      | `(controller, action, uri) => PageComponent`                                 | Next page wrapper used by generated `page.tsx`.                                      |
+| `page`                      | `(controller, action, uri) => NextPage`                                      | Next page wrapper used by generated `page.tsx`.                                      |
+| `NextPage`                  | `(props: PageProps) => Promise<ReactNode>`                                   | Return type Next's AppPageConfig accepts.                                            |
 | `dispatch`                  | `(controller, action, uri, formData) => Promise<NextNativeResponse>`         | Server-action entry used by generated writes.                                        |
 | `handleRoute`               | `(controller, action, uri, request, params?) => Promise<NextNativeResponse>` | JSON route-handler entry used by `.api()` files.                                     |
+| `reportFailure`             | `(scope, uri, error) => void`                                                | Writes a request failure and its cause chain to stderr.                              |
 | `middleware`                | `(request, routes?) => Promise<NextNativeResponse>`                          | `proxy.ts` / `middleware.ts` bridge. Pass generated routes on the Node proxy.        |
 | `MiddlewareRoute`           | `interface`                                                                  | Method, path, and middleware aliases for Edge auth.                                  |
 | `setCookie`                 | `(name, value, options?) => void`                                            | Queues a cookie write for the current Next request.                                  |
 | `clearCookie`               | `(name, options?) => void`                                                   | Queues a cookie deletion for the current Next request.                               |
 | `PendingCookie`             | `interface`                                                                  | Queued cookie name, value, and options.                                              |
-| `ViewRegistry`              | `type`                                                                       | String view tokens mapped to render functions.                                       |
+| `ViewRegistry`              | `type`                                                                       | String view tokens mapped to functions returning `ReactNode`.                        |
 | `formProps`                 | `(name, params?) => { action, method, fields }`                              | Hidden fields and action export for a named write route.                             |
 | `generateRouter`            | `(manifest, root, options) => Promise<readonly string[]>`                    | Destructive codegen used by `mount`.                                                 |
 | `findMountedRoute`          | `(controller, action, uri) => RouteDefinition`                               | Resolves a generated helper back to its manifest entry.                              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avelonjs/next",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Next.js adapter for Avelon routing, server actions, and pages.",
   "license": "MIT",
@@ -40,18 +40,24 @@
     "@avelonjs/core": "workspace:*"
   },
   "peerDependencies": {
-    "next": ">=16.0.0"
+    "next": ">=16.0.0",
+    "react": ">=19.0.0"
   },
   "peerDependenciesMeta": {
     "next": {
       "optional": true
+    },
+    "react": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@avelonjs/assay": "workspace:*",
     "@avelonjs/conformance": "workspace:*",
     "@types/bun": "1.3.14",
+    "@types/react": "19.2.2",
     "next": "16.2.12",
+    "react": "19.2.0",
     "typescript": "5.9.3"
   },
   "engines": {

package/src/cookies.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import type { CookieOptions } from '@avelonjs/core'
+import type { ReactNode } from 'react'
 
 /** One cookie write queued during kernel dispatch. */
 export interface PendingCookie {
@@ -20,7 +21,7 @@ const storage = new AsyncLocalStorage<CookieStore>()
 const fallbackOutgoing: PendingCookie[] = []
 
 /** View and form components the Next adapter can render from a string view token. */
-export type ViewRegistry = Readonly<Record<string, (props: object) => unknown>>
+export type ViewRegistry = Readonly<Record<string, (props: object) => ReactNode>>
 
 function currentStore(): CookieStore | undefined {
   return storage.getStore()

package/src/dispatch.ts

@@ -1,9 +1,35 @@
-import { finishResponse, type ControllerClass } from '@avelonjs/core'
+import { finishResponse, mapKernelException, type ControllerClass } from '@avelonjs/core'
 
 import { ensureAdapter, findMountedRoute } from './adapter'
 import { readIncomingCookies, withCookies } from './cookies'
+import { reportFailure } from './failures'
 import { isNextControlFlow, type NextNativeResponse } from './response'
 
+/**
+ * Reports a failure the kernel never saw, and answers with it when the taxonomy can.
+ *
+ * `ensureAdapter` boots the application on the first request, so a driver that refuses its
+ * environment throws here rather than inside `kernel.dispatch`, where `mapKernelException` would
+ * have turned it into a result. Unhandled, it reaches the host as a 500 with an empty log line and
+ * a blank screen — the state a first deploy with one missing variable lands in.
+ */
+function failedAction(
+  scope: string,
+  uri: string,
+  error: unknown,
+): NextNativeResponse & { kind: 'action' } {
+  reportFailure(scope, uri, error)
+  const mapped = mapKernelException(error)
+  if (mapped?.type !== 'action') throw error
+  return {
+    kind: 'action',
+    ok: mapped.ok,
+    data: mapped.data,
+    errors: mapped.errors,
+    status: mapped.status ?? 422,
+  }
+}
+
 /**
  * Runs a write action behind a generated server action. Validation failures return action state
  * for `useActionState`; redirects keep propagating.
@@ -14,25 +40,25 @@ export async function dispatch(
   uri: string,
   formData: FormData,
 ): Promise<NextNativeResponse> {
-  const adapter = await ensureAdapter()
-  const kernel = adapter.kernel
-  if (kernel === undefined) {
-    throw new Error('Next adapter kernel is missing. Mount the adapter before dispatch().')
-  }
-  const cookies = await readIncomingCookies()
-  return await withCookies(cookies, async () => {
-    const request = await adapter.toRequest({ kind: 'form', uri, formData, cookies })
-    const route = findMountedRoute(controller, action, uri)
-    try {
+  try {
+    const adapter = await ensureAdapter()
+    const kernel = adapter.kernel
+    if (kernel === undefined) {
+      throw new Error('Next adapter kernel is missing. Mount the adapter before dispatch().')
+    }
+    const cookies = await readIncomingCookies()
+    return await withCookies(cookies, async () => {
+      const request = await adapter.toRequest({ kind: 'form', uri, formData, cookies })
+      const route = findMountedRoute(controller, action, uri)
       const result = await kernel.dispatch(route, request)
       const response = await adapter.toResponse(result)
       await finishResponse()
       return response
-    } catch (error) {
-      if (isNextControlFlow(error)) throw error
-      throw error
-    }
-  })
+    })
+  } catch (error) {
+    if (isNextControlFlow(error)) throw error
+    return failedAction('action', uri, error)
+  }
 }
 
 /** JSON route-handler entry used by generated `app/(api)` files. */
@@ -43,11 +69,6 @@ export async function handleRoute(
   request: Request,
   params: Readonly<Record<string, string>> = {},
 ): Promise<NextNativeResponse> {
-  const adapter = await ensureAdapter()
-  const kernel = adapter.kernel
-  if (kernel === undefined) {
-    throw new Error('Next adapter kernel is missing. Mount the adapter before handleRoute().')
-  }
   const cookies: Record<string, string> = {}
   const header = request.headers.get('cookie')
   if (header !== null && header.length > 0) {
@@ -58,17 +79,22 @@ export async function handleRoute(
       cookies[trimmed.slice(0, eq)] = decodeURIComponent(trimmed.slice(eq + 1))
     }
   }
-  return await withCookies(cookies, async () => {
-    const http = await adapter.toRequest({ kind: 'http', request, params })
-    const route = findMountedRoute(controller, action, uri)
-    try {
+  try {
+    const adapter = await ensureAdapter()
+    const kernel = adapter.kernel
+    if (kernel === undefined) {
+      throw new Error('Next adapter kernel is missing. Mount the adapter before handleRoute().')
+    }
+    return await withCookies(cookies, async () => {
+      const http = await adapter.toRequest({ kind: 'http', request, params })
+      const route = findMountedRoute(controller, action, uri)
       const result = await kernel.dispatch(route, http)
       const response = await adapter.toResponse(result)
       await finishResponse()
       return response
-    } catch (error) {
-      if (isNextControlFlow(error)) throw error
-      throw error
-    }
-  })
+    })
+  } catch (error) {
+    if (isNextControlFlow(error)) throw error
+    return failedAction('route', uri, error)
+  }
 }

package/src/failures.ts

@@ -0,0 +1,36 @@
+import { AvelonError } from '@avelonjs/core'
+
+/**
+ * Writes a request failure to stderr.
+ *
+ * A framework error thrown before the kernel exists — a driver refusing the environment it was
+ * given, a missing key — leaves `dispatch` and `page` with nothing to map, so it reaches the host
+ * as a bare 500. A serverless host records that status and no reason: the exception never crossed
+ * a boundary that logs. This is that boundary.
+ */
+export function reportFailure(scope: string, uri: string, error: unknown): void {
+  const lines = [`[avelon] ${scope} ${uri} failed: ${describe(error)}`]
+  for (const cause of causes(error)) lines.push(`[avelon]   caused by: ${describe(cause)}`)
+  const stack = error instanceof Error ? error.stack : undefined
+  if (stack !== undefined) lines.push(stack)
+  console.error(lines.join('\n'))
+}
+
+function describe(error: unknown): string {
+  if (error instanceof AvelonError) {
+    return `${error.name}(${error.code}) ${error.message} ${JSON.stringify(error.metadata)}`
+  }
+  if (error instanceof Error) return `${error.name}: ${error.message}`
+  return String(error)
+}
+
+function* causes(error: unknown): Generator<unknown> {
+  let current: unknown = error
+  // A driver keeps the vendor payload as `.cause`; a config failure keeps the value it rejected.
+  for (let depth = 0; depth < 4; depth += 1) {
+    const cause = (current as { cause?: unknown } | null)?.cause
+    if (cause === undefined || cause === null) return
+    yield cause
+    current = cause
+  }
+}

package/src/index.ts

@@ -11,10 +11,11 @@ export {
   type NextNativeRequest,
 } from './adapter'
 export { clearCookie, setCookie, type PendingCookie, type ViewRegistry } from './cookies'
+export { reportFailure } from './failures'
 export { generateRouter } from './codegen'
 export { dispatch, handleRoute } from './dispatch'
 export { middleware, type MiddlewareRoute } from './middleware'
-export { page, type PageProps } from './page'
+export { page, type NextPage, type PageProps } from './page'
 export {
   isNextControlFlow,
   kernelToResponse,

package/src/page.ts

@@ -1,7 +1,9 @@
-import { finishResponse, type ControllerClass } from '@avelonjs/core'
+import { finishResponse, Invalid, type ControllerClass } from '@avelonjs/core'
+import type { ReactNode } from 'react'
 
 import { ensureAdapter, findMountedRoute } from './adapter'
 import { readIncomingCookies, withCookies } from './cookies'
+import { reportFailure } from './failures'
 import { isNextControlFlow } from './response'
 
 /** Next page props after awaiting the async params/searchParams contracts. */
@@ -14,6 +16,9 @@ export interface PageProps {
     | Record<string, string | string[] | undefined>
 }
 
+/** Generated `page.tsx` default export. Next's AppPageConfig requires `Promise<ReactNode>`. */
+export type NextPage = (props: PageProps) => Promise<ReactNode>
+
 async function resolveRecord(
   value:
     | Promise<Record<string, string | string[] | undefined>>
@@ -28,9 +33,18 @@ async function resolveRecord(
  * Wraps a controller action as a Next page component. Generated `page.tsx` files are four lines
  * that call this helper.
  */
-export function page(controller: ControllerClass, action: string, uri: string) {
-  return async function Page(props: PageProps): Promise<unknown> {
-    const adapter = await ensureAdapter()
+export function page(controller: ControllerClass, action: string, uri: string): NextPage {
+  return async function Page(props: PageProps): Promise<ReactNode> {
+    // `ensureAdapter` boots the application here on the first request, so a driver refusing its
+    // environment throws before there is a kernel to map it. Reporting it is the only record a
+    // serverless host keeps of why the page 500'd.
+    let adapter
+    try {
+      adapter = await ensureAdapter()
+    } catch (error) {
+      reportFailure('page', uri, error)
+      throw error
+    }
     const kernel = adapter.kernel
     if (kernel === undefined) {
       throw new Error('Next adapter kernel is missing. Mount the adapter before rendering a page.')
@@ -67,9 +81,12 @@ export function page(controller: ControllerClass, action: string, uri: string) {
           }
           throw new Error(message)
         }
-        return response
+        throw new Invalid('The page action did not return a view.', {
+          metadata: { fields: { view: ['Expected a view result.'] } },
+        })
       } catch (error) {
         if (isNextControlFlow(error)) throw error
+        reportFailure('page', uri, error)
         throw error
       }
     })

package/src/response.ts

@@ -1,10 +1,11 @@
-import type { KernelResult, ViewRef } from '@avelonjs/core'
+import { Invalid, type KernelResult, type ViewRef } from '@avelonjs/core'
+import type { ReactNode } from 'react'
 
 import type { ViewRegistry } from './cookies'
 
 /** Native response shapes the Next adapter returns from `toResponse`. */
 export type NextNativeResponse =
-  | { kind: 'view'; body: unknown; status: number }
+  | { kind: 'view'; body: ReactNode; status: number }
   | {
       kind: 'action'
       ok: boolean
@@ -43,13 +44,20 @@ export function isNextControlFlow(error: unknown): boolean {
   return typeof digest === 'string' && /^NEXT_(REDIRECT|HTTP_ERROR_FALLBACK|NOT_FOUND)/.test(digest)
 }
 
-function renderView(view: unknown, props: object, views?: ViewRegistry): unknown {
-  if (typeof view === 'function') return (view as (value: object) => unknown)(props)
+function isViewRenderer(view: unknown): view is (props: object) => ReactNode {
+  return typeof view === 'function'
+}
+
+function renderView(view: unknown, props: object, views?: ViewRegistry): ReactNode {
+  if (isViewRenderer(view)) return view(props)
   if (typeof view === 'string' && views !== undefined) {
     const component = views[view]
     if (component !== undefined) return component(props)
   }
-  return { view, props }
+  const token = typeof view === 'string' ? view : 'anonymous'
+  throw new Invalid(`No view is registered for ${token}.`, {
+    metadata: { fields: { view: [`${token} is not in the view registry.`] } },
+  })
 }
 
 /**