@typeonce/effect-machine-devtools 0.23.0

package/src/internal/browser/visualizer-model.ts

@@ -0,0 +1,173 @@
+import type {
+  Activity as VisualizationActivity,
+  Branch as VisualizationBranch,
+  MachineDocument as VisualizationDocument,
+  State as VisualizationState,
+  Transition as VisualizationTransition
+} from "../../MachineDocument.js"
+
+export interface TopologyNode {
+  readonly path: string
+  readonly label: string
+  readonly type: VisualizationState["type"]
+  readonly active: boolean
+  readonly initial: boolean
+  readonly transitionCount: number
+  readonly activityCount: number
+  readonly children: ReadonlyArray<TopologyNode>
+}
+
+export interface StateBreadcrumb {
+  readonly path: string
+  readonly label: string
+}
+
+export interface IncomingTransition {
+  readonly transition: VisualizationTransition
+  readonly branch: VisualizationBranch
+}
+
+export interface StateInspection {
+  readonly state: VisualizationState
+  readonly label: string
+  readonly active: boolean
+  readonly initial: boolean
+  readonly breadcrumbs: ReadonlyArray<StateBreadcrumb>
+  readonly outgoing: ReadonlyArray<VisualizationTransition>
+  readonly incoming: ReadonlyArray<IncomingTransition>
+  readonly activities: ReadonlyArray<VisualizationActivity>
+}
+
+export interface EventInspection {
+  readonly event: string
+  readonly candidate: boolean
+  readonly transitions: ReadonlyArray<VisualizationTransition>
+}
+
+export interface VisualizerModel {
+  readonly machineId: string
+  readonly roots: ReadonlyArray<TopologyNode>
+  readonly hasSnapshot: boolean
+  readonly activePaths: ReadonlyArray<string>
+  readonly candidateEvents: ReadonlyArray<string>
+  readonly inspectState: (path: string) => StateInspection | undefined
+  readonly inspectEvent: (event: string) => EventInspection
+}
+
+export const stateLabel = (state: VisualizationState): string =>
+  state.title === null ? state.key : `${state.title} (${state.key})`
+
+export const triggerLabel = (transition: VisualizationTransition): string => {
+  switch (transition.trigger.type) {
+    case "event":
+      return transition.trigger.event
+    case "always":
+      return "Always"
+    case "done":
+      return "On completion"
+    case "choice":
+      return "Choice"
+    case "invoke":
+      return `${transition.trigger.id} · ${transition.trigger.outcome}`
+  }
+}
+
+const buildInitialPaths = (document: VisualizationDocument): ReadonlySet<string> => {
+  const initial = new Set<string>([document.initial.target])
+  for (const state of document.states) {
+    if (state.initial !== null) initial.add(state.initial)
+  }
+  return initial
+}
+
+export const makeVisualizerModel = (document: VisualizationDocument): VisualizerModel => {
+  const states = new Map(document.states.map((state) => [state.path, state]))
+  const transitions = new Map(document.transitions.map((transition) => [transition.id, transition]))
+  const activities = new Map(document.activities.map((activity) => [activity.id, activity]))
+  const active = new Set(document.snapshot?.activePaths ?? [])
+  const initial = buildInitialPaths(document)
+  const candidateEvents = document.snapshot?.candidateEvents ?? []
+
+  const outgoing = (state: VisualizationState): ReadonlyArray<VisualizationTransition> =>
+    state.transitionIds.flatMap((id): ReadonlyArray<VisualizationTransition> => {
+      const transition = transitions.get(id)
+      return transition === undefined ? [] : [transition]
+    })
+
+  const ownedActivities = (state: VisualizationState): ReadonlyArray<VisualizationActivity> =>
+    state.activityIds.flatMap((id): ReadonlyArray<VisualizationActivity> => {
+      const definition = activities.get(id)
+      return definition === undefined ? [] : [definition]
+    })
+
+  const incoming = new Map<string, Array<IncomingTransition>>()
+  for (const transition of document.transitions) {
+    for (const branch of transition.branches) {
+      if (branch.target === null) continue
+      const registrations = incoming.get(branch.target) ?? []
+      registrations.push({ transition, branch })
+      incoming.set(branch.target, registrations)
+    }
+  }
+
+  const visit = (path: string): TopologyNode | undefined => {
+    const state = states.get(path)
+    if (state === undefined) return undefined
+    return {
+      path: state.path,
+      label: stateLabel(state),
+      type: state.type,
+      active: active.has(state.path),
+      initial: initial.has(state.path),
+      transitionCount: state.transitionIds.length,
+      activityCount: state.activityIds.length,
+      children: state.children.flatMap((childPath): ReadonlyArray<TopologyNode> => {
+        const child = visit(childPath)
+        return child === undefined ? [] : [child]
+      })
+    }
+  }
+
+  const breadcrumbs = (state: VisualizationState): ReadonlyArray<StateBreadcrumb> => {
+    const result: Array<StateBreadcrumb> = []
+    let current: VisualizationState | undefined = state
+    while (current !== undefined) {
+      result.unshift({ path: current.path, label: stateLabel(current) })
+      current = current.parent === null ? undefined : states.get(current.parent)
+    }
+    return result
+  }
+
+  return {
+    machineId: document.machineId,
+    roots: document.roots.flatMap((path): ReadonlyArray<TopologyNode> => {
+      const root = visit(path)
+      return root === undefined ? [] : [root]
+    }),
+    hasSnapshot: document.snapshot !== null,
+    activePaths: [...active],
+    candidateEvents: [...candidateEvents],
+    inspectState: (path) => {
+      const state = states.get(path)
+      return state === undefined
+        ? undefined
+        : {
+          state,
+          label: stateLabel(state),
+          active: active.has(path),
+          initial: initial.has(path),
+          breadcrumbs: breadcrumbs(state),
+          outgoing: outgoing(state),
+          incoming: [...incoming.get(path) ?? []],
+          activities: ownedActivities(state)
+        }
+    },
+    inspectEvent: (event) => ({
+      event,
+      candidate: candidateEvents.includes(event),
+      transitions: document.transitions.filter((transition) =>
+        transition.trigger.type === "event" && transition.trigger.event === event
+      )
+    })
+  }
+}

