docs: update examples and changelog for struct state

- Add changelog entry under [Unreleased] documenting the breaking change
- Update README handler examples to use dot access instead of Map.get
- Add note to DurableObject moduledoc about the generated State struct

Author: ChristianAlexander

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- State is now returned as a struct (`%MyApp.Counter.State{count: 0}`) instead of a plain atom-keyed map (`%{count: 0}`)
+  - The DSL automatically generates a nested `State` struct module from the declared fields and defaults
+  - `%{state | field: value}` update syntax continues to work unchanged
+  - State is persisted to the database as a plain JSON map (no `__struct__` key)
+  - Unknown keys in persisted state are silently dropped on load (forward-compatible with field removal)
+  - `get_persisted_state/3` in `DurableObject.Testing` now returns the module's `State` struct
+  - **Breaking:** `state[:field]` bracket access no longer works — use `state.field` dot access instead
+
 ## [0.2.1] - 2026-02-03
 
 ### Added

README.md

@@ -84,13 +84,12 @@ defmodule MyApp.Counter do
   end
 
   def handle_increment(amount \\ 1, state) do
-    new_count = Map.get(state, :count, 0) + amount
-    new_state = %{state | count: new_count, last_incremented_at: DateTime.utc_now()}
-    {:reply, new_count, new_state}
+    new_count = state.count + amount
+    {:reply, new_count, %{state | count: new_count, last_incremented_at: DateTime.utc_now()}}
   end
 
   def handle_get(state) do
-    {:reply, Map.get(state, :count, 0), state}
+    {:reply, state.count, state}
   end
 
   def handle_reset(state) do

lib/durable_object.ex

@@ -45,6 +45,10 @@ defmodule DurableObject do
       {:ok, count} = MyApp.Counter.increment("user-123", 5)
       {:ok, count} = MyApp.Counter.get("user-123")
 
+  The DSL generates a `MyApp.Counter.State` struct with the declared fields
+  and defaults. State is passed to handlers as a struct, so `state.count`
+  and `%{state | count: new_count}` work as expected.
+
   ## Manual Usage (without DSL)
 
   You can also call Durable Objects directly without the DSL: