@alwatr/fsm 4.1.1 → 6.0.0

package/CHANGELOG.md

@@ -3,6 +3,115 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [6.0.0](https://github.com/Alwatr/flux/compare/v5.2.2...v6.0.0) (2025-09-19)
+
+### ⚠ BREAKING CHANGES
+
+* Complete rewrite of @alwatr/fsm package
+
+Summary:
+- The package has been fully rewritten: public API, types, internal behavior and lifecycle semantics have changed.
+- Consumers must update imports and usage. Existing code written for the old API will not work without changes.
+
+Example:
+```ts
+import {createFsmService} from '@alwatr/fsm';
+const service = createFsmService({
+  name: 'light-switch',
+  initial: 'off',
+  context: {brightness: 0},
+  states: {
+    off: {
+      on: { TOGGLE: { target: 'on', actions: [() => ({brightness: 100})] } },
+    },
+    on: {
+      on: {
+        TOGGLE: { target: 'off', actions: [() => ({brightness: 0})] },
+        SET_BRIGHTNESS: { actions: [(e) => ({brightness: e.level})] },
+      },
+    },
+  },
+});
+
+const sub = service.stateSignal.subscribe((state) => {
+  console.log(\`Light is \${state.name} brightness=\${state.context.brightness}\`);
+});
+
+service.eventSignal.dispatch({type: 'TOGGLE'});
+// When done:
+sub.unsubscribe?.();
+service.destroy();
+```
+
+### ✨ Features
+
+* add factory function for creating StateMachine instances ([d5afa79](https://github.com/Alwatr/flux/commit/d5afa79f323f4a20b9d9917861774dba3c18ba91))
+* add type definitions for state machine events, states, and transitions ([cd5d770](https://github.com/Alwatr/flux/commit/cd5d770d2c5ca0ab462e27d2ac6a119e6816d82e))
+* implement FsmService for managing finite state machines with event and state signals ([4fbc72a](https://github.com/Alwatr/flux/commit/4fbc72addbc4dc29b3deb1bb5c07e3fa5ad6e2e1))
+* implement StateMachine class with state management and transition logic ([eca4208](https://github.com/Alwatr/flux/commit/eca4208c82932b736f284c7f28df79820c24986a))
+* rewrite new state machine interfaces and types ([31885e5](https://github.com/Alwatr/flux/commit/31885e59dd5542ecffad971704cc20ae26ccca90))
+
+### 🐛 Bug Fixes
+
+* add documentation for eventSignal in FsmService class ([a11cb4a](https://github.com/Alwatr/flux/commit/a11cb4a8c005356832fab3a9924d4f75cc9cc8af))
+* add logging to destroy method for better tracking of service cleanup ([6187d17](https://github.com/Alwatr/flux/commit/6187d17bb4765bae89b271f3dc6920cb69818fa6))
+* allow void return type for Assigner function ([5e1ae6b](https://github.com/Alwatr/flux/commit/5e1ae6b4cd7e472f2928a7ad25c81d2b9d40e8b7))
+* correct entry action execution to use target state context for improved accuracy ([cf16271](https://github.com/Alwatr/flux/commit/cf16271969f020fa502f1178459d44a9c8e74677))
+* correct logger method names in processTransition and applyAssigners for consistency ([f33d553](https://github.com/Alwatr/flux/commit/f33d5533f9b296483f807779e3cb522d4313a876))
+* correct stateSignal naming and improve documentation in FsmService class ([7d5b7fe](https://github.com/Alwatr/flux/commit/7d5b7feef54fbbd76fead7a2fa1a964d77ec0401))
+* enhance applyAssigners logic for atomic updates and improved error handling ([988e00c](https://github.com/Alwatr/flux/commit/988e00cfe4be5974966d52235d2bf3a8f08e1d59))
+* enhance applyAssigners logic to improve context updates and error handling ([73384c0](https://github.com/Alwatr/flux/commit/73384c04479c7398cea0504c0ea8a14b57b7a366))
+* enhance executeEffects logic to improve error handling and logging ([8fe6bed](https://github.com/Alwatr/flux/commit/8fe6beda209ee75ab81bf2249fe1d0b25185a1cd))
+* enhance FSM transition handling and logging for improved clarity and performance ([8695d99](https://github.com/Alwatr/flux/commit/8695d99910b5a1e0abc8603a5ea947d6f77d463b))
+* enhance transition condition logging for better debugging and clarity ([e7cd799](https://github.com/Alwatr/flux/commit/e7cd79964ecfab3c8e9a9ff1d0b74eb4d2f09cbf))
+* ensure proper cleanup of stateSignal in destroy method ([d90a0cf](https://github.com/Alwatr/flux/commit/d90a0cf3ae871f0db1832bdc92a61cb7b0567a65))
+* ensure proper destruction of state signals in destroy method ([512221b](https://github.com/Alwatr/flux/commit/512221bc7a62b77392eb368b97e323bfd95a02fb))
+* execute exit/entry effects only when state changes in FSM ([99a1d66](https://github.com/Alwatr/flux/commit/99a1d6653be5350867d7050cf59d18dd43966cb0))
+* executeEffects__ context ([f1fde9b](https://github.com/Alwatr/flux/commit/f1fde9baccebd27ca76ae785643d60cd463aff97))
+* fsm-service.ts run cond ([5c91967](https://github.com/Alwatr/flux/commit/5c91967b605e5529a8d3e9deb630808966d4f3aa))
+* fsm-service.ts type ([239ea9b](https://github.com/Alwatr/flux/commit/239ea9b77b2cc3c41d14df426315381ce65f156d))
+* improve context handling in applyAssigners__ method ([d3ac560](https://github.com/Alwatr/flux/commit/d3ac56007e18d744fea289d21f5f3518d8726794))
+* improve processTransition logic and enhance logging in FsmService class ([434e6e1](https://github.com/Alwatr/flux/commit/434e6e10b9ee764830898d9c762afba2c893b9d9))
+* move powerLostWarning action to flashingRed state entry ([441223d](https://github.com/Alwatr/flux/commit/441223d30d571b5fd244d7f50a1428c74fef39f0))
+* refactor findTransition logic to improve condition evaluation and logging ([0a32c8d](https://github.com/Alwatr/flux/commit/0a32c8de6974f587404de6d39b8dd10ca20f0d0f))
+* remove space in logger initialization for FsmService class ([d91065a](https://github.com/Alwatr/flux/commit/d91065aa08339f9a3075304e9b061672118f9525))
+* rename transition.actions to transition.assigners for clarity ([1198b59](https://github.com/Alwatr/flux/commit/1198b597c5b326a4a8deb84c1503648a62d28a1c))
+* reorder assigners property documentation for improved clarity ([019a9f0](https://github.com/Alwatr/flux/commit/019a9f0c56876f82e2dcb9c02aaa01ab8a6b2234))
+* replace computed state signal with read-only state signal for improved performance ([76fac47](https://github.com/Alwatr/flux/commit/76fac47612a1e5566dcfd246b16823f93078c908))
+* simplify assigner function in light machine config ([a479b5d](https://github.com/Alwatr/flux/commit/a479b5d6fb511409a1b66734b262fc5371d83d79))
+* standardize light state logging messages for clarity ([a1a464a](https://github.com/Alwatr/flux/commit/a1a464a1588459de1a4e26c6bd933a00fb031b75))
+* update Assigner and Effect types to support SingleOrArray for improved flexibility ([8e6e7ad](https://github.com/Alwatr/flux/commit/8e6e7ad10bfde1170904f3b2820810230af80241))
+* update Assigner type definition to allow void return and change Transition type to array ([f43c993](https://github.com/Alwatr/flux/commit/f43c99369c993c5e252bdb6e47b177d46e86e18f))
+* update entry actions to assigners for consistency in light machine configuration ([66f76c7](https://github.com/Alwatr/flux/commit/66f76c7627af9b096db4a2c4ab16fcbb79b81321))
+* update package description for clarity and accuracy ([86c29fb](https://github.com/Alwatr/flux/commit/86c29fb38eeed2fe71f9b04f28a00231a1074d1f))
+* update type definitions for MachineState, Assigner, Effect, and Transition interfaces ([79760f4](https://github.com/Alwatr/flux/commit/79760f4bf4df48685cb60af5fd20c9496130161c))
+
+### 🔨 Code Refactoring
+
+* enhance action and guard types for state transitions ([1fdfa1b](https://github.com/Alwatr/flux/commit/1fdfa1bb3e847b9e4d1051320a23701d29d243ca))
+* migrate light switch implementation to JavaScript and enhance logging ([2f81bc0](https://github.com/Alwatr/flux/commit/2f81bc03b7ceda739e2204021ce40e0389f52e2a))
+* migrate to createFsmService and enhance state management logging ([5209c4b](https://github.com/Alwatr/flux/commit/5209c4b0dfb6e5737c386a344f7bdbbca3c4c2dd))
+* remove obsolete files and clean up state machine implementation ([921cb24](https://github.com/Alwatr/flux/commit/921cb24f363a635ad8e91523e49500780ffcbb9a))
+* remove unused import and clean up exports in fsm module ([a6c6374](https://github.com/Alwatr/flux/commit/a6c63742ee5d3f7fc8042b51f0889978e0e709e6))
+* replace signalId with name in StateMachine signal creation ([0ce2654](https://github.com/Alwatr/flux/commit/0ce2654b10b7c6dd6f519a62428cdfcac8fa3189))
+* restructure state machine types for improved clarity and functionality ([7b21778](https://github.com/Alwatr/flux/commit/7b21778db22a3fcf5a855790708ee7576d257682))
+* standardize signal naming and visibility in FsmService ([ddfae0f](https://github.com/Alwatr/flux/commit/ddfae0f62fa5355054cf43ca88a0e00f65dc0bb4))
+* update createStateMachine to createFsmService with improved documentation and example ([cc73194](https://github.com/Alwatr/flux/commit/cc73194ec01ab570054e2dba877d8b6c2cd336c2))
+* update exports in main.ts to include facade, state-machine, and types ([0796b4f](https://github.com/Alwatr/flux/commit/0796b4fd3281e42614eec8a79389e242592df5a4))
+* update exports in main.ts to include fsm-service and type-old ([ddcf0be](https://github.com/Alwatr/flux/commit/ddcf0bef31958a93f0433f587184b88e75f2819f))
+* update log message for new event from enter effect in processTransition method ([314e516](https://github.com/Alwatr/flux/commit/314e516745ffaaae0495fe96aea6bcd06d7e49d9))
+* update type definitions and improve state machine configuration ([5d749ca](https://github.com/Alwatr/flux/commit/5d749ca5a4cec6065e91e87f203e0ea05392f6fb))
+
+### 🧹 Miscellaneous Chores
+
+* rollback old fsm ([b2e7f32](https://github.com/Alwatr/flux/commit/b2e7f323841443e30772874eeab52481025a4b1e))
+
+### 🔗 Dependencies update
+
+* update @alwatr/logger to version 6.0.2 and @types/node to version 22.18.6; upgrade esbuild and other dependencies ([95dfaba](https://github.com/Alwatr/flux/commit/95dfabab2a4d4ea2b0e42a70bee1f3e68a67bffc))
+* update dependencies for logger, nano-build, type-helper, and node types ([23fe723](https://github.com/Alwatr/flux/commit/23fe7236ffa0bfd2551a6dfc52c23689ce4b036e))
+* update package dependencies for improved compatibility and performance ([1e91063](https://github.com/Alwatr/flux/commit/1e9106343d01330089c33d9591969a66625a1e7b))
+
 ## [4.1.1](https://github.com/Alwatr/flux/compare/v4.1.0...v4.1.1) (2025-09-08)
 
 ### 🔗 Dependencies update

package/README.md

@@ -1,96 +1,307 @@
-# Flux: Finite State Machine
+# Alwatr FSM
 
-A robust TypeScript library for implementing Flux (Finite) State Machines, enabling clear and organized management of application state and transitions.
+[](https://www.google.com/search?q=https://www.npmjs.com/package/%40alwatr/fsm)
+[](https://www.google.com/search?q=https://bundlephobia.com/package/%40alwatr/fsm)
 
-## Features
+A tiny, type-safe, declarative, and reactive finite state machine (FSM) library for modern TypeScript applications, built on top of [Alwatr Signals](https://www.google.com/search?q=https://github.com/Alwatr/alwatr/tree/main/packages/signal).
 
-* **Clear State Management:**  Model your application's behavior with well-defined states and transitions.
-* **TypeScript Support:** Written in TypeScript with full type definitions for improved code quality and developer experience.
-* **Flexible Actions:**  Attach custom actions to state transitions and events.
-* **Observable Integration:**  Built-in integration with `@alwatr/observable` for reactive state updates.
-* **Built-in Logging:**  Integrated logging for debugging and monitoring state machine behavior.
+یک کتابخانه کوچک، تایپ-سیف، اعلانی و واکنش‌گرا (reactive) برای مدیریت وضعیت به روش ماشین حالت متناهی (FSM) در اپلیکیشن‌های مدرن TypeScript که بر پایه [Alwatr Signals](https://www.google.com/search?q=https://github.com/Alwatr/alwatr/tree/main/packages/signal) ساخته شده است.
+
+[](https://www.google.com/search?q=https://www.npmjs.com/package/%40alwatr/fsm)
+[](https://www.google.com/search?q=https://www.npmjs.com/package/%40alwatr/flux)
+[](https://www.google.com/search?q=alwatr+fsm)
+[](https://www.google.com/search?q=alwatr+flux)
+[](https://www.google.com/search?q=alwatr)
+
+## Philosophy
+
+Managing state in complex applications can be challenging. As features grow, state transitions can become unpredictable, leading to bugs and difficult-to-maintain code. Finite State Machines provide a powerful model to solve this problem by formalizing application logic.
+
+An FSM describes a system that can be in **exactly one** of a finite number of **states** at any given time. It transitions from one state to another in response to **events**, following predefined rules. This approach makes state changes predictable, visualizable, and robust.
+
+This library is designed to be:
+
+- **Declarative**: Define your entire machine logic in a single, easy-to-read configuration object.
+- **Type-Safe**: Leverage TypeScript to catch errors at compile time, not runtime.
+- **Reactive**: Built around signals for seamless integration with modern UI frameworks and reactive codebases.
+- **Resilient**: Guarantees Run-to-Completion (RTC) and handles errors in user-defined functions gracefully without crashing.
+
+---
+
+## مفاهیم و فلسفه
+
+مدیریت وضعیت در اپلیکیشن‌های پیچیده یک چالش است. با رشد برنامه، جریان تغییر وضعیت‌ها می‌تواند غیرقابل‌پیش‌بینی شده و منجر به باگ‌ها و کدهای غیرقابل نگهداری شود. ماشین‌های حالت متناهی (FSM) یک مدل قدرتمند برای حل این مشکل از طریق ساختارمند کردن منطق برنامه ارائه می‌دهند.
+
+یک FSM سیستمی را توصیف می‌کند که در هر لحظه **دقیقا در یکی** از تعداد محدودی **وضعیت (state)** قرار دارد. این سیستم در پاسخ به **رویدادها (events)** و بر اساس قوانین از پیش تعریف‌شده، از یک وضعیت به وضعیت دیگر **گذار (transition)** می‌کند. این رویکرد، تغییرات وضعیت را قابل‌پیش‌بینی، قابل ترسیم و مستحکم می‌سازد.
+
+این کتابخانه با اهداف زیر طراحی شده است:
+
+- **اعلانی (Declarative)**: تمام منطق ماشین خود را در یک آبجکت پیکربندی واحد و خوانا تعریف کنید.
+- **تایپ-سیف (Type-Safe)**: با بهره‌گیری از قدرت TypeScript، خطاها را در زمان کامپایل پیدا کنید، نه در زمان اجرا.
+- **واکنش‌گرا (Reactive)**: مبتنی بر سیگنال‌ها برای یکپارچه‌سازی آسان با فریم‌ورک‌های مدرن و کدهای واکنش‌گرا.
+- **مستحکم و تاب‌آور (Resilient)**: مدل اجرای کامل تا انتها (RTC) را تضمین کرده و خطاهای توابع تعریف‌شده توسط کاربر را بدون متوقف کردن سیستم مدیریت می‌کند.
 
 ## Installation
 
 ```bash
-npm install @alwatr/fsm
+npm i @alwatr/fsm
+```
+
+## Core Concepts / مفاهیم کلیدی
+
+| Term           | Description                                                                                                         |
+| :------------- | :------------------------------------------------------------------------------------------------------------------ |
+| **State**      | The current finite state of the machine (e.g., `'idle'`, `'loading'`).                                              |
+| **Context**    | An object holding the "extended state"—any quantitative or non-finite data (e.g., `{retries: 2, data: null}`).      |
+| **Event**      | An object that triggers a potential state transition (e.g., `{type: 'FETCH', id: '123'}`).                          |
+| **Transition** | A rule defining the path from a source state to a target state for a given event. It can be guarded by a condition. |
+| **Assigner**   | A **pure function** that synchronously updates the `context` during a transition.                                   |
+| **Effect**     | A function for **side effects** (e.g., API calls, logging) that runs upon entering or exiting a state.              |
+| **Condition**  | A **predicate function** that must return `true` for its associated transition to be taken.                         |
+
+| اصطلاح                     | توضیحات                                                                                                                        |
+| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
+| **وضعیت (State)**          | وضعیت متناهی فعلی ماشین (مثلاً `'idle'`, `'loading'`).                                                                         |
+| **زمینه (Context)**        | یک آبجکت برای نگهداری "وضعیت گسترده"—هرگونه داده کمی یا نامتناهی (مثلاً `{retries: 2, data: null}`).                           |
+| **رویداد (Event)**         | آبجکتی که یک گذار وضعیت بالقوه را آغاز می‌کند (مثلاً `{type: 'FETCH', id: '123'}`).                                            |
+| **گذار (Transition)**      | قانونی که مسیر از یک وضعیت مبدأ به یک وضعیت مقصد را برای یک رویداد خاص تعریف می‌کند. این گذار می‌تواند توسط یک شرط محافظت شود. |
+| **تخصیص‌دهنده (Assigner)** | یک **تابع خالص** که به صورت همزمان (synchronously) `context` را در طول یک گذار به‌روزرسانی می‌کند.                             |
+| **اثر جانبی (Effect)**     | تابعی برای **عملیات‌های جانبی** (مانند فراخوانی API یا لاگ کردن) که هنگام ورود یا خروج از یک وضعیت اجرا می‌شود.                |
+| **شرط (Condition)**        | یک **تابع گزاره‌ای** که باید `true` برگرداند تا گذار مرتبط با آن انجام شود.                                                    |
+
+## Example 1: A Simple Light Switch
+
+Let's model a simple light switch that can be turned on and off.
+
+### ۱. تعریف انواع
+
+First, define the types for the states, events, and context.
+ابتدا انواع مربوط به وضعیت‌ها، رویدادها و زمینه را تعریف می‌کنیم.
+
+```ts
+import type {StateMachineConfig} from '@alwatr/fsm';
+
+// The context stores the brightness level.
+type LightContext = {brightness: number};
+
+// The machine can only be in one of these two states.
+type LightState = 'on' | 'off';
+
+// Define the events that can be sent to the machine.
+type LightEvent = {type: 'TOGGLE'} | {type: 'SET_BRIGHTNESS'; level: number};
 ```
 
-## Usage
+### ۲. پیکربندی ماشین
 
-```typescript
-import {FluxStateMachineBase} from '@alwatr/fsm';
+Define the entire machine logic in a configuration object.
+کل منطق ماشین را در یک آبجکت پیکربندی تعریف می‌کنیم.
 
-// Define your states and events
-type MyState = 'idle' | 'loading' | 'success' | 'error';
-type MyEvent = 'fetch' | 'success' | 'error';
+```ts
+const lightMachineConfig: StateMachineConfig<LightState, LightEvent, LightContext> = {
+  name: 'light-switch',
+  initial: 'off',
+  context: {brightness: 0},
+  states: {
+    off: {
+      on: {
+        // When in the 'off' state and a 'TOGGLE' event occurs...
+        TOGGLE: {
+          target: 'on', // ...transition to the 'on' state.
+          assigners: [() => ({brightness: 100})], // ...and set brightness to 100.
+        },
+      },
+    },
+    on: {
+      on: {
+        // When in the 'on' state and a 'TOGGLE' event occurs...
+        TOGGLE: {
+          target: 'off', // ...transition to 'off'.
+          assigners: [() => ({brightness: 0})], // ...and reset brightness.
+        },
+        // An internal transition that only updates context without changing the state.
+        SET_BRIGHTNESS: {
+          // No 'target' means it's an internal transition.
+          assigners: [(event) => ({brightness: event.level})],
+        },
+      },
+    },
+  },
+};
+```
+
+### ۳. ساخت و استفاده از سرویس
+
+Create the service and interact with it using signals.
+سرویس را ایجاد کرده و با استفاده از سیگنال‌ها با آن تعامل می‌کنیم.
+
+```ts
+import {createFsmService} from '@alwatr/fsm';
+
+// Create the FSM service instance.
+const lightService = createFsmService(lightMachineConfig);
+
+// Subscribe to state changes.
+lightService.stateSignal.subscribe((state) => {
+  console.log(`Light is ${state.name} with brightness ${state.context.brightness}`);
+});
+
+// Dispatch events to trigger transitions.
+lightService.eventSignal.dispatch({type: 'TOGGLE'});
+// Logs: Light is on with brightness 100
+
+lightService.eventSignal.dispatch({type: 'SET_BRIGHTNESS', level: 50});
+// Logs: Light is on with brightness 50
+
+lightService.eventSignal.dispatch({type: 'TOGGLE'});
+// Logs: Light is off with brightness 0
+```
 
-class MyStateMachine extends FluxStateMachineBase<MyState, MyEvent> {
-  constructor() {
-    super({
-      name: 'my-state-machine',
-      initialState: 'idle',
-    });
+## Example 2: Async Data Fetching
 
-    // Define state transitions
-    this.stateRecord_ = {
-      idle: {
-        fetch: 'loading',
+A more advanced example showing side effects (`effects`) and conditional transitions (`condition`).
+
+```ts
+import {createFsmService} from '@alwatr/fsm';
+import type {StateMachineConfig} from '@alwatr/fsm';
+
+// Types
+type User = {id: string; name: string};
+type FetchContext = {user: User | null; error: string | null};
+type FetchState = 'idle' | 'pending' | 'success' | 'error';
+type FetchEvent = {type: 'FETCH'; id: string} | {type: 'RESOLVE'; user: User} | {type: 'REJECT'; error: string} | {type: 'RETRY'};
+
+// FSM Configuration
+const fetchMachineConfig: StateMachineConfig<FetchState, FetchEvent, FetchContext> = {
+  name: 'fetch-user',
+  initial: 'idle',
+  context: {
+    user: null,
+    error: null,
+  },
+  states: {
+    idle: {
+      on: {
+        FETCH: {target: 'pending'},
       },
-      loading: {
-        success: 'success',
-        error: 'error',
+    },
+    pending: {
+      // On entering 'pending' state, execute the fetchUser effect.
+      entry: [
+        async (event, context) => {
+          if (event.type !== 'FETCH') return; // Type guard
+          try {
+            console.log(`Fetching user with id: ${event.id}...`);
+            const response = await fetch(`https://api.example.com/users/${event.id}`);
+            if (!response.ok) throw new Error('User not found');
+            const user = (await response.json()) as User;
+            // An effect can return a new event to be dispatched back to the machine.
+            return {type: 'RESOLVE', user};
+          } catch (err) {
+            // If an error occurs, dispatch a 'REJECT' event.
+            return {type: 'REJECT', error: (err as Error).message};
+          }
+        },
+      ],
+      on: {
+        RESOLVE: {
+          target: 'success',
+          assigners: [(event) => ({user: event.user})],
+        },
+        REJECT: {
+          target: 'error',
+          assigners: [(event) => ({error: event.error})],
+        },
       },
-      success: {}, // Terminal state
-      error: {},    // Terminal state
-    };
-
-    // Define actions (optional)
-    this.actionRecord_ = {
-      'on_fetch': this.handleFetch,
-      'on_success': this.handleSuccess,
-      'on_error': this.handleError,
-    };
-  }
-
-  // ... (Implement your action methods: handleFetch, handleSuccess, handleError)
-
-  // Trigger a state transition
-  fetchData() {
-    this.transition_('fetch'); 
-  }
-}
+    },
+    success: {
+      on: {
+        FETCH: {target: 'pending'}, // Allow re-fetching
+      },
+    },
+    error: {
+      on: {
+        RETRY: {
+          target: 'pending',
+          // A condition that must be met for the transition to occur.
+          condition: (event, context) => {
+            // This is just an example; you might have retry logic in the context.
+            console.log('Checking retry condition...');
+            return true;
+          },
+        },
+      },
+    },
+  },
+};
+
+// --- Usage ---
+const fetchService = createFsmService(fetchMachineConfig);
+
+fetchService.stateSignal.subscribe((state) => {
+  console.log('Current State:', state.name);
+  if (state.name === 'success') console.log('User:', state.context.user);
+  if (state.name === 'error') console.log('Error:', state.context.error);
+});
+
+fetchService.eventSignal.dispatch({type: 'FETCH', id: '1'});
 ```
 
-## API
+## Architectural Advantages / مزیت‌های معماری
+
+- **Predictable & Visualizable**: By constraining how and when state can change, your application logic becomes deterministic and easy to reason about. The declarative nature of the config allows for easy visualization of all possible states and transitions.
+  <br>
+  **قابل پیش‌بینی و ترسیم**: با محدود کردن زمان و چگونگی تغییر وضعیت، منطق برنامه شما قطعی و قابل درک می‌شود. ماهیت اعلانی پیکربندی، امکان ترسیم و مشاهده تمام وضعیت‌ها و گذارهای ممکن را فراهم می‌کند.
 
-### `FluxStateMachineBase<S extends string, E extends string>`
+- **Type-Safe by Design**: The library is built from the ground up with TypeScript. It ensures that event payloads are correctly typed for each transition and that assigners update the context with valid data, preventing a wide class of bugs at compile time.
+  <br>
+  **ذاتاً تایپ-سیف**: این کتابخانه از پایه با TypeScript ساخته شده است. این امر تضمین می‌کند که پارامترهای رویدادها در هر گذار به درستی تایپ‌دهی شده و `assigner`ها زمینه (`context`) را با داده‌های معتبر به‌روزرسانی می‌کنند، که از بروز دسته وسیعی از باگ‌ها در زمان کامپایل جلوگیری می‌کند.
 
-* **`constructor(config: {name: string; loggerPrefix?: string; initialState: S})`:**
-  * `config.name`: The name of the state machine (used for logging).
-  * `config.loggerPrefix`: Optional prefix for log messages.
-  * `config.initialState`: The initial state of the machine.
+- **Decouples Logic from UI**: The `FsmService` encapsulates your application's logic, keeping it completely independent of your UI framework. Your UI simply subscribes to the `stateSignal` and dispatches events to the `eventSignal`. This improves testability and makes it easy to refactor or even replace the UI layer.
+  <br>
+  **جداسازی منطق از UI**: سرویس FSM منطق برنامه شما را کپسوله کرده و آن را کاملاً مستقل از فریم‌ورک UI نگه می‌دارد. لایه UI شما تنها به `stateSignal` گوش می‌دهد و رویدادها را به `eventSignal` ارسال می‌کند. این رویکرد آزمون‌پذیری را بهبود بخشیده و بازنویسی یا حتی تعویض لایه UI را آسان می‌کند.
 
-* **`stateRecord_: StateRecord<S, E>`:**  Defines the states and their possible transitions based on events.
+- **Robust & Resilient**: The machine operates on a Run-to-Completion (RTC) model, ensuring that each event is fully processed before the next one begins, preventing race conditions. Furthermore, any errors thrown inside user-defined functions (`condition`, `assigner`, `effect`) are caught and logged, preventing the entire machine from crashing.
+    <br>
+    **مستحکم و انعطاف‌پذیر**: ماشین بر اساس مدل اجرای کامل تا انتها (RTC) عمل می‌کند، که تضمین می‌کند هر رویداد به طور کامل پردازش شده و سپس رویداد بعدی آغاز می‌شود. این از بروز race condition جلوگیری می‌کند. علاوه بر این، هرگونه خطای ایجاد شده در توابع تعریف‌شده توسط کاربر (`condition`, `assigner`, `effect`) مدیریت و لاگ می‌شود و از کرش کردن کل ماشین جلوگیری می‌کند.
 
-* **`actionRecord_: ActionRecord<S, E>`:**  Binds action names to class methods for execution during transitions.
+## API Reference / مرجع API
 
-* **`transition_(event: E)`:**  Triggers a state transition based on the provided event.
+### `createFsmService(config)`
 
-* **`shouldTransition_(_eventDetail: StateEventDetail<S, E>): MaybePromise<boolean>`:**  (Optional) Allows you to define custom conditions for transitions.
+The main factory function to create a new FSM service.
+تابع اصلی برای ساخت یک سرویس FSM جدید.
 
-* **`postTransition__(eventDetail: StateEventDetail<S, E>)`:**  Executes actions associated with state transitions and events.
+- **`config`**: `StateMachineConfig<TState, TEvent, TContext>`
+  - The declarative configuration object for the state machine.
+  - آبجکت پیکربندی اعلانی برای ماشین حالت.
+- **Returns**: `FsmService<TState, TEvent, TContext>`
+  - An instance of the FSM service with two main properties:
+    - `stateSignal`: A readable signal that emits the current `MachineState`.
+    - `eventSignal`: A signal to `dispatch` new events to the machine.
+  - یک نمونه از سرویس FSM با دو پراپرتی اصلی:
+    - `stateSignal`: یک سیگنال خواندنی که `MachineState` فعلی را منتشر می‌کند.
+    - `eventSignal`: سیگنالی برای ارسال (`dispatch`) رویدادهای جدید به ماشین.
 
-* **`execAction__(name: ActionName<S, E>, eventDetail: StateEventDetail<S, E>)`:**  Executes a specific action if defined in the `actionRecord_`.
+### Key Types / انواع کلیدی
 
-* **`resetToInitialState_()`:**  Resets the machine to its initial state without notifying subscribers.
+| Type                     | Description                                                                   |
+| :----------------------- | :---------------------------------------------------------------------------- |
+| **`MachineState<S, C>`** | Represents the complete state, containing `name: S` and `context: C`.         |
+| **`MachineEvent<T>`**    | The base interface for events. Must have a `type: T` property.                |
+| **`StateMachineConfig`** | The main configuration object defining `initial`, `context`, and `states`.    |
+| **`Transition`**         | Defines a transition with an optional `target`, `condition`, and `assigners`. |
+
+| نوع                      | توضیحات                                                                                                        |
+| :----------------------- | :------------------------------------------------------------------------------------------------------------- |
+| **`MachineState<S, C>`** | وضعیت کامل ماشین را نمایش می‌دهد که شامل `name: S` (نام وضعیت) و `context: C` (زمینه) است.                     |
+| **`MachineEvent<T>`**    | اینترفیس پایه برای رویدادها. باید یک پراپرتی `type: T` داشته باشد.                                             |
+| **`StateMachineConfig`** | آبجکت اصلی پیکربندی که `initial` (وضعیت اولیه)، `context` (زمینه اولیه) و `states` (وضعیت‌ها) را تعریف می‌کند. |
+| **`Transition`**         | یک گذار را با `target` (مقصد)، `condition` (شرط) و `assigners` (تخصیص‌دهنده‌ها)ی اختیاری تعریف می‌کند.         |
 
 ## Sponsors
 
 The following companies, organizations, and individuals support flux ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.
 
-
-### Contributing
+## Contributing
 
 Contributions are welcome! Please read our [contribution guidelines](https://github.com/Alwatr/.github/blob/next/CONTRIBUTING.md) before submitting a pull request.
-

package/dist/facade.d.ts

@@ -0,0 +1,64 @@
+import { FsmService } from './fsm-service.js';
+import type { MachineEvent, StateMachineConfig } from './type.js';
+/**
+ * A simple and clean factory function for creating an `FsmService` instance.
+ * This is the recommended way to instantiate a new state machine.
+ *
+ * @template TState - The union type of all possible states.
+ * @template TEvent - The union type of all possible events.
+ * @template TContext - The type of the machine's context.
+ *
+ * @param config - The machine's configuration object.
+ * @returns A new, ready-to-use instance of `FsmService`.
+ *
+ * @example
+ * ```ts
+ * import {createFsmService} from '@alwatr/fsm';
+ * import type {StateMachineConfig} from '@alwatr/fsm';
+ *
+ * // 1. Define types
+ * type LightContext = {brightness: number};
+ * type LightState = 'on' | 'off';
+ * type LightEvent = {type: 'TOGGLE'} | {type: 'SET_BRIGHTNESS'; level: number};
+ *
+ * // 2. Config the state machine
+ * const lightMachineConfig: StateMachineConfig<LightState, LightEvent, LightContext> = {
+ *   name: 'light-switch',
+ *   initial: 'off',
+ *   context: {brightness: 0},
+ *   states: {
+ *     off: {
+ *       on: {
+ *         TOGGLE: {
+ *           target: 'on',
+ *           assigners: [() => ({brightness: 100})],
+ *         },
+ *       },
+ *     },
+ *     on: {
+ *       on: {
+ *         TOGGLE: {target: 'off', assigners: [() => ({brightness: 0})]},
+ *         SET_BRIGHTNESS: {assigners: [(event) => ({brightness: event.level})]},
+ *       },
+ *     },
+ *   },
+ * };
+ *
+ * // 3. Create the service
+ * const lightService = createFsmService(lightMachineConfig);
+ *
+ * // 4. Use it in your application
+ * lightService.stateSignal.subscribe((state) => {
+ *   console.log(`Light is ${state.name} with brightness ${state.context.brightness}`);
+ * });
+ *
+ * lightService.eventSignal.dispatch({type: 'TOGGLE'}); // Light is on with brightness 100
+ *
+ * lightService.eventSignal.dispatch({type: 'SET_BRIGHTNESS', level: 50}); // Light is on with brightness 50
+ *
+ * // 5. Cleanup
+ * // lightService.destroy();
+ * ```
+ */
+export declare function createFsmService<TState extends string, TEvent extends MachineEvent, TContext extends Record<string, unknown>>(config: StateMachineConfig<TState, TEvent, TContext>): FsmService<TState, TEvent, TContext>;
+//# sourceMappingURL=facade.d.ts.map

package/dist/facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../src/facade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAE,kBAAkB,EAAC,MAAM,WAAW,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,SAAS,YAAY,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3H,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,GACnD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAEtC"}

package/dist/fsm-service.d.ts

@@ -0,0 +1,61 @@
+import type { StateMachineConfig, MachineState, MachineEvent } from './type.js';
+/**
+ * A generic, encapsulated service that creates, runs, and manages a finite state machine.
+ * It handles signal creation, logic connection, and lifecycle management, providing a clean,
+ * reactive API for interacting with the FSM.
+ *
+ * @template TState The union type of all possible state names.
+ * @template TEvent The union type of all possible events.
+ * @template TContext The type of the machine's context (extended state).
+ */
+export declare class FsmService<TState extends string, TEvent extends MachineEvent, TContext extends Record<string, unknown>> {
+    protected readonly config_: StateMachineConfig<TState, TEvent, TContext>;
+    protected readonly logger_: import("@alwatr/logger").AlwatrLogger;
+    /** The event signal for sending events to the FSM. */
+    readonly eventSignal: import("@alwatr/signal").EventSignal<TEvent>;
+    private readonly stateSignal__;
+    /** The public, read-only state signal. Subscribe to react to state changes. */
+    readonly stateSignal: import("@alwatr/signal").IReadonlySignal<MachineState<TState, TContext>>;
+    constructor(config_: StateMachineConfig<TState, TEvent, TContext>);
+    /**
+     * The core FSM logic that processes a single event and transitions the machine to a new state.
+     * This process is atomic and follows the Run-to-Completion (RTC) model.
+     *
+     * @param event The event to process.
+     */
+    private processTransition__;
+    /**
+     * Finds the first valid transition for the given event and context by evaluating conditions.
+     *
+     * @param event The triggering event.
+     * @param context The current machine context.
+     * @returns The first matching transition or `undefined` if none are found.
+     */
+    private findTransition__;
+    /**
+     * Sequentially executes a list of effects (side-effects).
+     * Errors are caught and logged without stopping the FSM.
+     *
+     * @param event The event that triggered these effects.
+     * @param context The context at the time of execution.
+     * @param effects A single effect or an array of effects.
+     */
+    private executeEffects__;
+    /**
+     * Applies all assigner functions to the context to produce a new, updated context.
+     * This process is atomic (all-or-nothing). If any assigner fails, the original
+     * context is returned, and all updates are discarded.
+     *
+     * @param event The event that triggered the transition.
+     * @param context The current context.
+     * @param assigners A single assigner or an array of assigners.
+     * @returns The new, updated context, or the original context if any assigner fails.
+     */
+    private applyAssigners__;
+    /**
+     * Destroys the service, cleaning up all internal signals and subscriptions
+     * to prevent memory leaks.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=fsm-service.d.ts.map

package/dist/fsm-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsm-service.d.ts","sourceRoot":"","sources":["../src/fsm-service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAA+B,MAAM,WAAW,CAAC;AAE5G;;;;;;;;GAQG;AACH,qBAAa,UAAU,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,SAAS,YAAY,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAmB/F,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;IAlB3F,SAAS,CAAC,QAAQ,CAAC,OAAO,wCAA4C;IAEtE,sDAAsD;IACtD,SAAgB,WAAW,+CAExB;IAEH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAM3B;IAEH,+EAA+E;IAC/E,SAAgB,WAAW,2EAAmC;gBAExB,OAAO,EAAE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;IAK3F;;;;;OAKG;YACW,mBAAmB;IAuCjC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAwCxB;;;;;;;OAOG;YACW,gBAAgB;IAqC9B;;;;;;;;;OASG;IACH,OAAO,CAAC,gBAAgB;IAkCxB;;;OAGG;IACI,OAAO,IAAI,IAAI;CAKvB"}