Solidart v3: Refactor v3 core API and align ecosystem packages

README.md

@@ -53,7 +53,7 @@ To change the value, you can use:
 // Set the value to 2
 counter.value = 2;
 // Update the value based on the current value
-counter.updateValue((value) => value * 2);
+counter.value *= 2;
 ```
 
 ### Effect
@@ -177,8 +177,8 @@ SignalBuilder(
 )
 ```
 
-The `on` method forces you to handle all the states of a Resource (_ready_, _error_ and _loading_).
-The are also other convenience methods to handle only specific states.
+The `when` method forces you to handle all the states of a Resource (_ready_, _error_ and _loading_).
+There are also convenience helpers like `maybeWhen`, `asReady`, and `asError`.
 
 ### Dependency Injection
 

benchmark.dart

@@ -39,7 +39,6 @@ void main() {
   solidart.SolidartConfig.devToolsEnabled = false;
   solidart.SolidartConfig.trackPreviousValue = false;
   solidart.SolidartConfig.autoDispose = false;
-  solidart.SolidartConfig.equals = true;
   const framework = SolidartReactiveFramework();
   runFrameworkBench(framework);
 }

docs-v2/src/content/docs/migration.mdx

@@ -0,0 +1,169 @@
+---
+title: Migration (v2 -> v3)
+description: Upgrade guide for solidart v3
+---
+
+This guide is generated by comparing **v2** with **v3**. It reflects the actual
+public API changes in
+`solidart`, `flutter_solidart`, and `solidart_hooks`.
+
+## 1) Update package versions (upgrade together)
+
+```yaml
+# pubspec.yaml
+
+dependencies:
+  solidart: 3.0.0-dev.0
+  flutter_solidart: 3.0.0-dev.0
+  solidart_hooks: 3.2.0-dev.0
+
+dev_dependencies:
+  solidart_lint: 3.0.3
+```
+
+## 2) Entry points and exports
+
+### solidart
+
+**v2 (main) exported:**
+
+- `src/core/core.dart`
+- `src/extensions/until.dart`
+- `src/utils.dart` (Debouncer / SolidartException, etc.)
+
+**v3 (current) exported:**
+
+- `Signal`, `Computed`, `Effect`, `Resource`, `ListSignal`, `MapSignal`, `SetSignal`
+- `ReadonlySignal`, `SolidartConfig`, `SolidartObserver`
+- `ObserveSignal`, `UntilSignal`
+- `batch`, `untracked`
+- `DisposeObservation`, `ObserveCallback`, `ValueComparator`
+
+**New advanced entry point:**
+
+```dart
+import 'package:solidart/advanced.dart';
+```
+
+Exports `Configuration`, `Disposable`, `DisposableMixin`, `Identifier`,
+`Option`, `Some`, `None` (previously in core/utils).
+
+## 3) Core API changes (main -> current)
+
+### 3.1 Types and naming
+
+| v2 (main)                             | v3 (current)                      | Notes                                          |
+| ------------------------------------- | --------------------------------- | ---------------------------------------------- |
+| `SignalBase<T>`                       | `ReadonlySignal<T>` / `Signal<T>` | `SignalBase` removed                           |
+| `ReadSignal<T>` / `ReadableSignal<T>` | `ReadonlySignal<T>`               | ReadSignal types removed                       |
+| `toReadSignal()`                      | `toReadonly()`                    | Rename                                         |
+| `disposed`                            | `isDisposed`                      | Rename                                         |
+| `hasValue`                            | `LazySignal.isInitialized`        | Normal `Signal` is always initialized          |
+| `hasPreviousValue`                    | Removed                           | Use `previousValue` / `untrackedPreviousValue` |
+| `name`                                | `identifier.name`                 | `name` field removed from public API           |
+
+### 3.2 Signal updates
+
+**Removed:** `updateValue` / `setValue` public API.
+
+Use `.value` assignment instead.
+
+```dart
+// v2
+counter.updateValue((v) => v + 1);
+
+// v3
+counter.value += 1;
+```
+
+**Comparator change:**
+
+- v2 had `equals` (bool) + `comparator`
+- v3 keeps only a comparator:
+
+```dart
+final s = Signal(0, equals: (a, b) => a == b);
+```
+
+### 3.3 Effect
+
+**v2:** `Effect(callback, delay:, onError:, autorun:)` and `effect()` to dispose.  
+**v3:** `delay`, `onError`, `autorun` removed. Dispose via `effect.dispose()`.
+
+```dart
+// v2
+final dispose = Effect(() { ... }, delay: ..., onError: ...);
+dispose();
+
+// v3
+final effect = Effect(() { ... });
+effect.dispose();
+```
+
+If you need delayed/debounced effects, use `Timer`/debounce in user code.
+
+### 3.4 Resource
+
+- `source` now accepts `ReadonlySignal` instead of `SignalBase`.
+- `update` / `updateValue` removed → set `state` directly.
+- `ResourceExtensions` replaced by `ResourceStateExtensions`.
+- `on()` is removed (was deprecated in v2).
+- `resolve()` is now public (v2 had private `_resolve()`).
+
+```dart
+// v2
+resource.update((state) => state);
+
+// v3
+resource.state = ResourceState.ready(value);
+```
+
+### 3.5 Utils removal
+
+`solidart.dart` no longer exports:
+
+- `Debouncer` / `DebounceOperation`
+- `SolidartException`, `SolidartReactionException`, `SolidartCaughtException`
+- `createDelayedScheduler`
+
+If you relied on them, reimplement in your app or wrap them in a utility layer.
+
+## 4) Flutter integration (flutter_solidart)
+
+- `ReadableSignal` removed; use `ReadonlySignal`.
+- `ValueNotifierSignalMixin` is no longer exported.
+
+Extensions changed:
+
+- v2: `SignalBase.toValueNotifier()` and `ValueNotifier.toSignal()`
+- v3: `ReadonlySignal.toValueNotifier()` and `ValueListenable.toSignal()`
+
+## 5) Hooks (solidart_hooks)
+
+- `ReadSignal` → `ReadonlySignal`
+- `equals/comparator` replaced by `equals: ValueComparator<T>`
+
+Lifecycle change:
+
+- v2: dispose on unmount only if `autoDispose` was true
+- v3: hook-created signals are **always** disposed on unmount
+
+Use `useExistingSignal(...)` to bind external signals without disposing them.
+
+## 6) Behavioral differences
+
+- `SolidartConfig.autoDispose` default changed **true → false**
+- `SolidartConfig.equals` removed
+- `previousValue` updates only after a tracked read
+- `LazySignal` throws if read before first assignment (check `isInitialized`)
+
+## 7) Quick migration checklist
+
+- [ ] Upgrade versions in all solidart ecosystem packages
+- [ ] Replace `ReadSignal`/`SignalBase` with `ReadonlySignal`
+- [ ] Replace `toReadSignal()` with `toReadonly()`
+- [ ] Remove `updateValue` usages (use `.value = ...`)
+- [ ] Update Effect usage (no `delay/onError`, dispose via `.dispose()`)
+- [ ] Update Resource state handling (`state =`, `when/maybeWhen`)
+- [ ] Update Flutter extensions (`toValueNotifier`/`toSignal`)
+- [ ] Adjust hooks disposal expectations

