@typeonce/effect-machine 0.20.0 → 0.21.0

package/README.md

@@ -420,6 +420,47 @@ choice destinations remain calls such as `to.full.Running()`. Runtime named
 branch builders remain callable, including `select.unchanged()`, because their
 result carries the selected branch evidence.
 
+### Update an active scope value
+
+Use `to.local.update(...)` to replace the value owned by the nearest active
+compound scope without rebuilding its active child. Use
+`to.branch.<path>.update(...)` for a valued compound or parallel ancestor of the
+handler source:
+
+```ts
+Increment: ;
+;((to) =>
+  to.branch.root.session.update(({ ancestors, target }) => target.from({ count: ancestors["root.session"].count + 1 })))
+```
+
+The update keeps the exact active descendants, their values, history records,
+completion outputs, and unrelated parallel regions. It runs no exit or entry
+actions and does not restart state-owned work. Eventless stabilization still
+runs, so an `always` transition can react to the new value.
+
+`update` is callable when used directly and is also a static selection for a
+named branch:
+
+```ts
+to.branches({
+  changed: { target: to.local.update },
+  unchanged: { target: to.none }
+}).resolve(({ select, event }) =>
+  event.changed
+    ? select.changed.from({ count: event.count })
+    : select.unchanged()
+)
+```
+
+The resolver must return `target(value)` or `target.from(input)`. It may return
+`decline()` only with `{ declinable: true }`. Pass `{ reenter: true }` on event
+or invocation transitions when the handler source should exit and enter again.
+Reentry applies to that source, not to the ancestor whose value changed.
+
+The selector omits `update` for schema-less scopes, atomic and final states,
+inactive branches, parallel sibling regions, and choice resolvers. Updating a
+parallel sibling requires an event handled by that region.
+
 Use `declinable: true` when a resolver may decide that its transition is not
 enabled. Only that resolver receives `decline()`, and its return type expands to
 accept the opaque declined result:

package/dist/Machine.d.ts

@@ -2234,9 +2234,10 @@ export declare namespace Machine {
      *
      * **Details**
      *
-     * Every branch exposes its selected target without executing its resolver.
-     * A compound local or branch target covers its descendants;
-     * `undefined` identifies an explicitly targetless branch.
+     * Every branch exposes its static selection without executing its resolver.
+     * A compound local or branch target covers its descendants. An `update`
+     * selection keeps `target` undefined and records its value owner in
+     * `selection.path`; `none` identifies an explicitly targetless branch.
      *
      * @category models
      * @since 0.4.0
@@ -2841,6 +2842,20 @@ export declare namespace Machine {
             readonly [AncestorStateId in ValuedStateIdentifier<States>]: StateByIdentifier<States, AncestorStateId>;
         }>;
     }
+    /**
+     * Opaque instruction that replaces one active compound or parallel state's
+     * value without changing its active descendants.
+     *
+     * @category models
+     * @since 0.21.0
+     */
+    interface StateUpdate<States extends StateSchemas, StateId extends ValuedStateIdentifier<States>> {
+        readonly [Topology.StateUpdateTypeId]: typeof Topology.StateUpdateTypeId;
+        readonly path: StateId;
+        readonly value: StateByIdentifier<States, StateId>;
+    }
+    /** @internal */
+    type StateUpdateBuilder<States extends StateSchemas, StateId extends ValuedStateIdentifier<States>> = ((value: StateByIdentifier<States, StateId>) => StateUpdate<States, StateId>) & FromMethod<readonly [input: SchemaByIdentifier<States, StateId>["~type.make.in"]], StateUpdate<States, StateId>>;
     /**
      * Opaque result returned by an explicitly targetless transition.
      *
@@ -3045,6 +3060,20 @@ export declare namespace Machine {
     type SelectionNode<AllStates extends StateSchemas, Node, Path extends string, Scope extends "local" | "branch", Builder> = Node extends ChoiceStateNodeConfig ? SelectionMethod<Builder, Path, "choice"> : Node extends {
         readonly states: infer Children extends StateSchemas;
     } ? SelectionMethod<Builder, Path> & InitialSelectionMethod<Builder, Path> & SelectionTreeWithPrefix<AllStates, Children, Path, Scope, Builder> : SelectionMethod<Builder, Path>;
+    /** @internal */
+    type StateUpdateSelectionForNode<AllStates extends StateSchemas, Node, Path extends string> = Node extends {
+        readonly states: StateSchemas;
+    } ? NodeSchema<Node> extends never ? {} : {
+        readonly update: SelectionValue<StateUpdateBuilder<AllStates, Extract<Path, ValuedStateIdentifier<AllStates>>>, Path, "update">;
+    } : {};
+    /** @internal */
+    type BranchUpdateSelectionPath<AllStates extends StateSchemas, Node, Path extends string, Rest extends string> = StateUpdateSelectionForNode<AllStates, Node, Path> & (Node extends {
+        readonly states: infer Children extends StateSchemas;
+    } ? Rest extends `${infer Head}.${infer Tail}` ? Head extends keyof Children ? {
+        readonly [Key in Head]: BranchUpdateSelectionPath<AllStates, Children[Head], JoinPath<Path, Head>, Tail>;
+    } : {} : Rest extends keyof Children ? {
+        readonly [Key in Rest]: StateUpdateSelectionForNode<AllStates, Children[Rest], JoinPath<Path, Rest>>;
+    } : {} : {});
     type FullSelectionNode<AllStates extends StateSchemas, Node, Path extends StateIdentifier<AllStates>, Builder> = Node extends {
         readonly states: StateSchemas;
     } ? SelectionMethod<Builder, Path> & InitialSelectionMethod<Builder, Path> : SelectionMethod<Builder, Path>;
