fix(v1.0.0): complete v1.0.0 release preparation

Breaking Changes:
- Removed default handle_async/3 implementation in :reducer macro
  - Previously all reducers had a no-op handle_async/3 by default
  - This caused async: true actions to be silently ignored
  - Now handle_async/3 is only exported if explicitly defined
  - Actions with async: true will route to handle_action/2 if no handle_async/3

API Changes:
- dispatch_async/4 is now a convenience alias that adds async: true to meta
- dispatch_async/4 returns :ok (not {:ok, cancel_fn})
- Both dispatch/4 and dispatch_async/4 are fire-and-forget (async)

Version Updates:
- Updated version to 1.0.0 in mix.exs
- Updated README installation instructions to ~> 1.0
- Updated CHANGELOG release date to 2025-10-31
- Removed deprecated Redux modules from docs configuration

Documentation Updates:
- Fixed dispatch callback signatures in examples (3 arguments required)
- Updated all docs to reflect dispatch_async as convenience alias
- Clarified that async: true routes to handle_async/3 if available
- Added notes about default handle_async removal

Test Updates:
- Fixed dispatch_test.exs to expect :ok instead of {:ok, cancel_fn}
- Increased Process.sleep to 50ms for async action processing
- All 148 tests passing

Fixes:
- Fixed async actions being silently ignored when reducer lacks handle_async/3
- Fixed dispatch callback arguments in Example 03 (3 args required)
- Fixed test expectations for dispatch_async return value

Author: GSMLG-BOT

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 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).
 
-## [Unreleased] - v1.0.0
+## [1.0.0] - 2025-10-31
 
 ### Breaking Changes
 

CLAUDE.md

@@ -99,7 +99,7 @@ The library is organized into several logical groups:
 
    **Redux Store API (v1.0.0)** - SessionProcess IS the Redux store:
    - `dispatch/4` - Dispatch actions: `dispatch(session_id, type, payload \\ nil, meta \\ [])`
-   - `dispatch_async/4` - Async dispatch returning cancellation: `{:ok, cancel_fn}`
+   - `dispatch_async/4` - Convenience alias: `dispatch(id, type, payload, [meta | async: true])`
    - `subscribe/4` - Subscribe with selector
    - `unsubscribe/2` - Remove subscription
    - `get_state/1-2` - Get state (client-side, with optional selector)
@@ -266,8 +266,8 @@ The library is organized into several logical groups:
     - `type`: binary string (required)
     - `payload`: any term (defaults to nil)
     - `meta`: keyword list (defaults to [])
-  - `dispatch_async/4` returns `{:ok, cancel_fn}` where cancel_fn is `(() -> :ok)`
-  - `handle_async/3` MUST return cancellation callback `(() -> any())`
+  - `dispatch_async/4` is an alias for `dispatch(id, type, payload, [meta | async: true])`
+  - `handle_async/3` MUST return cancellation callback `(() -> any())` for internal use
 
 - **LiveView Integration**:
   - Use `Phoenix.SessionProcess.LiveView.mount_store/4` for direct subscriptions
@@ -446,13 +446,11 @@ defmodule MyAppWeb.PageController do
     :ok = SessionProcess.dispatch(session_id, "counter.increment")
     :ok = SessionProcess.dispatch(session_id, "user.set", %{id: 1, name: "Alice"})
 
-    # Async dispatch with cancellation
-    {:ok, cancel_fn} = SessionProcess.dispatch_async(
-      session_id,
-      "user.fetch",
-      123,
-      async: true
-    )
+    # Async dispatch (convenience - automatically adds async: true)
+    :ok = SessionProcess.dispatch_async(session_id, "user.fetch", 123)
+
+    # Equivalent to:
+    # :ok = SessionProcess.dispatch(session_id, "user.fetch", 123, async: true)
 
     # Get state
     state = SessionProcess.get_state(session_id)
@@ -631,11 +629,13 @@ Use `Phoenix.SessionProcess.Error.message/1` for human-readable error messages.
    end
    ```
 
-5. **dispatch_async Returns Cancellation**:
+5. **dispatch_async is Convenience Alias**:
    ```elixir
