refactor: rename start/1,2,3 to start_session/1,2,3 for better semantics

Rename the session creation functions from start to start_session to
avoid confusion with start_link/1 (supervisor startup) and provide
clearer semantics about what the functions do.

Changes:
- Added start_session/1,2,3 as the new primary API
- Deprecated start/1,2,3 with @deprecated attribute
- Old functions delegate to new ones for backward compatibility
- Updated all documentation, examples, and tests to use start_session
- Updated files:
  * lib/phoenix/session_process.ex - New functions + deprecations
  * lib/phoenix/session_process/helpers.ex - Use start_session
  * All test files - Use start_session
  * All example files - Use start_session
  * README.md - Use start_session
  * CLAUDE.md - Use start_session

Benefits:
- Clearer distinction between supervisor startup (start_link) and session creation (start_session)
- More explicit naming reduces confusion
- Backward compatible - old API still works with deprecation warnings
- All 148 tests pass

Migration:
Replace Phoenix.SessionProcess.start(...) with Phoenix.SessionProcess.start_session(...)
The old functions will show deprecation warnings but continue to work.

Author: GSMLG-BOT

CLAUDE.md

@@ -441,7 +441,7 @@ defmodule MyAppWeb.PageController do
     session_id = conn.assigns.session_id
 
     # Start session
-    {:ok, _pid} = SessionProcess.start(session_id)
+    {:ok, _pid} = SessionProcess.start_session(session_id)
 
     # Dispatch actions (MUST use binary types)
     :ok = SessionProcess.dispatch(session_id, "counter.increment")

README.md

@@ -93,7 +93,7 @@ defmodule MyAppWeb.PageController do
     session_id = conn.assigns.session_id
 
     # Start session process
-    {:ok, _pid} = Phoenix.SessionProcess.start(session_id)
+    {:ok, _pid} = Phoenix.SessionProcess.start_session(session_id)
 
     # Store user data
     Phoenix.SessionProcess.cast(session_id, {:put, :user_id, conn.assigns.current_user.id})
@@ -193,7 +193,7 @@ end
 
 ```elixir
 # In your controller:
-{:ok, _pid} = Phoenix.SessionProcess.start(session_id, MyApp.SessionProcess)
+{:ok, _pid} = Phoenix.SessionProcess.start_session(session_id, MyApp.SessionProcess)
 
 # Dispatch actions (MUST use binary types)
 :ok = Phoenix.SessionProcess.dispatch(session_id, "counter.increment")
@@ -287,13 +287,13 @@ end
 
 ```elixir
 # Start with default module
-{:ok, pid} = Phoenix.SessionProcess.start("session_123")
+{:ok, pid} = Phoenix.SessionProcess.start_session("session_123")
 
 # Start with custom module
-{:ok, pid} = Phoenix.SessionProcess.start("session_123", MyApp.CustomProcess)
+{:ok, pid} = Phoenix.SessionProcess.start_session("session_123", MyApp.CustomProcess)
 
 # Start with custom module and arguments
-{:ok, pid} = Phoenix.SessionProcess.start("session_123", MyApp.CustomProcess, %{user_id: 456})
+{:ok, pid} = Phoenix.SessionProcess.start_session("session_123", MyApp.CustomProcess, %{user_id: 456})
 ```
 
 ### Communication
@@ -536,7 +536,7 @@ The library provides detailed error responses with the `Phoenix.SessionProcess.E
 ### Error Handling Examples
 
 ```elixir
-case Phoenix.SessionProcess.start(session_id) do
+case Phoenix.SessionProcess.start_session(session_id) do
   {:ok, pid} ->
     # Session started successfully
     {:ok, pid}
@@ -560,7 +560,7 @@ end
 Use `Phoenix.SessionProcess.Error.message/1` to get human-readable error messages:
 
 ```elixir