examples/auth_flow/.metadata

@@ -15,7 +15,7 @@ migration:
     - platform: root
       create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
       base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
-    - platform: macos
+    - platform: web
       create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
       base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
 

examples/auth_flow/lib/domain/user.dart

@@ -8,8 +8,11 @@ class User {
   final String name;
   final String email;
 
-  factory User.fromMap(Map<String, dynamic> map) =>
-      User(id: map['id'] as String, name: map['name'] as String, email: map['email'] as String);
+  factory User.fromMap(Map<String, dynamic> map) => User(
+    id: map['id'] as String,
+    name: map['name'] as String,
+    email: map['email'] as String,
+  );
 
   Map<String, dynamic> toMap() => {'id': id, 'name': name, 'email': email};
 }

examples/auth_flow/lib/main.dart

@@ -9,7 +9,9 @@ void main() async {
   WidgetsFlutterBinding.ensureInitialized();
   await initLocalStorage();
 
-  runApp(ProviderScope(providers: [AuthNotifier.provider], child: const MyApp()));
+  runApp(
+    ProviderScope(providers: [AuthNotifier.provider], child: const MyApp()),
+  );
 }
 
 class MyApp extends StatefulWidget {
@@ -39,7 +41,9 @@ class _MyAppState extends State<MyApp> {
     return MaterialApp.router(
       title: 'Auth Demo - GoRouter',
       debugShowCheckedModeBanner: false,
-      theme: ThemeData(colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple)),
+      theme: ThemeData(
+        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
+      ),
       routerConfig: router,
     );
   }

examples/auth_flow/lib/routes/app_router.dart

@@ -2,6 +2,7 @@ import 'package:auth_flow/notifiers/auth_notifier.dart';
 import 'package:auth_flow/ui/home_page.dart';
 import 'package:auth_flow/ui/login_page.dart';
 import 'package:auth_flow/ui/profile_page.dart';
