Changelog

Copy Markdown View Source

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.1 - 2026-10-12

Fixed

  • Explicit session termination now cancels the cleanup timer and removes activity tracking.
  • Scheduled cleanup removes stale activity after a session process has crashed.
  • TTL expiration avoids synchronous calls from Cleanup to itself and cancels timers during periodic cleanup.
  • Cleanup cancellation removes stale activity even when the timer is already absent.

Changed

  • Updated all active dependencies within their existing version constraints, including Plug 1.20.3.
  • Removed unused dependency lock entries.

[1.0.0] - 2025-10-31

Breaking Changes

  • Renamed @prefix to @action_prefix in reducer modules

    • All reducer modules must now use @action_prefix instead of @prefix
    • The @action_prefix can be nil or "" to create catch-all reducers that handle all actions
    • Migration: Simply rename @prefix to @action_prefix in your reducer modules
    • Example:
      # Before (v0.x)
defmodule MyReducer do
  use Phoenix.SessionProcess, :reducer
  @name :my_reducer
  @prefix "my"  # Old name
end

# After (v1.0.0)
defmodule MyReducer do
  use Phoenix.SessionProcess, :reducer
  @name :my_reducer
  @action_prefix "my"  # New name
end

  • Changed dispatch/3 and dispatch_async/3 return values

    • Both functions now return :ok instead of {:ok, new_state}
    • All dispatches are now async (fire-and-forget) by default
    • Use get_state/1-2 to retrieve state after dispatch
    • Migration:
      # Before (v0.x)
{:ok, new_state} = SessionProcess.dispatch(session_id, :increment)
IO.inspect(new_state)

# After (v1.0.0)
:ok = SessionProcess.dispatch(session_id, :increment)
new_state = SessionProcess.get_state(session_id)
IO.inspect(new_state)

  • Removed deprecated Phoenix.SessionProcess.Redux module

    • The old struct-based Redux API has been removed
    • Use the Redux Store API (built into SessionProcess) instead
    • See migration guide: REDUX_TO_SESSIONPROCESS_MIGRATION.md

  • Action prefix stripping in reducers

    • Reducers with @action_prefix now receive action types with the prefix stripped
    • When a reducer has @action_prefix "counter", handle_action receives "increment" instead of "counter.increment"
    • Dispatch calls still use full prefixed names (e.g., dispatch(id, "counter.increment"))
    • Catch-all reducers (prefix nil or "") receive unchanged action types
    • Migration:
      # Before (v0.x)
defmodule CounterReducer do
  use Phoenix.SessionProcess, :reducer
  @name :counter
  @action_prefix "counter"

  def handle_action(%Action{type: "counter.increment"}, state) do
    %{state | count: state.count + 1}
  end
end

# After (v1.0.0)
defmodule CounterReducer do
  use Phoenix.SessionProcess, :reducer
  @name :counter
  @action_prefix "counter"

  def handle_action(%Action{type: "increment"}, state) do
    %{state | count: state.count + 1}
  end
end

# Dispatch calls remain unchanged
dispatch(session_id, "counter.increment")

Added

  • dispatch_async/3 function for explicit async dispatch
    • Same behavior as dispatch/3 but with clearer naming for async operations
    • Makes code intent more explicit when dispatching async actions
    • Example: :ok = SessionProcess.dispatch_async(session_id, :increment)

Changed

  • Improved action routing with @action_prefix
    • More consistent naming aligns with action routing semantics
    • Catch-all reducers now explicitly use nil or "" for @action_prefix
    • Better documentation and examples for action routing

Migration Guide

  1. Rename @prefix to @action_prefix in all reducer modules

    • Search your codebase for @prefix in reducer modules
    • Replace with @action_prefix
    • No logic changes required

  2. Update action type patterns in handle_action/handle_async

    • Remove the prefix from action type patterns
    • Example: "counter.increment" becomes "increment"
    • Dispatch calls remain unchanged (still use full prefixed names)
    • Only affects reducers with non-nil/non-empty @action_prefix

  3. Update dispatch call sites to handle :ok return value

    • Replace {:ok, state} = dispatch(...) with :ok = dispatch(...)
    • Add get_state(session_id) calls where you need the updated state
    • Consider: Do you actually need the state? Many dispatches are fire-and-forget

  4. Remove uses of deprecated Redux module

    • If using Phoenix.SessionProcess.Redux struct-based API
    • Migrate to Redux Store API (SessionProcess IS the store)
    • See REDUX_TO_SESSIONPROCESS_MIGRATION.md for detailed migration

