small-state 0.2.0 → 0.3.0

package/README.ja.md

@@ -9,6 +9,13 @@ A state machine inspired by [XState](https://stately.ai/docs/xstate).
 - 迷子になりにくい記述
 
 
+## Installation
+
+```
+npm i small-state
+```
+
+
 ## FSM（Finite State Machine / 有限ステートマシン）とは
 
 有限個の状態と、状態間の遷移を定義するモデル。
@@ -237,8 +244,26 @@ idle 内で LOGIN_SUCCESS を受け取ると、定義に従い "loggedIn" ステ
     - 'notStarted' - まだ .start() されていない。
     - 'active' - .start() され、稼働している。
     - 'stopped' - .stop() され、停止している。
-    - 'done' - 最終状態に入り完了し、停止した。
+    - 'done' - 最終状態に入り完了し、正常停止した。
     - 'error' - エラーで停止した。
+  - `type Runtime<M extends AnyMachine>`
+  - `type Snapshot<M extends AnyMachine>` - Runtime の getSnapshot の項参照。
+
+### 補助関数
+
+- `isMachine(v: unknown): v is AnyMachine` - 引数がマシンかどうかを判定。
+- `isRuntime(v: unknown): v is Runtime<AnyMachine>` - 引数がランタイムかどうかを判定。
+- `defServiceFn(serviceFn: ServiceFn): ServiceFn`
+  - サービス関数を定義する。
+  - マシン外部でサービス関数を定義するときか、invoke に直接関数を渡すときに裸の関数だと型推論が崩れてしまうが、この関数でラップすることで型を通すことができる。
+- `waitFor<R extends Runtime<any>>(runtime, cond, options?): Promise<SnapshotFrom<R>>` - 渡した runtime が条件を満たすまで待機する。
+
+
+### メイン関数
+
+- `makeMachine(config, states): Machine` - マシンを作る。
+- `makeRuntime(machine, option?): Runtime` - マシンを実際に動かすランタイムを作る。
+
 
 ### 予約されているイベントタイプ
 
@@ -253,16 +278,6 @@ idle 内で LOGIN_SUCCESS を受け取ると、定義に従い "loggedIn" ステ
   - `{type: ':done:', output: unknown}` - そのサービスが正常終了したときに発火する
   - `{type: ':error:', error: unknown}` - そのサービスが異常狩猟したときに発火する
 
-### 補助関数
-
-- `defServiceFn(serviceFn): ServiceFn` - サービス関数を定義する。
-  - マシン外部でサービス関数を定義するときか、invoke に直接関数を渡すときに裸の関数だと型推論が崩れてしまうが、この関数でラップすることで型を通すことができる。
-- `waitFor<RT extends Runtime<any>>(runtime, cond, options?): Promise<SnapshotFrom<RT>>` - 渡した runtime が条件を満たすまで待機する。
-
-### メイン関数
-
-- `makeMachine(config, states): Machine` - マシンを作る。
-- `makeRuntime(machine, option?): Runtime` - マシンを実際に動かすランタイムを作る。
 
 ### `makeMachine(config: MachineConfig, defineStates: (tools)=>Record<string, StateDefinition>): Machine`
 
@@ -473,7 +488,8 @@ Runtime は以下のメンバーを持つ:
     - `output: O | undefined` - ランタイムが最終状態に入るまでは undefined。最終状態に入ったとき計算され結果がここに設定される。
     - `error: unknown` - エラーが生じてランタイムが停止したときにそのエラー内容が入る。それまでは undefined。
     - `_children` - デバッグ用。業務では使用しないのが望ましい。キーにサービス名、値に invoke などで起動中のサービスが入る。subKey を設定して起動している場合、キーは `${serviceName}:${subKey}` になる。
-  - 怠惰のために runtime から直接プロパティでsnapshot を参照できる getter が用意されている。以下のものが設定されている。
+    - `_runtime` - このスナップショットを作ったランタイム自身。
+  - 怠惰のために runtime から直接プロパティでsnapshot を参照できる getter が用意されている。以下のものが設定されている:
     - states, stateValue, context, runtimeStatus, output
 - `subscribe(onSnapshot: ((current: Snapshot, prev: Snapshot)=>void)|undefined, onError?:(err:unknown)=>void): UnsubscribeFn`
   - snapshot が更新されるたびに呼ばれる観測関数を登録する。ただし第一引数の関数はエラーは監視しない。それは省略可能な第二引数の関数の役割である。
@@ -508,6 +524,7 @@ Runtime は以下のメンバーを持つ:
 |  | XState | small-state |
 | - | - | - |
 | パス区切り文字 | `.` | `/` |
+| ロジックを持つのは | マシン | ランタイム |
 | context 更新 | assign | update: action内引数 |
 | 子から親への通信 | sendParent | emit |
 | 親から子への通信に使うもの | actor id | service name (と subKey) |
@@ -545,5 +562,3 @@ Runtime は以下のメンバーを持つ:
 - parallel のインターフェースの改修
   - もう少し分かりやすく
   - 連続で入れ子にできないのを改善する
-- error 時に正しく捕捉しランタイムを "error" 状態にする
-- Runtime のエラーメッセージにマシン名を入れる。

package/README.md

@@ -13,6 +13,13 @@ A state machine library inspired by [XState](https://stately.ai/docs/xstate).
 - Clean syntax that is hard to get lost in
 
 
+## Installation
+
+```
+npm i small-state
+```
+
+
 ## What is an FSM (Finite State Machine)?
 
 A Finite State Machine is a computational model defined by a finite number of states and transitions between those states.
@@ -243,8 +250,25 @@ Since `loggedIn` is defined as `null`, it acts as a final state. The machine sto
     - `'notStarted'` - `.start()` has not been called yet.
     - `'active'` - `.start()` has been called and the machine is running.
     - `'stopped'` - `.stop()` was called and execution is halted.
-    - `'done'` - The machine reached a final state and finished execution.
+    - `'done'` - Entered the final state, completed, and successfully stopped.
     - `'error'` - Execution stopped due to an error.
+  - `type Runtime<M AnyMachine extends>`
+  - `type Snapshot<M AnyMachine extends>` - Refer to the Runtime getSnapshot section.
+
+### Utility Functions
+
+- `isMachine(v: unknown): v is AnyMachine` - Determines whether the argument is a machine.
+- `isRuntime(v: unknown): v is Runtime<AnyMachine>` - Determines whether the argument is a runtime.
+- `defServiceFn(serviceFn): ServiceFn`
+  - Defines a service function.
+  - Passing plain functions directly to `invoke` or defining them outside a machine configuration might cause type inference to break. Wrapping them with `defServiceFn` preserves type inference.
+- `waitFor<R extends Runtime<any>>(runtime, cond, options?): Promise<SnapshotFrom<R>>` - Returns a Promise that resolves when the specified `runtime` satisfies `cond`.
+
+### Primary Functions
+
+- `makeMachine(config, states): Machine` - Creates a machine definition.
+- `makeRuntime(machine, option?): Runtime` - Creates an executable runtime instance for a machine.
+
 
 ### Reserved Event Types
 
@@ -259,17 +283,6 @@ The following event names are currently reserved:
   - `{type: ':done:', output: unknown}` - Fires when the invoked service completes successfully.
   - `{type: ':error:', error: unknown}` - Fires when the invoked service terminates with an error.
 
-### Utility Functions
-
-- `defServiceFn(serviceFn): ServiceFn` - Defines a service function.
-  - Passing plain functions directly to `invoke` or defining them outside a machine configuration might cause type inference to break. Wrapping them with `defServiceFn` preserves type inference.
-- `waitFor<RT extends Runtime<any>>(runtime, cond, options?): Promise<SnapshotFrom<RT>>` - Returns a Promise that resolves when the specified `runtime` satisfies `cond`.
-
-### Primary Functions
-
-- `makeMachine(config, states): Machine` - Creates a machine definition.
-- `makeRuntime(machine, option?): Runtime` - Creates an executable runtime instance for a machine.
-
 ### `makeMachine(config: MachineConfig, defineStates: (tools)=>Record<string, StateDefinition>): Machine`
 
 #### makeMachine > `MachineConfig`
@@ -478,6 +491,7 @@ Runtime instances expose the following members:
     - `output: O | undefined` - Contains final execution output values when `runtimeStatus === 'done'`; `undefined` otherwise.
     - `error: unknown` - Contains error details if execution halted due to errors; `undefined` otherwise.
     - `_children` - Debugging member. Keyed by service name mapping to running service instances. When `subKey` is present, keys map as `${serviceName}:${subKey}`.
+    - `_runtime` - The runtime instance itself that generated this snapshot.
   - Direct shortcut getters exist on `runtime` instances for convenience:
     - `states`, `stateValue`, `context`, `runtimeStatus`, `output`
 - `subscribe(onSnapshot: ((current: Snapshot, prev: Snapshot)=>void)|undefined, onError?:(err:unknown)=>void): UnsubscribeFn`
@@ -513,6 +527,7 @@ Runtime instances expose the following members:
 | Feature / Behavior | XState | small-state |
 | - | - | - |
 | Path Delimiter | `.` | `/` |
+| Logic ownership | Machine | Runtime |
 | Context Updates | `assign` | `update` argument inside action handlers |
 | Child to Parent Messaging | `sendParent` | `emit` |
 | Parent to Child Messaging | actor id | service name (and optional `subKey`) |
@@ -550,5 +565,3 @@ The following features are not supported:
 - Refactor `parallel` interface structure
   - Improve clarity and usability
   - Support nested continuous parallel structures
-- Improve error handling to catch runtime errors reliably and set status to `"error"`
-- Include machine name strings in Runtime error messages

package/dist/index.cjs

@@ -519,6 +519,11 @@ function getDefinitionAndCatalog(config, defineStates) {
 function defServiceFn(fn) {
 	return fn;
 }
+function isMachine(v) {
+	if (!(v && typeof v === "object" && "internal" in v)) return false;
+	const { internal } = v;
+	return !!(internal && typeof internal === "object" && MachineSymbol in internal);
+}
 function makeMachine(config, defineStates) {
 	const { definition, topLvDefItem, stateCatalog } = getDefinitionAndCatalog(config, defineStates);
 	const { name, initContext, output, guards, actions, services } = config;
@@ -1487,6 +1492,9 @@ function exitAndEntry(tExecs, crrStates, actionRunner, { guards, services, state
 }
 //#endregion
 //#region src/runtime/Runtime.ts
+function isRuntime(v) {
+	return v instanceof Runtime;
+}
 function makeRuntime(machine, options) {
 	return new Runtime(machine, options);
 }
@@ -1663,8 +1671,10 @@ var Runtime = class {
 					output: void 0
 				}, this.#input)),
 				error: void 0,
-				_children: this.#outbound.children
+				_children: this.#outbound.children,
+				_runtime: this
 			};
+			Object.defineProperty(this.#snapshot, "_runtime", { enumerable: false });
 			{
 				const snapshot = this.#snapshot;
 				for (const { onSnapshot } of this.#subscribers) {
@@ -1737,6 +1747,8 @@ async function waitFor(runtime, cond, options) {
 }
 //#endregion
 exports.defServiceFn = defServiceFn;
+exports.isMachine = isMachine;
+exports.isRuntime = isRuntime;
 exports.makeMachine = makeMachine;
 exports.makeRuntime = makeRuntime;
 exports.waitFor = waitFor;

package/dist/index.d.cts

@@ -59,7 +59,9 @@ type EmittableEvent = {
   [key: string]: any;
 };
 type StateName = string;
-type PureETypeString<E extends SendableEvent> = E extends unknown ? Exclude<keyof E, "type"> extends never ? E['type'] : never : any;
+type O_PureETypeString<E extends SendableEvent> = E extends unknown ? Exclude<keyof E, "type"> extends never ? E['type'] : never : any;
+type O_InferMachineSendableEvent<M extends AnyMachine> = M extends Machine<any, infer E, any, any, any, any, any, any, any> ? E : never;
+type SendFnEvent<M extends AnyMachine> = O_InferMachineSendableEvent<M> extends (infer E extends SendableEvent) ? E | O_PureETypeString<E> : never;
 type FnBaseParams<C extends MContext, Ex extends SendableEvent, I, Additional = unknown, Prm = any> = [arg: Expand<{
   c: C;
   context: C;
@@ -98,10 +100,10 @@ type EnqueueFn<C extends MContext, Ex extends SendableEvent, I, EM extends Emitt
 };
 type UpdateFnParam<C extends MContext> = { [K in keyof C]?: C[K] | (() => (C[K])); };
 type UpdateFn<C extends MContext> = (updates: UpdateFnParam<C>) => unknown;
-type O_InferSendableEvent<S extends ServiceRecord[string]> = S extends Machine<any, infer E, any, any, any, any, any, any, any> ? E : S extends AnyFn ? (Parameters<S>[2] extends ListenFn<infer Er> ? Er : never) : never;
+type O_InferServiceSendableEvent<S extends ServiceRecord[string]> = S extends Machine<any, infer E, any, any, any, any, any, any, any> ? E : S extends AnyFn ? (Parameters<S>[2] extends ListenFn<infer Er> ? Er : never) : never;
 type SendToFn<S extends ServiceRecord> = {
-  <Sk extends keyof S>(serviceName: Sk, subKey: string | number, event: O_InferSendableEvent<S[Sk]>): void;
-  <Sk extends keyof S>(serviceName: Sk, event: O_InferSendableEvent<S[Sk]>): void;
+  <Sk extends keyof S>(serviceName: Sk, subKey: string | number, event: O_InferServiceSendableEvent<S[Sk]>): void;
+  <Sk extends keyof S>(serviceName: Sk, event: O_InferServiceSendableEvent<S[Sk]>): void;
 };
 type EmitFn<EM extends EmittableEvent> = (event: EM) => void;
 type ListenFn<E extends SendableEvent> = (listener: (event: E) => void) => void;
@@ -212,7 +214,7 @@ type X_HiddenImpl = any & {
   __brand: 'HiddenImpl';
 };
 type X_DefTypeRefluxer<C extends MContext, E extends SendableEvent, I // Input
-, EM extends EmittableEvent, G extends Record<string, Placeholder>, A extends Record<string, Placeholder>, S extends ServiceRecord = ServiceRecord, Eb extends BuiltinEType = BuiltinEType, R = unknown> = () => R;
+, EM extends EmittableEvent, G extends Record<string, Placeholder>, A extends Record<string, Placeholder>, S extends ServiceRecord = ServiceRecord, Eb extends BuiltinEType = BuiltinEType, Ret = unknown> = () => Ret;
 type X_DefineStatesTools = {
   on: typeof on;
   entryHook: typeof entryHook;
@@ -292,13 +294,14 @@ declare function invoke<C extends MContext, E extends SendableEvent, I, EM exten
 declare function invoke<C extends MContext, E extends SendableEvent, I, EM extends EmittableEvent, const G extends Record<string, Placeholder>, const A extends Record<string, Placeholder>, S extends ServiceRecord, Src extends keyof S | InvokeSrcExpr<[SrcInput] extends [never] ? any : SrcInput>, SrcInput = never>(service: Src, config: InvokeConfig<C, E, I, S, Src, SrcInput>, ...events: InvocationEvents<C, I, EM, G, A, S, O_InferIvkSrcTypes<Src, S>>): readonly [typeof InvokeSymbol, X_DefTypeRefluxer<C, E, I, EM, G, A, S, BuiltinEType, unknown>, null, X_HiddenImpl, X_HiddenImpl, InvocationEvents<C, I, EM, G, A, S, O_InferIvkSrcTypes<Src, S>>];
 type X_GlobalEvents<C extends MContext, E extends SendableEvent, I, EM extends EmittableEvent, G extends Record<string, Placeholder>, A extends Record<string, Placeholder>> = Array<readonly [E['type'] | BuiltinEType, X_DefTypeRefluxer<C, E, I, EM, G, A>, X_HiddenImpl]>;
 export declare function defServiceFn<TFn extends ServiceFn>(fn: TFn): TFn;
-export declare function makeMachine<C extends MContext, const E extends SendableEvent, const I, const EM extends EmittableEvent, const O, const S extends ServiceRecord, const D extends { [K in string]: StateDefinition<C, E, I, EM, G, A, S>; }, const G extends Record<string, Placeholder> = Record<string, Placeholder>, const A extends Record<string, Placeholder> = Record<string, Placeholder>>(config: Expand<MachineConfig<C, E, I, EM, O, G, A, S>>, defineStates: (defineStatesTools: Expand<X_DefineStatesTools>) => readonly [X_GlobalEvents<C, E, I, EM, G, A>, D] | readonly [D] | D): Readonly<Machine<C, E, I, EM, O, G, A, S, {
+export declare function isMachine(v: unknown): v is AnyMachine;
+export declare function makeMachine<C extends MContext, const E extends SendableEvent, const I, const EM extends EmittableEvent, const O, const S extends ServiceRecord, const D extends { [K in string]: StateDefinition<C, E, I, EM, G, A, S>; }, const G extends Record<string, Placeholder> = Record<string, Placeholder>, const A extends Record<string, Placeholder> = Record<string, Placeholder>>(config: Expand<MachineConfig<C, E, I, EM, O, G, A, S>>, defineStates: (defineStatesTools: Expand<X_DefineStatesTools>) => readonly [X_GlobalEvents<C, E, I, EM, G, A>, D] | readonly [D] | D): Machine<C, E, I, EM, O, G, A, S, {
   initial: string;
   stateOf: { [K in keyof D]: {
     def: NStateItemDef<X_ExtractEType<D[K]>>;
     sub: X_ExtractSubStDefinition<D[K]>;
   }; };
-}>>;
+}>;
 //#endregion
 //#region src/runtime/r.types.d.ts
 type Child<TService> = TService extends AnyMachine ? Runtime<TService> : TService extends AnyFn ? {
@@ -308,82 +311,59 @@ type Child<TService> = TService extends AnyMachine ? Runtime<TService> : TServic
 type Children<S extends ServiceRecord> = { [K in keyof S & string as K | `${K}:${string | number}`]?: Child<S[K]>; } & {
   [key: string]: Child<any>;
 };
-type InferredMachineTypes<M extends AnyMachine> = IsAny<M> extends true ? {
-  C: any;
-  E: any;
-  I: any;
-  EM: any;
-  O: any;
-  G: any;
-  A: any;
-  S: any;
-  ND: any;
-  M: AnyMachine;
-} : M extends Machine<infer C, infer E, infer I, infer EM, infer O, infer G, infer A, infer S, infer ND> ? {
-  C: C;
-  E: E;
-  I: I;
-  EM: EM;
-  O: O;
-  G: G;
-  A: A;
-  S: S;
-  ND: ND;
-  M: Machine<C, E, I, EM, O, G, A, S, ND>;
-} : never;
-type InferMInput<M extends AnyMachine> = M extends Machine<any, any, infer I, any, any, any, any, any, any> ? I : never;
-type SnapshotFrom<RT extends Runtime<any>> = RT extends Runtime<any, infer Mt> ? Snapshot<Mt['C'], Mt['O'], Mt['S']> : never;
+type SnapshotFrom<R extends Runtime<any>> = R extends Runtime<infer M> ? Snapshot<M> : never;
 //#endregion
 //#region src/runtime/Runtime.d.ts
 type RuntimeStatus = 'notStarted' | 'active' | 'stopped' | 'done' | 'error';
-type Snapshot<C extends MContext, O, S extends ServiceRecord> = {
+type C<M extends AnyMachine> = M extends Machine<infer C, any, any, any, any, any, any, any, any> ? C : never;
+type I<M extends AnyMachine> = M extends Machine<any, any, infer I, any, any, any, any, any, any> ? I : never;
+type EM$1<M extends AnyMachine> = M extends Machine<any, any, any, infer EM, any, any, any, any, any> ? EM : never;
+type O$1<M extends AnyMachine> = M extends Machine<any, any, any, any, infer O, any, any, any, any> ? O : never;
+type S<M extends AnyMachine> = M extends Machine<any, any, any, any, any, any, any, infer S, any> ? S : never;
+type X_RemovePrivateKeys<T extends Record<string, unknown>> = { [K in keyof T as K extends `_${string}` ? never : K]: T[K]; };
+type Snapshot<M extends AnyMachine> = {
   runtimeId: string;
   states: string[];
   stateValue: string | string[] | undefined;
-  context: Expand<X_RemovePrivateKeys<C>>;
-  c: Expand<X_RemovePrivateKeys<C>>;
+  context: Expand<X_RemovePrivateKeys<C<M>>>;
+  c: Expand<X_RemovePrivateKeys<C<M>>>;
   runtimeStatus: RuntimeStatus;
-  output: O | undefined;
+  output: O$1<M> | undefined;
   error: unknown;
-  _children: Children<S>;
+  _children: Children<S<M>>;
+  _runtime: Runtime<M>;
 };
-type Subscriber<C extends MContext, O, S extends ServiceRecord> = {
-  onSnapshot?: (current: Expand<Snapshot<C, O, S>>, prev: Expand<Snapshot<C, O, S>>) => void;
+type Subscriber<M extends AnyMachine> = {
+  onSnapshot?: (current: Expand<Snapshot<M>>, prev: Expand<Snapshot<M>>) => void;
   onError?: (err: unknown) => void;
 };
-type RuntimeOptions<I> = {
+export declare function isRuntime(v: unknown): v is Runtime<AnyMachine>;
+type RuntimeOptions<M extends AnyMachine> = {
   id?: string;
-  input?: () => I;
+  input?: () => I<M>;
 };
-type X_RemovePrivateKeys<T extends Record<string, unknown>> = { [K in keyof T as K extends `_${string}` ? never : K]: T[K]; };
-export declare function makeRuntime<M extends AnyMachine>(machine: M, options?: RuntimeOptions<InferMInput<M>>): Runtime<M, InferredMachineTypes<M>>;
-type C$1<Mt extends InferredMachineTypes<any>> = Mt['C'];
-type E$1<Mt extends InferredMachineTypes<any>> = Mt['E'];
-type I$1<Mt extends InferredMachineTypes<any>> = Mt['I'];
-type EM$1<Mt extends InferredMachineTypes<any>> = Mt['EM'];
-type O$1<Mt extends InferredMachineTypes<any>> = Mt['O'];
-type S$1<Mt extends InferredMachineTypes<any>> = Mt['S'];
-declare class Runtime<M extends AnyMachine, Mt extends InferredMachineTypes<M> = InferredMachineTypes<M>> {
+export declare function makeRuntime<M extends AnyMachine>(machine: M, options?: RuntimeOptions<M>): Runtime<M>;
+declare class Runtime<M extends AnyMachine> {
   #private;
   readonly id: string;
-  readonly machine: Mt['M'];
+  readonly machine: M;
   get states(): string[];
   get stateValue(): string | string[] | undefined;
-  get context(): X_RemovePrivateKeys<C$1<Mt>> extends (infer T) ? { [K in keyof T]: X_RemovePrivateKeys<C$1<Mt>>[K]; } : never;
+  get context(): X_RemovePrivateKeys<C<M>> extends (infer T) ? { [K in keyof T]: X_RemovePrivateKeys<C<M>>[K]; } : never;
   get runtimeStatus(): RuntimeStatus;
-  get output(): O$1<Mt> | undefined;
-  getSnapshot(): Snapshot<C$1<Mt>, O$1<Mt>, S$1<Mt>>;
-  constructor(machine: M, { id, input }?: RuntimeOptions<I$1<Mt>>);
-  subscribe(onSnapshot: Subscriber<C$1<Mt>, O$1<Mt>, S$1<Mt>>['onSnapshot'], onError?: Subscriber<C$1<Mt>, O$1<Mt>, S$1<Mt>>['onError']): () => void;
+  get output(): O$1<M> | undefined;
+  getSnapshot(): Snapshot<M>;
+  constructor(machine: M, { id, input }?: RuntimeOptions<I<M>>);
+  subscribe(onSnapshot: Subscriber<M>['onSnapshot'], onError?: Subscriber<M>['onError']): () => void;
   start(): this;
-  send(event: E$1<Mt> | PureETypeString<E$1<Mt>>): this;
+  send(event: SendFnEvent<M>): this;
   stop(): this;
-  onEmitted(emittedEventType: EM$1<Mt>['type'], handler: (emittedEvent: EM$1<Mt>) => void): () => void;
+  onEmitted(emittedEventType: EM$1<M>['type'], handler: (emittedEvent: EM$1<M>) => void): () => void;
 }
 //#endregion
 //#region src/tools/waitFor.d.ts
-export declare function waitFor<RT extends Runtime<any>>(runtime: RT, cond: (snapshot: SnapshotFrom<RT>) => boolean, options?: {
+export declare function waitFor<R extends Runtime<any>>(runtime: R, cond: (snapshot: SnapshotFrom<R>) => boolean, options?: {
   timeout?: number;
-}): Promise<SnapshotFrom<RT>>;
+}): Promise<SnapshotFrom<R>>;
 //#endregion
-export type { AnyMachine, BuiltinEType, EmitFn as Emit, EmittableEvent, ListenFn as Listen, MContext, Runtime, RuntimeOptions, RuntimeStatus, SendableEvent, ServiceFn };
+export type { AnyMachine, BuiltinEType, EmitFn as Emit, EmittableEvent, ListenFn as Listen, MContext, Runtime, RuntimeOptions, RuntimeStatus, SendFnEvent, SendableEvent, ServiceFn, Snapshot };

package/dist/index.d.mts

@@ -59,7 +59,9 @@ type EmittableEvent = {
   [key: string]: any;
 };
 type StateName = string;
-type PureETypeString<E extends SendableEvent> = E extends unknown ? Exclude<keyof E, "type"> extends never ? E['type'] : never : any;
+type O_PureETypeString<E extends SendableEvent> = E extends unknown ? Exclude<keyof E, "type"> extends never ? E['type'] : never : any;
+type O_InferMachineSendableEvent<M extends AnyMachine> = M extends Machine<any, infer E, any, any, any, any, any, any, any> ? E : never;
+type SendFnEvent<M extends AnyMachine> = O_InferMachineSendableEvent<M> extends (infer E extends SendableEvent) ? E | O_PureETypeString<E> : never;
 type FnBaseParams<C extends MContext, Ex extends SendableEvent, I, Additional = unknown, Prm = any> = [arg: Expand<{
   c: C;
   context: C;
@@ -98,10 +100,10 @@ type EnqueueFn<C extends MContext, Ex extends SendableEvent, I, EM extends Emitt
 };
 type UpdateFnParam<C extends MContext> = { [K in keyof C]?: C[K] | (() => (C[K])); };
 type UpdateFn<C extends MContext> = (updates: UpdateFnParam<C>) => unknown;
-type O_InferSendableEvent<S extends ServiceRecord[string]> = S extends Machine<any, infer E, any, any, any, any, any, any, any> ? E : S extends AnyFn ? (Parameters<S>[2] extends ListenFn<infer Er> ? Er : never) : never;
+type O_InferServiceSendableEvent<S extends ServiceRecord[string]> = S extends Machine<any, infer E, any, any, any, any, any, any, any> ? E : S extends AnyFn ? (Parameters<S>[2] extends ListenFn<infer Er> ? Er : never) : never;
 type SendToFn<S extends ServiceRecord> = {
-  <Sk extends keyof S>(serviceName: Sk, subKey: string | number, event: O_InferSendableEvent<S[Sk]>): void;
-  <Sk extends keyof S>(serviceName: Sk, event: O_InferSendableEvent<S[Sk]>): void;
+  <Sk extends keyof S>(serviceName: Sk, subKey: string | number, event: O_InferServiceSendableEvent<S[Sk]>): void;
+  <Sk extends keyof S>(serviceName: Sk, event: O_InferServiceSendableEvent<S[Sk]>): void;
 };
 type EmitFn<EM extends EmittableEvent> = (event: EM) => void;
 type ListenFn<E extends SendableEvent> = (listener: (event: E) => void) => void;
@@ -212,7 +214,7 @@ type X_HiddenImpl = any & {
   __brand: 'HiddenImpl';
 };
 type X_DefTypeRefluxer<C extends MContext, E extends SendableEvent, I // Input
-, EM extends EmittableEvent, G extends Record<string, Placeholder>, A extends Record<string, Placeholder>, S extends ServiceRecord = ServiceRecord, Eb extends BuiltinEType = BuiltinEType, R = unknown> = () => R;
+, EM extends EmittableEvent, G extends Record<string, Placeholder>, A extends Record<string, Placeholder>, S extends ServiceRecord = ServiceRecord, Eb extends BuiltinEType = BuiltinEType, Ret = unknown> = () => Ret;
 type X_DefineStatesTools = {
   on: typeof on;
   entryHook: typeof entryHook;
@@ -292,13 +294,14 @@ declare function invoke<C extends MContext, E extends SendableEvent, I, EM exten
 declare function invoke<C extends MContext, E extends SendableEvent, I, EM extends EmittableEvent, const G extends Record<string, Placeholder>, const A extends Record<string, Placeholder>, S extends ServiceRecord, Src extends keyof S | InvokeSrcExpr<[SrcInput] extends [never] ? any : SrcInput>, SrcInput = never>(service: Src, config: InvokeConfig<C, E, I, S, Src, SrcInput>, ...events: InvocationEvents<C, I, EM, G, A, S, O_InferIvkSrcTypes<Src, S>>): readonly [typeof InvokeSymbol, X_DefTypeRefluxer<C, E, I, EM, G, A, S, BuiltinEType, unknown>, null, X_HiddenImpl, X_HiddenImpl, InvocationEvents<C, I, EM, G, A, S, O_InferIvkSrcTypes<Src, S>>];
 type X_GlobalEvents<C extends MContext, E extends SendableEvent, I, EM extends EmittableEvent, G extends Record<string, Placeholder>, A extends Record<string, Placeholder>> = Array<readonly [E['type'] | BuiltinEType, X_DefTypeRefluxer<C, E, I, EM, G, A>, X_HiddenImpl]>;
 export declare function defServiceFn<TFn extends ServiceFn>(fn: TFn): TFn;
-export declare function makeMachine<C extends MContext, const E extends SendableEvent, const I, const EM extends EmittableEvent, const O, const S extends ServiceRecord, const D extends { [K in string]: StateDefinition<C, E, I, EM, G, A, S>; }, const G extends Record<string, Placeholder> = Record<string, Placeholder>, const A extends Record<string, Placeholder> = Record<string, Placeholder>>(config: Expand<MachineConfig<C, E, I, EM, O, G, A, S>>, defineStates: (defineStatesTools: Expand<X_DefineStatesTools>) => readonly [X_GlobalEvents<C, E, I, EM, G, A>, D] | readonly [D] | D): Readonly<Machine<C, E, I, EM, O, G, A, S, {
+export declare function isMachine(v: unknown): v is AnyMachine;
+export declare function makeMachine<C extends MContext, const E extends SendableEvent, const I, const EM extends EmittableEvent, const O, const S extends ServiceRecord, const D extends { [K in string]: StateDefinition<C, E, I, EM, G, A, S>; }, const G extends Record<string, Placeholder> = Record<string, Placeholder>, const A extends Record<string, Placeholder> = Record<string, Placeholder>>(config: Expand<MachineConfig<C, E, I, EM, O, G, A, S>>, defineStates: (defineStatesTools: Expand<X_DefineStatesTools>) => readonly [X_GlobalEvents<C, E, I, EM, G, A>, D] | readonly [D] | D): Machine<C, E, I, EM, O, G, A, S, {
   initial: string;
   stateOf: { [K in keyof D]: {
     def: NStateItemDef<X_ExtractEType<D[K]>>;
     sub: X_ExtractSubStDefinition<D[K]>;
   }; };
-}>>;
+}>;
 //#endregion
 //#region src/runtime/r.types.d.ts
 type Child<TService> = TService extends AnyMachine ? Runtime<TService> : TService extends AnyFn ? {
@@ -308,82 +311,59 @@ type Child<TService> = TService extends AnyMachine ? Runtime<TService> : TServic
 type Children<S extends ServiceRecord> = { [K in keyof S & string as K | `${K}:${string | number}`]?: Child<S[K]>; } & {
   [key: string]: Child<any>;
 };
-type InferredMachineTypes<M extends AnyMachine> = IsAny<M> extends true ? {
-  C: any;
-  E: any;
-  I: any;
-  EM: any;
-  O: any;
-  G: any;
-  A: any;
-  S: any;
-  ND: any;
-  M: AnyMachine;
-} : M extends Machine<infer C, infer E, infer I, infer EM, infer O, infer G, infer A, infer S, infer ND> ? {
-  C: C;
-  E: E;
-  I: I;
-  EM: EM;
-  O: O;
-  G: G;
-  A: A;
-  S: S;
-  ND: ND;
-  M: Machine<C, E, I, EM, O, G, A, S, ND>;
-} : never;
-type InferMInput<M extends AnyMachine> = M extends Machine<any, any, infer I, any, any, any, any, any, any> ? I : never;
-type SnapshotFrom<RT extends Runtime<any>> = RT extends Runtime<any, infer Mt> ? Snapshot<Mt['C'], Mt['O'], Mt['S']> : never;
+type SnapshotFrom<R extends Runtime<any>> = R extends Runtime<infer M> ? Snapshot<M> : never;
 //#endregion
 //#region src/runtime/Runtime.d.ts
 type RuntimeStatus = 'notStarted' | 'active' | 'stopped' | 'done' | 'error';
-type Snapshot<C extends MContext, O, S extends ServiceRecord> = {
+type C<M extends AnyMachine> = M extends Machine<infer C, any, any, any, any, any, any, any, any> ? C : never;
+type I<M extends AnyMachine> = M extends Machine<any, any, infer I, any, any, any, any, any, any> ? I : never;
+type EM$1<M extends AnyMachine> = M extends Machine<any, any, any, infer EM, any, any, any, any, any> ? EM : never;
+type O$1<M extends AnyMachine> = M extends Machine<any, any, any, any, infer O, any, any, any, any> ? O : never;
+type S<M extends AnyMachine> = M extends Machine<any, any, any, any, any, any, any, infer S, any> ? S : never;
+type X_RemovePrivateKeys<T extends Record<string, unknown>> = { [K in keyof T as K extends `_${string}` ? never : K]: T[K]; };
+type Snapshot<M extends AnyMachine> = {
   runtimeId: string;
   states: string[];
   stateValue: string | string[] | undefined;
-  context: Expand<X_RemovePrivateKeys<C>>;
-  c: Expand<X_RemovePrivateKeys<C>>;
+  context: Expand<X_RemovePrivateKeys<C<M>>>;
+  c: Expand<X_RemovePrivateKeys<C<M>>>;
   runtimeStatus: RuntimeStatus;
-  output: O | undefined;
+  output: O$1<M> | undefined;
   error: unknown;
-  _children: Children<S>;
+  _children: Children<S<M>>;
+  _runtime: Runtime<M>;
 };
-type Subscriber<C extends MContext, O, S extends ServiceRecord> = {
-  onSnapshot?: (current: Expand<Snapshot<C, O, S>>, prev: Expand<Snapshot<C, O, S>>) => void;
+type Subscriber<M extends AnyMachine> = {
+  onSnapshot?: (current: Expand<Snapshot<M>>, prev: Expand<Snapshot<M>>) => void;
   onError?: (err: unknown) => void;
 };
-type RuntimeOptions<I> = {
+export declare function isRuntime(v: unknown): v is Runtime<AnyMachine>;
+type RuntimeOptions<M extends AnyMachine> = {
   id?: string;
-  input?: () => I;
+  input?: () => I<M>;
 };
-type X_RemovePrivateKeys<T extends Record<string, unknown>> = { [K in keyof T as K extends `_${string}` ? never : K]: T[K]; };
-export declare function makeRuntime<M extends AnyMachine>(machine: M, options?: RuntimeOptions<InferMInput<M>>): Runtime<M, InferredMachineTypes<M>>;
-type C$1<Mt extends InferredMachineTypes<any>> = Mt['C'];
-type E$1<Mt extends InferredMachineTypes<any>> = Mt['E'];
-type I$1<Mt extends InferredMachineTypes<any>> = Mt['I'];
-type EM$1<Mt extends InferredMachineTypes<any>> = Mt['EM'];
-type O$1<Mt extends InferredMachineTypes<any>> = Mt['O'];
-type S$1<Mt extends InferredMachineTypes<any>> = Mt['S'];
-declare class Runtime<M extends AnyMachine, Mt extends InferredMachineTypes<M> = InferredMachineTypes<M>> {
+export declare function makeRuntime<M extends AnyMachine>(machine: M, options?: RuntimeOptions<M>): Runtime<M>;
+declare class Runtime<M extends AnyMachine> {
   #private;
   readonly id: string;
-  readonly machine: Mt['M'];
+  readonly machine: M;
   get states(): string[];
   get stateValue(): string | string[] | undefined;
-  get context(): X_RemovePrivateKeys<C$1<Mt>> extends (infer T) ? { [K in keyof T]: X_RemovePrivateKeys<C$1<Mt>>[K]; } : never;
+  get context(): X_RemovePrivateKeys<C<M>> extends (infer T) ? { [K in keyof T]: X_RemovePrivateKeys<C<M>>[K]; } : never;
   get runtimeStatus(): RuntimeStatus;
-  get output(): O$1<Mt> | undefined;
-  getSnapshot(): Snapshot<C$1<Mt>, O$1<Mt>, S$1<Mt>>;
-  constructor(machine: M, { id, input }?: RuntimeOptions<I$1<Mt>>);
-  subscribe(onSnapshot: Subscriber<C$1<Mt>, O$1<Mt>, S$1<Mt>>['onSnapshot'], onError?: Subscriber<C$1<Mt>, O$1<Mt>, S$1<Mt>>['onError']): () => void;
+  get output(): O$1<M> | undefined;
+  getSnapshot(): Snapshot<M>;
+  constructor(machine: M, { id, input }?: RuntimeOptions<I<M>>);
+  subscribe(onSnapshot: Subscriber<M>['onSnapshot'], onError?: Subscriber<M>['onError']): () => void;
   start(): this;
-  send(event: E$1<Mt> | PureETypeString<E$1<Mt>>): this;
+  send(event: SendFnEvent<M>): this;
   stop(): this;
-  onEmitted(emittedEventType: EM$1<Mt>['type'], handler: (emittedEvent: EM$1<Mt>) => void): () => void;
+  onEmitted(emittedEventType: EM$1<M>['type'], handler: (emittedEvent: EM$1<M>) => void): () => void;
 }
 //#endregion
 //#region src/tools/waitFor.d.ts
-export declare function waitFor<RT extends Runtime<any>>(runtime: RT, cond: (snapshot: SnapshotFrom<RT>) => boolean, options?: {
+export declare function waitFor<R extends Runtime<any>>(runtime: R, cond: (snapshot: SnapshotFrom<R>) => boolean, options?: {
   timeout?: number;
-}): Promise<SnapshotFrom<RT>>;
+}): Promise<SnapshotFrom<R>>;
 //#endregion
-export type { AnyMachine, BuiltinEType, EmitFn as Emit, EmittableEvent, ListenFn as Listen, MContext, Runtime, RuntimeOptions, RuntimeStatus, SendableEvent, ServiceFn };
+export type { AnyMachine, BuiltinEType, EmitFn as Emit, EmittableEvent, ListenFn as Listen, MContext, Runtime, RuntimeOptions, RuntimeStatus, SendFnEvent, SendableEvent, ServiceFn, Snapshot };

package/dist/index.mjs

@@ -518,6 +518,11 @@ function getDefinitionAndCatalog(config, defineStates) {
 function defServiceFn(fn) {
 	return fn;
 }
+function isMachine(v) {
+	if (!(v && typeof v === "object" && "internal" in v)) return false;
+	const { internal } = v;
+	return !!(internal && typeof internal === "object" && MachineSymbol in internal);
+}
 function makeMachine(config, defineStates) {
 	const { definition, topLvDefItem, stateCatalog } = getDefinitionAndCatalog(config, defineStates);
 	const { name, initContext, output, guards, actions, services } = config;
@@ -1486,6 +1491,9 @@ function exitAndEntry(tExecs, crrStates, actionRunner, { guards, services, state
 }
 //#endregion
 //#region src/runtime/Runtime.ts
+function isRuntime(v) {
+	return v instanceof Runtime;
+}
 function makeRuntime(machine, options) {
 	return new Runtime(machine, options);
 }
@@ -1662,8 +1670,10 @@ var Runtime = class {
 					output: void 0
 				}, this.#input)),
 				error: void 0,
-				_children: this.#outbound.children
+				_children: this.#outbound.children,
+				_runtime: this
 			};
+			Object.defineProperty(this.#snapshot, "_runtime", { enumerable: false });
 			{
 				const snapshot = this.#snapshot;
 				for (const { onSnapshot } of this.#subscribers) {
@@ -1735,4 +1745,4 @@ async function waitFor(runtime, cond, options) {
 	});
 }
 //#endregion
-export { defServiceFn, makeMachine, makeRuntime, waitFor };
+export { defServiceFn, isMachine, isRuntime, makeMachine, makeRuntime, waitFor };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "small-state",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A state machine inspired by XState.",
   "author": "qyvvy",
   "license": "MIT",
@@ -27,7 +27,9 @@
     "dist",
     "THIRD_PARTY_LICENSES.md"
   ],
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "arktype": "^2.2.8"
   },