@typeonce/effect-machine 0.10.0 → 0.12.0

package/src/internal/machine/process.ts

@@ -459,7 +459,7 @@ const makeProcessLogic: <
   ) =>
     compiledInitial === undefined
       ? internalRuntime.provideMachineRuntime(
-        internalPlanner.planInitial(internalPlanner.withActorScope(machine, scope), ...initialArgs).pipe(
+        internalPlanner.planInitial(internalPlanner.withMachineReferences(machine, scope), ...initialArgs).pipe(
           Effect.flatMap((planned) => {
             const commands = planned.commands.length === 0
               ? undefined
@@ -540,7 +540,7 @@ const makeProcessLogic: <
               try {
                 planned = internalPlanner.planConfiguration(
                   machine,
-                  Configuration.withActorScope(
+                  Configuration.withMachineReferences(
                     configuration ?? Configuration.normalizeConfigurationSync(machine, current),
                     context
                   ),
@@ -651,7 +651,7 @@ const makeProcessLogic: <
               try {
                 planned = internalPlanner.planConfiguration(
                   machine,
-                  Configuration.withActorScope(
+                  Configuration.withMachineReferences(
                     configuration ?? Configuration.normalizeConfigurationSync(machine, current),
                     context
                   ),
@@ -825,6 +825,18 @@ export const startWithRuntimeStrategyForTesting = (
     machine.id === undefined ? undefined : { id: machine.id }
   )
 
+/** @internal Test-only prepared startup strategy selection for a fresh machine. */
+export const prepareWithRuntimeStrategyForTesting = (
+  machine: Machine.Any,
+  strategy: internalRuntime.ProcessRuntimeStrategy,
+  ...args: ReadonlyArray<unknown>
+): Effect.Effect<internalRuntime.PreparedProcess<any, any, any, any, any, any, any>, any, any> =>
+  internalRuntime.prepareProcessWithStrategyForTesting(
+    (toProcessLogic as any)(machine, ...args),
+    strategy,
+    machine.id === undefined ? undefined : { id: machine.id }
+  )
+
 /** @internal Test-only runtime strategy selection for a resumed machine. */
 export const resumeWithRuntimeStrategyForTesting = (
   machine: Machine.Any,
@@ -881,6 +893,51 @@ export const start: <
     machine.id === undefined ? undefined : { id: machine.id }
   ) as any
 
+export const prepare: <
+  const States extends Machine.StateSchemas,
+  const Events extends ReadonlyArray<Machine.TaggedSchema>,
+  const Emits extends ReadonlyArray<Machine.TaggedSchema> = readonly [],
+  const Input extends Schema.Top = typeof Schema.Void,
+  UnhandledStates extends Machine.StateIdentifier<States> = Machine.StateIdentifier<States>,
+  E = never,
+  R = never,
+  InitialE = never,
+  InitialR = never,
+  FinalStates extends Machine.StateIdentifier<States> = never,
+  Output = never
+>(
+  machine: Machine<States, Events, Input, UnhandledStates, E, R, InitialE, InitialR, FinalStates, Output, Emits>,
+  ...args: [...Machine.InputArgs<Input>]
+) => Effect.Effect<
+  internalRuntime.PreparedProcess<
+    Machine.Snapshot<States>,
+    Machine.EventOf<Events>,
+    | E
+    | ActionError<R>
+    | InfiniteTransitionError
+    | MachineSchemaDecodeError
+    | StoppedError,
+    Output,
+    Machine.EmittedEventOf<Emits>,
+    | InitialE
+    | E
+    | ActionError<InitialR | R>
+    | InfiniteTransitionError
+    | MachineSchemaDecodeError
+    | StartupError
+    | StoppedError,
+    ExcludeCompatibleRuntime<
+      Exclude<ExecutionServices<InitialR | R>, internalRuntime.MachineRuntime>,
+      Machine.EventOf<Events>,
+      Machine.EmitOf<Emits>
+    >
+  >
+> = (machine, ...args) =>
+  internalRuntime.prepareProcess(
+    toProcessLogic(machine, ...args),
+    machine.id === undefined ? undefined : { id: machine.id }
+  ) as any
+
 export const resume: <
   const States extends Machine.StateSchemas,
   const Events extends ReadonlyArray<Machine.TaggedSchema>,

package/src/internal/machine/runtime.ts

@@ -18,7 +18,7 @@ import * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
 import * as SynchronizedRef from "effect/SynchronizedRef"
 import type * as Take from "effect/Take"
-import type { ActorRef } from "../../Machine.js"
+import type { MachineTarget } from "../../Machine.js"
 import { ChildAlreadyExistsError, StoppedError } from "./errors.js"
 
 type ChildDescriptor = {
@@ -302,6 +302,22 @@ export interface MachineRef<out State, in Event, out Error = never, out Output =
   readonly childChanges: (child: any) => Stream.Stream<Option.Option<any>>
 }
 
+export interface PreparedProcess<
+  out State,
+  in Event,
+  out Error,
+  out Output,
+  out Emitted,
+  out StartError,
+  StartRequirements
+> {
+  readonly id: string
+  readonly sessionId: string
+  readonly changes: Stream.Stream<RuntimeSnapshot<State, Error, Output>, StartError>
+  readonly emissions: Stream.Stream<Emitted>
+  readonly start: Effect.Effect<MachineRef<State, Event, Error, Output, Emitted>, StartError, StartRequirements>
+}
+
 interface ProcessAddress<in Event> {
   readonly id: string
   readonly sessionId: string
@@ -309,7 +325,7 @@ interface ProcessAddress<in Event> {
   readonly send: (event: Event) => Effect.Effect<void, StoppedError>
 }
 
-const isProcessAddress = (value: unknown): value is ActorRef<unknown> =>
+const isProcessAddress = (value: unknown): value is MachineTarget<unknown> =>
   typeof value === "object" && value !== null && "send" in value && typeof value.send === "function"
 
 export interface ProcessScope<Event> {
@@ -319,7 +335,7 @@ export interface ProcessScope<Event> {
   readonly sendParent: (event: unknown) => Effect.Effect<void, StoppedError>
   readonly emit: (event: unknown) => Effect.Effect<void>
   readonly sendTo: {
-    <TargetEvent>(target: ActorRef<TargetEvent>, event: TargetEvent): Effect.Effect<void, StoppedError>
+    <TargetEvent>(target: MachineTarget<TargetEvent>, event: TargetEvent): Effect.Effect<void, StoppedError>
     (child: ChildSelector, event: unknown): Effect.Effect<void, StoppedError>
   }
   readonly stopChild: (child: ChildSelector) => Effect.Effect<void>
@@ -351,7 +367,7 @@ export interface ProcessContext<State, Event> extends ProcessScope<Event> {
  *
  * Unlike `ProcessContext`, synchronous mailbox and state operations do not
  * introduce an Effect boundary. The compiled drain still returns an Effect so
- * actor commands, invokes, observation callbacks, interruption, and the Effect
+ * machine commands, invokes, observation callbacks, interruption, and the Effect
  * scheduler remain explicit at their actual boundaries.
  *
  * @internal
@@ -609,6 +625,8 @@ const makeProcessRuntime: Effect.Effect<ProcessRuntime> = Effect.sync(() => {
 interface StartInternalOptions {
   readonly detached?: boolean
   readonly id?: string
+  readonly sessionId?: string
+  readonly emissions?: EmissionRuntime
   readonly onOutcome?: (outcome: RuntimeOutcome<any, any, any>) => Effect.Effect<void>
   readonly onSnapshot?: (
     snapshot: Extract<RuntimeSnapshot<any, any, any>, { readonly status: "active" }>
@@ -802,6 +820,54 @@ const EmissionsClosed: unique symbol = Symbol("effect/Machine/EmissionsClosed")
 
 type LazyEmissions = PubSub.PubSub<unknown> | typeof EmissionsClosed | undefined
 
+interface EmissionRuntime {
+  readonly emit: (event: unknown) => Effect.Effect<void>
+  readonly close: () => Effect.Effect<void>
+  readonly stream: Stream.Stream<unknown>
+}
+
+const makeEmissionRuntime = (): EmissionRuntime => {
+  let emissions: LazyEmissions
+  const getOrCreate: Effect.Effect<PubSub.PubSub<unknown> | undefined> = Effect.suspend(() => {
+    const observed = emissions
+    if (observed === EmissionsClosed) return Effect.succeed(undefined)
+    if (observed !== undefined) return Effect.succeed(observed)
+    return PubSub.unbounded<unknown>().pipe(
+      Effect.flatMap((candidate) =>
+        Effect.sync(() => {
+          const latest = emissions
+          if (latest === EmissionsClosed) return [undefined, true] as const
+          if (latest !== undefined) return [latest, true] as const
+          emissions = candidate
+          return [candidate, false] as const
+        }).pipe(
+          Effect.flatMap(([selected, discard]) =>
+            discard ? PubSub.shutdown(candidate).pipe(Effect.as(selected)) : Effect.succeed(selected)
+          )
+        )
+      )
+    )
+  })
+  return {
+    emit: (event) =>
+      Effect.suspend(() =>
+        emissions === undefined || emissions === EmissionsClosed
+          ? Effect.void
+          : PubSub.publish(emissions, event).pipe(Effect.asVoid)
+      ),
+    close: () => {
+      const observed = emissions
+      emissions = EmissionsClosed
+      return observed === undefined || observed === EmissionsClosed ? Effect.void : PubSub.shutdown(observed)
+    },
+    stream: Stream.unwrap(
+      getOrCreate.pipe(
+        Effect.map((emissions) => emissions === undefined ? Stream.empty : Stream.fromPubSub(emissions))
+      )
+    )
+  }
+}
+
 const childlessRuntime: ChildRuntime = {
   close: () => Effect.void,
   spawn: (() => Effect.die(new Error("Childless machine logic cannot spawn a process"))) as ProcessSpawn,
@@ -1104,41 +1170,10 @@ const startGenericInternal: <
     | { readonly _tag: "Done"; readonly output: Output }
     | { readonly _tag: "Failure"; readonly cause: Cause.Cause<Error> }
 
-  const sessionId = yield* runtime.nextSessionId
+  const sessionId = options.sessionId ?? (yield* runtime.nextSessionId)
   const id = requestedId ?? sessionId
   const queue = yield* Queue.unbounded<ProcessMessage<Event>>()
-  let emissions: LazyEmissions
-  const getOrCreateEmissions: Effect.Effect<PubSub.PubSub<unknown> | undefined> = Effect.suspend(() => {
-    const observed = emissions
-    if (observed === EmissionsClosed) return Effect.succeed(undefined)
-    if (observed !== undefined) return Effect.succeed(observed)
-    return PubSub.unbounded<unknown>().pipe(
-      Effect.flatMap((candidate) =>
-        Effect.sync(() => {
-          const latest = emissions
-          if (latest === EmissionsClosed) return [undefined, true] as const
-          if (latest !== undefined) return [latest, true] as const
-          emissions = candidate
-          return [candidate, false] as const
-        }).pipe(
-          Effect.flatMap(([selected, discard]) =>
-            discard ? PubSub.shutdown(candidate).pipe(Effect.as(selected)) : Effect.succeed(selected)
-          )
-        )
-      )
-    )
-  })
-  const closeEmissions = (): Effect.Effect<void> => {
-    const observed = emissions
-    emissions = EmissionsClosed
-    return observed === undefined || observed === EmissionsClosed ? Effect.void : PubSub.shutdown(observed)
-  }
-  const emit = (event: unknown): Effect.Effect<void> =>
-    Effect.suspend(() =>
-      emissions === undefined || emissions === EmissionsClosed
-        ? Effect.void
-        : PubSub.publish(emissions, event).pipe(Effect.asVoid)
-    )
+  const emissions = options.emissions ?? makeEmissionRuntime()
   const termination = yield* Deferred.make<ProcessTermination>()
   const done = yield* Deferred.make<Output, Error | StoppedError>()
   const awaitCompletion = Deferred.await(done).pipe(Effect.exit, Effect.asVoid)
@@ -1209,7 +1244,7 @@ const startGenericInternal: <
   }
   const cleanupStartupFailure = <A, E>(exit: Exit.Exit<A, E>): Effect.Effect<void> =>
     Exit.isFailure(exit)
-      ? closeChildren(exit).pipe(Effect.andThen(closeEmissions()))
+      ? closeChildren(exit).pipe(Effect.andThen(emissions.close()))
       : Effect.void
   const cleanup = onStopSync === undefined ? onStop ?? Effect.void : Effect.sync(onStopSync)
   const sendParent = overrideSendParent ?? (parent === undefined ? noParentSend : parent.send)
@@ -1219,7 +1254,7 @@ const startGenericInternal: <
     parent,
     spawn,
     sendParent,
-    emit,
+    emit: emissions.emit,
     sendTo: ((target: unknown, event: unknown) =>
       isProcessAddress(target) ? target.send(event) : sendTo(target as ChildSelector, event)) as ProcessScope<
         Event
@@ -1402,7 +1437,7 @@ const startGenericInternal: <
         Effect.andThen(Queue.shutdown(queue)),
         Effect.andThen(closeChildren(exit)),
         Effect.andThen(setAndPublishSnapshot(snapshot)),
-        Effect.andThen(closeEmissions()),
+        Effect.andThen(emissions.close()),
         Effect.andThen(Effect.sync(() => {
           if (Exit.isFailure(exit)) {
             failAcknowledgedMessage(inFlightMessage, exit.cause)
@@ -1559,11 +1594,7 @@ const startGenericInternal: <
     state: SynchronizedRef.get(current).pipe(Effect.map((current) => current.snapshot.state)),
     snapshot: SynchronizedRef.get(current).pipe(Effect.map((current) => current.snapshot)),
     changes: changesStream,
-    emissions: Stream.unwrap(
-      getOrCreateEmissions.pipe(
-        Effect.map((emissions) => emissions === undefined ? Stream.empty : Stream.fromPubSub(emissions))
-      )
-    ) as Stream.Stream<never>,
+    emissions: emissions.stream as Stream.Stream<never>,
     join: Deferred.await(done),
     stop,
     send: self.send,
@@ -1717,6 +1748,7 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
   private interruptRequested = false
   private offerRevision = 0
   private inFlightMessage: ProcessMessage<unknown> | undefined
+  private readonly externalEmissions: EmissionRuntime | undefined
   private emissionsPubSub: LazyEmissions
 
   constructor(
@@ -1727,6 +1759,7 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
   ) {
     this.sessionId = sessionId
     this.id = options.id ?? sessionId
+    this.externalEmissions = options.emissions
     this.send = (event) => this.offerMessage(event)
     this.address = {
       id: this.id,
@@ -1908,7 +1941,7 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
   }
 
   get emissions(): Stream.Stream<never> {
-    return this.emissionsStream() as Stream.Stream<never>
+    return (this.externalEmissions?.stream ?? this.emissionsStream()) as Stream.Stream<never>
   }
 
   get join(): Effect.Effect<unknown, unknown> {
@@ -2268,6 +2301,7 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
   }
 
   private emitEvent(event: unknown): Effect.Effect<void> {
+    if (this.externalEmissions !== undefined) return this.externalEmissions.emit(event)
     return Effect.suspend(() =>
       this.emissionsPubSub === undefined || this.emissionsPubSub === EmissionsClosed
         ? Effect.void
@@ -2280,6 +2314,7 @@ class CompiledProcess implements MachineRef<any, any, any, any> {
   }
 
   private closeEmissions(): Effect.Effect<void> {
+    if (this.externalEmissions !== undefined) return this.externalEmissions.close()
     const observed = this.emissionsPubSub
     this.emissionsPubSub = EmissionsClosed
     return observed === undefined || observed === EmissionsClosed ? Effect.void : PubSub.shutdown(observed)
@@ -2523,7 +2558,7 @@ const startCompactCompiledInternal: typeof startGenericInternal = Effect.fnUntra
   logic: ProcessLogic<any, any, any, any, any, any>,
   options: StartInternalOptions
 ) {
-  const sessionId = yield* options.runtime.nextSessionId
+  const sessionId = options.sessionId ?? (yield* options.runtime.nextSessionId)
   const services = yield* Effect.context<any>()
   const execution = logic.execution as CompiledProcessExecution<any, any, any, any, any, any>
   const process = new CompiledProcess(logic, options, services, sessionId)
@@ -2636,3 +2671,97 @@ export const startProcess: <
       }
   )
 })
+
+const prepareProcessWithStrategy = Effect.fnUntraced(function*<
+  State,
+  Event,
+  Error,
+  Requirements,
+  Output,
+  InitialError,
+  Emitted
+>(
+  logic: ProcessLogic<State, Event, Error, Requirements, Output, InitialError>,
+  strategy: ProcessRuntimeStrategy,
+  options?: {
+    readonly id?: string
+  }
+) {
+  const runtime = yield* makeProcessRuntime
+  const sessionId = yield* runtime.nextSessionId
+  const emissions = makeEmissionRuntime()
+  const started = yield* Deferred.make<MachineRef<State, Event, Error, Output, Emitted>, InitialError>()
+  const internalOptions: StartInternalOptions = options === undefined
+    ? {
+      detached: true,
+      emissions,
+      runtime,
+      sessionId
+    }
+    : {
+      ...options,
+      detached: true,
+      emissions,
+      runtime,
+      sessionId
+    }
+  const initialize = strategy === "generic"
+    ? startGenericInternal(logic, internalOptions)
+    : strategy === "compiled"
+    ? logic.execution?._tag === "Compiled"
+      ? startCompactCompiledInternal(logic, internalOptions)
+      : Effect.die(new Error("Machine cannot force the compiled runtime for generic process logic"))
+    : startLogicInternal(logic, internalOptions)
+  const start = yield* Effect.cached(
+    initialize.pipe(
+      Effect.onExit((exit) => Deferred.done(started, exit))
+    ) as Effect.Effect<MachineRef<State, Event, Error, Output, Emitted>, InitialError, Requirements>
+  )
+  return {
+    id: options?.id ?? sessionId,
+    sessionId,
+    changes: Stream.unwrap(
+      Deferred.await(started).pipe(Effect.map((ref) => ref.changes))
+    ),
+    emissions: emissions.stream as Stream.Stream<Emitted>,
+    start
+  }
+})
+
+export const prepareProcess: <
+  State,
+  Event,
+  Error = never,
+  Requirements = never,
+  Output = never,
+  InitialError = never,
+  Emitted = never
+>(
+  logic: ProcessLogic<State, Event, Error, Requirements, Output, InitialError>,
+  options?: {
+    readonly id?: string
+  }
+) => Effect.Effect<
+  PreparedProcess<State, Event, Error, Output, Emitted, InitialError, Requirements>
+> =
+  ((logic: ProcessLogic<any, any, any, any, any, any>, options?: { readonly id?: string }) =>
+    prepareProcessWithStrategy(logic, "auto", options)) as any
+
+/** @internal Test-only prepared startup strategy selection. */
+export const prepareProcessWithStrategyForTesting = <
+  State,
+  Event,
+  Error = never,
+  Requirements = never,
+  Output = never,
+  InitialError = never,
+  Emitted = never
+>(
+  logic: ProcessLogic<State, Event, Error, Requirements, Output, InitialError>,
+  strategy: ProcessRuntimeStrategy,
+  options?: {
+    readonly id?: string
+  }
+): Effect.Effect<
+  PreparedProcess<State, Event, Error, Output, Emitted, InitialError, Requirements>
+> => prepareProcessWithStrategy(logic, strategy, options) as any

package/src/unstable/reactivity/AtomMachine.ts

@@ -167,8 +167,10 @@ type RefOutput<Ref> = Ref extends Machine.MachineRef<any, any, any, infer Output
 type RefEmitted<Ref> = Ref extends Machine.MachineRef<any, any, any, any, infer Emitted> ? Emitted : never
 
 /**
- * Observes ephemeral notifications from the actor owned by a machine atom.
- * The stream requires an `AtomRegistry` and does not replay earlier emissions.
+ * Observes ephemeral notifications from the running machine owned by a machine
+ * atom. When this stream activates a fresh bridge, it subscribes before machine
+ * initialization and observes initial-entry emissions. It never replays
+ * emissions from a machine that was already running.
  *
  * @category getters
  * @since 0.10.0