@avelonjs/next 0.1.0

package/src/cookies.ts

@@ -0,0 +1,137 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { CookieOptions } from '@avelonjs/core'
+
+/** One cookie write queued during kernel dispatch. */
+export interface PendingCookie {
+  /** Cookie name. */
+  name: string
+  /** Cookie value. `null` deletes the cookie. */
+  value: string | null
+  /** Transport-neutral cookie options. */
+  options?: CookieOptions
+}
+
+interface CookieStore {
+  incoming: Record<string, string>
+  outgoing: PendingCookie[]
+}
+
+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>>
+
+function currentStore(): CookieStore | undefined {
+  return storage.getStore()
+}
+
+/** Runs `fn` with a request-scoped cookie jar. */
+export async function withCookies<T>(
+  incoming: Record<string, string>,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return await storage.run({ incoming, outgoing: [] }, fn)
+}
+
+/** Queues a cookie write for the current Next request. No-op outside a request when unused. */
+export function setCookie(name: string, value: string, options?: CookieOptions): void {
+  const entry: PendingCookie = { name, value, options }
+  const store = currentStore()
+  if (store !== undefined) {
+    store.outgoing.push(entry)
+    return
+  }
+  fallbackOutgoing.push(entry)
+}
+
+/** Queues a cookie deletion for the current Next request. */
+export function clearCookie(name: string, options?: Pick<CookieOptions, 'domain' | 'path'>): void {
+  const entry: PendingCookie = { name, value: null, options }
+  const store = currentStore()
+  if (store !== undefined) {
+    store.outgoing.push(entry)
+    return
+  }
+  fallbackOutgoing.push(entry)
+}
+
+/** Returns and clears queued cookie writes. */
+export function takePendingCookies(): readonly PendingCookie[] {
+  const store = currentStore()
+  if (store !== undefined) {
+    const queued = store.outgoing.splice(0)
+    return queued
+  }
+  const queued = fallbackOutgoing.splice(0)
+  return queued
+}
+
+/** Incoming cookies for the current request, or an empty map. */
+export function incomingCookies(): Record<string, string> {
+  return currentStore()?.incoming ?? {}
+}
+
+function cookieHeader(cookies: Record<string, string>): string {
+  return Object.entries(cookies)
+    .map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
+    .join('; ')
+}
+
+/**
+ * Reads cookies from `next/headers` when the Next runtime is present.
+ * Returns an empty map in tests and other non-Next processes.
+ */
+export async function readIncomingCookies(): Promise<Record<string, string>> {
+  try {
+    const headers = (await import('next/headers')) as {
+      cookies: () => Promise<{ getAll: () => readonly { name: string; value: string }[] }>
+    }
+    const jar = await headers.cookies()
+    const result: Record<string, string> = {}
+    for (const cookie of jar.getAll()) result[cookie.name] = cookie.value
+    return result
+  } catch {
+    return {}
+  }
+}
+
+function toNextCookieOptions(options?: CookieOptions): Record<string, unknown> {
+  if (options === undefined) return { path: '/', httpOnly: true, sameSite: 'lax' }
+  return {
+    domain: options.domain,
+    expires: options.expires,
+    httpOnly: options.httpOnly ?? true,
+    maxAge: options.maxAge,
+    partitioned: options.partitioned,
+    path: options.path ?? '/',
+    sameSite: options.sameSite ?? 'lax',
+    secure: options.secure,
+  }
+}
+
+/** Writes queued cookies through `next/headers` when available. */
+export async function flushOutgoingCookies(): Promise<void> {
+  const pending = takePendingCookies()
+  if (pending.length === 0) return
+  try {
+    const headers = (await import('next/headers')) as {
+      cookies: () => Promise<{
+        set: (name: string, value: string, options?: Record<string, unknown>) => void
+        delete: (name: string) => void
+      }>
+    }
+    const jar = await headers.cookies()
+    for (const cookie of pending) {
+      if (cookie.value === null) jar.delete(cookie.name)
+      else jar.set(cookie.name, cookie.value, toNextCookieOptions(cookie.options))
+    }
+  } catch {
+    // Tests and non-Next hosts keep the queue discarded after takePendingCookies.
+  }
+}
+
+/** Serializes incoming cookies for a Fetch `Request` header. */
+export function serializeCookieHeader(cookies: Record<string, string>): string {
+  return cookieHeader(cookies)
+}

package/src/dispatch.ts

