@camcima/finita 1.0.0

package/README.md

@@ -0,0 +1,176 @@
+<div align="center">
+
+<picture>
+  <img alt="finita" src="assets/logo.svg" width="480">
+</picture>
+
+<br>
+
+[![CI](https://github.com/camcima/finita/actions/workflows/ci.yml/badge.svg)](https://github.com/camcima/finita/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/camcima/finita/graph/badge.svg)](https://codecov.io/gh/camcima/finita)
+[![npm version](https://img.shields.io/npm/v/finita)](https://www.npmjs.com/package/finita)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18%20%7C%2020%20%7C%2022-green.svg)](https://nodejs.org/)
+
+</div>
+
+A full-featured finite state machine (FSM) library for TypeScript.
+
+This library is a TypeScript port of [metabor/statemachine](https://github.com/Metabor/Statemachine), the PHP state machine library created by **Oliver Tischlinger**. The original library was the engine behind _Bob_ -- the backend component of the _Alice & Bob_ retail system that [Rocket Internet](https://www.rocket-internet.com/) used to power its e-commerce ventures worldwide. The author of this TypeScript port and Oliver worked together at Rocket Internet, where the state machine proved itself at scale across multiple global operations.
+
+## Features
+
+- **Async-First** -- all conditions, observers, and mutexes support async operations via `MaybePromise<T>` return types
+- **States, Transitions, Events** -- define complex workflows declaratively
+- **Conditions (Guards)** -- control when transitions are allowed, with composable AND/OR/NOT logic
+- **Observers (Commands)** -- execute side effects when events fire or states change
+- **Automatic Transitions** -- transitions that fire when a condition becomes true, without an explicit event
+- **Transition Selectors** -- pluggable strategies for resolving ambiguous transitions (score-based, weight-based)
+- **Mutex/Locking** -- concurrency control with pluggable lock adapters
+- **Factory Pattern** -- create pre-configured state machines from subject objects
+- **Process Merging** -- combine state collections with optional name prefixing
+- **Graph Visualization** -- build graph data structures for rendering with GraphViz or other tools
+- **Setup Helper** -- fluent API for building state machines from configuration
+- **Zero Dependencies** -- no runtime dependencies
+
+## Installation
+
+```bash
+npm install finita
+```
+
+## Quick Start
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft
+    draft --> published : publish
+    published --> archived : archive
+    archived --> draft : reopen
+```
+
+```typescript
+import { State, Transition, Process, Statemachine } from "finita";
+
+// Define states
+const draft = new State("draft");
+const published = new State("published");
+const archived = new State("archived");
+
+// Define transitions
+draft.addTransition(new Transition(published, "publish"));
+published.addTransition(new Transition(archived, "archive"));
+archived.addTransition(new Transition(draft, "reopen"));
+
+// Create process and state machine
+const process = new Process("article-workflow", draft);
+const article = { title: "Hello World" };
+const sm = new Statemachine(article, process);
+
+console.log(sm.getCurrentState().getName()); // 'draft'
+
+await sm.triggerEvent("publish");
+console.log(sm.getCurrentState().getName()); // 'published'
+
+await sm.triggerEvent("archive");
+console.log(sm.getCurrentState().getName()); // 'archived'
+
+// Note: use top-level await (supported in ES modules) or wrap in an async function.
+```
+
+## Concepts
+
+A state machine consists of:
+
+| Concept          | Description                                                                                                          |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **State**        | A named node in the workflow graph. Holds transitions, events, and metadata.                                         |
+| **Transition**   | A directed edge from one state to another, optionally guarded by a condition and triggered by an event.              |
+| **Event**        | A named trigger attached to a state. When invoked, it fires observers (commands) and initiates transitions.          |
+| **Condition**    | A guard that determines whether a transition is active.                                                              |
+| **Process**      | A named collection of states that defines a complete workflow, starting from an initial state.                       |
+| **Statemachine** | The runtime orchestrator that manages the current state, triggers events, checks conditions, and notifies observers. |
+| **Observer**     | A callback that reacts to events or state changes.                                                                   |
+
+```mermaid
+classDiagram
+    direction LR
+    Process *-- State : contains
+    State *-- Transition : has outgoing
+    State *-- Event : has named
+    Transition --> State : targets
+    Transition --> Condition : guarded by
+    Event --> Observer : notifies
+    Statemachine --> Process : uses
+    Statemachine --> State : tracks current
+    Statemachine --> Observer : notifies on change
+```
+
+## Documentation
+
+Detailed documentation for every component:
+
+- **[Core](docs/core.md)** -- State, Transition, Event, Process, Statemachine, Dispatcher, StateCollection
+- **[Conditions](docs/conditions.md)** -- Tautology, Contradiction, CallbackCondition, Timeout, AndComposite, OrComposite, Not
+- **[Observers](docs/observers.md)** -- CallbackObserver, StatefulStatusChanger, OnEnterObserver, TransitionLogger
+- **[Filters](docs/filters.md)** -- ActiveTransitionFilter, FilterStateByEvent, FilterStateByTransition, FilterStateByFinalState, FilterTransitionByEvent
+- **[Selectors](docs/selectors.md)** -- OneOrNoneActiveTransition, ScoreTransition, WeightTransition
+- **[Mutex](docs/mutex.md)** -- NullMutex, LockAdapterMutex, MutexFactory
+- **[Factory](docs/factory.md)** -- Factory, SingleProcessDetector, AbstractNamedProcessDetector, StatefulStateNameDetector
+- **[Utilities](docs/utilities.md)** -- SetupHelper, StateCollectionMerger
+- **[Graph](docs/graph.md)** -- GraphBuilder
+- **[Errors](docs/errors.md)** -- WrongEventForStateError, LockCanNotBeAcquiredError, DuplicateStateError
+- **[Interfaces](docs/interfaces.md)** -- All TypeScript interfaces
+
+## Examples
+
+A complete working example (order processing with prepayment and postpayment workflows) is available in the [finita-example](https://github.com/camcima/finita-example) repository.
+
+## Architecture
+
+```
+src/
+  index.ts                 # Barrel export
+  MaybePromise.ts          # MaybePromise<T> = T | Promise<T> utility type
+  Event.ts                 # Event implementation
+  State.ts                 # State implementation
+  Transition.ts            # Transition implementation
+  StateCollection.ts       # Named collection of states
+  Process.ts               # Process (workflow definition)
+  Statemachine.ts          # Runtime state machine
+  Dispatcher.ts            # Deferred event dispatcher
+  interfaces/              # All TypeScript interfaces
+  condition/               # Condition (guard) implementations
+  observer/                # Observer implementations
+  filter/                  # State and transition filters
+  selector/                # Transition selection strategies
+  mutex/                   # Locking implementations
+  factory/                 # State machine factory pattern
+  util/                    # SetupHelper, StateCollectionMerger
+  graph/                   # Graph visualization builder
+  error/                   # Custom error classes
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Type check
+npm run lint
+
+# Build
+npm run build
+```
+
+## License
+
+MIT

package/dist/Dispatcher.d.ts

@@ -0,0 +1,11 @@
+import type { DispatcherInterface, CallbackInterface } from "./interfaces/DispatcherInterface.js";
+import type { EventInterface } from "./interfaces/EventInterface.js";
+export declare class Dispatcher implements DispatcherInterface {
+    private commands;
+    private onReadyCallbacks;
+    private ready;
+    dispatch(event: EventInterface, args?: unknown[], onReadyCallback?: CallbackInterface): void;
+    invoke(): Promise<void>;
+    isReady(): boolean;
+}
+//# sourceMappingURL=Dispatcher.d.ts.map

package/dist/Dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.d.ts","sourceRoot":"","sources":["../src/Dispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,qBAAa,UAAW,YAAW,mBAAmB;IACpD,OAAO,CAAC,QAAQ,CAAyD;IACzE,OAAO,CAAC,gBAAgB,CAA2B;IACnD,OAAO,CAAC,KAAK,CAAS;IAEtB,QAAQ,CACN,KAAK,EAAE,cAAc,EACrB,IAAI,GAAE,OAAO,EAAO,EACpB,eAAe,CAAC,EAAE,iBAAiB,GAClC,IAAI;IAUD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAa7B,OAAO,IAAI,OAAO;CAGnB"}

package/dist/Dispatcher.js

@@ -0,0 +1,30 @@
+export class Dispatcher {
+    commands = [];
+    onReadyCallbacks = [];
+    ready = false;
+    dispatch(event, args = [], onReadyCallback) {
+        if (this.ready) {
+            throw new Error("Was already invoked!");
+        }
+        this.commands.push({ event, args });
+        if (onReadyCallback) {
+            this.onReadyCallbacks.push(onReadyCallback);
+        }
+    }
+    async invoke() {
+        if (this.ready) {
+            throw new Error("Was already invoked!");
+        }
+        for (const { event, args } of this.commands) {
+            await event.invoke(...args);
+        }
+        this.ready = true;
+        for (const callback of this.onReadyCallbacks) {
+            await callback.invoke();
+        }
+    }
+    isReady() {
+        return this.ready;
+    }
+}
+//# sourceMappingURL=Dispatcher.js.map

package/dist/Dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.js","sourceRoot":"","sources":["../src/Dispatcher.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,UAAU;IACb,QAAQ,GAAsD,EAAE,CAAC;IACjE,gBAAgB,GAAwB,EAAE,CAAC;IAC3C,KAAK,GAAG,KAAK,CAAC;IAEtB,QAAQ,CACN,KAAqB,EACrB,OAAkB,EAAE,EACpB,eAAmC;QAEnC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpC,IAAI,eAAe,EAAE,CAAC;YACpB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;QAC1C,CAAC;QACD,KAAK,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5C,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC7C,MAAM,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}

package/dist/Event.d.ts

@@ -0,0 +1,22 @@
+import type { EventInterface } from "./interfaces/EventInterface.js";
+import type { Observer } from "./interfaces/Observer.js";
+export declare class Event implements EventInterface {
+    private readonly name;
+    private readonly observers;
+    private readonly metadata;
+    private invokeArgs;
+    constructor(name: string);
+    getName(): string;
+    getInvokeArgs(): unknown[];
+    invoke(...args: unknown[]): Promise<void>;
+    attach(observer: Observer): void;
+    detach(observer: Observer): void;
+    notify(): Promise<void>;
+    getObservers(): Iterable<Observer>;
+    getMetadata(): Record<string, unknown>;
+    getMetadataValue(key: string): unknown;
+    setMetadataValue(key: string, value: unknown): void;
+    hasMetadataValue(key: string): boolean;
+    deleteMetadataValue(key: string): void;
+}
+//# sourceMappingURL=Event.d.ts.map

package/dist/Event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Event.d.ts","sourceRoot":"","sources":["../src/Event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,qBAAa,KAAM,YAAW,cAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,UAAU,CAAiB;gBAEvB,IAAI,EAAE,MAAM;IAIxB,OAAO,IAAI,MAAM;IAIjB,aAAa,IAAI,OAAO,EAAE;IAIpB,MAAM,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAIhC,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAI1B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B,YAAY,IAAI,QAAQ,CAAC,QAAQ,CAAC;IAIlC,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAItC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAItC,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAInD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAItC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGvC"}

package/dist/Event.js

@@ -0,0 +1,54 @@
+export class Event {
+    name;
+    observers = new Set();
+    metadata = new Map();
+    invokeArgs = [];
+    constructor(name) {
+        this.name = name;
+    }
+    getName() {
+        return this.name;
+    }
+    getInvokeArgs() {
+        return this.invokeArgs;
+    }
+    async invoke(...args) {
+        this.invokeArgs = args;
+        try {
+            await this.notify();
+        }
+        finally {
+            this.invokeArgs = [];
+        }
+    }
+    attach(observer) {
+        this.observers.add(observer);
+    }
+    detach(observer) {
+        this.observers.delete(observer);
+    }
+    async notify() {
+        for (const observer of this.observers) {
+            await observer.update(this);
+        }
+    }
+    getObservers() {
+        return this.observers;
+    }
+    getMetadata() {
+        return Object.fromEntries(this.metadata);
+    }
+    getMetadataValue(key) {
+        return this.metadata.get(key);
+    }
+    setMetadataValue(key, value) {
+        this.metadata.set(key, value);
+    }
+    hasMetadataValue(key) {
+        return this.metadata.has(key);
+    }
+    deleteMetadataValue(key) {
+        this.metadata.delete(key);
+    }
+}
+//# sourceMappingURL=Event.js.map

package/dist/Event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Event.js","sourceRoot":"","sources":["../src/Event.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,KAAK;IACC,IAAI,CAAS;IACb,SAAS,GAAkB,IAAI,GAAG,EAAE,CAAC;IACrC,QAAQ,GAAyB,IAAI,GAAG,EAAE,CAAC;IACpD,UAAU,GAAc,EAAE,CAAC;IAEnC,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAG,IAAe;QAC7B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,CAAC,QAAkB;QACvB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,MAAM,CAAC,QAAkB;QACvB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,MAAM;QACV,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,WAAW;QACT,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,gBAAgB,CAAC,GAAW;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,gBAAgB,CAAC,GAAW,EAAE,KAAc;QAC1C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,gBAAgB,CAAC,GAAW;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,mBAAmB,CAAC,GAAW;QAC7B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/MaybePromise.d.ts

@@ -0,0 +1,2 @@
+export type MaybePromise<T> = T | Promise<T>;
+//# sourceMappingURL=MaybePromise.d.ts.map

package/dist/MaybePromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaybePromise.d.ts","sourceRoot":"","sources":["../src/MaybePromise.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/dist/MaybePromise.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=MaybePromise.js.map

package/dist/MaybePromise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaybePromise.js","sourceRoot":"","sources":["../src/MaybePromise.ts"],"names":[],"mappings":""}

package/dist/Process.d.ts

@@ -0,0 +1,15 @@
+import type { ProcessInterface } from "./interfaces/ProcessInterface.js";
+import type { StateInterface } from "./interfaces/StateInterface.js";
+export declare class Process implements ProcessInterface {
+    private readonly name;
+    private readonly initialState;
+    private readonly states;
+    constructor(name: string, initialState: StateInterface);
+    private registerState;
+    getName(): string;
+    getInitialState(): StateInterface;
+    getStates(): Iterable<StateInterface>;
+    getState(name: string): StateInterface;
+    hasState(name: string): boolean;
+}
+//# sourceMappingURL=Process.d.ts.map

package/dist/Process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Process.d.ts","sourceRoot":"","sources":["../src/Process.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAKrE,qBAAa,OAAQ,YAAW,gBAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc;IAOtD,OAAO,CAAC,aAAa;IAerB,OAAO,IAAI,MAAM;IAIjB,eAAe,IAAI,cAAc;IAIjC,SAAS,IAAI,QAAQ,CAAC,cAAc,CAAC;IAIrC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAItC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGhC"}

package/dist/Process.js

@@ -0,0 +1,43 @@
+import { StateCollection } from "./StateCollection.js";
+import { DuplicateStateError } from "./error/DuplicateStateError.js";
+export class Process {
+    name;
+    initialState;
+    states;
+    constructor(name, initialState) {
+        this.name = name;
+        this.initialState = initialState;
+        this.states = new StateCollection();
+        this.registerState(initialState);
+    }
+    registerState(state) {
+        const name = state.getName();
+        if (this.states.hasState(name)) {
+            if (this.states.getState(name) !== state) {
+                throw new DuplicateStateError(name);
+            }
+            return;
+        }
+        this.states.addState(state);
+        for (const transition of state.getTransitions()) {
+            const targetState = transition.getTargetState();
+            this.registerState(targetState);
+        }
+    }
+    getName() {
+        return this.name;
+    }
+    getInitialState() {
+        return this.initialState;
+    }
+    getStates() {
+        return this.states.getStates();
+    }
+    getState(name) {
+        return this.states.getState(name);
+    }
+    hasState(name) {
+        return this.states.hasState(name);
+    }
+}
+//# sourceMappingURL=Process.js.map

package/dist/Process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Process.js","sourceRoot":"","sources":["../src/Process.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE,MAAM,OAAO,OAAO;IACD,IAAI,CAAS;IACb,YAAY,CAAiB;IAC7B,MAAM,CAAkB;IAEzC,YAAY,IAAY,EAAE,YAA4B;QACpD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IACnC,CAAC;IAEO,aAAa,CAAC,KAAqB;QACzC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;gBACzC,MAAM,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5B,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;YAChD,MAAM,WAAW,GAAI,UAAkC,CAAC,cAAc,EAAE,CAAC;YACzE,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;IACjC,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/State.d.ts

@@ -0,0 +1,22 @@
+import type { StateInterface } from "./interfaces/StateInterface.js";
+import type { TransitionInterface } from "./interfaces/TransitionInterface.js";
+import type { EventInterface } from "./interfaces/EventInterface.js";
+export declare class State implements StateInterface {
+    private readonly name;
+    private readonly transitions;
+    private readonly events;
+    private readonly metadata;
+    constructor(name: string);
+    getName(): string;
+    getTransitions(): Iterable<TransitionInterface>;
+    addTransition(transition: TransitionInterface): void;
+    getEventNames(): string[];
+    hasEvent(name: string): boolean;
+    getEvent(name: string): EventInterface;
+    getMetadata(): Record<string, unknown>;
+    getMetadataValue(key: string): unknown;
+    setMetadataValue(key: string, value: unknown): void;
+    hasMetadataValue(key: string): boolean;
+    deleteMetadataValue(key: string): void;
+}
+//# sourceMappingURL=State.d.ts.map

package/dist/State.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.d.ts","sourceRoot":"","sources":["../src/State.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE,qBAAa,KAAM,YAAW,cAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAuC;IACnE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;gBAEhD,IAAI,EAAE,MAAM;IAIxB,OAAO,IAAI,MAAM;IAIjB,cAAc,IAAI,QAAQ,CAAC,mBAAmB,CAAC;IAI/C,aAAa,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI;IAsBpD,aAAa,IAAI,MAAM,EAAE;IAIzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAStC,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAItC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAItC,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAInD,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAItC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAGvC"}

package/dist/State.js

@@ -0,0 +1,65 @@
+import { Event } from "./Event.js";
+export class State {
+    name;
+    transitions = new Set();
+    events = new Map();
+    metadata = new Map();
+    constructor(name) {
+        this.name = name;
+    }
+    getName() {
+        return this.name;
+    }
+    getTransitions() {
+        return this.transitions;
+    }
+    addTransition(transition) {
+        if (this.transitions.has(transition)) {
+            return;
+        }
+        const targetName = transition.getTargetState().getName();
+        const eventName = transition.getEventName();
+        const conditionName = transition.getConditionName();
+        for (const existing of this.transitions) {
+            if (existing.getTargetState().getName() === targetName &&
+                existing.getEventName() === eventName &&
+                existing.getConditionName() === conditionName) {
+                return;
+            }
+        }
+        this.transitions.add(transition);
+        if (eventName) {
+            this.getEvent(eventName);
+        }
+    }
+    getEventNames() {
+        return Array.from(this.events.keys());
+    }
+    hasEvent(name) {
+        return this.events.has(name);
+    }
+    getEvent(name) {
+        let event = this.events.get(name);
+        if (!event) {
+            event = new Event(name);
+            this.events.set(name, event);
+        }
+        return event;
+    }
+    getMetadata() {
+        return Object.fromEntries(this.metadata);
+    }
+    getMetadataValue(key) {
+        return this.metadata.get(key);
+    }
+    setMetadataValue(key, value) {
+        this.metadata.set(key, value);
+    }
+    hasMetadataValue(key) {
+        return this.metadata.has(key);
+    }
+    deleteMetadataValue(key) {
+        this.metadata.delete(key);
+    }
+}
+//# sourceMappingURL=State.js.map

package/dist/State.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"State.js","sourceRoot":"","sources":["../src/State.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,OAAO,KAAK;IACC,IAAI,CAAS;IACb,WAAW,GAA6B,IAAI,GAAG,EAAE,CAAC;IAClD,MAAM,GAAgC,IAAI,GAAG,EAAE,CAAC;IAChD,QAAQ,GAAyB,IAAI,GAAG,EAAE,CAAC;IAE5D,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,aAAa,CAAC,UAA+B;QAC3C,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YACrC,OAAO;QACT,CAAC;QACD,MAAM,UAAU,GAAG,UAAU,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,CAAC;QACzD,MAAM,SAAS,GAAG,UAAU,CAAC,YAAY,EAAE,CAAC;QAC5C,MAAM,aAAa,GAAG,UAAU,CAAC,gBAAgB,EAAE,CAAC;QACpD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACxC,IACE,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,KAAK,UAAU;gBAClD,QAAQ,CAAC,YAAY,EAAE,KAAK,SAAS;gBACrC,QAAQ,CAAC,gBAAgB,EAAE,KAAK,aAAa,EAC7C,CAAC;gBACD,OAAO;YACT,CAAC;QACH,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACjC,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,aAAa;QACX,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC;YACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,WAAW;QACT,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,gBAAgB,CAAC,GAAW;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,gBAAgB,CAAC,GAAW,EAAE,KAAc;QAC1C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,gBAAgB,CAAC,GAAW;QAC1B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,mBAAmB,CAAC,GAAW;QAC7B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/StateCollection.d.ts

@@ -0,0 +1,14 @@
+import type { StateCollectionInterface } from "./interfaces/StateCollectionInterface.js";
+import type { StateInterface } from "./interfaces/StateInterface.js";
+import { StateCollectionMerger } from "./util/StateCollectionMerger.js";
+export declare class StateCollection implements StateCollectionInterface {
+    private readonly states;
+    private stateCollectionMerger;
+    getState(name: string): StateInterface;
+    getStates(): Iterable<StateInterface>;
+    hasState(name: string): boolean;
+    addState(state: StateInterface): void;
+    getStateCollectionMerger(): StateCollectionMerger;
+    merge(source: StateCollectionInterface): void;
+}
+//# sourceMappingURL=StateCollection.d.ts.map

package/dist/StateCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateCollection.d.ts","sourceRoot":"","sources":["../src/StateCollection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAGxE,qBAAa,eAAgB,YAAW,wBAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IACjE,OAAO,CAAC,qBAAqB,CAAsC;IAEnE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;IAQtC,SAAS,IAAI,QAAQ,CAAC,cAAc,CAAC;IAIrC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAQrC,wBAAwB,IAAI,qBAAqB;IAOjD,KAAK,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI;CAI9C"}

package/dist/StateCollection.js

@@ -0,0 +1,37 @@
+import { StateCollectionMerger } from "./util/StateCollectionMerger.js";
+import { DuplicateStateError } from "./error/DuplicateStateError.js";
+export class StateCollection {
+    states = new Map();
+    stateCollectionMerger = null;
+    getState(name) {
+        const state = this.states.get(name);
+        if (!state) {
+            throw new Error(`State "${name}" not found`);
+        }
+        return state;
+    }
+    getStates() {
+        return this.states.values();
+    }
+    hasState(name) {
+        return this.states.has(name);
+    }
+    addState(state) {
+        const existing = this.states.get(state.getName());
+        if (existing && existing !== state) {
+            throw new DuplicateStateError(state.getName());
+        }
+        this.states.set(state.getName(), state);
+    }
+    getStateCollectionMerger() {
+        if (!this.stateCollectionMerger) {
+            this.stateCollectionMerger = new StateCollectionMerger(this);
+        }
+        return this.stateCollectionMerger;
+    }
+    merge(source) {
+        const merger = this.getStateCollectionMerger();
+        merger.merge(source);
+    }
+}
+//# sourceMappingURL=StateCollection.js.map

package/dist/StateCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateCollection.js","sourceRoot":"","sources":["../src/StateCollection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErE,MAAM,OAAO,eAAe;IACT,MAAM,GAAgC,IAAI,GAAG,EAAE,CAAC;IACzD,qBAAqB,GAAiC,IAAI,CAAC;IAEnE,QAAQ,CAAC,IAAY;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,aAAa,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,QAAQ,CAAC,KAAqB;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,IAAI,QAAQ,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YACnC,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,wBAAwB;QACtB,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE,CAAC;YAChC,IAAI,CAAC,qBAAqB,GAAG,IAAI,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,IAAI,CAAC,qBAAqB,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,MAAgC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,wBAAwB,EAAE,CAAC;QAC/C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;CACF"}

package/dist/Statemachine.d.ts

@@ -0,0 +1,45 @@
+import type { StatemachineInterface } from "./interfaces/StatemachineInterface.js";
+import type { StateInterface } from "./interfaces/StateInterface.js";
+import type { ProcessInterface } from "./interfaces/ProcessInterface.js";
+import type { TransitionInterface } from "./interfaces/TransitionInterface.js";
+import type { MutexInterface } from "./interfaces/MutexInterface.js";
+import type { TransitionSelectorInterface } from "./interfaces/TransitionSelectorInterface.js";
+import type { DispatcherInterface } from "./interfaces/DispatcherInterface.js";
+import type { Observer } from "./interfaces/Observer.js";
+export declare class Statemachine implements StatemachineInterface {
+    private readonly subject;
+    private currentState;
+    private lastState;
+    private readonly transitionSelector;
+    private selectedTransition;
+    private readonly process;
+    private readonly mutex;
+    private autoreleaseLock;
+    private dispatcher;
+    private currentEvent;
+    private currentContext;
+    private readonly observers;
+    constructor(subject: unknown, process: ProcessInterface, stateName?: string | null, transitionSelector?: TransitionSelectorInterface | null, mutex?: MutexInterface | null);
+    getProcess(): ProcessInterface;
+    getCurrentState(): StateInterface;
+    getLastState(): StateInterface | null;
+    getSubject(): unknown;
+    getSelectedTransition(): TransitionInterface | null;
+    getCurrentContext(): Map<string, unknown> | null;
+    private doCheckTransitions;
+    private onDispatcherReady;
+    dispatchEvent(dispatcher: DispatcherInterface, name: string, context?: Map<string, unknown>): Promise<void>;
+    triggerEvent(name: string, context?: Map<string, unknown>): Promise<void>;
+    checkTransitions(context?: Map<string, unknown>): Promise<void>;
+    private acquireLockOrThrowException;
+    isAutoreleaseLock(): boolean;
+    setAutoreleaseLock(autorelease: boolean): void;
+    acquireLock(): Promise<boolean>;
+    releaseLock(): Promise<void>;
+    isLockAcquired(): boolean;
+    attach(observer: Observer): void;
+    detach(observer: Observer): void;
+    notify(): Promise<void>;
+    getObservers(): Iterable<Observer>;
+}
+//# sourceMappingURL=Statemachine.d.ts.map

package/dist/Statemachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Statemachine.d.ts","sourceRoot":"","sources":["../src/Statemachine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAE/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,6CAA6C,CAAC;AAC/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AASzD,qBAAa,YAAa,YAAW,qBAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA8B;IACjE,OAAO,CAAC,kBAAkB,CAAoC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,eAAe,CAAQ;IAC/B,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;gBAGpD,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,gBAAgB,EACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,EACzB,kBAAkB,CAAC,EAAE,2BAA2B,GAAG,IAAI,EACvD,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI;IAc/B,UAAU,IAAI,gBAAgB;IAI9B,eAAe,IAAI,cAAc;IAIjC,YAAY,IAAI,cAAc,GAAG,IAAI;IAIrC,UAAU,IAAI,OAAO;IAIrB,qBAAqB,IAAI,mBAAmB,GAAG,IAAI;IAInD,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;YAIlC,kBAAkB;YAyDlB,iBAAiB;IAiBzB,aAAa,CACjB,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IA6BV,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC;IAeV,gBAAgB,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;YAYvD,2BAA2B;IAMzC,iBAAiB,IAAI,OAAO;IAI5B,kBAAkB,CAAC,WAAW,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAO/B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC,cAAc,IAAI,OAAO;IAIzB,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAIhC,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAI1B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B,YAAY,IAAI,QAAQ,CAAC,QAAQ,CAAC;CAGnC"}