-{:error, error} = Phoenix.SessionProcess.start("invalid@session")
+{:error, error} = Phoenix.SessionProcess.start_session("invalid@session")
 Phoenix.SessionProcess.Error.message(error)
 # Returns: "Invalid session ID format: \"invalid@session\""
 ```

examples/01_basic_session.exs

@@ -41,7 +41,7 @@ end
 # Create a session
 session_id = "session_#{:rand.uniform(1_000_000)}"
 IO.puts("1. Starting session...")
-{:ok, pid} = Phoenix.SessionProcess.start(session_id, BasicSession)
+{:ok, pid} = Phoenix.SessionProcess.start_session(session_id, BasicSession)
 IO.puts("   ✓ Session started: #{session_id}")
 IO.puts("   ✓ Process PID: #{inspect(pid)}")
 

examples/02_redux_reducers.exs

@@ -82,7 +82,7 @@ end
 # Create a session
 session_id = "redux_session_#{:rand.uniform(1_000_000)}"
 IO.puts("1. Starting session with combined reducers...")
-{:ok, _pid} = Phoenix.SessionProcess.start(session_id, ReduxSession)
+{:ok, _pid} = Phoenix.SessionProcess.start_session(session_id, ReduxSession)
 IO.puts("   ✓ Session started: #{session_id}")
 IO.puts("   ✓ Reducers registered: counter, user")
 

examples/03_async_actions.exs

@@ -88,7 +88,7 @@ end
 # Create a session
 session_id = "async_session_#{:rand.uniform(1_000_000)}"
 IO.puts("1. Starting session...")
-{:ok, _pid} = Phoenix.SessionProcess.start(session_id, AsyncSession)
+{:ok, _pid} = Phoenix.SessionProcess.start_session(session_id, AsyncSession)
 IO.puts("   ✓ Session started: #{session_id}")
 
 # Subscribe to loading state

lib/phoenix/session_process.ex

@@ -51,7 +51,7 @@ defmodule Phoenix.SessionProcess do
           session_id = conn.assigns.session_id
 
           # Start session process
-          {:ok, _pid} = Phoenix.SessionProcess.start(session_id)
+          {:ok, _pid} = Phoenix.SessionProcess.start_session(session_id)
 
           # Store data
           Phoenix.SessionProcess.cast(session_id, {:put, :user_id, 123})
@@ -224,11 +224,20 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, pid} = Phoenix.SessionProcess.start("user_123")
-      {:error, {:already_started, pid}} = Phoenix.SessionProcess.start("user_123")
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123")
+      {:error, {:already_started, pid}} = Phoenix.SessionProcess.start_session("user_123")
   """
+  @spec start_session(binary()) :: {:ok, pid()} | {:error, term()}
+  defdelegate start_session(session_id), to: Phoenix.SessionProcess.ProcessSupervisor
+
+  @doc """
+  Deprecated: Use `start_session/1` instead.
+
+  This function is kept for backward compatibility but will be removed in a future version.
+  """
+  @deprecated "Use start_session/1 instead"
   @spec start(binary()) :: {:ok, pid()} | {:error, term()}
-  defdelegate start(session_id), to: Phoenix.SessionProcess.ProcessSupervisor, as: :start_session
+  def start(session_id), do: start_session(session_id)
 
   @doc """
   Starts a session process using a custom module.
@@ -248,19 +257,26 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, pid} = Phoenix.SessionProcess.start("user_123", MyApp.CustomSessionProcess)
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123", MyApp.CustomSessionProcess)
 
-      iex> result = Phoenix.SessionProcess.start("valid_session", Phoenix.SessionProcess.DefaultSessionProcess)
+      iex> result = Phoenix.SessionProcess.start_session("valid_session", Phoenix.SessionProcess.DefaultSessionProcess)
       iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
       true
 
-      iex> Phoenix.SessionProcess.start("invalid@session", Phoenix.SessionProcess.DefaultSessionProcess)
+      iex> Phoenix.SessionProcess.start_session("invalid@session", Phoenix.SessionProcess.DefaultSessionProcess)
       {:error, {:invalid_session_id, "invalid@session"}}
   """
+  @spec start_session(binary(), atom()) :: {:ok, pid()} | {:error, term()}
+  defdelegate start_session(session_id, module), to: Phoenix.SessionProcess.ProcessSupervisor
+
+  @doc """
+  Deprecated: Use `start_session/2` instead.
+
+  This function is kept for backward compatibility but will be removed in a future version.
+  """
+  @deprecated "Use start_session/2 instead"
   @spec start(binary(), atom()) :: {:ok, pid()} | {:error, term()}
-  defdelegate start(session_id, module),
-    to: Phoenix.SessionProcess.ProcessSupervisor,
-    as: :start_session
+  def start(session_id, module), do: start_session(session_id, module)
 
   @doc """
   Starts a session process with a custom module and initialization arguments.
@@ -282,23 +298,30 @@ defmodule Phoenix.SessionProcess do
   ## Examples
 
       # With map argument
-      {:ok, pid} = Phoenix.SessionProcess.start("user_123", MyApp.SessionProcess, %{user_id: 123})
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_123", MyApp.SessionProcess, %{user_id: 123})
 
       # With keyword list
-      {:ok, pid} = Phoenix.SessionProcess.start("user_456", MyApp.SessionProcess, [debug: true])
+      {:ok, pid} = Phoenix.SessionProcess.start_session("user_456", MyApp.SessionProcess, [debug: true])
 
-      iex> result = Phoenix.SessionProcess.start("valid_session_with_args", Phoenix.SessionProcess.DefaultSessionProcess, %{user_id: 123})
+      iex> result = Phoenix.SessionProcess.start_session("valid_session_with_args", Phoenix.SessionProcess.DefaultSessionProcess, %{user_id: 123})
       iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
       true
 
-      iex> result = Phoenix.SessionProcess.start("valid_session_with_list", Phoenix.SessionProcess.DefaultSessionProcess, [debug: true])
+      iex> result = Phoenix.SessionProcess.start_session("valid_session_with_list", Phoenix.SessionProcess.DefaultSessionProcess, [debug: true])
       iex> match?({:ok, _pid}, result) or match?({:error, {:already_started, _pid}}, result)
       true
   """
+  @spec start_session(binary(), atom(), any()) :: {:ok, pid()} | {:error, term()}
+  defdelegate start_session(session_id, module, arg), to: Phoenix.SessionProcess.ProcessSupervisor
+
+  @doc """
+  Deprecated: Use `start_session/3` instead.
+
+  This function is kept for backward compatibility but will be removed in a future version.
+  """
+  @deprecated "Use start_session/3 instead"
   @spec start(binary(), atom(), any()) :: {:ok, pid()} | {:error, term()}
-  defdelegate start(session_id, module, arg),
-    to: Phoenix.SessionProcess.ProcessSupervisor,
-    as: :start_session
+  def start(session_id, module, arg), do: start_session(session_id, module, arg)
 
   @doc """
   Checks if a session process is currently running.
@@ -312,7 +335,7 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      {:ok, _pid} = Phoenix.SessionProcess.start_session("user_123")
       true = Phoenix.SessionProcess.started?("user_123")
       false = Phoenix.SessionProcess.started?("nonexistent")
   """
@@ -336,7 +359,7 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      {:ok, _pid} = Phoenix.SessionProcess.start_session("user_123")
       :ok = Phoenix.SessionProcess.terminate("user_123")
       {:error, :not_found} = Phoenix.SessionProcess.terminate("user_123")
   """
@@ -361,7 +384,7 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      {:ok, _pid} = Phoenix.SessionProcess.start_session("user_123")
 
       # Keep session alive
       :ok = Phoenix.SessionProcess.touch("user_123")
@@ -396,7 +419,7 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      {:ok, _pid} = Phoenix.SessionProcess.start_session("user_123")
       {:ok, state} = Phoenix.SessionProcess.call("user_123", :get_state)
       {:ok, :pong} = Phoenix.SessionProcess.call("user_123", :ping, 5_000)
   """
@@ -421,7 +444,7 @@ defmodule Phoenix.SessionProcess do
 
   ## Examples
 
-      {:ok, _pid} = Phoenix.SessionProcess.start("user_123")
+      {:ok, _pid} = Phoenix.SessionProcess.start_session("user_123")
       :ok = Phoenix.SessionProcess.cast("user_123", {:put, :user_id, 123})
       :ok = Phoenix.SessionProcess.cast("user_123", {:delete, :old_key})
   """

lib/phoenix/session_process/helpers.ex

@@ -22,7 +22,7 @@ defmodule Phoenix.SessionProcess.Helpers do
   def start_sessions(session_ids) when is_list(session_ids) do
     session_ids
     |> Enum.map(fn session_id ->
-      Task.async(fn -> {session_id, SessionProcess.start(session_id)} end)
+      Task.async(fn -> {session_id, SessionProcess.start_session(session_id)} end)
     end)
     |> Task.await_many(5_000)
   end
@@ -159,12 +159,12 @@ defmodule Phoenix.SessionProcess.Helpers do
     result =
       if module do
         if arg do
-          SessionProcess.start(session_id, module, arg)
+          SessionProcess.start_session(session_id, module, arg)
         else
-          SessionProcess.start(session_id, module)
+          SessionProcess.start_session(session_id, module)
         end
       else
-        SessionProcess.start(session_id)
+        SessionProcess.start_session(session_id)
       end
 
     case result do

test/phoenix/session_process/dispatch_test.exs

@@ -51,7 +51,7 @@ defmodule Phoenix.SessionProcess.DispatchTest do
 
   setup do
     session_id = "test_session_#{:rand.uniform(1_000_000)}"
-    {:ok, _pid} = SessionProcess.start(session_id, TestSessionProcess)
+    {:ok, _pid} = SessionProcess.start_session(session_id, TestSessionProcess)
 
     on_exit(fn ->
       if SessionProcess.started?(session_id) do
@@ -137,7 +137,7 @@ defmodule Phoenix.SessionProcess.DispatchTest do
 
     test "dispatch validates action type is binary" do
       session_id = "validate_session_#{:rand.uniform(1_000_000)}"
-      {:ok, _pid} = SessionProcess.start(session_id, TestSessionProcess)
+      {:ok, _pid} = SessionProcess.start_session(session_id, TestSessionProcess)
 
       assert_raise ArgumentError, ~r/Action type must be a binary string/, fn ->
         SessionProcess.dispatch(session_id, :atom_type)
@@ -148,7 +148,7 @@ defmodule Phoenix.SessionProcess.DispatchTest do
 
     test "dispatch validates meta is a keyword list" do
       session_id = "validate_meta_#{:rand.uniform(1_000_000)}"
-      {:ok, _pid} = SessionProcess.start(session_id, TestSessionProcess)
+      {:ok, _pid} = SessionProcess.start_session(session_id, TestSessionProcess)
 
       assert_raise ArgumentError, ~r/Action meta must be a keyword list/, fn ->
         SessionProcess.dispatch(session_id, "test", nil, %{async: true})

test/phoenix/session_process/integration_test.exs

@@ -6,10 +6,10 @@ defmodule Phoenix.SessionProcess.IntegrationTest do
   test "session validation and limits" do
     # Test invalid session ID
     assert {:error, {:invalid_session_id, "invalid@session"}} =
-             SessionProcess.start("invalid@session")
+             SessionProcess.start_session("invalid@session")
 
     # Test empty session ID
-    assert {:error, {:invalid_session_id, ""}} = SessionProcess.start("")
+    assert {:error, {:invalid_session_id, ""}} = SessionProcess.start_session("")
   end
 
   test "error handling for non-existent sessions" do
@@ -45,7 +45,8 @@ defmodule Phoenix.SessionProcess.IntegrationTest do
     session_id = "custom_module_test"
 
     # Start with custom module
-    assert {:ok, _pid} = SessionProcess.start(session_id, TestCustomSession, %{test: "data"})
+    assert {:ok, _pid} =
+             SessionProcess.start_session(session_id, TestCustomSession, %{test: "data"})
 
     # Verify custom initialization worked
     assert %{custom: true} = SessionProcess.call(session_id, :get_state)

test/phoenix/session_process/macro_consistency_test.exs

@@ -32,7 +32,7 @@ defmodule Phoenix.SessionProcess.MacroConsistencyTest do
       session_id = "test_process_with_arg_#{:rand.uniform(10000)}"
       init_arg = %{user_id: 123, data: "test"}
 
-      {:ok, _pid} = SessionProcess.start(session_id, TestProcessWithArg, init_arg)
+      {:ok, _pid} = SessionProcess.start_session(session_id, TestProcessWithArg, init_arg)
 
       state = SessionProcess.call(session_id, :get_state)
       assert state.initialized_with == init_arg
@@ -44,7 +44,7 @@ defmodule Phoenix.SessionProcess.MacroConsistencyTest do
       session_id = "test_process_with_arg_#{:rand.uniform(10000)}"
       init_arg = %{user_id: 456, data: "test"}
 
-      {:ok, _pid} = SessionProcess.start(session_id, TestProcessLinkWithArg, init_arg)
+      {:ok, _pid} = SessionProcess.start_session(session_id, TestProcessLinkWithArg, init_arg)
 
       state = SessionProcess.call(session_id, :get_state)
       assert state.initialized_with == init_arg
@@ -61,8 +61,8 @@ defmodule Phoenix.SessionProcess.MacroConsistencyTest do
       init_arg = %{value: 42}
 
       # Both should accept the same argument format
-      {:ok, _} = SessionProcess.start(session_id_1, TestProcessWithArg, init_arg)
-      {:ok, _} = SessionProcess.start(session_id_2, TestProcessLinkWithArg, init_arg)
+      {:ok, _} = SessionProcess.start_session(session_id_1, TestProcessWithArg, init_arg)
+      {:ok, _} = SessionProcess.start_session(session_id_2, TestProcessLinkWithArg, init_arg)
 
       state1 = SessionProcess.call(session_id_1, :get_state)
       state2 = SessionProcess.call(session_id_2, :get_state)