feat: automatic dispose (#76)

docs.json

@@ -71,6 +71,15 @@
         ]
       ]
     ],
+    [
+      "Advanced",
+      [
+        [
+          "Automatic disposal",
+          "/advanced/automatic-disposal"
+        ]
+      ]
+    ],
     [
       "Testing",
       [

docs/advanced/automatic-disposal.mdx

@@ -0,0 +1,118 @@
+---
+title: Automatic Disposal
+description: Learn how the automatic disposal works
+---
+
+# Automatic Disposal
+
+By default when you create a `Signal`, `Computed`, `Resource` or `Effect` the library will dispose them automatically.
+You can customize this behaviour using the options, for example for a `Signal` you have to create it with `autoDispose` set to `false`.
+
+```dart
+final counter = Signal(0, options: const SignalOptions<int>(autoDispose: false));
+```
+
+The automatic disposal happens automatically when there are no longer subscribers (for `Signal`, `Computed`, `Resource`) and when the __currently__ tracked dependencies are all disposed (for `Effect`).
+
+You don't need to dispose manually an `Observation` unless you want to stop it before the `Signal` is disposed.
+```dart
+final counter = Signal(0);
+final disposeObservation = counter.observe((previousValue, value) {
+   // do something 
+});
+```
+
+No need to call `disposeObservation()` if you need the observation to be called until the `counter` is alive.
+In fact you don't need to store the `disposeObservation` variable:
+
+```dart
+final counter = Signal(0);
+counter.observe((previousValue, value) {
+   // do something 
+});
+```
+
+There is a single case that the automatic disposal won't cover:
+
+```dart
+final count = Signal(0);
+
+@override
+void initState() {
+  super.initState();
+  Effect((_) {
+      print("The count is ${count.value}");
+    },
+  );
+}
+
+@override
+void dispose() {
+  // nothing disposed manually here
+  super.dispose();
+}
+```
+
+In the example above the `count` signal will not be disposed because the `Effect` is a subscriber, and the `Effect` won't be disposed because the `count` that watches is not disposed. So they're going to be alive forever.
+In order to fix this we need to dispose the `Effect` manually:
+
+```dart
+final count = Signal(0);
+late final DisposeEffect disposeEffect;
+
+@override
+void initState() {
+  super.initState();
+  disposeEffect = Effect((_) {
+      print("The count is ${count.value}");
+    },
+  );
+}
+
+@override
+void dispose() {
+  disposeEffect();
+  super.dispose();
+}
+```
+
+In this case the `count` signal would be disposed because the subscriber is disposed and no longer watches it.
+This would work also if you disposed only the `count` instead of the `Effect`.
+
+But I suggest to always dispose the `Effect` because it's always one, but if it is tracking multiple signals, all of them need to be disposed in order for the effect to dispose, for example:
+
+```dart
+final count = Signal(0);
+final name = Signal('Alex');
+
+@override
+void initState() {
+  super.initState();
+  Effect((_) {
+      print("The count is ${count.value} and the name is ${name.value}");
+    },
+  );
+}
+
+@override
+void dispose() {
+  count.dispose();
+  name.dispose();
+  super.dispose();
+}
+```
+
+As you can see both the `count` and `name` signals needs to be disposed in order for the `Effect` to dispose.
+This is the reason why I suggest to always dispose the `Effect`.
+
+In any case, don't worry to call `dispose()` yourself. It won't produce any error if it's already disposed. It just skips the operation.
+In fact in the source code the operation is skipped if the object is already disposed:
+
+```dart
+@override
+void dispose() {
+  // ignore if already disposed
+  if (_disposed) return;
+  ...
+}
+```

docs/learning/signals.mdx

@@ -56,8 +56,3 @@ counter.set(2);
 // Update the value based on the current value
 counter.updateValue((value) => value * 2);
 ```
-
-<Warning>Don't forget to call the `dispose()` method when you no longer need the signal.</Warning>
-```dart
-counter.dispose();
-```

examples/counter/pubspec.yaml

@@ -31,7 +31,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  flutter_solidart: ^1.4.0
+  flutter_solidart: ^1.5.0
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.

examples/github_search/pubspec.yaml

@@ -30,7 +30,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  flutter_solidart: ^1.4.0
+  flutter_solidart: ^1.5.0
   json_annotation: ^4.8.1
   equatable: ^2.0.5
   http: ^1.0.0

examples/todos/pubspec.yaml

@@ -31,7 +31,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  flutter_solidart: ^1.4.0
+  flutter_solidart: ^1.5.0
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.

examples/toggle_theme/pubspec.yaml

@@ -31,7 +31,7 @@ environment:
 dependencies:
   flutter:
     sdk: flutter
-  flutter_solidart: ^1.4.0
+  flutter_solidart: ^1.5.0
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.

packages/flutter_solidart/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.5.0
+
+### Changes from solidart
+
+- **FEAT**: Automatic disposal, [see the docs here](https://docs.page/nank1ro/solidart/advanced/automatic-disposal)
+
 ## 1.4.3
 
 ### Changes from solidart

packages/flutter_solidart/example/lib/main.dart

@@ -23,6 +23,7 @@ class MyApp extends StatelessWidget {
       debugShowCheckedModeBanner: false,
       title: 'Flutter Demo',
       theme: ThemeData(
+        useMaterial3: false,
         primarySwatch: Colors.blue,
       ),
       home: const HomePage(),

packages/flutter_solidart/example/lib/pages/counter.dart

@@ -11,12 +11,6 @@ class CounterPage extends StatefulWidget {
 class _CounterPageState extends State<CounterPage> {
   final counter = Signal(0);
 
-  @override
-  void dispose() {
-    counter.dispose();
-    super.dispose();
-  }
-
   @override
   Widget build(BuildContext context) {
     return Scaffold(

packages/flutter_solidart/example/lib/pages/derived_signal.dart

@@ -12,13 +12,6 @@ class _DerivedSignalsPageState extends State<DerivedSignalsPage> {
   late final count = Signal(0);
   late final doubleCount = Computed(() => count() * 2);
 
-  @override
-  void dispose() {
-    count.dispose();
-    doubleCount.dispose();
-    super.dispose();
-  }
-
   @override
   Widget build(BuildContext context) {
     return Scaffold(

packages/flutter_solidart/example/lib/pages/dual_signal_builder.dart

@@ -12,13 +12,6 @@ class _DualSignalBuilderPageState extends State<DualSignalBuilderPage> {
   final counter1 = Signal(0);
   final counter2 = Signal(0);
 
-  @override
-  void dispose() {
-    counter1.dispose();
-    counter2.dispose();
-    super.dispose();
-  }
-
   @override
   Widget build(BuildContext context) {
     final textTheme = Theme.of(context).textTheme;

packages/flutter_solidart/example/lib/pages/effects.dart

@@ -9,13 +9,13 @@ class EffectsPage extends StatefulWidget {
 }
 
 class _EffectsPageState extends State<EffectsPage> {
-  late final count = Signal(0);
-  late DisposeEffect disposeEffectFn;
+  final count = Signal(0);
+  late final DisposeEffect disposeEffect;
 
   @override
   void initState() {
     super.initState();
-    disposeEffectFn = Effect(
+    disposeEffect = Effect(
       (disposeFn) {
         // ignore: avoid_print
         print("The count is now ${count.value}");
@@ -25,8 +25,7 @@ class _EffectsPageState extends State<EffectsPage> {
 
   @override
   void dispose() {
-    count.dispose();
-    disposeEffectFn();
+    disposeEffect();
     super.dispose();
   }
 

packages/flutter_solidart/example/lib/pages/list_signal.dart

@@ -14,19 +14,17 @@ class ListSignalPage extends StatefulWidget {
 
 class _ListSignalPageState extends State<ListSignalPage> {
   final items = ListSignal([1, 2]);
-  late final DisposeObservation observation;
 
   @override
   void initState() {
     super.initState();
-    observation = items.observe((previousValue, value) {
+    items.observe((previousValue, value) {
       print("Items changed: $previousValue -> $value");
     });
   }
 
   @override
   void dispose() {
-    observation();
     items.dispose();
     super.dispose();
   }

packages/flutter_solidart/example/lib/pages/map_signal.dart

@@ -16,19 +16,17 @@ class MapSignalPage extends StatefulWidget {
 
 class _MapSignalPageState extends State<MapSignalPage> {
   final items = MapSignal({'a': 1, 'b': 2});
-  late final DisposeObservation observation;
 
   @override
   void initState() {
     super.initState();
-    observation = items.observe((previousValue, value) {
+    items.observe((previousValue, value) {
       print("Items changed: $previousValue -> $value");
     });
   }
 
   @override
   void dispose() {
-    observation();
     items.dispose();
     super.dispose();
   }

packages/flutter_solidart/example/lib/pages/resource.dart

@@ -20,13 +20,6 @@ class _ResourcePageState extends State<ResourcePage> {
     return jsonDecode(data)['hair_color'] as String;
   });
 
-  @override
-  void dispose() {
-    user.dispose();
-    userId.dispose();
-    super.dispose();
-  }
-
   Future<String> fetchUser() async {
     // simulating a delay to mimic a slow HTTP request
     await Future.delayed(const Duration(seconds: 2));

packages/flutter_solidart/example/lib/pages/set_signal.dart

@@ -14,19 +14,17 @@ class SetSignalPage extends StatefulWidget {
 
 class _SetSignalPageState extends State<SetSignalPage> {
   final items = SetSignal({1, 2});
-  late final DisposeObservation observation;
 
   @override
   void initState() {
     super.initState();
-    observation = items.observe((previousValue, value) {
+    items.observe((previousValue, value) {
       print("Items changed: $previousValue -> $value");
     });
   }
 
   @override
   void dispose() {
-    observation();
     items.dispose();
     super.dispose();
   }

packages/flutter_solidart/example/lib/pages/show.dart

@@ -12,12 +12,6 @@ class ShowPage extends StatefulWidget {
 class _ShowPageState extends State<ShowPage> {
   final loggedIn = Signal(false);
 
-  @override
-  void dispose() {
-    loggedIn.dispose();
-    super.dispose();
-  }
-
   @override
   Widget build(BuildContext context) {
     return Scaffold(

packages/flutter_solidart/example/lib/pages/solid/solid_signals.dart

@@ -28,8 +28,6 @@ class _SolidSignalsPageState extends State<SolidSignalsPage> {
           // provide the count signal to descendants
           Provider<Signal<int>>(
             create: () => count,
-            // do not autoDispose the signal, because we already dispose it ourself
-            autoDispose: false,
           ),
 
           // provide the doubleCount signal to descendants

packages/flutter_solidart/example/pubspec.yaml

@@ -36,7 +36,7 @@ dependencies:
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.
   cupertino_icons: ^1.0.2
-  flutter_solidart: ^1.4.0
+  flutter_solidart: ^1.5.0
 
 dev_dependencies:
   flutter_test: