@typeonce/effect-machine-devtools 0.23.0 → 0.25.0

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

@@ -72,6 +72,110 @@ export const triggerLabel = (transition: VisualizationTransition): string => {
   }
 }
 
+const propertyAccess = (key: string): string => /^[$A-Z_a-z][$\w]*$/.test(key) ? `.${key}` : `[${JSON.stringify(key)}]`
+
+const pathAccess = (path: string): string => path.split(".").map(propertyAccess).join("")
+
+const nearestCompoundScope = (
+  document: VisualizationDocument,
+  source: string
+): string | undefined => {
+  const states = new Map(document.states.map((state) => [state.path, state]))
+  let current = states.get(source)
+  while (current !== undefined) {
+    if (current.type === "compound") return current.path
+    current = current.parent === null ? undefined : states.get(current.parent)
+  }
+  return undefined
+}
+
+const localPathAccess = (
+  document: VisualizationDocument,
+  source: string,
+  path: string
+): string | undefined => {
+  const scope = nearestCompoundScope(document, source)
+  if (scope === undefined) return undefined
+  if (path === scope) return ""
+  const prefix = `${scope}.`
+  return path.startsWith(prefix) ? pathAccess(path.slice(prefix.length)) : undefined
+}
+
+/** Canonical Effect Machine selector represented by one retained transition branch. */
+export const branchTargetApi = (
+  document: VisualizationDocument,
+  source: string,
+  branch: VisualizationBranch
+): string | undefined => {
+  const { selection } = branch
+  if (selection.kind === "none") return "to.none"
+  const path = selection.path
+  if (path === null || selection.scope === null) return undefined
+
+  let api: string | undefined
+  if (selection.kind === "history" && selection.scope === "full") {
+    api = `to.history${pathAccess(path)}`
+  } else if (selection.scope === "local") {
+    const local = localPathAccess(document, source, path)
+    if (local === undefined) return undefined
+    switch (selection.kind) {
+      case "state":
+        api = local === "" ? "to.local.with" : `to.local${local}()`
+        break
+      case "choice":
+        api = local === "" ? undefined : `to.local${local}()`
+        break
+      case "initial":
+        api = local === "" ? undefined : `to.local${local}.initial`
+        break
+      case "update":
+        api = local === "" ? "to.local.update" : undefined
+        break
+      case "history":
+        break
+    }
+  } else if (selection.scope === "branch") {
+    switch (selection.kind) {
+      case "state":
+      case "choice":
+        api = `to.branch${pathAccess(path)}()`
+        break
+      case "initial":
+        api = `to.branch${pathAccess(path)}.initial`
+        break
+      case "update":
+        api = `to.branch${pathAccess(path)}.update`
+        break
+      case "history":
+        break
+    }
+  } else if (selection.scope === "full") {
+    switch (selection.kind) {
+      case "state":
+      case "choice":
+        api = `to.full${pathAccess(path)}()`
+        break
+      case "initial":
+        api = `to.full${pathAccess(path)}.initial`
+        break
+      case "history":
+        api = `to.history${pathAccess(path)}`
+        break
+      case "update":
+        break
+    }
+  } else if (selection.scope === "initial") {
+    if (selection.kind === "state") api = `to${pathAccess(path)}()`
+    if (selection.kind === "initial") api = `to${pathAccess(path)}.initial`
+  }
+
+  if (api === undefined || selection.kind === "update") return api
+  return branch.updates.reduce(
+    (expression, owner) => `${expression}.updating(to.branch${pathAccess(owner)})`,
+    api
+  )
+}
+
 const buildInitialPaths = (document: VisualizationDocument): ReadonlySet<string> => {
   const initial = new Set<string>([document.initial.target])
   for (const state of document.states) {

package/src/internal/browser/visualizer.ts

@@ -22,7 +22,7 @@ export const mountVisualizer = (root: HTMLElement, source: MachineResult): void
   switch (source._tag) {
     case "Ready":
     case "Partial":
-      renderVisualizer(root, source.document, source.diagnostics)
+      renderVisualizer(root, source.key, source.document, source.diagnostics)
       break
     case "Failed":
       renderError(root, source)

package/src/internal/devServer.ts

@@ -7,6 +7,7 @@ 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"
+import * as ProjectInspector from "../ProjectInspector.js"
 
 type DevServerErrorConstructor = typeof DevServer.DevServerError
 
@@ -41,8 +42,8 @@ const isIgnored = (file: string): boolean =>
     part === "references"
   )
 
-const writeJson = (response: ServerResponse, value: unknown): void => {
-  response.statusCode = 200
+const writeJson = (response: ServerResponse, value: unknown, status = 200): void => {
+  response.statusCode = status
   response.setHeader("content-type", "application/json; charset=utf-8")
   response.setHeader("cache-control", "no-store")
   response.end(JSON.stringify(value))
@@ -54,7 +55,7 @@ const apiPlugin = (
   name: "effect-machine-devtools-api",
   configureServer(server) {
     server.middlewares.use((request: IncomingMessage, response: ServerResponse, next: () => void) => {
-      if (request.url === "/api/machines") {
+      if (request.method === "GET" && request.url === "/api/machines") {
         void Effect.runPromise(registry.get).then(
           (snapshot) => writeJson(response, snapshot),
           (cause) => {
@@ -154,7 +155,11 @@ export const watcherOptions = (options: DevServer.Options): ChokidarOptions =>
 export const run = (
   ErrorType: DevServerErrorConstructor,
   options: DevServer.Options
-): Effect.Effect<never, DevServer.DevServerError, MachineRegistry.MachineRegistry> =>
+): Effect.Effect<
+  never,
+  DevServer.DevServerError,
+  MachineRegistry.MachineRegistry | ProjectInspector.ProjectInspector
+> =>
   Effect.gen(function*() {
     const registry = yield* MachineRegistry.MachineRegistry
     const server = yield* Effect.acquireRelease(

package/src/internal/evaluationWorker.ts

@@ -1,6 +1,7 @@
 import * as NodeWorkerRunner from "@effect/platform-node/NodeWorkerRunner"
-import type { Machine } from "@typeonce/effect-machine"
+import { Machine } from "@typeonce/effect-machine"
 import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
 import * as WorkerRunner from "effect/unstable/workers/WorkerRunner"
 import { resolve } from "node:path"
 import { pathToFileURL } from "node:url"
@@ -10,15 +11,20 @@ import * as MachineDocument from "../MachineDocument.js"
 import type * as ProjectInspector from "../ProjectInspector.js"
 
 interface EvaluationRequest {
+  readonly _tag: "InspectMachines"
   readonly root: string
   readonly revision: number
   readonly candidates: ReadonlyArray<ProjectInspector.Candidate>
 }
 
 interface EvaluationResponse {
+  readonly _tag: "InspectedMachines"
   readonly results: ReadonlyArray<DevToolsProtocol.MachineResult>
 }
 
+type WorkerRequest = EvaluationRequest
+type WorkerResponse = EvaluationResponse
+
 const isMachine = (value: unknown): value is Machine.Machine.Any =>
   typeof value === "object" &&
   value !== null &&
@@ -41,7 +47,22 @@ const diagnostic = (
   statePath: null
 })
 
-const messageOf = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause)
+const messageOf = (cause: unknown): string => {
+  if (Schema.isSchemaError(cause)) return `Invalid machine value: ${cause.message}`
+  if (cause instanceof Error && cause.message.length > 0) return cause.message
+  if (typeof cause === "object" && cause !== null && "cause" in cause && Schema.isSchemaError(cause.cause)) {
+    const boundary = "boundary" in cause ? String(cause.boundary) : "value"
+    return `Invalid machine ${boundary}: ${cause.cause.message}`
+  }
+  try {
+    const encoded = JSON.stringify(cause, null, 2)
+    if (encoded !== undefined && encoded !== "{}") return encoded
+  } catch {
+    // Fall back to the runtime string representation below.
+  }
+  const rendered = String(cause)
+  return rendered.length > 0 ? rendered : "The evaluator failed without a diagnostic message"
+}
 
 const failed = (
   candidate: ProjectInspector.Candidate,
@@ -121,18 +142,15 @@ const handle = (server: ViteDevServer, request: EvaluationRequest): Effect.Effec
   Effect.forEach(request.candidates, (candidate) => evaluateCandidate(server, request, candidate), {
     concurrency: 1
   }).pipe(
-    Effect.map((results) => ({ results: results.flat() }))
+    Effect.map((results) => ({ _tag: "InspectedMachines" as const, results: results.flat() }))
   )
 
-export const run = (server: ViteDevServer): Promise<void> => {
-  return Effect.gen(function*() {
+export const run = (server: ViteDevServer): Promise<void> =>
+  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))
-    )
+    const runner = yield* platform.start<WorkerResponse, WorkerRequest>()
+    yield* runner.run((_portId, request) => Effect.flatMap(handle(server, request), (value) => runner.send(0, value)))
   }).pipe(
     Effect.provide(NodeWorkerRunner.layer),
     Effect.runPromise
   )
-}

package/src/internal/machineDocument.ts

@@ -1,4 +1,5 @@
 import { Machine } from "@typeonce/effect-machine"
+import * as Schema from "effect/Schema"
 import type * as Public from "../MachineDocument.js"
 
 const enabled = Machine.enabled as (
@@ -6,6 +7,72 @@ const enabled = Machine.enabled as (
   snapshot: unknown
 ) => ReadonlyArray<PropertyKey>
 
+const inputEventSchemas = Machine.inputEventSchemas as (
+  machine: Machine.Machine.Any
+) => ReadonlyArray<Machine.Machine.TaggedSchema>
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const resolveReference = (
+  value: unknown,
+  definitions: Readonly<Record<string, unknown>>
+): Record<string, unknown> | undefined => {
+  if (!isRecord(value)) return undefined
+  if (typeof value.$ref !== "string" || !value.$ref.startsWith("#/$defs/")) return value
+  const name = decodeURIComponent(value.$ref.slice("#/$defs/".length))
+  const target = definitions[name]
+  return isRecord(target) ? target : undefined
+}
+
+const tagsOf = (
+  value: unknown,
+  definitions: Readonly<Record<string, unknown>>
+): ReadonlyArray<string> => {
+  const schema = resolveReference(value, definitions)
+  if (schema === undefined || !isRecord(schema.properties)) return []
+  const tag = resolveReference(schema.properties._tag, definitions)
+  if (tag === undefined) return []
+  if (typeof tag.const === "string" || typeof tag.const === "number") return [String(tag.const)]
+  return Array.isArray(tag.enum)
+    ? tag.enum.filter((item): item is string | number => typeof item === "string" || typeof item === "number").map(
+      String
+    )
+    : []
+}
+
+const inputSchema = (schema: Schema.Top): Public.InputSchema => {
+  const document = Schema.toJsonSchemaDocument(schema)
+  return {
+    dialect: document.dialect,
+    schema: document.schema as Schema.Json,
+    definitions: document.definitions as Record<string, Schema.Json>
+  }
+}
+
+const eventInputs = (machine: Machine.Machine.Any): ReadonlyArray<Public.EventInput> => {
+  const inputs: Array<Public.EventInput> = []
+  for (const eventSchema of inputEventSchemas(machine)) {
+    const document = inputSchema(eventSchema)
+    const root = document.schema
+    const record = isRecord(root) ? root : undefined
+    const variants = record !== undefined && Array.isArray(record.anyOf)
+      ? record.anyOf
+      : record !== undefined && Array.isArray(record.oneOf)
+      ? record.oneOf
+      : [root]
+    for (const variant of variants) {
+      for (const event of tagsOf(variant, document.definitions)) {
+        inputs.push({
+          event,
+          schema: { ...document, schema: variant as Schema.Json }
+        })
+      }
+    }
+  }
+  return inputs
+}
+
 const selection = (value: Machine.Machine.TransitionTargetSelection): Public.Selection => ({
   path: value.path ?? null,
   kind: value.kind,
@@ -102,7 +169,7 @@ export const make = <M extends Machine.Machine.Any>(
 
   const initial = Machine.initialDefinition(machine)
   return {
-    schemaVersion: 1,
+    schemaVersion: 3,
     revision: options.revision ?? 0,
     source: options.source ?? null,
     machineId: machine.id ?? "Machine",
@@ -123,16 +190,24 @@ export const make = <M extends Machine.Machine.Any>(
       parent: node.parent ?? null,
       children: [...childPaths.get(node.path) ?? []],
       initial: node.initial ?? null,
+      valueSchema: node.schema === undefined ? null : inputSchema(node.schema),
+      outputSchema: node.output === undefined ? null : inputSchema(node.output),
       transitionIds: [...transitionIds.get(node.path) ?? []],
       activityIds: [...activityIds.get(node.path) ?? []]
     })),
     transitions,
     activities,
+    inputs: {
+      machine: machine.input === undefined ? null : inputSchema(machine.input),
+      events: eventInputs(machine)
+    },
     snapshot: options.snapshot === undefined
       ? null
       : {
         activePaths: Machine.configuration(machine, options.snapshot).map((node) => node.path),
-        candidateEvents: enabled(machine, options.snapshot).map(String)
+        candidateEvents: enabled(machine, options.snapshot)
+          .map(String)
+          .filter((event) => Object.hasOwn(machine.events, event))
       }
   }
 }