How to pass an initialization param to a capsule from build?

[opsb]

I've been trying to figure out how to pass parameters in when creating a capsule. Here's my two attempts:

1. Pass use into capsule function:

(String, Function(String)) counter(CapsuleHandle use, int initialValue) {
  return use.state(initialValue);
}

RearchBuilder(builder: (context, use) {
  final (count, setCount) = counter(use, 3);
});

This results in a compilation error because use is a WidgetHandle not a CapsuleHandle. Switching it to expect a WidgetHandle doesn't help because it doesn't have the use.state function available.

2. Use a factory

(String, Function(String)) Function(int) counter(CapsuleHandle use) {
  return (initialCount) => use.state(initialCount)
}

final (count, setCount) = use(counter)(3);

This time there's a runtime error You may only register side effects during a capsule's build!.

What's the right approach here?

[busslina]

You can't modify the capsule signature, so you can't pass initialization params to a capsule. You can read params from another capsule or you can modify a capsule (like the example set or increment). To pass initialization params seems to be imperative, so you should find a declarative way to do it.
You can pass initialization params to a custom side effect, but not to a capsule.

CounterController counterCapsule(CapsuleHandle use) {
  final count = use.data(0);

  return CounterController(
    count: count.value,
    increment: () => count.value++,
    set: (newValue) => count.value = newValue,
  );
}

class CounterController {
  CounterController({
    required this.count,
    required this.increment,
    required this.set,
  });

  final int count;
  final void Function() increment;
  final void Function(int value) set;
}

main() {
  final container = CapsuleContainer();

  final counter = container.read(counterCapsule);

  counter.set(3);
}

[opsb]

Interesting, what's the rationale for that?

[busslina]

Interesting, what's the rationale for that?

If you mean about state/data, state was first introduced and not too much time ago Greg introduced data at the same time he modified the core to allow to modify the current capsule state (data) when building the capsule. Prior to that (state) you couldn't do that because an error came after that (recursive building). So now, with data you can do almost everything: modify current state on building or modify capsule state from outside (executing a returned controller callback). One thing to consider is that it seems better to return a getter instead of a value, because the getter will give you always the latest value (even if you cache the getter). So use.data returns a getter/setter while use.state returns a value/setter.

[busslina]

We can say data and state is almost the same., But data is like a replacement for state and it's marked as:

/// While [state] will continue to work just fine,
/// it is recommended that newer applications also take a look at [data].

[GregoryConrad]

As @busslina mentioned, the idea is that data is more flexible than state. You can update data within or externally to a build using the same exact API and all will continue to work just fine.

For some (pretty recent) history, before there was a use.rawValueWrapper that I was never happy with, and one had to manually call rebuild to get states to update. Now, no new code should ever touch rebuild directly. I would remove it, but that'd break backwards compatibility. Perhaps I should deprecate it though--that's an idea.

state is kept because:

1. backwards compatibility reasons
2. it's exactly the api you want in certain simple scenarios, so you can just do => use.state(123);
3. for folks coming from react/flutter hooks

[opsb]

Coming from react hooks it certainly seemed like use.state would be the preferred way to do it. From what you say deprecating it would be helpful for newcomers (possibly even permanently as it's a good breadcrumb for react folk).

[GregoryConrad]

You cannot pass parameters to a capsule because it would no longer be a capsule (and capsules are typedefs for T Function(CapsuleHandle)). For many situations, the answer is factory capsules. There are also "dynamic capsules," but unless you need incremental computation (you will know if you need it when you need it) then you don't need it. For yours, it looks like you just want another capsule:

ValueWrapper<int> startingCountManager(CapsuleHandle use) => use.data(0);

(int, void Function()) countManager(CapsuleHandle use) {
  final count = use.data(use(startingCountManager).value);
  return (count.value, () => count.value++);
}

And just make sure to read/set the startingCountManager before countManager so the default is used.

[GregoryConrad]

You can do that, but it’s more idiomatic to make an extension on SideEffectRegistrar instead of making a method that consumes a WidgetHandle there

[opsb]

I suppose the way to think about this is not creating a parameterised capsule, rather just having a helper which uses an existing side effect.

[opsb]

Right, gotcha, I haven't used that mechanism yet, makes sense

[GregoryConrad]

just having a helper which uses an existing side effect

Oh sure, that’s just making a new side effect, which is done with extension methods on SideEffectRegisrar/WidgetSideEffectRegistrar

[opsb]

Awesome, thanks!