@mantaq/core 0.2.0 → 0.4.0

package/dist/index.d.mts

@@ -1,31 +1,218 @@
-import { _ as InternalEvent, a as EffectInput, b as StateRef, c as ErrorState, d as TransitionResult, f as Context, g as EventRef, h as CreatedOfEvent, i as EffectFn, l as NonFinalStateRef, m as AnyEventRef, n as Snapshot, o as ErrorInfo, p as Clock, r as CreatedOf, s as ErrorReason, t as AnyActor, u as TransitionInfo, v as event, x as state, y as AnyStateRef } from "./actor-internal-B4iAxUG_.mjs";
-//#region src/real-clock.d.ts
-declare class RealClock implements Clock {
-  #private;
-  now(): number;
-  setTimeout(ms: number, cb: () => void, options?: {
-    signal?: AbortSignal;
-    eventName?: string;
-  }): number;
+//#region src/event.d.ts
+declare function event<const T extends string>(type: T): <Payload extends object | void = void>() => EventRef<T, Payload>;
+interface EventRef<T extends string = string, Payload extends object | void = void> {
+  readonly type: T;
+  is(anyEvent: unknown): anyEvent is CreatedOfEvent<T, Payload>;
+  create(): Payload extends void ? {
+    type: T;
+  } : void;
+  create(payload: Payload): Payload extends void ? {
+    type: T;
+  } : {
+    type: T;
+    payload: Payload;
+  };
+}
+type AnyEventRef = EventRef<string, object | void>;
+type CreatedOfEvent<T extends string, P> = P extends void ? {
+  type: T;
+} : {
+  type: T;
+  payload: P;
+};
+declare function EventRef<const T extends string, Payload extends object | void = void>(type: T): EventRef<T, Payload>;
+//#endregion
+//#region src/clock.d.ts
+interface Clock {
+  setTimeout(ms: number, options: ClockTimerOptions): number;
   clearTimeout(id: number): void;
-  setInterval(ms: number, cb: () => void, options?: {
-    signal?: AbortSignal;
-  }): number;
+  setInterval(ms: number, options: ClockIntervalOptions): number;
   clearInterval(id: number): void;
+  now(): number;
+  /** Optional hook for draining queues after clock advances (VirtualClock). */
+  setDrain?(fn: () => void): void;
+}
+interface ClockTimerOptions {
+  cb: () => void;
+  signal?: AbortSignal;
+  eventName?: string;
+}
+interface ClockIntervalOptions {
+  cb: () => void;
+  signal?: AbortSignal;
+}
+//#endregion
+//#region src/context.d.ts
+interface Context<T> {
+  get(): T;
+  set(value: T): void;
+}
+/** Two-way handle over an owner's context: reads see live values, writes flag dirty state upstream. */
+declare function Context<T>(options: {
+  get: () => T;
+  set: (value: T) => void;
+}): Context<T>;
+//#endregion
+//#region src/state.d.ts
+declare function state<const T extends string>(name: T): <Payload = unknown>() => StateRef<T, Payload, false>;
+type AnyStateRef = StateRef<string, unknown, boolean>;
+interface RegionOptions {
+  initial: string;
+  states: Record<string, AnyStateRef>;
+}
+type RegionsOptions = Record<string, RegionOptions>;
+interface StateRef<T extends string = string, Payload = unknown, IsFinal extends boolean = false> {
+  readonly name: T;
+  readonly isFinal: IsFinal;
+  /** @internal */ _regions?: RegionsOptions;
+  regions(options: RegionsOptions): this;
+  final(): StateRef<T, Payload, true>;
+  create(payload: Payload): {
+    state: StateRef<T, Payload, IsFinal>;
+    payload: Payload;
+  };
+}
+declare function isStateRef(value: unknown): value is StateRef;
+declare function StateRef<T extends string, Payload = unknown, IsFinal extends boolean = false>(name: T, options: {
+  isFinal: IsFinal;
+}): StateRef<T, Payload, IsFinal>;
+//#endregion
+//#region src/actor-types.d.ts
+type CreatedOf<E extends EventRef<string, object | void>> = E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never;
+type NonFinalStateRef<States extends AnyStateRef[]> = Extract<States[number], {
+  isFinal: false;
+}>;
+interface EffectInput<ActorContext, Payload = unknown> {
+  signal: AbortSignal;
+  state: {
+    name: string;
+    payload: Payload;
+  };
+  event: InternalEvent;
+  context: Context<ActorContext>;
+  emit: (event: InternalEvent) => void;
+  clock: Clock;
+}
+type EffectFn<ActorContext, Payload = unknown> = (input: EffectInput<ActorContext, Payload>) => void | Promise<void> | {
+  then(onFulfilled: unknown, onRejected: unknown): unknown;
+};
+type ErrorReason = "transition" | "effect" | "budget" | "output" | "internal" | "async" | "unhandled";
+interface ErrorInfo {
+  error: unknown;
+  state: AnyStateRef;
+  context: unknown;
+  event: InternalEvent;
+  reason: ErrorReason;
+}
+interface TransitionInfo {
+  event: InternalEvent;
+  from: string;
+  to: string;
+  transitioned: boolean;
+  /** Names of effects invoked on entry into `to`, in registration order. */
+  effects: string[];
+}
+type ErrorState = StateRef<"__error", unknown, true>;
+type TransitionResult<AllowedState extends AnyStateRef = AnyStateRef, AllowedEmit extends string = string> = {
+  state?: AllowedState | {
+    state: AllowedState;
+    payload?: unknown;
+  };
+  payload?: unknown;
+  emit?: Array<{
+    type: AllowedEmit;
+    payload?: unknown;
+  }>;
+};
+//#endregion
+//#region src/actor-internal.d.ts
+interface Snapshot<C = unknown> {
+  path: string[];
+  context: C;
+  payload?: unknown;
+  regions: Record<string, Snapshot<unknown>>;
+  done?: boolean;
+  error?: ErrorInfo;
+}
+type SubscriberEventName = "change" | "done" | "transition" | "error" | "output";
+type SubscriberHandler<C, E extends SubscriberEventName> = E extends "change" ? (snapshot: Snapshot<C>, prev: Snapshot<C>) => void : E extends "done" ? () => void : E extends "transition" ? (info: TransitionInfo) => void : E extends "error" ? (info: ErrorInfo) => void : E extends "output" ? (event: InternalEvent) => void : never;
+interface AnyActor<C = Record<string, unknown>> {
+  state: AnyStateRef;
+  clock: Clock;
+  regions: Record<string, AnyActor>;
+  send(event: InternalEvent): void;
+  snapshot(): Snapshot<C>;
+  on<E extends SubscriberEventName>(event: E, options: {
+    fn: SubscriberHandler<C, E>;
+  }): () => void;
+  recover(target: {
+    state: AnyStateRef;
+    context: C;
+  }): void;
+  settled(): Promise<void>;
+  context?: C;
+  options?: {
+    transitions?: Record<string, Record<string, unknown>>;
+    effects?: Record<string, unknown[]>;
+    states?: ReadonlyArray<{
+      name: string;
+      isFinal: boolean;
+    }>;
+  };
+  inject(event: InternalEvent): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/parse-handler.d.ts
+type RuntimeTransitionHandler<States extends readonly AnyStateRef[], ActorContext> = (event: InternalEvent, options: {
+  context: Context<ActorContext>;
+  actor: AnyActor<ActorContext>;
+}) => TransitionResult<States[number], string>;
+//#endregion
+//#region src/builder.d.ts
+type EventTypeOf<E extends AnyEventRef> = E extends EventRef<infer Type, object | void> ? Type : never;
+type PayloadOf<S extends AnyStateRef> = S extends StateRef<infer _Name, infer Payload, infer _IsFinal> ? Payload : never;
+type TransitionHandler<States extends readonly AnyStateRef[], ActorContext> = RuntimeTransitionHandler<States, ActorContext>;
+interface EffectEntry<ActorContext> {
+  name: string;
+  fn: EffectFn<ActorContext>;
 }
+interface BuiltMaps<States extends readonly AnyStateRef[], ActorContext> {
+  transitions: Record<string, Record<string, TransitionHandler<States, ActorContext>>>;
+  effects: Record<string, Array<EffectEntry<ActorContext>>>;
+}
+type HandlerFn<States extends readonly AnyStateRef[], _InputsInternal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext, E extends AnyEventRef> = (event: E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never, opts: {
+  context: Context<ActorContext>;
+  actor: AnyActor<ActorContext>;
+}) => TransitionResult<States[number], EventTypeOf<Outputs[number]>>;
+interface ActorBuilder<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> {
+  on<S extends States[number], E extends Inputs[number] | Internal[number]>(stateRef: S, options: {
+    eventRef: E;
+    handler: HandlerFn<States, Inputs | Internal, Outputs, ActorContext, E>;
+  }): ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>;
+  onAny<E extends Inputs[number] | Internal[number]>(options: {
+    eventRef: E;
+    handler: HandlerFn<States, Inputs | Internal, Outputs, ActorContext, E>;
+  }): ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>;
+  effect<S extends States[number]>(stateRef: S, definition: {
+    name: string;
+    fn: EffectFn<ActorContext, PayloadOf<S>>;
+  }): ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>;
+  /** @internal */
+  build(): BuiltMaps<States, ActorContext>;
+}
+declare function ActorBuilder<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext>(): ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>;
+type SetupFn<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (m: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
+//#endregion
+//#region src/real-clock.d.ts
+declare function RealClock(): Clock;
 //#endregion
 //#region src/virtual-clock.d.ts
-declare class VirtualClock implements Clock {
-  #private;
+interface VirtualClock {
   now(): number;
-  setTimeout(ms: number, cb: () => void, options?: {
-    signal?: AbortSignal;
-    eventName?: string;
-  }): number;
+  setTimeout(ms: number, options: ClockTimerOptions): number;
   clearTimeout(id: number): void;
-  setInterval(ms: number, cb: () => void, options?: {
-    signal?: AbortSignal;
-  }): number;
+  setInterval(ms: number, options: ClockIntervalOptions): number;
   clearInterval(id: number): void;
   advance(ms: number): void;
   hasPending(): boolean;
@@ -37,43 +224,19 @@ declare class VirtualClock implements Clock {
   }>;
   setDrain(fn: () => void): void;
 }
-//#endregion
-//#region src/builder.d.ts
-type EventTypeOf<E extends AnyEventRef> = E extends EventRef<infer Type, object | void> ? Type : never;
-type PayloadOf<S extends AnyStateRef> = S extends StateRef<infer _Name, infer Payload, infer _IsFinal> ? Payload : never;
-type TransitionHandler<States extends readonly AnyStateRef[], ActorContext> = (event: InternalEvent, opts: {
-  context: Context<ActorContext>;
-  actor: AnyActor;
-}) => TransitionResult<States[number], string>;
-interface BuiltMaps<States extends readonly AnyStateRef[], ActorContext> {
-  transitions: Record<string, Record<string, TransitionHandler<States, ActorContext>>>;
-  effects: Record<string, Array<EffectFn<ActorContext>>>;
-}
-declare class ActorBuilder<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> {
-  #private;
-  on<S extends States[number], E extends Inputs[number] | Internal[number]>(stateRef: S, eventRef: E, fn: (event: E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never, opts: {
-    context: Context<ActorContext>;
-    actor: AnyActor;
-  }) => TransitionResult<States[number], EventTypeOf<Outputs[number]>>): this;
-  onAny<E extends Inputs[number] | Internal[number]>(eventRef: E, fn: (event: E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never, opts: {
-    context: Context<ActorContext>;
-    actor: AnyActor;
-  }) => TransitionResult<States[number], EventTypeOf<Outputs[number]>>): this;
-  effect<S extends States[number]>(stateRef: S, fn: EffectFn<ActorContext, PayloadOf<S>>): this;
-  /** @internal */ build(): BuiltMaps<States, ActorContext>;
-}
-type SetupFn<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext> = (m: ActorBuilder<States, Inputs, Internal, Outputs, ActorContext>) => void;
+declare function VirtualClock(): VirtualClock;
 //#endregion
 //#region src/actor.d.ts
-type CreatedOf$1<E extends AnyEventRef> = E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never;
-type InitialState<S extends AnyStateRef> = S extends StateRef<infer _N extends string, infer P> ? [unknown] extends [P] ? S | {
+type CreatedOf$1<E extends AnyEventRef$1> = E extends EventRef<infer Type, infer P> ? CreatedOfEvent<Type, P> : never;
+type AnyEventRef$1 = AnyEventRef;
+type InitialState<S extends AnyStateRef> = S extends StateRef<infer _N extends string, infer P, infer _I extends boolean> ? [unknown] extends [P] ? S | {
   state: S;
   payload?: P;
 } : {
   state: S;
   payload: P;
 } : never;
-interface ActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext = Record<string, unknown>> {
+interface ActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef$1[], Internal extends readonly AnyEventRef$1[], Outputs extends readonly AnyEventRef$1[], ActorContext = Record<string, unknown>> {
   inputs: Inputs;
   outputs?: Outputs;
   internal?: Internal;
@@ -85,38 +248,41 @@ interface ActorOptions<States extends readonly AnyStateRef[], Inputs extends rea
   setup: SetupFn<States, Inputs, Internal, Outputs, ActorContext>;
   regions?: Record<string, AnyActor>;
 }
-interface InternalActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef[], Internal extends readonly AnyEventRef[], Outputs extends readonly AnyEventRef[], ActorContext = Record<string, unknown>> extends Omit<ActorOptions<States, Inputs, Internal, Outputs, ActorContext>, "setup"> {
+interface InternalActorOptions<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef$1[], Internal extends readonly AnyEventRef$1[], Outputs extends readonly AnyEventRef$1[], ActorContext = Record<string, unknown>> extends Omit<ActorOptions<States, Inputs, Internal, Outputs, ActorContext>, "setup"> {
   transitions: TransitionDispatch<States, ActorContext>;
-  effects: Record<string, Array<EffectFn<ActorContext>>>;
+  effects: Record<string, Array<EffectEntry<ActorContext>>>;
 }
-type TransitionDispatch<States extends readonly AnyStateRef[], ActorContext> = Record<string, Record<string, ((event: InternalEvent, options: {
+type TransitionDispatch<States extends readonly AnyStateRef[], ActorContext> = Record<string, Record<string, TransitionStepFn<States, ActorContext> | undefined>>;
+type TransitionStepFn<States extends readonly AnyStateRef[], ActorContext> = (event: InternalEvent, options: {
   context: Context<ActorContext>;
-  actor: AnyActor;
-}) => TransitionResult<States[number], string>) | undefined>>;
-declare class Actor<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef[], const Internal extends readonly AnyEventRef[] = readonly [], const Outputs extends readonly AnyEventRef[] = readonly [], ActorContext = Record<string, unknown>> {
-  #private;
+  actor: AnyActor<ActorContext>;
+}) => TransitionResult<States[number], string>;
+interface Actor<States extends readonly AnyStateRef[], Inputs extends readonly AnyEventRef$1[], Internal extends readonly AnyEventRef$1[] = readonly [], Outputs extends readonly AnyEventRef$1[] = readonly [], ActorContext = Record<string, unknown>> extends AnyActor<ActorContext> {
   state: States[number] | ErrorState;
   readonly clock: Clock;
-  get context(): ActorContext;
-  get regions(): Record<string, AnyActor>;
-  get options(): InternalActorOptions<States, Inputs, Internal, Outputs, ActorContext>;
-  constructor(options: ActorOptions<States, Inputs, Internal, Outputs, ActorContext>);
-  on(event: "change", fn: (snapshot: Snapshot<ActorContext>, prev: Snapshot<ActorContext>) => void): () => void;
-  on(event: "done", fn: () => void): () => void;
-  on(event: "transition", fn: (info: TransitionInfo) => void): () => void;
+  readonly context: ActorContext;
+  readonly regions: Record<string, AnyActor>;
+  readonly options: InternalActorOptions<States, Inputs, Internal, Outputs, ActorContext>;
+  on<E extends SubscriberEventName>(event: E, options: {
+    fn: SubscriberHandler<ActorContext, E>;
+  }): () => void;
   settled(): Promise<void>;
+  pendingEffectCount(): number;
   send(event: CreatedOf$1<Inputs[number]>): void;
-  /**
-   * Manually restore the actor to a live state after a fatal `__error`.
-   * DANGER: the caller supplies state and context, so the trajectory is no
-   * longer deterministic ("same inputs, same trace"). Effects are not re-run
-   * and timers are not re-armed — processing resumes on the next event.
-   */
   recover(target: {
     state: States[number];
     context: ActorContext;
   }): void;
   snapshot(): Snapshot<ActorContext>;
+  inject(event: InternalEvent): void;
+  dispose(): void;
 }
+declare function Actor<const States extends readonly AnyStateRef[], const Inputs extends readonly AnyEventRef$1[], const Internal extends readonly AnyEventRef$1[] = readonly [], const Outputs extends readonly AnyEventRef$1[] = readonly [], ActorContext = Record<string, unknown>>(options: ActorOptions<States, Inputs, Internal, Outputs, ActorContext>): Actor<States, Inputs, Internal, Outputs, ActorContext>;
+//#endregion
+//#region src/index.d.ts
+type InternalEvent = {
+  type: string;
+  payload?: unknown;
+};
 //#endregion
-export { Actor, type ActorBuilder, type ActorOptions, type AnyActor, type AnyEventRef, type AnyStateRef, type BuiltMaps, type Clock, Context, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, type ErrorInfo, type ErrorReason, type ErrorState, EventRef, type EventTypeOf, type InitialState, type InternalEvent, type NonFinalStateRef, type PayloadOf, RealClock, type SetupFn, type Snapshot, StateRef, type TransitionHandler, type TransitionInfo, type TransitionResult, VirtualClock, event, state };
+export { Actor, type ActorBuilder, type ActorOptions, type AnyActor, type AnyEventRef, type AnyStateRef, type BuiltMaps, type Clock, Context, type CreatedOf, type CreatedOfEvent, type EffectFn, type EffectInput, type ErrorInfo, type ErrorReason, type ErrorState, EventRef, type EventTypeOf, type InitialState, InternalEvent, type NonFinalStateRef, type PayloadOf, RealClock, type SetupFn, type Snapshot, StateRef, type TransitionHandler, type TransitionInfo, type TransitionResult, VirtualClock, event, isStateRef, state };