@weft-js/start 0.1.0 → 0.1.2

package/src/server/routes.ts

@@ -0,0 +1,150 @@
+import type { AsyncLocalStorage } from 'node:async_hooks'
+import { BaseRootRoute, BaseRoute, isNotFound, type AnyRoute } from '@tanstack/router-core'
+import { isRedirect, type Redirect } from '../data'
+import * as exec from '../exec'
+import type { Scope } from '../exec'
+import type { Manifest, RouteModule } from './types'
+
+/**
+ * What each router-core loader gets as `context`: the request scope, where it leaves tags and redirects (router-core
+ * copies the context object, so those go in shared containers), and the matched page's catch-all name.
+ */
+export interface LoadContext {
+  request: Request
+  scope: Scope
+  tags: Map<string, Set<string>>
+  out: { redirect?: Redirect; chain?: Promise<unknown> }
+  splat?: string | undefined
+}
+
+interface TreeNode {
+  route: AnyRoute
+  children: AnyRoute[]
+  dir: string
+}
+
+const makeLoader =
+  (modules: Record<string, RouteModule>, als: AsyncLocalStorage<Scope>) =>
+  (file: string, splat?: string) =>
+  async ({
+    params,
+    context,
+    abortController,
+  }: {
+    params: Record<string, unknown>
+    context: LoadContext
+    abortController: AbortController
+  }) => {
+    const load = modules[file]?.load
+    if (!load) return undefined
+    // Parent first (router-core starts them together): a layout's `load` is a guard, so a child never runs for a
+    // visitor its parent redirects (research 28 §3).
+    const out = context.out
+    const before = out.chain
+    let done!: () => void
+    out.chain = new Promise<void>((ok) => {
+      done = ok
+    })
+    await before
+    if (out.redirect) return (done(), undefined)
+    // Each loader runs in its own frame of the request scope, which records the tags of the queries it read.
+    const f = exec.frame(context.scope)
+    context.tags.set(file, f.tags!)
+    try {
+      const ctx = await f.ctx()
+      const v = await als.run(f, () =>
+        load({
+          params: cleanParams(params, splat ?? context.splat),
+          request: context.request,
+          signal: abortController.signal,
+          ctx,
+        }),
+      )
+      // oxlint-disable-next-line typescript/only-throw-error -- router-core's own not-found signal, passed on as it came
+      if (isNotFound(v)) throw v
+      return v
+    } catch (e) {
+      if (!isRedirect(e)) throw e
+      out.redirect ??= e
+      return undefined
+    } finally {
+      done()
+    }
+  }
+
+/** The router-core tree for the manifest: layouts are path prefixes, routes hang under their innermost layout. */
+export function routeTree(
+  manifest: Manifest,
+  modules: Record<string, RouteModule>,
+  als: AsyncLocalStorage<Scope>,
+) {
+  const loader = makeLoader(modules, als)
+  const rootLayout = manifest.layouts.find((l) => l.dir === '')
+  const root = new BaseRootRoute({
+    ...(rootLayout && { loader: loader(rootLayout.file), weft: rootLayout }),
+  } as never)
+  const top: TreeNode = { route: root, children: [], dir: '' }
+  const nodes = new Map<string, TreeNode>()
+  const at = (id: string | undefined) => (id ? (nodes.get(id) ?? top) : top)
+  for (const l of manifest.layouts) {
+    if (l.dir === '') {
+      nodes.set(l.id, top)
+      continue
+    }
+    const parent = at(l.parent)
+    const route = new BaseRoute({
+      getParentRoute: () => parent.route,
+      path: toPath(l.dir, parent.dir),
+      loader: loader(l.file),
+      weft: l,
+    } as never)
+    parent.children.push(route)
+    nodes.set(l.id, { route, children: [], dir: l.dir })
+  }
+  const splats = new Set(manifest.routes.filter((r) => r.splat).map((r) => r.pattern))
+  for (const r of manifest.routes) {
+    if (r.kind !== 'page') continue
+    const parent = at(r.layouts.at(-1))
+    const rel = r.pattern
+      .slice(1)
+      .split('/')
+      .slice(parent.dir ? parent.dir.split('/').length : 0)
+      .join('/')
+    // A splat beside it (`docs/[...slug]` next to `docs/index`) also matches `/docs`, and router-core ranks the
+    // splat first unless the page is its index route, written with the slash.
+    const index = rel && splats.has(`${r.pattern}/$`) ? `${rel}/` : rel
+    parent.children.push(
+      new BaseRoute({
+        getParentRoute: () => parent.route,
+        path: index || '/',
+        loader: loader(r.file, r.splat),
+        weft: r,
+      } as never),
+    )
+  }
+  // Innermost layouts first, so each route's children are attached before its parent takes it.
+  for (const n of [...new Set(nodes.values())]
+    .filter((x) => x !== top)
+    .sort((a, b) => b.dir.length - a.dir.length))
+    if (n.children.length) n.route.addChildren(n.children)
+  return root.addChildren(top.children)
+}
+
+/** A layout dir relative to its parent layout's, as a router-core path: `users/[id]` → `users/$id`. */
+function toPath(dir: string, parentDir: string) {
+  const rel = dir.split('/').slice(parentDir ? parentDir.split('/').length : 0)
+  return rel
+    .map((s) => s.replace(/^\[\.\.\.(\w+)\]$/, '$').replace(/^\[(\w+)\]$/, '$$$1'))
+    .join('/')
+}
+
+/** router-core's params without its splat aliases; a splat is under its file name (`[...rest]` → `rest`). */
+export function cleanParams(
+  p: Record<string, unknown> = {},
+  splat?: string,
+): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const k in p) if (k !== '*' && k !== '_splat') out[k] = String(p[k])
+  if (splat && p._splat !== undefined) out[splat] = p._splat as string
+  return out
+}

