Statechart runtime

type CommandObject = {
  readonly type: string;
  readonly [key: string]: JsonValue;
};

declare function createService<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output = never>(machine: Machine<Input, Value, Context, Event, Command, Output>, options: {
  input: Input;
  runCommand?: (command: Command, tools: {
    send: (event: Event) => void;
    signal: AbortSignal;
  }) => void | (() => void);
  onDiagnostic?: (diagnostic: DiagnosticObject & {
    readonly machineId: string;
  }) => void;
  onError?: (error: ServiceError<Value, Context, Event, Command, Output>) => void;
}): Service<Input, Value, Context, Event, Command, Output>;

type DiagnosticObject = {
  readonly code: string;
  readonly message: string;
  readonly severity: "warning" | "error";
  readonly data?: JsonValue;
};

type EventObject = {
  readonly type: string;
};

type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
  readonly [key: string]: JsonValue;
};

interface Machine<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject = never, Output = never> {
  readonly id: string;
  initial(input: Readonly<Input>): Transition<Value, Context, Command, Output>;
  transition(state: MachineState<Value, Context, Output>, event: Readonly<Event>, input: Readonly<Input>): Transition<Value, Context, Command, Output>;
  sync?(state: MachineState<Value, Context, Output>, previous: Readonly<Input>, next: Readonly<Input>): Transition<Value, Context, Command, Output>;
}

interface MachineState<Value extends StateValue, Context, Output = never> {
  readonly value: Value;
  readonly context: Readonly<Context>;
  readonly output?: Output;
}

interface Service<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output = never> {
  start(): void;
  stop(): void;
  getSnapshot(): Snapshot<Value, Context, Output>;
  getInput(): Readonly<Input>;
  send(event: Event): Snapshot<Value, Context, Output>;
  setInput(next: Input): Snapshot<Value, Context, Output>;
  subscribe<Selected>(selector: (snapshot: Snapshot<Value, Context, Output>) => Selected, listener: (value: Selected, previous: Selected) => void, options?: {
    equals?: (a: Selected, b: Selected) => boolean;
    immediate?: boolean;
  }): () => void;
  batch<Result>(work: () => Result): Result;
}

interface ServiceError<Value extends StateValue, Context, Event, Command, Output = never> {
  readonly phase: "start" | "transition" | "sync" | "diagnostic" | "command";
  readonly cause: unknown;
  readonly machineId: string;
  readonly snapshot: Snapshot<Value, Context, Output>;
  readonly event?: Event;
  readonly diagnostic?: DiagnosticObject;
  readonly command?: Command;
}

interface Snapshot<Value extends StateValue, Context, Output = never> {
  readonly value: Value;
  readonly context: Readonly<Context>;
  readonly version: number;
  readonly status: "idle" | "active" | "done" | "stopped" | "error";
  readonly output?: Output;
  readonly error?: unknown;
}

type StateValue = string | {
  readonly [region: string]: StateValue;
};

interface Transition<Value extends StateValue, Context, Command extends CommandObject, Output = never> {
  readonly state: MachineState<Value, Context, Output>;
  readonly commands?: readonly Command[];
  readonly diagnostics?: readonly DiagnosticObject[];
}

type Action<C, E, I, Cmd extends CommandObject> = AssignAction<C, E, I> | CommandAction<C, E, I, Cmd> | BindingAction<any, C, E, I, Cmd>;

type ActionArgs<C, E, I> = {
  readonly context: C;
  readonly event: E;
  readonly input: I;
};

declare function assign<C, E, I>(fn: (args: ActionArgs<C, E, I>) => Partial<C>): AssignAction<C, E, I>;

interface AssignAction<C, E, I> {
  readonly __kind: "assign";
  readonly fn: (args: ActionArgs<C, E, I>) => Partial<C>;
}

declare function bindable<V, C = unknown, E = unknown, I = unknown>(options: BindableOptions<V>): BindableSpec<V, C, E, I>;

type BindableOptions<V> = ContextBackedBindableOptions | StateBackedBindableOptions<V>;

interface BindableSpec<V, C, E, I> {
  readonly __kind: "bindable";
  readonly prop: string;
  readonly defaultProp: string;
  readonly stateFor?: (value: V) => string;
  readonly valueOf?: (state: string) => V;
  set<Cmd extends CommandObject>(fn: (args: ActionArgs<C, E, I> & {
    readonly current: V;
  }) => V, requestFactory: (value: V, context: C, event: E) => Cmd): BindingSetAction<V, C, E, I, Cmd>;
  reset(): BindingResetAction<V, C, E, I>;
}

type BindingAction<V, C, E, I, Cmd extends CommandObject> = BindingSetAction<V, C, E, I, Cmd> | BindingResetAction<V, C, E, I>;

interface BindingResetAction<V, C, E, I> {
  readonly __kind: "binding";
  readonly op: "reset";
  readonly binding: BindableSpec<V, C, E, I>;
}