package/src/internal/browser/visualizer.ts

@@ -0,0 +1,31 @@
+import type { MachineResult } from "../../DevToolsProtocol.js"
+import { renderVisualizer } from "./visualizer-app.js"
+
+const renderError = (root: HTMLElement, source: Extract<MachineResult, { readonly _tag: "Failed" }>): void => {
+  const shell = document.createElement("main")
+  shell.className = "failure-shell"
+  shell.setAttribute("role", "alert")
+  const kind = document.createElement("span")
+  kind.className = "failure-kind"
+  kind.textContent = "Visualizer error"
+  const title = document.createElement("h1")
+  title.textContent = "Machine could not be inspected"
+  const message = document.createElement("pre")
+  message.textContent = source.diagnostics.map((diagnostic) => diagnostic.message).join("\n")
+  const hint = document.createElement("p")
+  hint.textContent = "Fix the machine definition and the page will reload."
+  shell.append(kind, title, message, hint)
+  root.replaceChildren(shell)
+}
+
+export const mountVisualizer = (root: HTMLElement, source: MachineResult): void => {
+  switch (source._tag) {
+    case "Ready":
+    case "Partial":
+      renderVisualizer(root, source.document, source.diagnostics)
+      break
+    case "Failed":
+      renderError(root, source)
+      break
+  }
+}

package/src/internal/devServer.ts