Documentation

  • Emphasized reusable reducers as core motivation
    • Updated README.md, CLAUDE.md to highlight reducer composition patterns
    • Added "Reducer Reusability - Core Value" section with concrete examples
    • Demonstrated how reducers are defined once and reused across session types
    • Included examples: UserSessionProcess, AdminSessionProcess, GuestSessionProcess
  • Added CODE_PROMPT.md for Claude Code assistance
    • Comprehensive 700+ line guide for AI-assisted development
    • Task-based examples covering setup, reducers, controllers, LiveView, testing
    • Common mistakes section with wrong/correct patterns
    • Best practices and troubleshooting guidance
  • Fixed session_id retrieval documentation
    • Corrected all examples from conn.assigns.session_id to get_session(conn, :session_id)
    • Updated SessionId plug documentation to show correct storage location
    • Fixed across README.md, CLAUDE.md, CODE_PROMPT.md, and source code
  • Clarified session lifecycle management
    • Documented that sessions should start in router hooks or login controllers
    • Updated LiveView examples to check for existing sessions, not start them
    • Added router hook and login controller examples
  • Fixed API signatures
    • Corrected start_session examples to use keyword arguments (module:, args:)
    • Added documentation for missing functions: touch/1 and session_stats/0
    • Updated all function signatures to match actual implementation
  • Enhanced reducer documentation
    • Added behaviour contract documentation (ProcessBehaviour, ReducerBehaviour)
    • Explained compile-time validation for reducer structure
    • Showed @impl annotations for callbacks

Notes

  • All changes are breaking but migrations are straightforward
  • Most codebases will only need to rename @prefix to @action_prefix
  • Dispatch return value change makes async nature more explicit
  • v0.9.x will be the last version supporting deprecated APIs

0.6.0 - 2025-10-29

Added

  • Redux Store API: SessionProcess now IS the Redux store - no separate Redux struct needed
  • Enhanced LiveView Integration: New helpers for Redux Store API
    • Phoenix.SessionProcess.LiveView.mount_store/4 - Mount with direct SessionProcess subscriptions
    • Phoenix.SessionProcess.LiveView.unmount_store/1 - Clean up subscriptions (optional, automatic cleanup via monitoring)
    • Phoenix.SessionProcess.LiveView.dispatch_store/3 - Dispatch actions with sync/async options
  • Selector-Based Subscriptions: Only receive updates when selected state changes
    • Efficient fine-grained state updates
    • Memoized selector support
    • Automatic equality checking to prevent unnecessary notifications
  • Process Monitoring: Automatic subscription cleanup when LiveView processes terminate
  • Comprehensive Documentation: Migration guides and examples
    • MIGRATION_GUIDE.md - Quick migration guide with 2-step process
    • REDUX_TO_SESSIONPROCESS_MIGRATION.md - Detailed migration guide
    • examples/liveview_redux_store_example.ex - Complete working example (400+ lines)
    • Updated CLAUDE.md with comprehensive Redux Store API documentation

Changed

  • 70% Less Boilerplate: Simplified API eliminates manual Redux struct management
  • Simpler Architecture: SessionProcess handles Redux infrastructure internally
  • Better Performance: Selector-based updates reduce unnecessary state notifications
  • Improved DX: Clearer code intent with less nesting and fewer concepts

Deprecated

  • Phoenix.SessionProcess.Redux module - Use Redux Store API instead
    • Redux.init_state/2 - Use user_init/1 callback
    • Redux.dispatch/3 - Use SessionProcess.dispatch/3
    • Redux.subscribe/3 - Use SessionProcess.subscribe/4
    • Redux.get_state/1 - Use SessionProcess.get_state/2
  • Phoenix.SessionProcess.LiveView old API - Use new Redux Store API
    • mount_session/4 - Use mount_store/4
    • unmount_session/1 - Use unmount_store/1
  • Migration Timeline: Deprecated APIs will be removed in v1.0.0 (supported through v0.9.x)

Migration

  • All old code continues to work with deprecation warnings
  • See MIGRATION_GUIDE.md for quick 2-step migration
  • See REDUX_TO_SESSIONPROCESS_MIGRATION.md for detailed examples
  • No breaking changes - 100% backward compatible

0.4.0 - 2024-10-24

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

Changed

  • Updated README.md with comprehensive state management section
  • Enhanced MIGRATION_GUIDE.md with Redux patterns and examples
  • Improved documentation structure and clarity

Documentation

  • Added detailed comparison of three state management approaches
  • Included comprehensive examples for each approach
  • Added performance benchmarking guide
  • Enhanced architecture documentation

0.3.1 - 2024-09-30

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

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