+import 'package:flutter_solidart/flutter_solidart.dart';
 import 'package:go_router/go_router.dart';
 
 class AppRouter {
@@ -10,7 +11,7 @@ class AppRouter {
   final AuthNotifier authNotifier;
 
   late final router = GoRouter(
-    refreshListenable: authNotifier.isLoggedIn,
+    refreshListenable: authNotifier.isLoggedIn.toValueNotifier(),
     redirect: (context, state) {
       final isLoggedIn = authNotifier.isLoggedIn.value;
       if (!isLoggedIn && state.matchedLocation != '/login') {
@@ -25,7 +26,9 @@ class AppRouter {
       GoRoute(
         path: '/',
         builder: (_, _) => const HomePage(title: 'Home'),
-        routes: [GoRoute(path: 'profile', builder: (_, _) => const ProfilePage())],
+        routes: [
+          GoRoute(path: 'profile', builder: (_, _) => const ProfilePage()),
+        ],
       ),
       GoRoute(path: '/login', builder: (_, _) => const LoginPage()),
     ],

examples/auth_flow/lib/ui/login_page.dart

@@ -16,7 +16,13 @@ class LoginPage extends StatelessWidget {
             ElevatedButton(
               onPressed: () {
                 final controller = AuthNotifier.provider.of(context);
-                controller.login(User(id: '1', name: 'John Doe', email: 'john.doe@example.com'));
+                controller.login(
+                  User(
+                    id: '1',
+                    name: 'John Doe',
+                    email: 'john.doe@example.com',
+                  ),
+                );
               },
               child: Text('Login'),
             ),

examples/auth_flow/pubspec.yaml

@@ -12,7 +12,7 @@ dependencies:
   flutter:
     sdk: flutter
   disco: ^1.0.3+1
-  flutter_solidart: ^2.7.2
+  flutter_solidart: 3.0.0-dev.0
   go_router: ^17.0.0
   localstorage: ^6.0.0
 
@@ -23,4 +23,3 @@ dev_dependencies:
 
 flutter:
   uses-material-design: true
-

examples/counter/.metadata

@@ -1,32 +1,23 @@
 # This file tracks properties of this Flutter project.
 # Used by Flutter tool to assess capabilities and perform upgrades etc.
 #
-# This file should be version controlled.
+# This file should be version controlled and should not be manually edited.
 
 version:
-  revision: 135454af32477f815a7525073027a3ff9eff1bfd
-  channel: stable
+  revision: "f6ff1529fd6d8af5f706051d9251ac9231c83407"
+  channel: "stable"
 
 project_type: app
 
 # Tracks metadata for the flutter migrate command
 migration:
   platforms:
     - platform: root
-      create_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-      base_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-    - platform: android
-      create_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-      base_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-    - platform: ios
-      create_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-      base_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-    - platform: macos
-      create_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-      base_revision: 135454af32477f815a7525073027a3ff9eff1bfd
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
     - platform: web
-      create_revision: 135454af32477f815a7525073027a3ff9eff1bfd
-      base_revision: 135454af32477f815a7525073027a3ff9eff1bfd
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
 
   # User provided section
 

examples/counter/pubspec.yaml

@@ -33,7 +33,7 @@ resolution: workspace
 dependencies:
   flutter:
     sdk: flutter
-  flutter_solidart: ^2.0.0
+  flutter_solidart: 3.0.0-dev.0
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.

examples/github_search/.metadata

@@ -1,32 +1,23 @@
 # This file tracks properties of this Flutter project.
 # Used by Flutter tool to assess capabilities and perform upgrades etc.
 #
-# This file should be version controlled.
+# This file should be version controlled and should not be manually edited.
 
 version:
-  revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-  channel: stable
+  revision: "f6ff1529fd6d8af5f706051d9251ac9231c83407"
+  channel: "stable"
 
 project_type: app
 
 # Tracks metadata for the flutter migrate command
 migration:
   platforms:
     - platform: root
-      create_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-      base_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-    - platform: android
-      create_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-      base_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-    - platform: ios
-      create_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-      base_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-    - platform: macos
-      create_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-      base_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
     - platform: web
-      create_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
-      base_revision: 84a1e904f44f9b0e9c4510138010edcc653163f8
+      create_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
+      base_revision: f6ff1529fd6d8af5f706051d9251ac9231c83407
 
   # User provided section
 

examples/github_search/pubspec.yaml

@@ -33,7 +33,7 @@ dependencies:
   disco: ^1.0.0
   flutter:
     sdk: flutter
-  flutter_solidart: ^2.0.0
+  flutter_solidart: 3.0.0-dev.0
   json_annotation: ^4.8.1
   equatable: ^2.0.5
   http: ^1.3.0