@@ -0,0 +1,171 @@
+import { type ChokidarOptions, type FSWatcher, watch } from "chokidar"
+import * as Effect from "effect/Effect"
+import * as Stream from "effect/Stream"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { isAbsolute, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { createServer, type Plugin, type ViteDevServer } from "vite"
+import type * as DevServer from "../DevServer.js"
+import * as MachineRegistry from "../MachineRegistry.js"
+
+type DevServerErrorConstructor = typeof DevServer.DevServerError
+
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url))
+
+const sourceExtension = /\.(?:[cm]?[jt]sx?)$/
+
+const isProjectSource = (root: string, file: string): boolean => {
+  const projectPath = relative(root, isAbsolute(file) ? file : resolve(root, file))
+  return projectPath !== "" &&
+    !projectPath.startsWith("..") &&
+    sourceExtension.test(projectPath) &&
+    !projectPath.split(/[\\/]/).some((part) =>
+      part === "node_modules" ||
+      part === ".git" ||
+      part === "dist" ||
+      part === "build" ||
+      part === "coverage" ||
+      part === ".data" ||
+      part === "references"
+    )
+}
+
+const isIgnored = (file: string): boolean =>
+  file.split(/[\\/]/).some((part) =>
+    part === "node_modules" ||
+    part === ".git" ||
+    part === "dist" ||
+    part === "build" ||
+    part === "coverage" ||
+    part === ".data" ||
+    part === "references"
+  )
+
+const writeJson = (response: ServerResponse, value: unknown): void => {
+  response.statusCode = 200
+  response.setHeader("content-type", "application/json; charset=utf-8")
+  response.setHeader("cache-control", "no-store")
+  response.end(JSON.stringify(value))
+}
+
+const apiPlugin = (
+  registry: MachineRegistry.MachineRegistry["Service"]
+): Plugin => ({
+  name: "effect-machine-devtools-api",
+  configureServer(server) {
+    server.middlewares.use((request: IncomingMessage, response: ServerResponse, next: () => void) => {
+      if (request.url === "/api/machines") {
+        void Effect.runPromise(registry.get).then(
+          (snapshot) => writeJson(response, snapshot),
+          (cause) => {
+            response.statusCode = 500
+            response.end(String(cause))
+          }
+        )
+        return
+      }
+      if (request.url !== "/api/events") {
+        next()
+        return
+      }
+
+      response.statusCode = 200
+      response.setHeader("content-type", "text/event-stream")
+      response.setHeader("cache-control", "no-cache, no-transform")
+      response.setHeader("connection", "keep-alive")
+      response.flushHeaders()
+
+      const controller = new AbortController()
+      request.on("close", () => controller.abort())
+      void Effect.runPromise(
+        registry.changes.pipe(
+          Stream.runForEach((snapshot) => Effect.sync(() => response.write(`data: ${JSON.stringify(snapshot)}\n\n`)))
+        ),
+        { signal: controller.signal }
+      ).catch(() => undefined)
+    })
+  }
+})
+
+const acquire = (
+  ErrorType: DevServerErrorConstructor,
+  options: DevServer.Options,
+  registry: MachineRegistry.MachineRegistry["Service"]
+): Effect.Effect<ViteDevServer, DevServer.DevServerError, never> =>
+  Effect.tryPromise({
+    try: async () => {
+      const server = await createServer({
+        root: packageRoot,
+        appType: "spa",
+        logLevel: "error",
+        plugins: [apiPlugin(registry)],
+        server: {
+          host: options.host,
+          port: options.port,
+          strictPort: true,
+          open: options.open ?? false
+        }
+      })
+      await server.listen()
+      return server
+    },
+    catch: (cause) =>
+      new ErrorType({
+        message: `Could not start the Effect Machine visualizer on ${options.host}:${options.port}`,
+        cause
+      })
+  })
+
+const acquireWatcher = (
+  options: DevServer.Options,
+  registry: MachineRegistry.MachineRegistry["Service"]
+): Effect.Effect<FSWatcher> =>
+  Effect.sync(() => {
+    let refreshTimer: ReturnType<typeof setTimeout> | undefined
+    const watcher = watch(options.root, watcherOptions(options))
+    watcher.on("all", (_event, file) => {
+      if (!isProjectSource(options.root, file)) return
+      if (refreshTimer !== undefined) clearTimeout(refreshTimer)
+      refreshTimer = setTimeout(() => {
+        Effect.runFork(
+          registry.refresh.pipe(
+            Effect.catch((cause) => Effect.logWarning("Machine reload failed", cause))
+          )
+        )
+      }, options.debounce ?? 150)
+    })
+    watcher.on("close", () => {
+      if (refreshTimer !== undefined) clearTimeout(refreshTimer)
+    })
+    watcher.on("error", (cause) => {
+      Effect.runFork(Effect.logError("Machine file watcher failed", cause))
+    })
+    return watcher
+  })
+
+export const watcherOptions = (options: DevServer.Options): ChokidarOptions =>
+  ({
+    ignoreInitial: true,
+    interval: 200,
+    usePolling: options.watchPolling ?? false,
+    ignored: (file, stats) => isIgnored(file) || stats?.isFile() === true && !sourceExtension.test(file)
+  }) satisfies ChokidarOptions
+
+export const run = (
+  ErrorType: DevServerErrorConstructor,
+  options: DevServer.Options
+): Effect.Effect<never, DevServer.DevServerError, MachineRegistry.MachineRegistry> =>
+  Effect.gen(function*() {
+    const registry = yield* MachineRegistry.MachineRegistry
+    const server = yield* Effect.acquireRelease(
+      acquire(ErrorType, options, registry),
+      (server) => Effect.promise(() => server.close())
+    )
+    yield* Effect.acquireRelease(
+      acquireWatcher(options, registry),
+      (watcher) => Effect.promise(() => watcher.close())
+    )
+    const address = server.resolvedUrls?.local[0] ?? `http://${options.host}:${options.port}/`
+    yield* Effect.logInfo(`Effect Machine visualizer: ${address}`)
+    return yield* Effect.never
+  }).pipe(Effect.scoped)

