npm - @statorjs/stator - Versions diffs - 1.0.0 - Mend

@statorjs/stator 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/LICENSE +21 -0
package/README.md +104 -0
package/package.json +99 -0
package/src/build/build.ts +244 -0
package/src/build/head.ts +43 -0
package/src/build/index.ts +10 -0
package/src/build/sync.ts +65 -0
package/src/client/bind.ts +47 -0
package/src/client/client-id.ts +10 -0
package/src/client/dispatch.ts +62 -0
package/src/client/element.ts +156 -0
package/src/client/index.ts +13 -0
package/src/client/inspector.ts +237 -0
package/src/client/machine.ts +39 -0
package/src/client/runtime.ts +246 -0
package/src/client/use.ts +119 -0
package/src/compiler/client-emit.ts +180 -0
package/src/compiler/client-script.ts +256 -0
package/src/compiler/compile.ts +459 -0
package/src/compiler/diagnostics.ts +65 -0
package/src/compiler/dts.ts +87 -0
package/src/compiler/hash.ts +8 -0
package/src/compiler/index.ts +48 -0
package/src/compiler/lower.ts +0 -0
package/src/compiler/regions.ts +79 -0
package/src/compiler/split.ts +168 -0
package/src/compiler/styles.ts +200 -0
package/src/compiler/virtual-code.ts +184 -0
package/src/components/index.ts +2 -0
package/src/components/json-ld.ts +85 -0
package/src/engine/actor.ts +248 -0
package/src/engine/define-machine.ts +113 -0
package/src/engine/index.ts +37 -0
package/src/engine/types.ts +236 -0
package/src/server/api-route.ts +149 -0
package/src/server/app-dispatch.ts +52 -0
package/src/server/app-store.ts +35 -0
package/src/server/cached-store.ts +117 -0
package/src/server/create-app.ts +83 -0
package/src/server/define-machine.ts +10 -0
package/src/server/dev.ts +255 -0
package/src/server/discovery.ts +111 -0
package/src/server/dispatch-context.ts +39 -0
package/src/server/effects.ts +120 -0
package/src/server/http.ts +475 -0
package/src/server/index.ts +101 -0
package/src/server/instance-proxy.ts +95 -0
package/src/server/logger.ts +52 -0
package/src/server/machine-store.ts +355 -0
package/src/server/reads-helpers.ts +40 -0
package/src/server/recompute.ts +287 -0
package/src/server/redis-store.ts +116 -0
package/src/server/render-context.ts +228 -0
package/src/server/render.ts +111 -0
package/src/server/route-discovery.ts +226 -0
package/src/server/route-request.ts +36 -0
package/src/server/routing.ts +175 -0
package/src/server/session-lock.ts +33 -0
package/src/server/session-runtime.ts +242 -0
package/src/server/session.ts +29 -0
package/src/server/sse.ts +175 -0
package/src/server/store.ts +95 -0
package/src/stator-modules.d.ts +12 -0
package/src/template/client-shell.ts +65 -0
package/src/template/conditional.ts +166 -0
package/src/template/directives/core.ts +58 -0
package/src/template/directives/list-attr.ts +183 -0
package/src/template/directives/on.ts +22 -0
package/src/template/each.ts +295 -0
package/src/template/html.ts +180 -0
package/src/template/index.ts +29 -0
package/src/template/parser.ts +341 -0
package/src/template/read.ts +50 -0
package/src/template/types.ts +33 -0
package/src/vite/index.ts +6 -0
package/src/vite/plugin.ts +151 -0
package/src/vite/stub.ts +79 -0
package/src/wire/apply.ts +103 -0
package/src/wire/index.ts +67 -0

package/src/server/dev.ts ADDED Viewed