package/src/server/services.ts

@@ -0,0 +1,69 @@
+import { runtime } from '../data'
+import * as exec from '../exec'
+import type { MediaServer } from '../exec'
+import { configure } from '../hub'
+import type { ServerExtension } from '../extension'
+import type { HandlerOptions } from './types'
+
+/** Handler-local extensions, media provider, and boot state. */
+export function makeServices(options: HandlerOptions) {
+  let provider: Promise<MediaServer> | undefined
+  const mediaServer = () => (provider ??= options.media?.())
+  const scopeOptions = {
+    context: options.context,
+    store: options.store,
+    dev: options.dev,
+    onDiagnostic: options.onDiagnostic,
+    media: mediaServer,
+    extensions: undefined as ServerExtension[] | undefined,
+  }
+  let checked = !options.dev
+  const authBase = (options.auth?.basePath ?? '/api/auth').replace(/\/$/, '')
+  const extensions = new Map<string, ServerExtension>()
+  let loading: Promise<void> | undefined
+  const loadExtensions = () =>
+    (loading ??= (async () => {
+      for (const e of options.extensions ?? []) extensions.set(e.key, await e.load())
+      scopeOptions.extensions = [...extensions.values()]
+    })())
+  let applied = -1
+  configure({
+    ...options.realtime,
+    build: options.build,
+    dev: options.dev,
+    store: options.store,
+    required: options.liveRequired,
+    onDiagnostic: options.onDiagnostic,
+  })
+
+  /**
+   * Before the first request (and in dev, when `drizzle/` grows): the auth secret, and the list each database applies
+   * before its first statement (db/core.ts), so a page with no queries doesn't need one. A client whose statements can't
+   * be held is migrated here; if that fails the request goes on, and Q016 is what using the database then gives.
+   */
+  async function boot() {
+    const list = options.migrations?.() ?? []
+    if (applied !== list.length) {
+      options.auth?.$weft?.check()
+      for (const e of extensions.values()) e.check?.(options.dev)
+      applied = list.length
+      const report = (e: unknown) =>
+        options.onDiagnostic?.({
+          code: 'Q016',
+          severity: 'error',
+          message: `Q016: ${String((e as Error | null)?.message ?? e)}`,
+        })
+      runtime.migrations = { list, report }
+    }
+    if (runtime.dbs?.size)
+      await Promise.all([...runtime.dbs].map((ready) => Promise.resolve(ready()).catch(() => {})))
+  }
+
+  const check = () => {
+    if (!checked) {
+      checked = true
+      exec.checkTags((d) => options.onDiagnostic?.(d))
+    }
+  }
+  return { mediaServer, scopeOptions, authBase, extensions, loadExtensions, boot, check }
+}

