base docs

Author: Nilay Vishwakarma

docs/1.Home.md

@@ -0,0 +1,77 @@
+# What is SharpFsm?
+
+A flexible finite state machine (FSM) library for .NET written in C#, it is designed to create and manage Finite State Machines (FSMs) in a simple and efficient way. It allows developers to define states, transitions, and events, enabling the modeling of complex behaviors in a structured manner.
+
+# Features
+- **State Management**: Easily define and manage states in your FSM. Strongly-typed FSMs using enums for states
+- **Transition Handling**: Transition conditions and side effects.
+- **Serialization**: Serialization to/from JSON and YAML.
+- **Builder Pattern**: Builder pattern for easy FSM construction.
+- **Extensible**: Easily extend the library to fit specific needs or integrate with other systems.
+- **Cross-Platform**: Multi-targeted for broad .NET compatibility
+
+
+# Advantage of using FSM
+
+Using a finite state machine (FSM) for managing state offers several advantages over ad-hoc approaches (like scattered conditionals, flags, or event-driven code) and even over some object-oriented state patterns. Here are the key benefits:
+
+1. Clarity and Explicitness
+    - All possible states and transitions are explicitly defined.
+    - The system’s behavior is easy to visualize, reason about, and document.
+    - Reduces ambiguity and hidden state changes.
+2. Predictability and Robustness
+    - Transitions are controlled and validated.
+    - Only allowed transitions can occur, preventing invalid or unexpected state changes.
+    - Makes it easier to handle edge cases and errors.
+3. Maintainability
+    - Adding or modifying states and transitions is straightforward.
+    - Changes are localized to the FSM definition, not scattered across the codebase.
+    - Reduces the risk of introducing bugs when requirements change.
+4. Testability
+    - FSMs are easy to test.
+    - You can systematically test all states and transitions.
+    - Makes it easier to write unit tests for state-dependent logic.
+5. Separation of Concerns
+    - State logic is separated from business logic.
+    - Conditions and side effects are encapsulated, making the codebase cleaner and more modular.
+6. Scalability
+    - FSMs scale well as complexity grows.
+    - Adding new states or transitions does not exponentially increase code complexity, unlike nested if/else or switch statements.
+7. Visualization and Documentation
+    - FSMs can be visualized as state diagrams.
+    - This aids in communication with stakeholders and helps onboard new developers.
+
+| Approach         | Pros of FSM over this approach                       | 
+|------------------|------------------------------------------------------|
+| If/else, switch  | Avoids spaghetti code, centralizes state logic       |
+| Flags/booleans   | Prevents invalid state combinations                  |
+| Event-driven     | Makes allowed transitions explicit and predictable   |
+| State pattern    | FSM is more declarative and easier to visualize      |
+
+# Use Cases
+Here are some common use cases for implementing a finite state machine (FSM) in software development:
+
+1. Workflow and Process Management
+    - Example: Ticketing systems, order processing, approval workflows.
+    - Why: Each item moves through a series of well-defined states (e.g., Open → In Progress → Resolved).
+2. User Interface (UI) Navigation
+    - Example: Wizard dialogs, multi-step forms, menu navigation.
+    - Why: UI components often have distinct states and transitions based on user actions.
+3. Game Development
+    - Example: Character states (Idle, Walking, Jumping, Attacking), enemy AI behaviors.
+    - Why: Game entities often have clear, rule-based state transitions.
+4. Protocol and Communication Handling
+    - Example: Network protocol implementations (TCP handshake, HTTP request/response), parsers.
+    - Why: Protocols are defined by sequences of states and transitions based on received data.
+5. Device and Hardware Control
+    - Example: Embedded systems, robotics, IoT devices (e.g., a washing machine: Idle → Washing → Rinsing → Spinning → Done).
+    - Why: Devices operate in modes with strict rules for moving between them.
+6. Authentication and Authorization Flows
+    - Example: Login processes, multi-factor authentication, session management.
+    - Why: Security flows require strict control over allowed transitions.
+7. Error Handling and Recovery
+    - Example: Retry logic, circuit breakers, transaction management.
+    - Why: Systems need to move between normal, error, and recovery states in a controlled way.
+8. Text Parsing and Lexical Analysis
+    - Example: Tokenizers, interpreters, compilers.
+    - Why: Parsing often involves moving through states based on input characters or tokens.

docs/2.Concepts.md

