@statorjs/stator 1.0.0

package/src/server/render.ts

@@ -0,0 +1,111 @@
+import { createRenderState, type RenderState, runInRender } from './render-context.ts'
+import type {
+  RouteDefinition,
+  RouteRenderContext,
+  RouteRequest,
+  RouteResponseContext,
+} from './routing.ts'
+import type { SessionRuntime } from './session-runtime.ts'
+
+export interface RenderResult {
+  html: string
+  renderState: RenderState
+  /** Response side effects the render function wrote (status, headers, cookies).
+   *  Caller (HTTP layer) is responsible for applying these to the outgoing
+   *  HTTP response. */
+  response: RenderedResponseEffects
+}
+
+export interface RenderedResponseEffects {
+  status: number
+  headers: Headers
+  cookies: Array<{
+    name: string
+    value: string
+    options: import('./routing.ts').RouteCookieOptions | undefined
+    deleted: boolean
+  }>
+}
+
+/**
+ * Build a fresh RouteResponseContext for a render. The render function
+ * mutates this; the HTTP layer reads back the effects and applies them
+ * to the outgoing Response.
+ */
+function createResponseContext(): {
+  ctx: RouteResponseContext
+  effects: RenderedResponseEffects
+} {
+  const effects: RenderedResponseEffects = {
+    status: 200,
+    headers: new Headers(),
+    cookies: [],
+  }
+  const ctx: RouteResponseContext = {
+    get status() {
+      return effects.status
+    },
+    set status(s: number) {
+      effects.status = s
+    },
+    headers: effects.headers,
+    cookies: {
+      set(name, value, options) {
+        effects.cookies.push({ name, value, options, deleted: false })
+      },
+      delete(name, options) {
+        effects.cookies.push({
+          name,
+          value: '',
+          options: { ...options, maxAge: 0 },
+          deleted: true,
+        })
+      },
+    },
+  }
+  return { ctx, effects }
+}
+
+/**
+ * Build the route's render context from a SessionRuntime (which already
+ * holds transient proxies for every machine the route depends on), then
+ * invoke the route's render function under a fresh RenderState.
+ *
+ * RenderState lifetime in the current model is request-scoped: a GET
+ * discards it after the response, a POST keeps it just long enough to
+ * run `recompute` against the post-event state. SSE connections retain
+ * it for the connection's lifetime.
+ *
+ * `request` carries URL-derived state and body access. `response` carries
+ * side-effect helpers (status, headers, cookies). The render function
+ * returns the rendered HTML; the HTTP layer combines the HTML with the
+ * response effects to build the final Response.
+ */
+export function renderRoute(
+  route: RouteDefinition,
+  routeKey: string,
+  sessionId: string,
+  runtime: SessionRuntime,
+  request: RouteRequest,
+): RenderResult {
+  const state = createRenderState(sessionId, routeKey)
+  const { ctx: responseCtx, effects } = createResponseContext()
+  const renderCtx: RouteRenderContext = {
+    response: responseCtx,
+  } as RouteRenderContext
+
+  for (const def of route.reads) {
+    if (def.name === 'response') {
+      throw new Error(
+        'stator: a machine cannot be named "response"; the render context reserves that key',
+      )
+    }
+    const proxy = runtime.proxyFor(def.name)
+    if (!proxy) {
+      throw new Error(`stator: route reads "${def.name}" but it's not loaded into the runtime`)
+    }
+    ;(renderCtx as Record<string, unknown>)[def.name] = proxy
+  }
+  const fragment = runInRender(state, () => route.render(renderCtx, request))
+  return { html: fragment.html, renderState: state, response: effects }
+}

package/src/server/route-discovery.ts

