@lite-fsm/core 2.0.5 → 2.1.0-alpha.0

package/dist/runtime/kernel/storage.d.cts

@@ -0,0 +1,226 @@
+import type { MachineManagerOptions } from "../../interfaces";
+import type { ManagerRuntimeContext as PublicManagerRuntimeContext, ScopedInvocationContext } from "../../plugin";
+import type { StorageActionStageResult as PublicStorageActionStageResult, StorageDehydrateResult as PublicStorageDehydrateResult, StorageHydrateResult as PublicStorageHydrateResult, StoragePrepareActionResult as PublicStoragePrepareActionResult, StorageReduceResult as PublicStorageReduceResult, StorageRuntimeExtension as PublicStorageRuntimeExtension } from "../../pluginStorageTypes";
+import type { AnyEvent, DehydrateOptions, HydrateStrategy, MachinesState, MachineStore, ManagerAction, ReadonlyManagerAction } from "../../types";
+import type { RouteConstraint, RoutingRuntime } from "./routing";
+export type StorageRuntimeState = unknown;
+export type RuntimeIdentity = Readonly<Record<string, unknown>>;
+export type StorageEffectInvocation = unknown;
+export type StorageActionStageResult = PublicStorageActionStageResult;
+export type StorageReduceResult = PublicStorageReduceResult;
+export type ValidateTemplateContext = {
+    readonly key: string;
+    readonly machine: MachineStore[string];
+    readonly storageKind: string;
+};
+export type CompileTemplateContext = ValidateTemplateContext;
+export type CompiledStorageTemplate = {
+    readonly key: string;
+    readonly kind: string;
+    readonly data?: unknown;
+};
+export type CreateRuntimeStateContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly manager: ManagerRuntimeContext;
+};
+export type CreatePublicInitialStateContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly state: StorageRuntimeState;
+};
+export type AcceptsEventContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageBeforeReduceContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceBucketContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageCommitContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type ResolveEffectInvocationsContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageEffectInvocationContext = {
+    readonly invocation: StorageEffectInvocation;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageConditionContext = {
+    readonly predicate: (action: ReadonlyManagerAction<AnyEvent>) => boolean;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+};
+export type StorageDehydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly rootState: Record<string, unknown>;
+    readonly options: DehydrateOptions<MachineStore> | undefined;
+};
+export type StorageHydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly machines: Readonly<Record<string, unknown>>;
+    readonly snapshot: unknown | undefined;
+    readonly baseState: Record<string, unknown>;
+    readonly strategy: HydrateStrategy;
+    readonly source: "hydrate" | "opts.snapshot";
+    readonly mode: "preview" | "commit" | "init";
+};
+export type ResolveIdentityContext = {
+    readonly state: StorageRuntimeState;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+};
+export type StorageReactionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly options: unknown;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionResult = PublicStoragePrepareActionResult;
+export type StorageHydrateResult = PublicStorageHydrateResult;
+export type StorageDehydrateResult = PublicStorageDehydrateResult<PublicStorageRuntimeExtension>;
+export type StorageDispatchContext = {
+    readonly options: unknown;
+    readonly runtime: Map<string, unknown>;
+    readonly route: RouteConstraint;
+    readonly prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    readonly skipDelivery: boolean;
+    reportError(error: unknown): void;
+};
+export type StorageDispatchOutcome = {
+    readonly type: "active";
+} | {
+    readonly type: "drop";
+    readonly action: ManagerAction<AnyEvent>;
+};
+export type StorageDispatchLifecycleContext = {
+    readonly originalAction: ManagerAction<AnyEvent>;
+    action: ManagerAction<AnyEvent>;
+    skipDelivery: boolean;
+    route: RouteConstraint;
+    prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    nextCalled: boolean;
+    outcome: StorageDispatchOutcome;
+    touched: Set<string>;
+    readonly dispatch: StorageDispatchContext;
+};
+export type DispatchSlot<T> = {
+    readonly key: string;
+    get(dispatch: StorageDispatchContext): T | undefined;
+    set(dispatch: StorageDispatchContext, value: T): void;
+};
+export declare const createDispatchSlot: <T>(key: string) => DispatchSlot<T>;
+export type ManagerRuntimeContext<Events extends AnyEvent = AnyEvent, S extends MachineStore = MachineStore> = PublicManagerRuntimeContext<Events, S> & {
+    readonly config: S;
+    readonly options: MachineManagerOptions<any, any, any> | undefined;
+    readonly schemaVersion: number | undefined;
+    readonly routing: RoutingRuntime;
+    getState(): MachinesState<S>;
+    transition(action: ManagerAction<Events>, options?: unknown): ManagerAction<Events>;
+    onTransition(cb: (prevState: MachinesState<S>, currentState: MachinesState<S>, action: ReadonlyManagerAction<Events> | {
+        readonly type: string;
+        readonly payload?: unknown;
+    }) => void): () => void;
+    getDependencies(): Record<string, unknown>;
+    createScopedDeps(baseDeps: Record<string, unknown>, ctx: ScopedInvocationContext): Record<string, unknown>;
+};
+export type StorageRouteMetaDependencyKeys = readonly string[];
+export type StorageRuntimeBase = {
+    readonly kind: string;
+    readonly routeMetaKeys?: StorageRouteMetaDependencyKeys;
+    validateTemplate(ctx: ValidateTemplateContext): void;
+    compileTemplate(ctx: CompileTemplateContext): CompiledStorageTemplate;
+    createRuntimeState(ctx: CreateRuntimeStateContext): StorageRuntimeState;
+    createPublicInitialState(ctx: CreatePublicInitialStateContext): unknown;
+    prepareAction?(ctx: StoragePrepareActionContext): StoragePrepareActionResult;
+    beforeReduce?(ctx: StorageBeforeReduceContext): StorageActionStageResult;
+    commit(ctx: StorageCommitContext): void;
+};
+export type TemplateStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope?: "template";
+    acceptsEvent(ctx: AcceptsEventContext): boolean;
+    reduce(ctx: StorageReduceContext): StorageReduceResult;
+    readonly reduceBucket?: never;
+};
+export type BucketStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope: "bucket";
+    reduceBucket(ctx: StorageReduceBucketContext): StorageReduceResult;
+    readonly acceptsEvent?: never;
+    readonly reduce?: never;
+};
+export type StorageEffectsRuntime = {
+    condition?(ctx: StorageConditionContext): Promise<boolean>;
+    resolveInvocations(ctx: ResolveEffectInvocationsContext): readonly StorageEffectInvocation[];
+    invoke(ctx: StorageEffectInvocationContext): void;
+};
+export type StorageSnapshotRuntime = {
+    dehydrate(ctx: StorageDehydrateContext): StorageDehydrateResult;
+    hydrate(ctx: StorageHydrateContext): StorageHydrateResult;
+};
+export type StorageIdentityRuntime = {
+    resolve(ctx: ResolveIdentityContext): RuntimeIdentity | undefined;
+};
+export type StorageReactionRuntime = {
+    run(ctx: StorageReactionContext): void;
+};
+export type StorageRuntime = (TemplateStorageRuntime | BucketStorageRuntime) & {
+    readonly effects?: StorageEffectsRuntime;
+    readonly snapshot?: StorageSnapshotRuntime;
+    readonly identity?: StorageIdentityRuntime;
+    readonly reactions?: StorageReactionRuntime;
+};
+export type StorageRegistry = {
+    register(kind: string, runtime: StorageRuntime, owner: string): void;
+    get(kind: string): StorageRuntime | undefined;
+};
+export type RuntimeStorageEntry = {
+    readonly kind: string;
+    readonly runtime: StorageRuntime;
+};
+export declare const compileStorageTemplates: (machines: MachineStore, machineKeys: readonly string[], storage: StorageRegistry, defaultStorageKind: string) => CompiledStorageTemplate[];

