@statorjs/stator 1.0.0

package/src/server/recompute.ts

@@ -0,0 +1,287 @@
+import { renderBranchBody } from '../template/conditional.ts'
+import { coerceKeys, renderKeyedItem, renderListBody } from '../template/each.ts'
+import type { Patch } from '../wire/index.ts'
+import {
+  keyedScopePrefix,
+  keyToken,
+  type RenderState,
+  runInRender,
+  unregisterBindingsForScope,
+} from './render-context.ts'
+import type { SessionRuntime } from './session-runtime.ts'
+
+/** A patch paired with its source slot id — the slot in the binding tree
+ *  this patch came from. Used internally for scope-subsumption. The wire
+ *  shape drops this field. */
+type PendingPatch = { patch: Patch; sourceSlot: string }
+
+/**
+ * Walk every binding tied to `machineName`, re-evaluate its selector against
+ * the current machine snapshot, and produce patches for any binding whose
+ * value changed.
+ *
+ * Scope subsumption: when a list (`each`) or branch (`when`/`match`) body
+ * is replaced via an 'html' patch, the new body's HTML already contains the
+ * fresh values of every descendant binding. Any text/attr patches whose
+ * source slots live inside that scope are therefore redundant and would
+ * either no-op (descendant slot IDs no longer exist in the DOM) or, worse,
+ * target unrelated elements once finer-grained patches arrive. The filter
+ * at the bottom of this function drops them explicitly.
+ */
+export function recompute(
+  state: RenderState,
+  machineName: string,
+  runtime: SessionRuntime,
+): Patch[] {
+  const proxy = runtime.proxyFor(machineName)
+  if (!proxy) return []
+
+  const pending: PendingPatch[] = []
+  // Keyed-list scopes torn down this pass (removed rows) — any patch already
+  // emitted for a slot inside one targets DOM the remove op deletes.
+  const removedScopes: string[] = []
+  const slotIds = state.byMachine.get(machineName)
+  if (!slotIds) return []
+
+  for (const slotId of [...slotIds]) {
+    const binding = state.bindings.get(slotId)
+    if (!binding) continue
+
+    const newValue = binding.selector(proxy)
+
+    if (binding.kind === 'text') {
+      if (!valuesEqual(newValue, binding.lastValue)) {
+        pending.push({
+          patch: {
+            target: { kind: 'slot', id: slotId },
+            op: 'text',
+            value: stringify(newValue),
+          },
+          sourceSlot: slotId,
+        })
+        binding.lastValue = newValue
+      }
+    } else if (binding.kind === 'attr') {
+      if (!valuesEqual(newValue, binding.lastValue)) {
+        pending.push({
+          patch: {
+            target: { kind: 'element', id: binding.parentId },
+            op: 'attr',
+            name: binding.attrName,
+            value: attrWireValue(newValue),
+          },
+          sourceSlot: slotId,
+        })
+        binding.lastValue = newValue
+      }
+    } else if (binding.kind === 'list') {
+      const newArray = newValue as readonly unknown[]
+      const oldArray = binding.lastValue as readonly unknown[]
+      if (!arrayShallowEqual(newArray, oldArray)) {
+        const fn = binding.itemRenderer
+        const newInner = runInRender(state, () => renderListBody(state, slotId, newArray, fn))
+        pending.push({
+          patch: {
+            target: { kind: 'slot', id: slotId },
+            op: 'html',
+            value: newInner,
+          },
+          sourceSlot: slotId,
+        })
+        binding.lastValue = newArray
+      }
+    } else if (binding.kind === 'list-keyed') {
+      // Keyed diff: shape changes become per-item insert/remove/move ops from
+      // a replay simulation (`work` mirrors what the client's DOM will look
+      // like after each emitted op — see the wire contract). Content inside
+      // retained items updates through the items' own nested bindings; the
+      // keyed path never re-renders a retained row.
+      const newArray = newValue as readonly unknown[]
+      const newKeys = coerceKeys(newArray, binding.keyFn, slotId)
+      const oldKeys = binding.lastKeys
+      if (!stringArraysEqual(newKeys, oldKeys)) {
+        const target = { kind: 'slot', id: slotId } as const
+        const newKeySet = new Set(newKeys)
+        const work = [...oldKeys]
+        // Removals right-to-left so earlier indices stay valid within the pass.
+        for (let i = work.length - 1; i >= 0; i--) {
+          const key = work[i]!
+          if (newKeySet.has(key)) continue
+          pending.push({ patch: { target, op: 'remove', index: i }, sourceSlot: slotId })
+          const scope = keyedScopePrefix(slotId, keyToken(key))
+          removedScopes.push(`${scope}:`)
+          unregisterBindingsForScope(state, scope)
+          work.splice(i, 1)
+        }
+        // Settle each position left-to-right: an existing key moves up, a new
+        // key renders under its key scope and inserts.
+        for (let i = 0; i < newKeys.length; i++) {
+          const key = newKeys[i]!
+          if (work[i] === key) continue
+          const from = work.indexOf(key, i + 1)
+          if (from !== -1) {
+            pending.push({ patch: { target, op: 'move', from, to: i }, sourceSlot: slotId })
+            work.splice(from, 1)
+            work.splice(i, 0, key)
+          } else {
+            const itemHtml = runInRender(state, () =>
+              renderKeyedItem(state, slotId, newArray[i], i, key, binding.itemRenderer),
+            )
+            pending.push({
+              patch: { target, op: 'insert', index: i, value: itemHtml },
+              sourceSlot: slotId,
+            })
+            work.splice(i, 0, key)
+          }
+        }
+        binding.lastKeys = newKeys
+      }
+      binding.lastValue = newArray
+    } else if (binding.kind === 'branch') {
+      const newKey = binding.branchKeyFn(newValue)
+      if (!Object.is(newKey, binding.lastBranchKey)) {
+        const renderer = binding.branchRenderFn(newValue)
+        const newInner = runInRender(state, () => renderBranchBody(state, slotId, newKey, renderer))
+        pending.push({
+          patch: {
+            target: { kind: 'slot', id: slotId },
+            op: 'html',
+            value: newInner,
+          },
+          sourceSlot: slotId,
+        })
+        binding.lastBranchKey = newKey
+        binding.lastValue = newValue
+      }
+    }
+  }
+
+  return subsumeScopes(pending, removedScopes)
+}
+
+/** Positional string-array equality — the keyed diff's "did anything change". */
+function stringArraysEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+/**
+ * Drop any patch whose source slot is a descendant of an 'html'-op patch's
+ * scope, or of a keyed-list scope removed this pass. Descendants share the
+ * prefix `<scope-slot-id>:` per our slot-id scheme (see allocSlotId /
+ * pushListScope / pushKeyedScope in render-context.ts).
+ */
+function subsumeScopes(pending: PendingPatch[], removedScopes: string[]): Patch[] {
+  const scopePrefixes: string[] = [...removedScopes]
+  for (const p of pending) {
+    if (p.patch.op === 'html') scopePrefixes.push(`${p.sourceSlot}:`)
+  }
+  if (scopePrefixes.length === 0) return pending.map((p) => p.patch)
+
+  const out: Patch[] = []
+  for (const p of pending) {
+    let inside = false
+    for (const prefix of scopePrefixes) {
+      // The html patch itself isn't a descendant of its own scope — skip
+      // the exact match.
+      if (`${p.sourceSlot}:` === prefix) continue
+      if (p.sourceSlot.startsWith(prefix)) {
+        inside = true
+        break
+      }
+    }
+    if (!inside) out.push(p.patch)
+  }
+  return out
+}
+
+function valuesEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (a == null || b == null) return false
+  if (typeof a !== typeof b) return false
+  if (typeof a !== 'object') return false
+  return JSON.stringify(a) === JSON.stringify(b)
+}
+
+function arrayShallowEqual(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a === b) return true
+  if (!Array.isArray(a) || !Array.isArray(b)) return false
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}
+
+function stringify(v: unknown): string {
+  if (v == null) return ''
+  if (typeof v === 'string') return v
+  return String(v)
+}
+
+/** Baseline invalidation marker — never equal to any real value or key. */
+const NEVER_SYNCED = Symbol('stator.never-synced')
+
+/**
+ * Initial-sync patches for a freshly opened live connection.
+ *
+ * The connection's diff baseline is built by re-rendering the route AT
+ * CONNECT time, but the browser's DOM was rendered at page-GET time — and
+ * any state change in the gap (an effect settling during navigation is the
+ * classic case) would otherwise be permanently invisible: future diffs run
+ * against a baseline the DOM never received. This forces every binding to
+ * emit its CURRENT value once, so the DOM converges to the baseline; the
+ * patches are idempotent, so an already-fresh page just repaints in place.
+ *
+ * Keyed lists are reset wholesale (one `html` patch of freshly rendered
+ * rows) — positional insert/remove/move ops assume a known DOM row set,
+ * which is exactly what a possibly-stale page can't offer.
+ */
+export function initialSyncPatches(state: RenderState, runtime: SessionRuntime): Patch[] {
+  const patches: Patch[] = []
+
+  // Keyed lists first: re-render every row under its key scope (replacing
+  // the scope's binding registrations) and emit one wholesale reset.
+  for (const [slotId, binding] of [...state.bindings]) {
+    if (binding.kind !== 'list-keyed') continue
+    const items = (binding.lastValue ?? []) as readonly unknown[]
+    const keys = binding.lastKeys
+    for (const key of keys) {
+      unregisterBindingsForScope(state, keyedScopePrefix(slotId, keyToken(key)))
+    }
+    let rowsHtml = ''
+    for (let i = 0; i < items.length; i++) {
+      rowsHtml += runInRender(state, () =>
+        renderKeyedItem(state, slotId, items[i], i, keys[i]!, binding.itemRenderer),
+      )
+    }
+    patches.push({ target: { kind: 'slot', id: slotId }, op: 'html', value: rowsHtml })
+  }
+
+  // Everything else: invalidate baselines and let the normal recompute paths
+  // re-emit at current values (branch bodies re-render through the same code
+  // that handles real branch flips).
+  for (const binding of state.bindings.values()) {
+    if (binding.kind === 'text' || binding.kind === 'attr' || binding.kind === 'list') {
+      binding.lastValue = NEVER_SYNCED
+    } else if (binding.kind === 'branch') {
+      binding.lastBranchKey = NEVER_SYNCED
+    }
+  }
+  for (const machineName of state.byMachine.keys()) {
+    patches.push(...recompute(state, machineName, runtime))
+  }
+  return patches
+}
+
+/** Attr-binding wire semantics, mirroring the render side: false/null/
+ *  undefined → null (attribute removed), true → '' (present, empty),
+ *  anything else stringified. */
+function attrWireValue(v: unknown): string | null {
+  if (v === false || v === null || v === undefined) return null
+  if (v === true) return ''
+  return stringify(v)
+}