@@ -0,0 +1,226 @@
+import { readdir } from 'node:fs/promises'
+import { basename, dirname, extname, relative, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { ModuleLoader } from './discovery.ts'
+import {
+  type ApiRouteDefinition,
+  isStatorApiRoute,
+  isStatorRoute,
+  type RouteDefinition,
+} from './routing.ts'
+
+const nativeLoader: ModuleLoader = (file) => import(/* @vite-ignore */ pathToFileURL(file).href)
+
+/** HTTP methods a route file may export. GET goes through `defineRoute`
+ *  (page rendering); the rest go through `defineApiRoute` (mutation/API
+ *  handlers). */
+export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
+export type HttpMethod = (typeof HTTP_METHODS)[number]
+
+export interface DiscoveredRoute {
+  /** Hono-shaped URL pattern. Path params are `:name`. */
+  urlPath: string
+  /** Names of path parameters in the order they appear in `urlPath`.
+   *  Empty for static routes. */
+  paramNames: string[]
+  filePath: string
+  /** GET route (page render). At most one. */
+  GET?: RouteDefinition
+  /** API routes by method. */
+  POST?: ApiRouteDefinition
+  PUT?: ApiRouteDefinition
+  PATCH?: ApiRouteDefinition
+  DELETE?: ApiRouteDefinition
+}
+
+/**
+ * Walk the routes directory recursively and build URL patterns from file
+ * paths. Conventions:
+ *
+ *   - `routes/foo.ts`         → `/foo`
+ *   - `routes/foo/index.ts`   → `/foo`
+ *   - `routes/foo/[id].ts`    → `/foo/:id`  (path param `id`)
+ *   - `routes/[a]/[b].ts`     → `/:a/:b`
+ *
+ * Files may export any combination of `GET`/`POST`/`PUT`/`PATCH`/`DELETE`.
+ * GET is a `defineRoute` (page renderer); the others are `defineApiRoute`.
+ *
+ * Files that don't export anything route-shaped are silently skipped. With
+ * recursive walking, the routes tree often contains utility files
+ * (templates, helpers) that aren't routes, and throwing on them would
+ * force separate trees.
+ */
+export async function discoverRoutes(
+  dir: string,
+  load: ModuleLoader = nativeLoader,
+): Promise<DiscoveredRoute[]> {
+  const absDir = resolve(dir)
+  const files = await walkRouteFiles(absDir)
+  const routes: DiscoveredRoute[] = []
+
+  for (const filePath of files) {
+    const mod = await load(filePath)
+
+    // GET is a page route, POST/PUT/PATCH/DELETE are API routes.
+    const get = isStatorRoute(mod.GET) ? (mod.GET as RouteDefinition) : undefined
+    const post = isStatorApiRoute(mod.POST) ? (mod.POST as ApiRouteDefinition) : undefined
+    const put = isStatorApiRoute(mod.PUT) ? (mod.PUT as ApiRouteDefinition) : undefined
+    const patch = isStatorApiRoute(mod.PATCH) ? (mod.PATCH as ApiRouteDefinition) : undefined
+    const del = isStatorApiRoute(mod.DELETE) ? (mod.DELETE as ApiRouteDefinition) : undefined
+
+    if (!get && !post && !put && !patch && !del) continue
+
+    // Catch the easy mistake: GET defined with `defineApiRoute`, or a
+    // mutation method defined with `defineRoute`. Throw with a clear hint.
+    if (mod.GET && !get) {
+      throw new Error(
+        `stator: ${filePath} exports GET but it is not a defineRoute. ` +
+          `GET handlers must be created with defineRoute(); use defineApiRoute() for POST/PUT/PATCH/DELETE.`,
+      )
+    }
+    for (const m of ['POST', 'PUT', 'PATCH', 'DELETE'] as const) {
+      if (mod[m] && !isStatorApiRoute(mod[m])) {
+        throw new Error(
+          `stator: ${filePath} exports ${m} but it is not a defineApiRoute. ` +
+            `${m} handlers must be created with defineApiRoute(); defineRoute() is GET-only.`,
+        )
+      }
+    }
+
+    const { urlPath, paramNames } = filePathToRoute(absDir, filePath)
+    routes.push({
+      urlPath,
+      paramNames,
+      filePath,
+      GET: get,
+      POST: post,
+      PUT: put,
+      PATCH: patch,
+      DELETE: del,
+    })
+  }
+
+  return sortRoutes(mergeByUrlPath(routes))
+}
+
+/**
+ * Merge routes that resolve to the same URL pattern (e.g. `about.stator`
+ * contributing GET and `about.ts` contributing POST). Same method on two files
+ * for one URL is a hard error.
+ */
+function mergeByUrlPath(routes: DiscoveredRoute[]): DiscoveredRoute[] {
+  const byPath = new Map<string, DiscoveredRoute>()
+  for (const r of routes) {
+    const existing = byPath.get(r.urlPath)
+    if (!existing) {
+      byPath.set(r.urlPath, r)
+      continue
+    }
+    for (const m of HTTP_METHODS) {
+      if (r[m] === undefined) continue
+      if (existing[m] !== undefined) {
+        throw new Error(
+          `stator: two files define ${m} for "${r.urlPath}" ` +
+            `(${existing.filePath} and ${r.filePath}). A URL may have at most one handler per method.`,
+        )
+      }
+      ;(existing as unknown as Record<string, unknown>)[m] = r[m]
+    }
+  }
+  return [...byPath.values()]
+}
+
+/**
+ * Sort routes most-specific-first (Astro's model). At match time the first
+ * matcher that matches wins, so order encodes priority:
+ *   - routes without a rest/catch-all segment rank before those with one
+ *   - per segment, left to right: static (0) > named param (1) > rest (2)
+ *   - more segments before fewer
+ *   - ties alphabetically by urlPath
+ */
+export function sortRoutes(routes: DiscoveredRoute[]): DiscoveredRoute[] {
+  const kinds = (urlPath: string): number[] =>
+    urlPath
+      .split('/')
+      .filter(Boolean)
+      .map((seg) => (seg.startsWith('*') ? 2 : seg.startsWith(':') ? 1 : 0))
+
+  return [...routes].sort((a, b) => {
+    const ka = kinds(a.urlPath)
+    const kb = kinds(b.urlPath)
+    const aRest = ka.includes(2)
+    const bRest = kb.includes(2)
+    if (aRest !== bRest) return aRest ? 1 : -1 // no-rest first
+    const len = Math.min(ka.length, kb.length)
+    for (let i = 0; i < len; i++) {
+      if (ka[i] !== kb[i]) return ka[i]! - kb[i]! // lower kind = more specific
+    }
+    if (ka.length !== kb.length) return kb.length - ka.length // more segments first
+    return a.urlPath < b.urlPath ? -1 : a.urlPath > b.urlPath ? 1 : 0
+  })
+}
+
+async function walkRouteFiles(dir: string): Promise<string[]> {
+  const out: string[] = []
+  // A missing routes dir means "no routes yet", not an error.
+  const entries = await readdir(dir, { withFileTypes: true }).catch((e: NodeJS.ErrnoException) => {
+    if (e.code === 'ENOENT') return []
+    throw e
+  })
+  for (const e of entries) {
+    const full = resolve(dir, e.name)
+    if (e.isDirectory()) {
+      out.push(...(await walkRouteFiles(full)))
+      continue
+    }
+    if (!e.isFile()) continue
+    const ext = extname(e.name)
+    // `.stator` route pages compile (via the loader) to a module exporting GET;
+    // `.ts`/`.js` carry API handlers (and merge with a same-named page).
+    if (ext !== '.ts' && ext !== '.js' && ext !== '.stator') continue
+    out.push(full)
+  }
+  return out
+}
+
+/**
+ * Turn an absolute file path inside the routes dir into a `/foo/:bar` URL
+ * pattern plus the list of param names extracted from `[brackets]`.
+ */
+export function filePathToRoute(
+  absDir: string,
+  filePath: string,
+): { urlPath: string; paramNames: string[] } {
+  const ext = extname(filePath)
+  const rel = relative(absDir, filePath)
+  const dirSegments = dirname(rel)
+    .split(sep)
+    .filter((s) => s && s !== '.')
+  // Strip a residual `.stator` too: production builds compile route pages to
+  // sibling `<name>.stator.ts` files, which must map to the same URL as the
+  // `<name>.stator` source did in dev.
+  const fileBase = basename(rel, ext).replace(/\.stator$/, '')
+  const segments = fileBase === 'index' ? dirSegments : [...dirSegments, fileBase]
+
+  if (segments.length === 0) return { urlPath: '/', paramNames: [] }
+
+  const paramNames: string[] = []
+  const urlSegments = segments.map((seg) => {
+    // Rest / catch-all: `[...name]` → `*name` (matches zero or more segments).
+    const rest = seg.match(/^\[\.\.\.(.+)\]$/)
+    if (rest) {
+      const name = rest[1]!
+      paramNames.push(name)
+      return `*${name}`
+    }
+    const m = seg.match(/^\[(.+)\]$/)
+    if (m) {
+      const name = m[1]!
+      paramNames.push(name)
+      return `:${name}`
+    }
+    return seg
+  })
+
+  return { urlPath: `/${urlSegments.join('/')}`, paramNames }
+}

package/src/server/route-request.ts

@@ -0,0 +1,36 @@
+import type { Context } from 'hono'
+import type { RouteRequest } from './routing.ts'
+
+/**
+ * Wrap Hono's request into the framework's RouteRequest shape. The raw
+ * `Request` is exposed for escape hatches, plus a small layer of convenience
+ * (params + query) the framework already does at routing time.
+ */
+export function buildRouteRequest(c: Context, paramNames: string[]): RouteRequest {
+  const raw = c.req.raw
+  const params: Record<string, string> = {}
+  for (const name of paramNames) {
+    const v = c.req.param(name)
+    if (v !== undefined) params[name] = v
+  }
+  const query: Record<string, string | undefined> = c.req.query()
+
+  return {
+    raw,
+    params,
+    query,
+    get method() {
+      return raw.method
+    },
+    get url() {
+      return raw.url
+    },
+    get headers() {
+      return raw.headers
+    },
+    formData: () => raw.formData(),
+    json: <T = unknown>() => raw.json() as Promise<T>,
+    text: () => raw.text(),
+    arrayBuffer: () => raw.arrayBuffer(),
+  }
+}

package/src/server/routing.ts

@@ -0,0 +1,175 @@
+import type { HtmlFragment } from '../template/types.ts'
+import type { WireEnvelope } from '../wire/index.ts'
+import type { AnyMachineDef, EventOf } from './define-machine.ts'
+
+/** Machine context passed to a route's render function. Keyed by machine name. */
+export type RouteContext = Record<string, unknown>
+
+/**
+ * Request context for routes. Mostly delegates to the underlying `Request`
+ * via `raw`, plus convenience fields for the bits that need parsing the
+ * framework already does (path params, query strings).
+ *
+ * Same shape on `defineRoute` and `defineApiRoute`. GETs ignore body access,
+ * API routes use it.
+ */
+export interface RouteRequest {
+  /** The underlying Web Platform Request. Escape hatch for anything the
+   *  wrapper doesn't expose directly. */
+  raw: Request
+  /** Path params extracted from `[name]` segments. Always strings. */
+  params: Record<string, string>
+  /** Query string params from the URL. Repeated keys collapse to the
+   *  first value (Hono's default). */
+  query: Record<string, string | undefined>
+  /** HTTP method. Same as `raw.method`. */
+  readonly method: string
+  /** Full request URL. Same as `raw.url`. */
+  readonly url: string
+  /** Request headers. Same Headers instance as `raw.headers`. */
+  readonly headers: Headers
+  /** Parsed form body. Throws if the content type doesn't match. */
+  formData(): Promise<FormData>
+  /** Parsed JSON body. Throws on invalid JSON. */
+  json<T = unknown>(): Promise<T>
+  /** Raw text body. */
+  text(): Promise<string>
+  /** Raw binary body. */
+  arrayBuffer(): Promise<ArrayBuffer>
+}
+
+/** Options for `response.cookies.set`. */
+export interface RouteCookieOptions {
+  domain?: string
+  path?: string
+  expires?: Date
+  maxAge?: number
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'Strict' | 'Lax' | 'None'
+}
+
+/**
+ * Response side-effect surface for `defineRoute` render functions. Pages
+ * return their content (HtmlFragment) and influence response-level
+ * concerns by mutating this object. The framework combines the rendered
+ * HTML with whatever was set here to build the final HTTP response.
+ *
+ * `headers` is a real Web Platform `Headers` instance. `status` is a
+ * settable property. `cookies` is a focused helper because the cookie
+ * attribute model is enough of its own thing to deserve a dedicated API.
+ */
+export interface RouteResponseContext {
+  /** HTTP status code. Default 200. */
+  status: number
+  /** Response headers. Mutable; standard Headers API. */
+  readonly headers: Headers
+  /** Cookie helpers. Distinct from headers because cookie attributes
+   *  (HttpOnly, SameSite, etc.) deserve a focused API. */
+  readonly cookies: {
+    set(name: string, value: string, options?: RouteCookieOptions): void
+    delete(name: string, options?: Pick<RouteCookieOptions, 'path' | 'domain'>): void
+  }
+}
+
+/** Machine context for `defineRoute` includes the response side-effect
+ *  surface alongside the machine proxies. */
+export type RouteRenderContext = RouteContext & {
+  /** Reserved key. User machines named `response` would collide; reserved
+   *  in the discovery validator. */
+  response: RouteResponseContext
+}
+
+export interface RouteDefinition {
+  readonly __isStatorRoute: true
+  reads: AnyMachineDef[]
+  render: (ctx: RouteRenderContext, request: RouteRequest) => HtmlFragment
+  /** When true, the rendered page opens an SSE channel that receives
+   *  patches when any of the route's `reads:` machines change state — from
+   *  any session, not just the viewer's own POSTs. Opt-in: routes without
+   *  this flag operate purely on POST request/response. */
+  live: boolean
+}
+
+export interface DefineRouteConfig<TReads extends ReadonlyArray<AnyMachineDef>> {
+  reads: TReads
+  render: (ctx: RouteRenderContext, request: RouteRequest) => HtmlFragment
+  live?: boolean
+}
+
+export function defineRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
+  config: DefineRouteConfig<TReads>,
+): RouteDefinition {
+  return {
+    __isStatorRoute: true,
+    reads: [...config.reads],
+    render: config.render,
+    live: config.live ?? false,
+  }
+}
+
+export function isStatorRoute(v: unknown): v is RouteDefinition {
+  return (
+    typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isStatorRoute === true
+  )
+}
+
+/* ------------------------------------------------------------------ */
+/* API routes (defineApiRoute)                                         */
+/* ------------------------------------------------------------------ */
+
+export type { Directive } from '../wire/index.ts'
+
+/** Envelope shape API route handlers return when they want the framework
+ *  to synthesize an HTTP response. Returning a raw Response is also OK.
+ *  Same shape as the wire envelope the client receives. */
+export type ApiRouteEnvelope = WireEnvelope
+
+export type ApiRouteResult = Response | ApiRouteEnvelope
+
+/** Helpers available inside an API route handler. The framework provides
+ *  these; user handlers ignore the ones they don't need. */
+export interface ApiRouteHelpers {
+  /** Dispatch an event to a machine, addressed by the imported machine def
+   *  (not a magic string). The target name is read from `machine.name`; the
+   *  event is type-checked against that machine's declared event union.
+   *  Processes the event under the dispatch context, persists touched machines,
+   *  fires cross-machine subscriptions. The machine must be in the route's
+   *  loaded graph (its `reads`, transitively). */
+  dispatch: <D extends AnyMachineDef>(machine: D, event: EventOf<D>) => Promise<void>
+}
+
+export interface ApiRouteDefinition {
+  readonly __isStatorApiRoute: true
+  reads: AnyMachineDef[]
+  handler: (
+    request: RouteRequest,
+    helpers: ApiRouteHelpers,
+  ) => Promise<ApiRouteResult> | ApiRouteResult
+}
+
+export interface DefineApiRouteConfig<TReads extends ReadonlyArray<AnyMachineDef>> {
+  reads?: TReads
+  handler: (
+    request: RouteRequest,
+    helpers: ApiRouteHelpers,
+  ) => Promise<ApiRouteResult> | ApiRouteResult
+}
+
+export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
+  config: DefineApiRouteConfig<TReads>,
+): ApiRouteDefinition {
+  return {
+    __isStatorApiRoute: true,
+    reads: config.reads ? [...config.reads] : [],
+    handler: config.handler,
+  }
+}
+
+export function isStatorApiRoute(v: unknown): v is ApiRouteDefinition {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as Record<string, unknown>).__isStatorApiRoute === true
+  )
+}