interface BindingSetAction<V, C, E, I, Cmd extends CommandObject> {
  readonly __kind: "binding";
  readonly op: "set";
  readonly binding: BindableSpec<V, C, E, I>;
  readonly fn: (args: ActionArgs<C, E, I> & {
    readonly current: V;
  }) => V;
  readonly requestFactory: (value: V, context: C, event: E) => Cmd;
}

interface Candidate<I, C, E extends EventObject, Cmd extends CommandObject> {
  readonly guard?: (args: ActionArgs<C, E, I>) => boolean;
  readonly target?: string;
  readonly actions?: readonly Action<C, E, I, Cmd>[];
}

export declare const CANDIDATE_KEYS: ReadonlySet<string>;

declare function candidateList<I, C, E extends EventObject, Cmd extends CommandObject>(entry: Candidate<I, C, E, Cmd> | readonly Candidate<I, C, E, Cmd>[]): readonly Candidate<I, C, E, Cmd>[];

declare function collectDefinitionIssues(definition: MachineDefinition<any, any, any, any, any>): readonly DefinitionIssue[];

declare function command<C, E, I, Cmd extends CommandObject>(fn: (args: ActionArgs<C, E, I>) => Cmd): CommandAction<C, E, I, Cmd>;

interface CommandAction<C, E, I, Cmd extends CommandObject> {
  readonly __kind: "command";
  readonly fn: (args: ActionArgs<C, E, I>) => Cmd;
}

declare function defineMachine<I, V extends StateValue, C, E extends EventObject, Cmd extends CommandObject = never>(definition: MachineDefinition<I, V, C, E, Cmd>): MachineDefinition<I, V, C, E, Cmd>;

interface DefinitionIssue {
  readonly code: string;
  readonly message: string;
  readonly path: string;
}

export declare const MACHINE_KEYS: ReadonlySet<string>;

interface MachineDefinition<I, V extends StateValue, C, E extends EventObject, Cmd extends CommandObject = never> {
  readonly id: string;
  readonly types?: {
    readonly input: I;
    readonly context: C;
    readonly events: E;
    readonly commands: Cmd;
  };
  readonly bindings?: Readonly<Record<string, BindableSpec<any, C, E, I>>>;
  readonly context: (args: {
    readonly input: I;
    readonly bindings: Readonly<Record<string, unknown>>;
  }) => C;
  readonly initial: string | ((args: {
    readonly input: I;
  }) => string);
  readonly states: Readonly<Record<string, StateDefinition<I, C, E, Cmd>>>;
}

export declare const STATE_KEYS: ReadonlySet<string>;

interface StateDefinition<I, C, E extends EventObject, Cmd extends CommandObject> {
  readonly on?: Readonly<Record<string, Candidate<I, C, E, Cmd> | readonly Candidate<I, C, E, Cmd>[]>>;
}

declare function toMachine<I, V extends StateValue, C, E extends EventObject, Cmd extends CommandObject = never>(definition: MachineDefinition<I, V, C, E, Cmd>): Machine<I, V, C, E, Cmd>;

declare function attachInspector<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output>(service: Service<Input, Value, Context, Event, Command, Output>, machineId: string, emit: (record: InspectorRecord) => void, inspectorOptions?: InspectorOptions): () => void;

declare function attachInspectorV2<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output>(service: Service<Input, Value, Context, Event, Command, Output>, meta: {
  readonly serviceId: string;
  readonly machineId: string;
}, emit: (record: InspectorRecordV2) => void, options?: {
  readonly now?: () => number;
}): () => void;

interface DevtoolsHook extends DevtoolsRegistrationHook {
  unregister(serviceId: string): void;
  list(): readonly DevtoolsServiceMeta[];
  subscribe(listener: (meta: DevtoolsServiceMeta, record: InspectorRecordV2) => void): () => void;
}

interface DevtoolsRegistrationHook {
  readonly hookVersion: number;
  register<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output>(service: Service<Input, Value, Context, Event, Command, Output>, machine: Machine<Input, Value, Context, Event, Command, Output>, meta: Omit<DevtoolsServiceMeta, "mountedAt">): () => void;
}

interface DevtoolsServiceMeta {
  readonly serviceId: string;
  readonly machineId: string;
  readonly componentKey: string;
  readonly framework: "react" | "vue" | "solid" | "svelte" | "angular" | "vanilla";
  readonly scopeSeed: string;
  readonly mountedAt: number;
}

export declare const HOOK_GLOBAL_KEY: "__GRASSROOT_DEVTOOLS_HOOK__";

export declare const HOOK_VERSION: 1;

export declare const INSPECTOR_PROTOCOL_VERSION: 1;

export declare const INSPECTOR_PROTOCOL_VERSION_2: 2;

interface InspectorOptions {
  now?: () => number;
}