package/src/server/text.ts

@@ -0,0 +1,29 @@
+import { esc } from '@weft-js/core/markup'
+export { esc } from '@weft-js/core/markup'
+
+export const json = (v: unknown) => JSON.stringify(v ?? null).replace(/</g, '\\u003c')
+/**
+ * A redirect's body. A server's 3xx is followed by its `location`; a prerendered one is a file on a static host, and this
+ * is what that file says: go now, and the address to index. No stylesheet, so no view transition starts on a page
+ * that never paints (Chrome aborts it, and logs an InvalidStateError).
+ */
+export const moved = (href: string) =>
+  `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Moved</title><meta name="robots" content="noindex"><link rel="canonical" href="${esc(href)}"><meta http-equiv="refresh" content="0; url=${esc(href)}"><a href="${esc(href)}">Moved here</a>`
+export const thenable = (v: unknown): v is PromiseLike<unknown> =>
+  typeof (v as Partial<PromiseLike<unknown>> | null | undefined)?.then === 'function'
+
+/** `/` → `index`, `/users/42` → `users/42`: the card path under `/_weft/og/`. */
+export const cardPath = (path: string) =>
+  path.replace(/[?#].*/, '').replace(/^\/+|\/+$/g, '') || 'index'
+
+/** FNV-1a, twice (different seeds), in base 36: a stable, sync content hash for `?v=`. */
+export function hash(s: string): string {
+  let a = 0x811c9dc5,
+    b = 0x01000193 ^ 0x5bd1e995
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    a = Math.imul(a ^ c, 0x01000193)
+    b = Math.imul(b ^ c, 0x5bd1e995)
+  }
+  return ((a >>> 0).toString(36) + (b >>> 0).toString(36)).slice(0, 10)
+}

package/src/server/types.ts

@@ -0,0 +1,160 @@
+import type { Site, Merged, Meta as MetaObject } from '@weft-js/core/ssr'
+import type { AssetReceipt, Component, Match } from '../router'
+import type { AuthProvider } from '../auth'
+import type { ExtensionEntry } from '../extension'
+import type { Context, Redirect } from '../data'
+import type { MediaServer, Store } from '../exec'
+import type { RealtimeOptions } from '../hub'
+import type { Pieces } from '../first-paint'
+
+/** A page route from the file tree. */
+export interface RouteEntry {
+  id: string
+  file: string
+  layouts: string[]
+  pattern: string
+  params: string[]
+  splat?: string
+  card?: string
+  kind: 'page' | '404' | 'error'
+}
+/** A layout from the file tree. */
+export interface LayoutEntry {
+  id: string
+  file: string
+  dir: string
+  parent?: string
+}
+/** The routes and layouts `weft build` found. */
+export interface Manifest {
+  dir: string
+  routes: RouteEntry[]
+  layouts: LayoutEntry[]
+  defaultCard?: string
+}
+
+/** What a route file exports. */
+export interface RouteModule {
+  default?: Component
+  load?: (args: {
+    params: Record<string, string>
+    request: Request
+    signal: AbortSignal
+    ctx: Context
+  }) => unknown
+  meta?:
+    | MetaObject
+    | ((args: {
+        params: Record<string, string>
+        data: unknown
+      }) => MetaObject | Promise<MetaObject>)
+  prerender?:
+    | true
+    | Record<string, string>[]
+    | (() => Record<string, string>[] | Promise<Record<string, string>[]>)
+  size?: { width: number; height: number }
+}
+
+/** A font for generated cards. */
+export interface Font {
+  name: string
+  data: Uint8Array
+  weight?: number
+  style?: 'normal' | 'italic'
+}
+
+/** `createHandler`: the app as the build describes it, and how to serve it. */
+export interface HandlerOptions {
+  manifest: Manifest
+  /** Route, layout and card modules by manifest file. */
+  modules: Record<string, RouteModule>
+  site?: Site
+  /**
+   * The client entry and what to preload (Nitro's `?assets=client`), plus the font build's preloads (`weft:fonts/preloads`).
+   * `pieces`: the build's first-paint table. Without it, `inline` and Weft's purge (`critical`) are what `pageStyles` uses.
+   */
+  assets?: {
+    entry?: string
+    js?: { href: string }[]
+    css?: { href: string }[]
+    fonts?: { href: string; type: string }[]
+    pieces?: Pieces & {
+      shared?: { href: string; has: string[] }
+      routes: { href: string; has: string[] }[]
+    }
+    inline?: Record<string, string>
+    critical?: {
+      parse: (css: string) => unknown[]
+      purge: (sheets: string[], found: { has: (word: string) => boolean }) => string[]
+    }
+  }
+  /** Changes with every build: part of each card's `?v=` hash. */
+  build?: string
+  /** Build-matched emitted asset receipt; null until the client bundle is available. */
+  routeAssetBytes?: AssetReceipt | null
+  dev?: boolean
+  fonts?: Font[]
+  /** Route and layout ids with no client code (PLAN §11): the server sends their HTML. */
+  statics?: string[]
+  /** Client chunks by level or island id: the page's own are preloaded, so they don't wait for the entry to ask. */
+  chunks?: Record<string, { js?: { href: string }[]; css?: { href: string }[] }>
+  /** Some island can wait, so every page carries the capture script: a navigation can arrive at one that does. */
+  lazy?: boolean
+  /** Stream timeout for Boundaries (ms). */
+  timeout?: number
+  /** How long (ms) a page waits for its Boundaries' data before streaming it: what lands sooner goes in the page. 0 streams at once. */
+  hold?: number
+  /** The app's context for `load` and server functions (`src/context.server.ts`'s default export). */
+  context?: (args: { request: Request }) => object | Promise<object>
+  /** The shared cache for `cache: { life }` queries (memory by default). */
+  store?: Store
+  /** `src/auth.server.ts`'s default export, any provider: mounted at its base path, checked on the first request. */
+  auth?: Pick<AuthProvider, 'handler' | 'basePath' | '$weft'>
+  /** `server.extension` providers with an app file (`virtual:weft/extensions`), loaded on the first request. */
+  extensions?: ExtensionEntry[]
+  /** The app's migrations (`drizzle/`); dev reads them each request, so `weft db generate` needs no restart. */
+  migrations?: () => { tag: string; sql: string }[]
+  /** The `media.server` provider (`virtual:weft/media`), loaded on first use. */
+  media?: () => Promise<MediaServer>
+  /** `src/realtime.server.ts`'s default export: the bus, origins and limits. */
+  realtime?: RealtimeOptions
+  /** `false`: never build URLs on the request's origin (`weft routes --meta`, whose requests aren't real). */
+  requestOrigin?: false
+  /** Queries marked `live: { required: true }` (`scanRequired`, at build). */
+  liveRequired?: string[]
+  /** Dev and tests: diagnostics found while serving (H005–H008, Q002–Q010). */
+  onDiagnostic?: (d: { code: string; severity: string; message: string; route?: string }) => void
+}
+
+/** One matched route level, with its module and the data before serialising. */
+export interface Level extends Match {
+  mod?: RouteModule | undefined
+  raw: unknown
+}
+
+/** Where the words on a page came from, and its image: what `weft routes --meta` and `weft check` report. */
+export interface MetaSource {
+  title: 'route' | 'layout' | 'auto' | 'config' | 'none'
+  description: 'route' | 'layout' | 'auto' | 'config' | 'none'
+  image: 'explicit' | 'card' | 'auto' | 'none'
+}
+
+/** What a path comes to: the status, the route and its levels. */
+export interface Resolved {
+  status: number
+  path: string
+  levels: Level[]
+  head: Merged
+  /** The page route, when one matched. */
+  route?: RouteEntry | undefined
+  error?: unknown
+  /** A loader called `redirect()`: nothing renders. */
+  redirect?: Redirect
+  /** Headers supplied by a router-core redirect. */
+  redirectHeaders?: Headers
+  /** The metas the head is merged from, until `complete` has finished it. */
+  metas?: MetaObject[] | undefined
+  source?: MetaSource
+  /** The origin URLs are built on, when one is known. */
+  origin?: string | undefined
+}