fix: infer dynamic invoke effect channels

Author: SandroMaglione

.changeset/inline-invocation-lifecycles.md

@@ -5,3 +5,5 @@
 Replace `Machine.invokeEffect`, `Machine.after`, `Machine.invokeMachine`, and `Machine.effect` with one inline `invoke` lifecycle object API and a zero-runtime `Machine.invoke` inference helper.
 
 Choose an `effect`, `after`, `logic`, or `child` source and handle typed outcomes directly with `onDone`, `onFailure`, and `onSnapshot`. Lifecycle handlers can now transition the owning state without routing results through mapped machine events.
+
+State-dependent Effect sources infer their owner state, output, error, and service requirements together without a manual return annotation.

README.md

@@ -221,13 +221,22 @@ Waiting: {
 Use `effect` for one Effect, `after` for a cancellable delay, `logic` for a
 reusable process, and `child` for a complete child statechart—all through
 `Machine.invoke({...})`. The helper is an identity at runtime and preserves
-source-channel inference across lifecycle handlers. A direct `invoke: { ... }`
-object is also supported and supplies owner context to dynamic `effect`,
-`logic`, `after`, and child `input` functions when their lifecycle handlers do
-not consume typed context. When handlers need typed output or failure values,
-use `Machine.invoke` and annotate a dynamic source's return type. Reuse one
-exported `Machine.child(id, machine)` descriptor for invocation, `sendTo`, and
-child lookup.
+owner-context and source-channel inference across lifecycle handlers, including
+for state-dependent Effects:
+
+```ts
+invoke: Machine.invoke({
+  id: "load-document",
+  effect: ({ state }) => loadDocument(state.documentId),
+  onDone: ({ output, target }) => target.full.Ready({ document: output }),
+  onFailure: ({ error, target }) => target.full.Failed({ message: error.message })
+})
+```
+
+A direct `invoke: { ... }` object is also supported when its lifecycle handlers
+do not need source-derived context. Reuse one exported
+`Machine.child(id, machine)` descriptor for invocation, `sendTo`, and child
+lookup.
 
 `onDone` is required for a non-`never` output, and `onFailure` is required for a
 non-`never` typed error; each handler is omitted when its channel is `never`.

docs/agent-guide.md

@@ -102,13 +102,12 @@ its extra control is required:
   `AtomMachine.resume(machine, snapshot)` for service-free machines.
 - Use one invocation object: `effect` for one-shot work, `after` for a timer,
   `logic` for reusable process logic, and `child` for a complete child
-  statechart. `Machine.invoke({...})` preserves source channels across sibling
-  lifecycle handlers. Use a direct object when a dynamic source or child input
-  primarily needs contextual owner-state inference and its lifecycle handlers
-  do not consume typed context.
+  statechart. `Machine.invoke({...})` preserves owner context and source
+  channels across sibling lifecycle handlers. Use a direct object only when its
+  lifecycle handlers do not need source-derived context.
 - Use `Machine.child(id, machine)` for a complete statechart descriptor and
-  `Machine.childAddress<Event>(id)` for a low-level process address. An
-  logic invocation is addressable only when `Machine.invoke` receives that
+  `Machine.childAddress<Event>(id)` for a low-level process address. A logic
+  invocation is addressable only when `Machine.invoke` receives that
   address explicitly.
 - Use the callback's `enqueue` argument for `raise`, `emit`, `sendTo`, and
   `stop`. These operations record closed actor commands and do not run Effects.
@@ -582,9 +581,20 @@ errors, defects, and interruption are machine failures rather than a second
 phase in `onFailure`.
 
 When a source function reads `state`, `parent`, `parents`, or the entry `event`,
-the direct object form supplies its owner context. If sibling handlers also
-need typed lifecycle context, wrap the object with `Machine.invoke` and annotate
-the returned Effect or Logic type.
+`Machine.invoke` infers that owner context and the returned Effect's output,
+error, and service channels together. No return annotation is needed:
+
+```ts
+invoke: Machine.invoke({
+  id: "load",
+  effect: ({ state }) => LoadService.load(state.userId),
+  onDone: ({ output, target }) => target.full.Loaded({ user: output }),
+  onFailure: ({ error, target }) => target.full.LoadFailed({ error })
+})
+```
+
+A direct `invoke: { ... }` object remains available when lifecycle handlers do
+not need source-derived context.
 
 A cancellable timer uses the same object:
 

examples/playground/src/examples/media-player/machine.ts

@@ -33,7 +33,7 @@ export const MediaPlayerMachine = MediaPlayerDefinition.handle({
           Loading: {
             invoke: Machine.invoke({
               id: "load-audio",
-              effect: ({ state }): ReturnType<typeof loadAudio> => loadAudio(state.url),
+              effect: ({ state }) => loadAudio(state.url),
               onDone: (_, enqueue) => enqueue.raise(MediaPlayerInternalEvents.LoadSucceeded()),
               onFailure: ({ error }, enqueue) =>
                 enqueue.raise(MediaPlayerInternalEvents.OperationFailed({ message: error.message }))

examples/pokemon/src/machines/selection.ts

@@ -106,8 +106,7 @@ export const SelectionMachine = Machine.make({
           Searching: {
             invoke: Machine.invoke({
               id: "search",
-              effect: ({ parents }): ReturnType<typeof searchPokemon> =>
-                searchPokemon(parents["form.search"].searchText),
+              effect: ({ parents }) => searchPokemon(parents["form.search"].searchText),
               onDone: ({ output, target }) =>
                 output.result.pipe(
                   Option.match({

perf/types/dynamic-invoke-control.ts

@@ -0,0 +1,18 @@
+import { Machine } from "@typeonce/effect-machine"
+import { Effect, Schema } from "effect"
+
+export class LoadError {
+  readonly _tag = "LoadError"
+}
+
+export const Loading = Schema.TaggedStruct("Loading", { userId: Schema.String })
+
+export const States = Machine.defineStates({ Loading })
+
+export const loadUser = (userId: string) => Effect.fail(new LoadError()).pipe(Effect.as({ id: userId, name: "Ada" }))
+
+export const machine = Machine.make({
+  states: States.states,
+  events: [],
+  initial: () => States.initial.Loading(Loading.make({ userId: "user-1" }))
+})

perf/types/dynamic-invoke.ts

@@ -0,0 +1,26 @@
+import { Machine } from "@typeonce/effect-machine"
+import { LoadError, loadUser, machine } from "./dynamic-invoke-control.js"
+
+interface User {
+  readonly id: string
+  readonly name: string
+}
+
+const invoked = machine.handle({
+  Loading: {
+    invoke: Machine.invoke({
+      id: "load-user",
+      effect: ({ state }) => loadUser(state.userId),
+      onDone: ({ output }) => {
+        const user: User = output
+        void user
+      },
+      onFailure: ({ error }) => {
+        const loadError: LoadError = error
+        void loadError
+      }
+    })
+  }
+})
+
+void invoked

scripts/type-performance.mjs

@@ -74,6 +74,20 @@ const scenarios = [
     maxInstantiations: 30_000,
     maxMarginalInstantiations: 19_000
   },
+  {
+    id: "dynamic-invoke-control",
+    label: "dynamic Machine.invoke control",
+    file: "dynamic-invoke-control.ts",
+    hidden: true
+  },
+  {
+    id: "dynamic-invoke",
+    label: "Machine.invoke (state-dependent Effect)",
+    file: "dynamic-invoke.ts",
+    control: "dynamic-invoke-control",
+    maxInstantiations: 85_000,
+    maxMarginalInstantiations: 76_000
+  },
   {
     id: "handle-depth-24-control",
     label: "machine.handle depth 24 control",

src/Machine.ts

@@ -1851,7 +1851,7 @@ export interface ChildMachine<Id extends string, M extends Machine.Any> {
   readonly machine: M
 
   /** @internal */
-  readonly [ChildMachineLogicTypeId]: (input: unknown) => Logic<any, any, any, any, any, any>
+  readonly [ChildMachineLogicTypeId]: (input?: unknown) => Logic<any, any, any, any, any, any>
 }
 
 /**
@@ -4480,12 +4480,22 @@ export declare namespace Machine {
       readonly onSnapshot?: never
     }
     & InvokeDoneRequirement<
-      Effect.Success<Fx>,
-      InvokeTransition<States, Events, Emits, InvokeDoneContext<States, Events, Emits, StateId, Effect.Success<Fx>>>
+      Effect.Success<NoInfer<Fx>>,
+      InvokeTransition<
+        States,
+        Events,
+        Emits,
+        InvokeDoneContext<States, Events, Emits, StateId, Effect.Success<NoInfer<Fx>>>
+      >
     >
     & InvokeFailureRequirement<
-      Effect.Error<Fx>,
-      InvokeTransition<States, Events, Emits, InvokeFailureContext<States, Events, Emits, StateId, Effect.Error<Fx>>>
+      Effect.Error<NoInfer<Fx>>,
+      InvokeTransition<
+        States,
+        Events,
+        Emits,
+        InvokeFailureContext<States, Events, Emits, StateId, Effect.Error<NoInfer<Fx>>>
+      >
     >
 
   export type TimerInvokeArgs<
@@ -6253,6 +6263,67 @@ export const decodeSnapshot: <
   Machine.SnapshotDecodingServices<States>
 > = internal.decodeSnapshot
 
+type DynamicEffectInvokeSource<
+  States extends Machine.StateSchemas,
+  Events extends ReadonlyArray<Machine.TaggedSchema>,
+  Emits extends ReadonlyArray<Machine.TaggedSchema>,
+  StateId extends Machine.StateIdentifier<States>,
+  Source extends (
+    context: Machine.InvokeContext<States, Events, Emits, StateId>
+  ) => Effect.Effect<unknown, unknown, unknown>
+> = {
+  readonly id: InvokeLifecycleId
+  readonly effect: Source
+  readonly after?: never
+  readonly logic?: never
+  readonly child?: never
+  readonly address?: never
+  readonly onSnapshot?: never
+}
+
+type DynamicEffectDoneHandler<
+  States extends Machine.StateSchemas,
+  Events extends ReadonlyArray<Machine.TaggedSchema>,
+  Emits extends ReadonlyArray<Machine.TaggedSchema>,
+  StateId extends Machine.StateIdentifier<States>,
+  Source extends (...args: ReadonlyArray<never>) => Effect.Effect<unknown, unknown, unknown>
+> = Machine.InvokeTransition<
+  States,
+  Events,
+  Emits,
+  Machine.InvokeDoneContext<States, Events, Emits, StateId, Effect.Success<ReturnType<NoInfer<Source>>>>
+>
+
+type DynamicEffectFailureHandler<
+  States extends Machine.StateSchemas,
+  Events extends ReadonlyArray<Machine.TaggedSchema>,
+  Emits extends ReadonlyArray<Machine.TaggedSchema>,
+  StateId extends Machine.StateIdentifier<States>,
+  Source extends (...args: ReadonlyArray<never>) => Effect.Effect<unknown, unknown, unknown>
+> = Machine.InvokeTransition<
+  States,
+  Events,
+  Emits,
+  Machine.InvokeFailureContext<States, Events, Emits, StateId, Effect.Error<ReturnType<NoInfer<Source>>>>
+>
+
+type DynamicEffectInvokeResult<
+  States extends Machine.StateSchemas,
+  Events extends ReadonlyArray<Machine.TaggedSchema>,
+  Emits extends ReadonlyArray<Machine.TaggedSchema>,
+  StateId extends Machine.StateIdentifier<States>,
+  Source extends (...args: ReadonlyArray<never>) => Effect.Effect<unknown, unknown, unknown>
+> =
+  & Machine.InvokeConfig<States, Events, Emits, StateId>
+  & Machine.InvokeTyped<
+    Effect.Success<ReturnType<Source>>,
+    Effect.Error<ReturnType<Source>>,
+    Effect.Services<ReturnType<Source>>,
+    never
+  >
+
+type InvokeChannelIsNever<Value> = IsAny<Value> extends true ? false : [Value] extends [never] ? true : false
+
 /**
  * Preserves inference for a state-owned invocation configuration.
  *
@@ -6263,11 +6334,9 @@ export const decodeSnapshot: <
  *
  * This constructor is an identity at runtime, but preserves lifecycle callback
  * inference through published declarations. Effects and durations may be
- * supplied directly or derived from the owning state's entry context. A direct
- * object in the state handler gives function-valued sources and child inputs
- * owner-context inference when lifecycle handlers do not consume typed context.
- * Use this constructor and annotate a dynamic source's return type when sibling
- * handlers need typed output or error values. Logic invocations require both a
+ * supplied directly or derived from the owning state's entry context. Dynamic
+ * Effect sources infer the owner context, output, error, and service channels
+ * together without a return annotation. Logic invocations require both a
  * lifecycle `id` and a typed communication `address`. Child descriptors already
  * own their identity, so `id` and `address` must not be repeated.
  *
@@ -6292,28 +6361,80 @@ export const invoke: {
     const Events extends ReadonlyArray<Machine.TaggedSchema>,
     const Emits extends ReadonlyArray<Machine.TaggedSchema>,
     StateId extends Machine.StateIdentifier<States>,
-    Output,
-    Error,
-    Requirements
+    const Source extends (
+      context: Machine.InvokeContext<States, Events, Emits, StateId>
+    ) => Effect.Effect<unknown, unknown, unknown>
   >(
-    config: Machine.EffectInvokeArgs<
-      States,
-      Events,
-      Emits,
-      StateId,
-      Effect.Effect<Output, Error, Requirements>,
-      (
-        context: Machine.InvokeContext<States, Events, Emits, StateId>
-      ) => Effect.Effect<Output, Error, Requirements>
-    >
-  ):
-    & Machine.InvokeConfig<States, Events, Emits, StateId>
-    & Machine.InvokeTyped<
-      Output,
-      Error,
-      Requirements,
-      never
-    >
+    config:
+      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & {
+        readonly onDone: DynamicEffectDoneHandler<States, Events, Emits, StateId, Source>
+        readonly onFailure: DynamicEffectFailureHandler<States, Events, Emits, StateId, Source>
+      },
+    ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
+        "onDone must be omitted when the Effect output is never"
+      ]
+      : InvokeChannelIsNever<Effect.Error<ReturnType<Source>>> extends true ? [
+          "onFailure must be omitted when the Effect error is never"
+        ]
+      : []
+  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
+  <
+    const States extends Machine.StateSchemas,
+    const Events extends ReadonlyArray<Machine.TaggedSchema>,
+    const Emits extends ReadonlyArray<Machine.TaggedSchema>,
+    StateId extends Machine.StateIdentifier<States>,
+    const Source extends (
+      context: Machine.InvokeContext<States, Events, Emits, StateId>
+    ) => Effect.Effect<unknown, never, unknown>
+  >(
+    config:
+      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & {
+        readonly onDone: DynamicEffectDoneHandler<States, Events, Emits, StateId, Source>
+        readonly onFailure?: never
+      },
+    ..._validation: InvokeChannelIsNever<Effect.Success<ReturnType<Source>>> extends true ? [
+        "onDone must be omitted when the Effect output is never"
+      ]
+      : []
+  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
+  <
+    const States extends Machine.StateSchemas,
+    const Events extends ReadonlyArray<Machine.TaggedSchema>,
+    const Emits extends ReadonlyArray<Machine.TaggedSchema>,
+    StateId extends Machine.StateIdentifier<States>,
+    const Source extends (
+      context: Machine.InvokeContext<States, Events, Emits, StateId>
+    ) => Effect.Effect<never, unknown, unknown>
+  >(
+    config:
+      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & {
+        readonly onDone?: never
+        readonly onFailure: DynamicEffectFailureHandler<States, Events, Emits, StateId, Source>
+      },
+    ..._validation: InvokeChannelIsNever<Effect.Error<ReturnType<Source>>> extends true ? [
+        "onFailure must be omitted when the Effect error is never"
+      ]
+      : []
+  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
+  <
+    const States extends Machine.StateSchemas,
+    const Events extends ReadonlyArray<Machine.TaggedSchema>,
+    const Emits extends ReadonlyArray<Machine.TaggedSchema>,
+    StateId extends Machine.StateIdentifier<States>,
+    const Source extends (
+      context: Machine.InvokeContext<States, Events, Emits, StateId>
+    ) => Effect.Effect<never, never, unknown>
+  >(
+    config:
+      & DynamicEffectInvokeSource<States, Events, Emits, StateId, Source>
+      & {
+        readonly onDone?: never
+        readonly onFailure?: never
+      }
+  ): DynamicEffectInvokeResult<States, Events, Emits, StateId, Source>
   <
     const States extends Machine.StateSchemas,
     const Events extends ReadonlyArray<Machine.TaggedSchema>,