@vidact/start 0.2.0-beta.0 → 0.2.0-beta.11

package/src/router.ts

@@ -0,0 +1,282 @@
+import type { CompiledRenderValue } from '@vidact/runtime'
+import type { FrameworkValue } from '@vidact/runtime/framework/protocol'
+
+const FILE_ROUTE = Symbol('Vidact.Start.FileRoute')
+
+export type RouteParameters = Readonly<Record<string, string>>
+export type StartComponent<LoaderData extends FrameworkValue = FrameworkValue> = {
+  bivarianceHack(props: RouteComponentProps<LoaderData>): unknown
+}['bivarianceHack']
+
+export interface RouteComponentProps<
+  LoaderData extends FrameworkValue = FrameworkValue,
+> extends Readonly<Record<string, unknown>> {
+  readonly children?: CompiledRenderValue
+  readonly loaderData: LoaderData
+  readonly params: RouteParameters
+  readonly requestUrl: string
+}
+
+export interface RouteLoaderContext {
+  readonly parentData: Readonly<Record<string, FrameworkValue>>
+  readonly params: RouteParameters
+  readonly request: Request
+}
+
+export interface RouteServerContext {
+  readonly params: RouteParameters
+  readonly request: Request
+}
+
+export type RouteServerHandler = (context: RouteServerContext) => Response | Promise<Response>
+
+export interface FileRouteOptions<LoaderData extends FrameworkValue = FrameworkValue> {
+  readonly component?: StartComponent<LoaderData>
+  readonly loader?: (context: RouteLoaderContext) => LoaderData | Promise<LoaderData>
+  readonly server?: {
+    readonly handlers: Readonly<Partial<Record<string, RouteServerHandler>>>
+  }
+}
+
+export interface FileRouteDefinition<LoaderData extends FrameworkValue = FrameworkValue> {
+  readonly [FILE_ROUTE]: true
+  readonly options: FileRouteOptions<LoaderData>
+}
+
+export interface RouteModule {
+  readonly Route?: FileRouteDefinition
+  readonly default?: FileRouteDefinition
+}
+
+export interface RouteManifestEntry {
+  readonly id: string
+  readonly parentId: string | null
+  readonly path: string
+  readonly load: () => PromiseLike<RouteModule>
+}
+
+export interface RouteManifest {
+  readonly entries: readonly RouteManifestEntry[]
+  readonly byId: ReadonlyMap<string, RouteManifestEntry>
+}
+
+export interface RouteMatch {
+  readonly entry: RouteManifestEntry
+  readonly params: RouteParameters
+}
+
+export interface ResolvedRouteMatch extends RouteMatch {
+  readonly definition: FileRouteDefinition
+}
+
+export interface LoadedRouteMatch extends ResolvedRouteMatch {
+  readonly loaderData: FrameworkValue
+}
+
+export function defineFileRoute<const LoaderData extends FrameworkValue = undefined>(
+  options: FileRouteOptions<LoaderData>,
+): FileRouteDefinition<LoaderData> {
+  return Object.freeze({ [FILE_ROUTE]: true as const, options: Object.freeze({ ...options }) })
+}
+
+export function isFileRouteDefinition(value: unknown): value is FileRouteDefinition {
+  return typeof value === 'object' && value !== null && FILE_ROUTE in value
+}
+
+export function createRouteManifest(entries: readonly RouteManifestEntry[]): RouteManifest {
+  const byId = new Map<string, RouteManifestEntry>()
+  for (const entry of entries) {
+    if (entry.id.length === 0) throw new TypeError('route id must be non-empty')
+    if (!entry.path.startsWith('/')) throw new TypeError(`route ${entry.id} path must start with /`)
+    if (byId.has(entry.id)) throw new TypeError(`duplicate route id ${entry.id}`)
+    byId.set(entry.id, Object.freeze({ ...entry }))
+  }
+  for (const entry of byId.values()) {
+    if (entry.parentId !== null && !byId.has(entry.parentId)) {
+      throw new TypeError(`route ${entry.id} has unknown parent ${entry.parentId}`)
+    }
+    assertAcyclicParentChain(entry, byId)
+  }
+  const frozenEntries = Object.freeze([...byId.values()])
+  return Object.freeze({ entries: frozenEntries, byId })
+}
+
+export function matchRoutes(manifest: RouteManifest, pathname: string): readonly RouteMatch[] {
+  const normalized = normalizePathname(pathname)
+  let selected: { entry: RouteManifestEntry; params: RouteParameters; score: number } | undefined
+  for (const entry of manifest.entries) {
+    const match = matchPath(entry.path, normalized)
+    if (match === undefined) continue
+    const score = routeScore(entry, manifest)
+    if (selected === undefined || score > selected.score) selected = { entry, params: match, score }
+  }
+  if (selected === undefined) return []
+  const chain: RouteManifestEntry[] = []
+  let entry: RouteManifestEntry | undefined = selected.entry
+  while (entry !== undefined) {
+    chain.push(entry)
+    entry = entry.parentId === null ? undefined : manifest.byId.get(entry.parentId)
+  }
+  return Object.freeze(
+    chain.toReversed().map((matchedEntry) =>
+      Object.freeze({
+        entry: matchedEntry,
+        params: Object.freeze({ ...selected.params }),
+      }),
+    ),
+  )
+}
+
+export async function loadRouteMatches(
+  matches: readonly RouteMatch[],
+  request: Request,
+  suppliedData: Readonly<Record<string, FrameworkValue>> = {},
+): Promise<readonly LoadedRouteMatch[]> {
+  return runRouteLoaders(await resolveRouteMatches(matches), request, suppliedData)
+}
+
+export async function resolveRouteMatches(
+  matches: readonly RouteMatch[],
+): Promise<readonly ResolvedRouteMatch[]> {
+  return Object.freeze(
+    await Promise.all(
+      matches.map(async (match) => {
+        const module = await match.entry.load()
+        return Object.freeze({
+          ...match,
+          definition: readRouteDefinition(match.entry.id, module),
+        })
+      }),
+    ),
+  )
+}
+
+export async function runRouteLoaders(
+  matches: readonly ResolvedRouteMatch[],
+  request: Request,
+  suppliedData: Readonly<Record<string, FrameworkValue>> = {},
+): Promise<readonly LoadedRouteMatch[]> {
+  const loaded: LoadedRouteMatch[] = []
+  const parentData: Record<string, FrameworkValue> = { ...suppliedData }
+  for (const match of matches) {
+    const loaderData = Object.hasOwn(suppliedData, match.entry.id)
+      ? suppliedData[match.entry.id]
+      : match.definition.options.loader === undefined
+        ? undefined
+        : // oxlint-disable-next-line no-await-in-loop -- Descendants receive settled parent data.
+          await match.definition.options.loader({
+            parentData: Object.freeze({ ...parentData }),
+            params: match.params,
+            request,
+          })
+    parentData[match.entry.id] = loaderData
+    loaded.push(Object.freeze({ ...match, loaderData }))
+  }
+  return Object.freeze(loaded)
+}
+
+export function composeRouteMatches(
+  matches: readonly LoadedRouteMatch[],
+  createElement: (component: StartComponent, props: RouteComponentProps) => unknown,
+  requestUrl: string,
+): unknown {
+  let children: CompiledRenderValue | undefined
+  for (let index = matches.length - 1; index >= 0; index -= 1) {
+    const match = matches[index]!
+    const component = match.definition.options.component
+    if (component === undefined) continue
+    children = createElement(component, {
+      children,
+      loaderData: match.loaderData,
+      params: match.params,
+      requestUrl,
+    }) as CompiledRenderValue
+  }
+  return children
+}
+
+export function routeLoaderData(
+  matches: readonly LoadedRouteMatch[],
+): Readonly<Record<string, FrameworkValue>> {
+  return Object.freeze(
+    Object.fromEntries(matches.map((match) => [match.entry.id, match.loaderData])) as Record<
+      string,
+      FrameworkValue
+    >,
+  )
+}
+
+function readRouteDefinition(id: string, module: RouteModule): FileRouteDefinition {
+  const definition = module.Route ?? module.default
+  if (!isFileRouteDefinition(definition)) {
+    throw new TypeError(`route module ${id} must export a Route created by defineFileRoute`)
+  }
+  return definition
+}
+
+function matchPath(pattern: string, pathname: string): RouteParameters | undefined {
+  if (pattern === '/') return pathname === '/' ? Object.freeze({}) : undefined
+  const patternSegments = segments(pattern)
+  const pathSegments = segments(pathname)
+  const parameters: Record<string, string> = {}
+  let pathIndex = 0
+  for (const segment of patternSegments) {
+    if (segment === '*') {
+      if (pathIndex >= pathSegments.length) return undefined
+      parameters['*'] = decodeSegment(pathSegments.slice(pathIndex).join('/'))
+      pathIndex = pathSegments.length
+      break
+    }
+    const value = pathSegments[pathIndex]
+    if (value === undefined) return undefined
+    if (segment.startsWith(':')) parameters[segment.slice(1)] = decodeSegment(value)
+    else if (segment !== value) return undefined
+    pathIndex += 1
+  }
+  return pathIndex === pathSegments.length ? Object.freeze(parameters) : undefined
+}
+
+function normalizePathname(pathname: string): string {
+  const path = pathname.split(/[?#]/u, 1)[0] ?? '/'
+  if (!path.startsWith('/')) throw new TypeError('route pathname must start with /')
+  return path.length > 1 ? path.replace(/\/+$/u, '') : '/'
+}
+
+function segments(pathname: string): string[] {
+  return pathname.split('/').filter(Boolean)
+}
+
+function decodeSegment(value: string): string {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    throw new TypeError(`invalid encoded route segment ${value}`)
+  }
+}
+
+function routeScore(entry: RouteManifestEntry, manifest: RouteManifest): number {
+  const specificity = segments(entry.path).reduce(
+    (score, segment) => score + (segment === '*' ? 1 : segment.startsWith(':') ? 10 : 100),
+    0,
+  )
+  let depth = 0
+  let current: RouteManifestEntry | undefined = entry
+  while (current !== undefined) {
+    depth += 1
+    current = current.parentId === null ? undefined : manifest.byId.get(current.parentId)
+  }
+  return specificity * 1_000 + depth
+}
+
+function assertAcyclicParentChain(
+  entry: RouteManifestEntry,
+  byId: ReadonlyMap<string, RouteManifestEntry>,
+): void {
+  const visited = new Set<string>([entry.id])
+  let parentId = entry.parentId
+  while (parentId !== null) {
+    if (visited.has(parentId)) throw new TypeError(`route ${entry.id} has a cyclic parent chain`)
+    visited.add(parentId)
+    parentId = byId.get(parentId)?.parentId ?? null
+  }
+}

package/src/server.ts

@@ -0,0 +1,295 @@
+import { renderToReadableStream } from '@vidact/runtime/framework/server'
+import { createElement, type ServerChild, type ServerComponent } from '@vidact/runtime/server'
+
+import {
+  composeRouteMatches,
+  matchRoutes,
+  resolveRouteMatches,
+  routeLoaderData,
+  runRouteLoaders,
+  type ResolvedRouteMatch,
+  type RouteManifest,
+  type RouteServerHandler,
+  type StartComponent,
+} from './router.ts'
+import {
+  encodeStartSnapshot,
+  VIDACT_START_NAVIGATION_HEADER,
+  VIDACT_START_PROTOCOL,
+  VIDACT_START_SNAPSHOT_MEDIA_TYPE,
+} from './snapshot.ts'
+
+/**
+ * The client mounts the route tree under a compiled root of its own, and every compiled
+ * root claims a component marker range while hydrating. Rendering the tree inside a
+ * matching root component on the server keeps the two sides' component ranges aligned;
+ * without it each client component would claim the range of the *next* server one.
+ */
+function StartApplication({ children }: { readonly children?: ServerChild }): ServerChild {
+  return children
+}
+
+const DEFAULT_ROOT_ID = 'vidact-start-root'
+const DEFAULT_SNAPSHOT_ID = 'vidact-start-snapshot'
+
+export interface StartDocumentContext {
+  readonly applicationHtml: string
+  readonly clientEntry: string | undefined
+  readonly rootId: string
+  readonly snapshot: string
+  readonly snapshotId: string
+}
+
+export interface StartDocumentShellContext {
+  readonly clientEntry: string | undefined
+  readonly rootId: string
+  readonly snapshot: string
+  readonly snapshotId: string
+}
+
+export interface StartDocumentShell {
+  readonly afterApplication: string
+  readonly beforeApplication: string
+}
+
+export interface StartHandlerOptions {
+  readonly clientEntry?: string
+  readonly manifest: RouteManifest
+  readonly notFound?: (request: Request) => Response | Promise<Response>
+  readonly renderDocument?: (context: StartDocumentContext) => string | Promise<string>
+  readonly renderDocumentShell?: (
+    context: StartDocumentShellContext,
+  ) => StartDocumentShell | Promise<StartDocumentShell>
+  readonly rootId?: string
+  readonly snapshotId?: string
+}
+
+export function createStartHandler(
+  options: StartHandlerOptions,
+): (request: Request) => Promise<Response> {
+  if (options.renderDocument !== undefined && options.renderDocumentShell !== undefined) {
+    throw new TypeError('renderDocument and renderDocumentShell cannot be used together')
+  }
+  const rootId = options.rootId ?? DEFAULT_ROOT_ID
+  const snapshotId = options.snapshotId ?? DEFAULT_SNAPSHOT_ID
+  return async (request) => {
+    const url = new URL(request.url)
+    const matches = matchRoutes(options.manifest, url.pathname)
+    if (matches.length === 0) {
+      return options.notFound === undefined
+        ? new Response('Not found', { status: 404 })
+        : await options.notFound(request)
+    }
+    const resolved = await resolveRouteMatches(matches)
+    const endpoint = endpointHandler(resolved, request.method)
+    if (endpoint !== undefined) {
+      const response = await endpoint({
+        params: resolved.at(-1)!.params,
+        request,
+      })
+      return responseForRequest(request, response)
+    }
+    const canRender = resolved.some((match) => match.definition.options.component !== undefined)
+    if ((request.method !== 'GET' && request.method !== 'HEAD') || !canRender) {
+      const allow = allowedMethods(resolved, canRender)
+      if (allow.length === 0) {
+        return options.notFound === undefined
+          ? new Response('Not found', { status: 404 })
+          : await options.notFound(request)
+      }
+      return new Response('Method not allowed', {
+        status: 405,
+        headers: { allow: allow.join(', ') },
+      })
+    }
+    let loaded
+    try {
+      loaded = await runRouteLoaders(resolved, request)
+    } catch (error) {
+      if (isResponse(error)) return responseForRequest(request, error)
+      throw error
+    }
+    const snapshot = escapeScriptText(
+      encodeStartSnapshot({
+        protocol: VIDACT_START_PROTOCOL,
+        pathname: `${url.pathname}${url.search}`,
+        loaderData: routeLoaderData(loaded),
+      }),
+    )
+    if (request.headers.get(VIDACT_START_NAVIGATION_HEADER) === '1') {
+      return new Response(request.method === 'HEAD' ? null : snapshot, {
+        headers: representationHeaders(`${VIDACT_START_SNAPSHOT_MEDIA_TYPE}; charset=utf-8`),
+      })
+    }
+    const headers = representationHeaders('text/html; charset=utf-8')
+    if (request.method === 'HEAD') return new Response(null, { headers })
+
+    const application = composeRouteMatches(
+      loaded,
+      (component, props) =>
+        createElement(component as unknown as ServerComponent, props) as ServerChild,
+      request.url,
+    ) as ServerChild
+    const stream = await renderToReadableStream(
+      () => createElement(StartApplication, { children: application }) as ServerChild,
+      { identifierPrefix: 'start-', signal: request.signal },
+    )
+    void stream.allReady.catch(() => undefined)
+    const shellContext = {
+      clientEntry: options.clientEntry,
+      rootId,
+      snapshot,
+      snapshotId,
+    }
+    if (options.renderDocument !== undefined) {
+      const applicationHtml = await new Response(stream).text()
+      const html = await options.renderDocument({ ...shellContext, applicationHtml })
+      return new Response(html, { headers })
+    }
+    const shell =
+      options.renderDocumentShell === undefined
+        ? defaultDocumentShell(shellContext)
+        : validateDocumentShell(await options.renderDocumentShell(shellContext))
+    return new Response(streamDocument(shell, stream), { headers })
+  }
+}
+
+function representationHeaders(contentType: string): Headers {
+  const headers = new Headers({ 'content-type': contentType })
+  headers.append('vary', VIDACT_START_NAVIGATION_HEADER)
+  return headers
+}
+
+function responseForRequest(request: Request, response: Response): Response {
+  return request.method === 'HEAD' ? new Response(null, response) : response
+}
+
+function isResponse(value: unknown): value is Response {
+  if (value instanceof Response) return true
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    Object.prototype.hasOwnProperty.call(value, Symbol.toStringTag) ||
+    Object.prototype.toString.call(value) !== '[object Response]'
+  ) {
+    return false
+  }
+  try {
+    const candidate = value as Response
+    return (
+      typeof candidate.arrayBuffer === 'function' &&
+      typeof candidate.clone === 'function' &&
+      typeof candidate.headers?.get === 'function' &&
+      Number.isInteger(candidate.status)
+    )
+  } catch {
+    return false
+  }
+}
+
+function endpointHandler(
+  matches: readonly ResolvedRouteMatch[],
+  method: string,
+): RouteServerHandler | undefined {
+  const handlers = matches.at(-1)?.definition.options.server?.handlers
+  return handlers?.[method.toUpperCase()] ?? (method === 'HEAD' ? handlers?.GET : undefined)
+}
+
+function allowedMethods(
+  matches: readonly ResolvedRouteMatch[],
+  canRender: boolean,
+): readonly string[] {
+  const methods = new Set<string>()
+  if (canRender) {
+    methods.add('GET')
+    methods.add('HEAD')
+  }
+  const handlers = matches.at(-1)?.definition.options.server?.handlers
+  for (const method of Object.keys(handlers ?? {})) methods.add(method.toUpperCase())
+  if (methods.has('GET')) methods.add('HEAD')
+  return [...methods].toSorted(
+    (left, right) => methodRank(left) - methodRank(right) || left.localeCompare(right),
+  )
+}
+
+function methodRank(method: string): number {
+  return method === 'GET' ? 0 : method === 'HEAD' ? 1 : 2
+}
+
+function defaultDocumentShell(context: StartDocumentShellContext): StartDocumentShell {
+  const clientScript =
+    context.clientEntry === undefined
+      ? ''
+      : `<script type="module" src="${escapeAttribute(context.clientEntry)}"></script>`
+  return {
+    beforeApplication: `<!doctype html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head><body><div id="${escapeAttribute(context.rootId)}">`,
+    afterApplication: `</div><script id="${escapeAttribute(context.snapshotId)}" type="application/json">${context.snapshot}</script>${clientScript}</body></html>`,
+  }
+}
+
+function validateDocumentShell(value: StartDocumentShell): StartDocumentShell {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    typeof value.beforeApplication !== 'string' ||
+    typeof value.afterApplication !== 'string'
+  ) {
+    throw new TypeError('renderDocumentShell must return beforeApplication and afterApplication')
+  }
+  return value
+}
+
+function streamDocument(
+  shell: StartDocumentShell,
+  application: ReadableStream<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  const before = encoder.encode(shell.beforeApplication)
+  const after = encoder.encode(shell.afterApplication)
+  const reader = application.getReader()
+  let phase: 'after' | 'application' | 'before' | 'done' = 'before'
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        if (phase === 'before') {
+          phase = 'application'
+          if (before.length > 0) controller.enqueue(before)
+          return
+        }
+        if (phase === 'application') {
+          const result = await reader.read()
+          if (!result.done) {
+            controller.enqueue(result.value)
+            return
+          }
+          phase = 'after'
+        }
+        if (phase === 'after') {
+          phase = 'done'
+          if (after.length > 0) controller.enqueue(after)
+          return
+        }
+        controller.close()
+      } catch (error) {
+        controller.error(error)
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason)
+    },
+  })
+}
+
+function escapeAttribute(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+}
+
+function escapeScriptText(value: string): string {
+  return value.replaceAll('&', '\\u0026').replaceAll('<', '\\u003c').replaceAll('>', '\\u003e')
+}
+
+export type { StartComponent }

