@statorjs/stator 1.2.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,7 +88,7 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.2.2"
+    "@statorjs/stator": "1.3.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/engine/actor.ts

@@ -63,6 +63,13 @@ export interface CreateActorOptions<C> {
    *  they take events straight from the untrusted wire (`/__events`), where a
    *  `@set` would be an arbitrary-context-write that bypasses every guard. */
   internalEvents?: boolean
+  /** Host hook: a state was ENTERED (fresh start or a value-changing transition —
+   *  never hydration). The server uses it to arm `after` timers from the state's
+   *  config; `ctx` is the current context (for context-dependent delays). */
+  onStateEnter?: (stateKey: string, ctx: C) => void
+  /** Host hook: a state was LEFT (a value-changing transition). The server uses
+   *  it to cancel that state's `after` timers. */
+  onStateExit?: (stateKey: string) => void
 }
 
 /** Unique per-invocation effect id — usable as an idempotency key, so it must
@@ -96,6 +103,10 @@ export function createActor<C extends object, E extends EventObject, S extends s
   let context: C = opts.snapshot
     ? (structuredClone(opts.snapshot.context) as C)
     : (structuredClone(def.context) as C)
+  // Hydrated actors have already lived: their current state's entry effect fired
+  // when it was entered, so `start()` must NOT re-fire it. Fresh actors (no
+  // snapshot) enter their initial state for the first time.
+  const hydrated = opts.snapshot !== undefined
 
   const subscribers = new Set<(s: Snapshot<C>) => void>()
   const emitListeners = new Map<string, Set<(e: EmittedEvent) => void>>()
@@ -112,6 +123,39 @@ export function createActor<C extends object, E extends EventObject, S extends s
     for (const fn of subscribers) fn(snap)
   }
 
+  // Schedule a state's entry effect (if declared) — the same host-scheduled,
+  // commit-time-snapshot, at-most-once path as a transition effect, minus the
+  // event. Firing does NOT bump `commits` (an entry is not a committed
+  // transition); the server persists an entry-firing machine via the host's
+  // pending-effects queue instead (see server/session-runtime.ts).
+  const fireEntryEffect = (stateKey: string): void => {
+    const entry = def.states[stateKey]?.entry
+    if (!entry) return
+    const effectId = newEffectId()
+    const ctxSnapshot = structuredClone(context)
+    const invocation: EffectInvocation = {
+      machineName: def.name,
+      effectId,
+      run: () => Promise.resolve(entry(ctxSnapshot, { effectId })),
+    }
+    if (opts.onEffect) {
+      opts.onEffect(invocation)
+    } else {
+      void invocation
+        .run()
+        .then((completion) => {
+          if (completion) actor.send(completion as E)
+        })
+        .catch((err) => {
+          console.error(
+            `stator: entry effect ${effectId} of "${def.name}" threw — effects must catch ` +
+              `and return their failure event. Dropped.`,
+            err,
+          )
+        })
+    }
+  }
+
   const actor: Actor<C, E> = {
     seed(partial: Partial<C>) {
       if (!started) context = { ...context, ...partial }
@@ -120,6 +164,12 @@ export function createActor<C extends object, E extends EventObject, S extends s
       if (!started) {
         started = true
         notify() // let subscribe-before-start consumers sync initial state
+        // Fresh initial-state entry (a hydrated actor already fired its).
+        if (!hydrated) {
+          const initial = value[value.length - 1]!
+          fireEntryEffect(initial)
+          opts.onStateEnter?.(initial, context)
+        }
       }
       return actor
     },
@@ -228,6 +278,15 @@ export function createActor<C extends object, E extends EventObject, S extends s
         }
       }
 
+      // A value-changing transition leaves the old state and enters the new one:
+      // fire the new state's entry effect and let the host arm/cancel `after`
+      // timers (self-transitions and action-only transitions do neither).
+      if (config.to && config.to !== stateKey) {
+        opts.onStateExit?.(stateKey)
+        fireEntryEffect(config.to)
+        opts.onStateEnter?.(config.to, context)
+      }
+
       notify()
     },
 

package/src/engine/types.ts

@@ -83,6 +83,31 @@ export type Effect<C, E extends EventObject, EAll extends EventObject = EventObj
   meta: EffectMeta,
 ) => Promise<EAll | null>
 
+/**
+ * A state ENTRY effect: async I/O the host schedules when a state is *entered* —
+ * a fresh start at the initial state, or a transition that changes the state
+ * value; never on hydration. Same host-scheduled, off-lock, at-most-once
+ * pipeline as a transition `Effect`, minus the event argument (a state entry has
+ * no triggering event). Returns the completion event to dispatch (annotate the
+ * return with your machine's event union, exactly as for `Effect`), or null.
+ */
+export type EntryEffect<C, EAll extends EventObject = EventObject> = (
+  ctx: C,
+  meta: EffectMeta,
+) => Promise<EAll | null>
+
+/**
+ * A state timeout: after `delay` ms in the state, the host dispatches `send`.
+ * Armed on entry, cancelled on exit — host-scheduled, in-memory, non-durable in
+ * v1 (a restart drops armed timers). `delay` may depend on context. The trigger
+ * is a *described* value, not a bare-ms key, so it can grow (dynamic delays now;
+ * durable/cron schedules later) without a breaking change.
+ */
+export interface AfterEntry<C, EAll extends EventObject = EventObject> {
+  delay: number | ((ctx: C) => number)
+  send: EAll
+}
+
 /** A scheduled effect surfaced to the host: everything needed to run it and
  *  dispatch its completion. `run` closes over the commit-time snapshots. */
 export interface EffectInvocation {
@@ -132,6 +157,14 @@ export type OnMap<C, E extends EventObject, S extends string, R = Record<string,
 
 export interface StateNode<C, E extends EventObject, S extends string, R = Record<string, any>> {
   on?: OnMap<C, E, S, R>
+  /** Async I/O run on *entering* this state (a fresh start at the initial state,
+   *  or a value-changing transition — never on hydration), host-scheduled like a
+   *  transition effect. `EAll` is the machine's full event union. See
+   *  `EntryEffect`. */
+  entry?: EntryEffect<C, E>
+  /** State timeouts: each fires `send` after its `delay` ms in this state
+   *  (armed on entry, cancelled on exit). See `AfterEntry`. */
+  after?: AfterEntry<C, E>[]
 }
 
 /** Payload selector runs synchronously AFTER the transition's action, so it

package/src/server/api-route.ts

@@ -83,8 +83,14 @@ export async function runApiRoute(
         return c.text('Internal Server Error', 500)
       }
 
+      // Persist committed machines plus any fresh machine that fired its initial
+      // entry effect (not in `touched` — an entry commits no transition), so it
+      // isn't re-created and re-fired next request. Fan-out stays on `touched`.
+      const toPersist = new Set([...touched, ...runtime.entryFiredMachines()])
+      if (toPersist.size > 0) {
+        await runtime.persistTouched(toPersist)
+      }
       if (touched.size > 0) {
-        await runtime.persistTouched(touched)
         await fanOut(touched, { sessionId })
       }
 

package/src/server/create-app.ts

@@ -52,8 +52,10 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     sessionTtlSeconds: config.sessionTtlSeconds,
     appStore: config.appStore,
   })
-  await store.bootAppMachines()
+  // Wire the effect scheduler BEFORE booting: a fresh app machine fires its
+  // initial-state entry effect during boot, and that must have somewhere to go.
   wireAppEffects(store)
+  await store.bootAppMachines()
 
   const routes = await discoverRoutes(routesDir)
   const app = await buildHonoApp({

package/src/server/dev.ts

@@ -135,8 +135,10 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
       sessionTtlSeconds: config.sessionTtlSeconds,
       appStore: config.appStore,
     })
-    await store.bootAppMachines()
+    // Wire the effect scheduler before booting — a fresh app machine's
+    // initial-state entry effect fires during boot and needs a live scheduler.
     runtime.wireAppEffects(store)
+    await store.bootAppMachines()
   }
   const rebuildRoutes = async (): Promise<void> => {
     routes = await runtime.discoverRoutes(routesDir, loader)

package/src/server/effects.ts

@@ -1,4 +1,4 @@
-import type { AnyMachineDef, EffectInvocation } from '../engine/index.ts'
+import type { AnyMachineDef, EffectInvocation, EventObject } from '../engine/index.ts'
 import { dispatchToApp } from './app-dispatch.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -95,22 +95,7 @@ async function runSessionEffect(
   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()
-      }
-    })
+    await reenterSessionEvent(store, sessionId, machineName, completion)
   } catch (err) {
     effectLog.error(
       { machine: machineName, effectId, err: String(err) },
@@ -118,3 +103,37 @@ async function runSessionEffect(
     )
   }
 }
+
+/**
+ * Re-enter an out-of-band event (an effect completion, or an `after` timeout)
+ * through the full session event path: fresh lock, hydrate the machine (the
+ * triggering runtime is long gone — the transient-actor model working for us),
+ * process, persist (including a machine that fired an entry effect on the
+ * resulting transition), fan out to live connections, and schedule any effect
+ * the event chained. Shared by effect completions and state timeouts.
+ */
+export async function reenterSessionEvent(
+  store: MachineStore,
+  sessionId: string,
+  machineName: string,
+  event: EventObject,
+): Promise<void> {
+  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 emits reach
+      // cross-machine listeners like any other event.
+      await runtime.loadGraph([def])
+      runtime.wireSubscriptions()
+      const touched = runtime.processEvent(machineName, event)
+      await runtime.persistTouched(new Set([...touched, ...runtime.entryFiredMachines()]))
+      await fanOut(touched, { sessionId })
+      // A transition or entry effect chained off this event surfaces here.
+      scheduleSessionEffects(runtime, store, sessionId)
+    } finally {
+      runtime.dispose()
+    }
+  })
+}

