Thoughts on API simplification

[alfalcon90]

Hi Rody! I'm in the process of migrating a large app to signals (hence the bug reports) and I figured I'd share some first impressions and feedback.

This is my second state management refactor on this app, after trying riverpod and building my own "homebrewed" solution, and I think signals is by far the best of those three options. I keep recommending signals over riverpod to people whenever the topic comes up 'cause I enjoy using it so much. Thanks for all your hard work!

The main draw for me (and I think for other folks as well) is how simple everything is. There's no boilerplate code, no passing ref around, no code generation, etc. Just writing final userName = signal('') is so simple and beautiful. It's also incredibly powerful when you start composing signals together. It's been very satisfying to replace whole freezed classes with just a couple of signals.

Having said that, I have noticed that there seems to be duplication of features and it's not obvious to newcomers like myself which feature they should be using. So here are some of the questions that have popped into my head this week while using signals:

• Why is _Signal a private class and why is it different from the Signal class? I think at some point I was trying to use a method that's only available in _Signal and I couldn't use it as a type 'cause it's private.
• Do we need the readonlySignal() function? I get using the ReadonlySignal class for computed() but I wonder if we need a separate function for it if we can just do final a = computed(() => true) or the readonly() method to accomplish the same.
• Why are previousValue, initialValue, and reset() available in some signals and not other? With the exception of ReadonlySignal not having reset(), shouldn't they be available on all signals?
• What's the difference between ValueSignal and Signal? Likewise, what about AsyncSignal and FutureSignal? Do we need them both? If we do, do we also need their respective create functions (asyncSignal() and valueSignal())
• Do we absolutely need the collection signals (ListSignal, MapSignal, SetSignal)? Is it mostly for the convenience of accessing methods like add() and remove()? If so, what if we had a separate package like collection_signals and kt_dart_signals for people that use kt_dart like myself?

I think in an ideal world, a dev trying out signals for the first time would only have to understand three basic concepts to get up and running:

1. I can create signals using three functions: signal(), futureSignal(), and streamSignal()
2. I can listen for changes using: subscribe(), effect(), and computed()
3. I can mutate signals using: set(), batch()

That's it. You can just know that much information and have a great time using signals. Other features like ChangeStack, SignalContainer and connect() can then be discovered naturally if there's a specific need but they're not necessary and don't conflict with the core features.

[rodydavis]

Thank you for this awesome feedback! Really appreciate the time to detail out the experience 💙

Signals is always evolving and I am not afraid to deprecate APIs, and move apis to other packages or extended imports. My goal with signals is to always create the smallest API possible that yields the greatest value.

For the value signals List/Map/Set the reason that got added early on was because people would first come to signals with a list and it wouldnt update when they set it.

final counter = signal(0);
final list = signal([1, 2, 3]);

counter.value++; // Updates
list.value.add(4); // Does not trigger

And I thought that this was going to be a big issue when first learning about signals. But I go think that having a separate package or import would be nice for them.

The reason _Signal is internal is because of the way computed and signals both share logic internally and that they are almost the same but not. I also leverage some static methods to set/update subscriptions.

Value signal now extends _SignalBase which signal and computed implement _Signal which is a small difference but from an API perspective is the correct order.

Value signal is really to be a drop in replacement for Cubit/ValueNotifier and any other class based signals you want to create yourself.

That being said, with the addition of .set(..., force: true) to signal I am thinking about deprecating value signal in favor of extending signal directly.

class MySignal extends Signal {
...
}

.reset is almost ready to be public but still trying to make sure it makes sense. The .overrideWith should be the replacement now that it has been added.

For ReadonlySignal and readonlySignal this was only meant to make it easy for using signals in DI since you can define a service as readonly but update it for testing.