@typeonce/effect-machine-devtools 0.23.0 → 0.25.0

package/src/internal/browser/planner-example.ts

@@ -0,0 +1,145 @@
+import { Machine } from "@typeonce/effect-machine"
+import { Schema } from "effect"
+import * as Effect from "effect/Effect"
+
+class Idle extends Schema.TaggedClass<Idle>("PlannerIdle")("Idle", { owner: Schema.String }) {}
+class Working extends Schema.TaggedClass<Working>("PlannerWorking")("Working", {
+  owner: Schema.String,
+  job: Schema.String
+}) {}
+class Finished extends Schema.TaggedClass<Finished>("PlannerFinished")("Finished", { job: Schema.String }) {}
+
+const Owner = Schema.NonEmptyString.annotate({
+  title: "Owner",
+  description: "A non-empty name carried into the initial Idle state."
+})
+const Attempts = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 5 })).annotate({
+  title: "Attempts",
+  description: "An integer between one and five."
+})
+const Labels = Schema.Array(Schema.NonEmptyString).check(Schema.isLengthBetween(1, 3)).annotate({
+  title: "Labels",
+  description: "One to three non-empty labels."
+})
+const Route = Schema.Union([
+  Schema.Literal("direct").annotate({ title: "Direct" }),
+  Schema.Struct({
+    queue: Schema.NonEmptyString.annotate({
+      title: "Queue",
+      description: "The queue used by the queued route."
+    })
+  }).annotate({ title: "Queued" })
+]).annotate({
+  title: "Route",
+  description: "Choose a literal direct route or provide a queue."
+})
+
+class Begin extends Schema.TaggedClass<Begin>("PlannerBegin")("Begin", {
+  job: Schema.NonEmptyString.annotate({
+    title: "Job",
+    description: "A non-empty job name used as the final output."
+  }),
+  priority: Schema.Literals(["normal", "urgent"]).annotate({
+    title: "Priority",
+    description: "Urgent jobs raise AutoFinish during the same macrostep."
+  }),
+  estimate: Schema.Finite.check(Schema.isBetween({ minimum: 0, maximum: 100 })).annotate({
+    title: "Estimate",
+    description: "A numeric estimate between zero and one hundred."
+  }),
+  approved: Schema.Boolean.annotate({
+    title: "Approved",
+    description: "A boolean checkbox included in the event payload."
+  }),
+  notes: Schema.optionalKey(
+    Schema.String.check(Schema.isMaxLength(80)).annotate({
+      title: "Notes",
+      description: "Optional text limited to eighty characters."
+    })
+  ),
+  labels: Schema.optionalKey(Labels),
+  route: Schema.optionalKey(Route)
+}) {}
+class Cancel extends Schema.TaggedClass<Cancel>("PlannerCancel")("Cancel", { reason: Schema.String }) {}
+class AutoFinish extends Schema.TaggedClass<AutoFinish>("PlannerAutoFinish")("AutoFinish", {}) {}
+class Planned extends Schema.TaggedClass<Planned>("PlannerPlanned")("Planned", { job: Schema.String }) {}
+
+const Events = Machine.events(Begin, Cancel)
+const InternalEvents = Machine.internalEvents(AutoFinish)
+const Emissions = Machine.emittedEvents(Planned)
+const States = Machine.states({
+  Idle,
+  Working,
+  Finished: { schema: Finished, type: "final", output: Schema.String }
+})
+
+export const plannerMachine = Machine.make({
+  id: "planner-example",
+  states: States.states,
+  events: Events,
+  internalEvents: InternalEvents,
+  emittedEvents: Emissions,
+  input: Schema.Struct({
+    owner: Owner,
+    attempts: Attempts,
+    notifications: Schema.Boolean.annotate({
+      title: "Notifications",
+      description: "A required boolean with false as a valid value."
+    }),
+    mode: Schema.Literals(["guided", "automatic"]).annotate({
+      title: "Mode",
+      description: "A fixed set of startup modes."
+    }),
+    note: Schema.optionalKey(
+      Schema.String.check(Schema.isMaxLength(40)).annotate({
+        title: "Note",
+        description: "Optional startup text limited to forty characters."
+      })
+    ),
+    labels: Schema.optionalKey(Labels),
+    preferences: Schema.optionalKey(
+      Schema.Struct({
+        retries: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 3 })).annotate({
+          title: "Retries"
+        }),
+        dryRun: Schema.Boolean.annotate({ title: "Dry run" })
+      }).annotate({
+        title: "Preferences",
+        description: "An optional nested object."
+      })
+    )
+  }),
+  initial: (to) => to.Idle().resolve(({ input, target }) => target.decoded(new Idle({ owner: input.owner })))
+}).handle({
+  Idle: {
+    on: {
+      Begin: (to) =>
+        to.branches({
+          urgent: { title: "Finish immediately", target: to.full.Working() },
+          normal: { title: "Wait in working", target: to.full.Working() }
+        }).resolve(({ event, self, select, state }, enqueue) => {
+          enqueue.emit(new Planned({ job: event.job }))
+          enqueue.sendTo(self, Events.Cancel({ reason: "planner command example" }))
+          if (event.priority === "urgent") enqueue.raise(InternalEvents.AutoFinish())
+          const working = new Working({ owner: state.owner, job: event.job })
+          return event.priority === "urgent"
+            ? select.urgent.decoded(working)
+            : select.normal.decoded(working)
+        })
+    }
+  },
+  Working: {
+    invoke: (from) => from.effect("monitor-job", () => Effect.never),
+    on: {
+      AutoFinish: (to) =>
+        to.full.Finished().resolve(({ state, target }) => target.decoded(new Finished({ job: state.job }))),
+      Cancel: (to) =>
+        to.full.Idle().resolve(({ event, state, target }) =>
+          target.decoded(new Idle({ owner: `${state.owner} · ${event.reason}` }))
+        )
+    }
+  },
+  Finished: {
+    output: ({ state }) => state.job
+  }
+})