package/src/server/redis-store.ts

@@ -0,0 +1,116 @@
+import Redis, { type RedisOptions } from 'ioredis'
+import type { AppStore } from './app-store.ts'
+import type { Store } from './store.ts'
+
+/**
+ * Redis-backed Store. One hash per session, machine names as fields:
+ *
+ *   stator:session:<sid>          (hash)
+ *     CartMachine        → JSON snapshot
+ *     CheckoutMachine    → JSON snapshot
+ *
+ * TTL is per-session: HSET + EXPIRE are pipelined on every set, so the
+ * whole hash's expiry refreshes every time the user interacts with any of
+ * their machines. Idle sessions expire as a unit; active users never see
+ * a machine's state drop while other machines stay alive.
+ *
+ * Works with Upstash, Fly Redis, hosted Redis Cloud, or any redis:// /
+ * rediss:// URL — ioredis handles TLS automatically when the scheme is
+ * rediss://. Pass the URL directly or a fully-formed RedisOptions object.
+ */
+export class RedisStore implements Store {
+  private client: Redis
+  private keyPrefix: string
+
+  constructor(connection: string | RedisOptions, keyPrefix = 'stator:session') {
+    this.client = typeof connection === 'string' ? new Redis(connection) : new Redis(connection)
+    this.keyPrefix = keyPrefix
+  }
+
+  private key(sid: string): string {
+    return `${this.keyPrefix}:${sid}`
+  }
+
+  async get(sid: string, name: string): Promise<unknown | null> {
+    const raw = await this.client.hget(this.key(sid), name)
+    if (raw === null) return null
+    try {
+      return JSON.parse(raw)
+    } catch {
+      // Corrupted entry — treat as missing rather than crash. Logged
+      // upstream if the caller cares.
+      return null
+    }
+  }
+
+  async set(
+    sid: string,
+    name: string,
+    snapshot: unknown,
+    opts?: { ttlSeconds?: number },
+  ): Promise<void> {
+    const key = this.key(sid)
+    const payload = JSON.stringify(snapshot)
+    if (opts?.ttlSeconds) {
+      // Pipeline HSET + EXPIRE so the whole hash's TTL refreshes atomically.
+      // Any field write extends the session's idle window — see Store
+      // interface docs for the per-session TTL semantic.
+      await this.client.multi().hset(key, name, payload).expire(key, opts.ttlSeconds).exec()
+    } else {
+      await this.client.hset(key, name, payload)
+    }
+  }
+
+  async has(sid: string, name: string): Promise<boolean> {
+    return (await this.client.hexists(this.key(sid), name)) === 1
+  }
+
+  async deleteSession(sid: string): Promise<void> {
+    await this.client.del(this.key(sid))
+  }
+
+  /** Close the connection. Call on graceful shutdown. */
+  async close(): Promise<void> {
+    await this.client.quit()
+  }
+
+  /** Underlying ioredis client, exposed for health checks / introspection. */
+  get raw(): Redis {
+    return this.client
+  }
+}
+
+/**
+ * Redis-backed AppStore: one plain key per app machine name, JSON snapshot,
+ * NO TTL — app state is process-equivalent persistence (see app-store.ts).
+ * Single-writer assumption; multi-replica coordination is out of scope.
+ */
+export class RedisAppStore implements AppStore {
+  private client: Redis
+  private keyPrefix: string
+
+  constructor(connection: string | RedisOptions, keyPrefix = 'stator:app') {
+    this.client = typeof connection === 'string' ? new Redis(connection) : new Redis(connection)
+    this.keyPrefix = keyPrefix
+  }
+
+  async loadAppMachine(name: string): Promise<unknown | null> {
+    const raw = await this.client.get(`${this.keyPrefix}:${name}`)
+    if (raw === null) return null
+    try {
+      return JSON.parse(raw)
+    } catch {
+      // Corrupted blob — treat as missing; the boot path logs and starts fresh.
+      return null
+    }
+  }
+
+  async saveAppMachine(name: string, snapshot: unknown): Promise<void> {
+    await this.client.set(`${this.keyPrefix}:${name}`, JSON.stringify(snapshot))
+  }
+
+  /** Close the connection. Call on graceful shutdown. */
+  async close(): Promise<void> {
+    await this.client.quit()
+  }
+}