@@ -3052,11 +3081,13 @@ export declare namespace Machine {
         readonly [Key in Extract<ActiveStateKey<States>, keyof FullTargetBuilder<States>>]: FullSelectionNode<States, States[Key], Extract<Key, StateIdentifier<States>>, FullTargetBuilder<States>[Key]>;
     };
     type BranchTargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>, Root extends string = Source extends `${infer Head}.${string}` ? Head : Source> = Root extends ActiveStateKey<States> ? Root extends keyof BranchTargetBuilder<States, Source> ? {
-        readonly [Key in Root]: SelectionNode<States, States[Key], Key, "branch", BranchTargetBuilder<States, Source>[Key]>;
+        readonly [Key in Root]: SelectionNode<States, States[Key], Key, "branch", BranchTargetBuilder<States, Source>[Key]> & (Source extends ChoiceIdentifier<States> ? {} : Source extends `${Key}.${infer Rest}` ? BranchUpdateSelectionPath<States, States[Key], Key, Rest> : StateUpdateSelectionForNode<States, States[Key], Key>);
     } : {} : {};
-    type LocalTargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>> = NearestCompoundScope<States, Source> extends infer Scope extends StateIdentifier<States> ? ChildrenOf<States, Scope> extends infer Children extends StateSchemas ? LocalTargetBuilder<States, Source> extends infer Builder ? SelectionTreeWithPrefix<States, Children, Scope, "local", Builder> & ("with" extends keyof Builder ? {
+    type LocalTargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>> = NearestCompoundScope<States, Source> extends infer Scope ? [Scope] extends [never] ? {} : Scope extends StateIdentifier<States> ? ChildrenOf<States, Scope> extends infer Children extends StateSchemas ? LocalTargetBuilder<States, Source> extends infer Builder ? SelectionTreeWithPrefix<States, Children, Scope, "local", Builder> & ("with" extends keyof Builder ? {
         readonly with: SelectionValue<Builder["with"], Scope>;
-    } : {}) : {} : {} : {};
+    } : {}) & (Source extends ChoiceIdentifier<States> ? {} : Scope extends ValuedStateIdentifier<States> ? {
+        readonly update: SelectionValue<StateUpdateBuilder<States, Scope>, Scope, "update">;
+    } : {}) : {} : {} : {} : {};
     type HistorySelectionTree<AllStates extends StateSchemas, States extends StateSchemas, Prefix extends string, Builder> = {
         readonly [Key in Extract<HistoryContainingKey<States>, keyof Builder>]: States[Key] extends HistoryStateNodeConfig ? SelectionValue<Builder[Key], JoinPath<Prefix, Key>, "history"> : States[Key] extends {
             readonly states: infer Children extends StateSchemas;
@@ -3074,9 +3105,9 @@ export declare namespace Machine {
     interface TargetSelector<States extends StateSchemas, Source extends StateNodeIdentifier<States>> {
         /** Handles the trigger without selecting a destination. */
         readonly none: SelectionValue<TargetBuilder<States, Source>["none"], never, "none">;
-        /** Selects a destination inside the nearest active compound scope. */
+        /** Selects a destination or updates the nearest active compound scope. */
         readonly local: LocalTargetSelector<States, Source>;
-        /** Selects a destination elsewhere under the currently active root. */
+        /** Selects a destination or updates a valued active ancestor under the current root. */
         readonly branch: BranchTargetSelector<States, Source>;
         /** Selects a complete destination under any top-level state. */
         readonly full: FullTargetSelector<States>;
@@ -3365,14 +3396,14 @@ export declare namespace Machine {
      * **Details**
      *
      * Handlers return snapshots for complete state replacement, target builder
-     * results for path-safe partial transitions, or `target.none()` for an
-     * explicitly targetless transition. Raw decoded state values and `void` are
-     * not accepted at transition boundaries.
+     * results for path-safe partial transitions, state-value updates, or
+     * `target.none()` for an explicitly targetless transition. Raw decoded state
+     * values and `void` are not accepted at transition boundaries.
      *
      * @category utility types
      * @since 0.4.0
      */
-    type HandlerResult<States extends StateSchemas, E, R> = Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>>> | NoTarget;
+    type HandlerResult<States extends StateSchemas, E, R> = Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateUpdate<States, ValuedStateIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateUpdate<States, ValuedStateIdentifier<States>>> | NoTarget;
     /** A choice resolver must always select a typed target synchronously. */
     type ChoiceResult<States extends StateSchemas, E, R> = Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>> | StateConstruction<Snapshot<States> | Target<States, StateIdentifier<States>> | HistoryTarget<States, HistoryIdentifier<States>> | ChoiceTarget<States, ChoiceIdentifier<States>>>;
     /**
@@ -3633,6 +3664,10 @@ export declare namespace Machine {
     }
     type TransitionResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined;
     type DeclinableTransitionResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection> & DeclineCapability, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => (SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined) | Declined;
+    /** @internal */
+    type StateUpdateResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection>, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectedTargetResult<Selection>;
+    /** @internal */
+    type DeclinableStateUpdateResolver<Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, Context, Selection> = (context: TransitionResolveContext<Context, Selection> & DeclineCapability, enqueue: Enqueue<EventOf<Events>, EmitOf<Emits>>) => SelectedTargetResult<Selection> | Declined;
     /** One named destination declared by a branching transition. */
     interface TransitionBranchInput<Selection extends TargetSelection<any, any, any> = TargetSelection<any, any, any>> {
         /** Exact topology destination available to the branching resolver. */
@@ -3725,6 +3760,16 @@ export declare namespace Machine {
         /** Reenters the source using the selected target's default construction. */
         readonly reenter: () => BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectionKind<Selection> extends "none" ? undefined : SelectedTargetResult<Selection> | undefined, "required">;
     } : {} : {});
+    /** @internal */
+    interface StateUpdateTransitionRequired<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Selection extends TargetSelection<any, any, "update">> {
+        (resolve: StateUpdateResolver<Events, Emits, Context, Selection>, options?: TransitionRequiredOptions<Reenter>): BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectedTargetResult<Selection>, "required">;
+    }
+    /** @internal */
+    interface StateUpdateTransitionDeclinable<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Selection extends TargetSelection<any, any, "update">> {
+        (resolve: DeclinableStateUpdateResolver<Events, Emits, Context, Selection>, options: TransitionDeclinableOptions<Reenter>): BuiltTransition<States, Events, Emits, StateId, Context, Reenter, SelectedTargetResult<Selection> | Declined, "declinable">;
+    }
+    /** @internal */
+    type StateUpdateTransition<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Selection extends TargetSelection<any, any, "update">> = Selection & StateUpdateTransitionRequired<States, Events, Emits, StateId, Context, Reenter, Selection> & ("declinable" extends Acceptance ? StateUpdateTransitionDeclinable<States, Events, Emits, StateId, Context, Reenter, Selection> : {});
     /** @internal Type evidence retained by a machine initial-entry declaration. */
     interface InitialBuilderEvidence<out Selection> {
         readonly [InitialBuilderTypeId]: Types.Covariant<Selection>;
@@ -3748,7 +3793,7 @@ export declare namespace Machine {
     type InitialSelector<States extends StateSchemas, Input = void> = InitialSelectorNode<Input, InitialTargetSelector<States>>;
     /** Target-first initial-entry declaration accepted by {@link make}. */
     type InitialBuilderInput<States extends StateSchemas, Input> = (to: InitialSelector<States, Input>) => InitialBuilderEvidence<TargetSelection<any, any, any>>;
-    type TransitionSelectorNode<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Node> = Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ? ((...args: Args) => TransitionTarget<States, Events, Emits, StateId, Context, Reenter, Acceptance, Selection>) & {
+    type TransitionSelectorNode<States extends StateSchemas, Events extends ReadonlyArray<TaggedSchema>, Emits extends ReadonlyArray<TaggedSchema>, StateId extends StateNodeIdentifier<States>, Context, Reenter extends boolean, Acceptance extends TransitionAcceptance, Node> = Node extends TargetSelection<any, any, "update"> ? StateUpdateTransition<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node> : Node extends (...args: infer Args) => infer Selection ? Selection extends TargetSelection<any, any, any> ? ((...args: Args) => TransitionTarget<States, Events, Emits, StateId, Context, Reenter, Acceptance, Selection>) & {
         readonly [Key in keyof Node]: TransitionSelectorNode<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node[Key]>;
     } : never : Node extends TargetSelection<any, any, any> ? TransitionTarget<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node> : {
         readonly [Key in keyof Node]: TransitionSelectorNode<States, Events, Emits, StateId, Context, Reenter, Acceptance, Node[Key]>;
@@ -4908,9 +4953,10 @@ export declare const initialDefinition: <M extends Machine.Any>(machine: M) => M
  *
  * Event handlers retain their handler-key order within each source state and
  * are followed by eventless and completion handlers. This function does not
- * execute resolvers. Every direct, named, and targetless branch exposes the
- * destination selected by its required static `target` declaration, while
- * `acceptance` reports whether the resolver may decline the transition.
+ * execute resolvers. Every branch exposes its static selection. State updates
+ * retain the updated owner in `selection.path` while leaving `target`
+ * undefined because they do not change topology. `acceptance` reports whether
+ * the resolver may decline the transition.
  *
  * @category getters
  * @since 0.4.0