@typeonce/effect-machine 0.14.0 → 0.15.0

package/src/internal/machine/machine.ts

@@ -11,6 +11,7 @@ import type {
   ChildAddress,
   ChildMachine,
   Command,
+  Definition,
   ExecutionServices,
   InitialEvent as InitialEventModel,
   Logic,
@@ -79,7 +80,14 @@ type ValidateDefinedStates<States extends Machine.StateSchemas> = [States] exten
 type InvalidDefinedStateTreeInput<States extends Machine.StateSchemas> = [States] extends
   [Machine.ValidateStateSchemas<States>] ? never
   : States & Machine.ValidateStateSchemas<States>
-interface DefineStates {
+type ReusableStateNodeConfig =
+  | Machine.AtomicStateNodeConfig
+  | Machine.CompoundStateNodeConfig
+  | Machine.ParallelStateNodeConfig
+interface StateConstructor {
+  <const Node extends ReusableStateNodeConfig>(node: Node): Node
+}
+interface StatesConstructor {
   <const States extends Machine.StateSchemas>(
     states: States,
     ..._validation: ValidateDefinedStates<NoInfer<States>>
@@ -106,8 +114,8 @@ const Proto = {
 
 const makeBoundInvoke = (config: unknown): unknown => config
 
-const cloneWithHandlers = (
-  self: Machine.Any,
+const makeWithHandlers = (
+  self: Definition.Any,
   handlers: Machine.StateConfigs<any, any, any, any, any, any, any>
 ): Machine.Any => {
   const machine = Object.create(Proto)
@@ -123,7 +131,6 @@ const cloneWithHandlers = (
   machine.stateNodes = self.stateNodes
   machine.makeTargetBuilder = self.makeTargetBuilder
   machine.handlers = handlers
-  machine.handle = makeHandle(machine)
   machine.invoke = makeBoundInvoke
   Protocol.copyProtocol(self, machine)
   return machine
@@ -220,7 +227,13 @@ const makeTargetSelector = (
   branch[root.key] = makeSelectionNode(stateNodes, root.path, "branch")
   const local: Record<string, unknown> = {}
   const localScope = getLocalTargetScope(stateNodes, source)
-  if (localScope !== undefined) addSelectionChildren(local, stateNodes, localScope, "local")
+  if (localScope !== undefined) {
+    const localScopeNode = getTargetBuilderNode(stateNodes, localScope)
+    if (localScopeNode.schema !== undefined) {
+      local.with = makeSelectionMethod("state", localScope, "local")
+    }
+    addSelectionChildren(local, stateNodes, localScope, "local")
+  }
   return {
     none: makeSelectionMethod("none", undefined, "local"),
     local,
@@ -263,7 +276,14 @@ const getSelectionBuilder = (
   } else if (selection.scope === "local") {
     builder = target.local
     const scope = getLocalTargetScope(stateNodes, source)
-    if (scope !== undefined) parts = selection.path!.slice(scope.length + 1).split(".")
+    if (scope !== undefined) {
+      if (selection.path === scope) {
+        builder = builder.with
+        parts = []
+      } else {
+        parts = selection.path!.slice(scope.length + 1).split(".")
+      }
+    }
   } else if (selection.scope === "branch") {
     builder = target.branch
   } else {
@@ -512,15 +532,12 @@ const flattenHandlers = (
   }
 }
 
-const makeHandle = (self: Machine.Any): Machine.Any["handle"] =>
+const makeHandle = (self: Definition.Any): Definition.Any["handle"] =>
   ((config: Record<string, unknown>) => {
-    const handlers: Record<PropertyKey, Machine.AnyStateConfig> = Object.assign(
-      Object.create(null),
-      self.handlers
-    )
+    const handlers: Record<PropertyKey, Machine.AnyStateConfig> = Object.create(null)
     flattenHandlers(handlers, self.stateNodes, self.states, "", config)
-    return cloneWithHandlers(self, handlers)
-  }) as Machine.Any["handle"]
+    return makeWithHandlers(self, handlers)
+  }) as Definition.Any["handle"]
 
 export const isMachine = (
   u: unknown
@@ -1128,12 +1145,19 @@ const compileInitial = (
   }
 }
 
-export const defineStates: DefineStates = (<const States extends Machine.StateSchemas>(
+export const state: StateConstructor = (<const Node extends ReusableStateNodeConfig>(node: Node): Node => {
+  StateDefinition.validateStateDefinitions({ state: node }, "Machine.state")
+  return StateDefinition.captureStateDefinitions({ state: node }).state
+}) as StateConstructor
+
+export const states: StatesConstructor = (<const States extends Machine.StateSchemas>(
   states: States
 ): Machine.DefinedStates<States> => {
-  StateDefinition.validateStateDefinitions(states, "Machine.defineStates")
+  StateDefinition.validateStateDefinitions(states, "Machine.states")
+  const captured = StateDefinition.captureStateDefinitions(states)
   return {
-    states,
+    states: captured,
+    path: ((path: string) => path) as Machine.DefinedStates<States>["path"],
     get:
       ((snapshot: Machine.AtomicSnapshot<string, unknown>, path: string) =>
         Topology.getSnapshotByPath(snapshot, path).pipe(
@@ -1150,7 +1174,7 @@ export const defineStates: DefineStates = (<const States extends Machine.StateSc
       ((snapshot: Machine.AtomicSnapshot<string, unknown>, path: string) =>
         Option.isSome(Topology.getSnapshotByPath(snapshot, path))) as Machine.DefinedStates<States>["matches"]
   }
-}) as DefineStates
+}) as StatesConstructor
 
 type MakeConfig<
   States extends Machine.StateSchemas,
@@ -1188,19 +1212,15 @@ type MakeResult<
   InitialR,
   InternalEvents extends ReadonlyArray<Machine.TaggedSchema>,
   ParentEvents extends ReadonlyArray<Machine.TaggedSchema>
-> = Machine<
+> = Definition<
   States,
   readonly [...InputEvents, ...InternalEvents],
   Input,
-  Machine.StateIdentifier<States>,
-  never,
-  never,
   InitialE,
   InitialR,
   Machine.FinalStateFromDefinition<States>,
   Machine.TerminalOutput<States>,
   Emits,
-  never,
   InputEvents,
   ParentEvents
 >

package/src/internal/machine/stateDefinition.ts

@@ -18,7 +18,7 @@ export type AllowedStateNodeProperty<Kind extends StateNodeKind> = (typeof State
 
 export type AllowedPseudoStateAnnotationProperty = (typeof PseudoStateAnnotationProperties)[number]
 
-export type StateDefinitionBoundary = "Machine.defineStates" | "Machine.make"
+export type StateDefinitionBoundary = "Machine.state" | "Machine.states" | "Machine.make"
 
 const hasOwn = (value: object, key: PropertyKey): boolean => Object.prototype.hasOwnProperty.call(value, key)
 
@@ -279,3 +279,43 @@ export const validateStateDefinitions = (
   states: unknown,
   boundary: StateDefinitionBoundary
 ): void => validateStateTree(boundary, states, "", false)
+
+const captureAnnotations = (annotations: unknown): unknown =>
+  typeof annotations === "object" && annotations !== null
+    ? Object.freeze({ ...annotations })
+    : annotations
+
+const captureStateTree = (states: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> => {
+  const captured: Record<string, unknown> = {}
+  for (const key of Object.keys(states)) {
+    const node = states[key]
+    if (Schema.isSchema(node)) {
+      Object.defineProperty(captured, key, {
+        value: node,
+        enumerable: true,
+        configurable: false,
+        writable: false
+      })
+      continue
+    }
+    const config = node as Readonly<Record<string, unknown>>
+    const copy: Record<string, unknown> = { ...config }
+    if ("states" in config) {
+      copy.states = captureStateTree(config.states as Readonly<Record<string, unknown>>)
+    }
+    if ("annotations" in config) {
+      copy.annotations = captureAnnotations(config.annotations)
+    }
+    Object.defineProperty(captured, key, {
+      value: Object.freeze(copy),
+      enumerable: true,
+      configurable: false,
+      writable: false
+    })
+  }
+  return Object.freeze(captured)
+}
+
+/** Captures caller-owned structural containers while preserving schema identity. */
+export const captureStateDefinitions = <States>(states: States): States =>
+  captureStateTree(states as Readonly<Record<string, unknown>>) as States

package/src/internal/testing/machine/finiteModel.ts

@@ -1509,7 +1509,7 @@ export const compileModel = (model: FiniteModel): Machine.Machine.Any => {
   const flattened = validateModel(model)
   const byPath = new Map(flattened.map((state) => [state.path, state]))
   const stateTree = makeStateTree(model.roots, undefined)
-  const defined = Machine.defineStates(stateTree as any)
+  const defined = Machine.states(stateTree as any)
   const eventSchemas = model.events.map((event) => Schema.TaggedStruct(event, {}))
   const initial = byPath.get(model.initial)!
   const machine = Machine.make({

package/src/testing/MachineTest.ts

@@ -227,7 +227,7 @@ export interface Scenarios<M extends AnyMachine> {
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
  * class Reset extends Schema.TaggedClass<Reset>("Reset")("Reset", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(Reset),
@@ -488,7 +488,7 @@ export { ProbeUnavailableError } from "../internal/testing/machine/verification.
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -1101,7 +1101,7 @@ export const Invariant: {
  * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
  *   value: Schema.Number
  * }) {}
- * const States = Machine.defineStates({ Count })
+ * const States = Machine.states({ Count })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -1436,7 +1436,7 @@ export type ExploreOptions<M extends AnyMachine, Key extends ExplorationKey = Ex
  *   value: Schema.Number
  * }) {}
  * class Increment extends Schema.TaggedClass<Increment>("Increment")("Increment", {}) {}
- * const States = Machine.defineStates({ Count })
+ * const States = Machine.states({ Count })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(Increment),
@@ -1629,7 +1629,7 @@ export type RunServices<M extends AnyMachine> = IsAny<
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -1893,7 +1893,7 @@ export interface Coverage<M extends AnyMachine> {
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -2118,7 +2118,7 @@ export interface VerifyOptions {
  * import { MachineTest } from "@typeonce/effect-machine/testing"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),

package/src/unstable/cluster/ClusterMachine.ts

@@ -312,7 +312,7 @@ export const layerMemory: Layer.Layer<Storage> = internal.layerMemory
  * import { ClusterMachine } from "@typeonce/effect-machine/cluster"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),

package/src/unstable/reactivity/AtomMachine.ts

@@ -366,7 +366,7 @@ type ChildState<Child extends Machine.ChildMachine.Any> = RefState<Machine.Child
  * class Count extends Schema.TaggedClass<Count>("Count")("Count", {
  *   value: Schema.Number
  * }) {}
- * const States = Machine.defineStates({ Count })
+ * const States = Machine.states({ Count })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -480,7 +480,7 @@ export const selectSnapshotChild: <
  * import { AtomMachine } from "@typeonce/effect-machine/reactivity"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),
@@ -653,7 +653,7 @@ export interface Bound<Services, RuntimeError = never> {
  * import { AtomMachine } from "@typeonce/effect-machine/reactivity"
  *
  * class Idle extends Schema.TaggedClass<Idle>("Idle")("Idle", {}) {}
- * const States = Machine.defineStates({ Idle })
+ * const States = Machine.states({ Idle })
  * const machine = Machine.make({
  *   states: States.states,
  *   events: Machine.events(),