package/src/server/session-lock.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-session async lock, shared by every state-mutating entry point —
+ * `POST /__events` (http.ts) and API-route handlers (api-route.ts).
+ *
+ * Serializes each session's load → mutate → persist cycle so concurrent
+ * mutations can't interleave and lose writes, *regardless of which path they
+ * arrive through*. The map must be process-wide and single: two entry points
+ * holding separate maps would each serialize against themselves but not
+ * against each other, letting an /__events POST and an API-route mutation on
+ * the same session race.
+ *
+ * GETs are read-only and do not acquire the lock.
+ */
+const sessionLocks = new Map<string, Promise<unknown>>()
+
+export function withSessionLock<T>(sid: string, fn: () => Promise<T>): Promise<T> {
+  const prev = sessionLocks.get(sid) ?? Promise.resolve()
+  const next = prev.then(fn, fn)
+  const settled = next.then(
+    () => undefined,
+    () => undefined,
+  )
+  sessionLocks.set(sid, settled)
+  void settled.then(() => {
+    if (sessionLocks.get(sid) === settled) sessionLocks.delete(sid)
+  })
+  return next
+}
+
+/** Number of sessions with an in-flight or queued mutation (test/observability). */
+export function activeSessionLockCount(): number {
+  return sessionLocks.size
+}