@@ -0,0 +1,255 @@
+import { readFile } from 'node:fs/promises'
+import { createServer as createHttpServer } from 'node:http'
+import { relative, resolve } from 'node:path'
+import { getRequestListener } from '@hono/node-server'
+import type { Hono } from 'hono'
+import { createServer as createViteServer, type ViteDevServer } from 'vite'
+import { compile } from '../compiler/index.ts'
+import { machineStub, stator } from '../vite/index.ts'
+import type { AppStore } from './app-store.ts'
+import { logger } from './logger.ts'
+import type { MachineStore } from './machine-store.ts'
+import type { DiscoveredRoute } from './route-discovery.ts'
+import type { Store } from './store.ts'
+/**
+ * Dev server: embeds Vite in middleware mode so `.stator` (and TS) modules are
+ * compiled on the way in, loads machines + routes through `vite.ssrLoadModule`,
+ * and injects each route's scoped component CSS into `<head>` at render time
+ * (SSR head injection — independent of the client JS bundle).
+ *
+ * Critically, the framework runtime itself is loaded *through Vite*
+ * (`ssrLoadModule('@statorjs/stator/server')`), not imported natively — so the
+ * render-context, machine defs, routes, and templates all share one module
+ * instance. Importing the runtime natively here would create a second instance
+ * whose render-context doesn't match the one the templates resolve against, and
+ * `read()` would throw. (This mirrors how Astro/SvelteKit run SSR through Vite.)
+ *
+ * The production serve path (pre-built assets + manifest, no Vite) is a separate
+ * follow-up; this is the dev half of Phase 3a.
+ */
+export interface DevAppConfig {
+  /** Vite root — the app directory (must reach node_modules for resolution). */
+  root: string
+  machinesDir: string
+  routesDir: string
+  staticDir?: string
+  store?: Store
+  /** Persistence for `persist: true` app machines. Defaults to in-memory. */
+  appStore?: AppStore
+  sessionTtlSeconds?: number
+  /** Auto-inject the dev inspector toolbar. On by default; set false to disable. */
+  inspector?: boolean
+}
+export interface DevApp {
+  fetch: (request: Request) => Response | Promise<Response>
+  vite: ViteDevServer
+  listen: (port: number) => Promise<void>
+  close: () => Promise<void>
+}
+export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
+  const vite = await createViteServer({
+    root: resolve(config.root),
+    appType: 'custom',
+    server: { middlewareMode: true },
+    // machineStub keeps server machines out of browser module graphs: island
+    // imports of a machine resolve to a `{ name }` stub (SSR loads are
+    // untouched — `options.ssr` gates it).
+    plugins: [stator(), machineStub({ machinesDir: resolve(config.machinesDir) })],
+    // The framework's own source is TS that Vite must transform, not externalize.
+    ssr: { noExternal: [/@statorjs\/stator/] },
+    logLevel: 'warn',
+  })
+  // Load the runtime through Vite so it shares an instance with the templates.
+  // (Type-only: the static import type is erased, so no second instance.)
+  const runtime = (await vite.ssrLoadModule(
+    '@statorjs/stator/server',
+  )) as typeof import('./index.ts')
+  const loader = (file: string) => vite.ssrLoadModule(file) as Promise<Record<string, unknown>>
+  const root = resolve(config.root)
+  const machinesDir = resolve(config.machinesDir)
+  const routesDir = resolve(config.routesDir)
+  const inspectorOn = config.inspector ?? true
+  const resultCache = new Map<string, ReturnType<typeof compile>>()
+  const compiledFor = async (file: string) => {
+    let r = resultCache.get(file)
+    if (r === undefined) {
+      // Match the plugin's kind detection so route-page frontmatter
+      // (Stator.reads etc.) compiles under the route capability set.
+      const kind = /[\\/]routes[\\/].*\.stator$/.test(file) ? 'route' : 'component'
+      r = compile(await readFile(file, 'utf8'), { id: file, kind })
+      resultCache.set(file, r)
+    }
+    return r
+  }
+  const headExtras = async (routeFile: string) => {
+    const files = reachableStatorFiles(vite, routeFile)
+    let css = ''
+    const scripts: string[] = []
+    for (const f of files) {
+      const r = await compiledFor(f)
+      if (r.css) css += `/* ${f} */\n${r.css}\n`
+      if (r.isClient) {
+        // Vite's transform middleware compiles this URL because browsers send
+        // `Sec-Fetch-Dest: script` for module scripts (the `.stator` extension
+        // alone wouldn't match its JS-request check). curl-style probes must
+        // send that header or they'll see raw source and cry wolf.
+        const url = `/${relative(root, f).replace(/\\/g, '/')}?stator&type=client`
+        scripts.push(`<script type="module" src="${url}"></script>`)
+      }
+    }
+    const head: string[] = []
+    // Vite's HMR client — pages are rendered by Hono, not Vite's
+    // transformIndexHtml, so it isn't injected for us. Without it the browser
+    // has no socket to receive the full-reload signal on a source change.
+    head.push('<script type="module" src="/@vite/client"></script>')
+    // The dev inspector toolbar (off in production — only the dev server injects it).
+    if (inspectorOn) head.push('<script src="/@stator/inspector.js" defer></script>')
+    if (css.trim()) head.push(`<style data-stator-dev>\n${css.trim()}\n</style>`)
+    head.push(...scripts)
+    return head.join('\n')
+  }
+  // The app graph is rebuilt on a source change so edits don't need a restart.
+  let store: MachineStore
+  let routes: DiscoveredRoute[] = []
+  let machineCount = 0
+  let app: Hono
+  const rebuildStore = async (): Promise<void> => {
+    const { defs } = await runtime.discoverMachines(machinesDir, loader)
+    machineCount = defs.length
+    store = new runtime.MachineStore(defs, config.store ?? new runtime.InMemoryStore(), {
+      sessionTtlSeconds: config.sessionTtlSeconds,
+      appStore: config.appStore,
+    })
+    await store.bootAppMachines()
+    runtime.wireAppEffects(store)
+  }
+  const rebuildRoutes = async (): Promise<void> => {
+    routes = await runtime.discoverRoutes(routesDir, loader)
+  }
+  const rebuildServer = async (): Promise<void> => {
+    app = await runtime.buildHonoApp({
+      routes,
+      store,
+      staticDir: config.staticDir,
+      headExtras,
+      inspector: inspectorOn,
+    })
+  }
+  await rebuildStore()
+  await rebuildRoutes()
+  await rebuildServer()
+  // Live reload: on a relevant source change, re-discover and rebuild the app,
+  // then tell the browser to reload. A template/route edit keeps the store (and
+  // your session — cart contents and all) intact; only a machine edit resets it,
+  // since route `reads:` bind to machine defs by identity and must re-bind as a
+  // set. Rebuilds are serialized so overlapping saves can't race.
+  const isAppFile = (file: string): boolean => {
+    if (!/\.(stator|ts|js)$/.test(file)) return false
+    if (file.includes('/node_modules/') || file.includes('/dist/')) return false
+    if (file.startsWith(machinesDir) || file.startsWith(routesDir)) return true
+    return (vite.moduleGraph.getModulesByFile(file)?.size ?? 0) > 0
+  }
+  let reloadChain: Promise<void> = Promise.resolve()
+  const onChange = (file: string): void => {
+    const abs = resolve(file)
+    if (!isAppFile(abs)) return
+    reloadChain = reloadChain.then(async () => {
+      invalidateModuleTree(vite, abs)
+      resultCache.delete(abs)
+      try {
+        if (abs.startsWith(machinesDir)) await rebuildStore()
+        await rebuildRoutes()
+        await rebuildServer()
+        vite.ws.send({ type: 'full-reload' })
+        logger.info({ file: relative(root, abs) }, 'reloaded')
+      } catch (err) {
+        logger.error({ err: (err as Error).message, file: relative(root, abs) }, 'reload failed')
+      }
+    })
+  }
+  vite.watcher.on('change', onChange)
+  vite.watcher.on('add', onChange)
+  vite.watcher.on('unlink', onChange)
+  return {
+    fetch: (request) => app.fetch(request),
+    vite,
+    listen(port: number): Promise<void> {
+      // Vite's middlewares serve client modules + HMR to the browser; anything
+      // it doesn't handle (routes, /__events, /__sse) falls through to Hono.
+      // The arrow re-reads `app` each request so a rebuild swaps in seamlessly.
+      const honoListener = getRequestListener((req) => app.fetch(req))
+      const server = createHttpServer((req, res) => {
+        vite.middlewares(req, res, () => honoListener(req, res))
+      })
+      return new Promise((resolveFn) => {
+        server.listen(port, () => {
+          logger.info(
+            {
+              port,
+              mode: 'dev',
+              machines: machineCount,
+              routes: routes.length,
+            },
+            'listening',
+          )
+          resolveFn()
+        })
+      })
+    },
+    close: () => vite.close(),
+  }
+}
+/** Invalidate a changed file and everything that (transitively) imports it, so
+ *  the next `ssrLoadModule` re-executes them with fresh code. */
+function invalidateModuleTree(vite: ViteDevServer, file: string): void {
+  const seen = new Set<unknown>()
+  const stack: Array<{ importers: Set<unknown> }> = [
+    ...((vite.moduleGraph.getModulesByFile(file) ?? []) as Set<never>),
+  ]
+  while (stack.length) {
+    const mod = stack.pop()
+    if (!mod || seen.has(mod)) continue
+    seen.add(mod)
+    vite.moduleGraph.invalidateModule(mod as never)
+    for (const imp of mod.importers) stack.push(imp as never)
+  }
+}
+/**
+ * Walk the SSR module graph from a route's file and return every `.stator` file
+ * reachable from it (route page + the components it renders). The caller compiles
+ * each to collect scoped CSS and client-component module scripts.
+ */
+function reachableStatorFiles(vite: ViteDevServer, entryFile: string): string[] {
+  const seen = new Set<string>()
+  const statorFiles = new Set<string>()
+  const visit = (node: { id: string | null; importedModules: Set<unknown> } | undefined): void => {
+    if (!node) return
+    const id = node.id ?? ''
+    if (seen.has(id)) return
+    seen.add(id)
+    const file = id.split('?')[0]!
+    if (/\.stator$/.test(file)) statorFiles.add(file)
+    for (const dep of node.importedModules) visit(dep as never)
+  }
+  for (const node of vite.moduleGraph.getModulesByFile(entryFile) ?? []) {
+    visit(node as never)
+  }
+  return [...statorFiles]
+}