package/src/server/http.ts

@@ -333,7 +333,10 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
           patches.push(...recompute(renderState, name, runtime))
         }
 
-        await runtime.persistTouched(touched)
+        // Persist committed machines plus any fresh machine that fired its
+        // initial entry effect (an entry commits no transition, so it's not in
+        // `touched`) — so it isn't re-created and re-fired next request.
+        await runtime.persistTouched(new Set([...touched, ...runtime.entryFiredMachines()]))
 
         await fanOut(touched, {
           sessionId,
@@ -479,6 +482,17 @@ async function handleGet(
         bodyEnd: bodyHtml.join(''),
       })
       applyRenderedEffects(c, result.response)
+
+      // A fresh machine that fired its initial entry effect on load must be
+      // persisted (so the next request hydrates instead of re-firing) and its
+      // effect scheduled off-lock, after the response. The common GET (no entry
+      // effect) skips both and stays a pure read.
+      const entryFired = runtime.entryFiredMachines()
+      if (entryFired.size > 0) {
+        await runtime.persistTouched(entryFired)
+        scheduleSessionEffects(runtime, store, sessionId)
+      }
+
       return c.html(html)
     } finally {
       runtime.dispose()

package/src/server/machine-store.ts

@@ -6,6 +6,7 @@ import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { scopedLogger } from './logger.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
 import type { Store } from './store.ts'
+import { APP_SCOPE, armAfterTimers, cancelAfterTimers } from './timers.ts'
 
 const storeLog = scopedLogger('machine-store')
 
@@ -259,6 +260,12 @@ export class MachineStore {
                 'app-machine effect dropped — no scheduler wired (call wireAppEffects(store))',
               )
           },
