What's New in 2.0

Shard 2.0 is a big release: a handful of new shards and mixins, richer async handling, first-class listeners, and a more robust persistence format. Most of it is additive—your existing code keeps working—but there are three small breaking changes to be aware of. This page is the tour; the Migrating from 1.x guide is the mechanical checklist.

Breaking changes

There are only three, and most apps touch at most one.

AsyncValue gained a fourth state, AsyncIdle. If you write your own exhaustive switch over an AsyncValue in app code, it will no longer compile until you handle AsyncIdle (or switch to when/maybeWhen). AsyncShardBuilder users are unaffected unless they want a distinct idle UI via onIdle:, and FutureShard/StreamShard never enter the idle state. See Migrating from 1.x.

StateStorage now requires a delete method. Any class that implements StateStorage must add Future<void> delete(String key). The contract is simple: after delete, a later load returns null, and deleting a key that was never stored is a no-op. See Migrating from 1.x.

Persisted state now uses a version envelope. Stored values are wrapped as {"__shard_v":N,"__shard_p":"…"}. No code change is required—reads are legacy-tolerant, so 1.x bare data is read as version 1 and your upgrade keeps its data. The only caveat is a 2.0→1.x downgrade, which cannot read 2.0-written data. You can optionally opt into schema migration with version/migrate. See Migrating from 1.x.

Highlights

Async

• AsyncIdle, the new fourth state, and ergonomic matchers when/maybeWhen → Async Values
• mapData/whenData for transforming the success case → Async Values
• AsyncValue.guard to wrap a future into an AsyncValue → Async Values
• AsyncShardBuilder.onIdle for a distinct idle UI → Widgets

Shards & composition

• CommandShard for explicit, user-triggered actions → CommandShard
• computedShard/ComputedShard for derived state that recomputes when its sources change → ComputedShard
• HistoryMixin for undo/redo → Undo & Redo
• Shard.stream to observe state changes as a stream → Core Concepts
• StreamShard.pause/resume to suspend and resume a subscription → StreamShard

Widgets

• ShardListener/MultiShardListener for side effects (navigation, snackbars, dialogs) → Widgets

Persistence

• clearPersistence to wipe a shard's stored slice → Persistent Shard
• Schema version/migrate to evolve your persisted model → Persistent Shard
• flushOnPause to persist when the app is backgrounded → Persistent Shard

Also now documented

These landed in 1.1/1.2 and now have full docs:

• LoggingObserver → Observing a Shard
• Testing utilities (ShardTester, FakeStateStorage, FakeCacheService, MockShardObserver) → Testing
• deepEquals/DeepEqualityMixin → Core Concepts
• MemoryCacheService bounding and CacheMixin logging → Response Caching

Next Steps

Next: Migrating from 1.x.