type InspectorRecord = {
  protocol: 1;
  kind: "snapshot";
  machineId: string;
  version: number;
  status: string;
  value: StateValue;
  at: number;
} | {
  protocol: 1;
  kind: "command";
  machineId: string;
  command: CommandObject;
  at: number;
} | {
  protocol: 1;
  kind: "diagnostic";
  machineId: string;
  diagnostic: DiagnosticObject;
  at: number;
} | {
  protocol: 1;
  kind: "error";
  machineId: string;
  phase: string;
  at: number;
};

type InspectorRecordV2 = (RecordBase & {
  readonly kind: "snapshot";
  readonly version: number;
  readonly status: Snapshot<any, any, any>["status"];
  readonly value: StateValue;
  readonly context: unknown;
}) | (RecordBase & {
  readonly kind: "event";
  readonly event: EventObject;
  readonly queuePosition: number;
  readonly source: "external" | "command" | "scheduled";
}) | (RecordBase & {
  readonly kind: "transition";
  readonly from: StateValue;
  readonly to: StateValue;
  readonly event: EventObject;
  readonly commands: readonly CommandObject[];
  readonly diagnostics: readonly DiagnosticObject[];
  readonly durationMs: number;
}) | (RecordBase & {
  readonly kind: "input";
  readonly prev: unknown;
  readonly next: unknown;
}) | (RecordBase & {
  readonly kind: "lifecycle";
  readonly phase: "start" | "stop";
}) | (RecordBase & {
  readonly kind: "command";
  readonly command: CommandObject;
}) | (RecordBase & {
  readonly kind: "diagnostic";
  readonly diagnostic: DiagnosticObject;
}) | (RecordBase & {
  readonly kind: "error";
  readonly phase: string;
});

type RedactHook = (path: readonly (string | number)[], value: unknown) => JsonValue | undefined;

declare function registerWithHook<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output>(service: Service<Input, Value, Context, Event, Command, Output>, machine: Machine<Input, Value, Context, Event, Command, Output>, meta: Omit<DevtoolsServiceMeta, "mountedAt">): (() => void) | undefined;

declare function serializeContext(context: unknown, redact?: RedactHook): JsonValue;

declare function withInspector<Opts extends ServiceOptionsConstraint>(machineId: string, options: Opts, emit: (record: InspectorRecord) => void, inspectorOptions?: InspectorOptions): Opts;

interface DevtoolsRegistrationHook {
  readonly hookVersion: number;
  register<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output>(service: Service<Input, Value, Context, Event, Command, Output>, machine: Machine<Input, Value, Context, Event, Command, Output>, meta: Omit<DevtoolsServiceMeta, "mountedAt">): () => void;
}

interface DevtoolsServiceMeta {
  readonly serviceId: string;
  readonly machineId: string;
  readonly componentKey: string;
  readonly framework: "react" | "vue" | "solid" | "svelte" | "angular" | "vanilla";
  readonly scopeSeed: string;
  readonly mountedAt: number;
}

export declare const HOOK_GLOBAL_KEY: "__GRASSROOT_DEVTOOLS_HOOK__";

export declare const HOOK_VERSION: 1;

declare function registerWithHook<Input, Value extends StateValue, Context, Event extends EventObject, Command extends CommandObject, Output>(service: Service<Input, Value, Context, Event, Command, Output>, machine: Machine<Input, Value, Context, Event, Command, Output>, meta: Omit<DevtoolsServiceMeta, "mountedAt">): (() => void) | undefined;

declare function migratePersistedSnapshot(data: unknown): PersistedSnapshot;

interface PersistedSnapshot {
  readonly schema: typeof SNAPSHOT_SCHEMA_VERSION;
  readonly machineId: string;
  readonly value: StateValue;
  readonly context: JsonValue;
  readonly version: number;
  readonly status: "idle" | "active" | "done" | "stopped" | "error";
  readonly output?: JsonValue;
}

declare function restoreService(): never;

declare function serializeSnapshot(machineId: string, snapshot: Snapshot<any, any, any>): PersistedSnapshot;

export declare const SNAPSHOT_SCHEMA_VERSION: 2;

declare function validatePersistedSnapshot(machineId: string, data: unknown): {
  ok: true;
  snapshot: PersistedSnapshot;
} | {
  ok: false;
  reason: "schema-version-mismatch" | "machine-mismatch" | "malformed";
  detail: string;
};

type CancelCommand = {
  readonly type: "statechart.cancel";
  readonly key: string;
};

declare function createNativeScheduler(): Scheduler;

declare function createScheduledEventRunner<Command extends CommandObject, Event extends EventObject>(scheduler: Scheduler, next?: RunCommand<Command, Event>): RunCommand<Command | ScheduledEventCommand<Event>, Event>;

declare function createVirtualScheduler(): VirtualScheduler;

type RunCommand<Command extends CommandObject, Event extends EventObject> = (command: Command, tools: RunCommandTools<Event>) => void | (() => void);

interface RunCommandTools<Event extends EventObject> {
  readonly send: (event: Event) => void;
  readonly signal: AbortSignal;
}