@@ -0,0 +1,74 @@
+import { finishResponse, type ControllerClass } from '@avelonjs/core'
+
+import { ensureAdapter, findMountedRoute } from './adapter'
+import { readIncomingCookies, withCookies } from './cookies'
+import { isNextControlFlow, type NextNativeResponse } from './response'
+
+/**
+ * Runs a write action behind a generated server action. Validation failures return action state
+ * for `useActionState`; redirects keep propagating.
+ */
+export async function dispatch(
+  controller: ControllerClass,
+  action: string,
+  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 {
+      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
+    }
+  })
+}
+
+/** JSON route-handler entry used by generated `app/(api)` files. */
+export async function handleRoute(
+  controller: ControllerClass,
+  action: string,
+  uri: string,
+  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) {
+    for (const part of header.split(';')) {
+      const trimmed = part.trim()
+      const eq = trimmed.indexOf('=')
+      if (eq <= 0) continue
+      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 {
+      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
+    }
+  })
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export {
+  NextAdapter,
+  bindAdapter,
+  ensureAdapter,
+  findMountedRoute,
+  formProps,
+  getAdapter,
+  setRuntimeBoot,
+  nextCapabilities,
+  type NextAdapterOptions,
+  type NextNativeRequest,
+} from './adapter'
+export { clearCookie, setCookie, type PendingCookie, type ViewRegistry } from './cookies'
+export { generateRouter } from './codegen'
+export { dispatch, handleRoute } from './dispatch'
+export { middleware, type MiddlewareRoute } from './middleware'
+export { page, type PageProps } from './page'
+export {
+  isNextControlFlow,
+  kernelToResponse,
+  NextRedirect,
+  type NextNativeResponse,
+} from './response'
+export { nativeToRequest } from './request'
+export { exportName, ResourceBuilder, Route, RouteBuilder, route, uriToSegments } from './routing'

package/src/middleware.ts

@@ -0,0 +1,75 @@
+import type { HttpMethod } from '@avelonjs/core'
+
+import { getAdapter } from './adapter'
+import type { NextNativeResponse } from './response'
+
+function pathnameOf(url: string): string {
+  return new URL(url).pathname
+}
+
+function scorePath(pattern: string, pathname: string): number | undefined {
+  const patternParts = pattern.split('/').filter(Boolean)
+  const pathParts = pathname.split('/').filter(Boolean)
+  if (patternParts.length !== pathParts.length) return undefined
+  let score = 0
+  for (let i = 0; i < patternParts.length; i += 1) {
+    const expected = patternParts[i]
+    const actual = pathParts[i]
+    if (expected === undefined || actual === undefined) return undefined
+    if (expected.startsWith('{') && expected.endsWith('}')) continue
+    if (expected !== actual) return undefined
+    score += 1
+  }
+  return score
+}
+
+/** Route slice middleware needs to decide an auth redirect. */
+export interface MiddlewareRoute {
+  /** Transport-neutral HTTP method. */
+  readonly method: string
+  /** Route path with named parameters. */
+  readonly path: string
+  /** Middleware aliases declared on the route. */
+  readonly middleware: readonly string[]
+}
+
+/**
+ * Next `middleware.ts` entry. Delegates auth cookies to the kernel's later dispatch; at the edge
+ * it only redirects unauthenticated requests onto routes that declare the `auth` alias.
+ *
+ * Pass `routes` from `manifest.generated.ts` so Edge middleware does not need a bound adapter.
+ */
+export async function middleware(
+  request: Request,
+  routes?: readonly MiddlewareRoute[],
+): Promise<NextNativeResponse> {
+  const resolved =
+    routes ??
+    ((() => {
+      try {
+        return getAdapter().manifest?.routes ?? []
+      } catch {
+        return []
+      }
+    })() as readonly MiddlewareRoute[])
+  const method = request.method.toUpperCase() as HttpMethod
+  const pathname = pathnameOf(request.url)
+  let best: { path: string; middleware: readonly string[]; score: number } | undefined
+  for (const route of resolved) {
+    if (route.method !== method && !(method === 'GET' && route.method === 'GET')) continue
+    const score = scorePath(route.path, pathname)
+    if (score === undefined) continue
+    if (best === undefined || score > best.score) {
+      best = { path: route.path, middleware: route.middleware, score }
+    }
+  }
+  if (best === undefined) return { kind: 'next' }
+  const cookieHeader = request.headers.get('cookie')
+  const signedIn =
+    (cookieHeader !== null && cookieHeader.length > 0) ||
+    (request.headers.get('authorization') ?? '').length > 0
+  if (best.middleware.includes('auth') && !signedIn) {
+    return { kind: 'redirect', location: '/login', status: 302 }
+  }
+  return { kind: 'next' }
+}

package/src/page.ts