package/src/internal/evaluationWorker.ts

@@ -0,0 +1,138 @@
+import * as NodeWorkerRunner from "@effect/platform-node/NodeWorkerRunner"
+import type { Machine } from "@typeonce/effect-machine"
+import * as Effect from "effect/Effect"
+import * as WorkerRunner from "effect/unstable/workers/WorkerRunner"
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import type { ViteDevServer } from "vite"
+import * as DevToolsProtocol from "../DevToolsProtocol.js"
+import * as MachineDocument from "../MachineDocument.js"
+import type * as ProjectInspector from "../ProjectInspector.js"
+
+interface EvaluationRequest {
+  readonly root: string
+  readonly revision: number
+  readonly candidates: ReadonlyArray<ProjectInspector.Candidate>
+}
+
+interface EvaluationResponse {
+  readonly results: ReadonlyArray<DevToolsProtocol.MachineResult>
+}
+
+const isMachine = (value: unknown): value is Machine.Machine.Any =>
+  typeof value === "object" &&
+  value !== null &&
+  "stateNodes" in value &&
+  "handlers" in value &&
+  "initialDefinition" in value &&
+  "initial" in value
+
+const sourceOf = (file: string, exportName: string | null): MachineDocument.Source => ({ file, exportName })
+
+const diagnostic = (
+  file: string,
+  code: string,
+  message: string
+): DevToolsProtocol.Diagnostic => ({
+  severity: "error",
+  code,
+  message,
+  location: { file, line: null, column: null },
+  statePath: null
+})
+
+const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause)
+
+const failed = (
+  candidate: ProjectInspector.Candidate,
+  code: string,
+  message: string,
+  exportName: string | null = candidate.exportNames[0] ?? null
+): DevToolsProtocol.Failed => ({
+  _tag: "Failed",
+  protocolVersion: DevToolsProtocol.protocolVersion,
+  key: exportName === null ? candidate.file : `${candidate.file}#${exportName}`,
+  source: sourceOf(candidate.file, exportName),
+  machineId: null,
+  diagnostics: [diagnostic(candidate.file, code, message)]
+})
+
+const evaluateCandidate = (
+  server: ViteDevServer,
+  request: EvaluationRequest,
+  candidate: ProjectInspector.Candidate
+): Effect.Effect<ReadonlyArray<DevToolsProtocol.MachineResult>> =>
+  Effect.tryPromise({
+    try: () => server.ssrLoadModule(pathToFileURL(resolve(request.root, candidate.file)).href),
+    catch: (cause) => cause
+  }).pipe(
+    Effect.flatMap((module) =>
+      Effect.try(() =>
+        Object.entries(module).filter((entry): entry is [string, Machine.Machine.Any] => isMachine(entry[1]))
+      )
+    ),
+    Effect.flatMap((machines) => {
+      if (machines.length === 0) {
+        return Effect.succeed([failed(
+          candidate,
+          "machine-export-not-found",
+          "The module contains a .handle(...) call but does not export the resulting machine"
+        )])
+      }
+
+      const seen = new Set<Machine.Machine.Any>()
+      return Effect.forEach(machines, ([exportName, machine]) => {
+        if (seen.has(machine)) return Effect.succeed<DevToolsProtocol.MachineResult | undefined>(undefined)
+        seen.add(machine)
+        const source = sourceOf(candidate.file, exportName)
+        return Effect.try({
+          try: () =>
+            ({
+              _tag: "Ready",
+              protocolVersion: DevToolsProtocol.protocolVersion,
+              key: `${candidate.file}#${exportName}`,
+              document: MachineDocument.make(machine, {
+                revision: request.revision,
+                source
+              }),
+              diagnostics: []
+            }) satisfies DevToolsProtocol.Ready,
+          catch: (cause) => cause
+        }).pipe(
+          Effect.catch((cause) =>
+            Effect.succeed(failed(
+              candidate,
+              "machine-inspection-failed",
+              messageOf(cause),
+              exportName
+            ))
+          )
+        )
+      }).pipe(
+        Effect.map((results) =>
+          results.filter((result): result is DevToolsProtocol.MachineResult => result !== undefined)
+        )
+      )
+    }),
+    Effect.catch((cause) => Effect.succeed([failed(candidate, "module-load-failed", messageOf(cause))]))
+  )
+
+const handle = (server: ViteDevServer, request: EvaluationRequest): Effect.Effect<EvaluationResponse> =>
+  Effect.forEach(request.candidates, (candidate) => evaluateCandidate(server, request, candidate), {
+    concurrency: 1
+  }).pipe(
+    Effect.map((results) => ({ results: results.flat() }))
+  )
+
+export const run = (server: ViteDevServer): Promise<void> => {
+  return Effect.gen(function*() {
+    const platform = yield* WorkerRunner.WorkerRunnerPlatform
+    const runner = yield* platform.start<EvaluationResponse, EvaluationRequest>()
+    yield* runner.run((_portId, request) =>
+      Effect.flatMap(handle(server, request), (response) => runner.send(0, response))
+    )
+  }).pipe(
+    Effect.provide(NodeWorkerRunner.layer),
+    Effect.runPromise
+  )
+}

