docs: enhance documentation with comprehensive state management guide

GSMLG-BOT · GSMLG-BOT · commit d015255f94eb · 2025-10-24T16:05:56.000+08:00
Add detailed state management documentation covering all three approaches:
Basic GenServer, Agent-Based State, and Redux-Style State management.

BREAKING CHANGE: None - Documentation only changes

Features:
- Add comprehensive State Management Options section to README
- Include code examples for all three state management approaches
- Add comparison table for choosing the right approach
- Update CHANGELOG.md to follow Keep a Changelog format
- Document version 0.4.0 features including Redux and State modules
- Enhance MIGRATION_GUIDE.md with better context and guidance
- Fix code example bug in migration guide (variable name)
- Add "When to Use Redux" section with clear decision criteria

Documentation improvements:
- Consistent formatting across all markdown files
- Cross-references between README and MIGRATION_GUIDE
- Complete version history with semantic versioning
- Detailed feature descriptions for each release
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,18 +1,96 @@
 # Changelog
 
-## 0.3.1 (30 Sep 2024)
+All notable changes to this project will be documented in this file.
 
-* Fix bug.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## 0.3.0 (30 Sep 2024)
+## [0.4.0] - 2024-10-24
 
-* Add get_session_id in process.
+### Added
+- **Redux State Management**: New `Phoenix.SessionProcess.Redux` module for predictable state updates
+  - Time-travel debugging with complete action history
+  - Middleware support for logging, validation, and side effects
+  - State persistence and replay capabilities
+  - Reducer pattern for handling actions
+  - Configurable action history size
+- **Agent-Based State**: New `Phoenix.SessionProcess.State` module for simple key-value storage
+  - Lightweight Agent-based state management
+  - Simple get/put API for quick prototyping
+  - Redux dispatch support for hybrid approaches
+- **Enhanced Documentation**: Comprehensive guides and examples
+  - State management comparison and usage patterns
+  - Redux migration guide with step-by-step instructions
+  - Benchmark documentation and performance tuning guide
+  - Architecture documentation in CLAUDE.md
+- **Developer Experience**: Improved debugging and monitoring
+  - Action history tracking in Redux mode
+  - State inspection tools
+  - Middleware for custom debugging logic
 
-## 0.2.0 (5 Feb 2024)
+### Changed
+- Updated README.md with comprehensive state management section
+- Enhanced MIGRATION_GUIDE.md with Redux patterns and examples
+- Improved documentation structure and clarity
 
-* Add list_sessions and process_monitor macro.
+### Documentation
+- Added detailed comparison of three state management approaches
+- Included comprehensive examples for each approach
+- Added performance benchmarking guide
+- Enhanced architecture documentation
 
-## 0.1.0 (5 Feb 2024)
+## [0.3.1] - 2024-09-30
 
-* Create package.
+### Fixed
+- Bug fixes and stability improvements
+
+## [0.3.0] - 2024-09-30
+
+### Added
+- `get_session_id/0` helper function within session processes
+  - Access current session ID from within GenServer callbacks
+  - Simplifies session-aware logic implementation
+
+## [0.2.0] - 2024-02-05
+
+### Added
+- `list_sessions/0` function to retrieve all active session IDs
+- `:process_link` macro for LiveView integration
+  - Automatic LiveView process monitoring
+  - `:session_expired` message sent when sessions terminate
+  - Enhanced session lifecycle management
+
+### Features
+- Session process discovery and introspection
+- LiveView-aware session management
+
+## [0.1.0] - 2024-02-05
+
+### Added
+- Initial release of Phoenix.SessionProcess
+- Core session process management with GenServer
+- `Phoenix.SessionProcess.Supervisor` for managing session lifecycle
+- `Phoenix.SessionProcess.ProcessSupervisor` for dynamic process creation
+- `Phoenix.SessionProcess.Registry` for session lookup
+- `Phoenix.SessionProcess.Cleanup` for TTL-based automatic cleanup
+- `Phoenix.SessionProcess.SessionId` plug for session ID generation
+- Basic telemetry events for monitoring
+- Configuration options for session limits, TTL, and rate limiting
+- Error handling with detailed error types
+- `:process` macro for basic session processes
+- Session validation and limit enforcement
+
+### Features
+- Session isolation with dedicated GenServer per session
+- Automatic cleanup with configurable TTL
+- High-performance registry-based lookups
+- Comprehensive error handling
+- Rate limiting and session limit enforcement
+- Telemetry integration for monitoring
+
+[0.4.0]: https://github.com/gsmlg-dev/phoenix_session_process/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/gsmlg-dev/phoenix_session_process/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/gsmlg-dev/phoenix_session_process/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/gsmlg-dev/phoenix_session_process/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/gsmlg-dev/phoenix_session_process/releases/tag/v0.1.0
 
diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md
@@ -2,6 +2,8 @@
 
 This guide helps you migrate from traditional state management to Redux-style state management with actions and reducers.
 
+> **Note**: Phoenix.SessionProcess offers three state management approaches. See the [State Management Options](README.md#state-management-options) section in the README for a complete comparison and to choose the right approach for your needs.
+
 ## Overview
 
 The Redux-style state management provides:
@@ -11,6 +13,18 @@ The Redux-style state management provides:
 - **State persistence** and replay capabilities
 - **Better debugging** with action logging
 
+## When to Use Redux
+
+Consider migrating to Redux when you need:
+
+1. **Complex State Logic** - Multiple related state changes that need to be coordinated
+2. **Debugging Support** - Need to trace state changes and replay actions
+3. **Team Collaboration** - Multiple developers working on the same session logic
+4. **State Persistence** - Need to serialize and restore state (e.g., session recovery)
+5. **Audit Trail** - Requirement to track all state changes for compliance
+
+For simpler use cases, consider using the [Agent-Based State](README.md#2-agent-based-state-simple-and-fast) approach instead.
+
 ## Quick Migration Steps
 
 ### 1. Add Redux Module
@@ -260,10 +274,10 @@ defmodule MyApp.SessionTestHelpers do
 
   defp simulate_new_state(module, initial_state, actions) do
     redux = Redux.init_state(initial_state)
-    Enum.reduce(actions, redux, fn action, acc ->
+    final_redux = Enum.reduce(actions, redux, fn action, acc ->
       Redux.dispatch(acc, action, &module.reducer/2)
     end)
-    Redux.current_state(new_redux)
+    Redux.current_state(final_redux)
   end
 end
 ```
diff --git a/README.md b/README.md
@@ -283,6 +283,188 @@ defmodule MyApp.ComplexSessionProcess do
 end
 ```
 
+## State Management Options
+
+Phoenix.SessionProcess provides three approaches to manage session state, each suited for different use cases:
+
+### 1. Basic GenServer (Full Control)
+
+Use standard GenServer callbacks for complete control over state management:
+
+```elixir
+defmodule MyApp.BasicSessionProcess do
+  use Phoenix.SessionProcess, :process
+
+  @impl true
+  def init(_init_arg) do
+    {:ok, %{user_id: nil, data: %{}, timestamps: []}}
+  end
+
+  @impl true
+  def handle_call(:get_user, _from, state) do
+    {:reply, state.user_id, state}
+  end
+
+  @impl true
+  def handle_cast({:set_user, user_id}, state) do
+    {:noreply, %{state | user_id: user_id}}
+  end
+
+  @impl true
+  def handle_cast({:add_data, key, value}, state) do
+    new_data = Map.put(state.data, key, value)
+    {:noreply, %{state | data: new_data}}
+  end
+end
+```
+
+**Best for:** Custom logic, complex state transitions, performance-critical applications.
+
+### 2. Agent-Based State (Simple and Fast)
+
+Use `Phoenix.SessionProcess.State` for simple key-value storage with Agent:
+
+```elixir
+defmodule MyApp.AgentSessionProcess do
+  use Phoenix.SessionProcess, :process
+
+  @impl true
+  def init(_init_arg) do
+    {:ok, state_pid} = Phoenix.SessionProcess.State.start_link(%{
+      user: nil,
+      preferences: %{},
+      cart: []
+    })
+    {:ok, %{state: state_pid}}
+  end
+
+  @impl true
+  def handle_call(:get_user, _from, %{state: state_pid} = state) do
+    user = Phoenix.SessionProcess.State.get(state_pid, :user)
+    {:reply, user, state}
+  end
+
+  @impl true
+  def handle_cast({:set_user, user}, %{state: state_pid} = state) do
+    Phoenix.SessionProcess.State.put(state_pid, :user, user)
+    {:noreply, state}
+  end
+
+  @impl true
+  def handle_cast({:add_to_cart, item}, %{state: state_pid} = state) do
+    cart = Phoenix.SessionProcess.State.get(state_pid, :cart)
+    Phoenix.SessionProcess.State.put(state_pid, :cart, [item | cart])
+    {:noreply, state}
+  end
+end
+```
+
+**Best for:** Simple state management, quick prototyping, lightweight applications.
+
+### 3. Redux-Style State (Predictable and Debuggable)
+
+Use `Phoenix.SessionProcess.Redux` for predictable state updates with actions and reducers:
+
+```elixir
+defmodule MyApp.ReduxSessionProcess do
+  use Phoenix.SessionProcess, :process
+  alias Phoenix.SessionProcess.Redux
+
+  @impl true
+  def init(_init_arg) do
+    initial_state = %{
+      user: nil,
+      preferences: %{},
+      cart: [],
+      activity_log: []
+    }
+
+    redux = Redux.init_state(initial_state, reducer: &reducer/2)
+    {:ok, %{redux: redux}}
+  end
+
+  # Define reducer to handle all state changes
+  def reducer(state, action) do
+    case action do
+      {:set_user, user} ->
+        %{state | user: user}
+
+      {:update_preferences, prefs} ->
+        %{state | preferences: Map.merge(state.preferences, prefs)}
+
+      {:add_to_cart, item} ->
+        %{state | cart: [item | state.cart]}
+
+      {:remove_from_cart, item_id} ->
+        cart = Enum.reject(state.cart, &(&1.id == item_id))
+        %{state | cart: cart}
+
+      :clear_cart ->
+        %{state | cart: []}
+
+      {:log_activity, activity} ->
+        log = [activity | state.activity_log]
+        %{state | activity_log: log}
+
+      :reset ->
+        %{user: nil, preferences: %{}, cart: [], activity_log: []}
+
+      _ ->
+        state
+    end
+  end
+
+  @impl true
+  def handle_call(:get_state, _from, %{redux: redux} = state) do
+    current_state = Redux.current_state(redux)
+    {:reply, current_state, state}
+  end
+
+  @impl true
+  def handle_call(:get_history, _from, %{redux: redux} = state) do
+    history = Redux.history(redux)
+    {:reply, history, state}
+  end
+
+  @impl true
+  def handle_cast({:dispatch, action}, %{redux: redux} = state) do
+    new_redux = Redux.dispatch(redux, action)
+    {:noreply, %{state | redux: new_redux}}
+  end
+end
+
+# Usage
+Phoenix.SessionProcess.start("session_123", MyApp.ReduxSessionProcess)
+Phoenix.SessionProcess.cast("session_123", {:dispatch, {:set_user, %{id: 1, name: "Alice"}}})
+Phoenix.SessionProcess.cast("session_123", {:dispatch, {:add_to_cart, %{id: 101, name: "Widget", price: 29.99}}})
+
+{:ok, state} = Phoenix.SessionProcess.call("session_123", :get_state)
+{:ok, history} = Phoenix.SessionProcess.call("session_123", :get_history)
+```
+
+**Redux Features:**
+- **Time-travel debugging** - Access complete action history
+- **Middleware support** - Add logging, validation, side effects
+- **State persistence** - Serialize and restore state
+- **Predictable updates** - All changes through explicit actions
+- **Developer tools** - Inspect actions and state changes
+
+**Best for:** Complex applications, team collaboration, debugging requirements, state persistence needs.
+
+### Comparison
+
+| Feature | Basic GenServer | Agent State | Redux |
+|---------|----------------|-------------|-------|
+| Complexity | Low | Very Low | Medium |
+| Performance | Excellent | Excellent | Good |
+| Debugging | Manual | Manual | Built-in |
+| Time-travel | No | No | Yes |
+| Middleware | Manual | No | Yes |
+| State History | No | No | Yes |
+| Learning Curve | Low | Very Low | Medium |
+
+See [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) for detailed Redux migration guide and examples.
+
 ## Configuration Options
 
 | Option | Default | Description |
