Skip to content

Commit 632f2a6

Browse files
escamoteurescamoteur
committed
Release v9.1.0: Add global errors stream
New Features: - Added Command.globalErrors stream for reactive error monitoring - Stream emits all globally-routed command errors - Perfect for analytics, crash reporting, and UI notifications - watch_it integration with registerStreamHandler Improvements: - Renamed ErrorHandler* classes to *ErrorFilter pattern - Deprecated old names (removed in v10.0.0) Tests: - Added tests for new ErrorFilter classes - Added comprehensive tests for globalErrors stream - All 36 tests passing Documentation: - Updated global_configuration.md with globalErrors section - Updated error_handling.md with stream examples - Updated README.md with link to stream docs - Created global_errors_stream_example.dart code sample
1 parent 9ea2d22 commit 632f2a6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+5591
-24638
lines changed

‎API_PROPOSAL_v8.1_v9.0.md‎

Lines changed: 532 additions & 0 deletions
Large diffs are not rendered by default.

‎BREAKING_CHANGE_ANNOUNCEMENT.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
<div align="center">
2+
3+
<img src="https://github.com/flutter-it/command_it/blob/main/command_it.png?raw=true" alt="command_it logo" width="200"/>
4+
5+
# 🔮 Upcoming Breaking Change: v9.0.0
6+
7+
# ⚡ `execute` → `run` ⚡
8+
9+
## Making Commands More Natural
10+
11+
**Status: Proposal** • **Your Feedback Needed!**
12+
13+
</div>
14+
15+
---
16+
17+
## 📢 The Change
18+
19+
<table>
20+
<tr>
21+
<th>Before (v8.x)</th>
22+
<th>After (v9.0.0+)</th>
23+
</tr>
24+
<tr>
25+
<td>
26+
27+
```dart
28+
// Methods
29+
command.execute(param);
30+
await command.executeWithFuture(param);
31+
32+
// Properties
33+
command.isExecuting.value;
34+
command.canExecute.value;
35+
36+
// Widgets
37+
FloatingActionButton(
38+
onPressed: command.execute,
39+
child: Icon(Icons.play),
40+
)
41+
```
42+
43+
</td>
44+
<td>
45+
46+
```dart
47+
// Methods
48+
command.run(param);
49+
await command.runWithFuture(param);
50+
51+
// Properties
52+
command.isRunning.value;
53+
command.canRun.value;
54+
55+
// Widgets
56+
FloatingActionButton(
57+
onPressed: command.run,
58+
child: Icon(Icons.play),
59+
)
60+
```
61+
62+
</td>
63+
</tr>
64+
</table>
65+
66+
---
67+
68+
## 🎯 Why This Change?
69+
70+
### The Problem
71+
The callable class syntax (`command()`) triggers linter warnings due to **implicit call tear-offs**:
72+
73+
```dart
74+
// ⚠️ Triggers implicit_call_tearoffs warning
75+
onPressed: command
76+
```
77+
78+
This forces developers to use `.execute()` as the primary API, not the callable syntax.
79+
80+
### The Solution
81+
Since `.execute()` is now the primary API surface, let's make it **natural and Flutter-idiomatic**:
82+
83+
✨ **`run`** feels lighter and more action-oriented
84+
✨ Aligns with Flutter's "run the app" terminology
85+
✨ Shorter and easier to type (`isRunning` vs `isExecuting`)
86+
✨ More approachable than formal "execute" terminology
87+
88+
---
89+
90+
## 📅 Timeline
91+
92+
| Version | Date | What Happens |
93+
|---------|------|--------------|
94+
| **v9.0.0** | November 2025 | New `run` API added<br>Old `execute` API deprecated with warnings |
95+
| **v9.x** | Nov 2025 - May 2026 | Migration period<br>Both APIs work |
96+
| **v10.0.0** | May-June 2026 | Old `execute` API removed |
97+
98+
**Deprecation period:** 6 months
99+
100+
---
101+
102+
## 🔧 Migration Guide
103+
104+
### Automated (Recommended)
105+
106+
Use global search and replace:
107+
108+
```
109+
.execute( → .run(
110+
.executeWithFuture( → .runWithFuture(
111+
.isExecuting → .isRunning
112+
.canExecute → .canRun
113+
```
114+
115+
### What Changes
116+
117+
| Old API | New API |
118+
|---------|---------|
119+
| `execute()` | `run()` |
120+
| `executeWithFuture()` | `runWithFuture()` |
121+
| `isExecuting` | `isRunning` |
122+
| `canExecute` | `canRun` |
123+
| `ifRestrictedExecuteInstead` | `ifRestrictedRunInstead` |
124+
125+
---
126+
127+
## 🤔 Help Us Decide: Awaitable Method Name
128+
129+
Which name do you prefer for the awaitable version?
130+
131+
### Option 1: `runWithFuture()` ⭐ (Current Recommendation)
132+
```dart
133+
await command.runWithFuture(param);
134+
```
135+
✅ Direct parallel to current `executeWithFuture()`
136+
✅ Clearly indicates it returns a Future
137+
✅ Easiest migration (suffix stays the same)
138+
139+
### Option 2: `runAwaited()`
140+
```dart
141+
await command.runAwaited(param);
142+
```
143+
✅ Shorter and more concise
144+
✅ Emphasizes await-ability
145+
⚠️ Less clear that it returns a Future
146+
147+
### Option 3: `runAsync()`
148+
```dart
149+
await command.runAsync(param);
150+
```
151+
✅ Short and commonly used
152+
⚠️ Ambiguous (async commands are already async)
153+
154+
### Option 4: `runFuture()`
155+
```dart
156+
await command.runFuture(param);
157+
```
158+
✅ Very short
159+
⚠️ Grammatically awkward
160+
161+
**Vote for your favorite!** 👆
162+
163+
---
164+
165+
## 💬 Feedback Welcome!
166+
167+
**What do you think?**
168+
169+
- Is "run" the right choice?
170+
- Prefer `runAwaited()` over `runWithFuture()`?
171+
- Need more time for migration?
172+
173+
**Join the discussion:**
174+
- 💬 GitHub Discussion: [link]
175+
- 💭 Discord: https://discord.gg/ZHYHYCM38h
176+
177+
---
178+
179+
## 📖 Complete Details
180+
181+
See [BREAKING_CHANGE_EXECUTE_TO_RUN.md](BREAKING_CHANGE_EXECUTE_TO_RUN.md) for:
182+
- Complete motivation and reasoning
183+
- Full API mapping (300+ affected locations)
184+
- Detailed migration examples
185+
- Implementation timeline
186+
- Risk assessment
187+
188+
---
189+
190+
<div align="center">
191+
192+
### **command_it**
193+
*Command pattern for Flutter with reactive state management*
194+
195+
[Documentation](https://flutter-it.dev/documentation/command_it/getting_started) • [GitHub](https://github.com/flutter-it/command_it) • [pub.dev](https://pub.dev/packages/command_it)
196+
197+
</div>

0 commit comments

Comments
 (0)