@@ -0,0 +1,89 @@
+Understanding the core building blocks of SharpFsm will help you design cleaner, maintainable, and more expressive state machines.
+
+# 📌 State
+A state represents a distinct condition or situation in the lifecycle of an object or process.
+
+## How to Define States
+States are typically defined using an `enum` for strong typing:
+```csharp
+public enum TicketState
+{
+    New,
+    InProgress,
+    Resolved,
+    Closed
+}
+```
+## Best Practices
+- Use clear and descriptive names (e.g., `PendingReview` > `Pending`).
+- Keep the enum definition in a shared or domain-specific namespace.
+- Avoid ambiguous or overloaded terms.
+
+# 🔁 Transition
+A transition defines how the FSM moves from one state to another.
+Each transition can specify:
+- Source state: where the transition starts
+- Target state: where it ends
+- Condition (optional): a predicate to allow or deny the transition
+- Side effect (optional): an action to run during the transition
+
+## Example
+```csharp
+.AddTransition(TicketState.New, TicketState.InProgress)
+    .When(ctx => ctx.IsAgentAssigned)
+    .WithSideEffect(ctx => Console.WriteLine("Notified agent"))
+    .Done()
+```
+## Condition
+A condition (or guard) is a predicate function used to determine if a transition should proceed.
+```csharp
+ctx => ctx.IsAgentAssigned
+```
+> Return `true` to allow the transition, `false` to block it.
+
+## Side Effect
+A side effect is a piece of logic executed during a transition. Use it for logging, notifications, or state synchronization.
+```csharp
+(ctx) => Console.WriteLine("Customer notified")
+```
+
+# 📦 Context
+The context is an object passed into transitions that contains runtime data.
+
+## Example
+```csharp
+public class TicketContext
+{
+    public bool IsAgentAssigned { get; set; }
+    public string CustomerEmail { get; set; }
+}
+```
+## Usage
+```csharp
+AddTransition(TicketState.New, TicketState.InProgress)
+    .When(ctx => ctx.IsAgentAssigned)
+    .WithSideEffect((ctx) => Notify(ctx.CustomerEmail))
+```
+
+# 🧬 State Machine Definition
+A state machine definition encapsulates:
+- All valid states
+- All transitions between those states
+- The initial state
+- Any associated logic (guards, side effects, outputs)
+
+This definition is used to construct a state machine instance via a builder.
+```csharp
+var context = new TicketContext { IsAgentAssigned = false, CustomerEmail = "[email protected]" };
+var definition = FiniteStateMachineBuilder<TicketState, TicketContext>.Create("Ticket")
+    .WithInitialState(TicketState.New)
+    .AddTransition(TicketState.New, TicketState.InProgress)
+        .When(ctx => ctx.IsAgentAssigned)
+        .WithSideEffect((ctx) => Notify(ctx.CustomerEmail))
+        .Done()
+    .Build();
+var fsm = new FiniteStateMachine<TicketState, TicketContext>(definition);
+fsm.TryTransitionTo(TicketState.InProgress, context); // Does not move to InProgress
+context.IsAgentAssigned = true;
+fsm.TryTransitionTo(TicketState.InProgress, context); // Moves to InProgress
+```

docs/3.Getting-Started.md