package/src/internal/browser/protocol-events-example.ts

@@ -0,0 +1,200 @@
+import { Machine } from "@typeonce/effect-machine"
+import { Schema } from "effect"
+
+class ChildProgress extends Schema.TaggedClass<ChildProgress>("ProtocolChildProgress")("ChildProgress", {
+  percent: Schema.Number
+}) {}
+class ChildFinished extends Schema.TaggedClass<ChildFinished>("ProtocolChildFinished")("ChildFinished", {
+  result: Schema.String
+}) {}
+class ChildProblem extends Schema.TaggedClass<ChildProblem>("ProtocolChildProblem")("ChildProblem", {
+  message: Schema.String
+}) {}
+
+const ParentEvents = Machine.events(ChildProgress, ChildFinished, ChildProblem)
+
+class ChildIdle extends Schema.TaggedClass<ChildIdle>("ProtocolChildIdle")("Idle", {}) {}
+class ChildWorking extends Schema.TaggedClass<ChildWorking>("ProtocolChildWorking")("Working", {
+  job: Schema.String,
+  progress: Schema.Number
+}) {}
+class ChildDone extends Schema.TaggedClass<ChildDone>("ProtocolChildDone")("Done", {
+  result: Schema.String
+}) {}
+class ChildCancelled extends Schema.TaggedClass<ChildCancelled>("ProtocolChildCancelled")("Cancelled", {
+  reason: Schema.String
+}) {}
+
+class BeginChildWork extends Schema.TaggedClass<BeginChildWork>("ProtocolBeginChildWork")("BeginChildWork", {
+  job: Schema.String
+}) {}
+class CancelChildWork extends Schema.TaggedClass<CancelChildWork>("ProtocolCancelChildWork")(
+  "CancelChildWork",
+  { reason: Schema.String }
+) {}
+class Heartbeat extends Schema.TaggedClass<Heartbeat>("ProtocolHeartbeat")("Heartbeat", {
+  percent: Schema.Number
+}) {}
+class CommitChildWork extends Schema.TaggedClass<CommitChildWork>("ProtocolCommitChildWork")(
+  "CommitChildWork",
+  {}
+) {}
+class ChildTrace extends Schema.TaggedClass<ChildTrace>("ProtocolChildTrace")("ChildTrace", {
+  message: Schema.String
+}) {}
+
+const ChildEvents = Machine.events(BeginChildWork, CancelChildWork)
+const ChildInternalEvents = Machine.internalEvents(Heartbeat, CommitChildWork)
+const ChildEmissions = Machine.emittedEvents(ChildTrace)
+const ChildStates = Machine.states({
+  Idle: ChildIdle,
+  Working: ChildWorking,
+  Done: { schema: ChildDone, type: "final", output: Schema.String },
+  Cancelled: { schema: ChildCancelled, type: "final", output: Schema.String }
+})
+
+export const requiredParentChildMachine = Machine.make({
+  id: "required-parent-child",
+  states: ChildStates.states,
+  events: ChildEvents,
+  internalEvents: ChildInternalEvents,
+  emittedEvents: ChildEmissions,
+  parent: Machine.parent(ParentEvents),
+  initial: (to) => to.Idle().resolve(({ target }) => target.decoded(new ChildIdle({})))
+}).handle({
+  Idle: {
+    on: {
+      BeginChildWork: (to) =>
+        to.full.Working().resolve(({ event, target }, enqueue) => {
+          enqueue.raise(ChildInternalEvents.Heartbeat({ percent: 25 }))
+          enqueue.emit(ChildEmissions.ChildTrace({ message: `started ${event.job}` }))
+          return target.decoded(new ChildWorking({ job: event.job, progress: 0 }))
+        })
+    }
+  },
+  Working: {
+    invoke: (from) =>
+      from.effect(
+        "report-progress-to-parent",
+        ({ parent, state }) => parent.send(ParentEvents.ChildProgress({ percent: state.progress }))
+      ).onDone((to) => to.none).onFailure((to) =>
+        to.full.Cancelled().resolve(({ error, target }) =>
+          target.decoded(new ChildCancelled({ reason: String(error) }))
+        )
+      ),
+    on: {
+      Heartbeat: (to) =>
+        to.full.Working().resolve(({ event, state, target }, enqueue) => {
+          enqueue.raise(ChildInternalEvents.CommitChildWork())
+          return target.decoded(new ChildWorking({ job: state.job, progress: event.percent }))
+        }),
+      CommitChildWork: (to) =>
+        to.full.Done().resolve(({ state, target }) =>
+          target.decoded(new ChildDone({ result: `${state.job}:complete` }))
+        ),
+      CancelChildWork: (to) =>
+        to.full.Cancelled().resolve(({ event, target }) => target.decoded(new ChildCancelled({ reason: event.reason })))
+    }
+  },
+  Done: {
+    output: ({ state }) => state.result
+  },
+  Cancelled: {
+    output: ({ state }) => state.reason
+  }
+})
+
+const ProtocolChild = Machine.child("protocol-child", requiredParentChildMachine)
+
+class ParentIdle extends Schema.TaggedClass<ParentIdle>("ProtocolParentIdle")("Idle", {}) {}
+class Supervising extends Schema.TaggedClass<Supervising>("ProtocolSupervising")("Supervising", {
+  latestProgress: Schema.Number
+}) {}
+class ParentComplete extends Schema.TaggedClass<ParentComplete>("ProtocolParentComplete")("Complete", {
+  result: Schema.String
+}) {}
+class ParentFailed extends Schema.TaggedClass<ParentFailed>("ProtocolParentFailed")("Failed", {
+  message: Schema.String
+}) {}
+class LaunchChild extends Schema.TaggedClass<LaunchChild>("ProtocolLaunchChild")("LaunchChild", {}) {}
+class ResetParent extends Schema.TaggedClass<ResetParent>("ProtocolResetParent")("ResetParent", {}) {}
+
+const ParentStates = Machine.states({
+  Idle: ParentIdle,
+  Supervising,
+  Complete: { schema: ParentComplete, type: "final", output: Schema.String },
+  Failed: ParentFailed
+})
+
+export const parentProtocolMachine = Machine.make({
+  id: "parent-child-protocol",
+  states: ParentStates.states,
+  events: Machine.events(LaunchChild, ResetParent, ParentEvents),
+  initial: (to) => to.Idle().resolve(({ target }) => target.decoded(new ParentIdle({})))
+}).handle({
+  Idle: {
+    on: {
+      LaunchChild: (to) =>
+        to.full.Supervising().resolve(({ target }) => target.decoded(new Supervising({ latestProgress: 0 })))
+    }
+  },
+  Supervising: {
+    invoke: (from) =>
+      from.child(ProtocolChild).onDone((to) =>
+        to.full.Complete().resolve(({ output, target }) => target.decoded(new ParentComplete({ result: output })))
+      ).onFailure((to) =>
+        to.full.Failed().resolve(({ error, target }) => target.decoded(new ParentFailed({ message: String(error) })))
+      ),
+    on: {
+      ChildProgress: (to) =>
+        to.full.Supervising().resolve(({ event, target }) =>
+          target.decoded(new Supervising({ latestProgress: event.percent }))
+        ),
+      ChildFinished: (to) =>
+        to.full.Complete().resolve(({ event, target }) => target.decoded(new ParentComplete({ result: event.result }))),
+      ChildProblem: (to) =>
+        to.full.Failed().resolve(({ event, target }) => target.decoded(new ParentFailed({ message: event.message }))),
+      ResetParent: (to) => to.full.Idle().resolve(({ target }) => target.decoded(new ParentIdle({})))
+    }
+  },
+  Complete: {
+    output: ({ state }) => state.result
+  },
+  Failed: {
+    on: {
+      ResetParent: (to) => to.full.Idle().resolve(({ target }) => target.decoded(new ParentIdle({})))
+    }
+  }
+})
+
+class Detached extends Schema.TaggedClass<Detached>("OptionalParentDetached")("Detached", {}) {}
+class Published extends Schema.TaggedClass<Published>("OptionalParentPublished")("Published", {
+  deliveredToParent: Schema.Boolean
+}) {}
+class PublishOutside extends Schema.TaggedClass<PublishOutside>("OptionalParentPublishOutside")(
+  "PublishOutside",
+  { result: Schema.String }
+) {}
+
+const OptionalParentStates = Machine.states({ Detached, Published })
+
+export const optionalParentMachine = Machine.make({
+  id: "optional-parent-protocol",
+  states: OptionalParentStates.states,
+  events: Machine.events(PublishOutside),
+  parent: Machine.optionalParent(ParentEvents),
+  initial: (to) => to.Detached().resolve(({ target }) => target.decoded(new Detached({})))
+}).handle({
+  Detached: {
+    on: {
+      PublishOutside: (to) =>
+        to.full.Published().resolve(({ event, parent, target }, enqueue) => {
+          if (parent !== undefined) {
+            enqueue.sendTo(parent, ParentEvents.ChildFinished({ result: event.result }))
+          }
+          return target.decoded(new Published({ deliveredToParent: parent !== undefined }))
+        })
+    }
+  },
+  Published: {}
+})