-   # Returns {:ok, cancel_fn}
-   {:ok, cancel_fn} = dispatch_async(session_id, "fetch", nil, async: true)
-   cancel_fn.()  # Call to cancel
+   # These are equivalent:
+   :ok = dispatch_async(session_id, "fetch", data)
+   :ok = dispatch(session_id, "fetch", data, async: true)
+
+   # Cancellation is handled internally via handle_async/3 callback in reducer
    ```
 
 6. **Prefer select_state/2 for Large States**:

README.md

@@ -37,7 +37,7 @@ Add `phoenix_session_process` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:phoenix_session_process, "~> 0.4.0"}
+    {:phoenix_session_process, "~> 1.0"}
   ]
 end
 ```
@@ -198,13 +198,11 @@ end
 :ok = Phoenix.SessionProcess.dispatch(session_id, "counter.increment")
 :ok = Phoenix.SessionProcess.dispatch(session_id, "counter.set", 10)
 
-# Async dispatch returns cancellation function
-{:ok, cancel_fn} = Phoenix.SessionProcess.dispatch_async(
-  session_id,
-  "counter.increment",
-  nil,
-  async: true
-)
+# Async dispatch (convenience - automatically adds async: true)
+:ok = Phoenix.SessionProcess.dispatch_async(session_id, "counter.increment")
+
+# Equivalent to:
+# :ok = Phoenix.SessionProcess.dispatch(session_id, "counter.increment", nil, async: true)
 
 # Get state (state is namespaced by reducer)
 state = Phoenix.SessionProcess.get_state(session_id)
@@ -438,12 +436,11 @@ The built-in Redux Store API provides state management with reducers defined usi
 # Dispatch actions (MUST use binary types)
 :ok = Phoenix.SessionProcess.dispatch(session_id, "counter.increment")
 