package/dist/runtime/kernel/storage.d.ts

@@ -0,0 +1,226 @@
+import type { MachineManagerOptions } from "../../interfaces";
+import type { ManagerRuntimeContext as PublicManagerRuntimeContext, ScopedInvocationContext } from "../../plugin";
+import type { StorageActionStageResult as PublicStorageActionStageResult, StorageDehydrateResult as PublicStorageDehydrateResult, StorageHydrateResult as PublicStorageHydrateResult, StoragePrepareActionResult as PublicStoragePrepareActionResult, StorageReduceResult as PublicStorageReduceResult, StorageRuntimeExtension as PublicStorageRuntimeExtension } from "../../pluginStorageTypes";
+import type { AnyEvent, DehydrateOptions, HydrateStrategy, MachinesState, MachineStore, ManagerAction, ReadonlyManagerAction } from "../../types";
+import type { RouteConstraint, RoutingRuntime } from "./routing";
+export type StorageRuntimeState = unknown;
+export type RuntimeIdentity = Readonly<Record<string, unknown>>;
+export type StorageEffectInvocation = unknown;
+export type StorageActionStageResult = PublicStorageActionStageResult;
+export type StorageReduceResult = PublicStorageReduceResult;
+export type ValidateTemplateContext = {
+    readonly key: string;
+    readonly machine: MachineStore[string];
+    readonly storageKind: string;
+};
+export type CompileTemplateContext = ValidateTemplateContext;
+export type CompiledStorageTemplate = {
+    readonly key: string;
+    readonly kind: string;
+    readonly data?: unknown;
+};
+export type CreateRuntimeStateContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly manager: ManagerRuntimeContext;
+};
+export type CreatePublicInitialStateContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly state: StorageRuntimeState;
+};
+export type AcceptsEventContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceContext = {
+    readonly template: CompiledStorageTemplate;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageBeforeReduceContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageReduceBucketContext = {
+    readonly templates: readonly CompiledStorageTemplate[];
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageCommitContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type ResolveEffectInvocationsContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageEffectInvocationContext = {
+    readonly invocation: StorageEffectInvocation;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StorageConditionContext = {
+    readonly predicate: (action: ReadonlyManagerAction<AnyEvent>) => boolean;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+};
+export type StorageDehydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly rootState: Record<string, unknown>;
+    readonly options: DehydrateOptions<MachineStore> | undefined;
+};
+export type StorageHydrateContext = {
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly machines: Readonly<Record<string, unknown>>;
+    readonly snapshot: unknown | undefined;
+    readonly baseState: Record<string, unknown>;
+    readonly strategy: HydrateStrategy;
+    readonly source: "hydrate" | "opts.snapshot";
+    readonly mode: "preview" | "commit" | "init";
+};
+export type ResolveIdentityContext = {
+    readonly state: StorageRuntimeState;
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+};
+export type StorageReactionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionContext = {
+    readonly action: ReadonlyManagerAction<AnyEvent>;
+    readonly originalAction: ReadonlyManagerAction<AnyEvent>;
+    readonly options: unknown;
+    readonly state: StorageRuntimeState;
+    readonly manager: ManagerRuntimeContext;
+    readonly dispatch: StorageDispatchContext;
+};
+export type StoragePrepareActionResult = PublicStoragePrepareActionResult;
+export type StorageHydrateResult = PublicStorageHydrateResult;
+export type StorageDehydrateResult = PublicStorageDehydrateResult<PublicStorageRuntimeExtension>;
+export type StorageDispatchContext = {
+    readonly options: unknown;
+    readonly runtime: Map<string, unknown>;
+    readonly route: RouteConstraint;
+    readonly prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    readonly skipDelivery: boolean;
+    reportError(error: unknown): void;
+};
+export type StorageDispatchOutcome = {
+    readonly type: "active";
+} | {
+    readonly type: "drop";
+    readonly action: ManagerAction<AnyEvent>;
+};
+export type StorageDispatchLifecycleContext = {
+    readonly originalAction: ManagerAction<AnyEvent>;
+    action: ManagerAction<AnyEvent>;
+    skipDelivery: boolean;
+    route: RouteConstraint;
+    prevState: Record<string, unknown>;
+    nextState: Record<string, unknown>;
+    nextCalled: boolean;
+    outcome: StorageDispatchOutcome;
+    touched: Set<string>;
+    readonly dispatch: StorageDispatchContext;
+};
+export type DispatchSlot<T> = {
+    readonly key: string;
+    get(dispatch: StorageDispatchContext): T | undefined;
+    set(dispatch: StorageDispatchContext, value: T): void;
+};
+export declare const createDispatchSlot: <T>(key: string) => DispatchSlot<T>;
+export type ManagerRuntimeContext<Events extends AnyEvent = AnyEvent, S extends MachineStore = MachineStore> = PublicManagerRuntimeContext<Events, S> & {
+    readonly config: S;
+    readonly options: MachineManagerOptions<any, any, any> | undefined;
+    readonly schemaVersion: number | undefined;
+    readonly routing: RoutingRuntime;
+    getState(): MachinesState<S>;
+    transition(action: ManagerAction<Events>, options?: unknown): ManagerAction<Events>;
+    onTransition(cb: (prevState: MachinesState<S>, currentState: MachinesState<S>, action: ReadonlyManagerAction<Events> | {
+        readonly type: string;
+        readonly payload?: unknown;
+    }) => void): () => void;
+    getDependencies(): Record<string, unknown>;
+    createScopedDeps(baseDeps: Record<string, unknown>, ctx: ScopedInvocationContext): Record<string, unknown>;
+};
+export type StorageRouteMetaDependencyKeys = readonly string[];
+export type StorageRuntimeBase = {
+    readonly kind: string;
+    readonly routeMetaKeys?: StorageRouteMetaDependencyKeys;
+    validateTemplate(ctx: ValidateTemplateContext): void;
+    compileTemplate(ctx: CompileTemplateContext): CompiledStorageTemplate;
+    createRuntimeState(ctx: CreateRuntimeStateContext): StorageRuntimeState;
+    createPublicInitialState(ctx: CreatePublicInitialStateContext): unknown;
+    prepareAction?(ctx: StoragePrepareActionContext): StoragePrepareActionResult;
+    beforeReduce?(ctx: StorageBeforeReduceContext): StorageActionStageResult;
+    commit(ctx: StorageCommitContext): void;
+};
+export type TemplateStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope?: "template";
+    acceptsEvent(ctx: AcceptsEventContext): boolean;
+    reduce(ctx: StorageReduceContext): StorageReduceResult;
+    readonly reduceBucket?: never;
+};
+export type BucketStorageRuntime = StorageRuntimeBase & {
+    readonly reduceScope: "bucket";
+    reduceBucket(ctx: StorageReduceBucketContext): StorageReduceResult;
+    readonly acceptsEvent?: never;
+    readonly reduce?: never;
+};
+export type StorageEffectsRuntime = {
+    condition?(ctx: StorageConditionContext): Promise<boolean>;
+    resolveInvocations(ctx: ResolveEffectInvocationsContext): readonly StorageEffectInvocation[];
+    invoke(ctx: StorageEffectInvocationContext): void;
+};
+export type StorageSnapshotRuntime = {
+    dehydrate(ctx: StorageDehydrateContext): StorageDehydrateResult;
+    hydrate(ctx: StorageHydrateContext): StorageHydrateResult;
+};
+export type StorageIdentityRuntime = {
+    resolve(ctx: ResolveIdentityContext): RuntimeIdentity | undefined;
+};
+export type StorageReactionRuntime = {
+    run(ctx: StorageReactionContext): void;
+};
+export type StorageRuntime = (TemplateStorageRuntime | BucketStorageRuntime) & {
+    readonly effects?: StorageEffectsRuntime;
+    readonly snapshot?: StorageSnapshotRuntime;
+    readonly identity?: StorageIdentityRuntime;
+    readonly reactions?: StorageReactionRuntime;
+};
+export type StorageRegistry = {
+    register(kind: string, runtime: StorageRuntime, owner: string): void;
+    get(kind: string): StorageRuntime | undefined;
+};
+export type RuntimeStorageEntry = {
+    readonly kind: string;
+    readonly runtime: StorageRuntime;
+};
+export declare const compileStorageTemplates: (machines: MachineStore, machineKeys: readonly string[], storage: StorageRegistry, defaultStorageKind: string) => CompiledStorageTemplate[];

package/dist/runtime/kernel/transitionGuard.d.cts

@@ -0,0 +1,4 @@
+import type { DispatchHookPhase } from "../../pluginTypes";
+export type TransitionGuardPhase = "storage.prepareAction" | "storage.beforeReduce" | "storage.acceptsEvent" | "storage.reduce" | "storage.reduceBucket" | "storage.commit" | "storage.reactions" | "plugin.intercept" | `hook.${DispatchHookPhase}`;
+export type GuardedCallbackRunner = <Result>(phase: TransitionGuardPhase, run: () => Result) => Result;
+export declare const throwTransitionGuardError: (phase: TransitionGuardPhase) => never;

package/dist/runtime/kernel/transitionGuard.d.ts

@@ -0,0 +1,4 @@
+import type { DispatchHookPhase } from "../../pluginTypes";
+export type TransitionGuardPhase = "storage.prepareAction" | "storage.beforeReduce" | "storage.acceptsEvent" | "storage.reduce" | "storage.reduceBucket" | "storage.commit" | "storage.reactions" | "plugin.intercept" | `hook.${DispatchHookPhase}`;
+export type GuardedCallbackRunner = <Result>(phase: TransitionGuardPhase, run: () => Result) => Result;
+export declare const throwTransitionGuardError: (phase: TransitionGuardPhase) => never;

package/dist/runtime/kernel/transitionTrace.d.cts

@@ -0,0 +1,40 @@
+import type { StorageDispatchContext } from "./storage";
+export declare const TRANSITION_TRACE_COLLECTOR_SYMBOL: unique symbol;
+export declare const TRANSITION_TRACE_RUNTIME_KEY = "@lite-fsm/core/transition-trace";
+export type TransitionTraceStatus = "ok" | "error";
+export type TransitionTracePhaseMetadata = {
+    readonly runtimeKind?: string;
+};
+export type TransitionTracePhaseRecord = {
+    readonly key: string;
+    readonly durationMs: number;
+    readonly runtimeKind?: string;
+};
+export type TransitionTraceCounterRecord = {
+    readonly key: string;
+    readonly value: number;
+};
+export type TransitionTraceRecord = {
+    readonly actionType: string | undefined;
+    readonly depth: number;
+    readonly status: TransitionTraceStatus;
+    readonly phases: readonly TransitionTracePhaseRecord[];
+    readonly counters: readonly TransitionTraceCounterRecord[];
+};
+export type TransitionTraceCollector = {
+    readonly records: TransitionTraceRecord[];
+};
+export type TransitionTraceSession = {
+    readonly depth: number;
+    now(): number;
+    record(key: string, startedAt: number, metadata?: TransitionTracePhaseMetadata): void;
+    count(key: string, value?: number): void;
+    finish(status: TransitionTraceStatus): void;
+};
+export declare const createTransitionTraceSession: (actionType: string | undefined) => TransitionTraceSession | undefined;
+export type TraceSpanRunner = <T>(key: string, run: () => T) => T;
+export declare const createTraceSpanRunner: (session: TransitionTraceSession | undefined) => TraceSpanRunner;
+export type BucketTraceRunner = <T>(phase: string, runtimeKind: string, run: () => T) => T;
+export declare const createBucketTraceRunner: (session: TransitionTraceSession | undefined) => BucketTraceRunner;
+export declare const attachTransitionTraceSession: (dispatch: StorageDispatchContext, session: TransitionTraceSession | undefined) => void;
+export declare const readTransitionTraceSession: (dispatch: StorageDispatchContext) => TransitionTraceSession | undefined;

package/dist/runtime/kernel/transitionTrace.d.ts

@@ -0,0 +1,40 @@
+import type { StorageDispatchContext } from "./storage";
+export declare const TRANSITION_TRACE_COLLECTOR_SYMBOL: unique symbol;
+export declare const TRANSITION_TRACE_RUNTIME_KEY = "@lite-fsm/core/transition-trace";
+export type TransitionTraceStatus = "ok" | "error";
+export type TransitionTracePhaseMetadata = {
+    readonly runtimeKind?: string;
+};
+export type TransitionTracePhaseRecord = {
+    readonly key: string;
+    readonly durationMs: number;
+    readonly runtimeKind?: string;
+};
+export type TransitionTraceCounterRecord = {
+    readonly key: string;
+    readonly value: number;
+};
+export type TransitionTraceRecord = {
+    readonly actionType: string | undefined;
+    readonly depth: number;
+    readonly status: TransitionTraceStatus;
+    readonly phases: readonly TransitionTracePhaseRecord[];
+    readonly counters: readonly TransitionTraceCounterRecord[];
+};
+export type TransitionTraceCollector = {
+    readonly records: TransitionTraceRecord[];
+};
+export type TransitionTraceSession = {
+    readonly depth: number;
+    now(): number;
+    record(key: string, startedAt: number, metadata?: TransitionTracePhaseMetadata): void;
+    count(key: string, value?: number): void;
+    finish(status: TransitionTraceStatus): void;
+};
+export declare const createTransitionTraceSession: (actionType: string | undefined) => TransitionTraceSession | undefined;
+export type TraceSpanRunner = <T>(key: string, run: () => T) => T;
+export declare const createTraceSpanRunner: (session: TransitionTraceSession | undefined) => TraceSpanRunner;
+export type BucketTraceRunner = <T>(phase: string, runtimeKind: string, run: () => T) => T;
+export declare const createBucketTraceRunner: (session: TransitionTraceSession | undefined) => BucketTraceRunner;
+export declare const attachTransitionTraceSession: (dispatch: StorageDispatchContext, session: TransitionTraceSession | undefined) => void;
+export declare const readTransitionTraceSession: (dispatch: StorageDispatchContext) => TransitionTraceSession | undefined;

package/dist/types.d.cts

@@ -15,9 +15,14 @@ export type FSMEventMeta = {
     senderGroupId?: string;
     senderGroupTag?: string;
 };
-export type ManagerAction<P extends AnyEvent> = P & {
-    meta?: FSMEventMeta;
-};
+export type CoreActionMeta = FSMEventMeta;
+export type ManagerAction<P extends AnyEvent, Meta extends object = CoreActionMeta> = P & {
+    meta?: Meta;
+};
+type DeepReadonly<Value> = Value extends (...args: any[]) => unknown ? Value : Value extends object ? {
+    readonly [Key in keyof Value]: DeepReadonly<Value[Key]>;
+} : Value;
+export type ReadonlyManagerAction<Events extends AnyEvent, Meta extends object = CoreActionMeta> = DeepReadonly<ManagerAction<Events, Meta>>;
 export type ActorMeta = {
     actorId: string;
     groupId: string;
@@ -99,14 +104,14 @@ export type HydrateAction<S extends MachineStore> = {
     };
 };
 export type ManagerCommitAction<S extends MachineStore, P extends AnyEvent = AnyEvent> = P | HydrateAction<S>;
-export type MiddlewareApi<S, P extends AnyEvent = AnyEvent> = {
+export type MiddlewareApi<S, P extends AnyEvent = AnyEvent, Meta extends object = CoreActionMeta> = {
     getState: () => S;
-    transition: (action: ManagerAction<P>) => ManagerAction<P>;
-    replaceReducer: (cb: (reducer: Reducer<S, ManagerAction<P>>) => Reducer<S, ManagerAction<P>>) => void;
+    transition: (action: ManagerAction<P, Meta>) => ManagerAction<P, Meta>;
+    replaceReducer: (cb: (reducer: Reducer<S, ManagerAction<P, Meta>>) => Reducer<S, ManagerAction<P, Meta>>) => void;
     onTransition: (cb: (prevState: S, currentState: S, action: ManagerCommitAction<MachineStore, AnyEvent>) => void) => () => void;
-    condition: (predicate: (a: ManagerAction<P>) => boolean) => Promise<boolean>;
+    condition: (predicate: (a: ManagerAction<P, Meta>) => boolean) => Promise<boolean>;
 };
-export type Middleware<S = unknown, P extends AnyEvent = AnyEvent> = (api: MiddlewareApi<S, P>) => (next: (action: ManagerAction<P>) => ManagerAction<P>) => (action: ManagerAction<P>) => ManagerAction<P>;
+export type Middleware<S = unknown, P extends AnyEvent = AnyEvent, Meta extends object = CoreActionMeta> = (api: MiddlewareApi<S, P, Meta>) => (next: (action: ManagerAction<P, Meta>) => ManagerAction<P, Meta>) => (action: ManagerAction<P, Meta>) => ManagerAction<P, Meta>;
 export type GenericMiddleware = <S, P extends AnyEvent>(api: MiddlewareApi<S, P>) => (next: (action: P) => P) => (action: P) => P;
 export type VoidReducerMiddleware = GenericMiddleware & {
     __liteFsmAllowVoidReducer: true;
@@ -148,7 +153,9 @@ export type ActorDefaultDeps<N extends SType, C extends object, P extends AnyEve
 };
 export type MachineEffect<N extends SType = WILDCARD, C extends object = Record<string, never>, P extends AnyEvent = AnyEvent, D extends AnyRecord = {}> = (deps: D & (HasLiteralInit<C> extends true ? ActorDefaultDeps<N, C, P> : DefaultDeps<N, C, P>)) => Promise<void> | void;
 export type EffectStateName<C extends object> = HasLiteralInit<C> extends true ? ActorPublicState<C> | WILDCARD : StateName<C> | WILDCARD;
+type CoreStorageKind = "instance";
 type BaseMachineConfig<C extends object, T extends AnyRecord, P extends AnyEvent, D extends AnyRecord> = {
+    storage?: CoreStorageKind;
     config: C;
     initialState: StateName<C>;
     initialContext: T;
@@ -177,6 +184,7 @@ type ActorPersistenceConfig<C extends object, T extends AnyRecord, Snapshot> = {
 });
 export type MachineConfig<C extends object, T extends AnyRecord, P extends AnyEvent, D extends AnyRecord = {}, Snapshot = HasLiteralInit<C> extends true ? DefaultActorSnapshot<C, T> : StateType<C, T>> = BaseMachineConfig<C, T, P, D> & (HasLiteralInit<C> extends true ? ActorPersistenceConfig<C, T, Snapshot> : DomainPersistenceConfig<C, T, Snapshot>);
 type AnyMachineConfig = {
+    storage?: unknown;
     config: object;
     initialState: string;
     initialContext: AnyRecord;
@@ -192,13 +200,25 @@ export type IsActorTemplate<M> = M extends {
     config: infer C extends object;
 } ? HasLiteralInit<C> : false;
 type ActorRuntimeRecord<C extends object, T extends AnyRecord> = Record<string, PublicActorSlice<C, T>>;
-export type MachineSliceState<M> = M extends {
+export type MachineRuntimeMetadata<M> = M extends {
+    readonly __liteFsmRuntime?: infer Metadata;
+} ? NonNullable<Metadata> : {};
+export type MachineResultMetadata<M> = MachineRuntimeMetadata<M> extends {
+    readonly resultMetadata: infer Metadata;
+} ? Metadata : {};
+type MachinePublicStateOverride<M> = MachineRuntimeMetadata<M> extends {
+    readonly publicState: infer PublicState;
+} ? PublicState : never;
+type DefaultMachineSliceState<M> = M extends {
     config: infer C extends object;
     initialContext: infer T extends AnyRecord;
 } ? IsActorTemplate<M> extends true ? ActorRuntimeRecord<C, T> : {
     state: StateName<C>;
     context: T;
 } : never;
+export type MachineSliceState<M> = [
+    MachinePublicStateOverride<M>
+] extends [never] ? DefaultMachineSliceState<M> : MachinePublicStateOverride<M>;
 export type MachinesState<S extends MachineStore> = {
     [key in keyof S]: MachineSliceState<S[key]>;
 };
@@ -254,12 +274,14 @@ export type MachineManagerSnapshot<S extends MachineStore> = {
     machines: Partial<{
         [key in SnapshotMachineKey<S>]: SnapshotForMachine<S[key]>;
     }>;
+    storage?: Record<string, unknown>;
 };
 export type MachineManagerDehydratedSnapshot<S extends MachineStore, K extends SnapshotMachineKey<S> = SnapshotMachineKey<S>> = {
     schemaVersion?: number;
     machines: {
         [key in K]: SnapshotForMachine<S[key]>;
     };
+    storage?: Record<string, unknown>;
 };
 export type MachineManagerDehydrateResult<S extends MachineStore, Keys extends ReadonlyArray<SnapshotMachineKey<S>>> = number extends Keys["length"] ? MachineManagerSnapshot<S> : MachineManagerDehydratedSnapshot<S, Keys[number]>;
 export type MachineManagerRuntimeSnapshot<S extends MachineStore> = {
@@ -270,17 +292,20 @@ export type MachineManagerRuntimeSnapshot<S extends MachineStore> = {
 };
 export type DehydrateOptions<S extends MachineStore, K extends SnapshotMachineKey<S> = SnapshotMachineKey<S>> = {
     machines?: ReadonlyArray<K>;
+    storage?: readonly string[];
 };
 export type MachineManagerDehydrateFn<S extends MachineStore> = {
     (opts?: {
         machines?: undefined;
+        storage?: readonly string[];
     }): MachineManagerDehydratedSnapshot<S>;
     <const Keys extends ReadonlyArray<SnapshotMachineKey<S>>>(opts: {
         machines: Keys;
+        storage?: readonly string[];
     }): MachineManagerDehydrateResult<S, Keys>;
     (opts: DehydrateOptions<S>): MachineManagerSnapshot<S>;
 };
-export type TransitionSubscriber<S extends MachineStore, P extends AnyEvent = AnyEvent> = (prevState: MachinesState<S>, currentState: MachinesState<S>, action: ManagerCommitAction<S, ManagerAction<P>>) => void;
+export type TransitionSubscriber<S extends MachineStore, P extends AnyEvent = AnyEvent, Meta extends object = CoreActionMeta> = (prevState: MachinesState<S>, currentState: MachinesState<S>, action: ManagerCommitAction<S, ManagerAction<P, Meta>>) => void;
 type IsAny<T> = 0 extends 1 & T ? true : false;
 type NoPayload = {
     readonly __liteFsmNoPayload: never;