@@ -0,0 +1,55 @@
+# 📆 Installation
+[![NuGet version (SharpWiki)](https://img.shields.io/nuget/v/SharpFsm?label=SharpFsm&logo=nuget)](https://www.nuget.org/packages/SharpFsm/)
+
+> Supported .NET versions: .NET 6, .NET 8, .NET Standard 2.0, 2.1.
+
+```bash
+# .NET CLI
+dotnet add package SharpFsm
+
+# NuGet Package Manager
+Install-Package SharpFsm
+
+# Packet CLI
+paket add SharpFsm
+```
+
+# 🛠️ Basic Example
+Here's a minimal example of a switch with `On` and `Off` states:
+```csharp
+using SharpFsm;
+
+public enum SwitchState { Off, On }
+public class SwitchContext { }
+
+var builder = FiniteStateMachineBuilder<SwitchState, SwitchContext>.Create("Switch")
+    .WithInitialState(SwitchState.Off)
+    .AddTransition(SwitchState.Off, SwitchState.On).Done()
+    .AddTransition(SwitchState.On, SwitchState.Off).Done();
+var definition = builder.Build();
+var fsm = new FiniteStateMachine<SwitchState, SwitchContext>(definition);
+var context = new SwitchContext();
+
+Console.WriteLine(fsm.Current); // Output: Off
+fsm.TryTransitionTo(SwitchState.On, context);
+Console.WriteLine(fsm.Current); // Output: On
+```
+
+# 🧠 Adding Transition Conditions
+Transition guards allow you to conditionally permit or deny a state change based on runtime logic. This transition will only succeed during working hours (9 AM to 5 PM).
+```csharp
+.AddTransition(SwitchState.Off, SwitchState.On)
+    .When(ctx => DateTime.Now.Hour >= 9 && DateTime.Now.Hour <= 17)
+```
+
+> You can write complex logic inside your transition logic like connecting from database, making API calls etc.
+
+# ⚡ Adding Side Effects (On Transition)
+You can attach side effects to transitions — useful for logging, triggering events, or updating services.
+```csharp
+.AddTransition(SwitchState.On, SwitchState.Off)
+    .WithSideEffect((ctx) =>
+    {
+        // Your code goes here
+    })
+``` 

docs/4.Advanced-Usage.md

@@ -0,0 +1,104 @@
+# 🗂️ Transition Registry
+
+`TransitionRegistry<TContext>` is a utility class in SharpFsm that allows you to register and reuse named conditions and side effects for your state machine transitions. This makes your FSM definitions cleaner, more maintainable, and enables sharing logic across multiple transitions.
+
+## Key Features
+- Conditions: Functions that determine if a transition is allowed, based on the current context.
+- Side Effects: Actions to execute when a transition occurs.
+- Named Registry: Both conditions and side effects are registered with string keys, so you can reference them by name in your FSM builder.
+
+## Usage
+### Register conditions and side effects:
+```csharp
+var registry = new TransitionRegistry<OrderContext>();
+registry.RegisterCondition("PaymentReceived", ctx => ctx.PaymentReceived);
+registry.RegisterSideEffect("NotifyShipment", ctx => Console.WriteLine("Order shipped!"));
+```
+### Reference them by name in your FSM builder:
+```csharp
+var builder = FiniteStateMachineBuilder<OrderState, OrderContext>.Create("Order")
+    .WithRegistry(registry)
+    .AddTransition(OrderState.Created, OrderState.Paid)
+        .When("PaymentReceived") // Uses the named condition
+        .WithSideEffect("NotifyShipment") // Uses the named side effect
+        .Done();
+```
+## Benefits
+- Avoids repetition of logic
+- Encourages separation of transition rules from FSM structure
+- Easier to test, debug, and document named logic elements
+
+## Notes
+- Registry keys must be unique.
+- Make sure to register conditions and side effects before using them in the FSM builder.
+- You can define multiple registries per context type if needed for modularity.
+
+# 🧾 Serialization
+Serialization in `SharpFsm` allows you to save and load your finite state machine (FSM) definitions. This enables persistence, versioning, portability, and sharing of FSMs. It supports multiple formats including JSON and YAML.
+
+> The `TransitionRegistry` plays a crucial role in serialization by decoupling logic from structure, allowing reusable and maintainable FSMs.
+
+## How Serialization Works
+### FSM Definition Serialization
+- FSM definitions (states, transitions, initial state) are converted into a serializable DTO: `SerializableStateMachine`.
+- Conditions and side effects are not serialized as code — only their names are stored.
+- The actual logic is managed externally in the `TransitionRegistry`.
+
+## FSM Definition Deserialization
+- Deserialization reconstructs the FSM from its DTO using the FSM builder.
+- The builder resolves the named conditions and side effects using a `TransitionRegistry`.
+
+This approach ensures the FSM logic remains modular, shareable, and easy to update.
+
+## Example: JSON Serialization
+```csharp
+using System.Text.Json;
+
+var builder = FiniteStateMachineBuilder<OrderState, OrderContext>.Create("Order")
+    .WithInitialState(OrderState.Created)
+    .WithRegistry(registry)
+    // ... add transitions ...
+    ;
+// Serialize
+var serializable = builder.ToSerializable();
+string json = JsonSerializer.Serialize(serializable);
+// Deserialize
+var dto = JsonSerializer.Deserialize<SerializableStateMachine>(json);
+var loadedBuilder = FiniteStateMachineBuilder<OrderState, OrderContext>
+    .Create(dto.EntityType)
+    .LoadFrom(dto, registry);
+var fsm = new FiniteStateMachine<OrderState, OrderContext>(loadedBuilder.Build());
+```
+
+## Example: YAML Serialization
+```csharp
+using YamlDotNet.Serialization;
+using YamlDotNet.Serialization.NamingConventions;
+
+// Serialize
+var yamlSerializer = new SerializerBuilder()
+    .WithNamingConvention(CamelCaseNamingConvention.Instance)
+    .Build();
+string yaml = yamlSerializer.Serialize(serializable);
+
+// Deserialize
+var yamlDeserializer = new DeserializerBuilder()
+    .WithNamingConvention(CamelCaseNamingConvention.Instance)
+    .IgnoreUnmatchedProperties()
+    .Build();
+var dto = yamlDeserializer.Deserialize<SerializableStateMachine>(new StringReader(yaml));
+
+var loadedBuilder = FiniteStateMachineBuilder<OrderState, OrderContext>
+    .Create(dto.EntityType)
+    .LoadFrom(dto, registry);
+
+var fsm = new FiniteStateMachine<OrderState, OrderContext>(loadedBuilder.Build());
+```
+
+## Why TransitionRegistry is Key
+
+- 🧹 Separation of Structure and Logic: FSM structure is serialized; logic remains in the registry.
+- 🔁 Reusability: Named logic can be reused across multiple FSMs.
+- 🚚 Portability: Serialized FSMs don’t include executable code, making them environment-agnostic.
+- 🛠 Maintainability: Update logic in the registry without touching serialized FSM definitions.
+