package/src/server/discovery.ts ADDED Viewed

@@ -0,0 +1,111 @@
+import { readdir } from 'node:fs/promises'
+import { extname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { type AnyMachineDef, isStatorMachine } from './define-machine.ts'
+export interface DiscoveryResult {
+  defs: AnyMachineDef[]
+}
+/** How a discovered file is turned into a module. Defaults to native dynamic
+ *  import; the dev server injects Vite's `ssrLoadModule` so `.stator` imports
+ *  (and TS) are compiled on the way in. */
+export type ModuleLoader = (file: string) => Promise<Record<string, unknown>>
+const nativeLoader: ModuleLoader = (file) => import(/* @vite-ignore */ pathToFileURL(file).href)
+export async function discoverMachines(
+  dir: string,
+  load: ModuleLoader = nativeLoader,
+): Promise<DiscoveryResult> {
+  const absDir = resolve(dir)
+  // A missing conventional dir means "no machines yet" (e.g. early in a fresh
+  // project), not an error. A *present* file that isn't a machine still throws
+  // below — that's a real mistake, not an absence.
+  const entries = await readdir(absDir, { withFileTypes: true }).catch(
+    (e: NodeJS.ErrnoException) => {
+      if (e.code === 'ENOENT') return []
+      throw e
+    },
+  )
+  const files: string[] = []
+  for (const e of entries) {
+    if (e.isFile() && (extname(e.name) === '.ts' || extname(e.name) === '.js')) {
+      files.push(resolve(absDir, e.name))
+    }
+  }
+  const defs: AnyMachineDef[] = []
+  const seenNames = new Set<string>()
+  for (const file of files) {
+    const mod = await load(file)
+    const def = mod.default
+    if (!isStatorMachine(def)) {
+      throw new Error(
+        `stator: ${file} default export is not a stator machine. ` +
+          `Did you forget to call defineMachine()?`,
+      )
+    }
+    if (seenNames.has(def.name)) {
+      throw new Error(`stator: duplicate machine name "${def.name}" in ${file}`)
+    }
+    seenNames.add(def.name)
+    defs.push(def)
+  }
+  validateReads(defs, absDir)
+  return { defs: topoSort(defs) }
+}
+function validateReads(defs: AnyMachineDef[], dir: string): void {
+  const byName = new Map(defs.map((d) => [d.name, d]))
+  for (const def of defs) {
+    for (const dep of def.reads) {
+      if (!byName.has(dep.name)) {
+        throw new Error(
+          `stator: machine "${def.name}" reads from "${dep.name}", which was not ` +
+            `discovered in ${dir}. Both must live in the machines directory.`,
+        )
+      }
+      if (def.lifecycle === 'app' && dep.lifecycle === 'session') {
+        throw new Error(
+          `stator: app-lifecycle machine "${def.name}" cannot read session-lifecycle ` +
+            `machine "${dep.name}". App machines exist before any session.`,
+        )
+      }
+    }
+  }
+}
+function topoSort(defs: AnyMachineDef[]): AnyMachineDef[] {
+  const sorted: AnyMachineDef[] = []
+  const WHITE = 0
+  const GRAY = 1
+  const BLACK = 2
+  const color = new Map<AnyMachineDef, number>()
+  for (const d of defs) color.set(d, WHITE)
+  const path: AnyMachineDef[] = []
+  const visit = (def: AnyMachineDef): void => {
+    const c = color.get(def) ?? WHITE
+    if (c === BLACK) return
+    if (c === GRAY) {
+      const startIdx = path.indexOf(def)
+      const cycle = [...path.slice(startIdx), def].map((d) => d.name).join(' -> ')
+      throw new Error(`stator: dependency cycle detected: ${cycle}`)
+    }
+    color.set(def, GRAY)
+    path.push(def)
+    for (const dep of def.reads) visit(dep)
+    path.pop()
+    color.set(def, BLACK)
+    sorted.push(def)
+  }
+  for (const def of defs) visit(def)
+  return sorted
+}

package/src/server/dispatch-context.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import type { SessionRuntime } from './session-runtime.ts'
+/**
+ * The slice of runtime context an action or guard needs while a single
+ * event is being processed:
+ *   - `runtime` so it can resolve `reads:` proxies on demand (both session
+ *     and app-scoped) via the active SessionRuntime
+ *   - `touched` for cross-machine subscription listeners to record which
+ *     machines need recomputed patches after the event settles
+ *
+ * Populated by `SessionRuntime.processEvent`. A single dispatch may fan
+ * out through subscription listeners that synchronously call
+ * `actor.send` on other machines; all of those nested calls share this
+ * same context, so actions running in any of them see the same runtime.
+ */
+export interface DispatchContext {
+  runtime: SessionRuntime
+  touched: Set<string>
+}
+let current: DispatchContext | null = null
+export function getDispatchContext(): DispatchContext | null {
+  return current
+}
+export function withDispatchContext<T>(ctx: DispatchContext, fn: () => T): T {
+  const prev = current
+  current = ctx
+  try {
+    return fn()
+  } finally {
+    current = prev
+  }
+}
+export function recordTouch(machineName: string): void {
+  if (current) current.touched.add(machineName)
+}

package/src/server/effects.ts ADDED Viewed

@@ -0,0 +1,120 @@
+import type { AnyMachineDef, EffectInvocation } from '../engine/index.ts'
+import { dispatchToApp } from './app-dispatch.ts'
+import { scopedLogger } from './logger.ts'
+import type { MachineStore } from './machine-store.ts'
+import { withSessionLock } from './session-lock.ts'
+import { SessionRuntime } from './session-runtime.ts'
+import { fanOut } from './sse.ts'
+const effectLog = scopedLogger('effect')
+/**
+ * Install the APP-plane effect scheduler on a MachineStore (injected
+ * post-construction — see MachineStore.setAppEffectScheduler). App
+ * completions are simpler than session ones: the actor is long-lived and
+ * in-process, so the completion goes through `dispatchToApp` — atomic send,
+ * persist opted-in machines, fan out. No lock involved.
+ *
+ * `createApp` and the dev server call this; a hand-rolled server that
+ * constructs MachineStore directly should too.
+ */
+export function wireAppEffects(store: MachineStore): void {
+  store.setAppEffectScheduler((invocation) => {
+    void runAppEffect(invocation, store)
+  })
+}
+async function runAppEffect(invocation: EffectInvocation, store: MachineStore): Promise<void> {
+  const { machineName, effectId } = invocation
+  let completion: Awaited<ReturnType<EffectInvocation['run']>>
+  try {
+    completion = await invocation.run()
+  } catch (err) {
+    effectLog.error(
+      { machine: machineName, effectId, err: String(err) },
+      'effect threw — effects must catch and return their failure event; dropped',
+    )
+    return
+  }
+  if (!completion) return
+  try {
+    const def = store.getDef(machineName)
+    if (!def) return // graph changed under us (dev reload) — drop
+    await dispatchToApp(store, def as AnyMachineDef, completion as never)
+  } catch (err) {
+    effectLog.error(
+      { machine: machineName, effectId, err: String(err) },
+      'effect completion dispatch failed',
+    )
+  }
+}
+/**
+ * Server-plane effect scheduling for SESSION machines.
+ *
+ * The session runtime queues invocations during `processEvent` (the actor's
+ * `onEffect` hook); an entry point (POST /__events, API route) calls
+ * `scheduleSessionEffects` after it has persisted — the effect's I/O then runs
+ * with **no session lock held**. The completion event re-enters through the
+ * full event path: fresh lock, fresh runtime hydrate (the triggering actor is
+ * long gone — the transient-actor model working for us), process, persist,
+ * fan out to live SSE connections. Non-live pages simply see the new state on
+ * their next request.
+ *
+ * At-most-once, non-durable (1.0 contract): a crash between commit and
+ * completion loses the effect; the machine stays in its pending state.
+ */
+export function scheduleSessionEffects(
+  runtime: SessionRuntime,
+  store: MachineStore,
+  sessionId: string,
+): void {
+  for (const invocation of runtime.drainPendingEffects()) {
+    void runSessionEffect(invocation, store, sessionId)
+  }
+}
+async function runSessionEffect(
+  invocation: EffectInvocation,
+  store: MachineStore,
+  sessionId: string,
+): Promise<void> {
+  const { machineName, effectId } = invocation
+  let completion: Awaited<ReturnType<EffectInvocation['run']>>
+  try {
+    completion = await invocation.run()
+  } catch (err) {
+    // Backstop only — the type contract asks effects to catch and return
+    // their failure event. Never crashes the host.
+    effectLog.error(
+      { machine: machineName, effectId, err: String(err) },
+      'effect threw — effects must catch and return their failure event; dropped',
+    )
+    return
+  }
+  if (!completion) return
+  try {
+    await withSessionLock(sessionId, async () => {
+      const runtime = new SessionRuntime(sessionId, store)
+      try {
+        const def = store.getDef(machineName)
+        if (!def) return // machine graph changed under us (dev reload) — drop
+        // loadGraph pulls reads + subscribers transitively, so completion
+        // emits reach cross-machine listeners like any other event.
+        await runtime.loadGraph([def])
+        runtime.wireSubscriptions()
+        const touched = runtime.processEvent(machineName, completion)
+        await runtime.persistTouched(touched)
+        await fanOut(touched, { sessionId })
+      } finally {
+        runtime.dispose()
+      }
+    })
+  } catch (err) {
+    effectLog.error(
+      { machine: machineName, effectId, err: String(err) },
+      'effect completion dispatch failed',
+    )
+  }
+}