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

package/src/server.ts

@@ -0,0 +1,211 @@
+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 StartHandlerOptions {
+  readonly clientEntry?: string
+  readonly manifest: RouteManifest
+  readonly notFound?: (request: Request) => Response | Promise<Response>
+  readonly renderDocument?: (context: StartDocumentContext) => string | Promise<string>
+  readonly rootId?: string
+  readonly snapshotId?: string
+}
+
+export function createStartHandler(
+  options: StartHandlerOptions,
+): (request: Request) => Promise<Response> {
+  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: { 'content-type': `${VIDACT_START_SNAPSHOT_MEDIA_TYPE}; charset=utf-8` },
+      })
+    }
+
+    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-' },
+    )
+    const applicationHtml = await new Response(stream).text()
+    const documentContext = {
+      applicationHtml,
+      clientEntry: options.clientEntry,
+      rootId,
+      snapshot,
+      snapshotId,
+    }
+    const html =
+      options.renderDocument === undefined
+        ? defaultDocument(documentContext)
+        : await options.renderDocument(documentContext)
+    return new Response(request.method === 'HEAD' ? null : html, {
+      headers: { 'content-type': 'text/html; charset=utf-8' },
+    })
+  }
+}
+
+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 defaultDocument(context: StartDocumentContext): string {
+  const clientScript =
+    context.clientEntry === undefined
+      ? ''
+      : `<script type="module" src="${escapeAttribute(context.clientEntry)}"></script>`
+  return `<!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)}">${context.applicationHtml}</div><script id="${escapeAttribute(context.snapshotId)}" type="application/json">${context.snapshot}</script>${clientScript}</body></html>`
+}
+
+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
+}

package/src/vite.ts