-# Async dispatch returns cancellation function
-{:ok, cancel_fn} = Phoenix.SessionProcess.dispatch_async(
+# Async dispatch (convenience alias)
+:ok = Phoenix.SessionProcess.dispatch_async(
   session_id,
   "user.set",
-  %{id: 123},
-  async: true
+  %{id: 123}
 )
 
 # Get current state after dispatch

examples/03_async_actions.exs

@@ -50,12 +50,12 @@ defmodule AsyncReducer do
         task =
           Task.async(fn ->
             # Simulate loading
-            dispatch.("data.loading")
+            dispatch.("data.loading", nil, [])
             Process.sleep(delay_ms)
 
             # Simulate fetching data
             items = ["item1", "item2", "item3"]
-            dispatch.("data.loaded", items)
+            dispatch.("data.loaded", items, [])
           end)
 
         # Return cancellation callback
@@ -107,19 +107,12 @@ receive do
     IO.puts("   • Initial state: loading=#{loading}, items=#{count}")
 end
 
-# Dispatch async action
+# Dispatch async action (dispatch_async automatically adds async: true)
 IO.puts("\n3. Dispatching async fetch (1000ms delay)...")
 
-{:ok, cancel_fn} =
-  Phoenix.SessionProcess.dispatch_async(
-    session_id,
-    "data.fetch",
-    1000,
-    async: true
-  )
+:ok = Phoenix.SessionProcess.dispatch_async(session_id, "data.fetch", 1000)
 
-IO.puts("   ✓ Async dispatch started")
-IO.puts("   ✓ Received cancellation function")
+IO.puts("   ✓ Async dispatch started (fire-and-forget)")
 
 # Receive loading notification
 receive do
@@ -142,28 +135,21 @@ end
 # Test cancellation
 IO.puts("\n4. Testing cancellation...")
 
-{:ok, cancel_fn2} =
-  Phoenix.SessionProcess.dispatch_async(
-    session_id,
-    "data.fetch",
-    2000,
-    async: true
-  )
+:ok = Phoenix.SessionProcess.dispatch_async(session_id, "data.fetch", 50)
 
-# Wait a bit
-Process.sleep(100)
+IO.puts("   • dispatch_async returns :ok (fire-and-forget)")
+IO.puts("   • Cancellation is handled internally by handle_async/3 callback")
+IO.puts("   • The cancel function is for internal lifecycle management only")
 
-# Cancel the task
-IO.puts("   • Calling cancellation function...")
-:ok = cancel_fn2.()
+# Wait for completion
+Process.sleep(100)
 
-# Should not receive completion
 receive do
-  {:state_changed, _} ->
-    IO.puts("   ⚠️  Received notification (task might have completed before cancel)")
+  {:state_changed, {loading, count}} ->
+    IO.puts("   ✓ Received notification: loading=#{loading}, items=#{count}")
 after
-  1000 ->
-    IO.puts("   ✓ No notification received (task was cancelled)")
+  200 ->
+    IO.puts("   • No notification (already processed)")
 end
 
 # Get final state

lib/phoenix/session_process.ex

@@ -636,74 +636,44 @@ defmodule Phoenix.SessionProcess do
   end
 
   @doc """
-  Dispatch an action asynchronously and return a cancellation function.
+  Dispatch an action asynchronously (convenience alias).
 
-  Unlike `dispatch/4` which returns `:ok`, this function returns a cancel callback
-  that can be used to cancel the pending async action.
+  This is a convenience function that automatically adds `async: true` to the meta.
+  It's equivalent to calling `dispatch(session_id, type, payload, [meta | async: true])`.
+
+  When `async: true` is in the meta, the action will trigger `handle_async/3` callbacks
+  in reducers that define them. The `handle_async` callback receives a dispatch function
+  and must return a cancellation callback for internal lifecycle management.
 
   ## Parameters
   - `session_id` - Session identifier
   - `action_type` - Action type (binary string)
   - `payload` - Action payload (any term)
-  - `meta` - Action metadata (keyword list)
+  - `meta` - Action metadata (keyword list, `async: true` will be added automatically)
 
   ## Returns
-  - `{:ok, cancel_fn}` - Action dispatched successfully with cancellation function
+  - `:ok` - Action dispatched successfully
   - `{:error, {:session_not_found, session_id}}` - If session doesn't exist
 
-  The cancellation function has signature: `cancel_fn.() :: :ok`
-  Calling it will attempt to cancel the pending action (best-effort).
-
   ## Examples
 
-      # Async dispatch with cancellation
-      {:ok, cancel} = SessionProcess.dispatch_async(session_id, "user.reload")
+      # Equivalent to: dispatch(id, "user.reload", nil, async: true)
+      :ok = SessionProcess.dispatch_async(session_id, "user.reload")
 
-      # Cancel if needed
-      cancel.()
+      # With payload - equivalent to: dispatch(id, "fetch_data", data, async: true)
+      :ok = SessionProcess.dispatch_async(session_id, "fetch_data", %{page: 1})
 
-      # With payload
-      {:ok, cancel} = SessionProcess.dispatch_async(session_id, "fetch_data", %{page: 1})
-
-      # Cancel after timeout
-      Process.send_after(self(), {:cancel, cancel}, 5000)
+      # With additional meta - equivalent to: dispatch(id, "reload", nil, [priority: :high, async: true])
+      :ok = SessionProcess.dispatch_async(session_id, "reload", nil, priority: :high)
   """
   @spec dispatch_async(binary(), String.t(), term(), keyword()) ::
-          {:ok, (-> :ok)} | {:error, term()}
+          :ok | {:error, term()}
   def dispatch_async(session_id, action_type, payload \\ nil, meta \\ [])
 
   def dispatch_async(session_id, action_type, payload, meta)
       when is_binary(session_id) and is_binary(action_type) and is_list(meta) do
-    alias Phoenix.SessionProcess.Action
-
-    # Convert keyword list to map for Action struct
-    meta_map = Map.new(meta)
-
-    # Generate unique reference for this dispatch
-    ref = make_ref()
-
-    # Add cancel_ref to meta
-    meta_with_ref = Map.put(meta_map, :cancel_ref, ref)
-
-    # Create action from components
-    action = Action.new(action_type, payload, meta_with_ref)
-
-    case ProcessSupervisor.session_process_pid(session_id) do
-      nil ->
-        {:error, {:session_not_found, session_id}}
-
-      pid ->
-        # Send async dispatch message
-        cast(session_id, {:dispatch_action, action})
-
-        # Return cancel function
-        cancel_fn = fn ->
-          GenServer.cast(pid, {:cancel_action, ref})
-          :ok
-        end
-
-        {:ok, cancel_fn}
-    end
+    # Add async: true to meta and delegate to dispatch/4
+    dispatch(session_id, action_type, payload, Keyword.put(meta, :async, true))
   end
 
   def dispatch_async(_session_id, action_type, _payload, _meta) when not is_binary(action_type) do
@@ -1066,9 +1036,12 @@ defmodule Phoenix.SessionProcess do
             fn -> nil end
           end
       """
-      def handle_async(_action, _dispatch, _state), do: fn -> nil end
 
-      defoverridable init_state: 0, handle_action: 2, handle_async: 3
+      # NOTE: No default implementation for handle_async/3
+      # Only export handle_async/3 if explicitly defined by the reducer
+      # This ensures function_exported?(module, :handle_async, 3) accurately reflects intent
+
+      defoverridable init_state: 0, handle_action: 2
     end
   end
 

mix.exs

@@ -1,7 +1,7 @@
 defmodule Phoenix.SessionProcess.MixProject do
   use Mix.Project
 
-  @version "0.6.0"
+  @version "1.0.0"
   @source_url "https://github.com/gsmlg-dev/phoenix_session_process"
 
   def project do
@@ -111,13 +111,7 @@ defmodule Phoenix.SessionProcess.MixProject do
         Utilities: [
           Phoenix.SessionProcess.Helpers,
           Phoenix.SessionProcess.Telemetry,
-          Phoenix.SessionProcess.Redux,
-          Phoenix.SessionProcess.Redux.Selector,
-          Phoenix.SessionProcess.Redux.Subscription,
-          Phoenix.SessionProcess.Redux.LiveView,
-          Phoenix.SessionProcess.MigrationExamples,
-          Phoenix.SessionProcess.ActivityTracker,
-          Phoenix.SessionProcess.RateLimiter
+          Phoenix.SessionProcess.Error
         ]
       ],
       skip_undefined_reference_warnings_on: ["CHANGELOG.md"]

test/phoenix/session_process/dispatch_test.exs

@@ -100,30 +100,29 @@ defmodule Phoenix.SessionProcess.DispatchTest do
       assert state2.test_reducer.count == 10
     end
 
-    test "dispatch_async returns {:ok, cancel_fn}", %{session_id: session_id} do
+    test "dispatch_async returns :ok (convenience alias)", %{session_id: session_id} do
       result = SessionProcess.dispatch_async(session_id, "increment")
-      assert {:ok, cancel_fn} = result
-      assert is_function(cancel_fn, 0)
+      assert :ok = result
 
-      # Wait a bit for async processing
-      Process.sleep(10)
+      # Wait for async processing (cast is asynchronous)
+      Process.sleep(50)
 
       # Verify state changed
       state = SessionProcess.get_state(session_id)
       assert state.test_reducer.count == 1
     end
 
-    test "dispatch_async returns cancellation function", %{session_id: session_id} do
-      # Dispatch async action
-      {:ok, cancel_fn} = SessionProcess.dispatch_async(session_id, "increment")
+    test "dispatch_async is equivalent to dispatch with async: true", %{session_id: session_id} do
+      # These two should be equivalent
+      :ok = SessionProcess.dispatch_async(session_id, "increment")
+      :ok = SessionProcess.dispatch(session_id, "increment", nil, async: true)
 
-      # Cancellation function can be called (best-effort cancellation)
-      assert :ok = cancel_fn.()
+      # Wait for async processing (cast is asynchronous)
+      Process.sleep(50)
 
-      # Note: Due to race conditions, we can't reliably test that the action
-      # was actually cancelled. The cancel is best-effort - if the action
-      # has already been processed before the cancel message arrives, it won't be cancelled.
-      # This test just verifies that the cancel function works without errors.
+      # Verify both actions were processed
+      state = SessionProcess.get_state(session_id)
+      assert state.test_reducer.count == 2
     end
 
     test "dispatch to non-existent session returns error", %{} do