Enhance documentation for session management; clarify usage of Session.use_store and configuration for various storage backends

Author: eliasjpr

docs/features/type-safe-sessions.md

@@ -13,7 +13,7 @@ class UserSession < Session::Base
 end
 ```
 
-The `authenticated?` method is abstract in `Session::Base` and must be implemented. Using `property?` is the simplest approach, but you can also define it manually:
+`Session::Base` provides a default `authenticated?` that returns `false`. Override it with your own logic:
 
 ```crystal
 class UserSession < Session::Base

docs/getting-started/installation.md

@@ -36,12 +36,14 @@ class TestSession < Session::Base
   property test : String = "Hello"
 end
 
+Session.use_store(Session::MemoryStore(TestSession))
+
 Session.configure do |config|
   config.secret = "test-secret-for-verification"
   config.store = Session::MemoryStore(TestSession).new
 end
 
-store = Session.config.store.not_nil!
+store = Session.config.store!
 session = store.create
 puts "Session ID: #{session.session_id}"
 puts "Installation successful!"

docs/getting-started/quick-start.md

@@ -28,9 +28,13 @@ end
 
 ## Step 2: Configure Session
 
-Set up the session configuration:
+Declare the store type with `Session.use_store`, then configure:
 
 ```crystal
+# Tell the library which concrete store type you'll use.
+# This must be called before Session.configure.
+Session.use_store(Session::MemoryStore(UserSession))
+
 Session.configure do |config|
   # Required: Secret key for encryption (use environment variable in production)
   config.secret = ENV["SESSION_SECRET"]? || "your-32-character-secret-key-here"
@@ -41,17 +45,22 @@ Session.configure do |config|
   # Cookie name
   config.session_key = "myapp_session"
 
-  # Choose a storage backend
+  # Assign a store instance matching the type declared above
   config.store = Session::MemoryStore(UserSession).new
 end
 ```
 
+> **Why `use_store`?** Crystal's generic type system is invariant: a
+> `MemoryStore(UserSession)` cannot be assigned to `Store(Base)?`. `use_store`
+> injects a typed `store` property into `Configuration` so the compiler knows
+> the exact type.
+
 ## Step 3: Use Sessions
 
 ### Create a Session
 
 ```crystal
-store = Session.config.store.not_nil!
+store = Session.config.store!
 
 # Create a new session
 session = store.create
@@ -100,13 +109,15 @@ Integrate with an HTTP server:
 require "http/server"
 require "session"
 
-# Configure session
+# Declare store type, then configure
+Session.use_store(Session::MemoryStore(UserSession))
+
 Session.configure do |config|
   config.secret = ENV["SESSION_SECRET"]
   config.store = Session::MemoryStore(UserSession).new
 end
 
-store = Session.config.store.not_nil!
+store = Session.config.store!
 
 # Create server with session handler
 server = HTTP::Server.new([
@@ -175,15 +186,17 @@ class UserSession < Session::Base
   end
 end
 
-# Configure
+# Declare store type, then configure
+Session.use_store(Session::MemoryStore(UserSession))
+
 Session.configure do |config|
   config.secret = ENV["SESSION_SECRET"]? || "dev-secret-32-characters-long!!"
   config.timeout = 1.hour
   config.sliding_expiration = true
   config.store = Session::MemoryStore(UserSession).new
 end
 
-store = Session.config.store.not_nil!
+store = Session.config.store!
 
 # Server
 server = HTTP::Server.new([

docs/storage-backends/overview.md

@@ -38,6 +38,8 @@ graph TD
 ### Cookie Store
 
 ```crystal
+Session.use_store(Session::CookieStore(UserSession))
+# then inside Session.configure:
 config.store = Session::CookieStore(UserSession).new
 ```
 
@@ -49,6 +51,8 @@ config.store = Session::CookieStore(UserSession).new
 ### Memory Store
 
 ```crystal
+Session.use_store(Session::MemoryStore(UserSession))
+# then inside Session.configure:
 config.store = Session::MemoryStore(UserSession).new
 ```
 
@@ -60,9 +64,9 @@ config.store = Session::MemoryStore(UserSession).new
 ### Redis Store
 
 ```crystal
-config.store = Session::RedisStore(UserSession).new(
-  client: Redis.new
-)
+Session.use_store(Session::RedisStore(UserSession))
+# then inside Session.configure:
+config.store = Session::RedisStore(UserSession).new(client: Redis.new)
 ```
 
 **Use when:**
@@ -73,10 +77,10 @@ config.store = Session::RedisStore(UserSession).new(
 ### Clustered Redis Store
 
 ```crystal
+Session.use_store(Session::ClusteredRedisStore(UserSession))
+# then inside Session.configure:
 config.cluster.enabled = true
-config.store = Session::ClusteredRedisStore(UserSession).new(
-  client: Redis.new
-)
+config.store = Session::ClusteredRedisStore(UserSession).new(client: Redis.new)
 ```
 
 **Use when:**