+          // `after` state timeouts, at app scope: arm on entry, cancel on exit.
+          // Timers live in the process-wide registry (server/timers.ts) and fire
+          // through dispatchToApp — no session, wall-clock only (revalidation,
+          // circuit breakers). See armAfterTimers.
+          onStateEnter: (stateKey, ctx) => armAfterTimers(this, APP_SCOPE, def, stateKey, ctx),
+          onStateExit: (stateKey) => cancelAfterTimers(APP_SCOPE, def.name, stateKey),
         }).start()
         this.appInstances.set(
           def.name,

package/src/server/session-runtime.ts

@@ -4,6 +4,7 @@ import { type DispatchContext, recordTouch, withDispatchContext } from './dispat
 import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { buildDispatchEvent, MAX_CASCADE_DEPTH, type MachineStore } from './machine-store.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
+import { armAfterTimers, cancelAfterTimers } from './timers.ts'
 
 /**
  * Per-request scope for session-lifecycle machine actors. Created at the
@@ -67,6 +68,11 @@ export class SessionRuntime {
       // Server plane: never run effects inline — queue them for the entry
       // point to schedule after persist + lock release.
       onEffect: (invocation) => this.pendingEffects.push(invocation),
+      // `after` state timeouts: arm on entry, cancel on exit. Timers live in the
+      // process-wide registry (server/timers.ts), not this transient runtime.
+      onStateEnter: (stateKey, ctx) =>
+        armAfterTimers(this.store, this.sessionId, def, stateKey, ctx),
+      onStateExit: (stateKey) => cancelAfterTimers(this.sessionId, def.name, stateKey),
     }).start()
     this.actors.set(
       def.name,
@@ -104,6 +110,14 @@ export class SessionRuntime {
     return this.store.getDef(name)?.lifecycle
   }
 
+  /** Machines whose entry effect fired on a fresh `start()` — queued in
+   *  `pendingEffects` but distinct from `touched` (an entry commits no
+   *  transition). Entry points persist this set so a freshly-entered state
+   *  isn't re-created and re-fired next request. Read before draining. */
+  entryFiredMachines(): Set<string> {
+    return new Set(this.pendingEffects.map((e) => e.machineName))
+  }
+
   /** Hand queued effect invocations to the scheduler, clearing the queue. */
   drainPendingEffects(): EffectInvocation[] {
     const drained = this.pendingEffects

package/src/server/timers.ts

@@ -0,0 +1,77 @@
+import type { AnyMachineDef } from '../engine/index.ts'
+import { dispatchToApp } from './app-dispatch.ts'
+import { reenterSessionEvent } from './effects.ts'
+import { scopedLogger } from './logger.ts'
+import type { MachineStore } from './machine-store.ts'
+
+const timerLog = scopedLogger('timers')
+
+/** Timer scope for app machines. They're process singletons (one instance per
+ *  name), so they share one scope and the machine name disambiguates the key —
+ *  unlike session machines, which scope by session id. */
+export const APP_SCOPE = '@app'
+
+/**
+ * Process-wide, in-memory, NON-DURABLE registry for `after` state timeouts.
+ * Session runtimes are transient (per request) and app instances live for the
+ * process, so a timer can't live on either — it lives here, keyed by the state
+ * it's counting down for, and fires across (or between) requests. A process
+ * restart drops armed timers (the 1.0 non-durable contract, same as effects).
+ */
+const timers = new Map<string, ReturnType<typeof setTimeout>[]>()
+
+const key = (scope: string, machineName: string, stateKey: string): string =>
+  `${scope} ${machineName} ${stateKey}`
+
+/** Cancel every `after` timer armed for a (scope, machine, state). `scope` is
+ *  the session id for session machines, `APP_SCOPE` for app machines. */
+export function cancelAfterTimers(scope: string, machineName: string, stateKey: string): void {
+  const k = key(scope, machineName, stateKey)
+  const handles = timers.get(k)
+  if (!handles) return
+  for (const h of handles) clearTimeout(h)
+  timers.delete(k)
+}
+
+/**
+ * Arm the `after` timers declared on `stateKey` (a no-op if it declares none).
+ * The host calls this when a machine ENTERS the state. Each timer, on elapse,
+ * dispatches its `send` event back through the machine's normal event path —
+ * a session machine through the session re-entry (fresh lock + hydrate), an app
+ * machine through `dispatchToApp` (no lock; the long-lived instance is sent
+ * directly). Either way it's guard-dropped if the state has since moved on (the
+ * cancel-on-exit is the fast path; the guard-drop is the correctness backstop).
+ * Re-arming clears any stale timers for the key first.
+ */
+export function armAfterTimers(
+  store: MachineStore,
+  scope: string,
+  def: AnyMachineDef,
+  stateKey: string,
+  ctx: object,
+): void {
+  const after = def.states[stateKey]?.after
+  if (!after || after.length === 0) return
+  cancelAfterTimers(scope, def.name, stateKey)
+  const k = key(scope, def.name, stateKey)
+  const handles = after.map((entry) => {
+    const delay = typeof entry.delay === 'function' ? entry.delay(ctx as never) : entry.delay
+    const h = setTimeout(() => {
+      timers.delete(k) // a state has one arm-set; drop the whole key on fire
+      const fire =
+        def.lifecycle === 'app'
+          ? dispatchToApp(store, def, entry.send as never).then(() => {})
+          : reenterSessionEvent(store, scope, def.name, entry.send)
+      void fire.catch((err) => {
+        timerLog.error(
+          { scope, machine: def.name, state: stateKey, err: String(err) },
+          'after-timer dispatch failed',
+        )
+      })
+    }, delay)
+    // Don't keep the process alive for a pending timer.
+    ;(h as unknown as { unref?: () => void }).unref?.()
+    return h
+  })
+  timers.set(k, handles)
+}