@@ -0,0 +1,256 @@
+import { readdir } from 'node:fs/promises'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import path from 'node:path'
+
+import { vidact, type VidactPluginOptions } from '@vidact/vite'
+import {
+  isRunnableDevEnvironment,
+  normalizePath,
+  type Plugin,
+  type ResolvedConfig,
+  type ViteDevServer,
+} from 'vite'
+
+const PUBLIC_ROUTES_ID = 'virtual:vidact-start/routes'
+const INTERNAL_ROUTES_ID = `\0${PUBLIC_ROUTES_ID}`
+const ROUTE_FILE = /\.(?:[cm]?[jt]sx?)$/u
+const IGNORED_ROUTE_FILE = /(?:^|\.)\b(?:test|spec)\.[cm]?[jt]sx?$/u
+
+export interface VidactStartOptions {
+  readonly compiler?: Omit<VidactPluginOptions, 'target'>
+  readonly routesDirectory?: string
+  readonly serverEntry?: string | false
+  readonly serverExport?: string
+}
+
+export interface GeneratedRouteRecord {
+  readonly file: string
+  readonly id: string
+  readonly parentId: string | null
+  readonly path: string
+}
+
+export function vidactStart(options: VidactStartOptions = {}): Plugin[] {
+  const compiler = options.compiler ?? {}
+  const features = [...new Set(['framework', ...(compiler.features ?? [])])] as NonNullable<
+    VidactPluginOptions['features']
+  >
+  const plugins = [
+    vidactForEnvironment('client', { ...compiler, target: 'hydrate', features }),
+    vidactForEnvironment('ssr', { ...compiler, target: 'server', features }),
+    routeManifestPlugin(options.routesDirectory),
+  ]
+  if (options.serverEntry !== false) {
+    plugins.push(
+      developmentServerPlugin(
+        options.serverEntry ?? '/src/server.ts',
+        options.serverExport ?? 'default',
+      ),
+    )
+  }
+  return plugins
+}
+
+function routeManifestPlugin(configuredRoutesDirectory: string | undefined): Plugin {
+  let config: ResolvedConfig
+  let routesDirectory: string
+  let server: ViteDevServer | undefined
+  return {
+    name: 'vidact-start-routes',
+    configResolved(resolved) {
+      config = resolved
+      routesDirectory = path.resolve(config.root, configuredRoutesDirectory ?? 'src/routes')
+    },
+    configureServer(viteServer) {
+      server = viteServer
+      viteServer.watcher.add(routesDirectory)
+    },
+    resolveId(source) {
+      return source === PUBLIC_ROUTES_ID ? INTERNAL_ROUTES_ID : null
+    },
+    async load(id) {
+      if (id !== INTERNAL_ROUTES_ID) return null
+      return generateRouteModule(await discoverRouteRecords(routesDirectory))
+    },
+    handleHotUpdate(context) {
+      if (!isRouteFile(routesDirectory, context.file)) return
+      const module = server?.moduleGraph.getModuleById(INTERNAL_ROUTES_ID)
+      if (module !== undefined) server?.moduleGraph.invalidateModule(module)
+      server?.ws.send({ type: 'full-reload' })
+      return []
+    },
+  }
+}
+
+function vidactForEnvironment(
+  environmentName: 'client' | 'ssr',
+  options: VidactPluginOptions,
+): Plugin {
+  const plugin = vidact(options)
+  return {
+    ...plugin,
+    name: `${plugin.name}:start:${environmentName}`,
+    applyToEnvironment: (environment) => environment.name === environmentName,
+  }
+}
+
+function developmentServerPlugin(serverEntry: string, serverExport: string): Plugin {
+  return {
+    name: 'vidact-start-development-server',
+    config: () => ({ appType: 'custom' }),
+    configureServer(server) {
+      return () => {
+        server.middlewares.use((nodeRequest, nodeResponse, next) => {
+          void serveDevelopmentRequest(
+            server,
+            serverEntry,
+            serverExport,
+            nodeRequest,
+            nodeResponse,
+          ).catch((error: unknown) => {
+            if (error instanceof Error) server.ssrFixStacktrace(error)
+            next(error)
+          })
+        })
+      }
+    },
+  }
+}
+
+async function serveDevelopmentRequest(
+  server: ViteDevServer,
+  serverEntry: string,
+  serverExport: string,
+  nodeRequest: IncomingMessage,
+  nodeResponse: ServerResponse,
+): Promise<void> {
+  const environment = server.environments.ssr
+  if (!isRunnableDevEnvironment(environment)) {
+    throw new Error("Vidact Start requires Vite's runnable SSR development environment")
+  }
+  const module = (await environment.runner.import(serverEntry)) as Record<string, unknown>
+  const handler = module[serverExport]
+  if (typeof handler !== 'function') {
+    throw new TypeError(`${serverEntry} must export a ${serverExport} request handler`)
+  }
+  const request = await nodeRequestToRequest(nodeRequest)
+  let response = await (handler as (request: Request) => Response | Promise<Response>)(request)
+  if (!(response instanceof Response)) {
+    throw new TypeError(`${serverEntry} ${serverExport} must return a Response`)
+  }
+  if (response.headers.get('content-type')?.startsWith('text/html') === true) {
+    const html = await server.transformIndexHtml(nodeRequest.url ?? '/', await response.text())
+    response = new Response(html, response)
+  }
+  await sendNodeResponse(nodeResponse, response)
+}
+
+async function nodeRequestToRequest(request: IncomingMessage): Promise<Request> {
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (Array.isArray(value)) for (const item of value) headers.append(name, item)
+    else if (value !== undefined) headers.set(name, value)
+  }
+  const forwardedProtocol = headers.get('x-forwarded-proto')?.split(',', 1)[0]?.trim()
+  const protocol =
+    forwardedProtocol ?? (Reflect.get(request.socket, 'encrypted') === true ? 'https' : 'http')
+  const url = new URL(request.url ?? '/', `${protocol}://${headers.get('host') ?? 'localhost'}`)
+  const body =
+    request.method === 'GET' || request.method === 'HEAD'
+      ? undefined
+      : await readRequestBody(request)
+  return new Request(url, {
+    method: request.method ?? 'GET',
+    headers,
+    ...(body === undefined ? {} : { body }),
+  })
+}
+
+async function readRequestBody(request: IncomingMessage): Promise<ArrayBuffer> {
+  const chunks: Uint8Array[] = []
+  for await (const chunk of request) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk)
+  }
+  return Uint8Array.from(Buffer.concat(chunks)).buffer
+}
+
+async function sendNodeResponse(response: ServerResponse, webResponse: Response): Promise<void> {
+  response.statusCode = webResponse.status
+  response.statusMessage = webResponse.statusText
+  for (const [name, value] of webResponse.headers) response.setHeader(name, value)
+  const cookies = webResponse.headers.getSetCookie()
+  if (cookies.length > 0) response.setHeader('set-cookie', cookies)
+  response.end(Buffer.from(await webResponse.arrayBuffer()))
+}
+
+export async function discoverRouteRecords(
+  routesDirectory: string,
+): Promise<readonly GeneratedRouteRecord[]> {
+  let filenames: string[]
+  try {
+    filenames = await readdir(routesDirectory, { recursive: true })
+  } catch (error) {
+    if (isMissingDirectory(error)) return []
+    throw error
+  }
+  const records = filenames
+    .filter((filename) => ROUTE_FILE.test(filename) && !IGNORED_ROUTE_FILE.test(filename))
+    .map((filename) => routeFileToRecord(filename, routesDirectory))
+  const ids = new Set(records.map((record) => record.id))
+  return Object.freeze(
+    records
+      .map((record) => Object.freeze({ ...record, parentId: parentRouteId(record.id, ids) }))
+      .toSorted((left, right) => left.id.localeCompare(right.id)),
+  )
+}
+
+export function routeFileToRecord(filename: string, routesDirectory: string): GeneratedRouteRecord {
+  const normalizedFilename = normalizePath(filename)
+  const id = normalizedFilename.replace(ROUTE_FILE, '')
+  if (id.length === 0) throw new TypeError(`invalid route filename ${filename}`)
+  const routeSegments = id
+    .split('/')
+    .filter((segment) => segment !== '__root' && segment !== 'index' && !segment.startsWith('_'))
+    .map((segment) =>
+      segment === '$' ? '*' : segment.startsWith('$') ? `:${segment.slice(1)}` : segment,
+    )
+  return {
+    file: normalizePath(path.resolve(routesDirectory, normalizedFilename)),
+    id,
+    parentId: null,
+    path: routeSegments.length === 0 ? '/' : `/${routeSegments.join('/')}`,
+  }
+}
+
+function parentRouteId(id: string, ids: ReadonlySet<string>): string | null {
+  if (id === '__root') return null
+  const segments = id.split('/')
+  if (segments.at(-1) === 'index') segments.pop()
+  while (segments.length > 0) {
+    const candidate = segments.join('/')
+    if (candidate !== id && ids.has(candidate)) return candidate
+    segments.pop()
+  }
+  return ids.has('__root') ? '__root' : null
+}
+
+function generateRouteModule(records: readonly GeneratedRouteRecord[]): string {
+  const entries = records
+    .map(
+      (record) =>
+        `{ id: ${JSON.stringify(record.id)}, parentId: ${JSON.stringify(record.parentId)}, path: ${JSON.stringify(record.path)}, load: () => import(${JSON.stringify(record.file)}) }`,
+    )
+    .join(',\n  ')
+  return `import { createRouteManifest } from '@vidact/start'\n\nexport const routeManifest = createRouteManifest([\n  ${entries}\n])\n`
+}
+
+function isRouteFile(routesDirectory: string, filename: string): boolean {
+  const relative = path.relative(routesDirectory, filename)
+  return (
+    !relative.startsWith('..') && ROUTE_FILE.test(relative) && !IGNORED_ROUTE_FILE.test(relative)
+  )
+}
+
+function isMissingDirectory(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && Reflect.get(error, 'code') === 'ENOENT'
+}

package/dist/index-client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-client.d.ts","sourceRoot":"","sources":["../src/index-client.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/index-client.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-client.js","sourceRoot":"","sources":["../src/index-client.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/dist/virtual.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"virtual.d.ts","sourceRoot":"","sources":["../src/virtual.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,6BAA6B,CAAC;IACpC,MAAM,aAAa,EAAE,OAAO,aAAa,EAAE,aAAa,CAAA;CAChE"}

package/dist/virtual.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"virtual.js","sourceRoot":"","sources":["../src/virtual.ts"],"names":[],"mappings":""}