package/src/server/render-context.ts

@@ -0,0 +1,228 @@
+import type { HtmlFragment } from '../template/types.ts'
+
+export type SlotId = string
+export type MachineName = string
+export type SessionId = string
+export type ElementId = string
+
+export type BindingKind = Binding['kind']
+
+/** A binding-stored selector with its instance type erased. `any` (not
+ *  `unknown`) is deliberate: parameters are contravariant, so a concrete
+ *  `(instance: CartProxy) => T` is only assignable into an `any`-typed slot. */
+// biome-ignore lint/suspicious/noExplicitAny: contravariant parameter — see doc comment
+export type ErasedSelector = (instance: any) => unknown
+
+/** A list binding's per-item renderer, item type erased (same variance argument). */
+// biome-ignore lint/suspicious/noExplicitAny: contravariant parameter — see doc comment
+export type ErasedItemRenderer = (item: any, index: number) => HtmlFragment
+
+interface BindingBase {
+  slotId: SlotId
+  machineName: MachineName
+  selector: ErasedSelector
+  lastValue: unknown
+}
+
+export interface TextBinding extends BindingBase {
+  kind: 'text'
+}
+
+export interface AttrBinding extends BindingBase {
+  kind: 'attr'
+  attrName: string
+  parentId: ElementId
+}
+
+export interface ListBinding extends BindingBase {
+  kind: 'list'
+  /** Re-invoked per item when the list re-renders. */
+  itemRenderer: ErasedItemRenderer
+}
+
+/** A keyed list's key selector, item type erased (same variance argument as
+ *  ErasedSelector). */
+// biome-ignore lint/suspicious/noExplicitAny: contravariant parameter — see ErasedSelector
+export type ErasedKeyFn = (item: any) => unknown
+
+export interface KeyedListBinding extends BindingBase {
+  kind: 'list-keyed'
+  /** Re-invoked per item for inserts and initial render. */
+  itemRenderer: ErasedItemRenderer
+  /** Derives each item's identity key (validated to string | number). */
+  keyFn: ErasedKeyFn
+  /** The previous render's keys, in order — the diff baseline. */
+  lastKeys: string[]
+}
+
+export interface BranchBinding extends BindingBase {
+  kind: 'branch'
+  /** The selector value reduced to a stable key — re-render only fires when
+   *  the key changes (so `when` doesn't re-render on every truthy-to-truthy
+   *  value transition). */
+  branchKeyFn: (value: unknown) => unknown
+  /** Returns the renderer for a given selector value, or null when nothing
+   *  should be rendered. */
+  branchRenderFn: (value: unknown) => (() => HtmlFragment) | null
+  /** The last computed key — distinct from lastValue, which holds the raw
+   *  selector result. */
+  lastBranchKey: unknown
+}
+
+/** Discriminated on `kind`, so per-kind fields are required where they apply —
+ *  recompute narrows on the discriminant instead of asserting optionals. */
+export type Binding = TextBinding | AttrBinding | ListBinding | KeyedListBinding | BranchBinding
+
+interface Scope {
+  prefix: string
+  counter: number
+}
+
+export interface RenderState {
+  sessionId: SessionId
+  routeKey: string
+  bindings: Map<SlotId, Binding>
+  byMachine: Map<MachineName, Set<SlotId>>
+  scopeStack: Scope[]
+  elementIdCounter: number
+}
+
+export function createRenderState(sessionId: SessionId, routeKey: string): RenderState {
+  return {
+    sessionId,
+    routeKey,
+    bindings: new Map(),
+    byMachine: new Map(),
+    scopeStack: [{ prefix: '', counter: 0 }],
+    elementIdCounter: 0,
+  }
+}
+
+let currentRenderState: RenderState | null = null
+
+export function getCurrentRenderState(): RenderState | null {
+  return currentRenderState
+}
+
+export function requireCurrentRenderState(): RenderState {
+  if (!currentRenderState) {
+    throw new Error('stator: must be called during a template render (inside runInRender)')
+  }
+  return currentRenderState
+}
+
+export function runInRender<T>(state: RenderState, fn: () => T): T {
+  const prev = currentRenderState
+  currentRenderState = state
+  try {
+    return fn()
+  } finally {
+    currentRenderState = prev
+  }
+}
+
+function topScope(state: RenderState): Scope {
+  const s = state.scopeStack[state.scopeStack.length - 1]
+  if (!s) throw new Error('stator: render scope stack is empty')
+  return s
+}
+
+export function allocSlotId(state: RenderState): SlotId {
+  const scope = topScope(state)
+  const id = `${scope.prefix ? `${scope.prefix}:` : ''}s${scope.counter++}`
+  return id
+}
+
+export function allocElementId(state: RenderState): ElementId {
+  return `e${state.elementIdCounter++}`
+}
+
+export function pushListScope(state: RenderState, listSlotId: SlotId, iterIndex: number): void {
+  state.scopeStack.push({ prefix: `${listSlotId}:i${iterIndex}`, counter: 0 })
+}
+
+/**
+ * Keyed-list scope: descendant slot ids are derived from the item's *key*, not
+ * its position — so a row's inner slot ids survive reordering, and a patch can
+ * address "the row for p1, wherever it is now". This is the item-identity
+ * primitive keyed `each` is built on.
+ */
+export function pushKeyedScope(state: RenderState, listSlotId: SlotId, token: string): void {
+  state.scopeStack.push({ prefix: `${listSlotId}:k${token}`, counter: 0 })
+}
+
+/** Keyed scope prefix for a key token (shared by render and recompute). */
+export function keyedScopePrefix(listSlotId: SlotId, token: string): string {
+  return `${listSlotId}:k${token}`
+}
+
+/**
+ * Encode an item key into a slot-id-safe token. Injective: only `[A-Za-z0-9-]`
+ * pass through (NOT `_`, which is the escape character); everything else
+ * becomes `_<codepoint hex>`. Keys land in `data-slot` attributes and CSS
+ * attribute selectors, so the charset must be quote- and bracket-free.
+ */
+export function keyToken(key: string): string {
+  return key.replace(/[^A-Za-z0-9-]/gu, (c) => `_${c.codePointAt(0)!.toString(16)}`)
+}
+
+export function popListScope(state: RenderState): void {
+  if (state.scopeStack.length <= 1) {
+    throw new Error('stator: cannot pop root render scope')
+  }
+  state.scopeStack.pop()
+}
+
+export function registerBinding(state: RenderState, binding: Binding): void {
+  state.bindings.set(binding.slotId, binding)
+  let slotIds = state.byMachine.get(binding.machineName)
+  if (!slotIds) {
+    slotIds = new Set()
+    state.byMachine.set(binding.machineName, slotIds)
+  }
+  slotIds.add(binding.slotId)
+}
+
+/**
+ * Remove every binding whose slot id is a *descendant* of the given scope prefix
+ * (i.e. starts with `prefix:`). The prefix itself is not removed — useful when
+ * re-rendering a list whose own list-binding must persist.
+ */
+export function unregisterBindingsForScope(state: RenderState, scopePrefix: string): void {
+  const toRemove: SlotId[] = []
+  for (const slotId of state.bindings.keys()) {
+    if (slotId.startsWith(`${scopePrefix}:`)) {
+      toRemove.push(slotId)
+    }
+  }
+  for (const slotId of toRemove) {
+    const b = state.bindings.get(slotId)!
+    state.bindings.delete(slotId)
+    const slotIds = state.byMachine.get(b.machineName)
+    if (slotIds) {
+      slotIds.delete(slotId)
+      if (slotIds.size === 0) state.byMachine.delete(b.machineName)
+    }
+  }
+}
+
+export type EventDescriptor = {
+  readonly __isEventDescriptor: true
+  machine: string
+  event: { type: string; [k: string]: unknown }
+}
+
+export function createEventDescriptor(
+  machine: string,
+  event: { type: string; [k: string]: unknown },
+): EventDescriptor {
+  return { __isEventDescriptor: true, machine, event }
+}
+
+export function isEventDescriptor(v: unknown): v is EventDescriptor {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as Record<string, unknown>).__isEventDescriptor === true
+  )
+}