package/src/internal/evaluationWorkerBootstrap.js

@@ -0,0 +1,21 @@
+import { workerData } from "node:worker_threads"
+import { createServer } from "vite"
+
+const server = await createServer({
+  appType: "custom",
+  logLevel: "silent",
+  server: {
+    hmr: false,
+    middlewareMode: true
+  },
+  optimizeDeps: {
+    noDiscovery: true
+  }
+})
+
+try {
+  const runtime = await server.ssrLoadModule(workerData.runtimeModuleUrl)
+  await runtime.run(server)
+} finally {
+  await server.close()
+}

package/src/internal/machineDocument.ts

@@ -0,0 +1,138 @@
+import { Machine } from "@typeonce/effect-machine"
+import type * as Public from "../MachineDocument.js"
+
+const enabled = Machine.enabled as (
+  machine: Machine.Machine.Any,
+  snapshot: unknown
+) => ReadonlyArray<PropertyKey>
+
+const selection = (value: Machine.Machine.TransitionTargetSelection): Public.Selection => ({
+  path: value.path ?? null,
+  kind: value.kind,
+  scope: value.scope ?? null
+})
+
+const trigger = (value: Machine.Machine.TransitionTrigger): Public.Trigger => {
+  switch (value.type) {
+    case "event":
+      return { type: "event", event: String(value.event) }
+    case "always":
+      return { type: "always" }
+    case "done":
+      return { type: "done" }
+    case "choice":
+      return { type: "choice" }
+    case "invoke":
+      return { type: "invoke", id: value.id, outcome: value.outcome }
+  }
+}
+
+const activity = (value: Machine.Machine.ActivityDefinition, id: string): Public.Activity => {
+  const common = { id, source: value.source, lifecycleId: value.id }
+  switch (value.type) {
+    case "process":
+      return { ...common, type: "process" }
+    case "effect":
+      return { ...common, type: "effect", outcomes: { ...value.outcomes } }
+    case "timer":
+      return { ...common, type: "timer", duration: value.duration }
+    case "stream":
+      return { ...common, type: "stream" }
+    case "machine":
+      return { ...common, type: "machine", child: { ...value.child } }
+  }
+}
+
+const appendReference = (index: Map<string, Array<string>>, owner: string, id: string): void => {
+  const references = index.get(owner) ?? []
+  references.push(id)
+  index.set(owner, references)
+}
+
+export const make = <M extends Machine.Machine.Any>(
+  machine: M,
+  options: Public.MakeOptions<M> = {}
+): Public.MachineDocument => {
+  const nodes = Machine.stateNodes(machine)
+  const transitionIds = new Map<string, Array<string>>()
+  const activityIds = new Map<string, Array<string>>()
+  const transitionOffsets = new Map<string, number>()
+  const activityOffsets = new Map<string, number>()
+  const childPaths = new Map<string | null, Array<string>>()
+
+  for (const node of nodes) {
+    const parent = node.parent ?? null
+    const siblings = childPaths.get(parent) ?? []
+    siblings.push(node.path)
+    childPaths.set(parent, siblings)
+  }
+
+  const transitions = Machine.transitionDefinitions(machine).map((definition): Public.Transition => {
+    const offset = transitionOffsets.get(definition.source) ?? 0
+    transitionOffsets.set(definition.source, offset + 1)
+    const id = `${definition.source}:transition:${offset}`
+    appendReference(transitionIds, definition.source, id)
+    return {
+      id,
+      source: definition.source,
+      trigger: trigger(definition.trigger),
+      reenter: definition.reenter,
+      acceptance: definition.acceptance,
+      branches: definition.branches.map((branch, branchIndex): Public.Branch => {
+        const common = {
+          id: `${id}:branch:${branchIndex}`,
+          target: branch.target ?? null,
+          selection: selection(branch.selection),
+          updates: [...branch.updates]
+        }
+        return branch.type === "direct"
+          ? { ...common, type: "direct" }
+          : { ...common, type: "branch", key: branch.key, title: branch.title }
+      })
+    }
+  })
+
+  const activities = Machine.activityDefinitions(machine).map((definition): Public.Activity => {
+    const offset = activityOffsets.get(definition.source) ?? 0
+    activityOffsets.set(definition.source, offset + 1)
+    const id = `${definition.source}:activity:${offset}`
+    appendReference(activityIds, definition.source, id)
+    return activity(definition, id)
+  })
+
+  const initial = Machine.initialDefinition(machine)
+  return {
+    schemaVersion: 1,
+    revision: options.revision ?? 0,
+    source: options.source ?? null,
+    machineId: machine.id ?? "Machine",
+    initial: {
+      target: initial.target,
+      selection: selection(initial.selection)
+    },
+    roots: [...childPaths.get(null) ?? []],
+    states: nodes.map((node): Public.State => ({
+      path: node.path,
+      key: node.key,
+      order: node.order,
+      title: node.annotations?.title ?? null,
+      description: node.annotations?.description ?? null,
+      documentation: node.annotations?.documentation ?? null,
+      type: node.type,
+      history: node.history ?? null,
+      parent: node.parent ?? null,
+      children: [...childPaths.get(node.path) ?? []],
+      initial: node.initial ?? null,
+      transitionIds: [...transitionIds.get(node.path) ?? []],
+      activityIds: [...activityIds.get(node.path) ?? []]
+    })),
+    transitions,
+    activities,
+    snapshot: options.snapshot === undefined
+      ? null
+      : {
+        activePaths: Machine.configuration(machine, options.snapshot).map((node) => node.path),
+        candidateEvents: enabled(machine, options.snapshot).map(String)
+      }
+  }
+}