package/src/snapshot.ts

@@ -0,0 +1,40 @@
+import {
+  decodeFrameworkValue,
+  encodeFrameworkValue,
+  type FrameworkValue,
+} from '@vidact/runtime/framework/protocol'
+
+export const VIDACT_START_PROTOCOL = 'vidact-start-v1'
+export const VIDACT_START_NAVIGATION_HEADER = 'x-vidact-start-navigation'
+export const VIDACT_START_SNAPSHOT_MEDIA_TYPE = 'application/x-vidact-start+json'
+
+export interface StartSnapshot {
+  readonly protocol: typeof VIDACT_START_PROTOCOL
+  readonly loaderData: Readonly<Record<string, FrameworkValue>>
+  readonly pathname: string
+}
+
+export function encodeStartSnapshot(snapshot: StartSnapshot): string {
+  return encodeFrameworkValue(snapshot as unknown as FrameworkValue)
+}
+
+export function decodeStartSnapshot(payload: string): StartSnapshot {
+  const value = decodeFrameworkValue(payload)
+  if (
+    !isRecord(value) ||
+    value.protocol !== VIDACT_START_PROTOCOL ||
+    typeof value.pathname !== 'string' ||
+    !isRecord(value.loaderData)
+  ) {
+    throw new TypeError('invalid Vidact Start snapshot')
+  }
+  return {
+    protocol: VIDACT_START_PROTOCOL,
+    pathname: value.pathname,
+    loaderData: value.loaderData as Readonly<Record<string, FrameworkValue>>,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/virtual.ts

@@ -0,0 +1,5 @@
+// Shipped verbatim as dist/virtual.d.ts: an ambient declaration cannot be bundled
+// without becoming a module augmentation, so it names the built router file.
+declare module 'virtual:vidact-start/routes' {
+  export const routeManifest: import('./router.js').RouteManifest
+}