Skip to content

Commit 2a05a15

Browse files
committed
Add tip box explaining why commands notify on every execution by default
Added tip box in getting_started.md after the async example to explain: - Why commands notify on every execution (user feedback, state changes, action matters) - When to use notifyOnlyWhenValueChanges: true (pure computation, high-frequency, performance) - That default behavior is correct for most real-world scenarios Positioned right after users see their first practical example, before they learn about command properties.
1 parent 8ce1e4a commit 2a05a15

File tree

1 file changed

+15
-0
lines changed

1 file changed

+15
-0
lines changed

docs/documentation/command_it/getting_started.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,21 @@ Most real apps need async operations (HTTP calls, database queries, etc.). Comma
7070

7171
This pattern eliminates the boilerplate of manually tracking loading states and nested builders → commands + watch_it handle everything for you.
7272

73+
::: tip Commands Always Notify (By Default)
74+
Commands notify listeners on **every execution**, even if the result value is identical. This is intentional because:
75+
76+
1. **User actions need feedback** - When clicking "Refresh", users expect loading indicators even if data hasn't changed
77+
2. **State changes during execution** - `isRunning`, `CommandResult`, and error states update during the async operation
78+
3. **The action matters, not just the result** - The command executed (API called, file saved), which is important regardless of return value
79+
80+
**When to use `notifyOnlyWhenValueChanges: true`:**
81+
- Pure computation commands where only the result matters
82+
- High-frequency updates where identical results should be ignored
83+
- Performance optimization when listeners are expensive
84+
85+
For most real-world scenarios with user actions and async operations, the default behavior is what you want.
86+
:::
87+
7388
## Key Concepts at a Glance
7489

7590
command_it offers powerful features for production apps:

0 commit comments

Comments
 (0)