@@ -0,0 +1,77 @@
+import { finishResponse, type ControllerClass } from '@avelonjs/core'
+
+import { ensureAdapter, findMountedRoute } from './adapter'
+import { readIncomingCookies, withCookies } from './cookies'
+import { isNextControlFlow } from './response'
+
+/** Next page props after awaiting the async params/searchParams contracts. */
+export interface PageProps {
+  params?:
+    | Promise<Record<string, string | string[] | undefined>>
+    | Record<string, string | string[] | undefined>
+  searchParams?:
+    | Promise<Record<string, string | string[] | undefined>>
+    | Record<string, string | string[] | undefined>
+}
+
+async function resolveRecord(
+  value:
+    | Promise<Record<string, string | string[] | undefined>>
+    | Record<string, string | string[] | undefined>
+    | undefined,
+): Promise<Record<string, string | string[] | undefined>> {
+  if (value === undefined) return {}
+  return await value
+}
+
+/**
+ * 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()
+    const kernel = adapter.kernel
+    if (kernel === undefined) {
+      throw new Error('Next adapter kernel is missing. Mount the adapter before rendering a page.')
+    }
+    const cookies = await readIncomingCookies()
+    return await withCookies(cookies, async () => {
+      const request = await adapter.toRequest({
+        kind: 'page',
+        uri,
+        params: await resolveRecord(props.params),
+        searchParams: await resolveRecord(props.searchParams),
+        cookies,
+      })
+      const route = findMountedRoute(controller, action, uri)
+      try {
+        const result = await kernel.dispatch(route, request)
+        const response = await adapter.toResponse(result)
+        await finishResponse()
+        if (response.kind === 'view') return response.body
+        if (response.kind === 'action' && response.ok === false) {
+          const message =
+            response.errors?._form?.[0] ??
+            Object.values(response.errors ?? {})[0]?.[0] ??
+            'The page could not be rendered.'
+          if (response.status === 404) {
+            try {
+              const navigation = (await import('next/navigation')) as {
+                notFound: () => never
+              }
+              navigation.notFound()
+            } catch (fallback) {
+              if (isNextControlFlow(fallback)) throw fallback
+            }
+          }
+          throw new Error(message)
+        }
+        return response
+      } catch (error) {
+        if (isNextControlFlow(error)) throw error
+        throw error
+      }
+    })
+  }
+}

package/src/request.ts

@@ -0,0 +1,139 @@
+import type { HttpMethod, HttpRequest } from '@avelonjs/core'
+
+import type { NextNativeRequest } from './adapter'
+
+function flatten(
+  source: Record<string, string | string[] | undefined> | undefined,
+): Record<string, string> {
+  const result: Record<string, string> = {}
+  if (source === undefined) return result
+  for (const [key, value] of Object.entries(source)) {
+    if (typeof value === 'string') result[key] = value
+    else if (Array.isArray(value) && value[0] !== undefined) result[key] = value[0]
+  }
+  return result
+}
+
+function cookiesFromHeader(header: string | null): Record<string, string> {
+  const cookies: Record<string, string> = {}
+  if (header === null || header.length === 0) return cookies
+  for (const part of header.split(';')) {
+    const trimmed = part.trim()
+    const eq = trimmed.indexOf('=')
+    if (eq <= 0) continue
+    const name = trimmed.slice(0, eq)
+    const value = trimmed.slice(eq + 1)
+    cookies[name] = decodeURIComponent(value)
+  }
+  return cookies
+}
+
+function headersFrom(request: Request): Record<string, string> {
+  const headers: Record<string, string> = {}
+  request.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+  return headers
+}
+
+function queryFrom(url: URL): Record<string, string | readonly string[]> {
+  const query: Record<string, string | string[]> = {}
+  for (const [key, value] of url.searchParams.entries()) {
+    const existing = query[key]
+    if (existing === undefined) query[key] = value
+    else if (typeof existing === 'string') query[key] = [existing, value]
+    else existing.push(value)
+  }
+  return query
+}
+
+function parameterNames(uri: string): string[] {
+  return [...uri.matchAll(/\{(\w+)\}/g)]
+    .map((match) => match[1])
+    .filter((name) => name !== undefined)
+}
+
+/** Converts a Next page, FormData, or Fetch request into a kernel `HttpRequest`. */
+export async function nativeToRequest(native: NextNativeRequest): Promise<HttpRequest> {
+  if (native.kind === 'page') {
+    const params = flatten(native.params)
+    const query = flatten(native.searchParams)
+    const url =
+      native.url ??
+      `http://localhost${native.uri.replace(/\{(\w+)\}/g, (_, name: string) => params[name] ?? '')}`
+    return {
+      method: 'GET',
+      url,
+      params,
+      query,
+      headers: {},
+      cookies: native.cookies ?? {},
+      body: null,
+      rawBody: async () => new Uint8Array(),
+      aborted: false,
+    }
+  }
+
+  if (native.kind === 'form') {
+    const body: Record<string, string> = {}
+    for (const [key, value] of native.formData.entries()) {
+      if (typeof value === 'string') body[key] = value
+    }
+    const params: Record<string, string> = {}
+    for (const name of parameterNames(native.uri)) {
+      const value = body[name]
+      if (value !== undefined) {
+        params[name] = value
+        delete body[name]
+      }
+    }
+    const spoofed = body._method
+    const method = (spoofed ?? 'POST').toUpperCase() as HttpMethod satisfies HttpMethod
+    delete body._method
+    const raw = new TextEncoder().encode(JSON.stringify(body))
+    return {
+      method,
+      url: native.url ?? `http://localhost${native.uri}`,
+      params,
+      query: {},
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      cookies: native.cookies ?? {},
+      body,
+      rawBody: async () => raw,
+      aborted: false,
+    }
+  }
+
+  const url = new URL(native.request.url)
+  let body: unknown = null
+  const bytes = new Uint8Array(await native.request.clone().arrayBuffer())
+  const contentType = native.request.headers.get('content-type') ?? ''
+  if (bytes.byteLength > 0) {
+    try {
+      if (contentType.includes('application/json'))
+        body = JSON.parse(new TextDecoder().decode(bytes))
+      else if (contentType.includes('form')) {
+        const form = await native.request.clone().formData()
+        const parsed: Record<string, string> = {}
+        for (const [key, value] of form.entries()) {
+          if (typeof value === 'string') parsed[key] = value
+        }
+        body = parsed
+      } else body = new TextDecoder().decode(bytes)
+    } catch {
+      body = null
+    }
+  }
+  const method = native.request.method.toUpperCase() as HttpMethod
+  return {
+    method,
+    url: native.request.url,
+    params: native.params ?? {},
+    query: queryFrom(url),
+    headers: headersFrom(native.request),
+    cookies: cookiesFromHeader(native.request.headers.get('cookie')),
+    body,
+    rawBody: async () => bytes,
+    aborted: native.request.signal.aborted,
+  }
+}

package/src/response.ts

@@ -0,0 +1,88 @@
+import type { KernelResult, ViewRef } from '@avelonjs/core'
+
+import type { ViewRegistry } from './cookies'
+
+/** Native response shapes the Next adapter returns from `toResponse`. */
+export type NextNativeResponse =
+  | { kind: 'view'; body: unknown; status: number }
+  | {
+      kind: 'action'
+      ok: boolean
+      data?: unknown
+      errors?: Readonly<Record<string, readonly string[]>>
+      status: number
+    }
+  | { kind: 'redirect'; location: string; status: 302 | 303 | 307 | 308 }
+  | { kind: 'stream'; body: AsyncIterable<Uint8Array>; contentType: string; status: number }
+  | { kind: 'next' }
+
+const REDIRECT_DIGEST = 'NEXT_REDIRECT'
+
+/** Error Next navigation uses to unwind the server component tree. */
+export class NextRedirect extends Error {
+  readonly digest: string
+  readonly location: string
+  readonly status: 302 | 303 | 307 | 308
+
+  constructor(location: string, status: 302 | 303 | 307 | 308) {
+    super(REDIRECT_DIGEST)
+    this.name = 'NextRedirect'
+    this.location = location
+    this.status = status
+    // Next 16 `isRedirectError` requires a trailing semicolon and only
+    // recognizes 303/307/308. Kernel redirects are 302; map those to 307.
+    const nextStatus = status === 302 ? 307 : status
+    this.digest = `${REDIRECT_DIGEST};replace;${location};${nextStatus};`
+  }
+}
+
+/** Returns true when `error` is a Next navigation control-flow throw. */
+export function isNextControlFlow(error: unknown): boolean {
+  if (error instanceof NextRedirect) return true
+  const digest = (error as { digest?: unknown })?.digest
+  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)
+  if (typeof view === 'string' && views !== undefined) {
+    const component = views[view]
+    if (component !== undefined) return component(props)
+  }
+  return { view, props }
+}
+
+/**
+ * Converts a kernel result. Redirects throw {@link NextRedirect} so generated server actions
+ * propagate navigation the way Next's `redirect()` does.
+ */
+export async function kernelToResponse(
+  result: KernelResult<ViewRef>,
+  views?: ViewRegistry,
+): Promise<NextNativeResponse> {
+  if (result.type === 'redirect') {
+    throw new NextRedirect(result.location, result.status)
+  }
+  if (result.type === 'action') {
+    return {
+      kind: 'action',
+      ok: result.ok,
+      data: result.data,
+      errors: result.errors,
+      status: result.status ?? (result.ok ? 200 : 422),
+    }
+  }
+  if (result.type === 'stream') {
+    return {
+      kind: 'stream',
+      body: result.body,
+      contentType: result.contentType,
+      status: result.status ?? 200,
+    }
+  }
+  return {
+    kind: 'view',
+    body: renderView(result.view, result.props, views),
+    status: result.status ?? 200,
+  }
+}