Flutter hook: useOptimistic 🪝

An easy-to-use hook to optimistically update generic state and then resolve it later (async or sync) by accept, acceptAs, or reject-ing.

Documentation

  • Full example of using this hook to manage integer state.
  • GitHub repo found here.
  • Package found here.

Documentation is largely found in the package itself via doc-comments (i.e. hover over package functions in your editor and it'll tell you what they do). First, however, view the above full example to get started.

Simple usage

demo image

Initialize the hook:

  final UseOptimistic<int> useOptimistic = UseOptimistic<int>(initialState: 0)

Ensure your widget listens to its state changes:

@override
void initState() {
  super.initState();
  useOptimistic.addListener(() => setState(() => debugPrint("state changed to: ${useOptimistic.state}")));
}

Ensure the hook will be disposed when your widget is:

@override
void dispose() {
  super.dispose();
  useOptimistic.dispose();
}

Update your state optimistically:

TextButton(
  onPressed: () async {

    Resolver r = useOptimistic.fn(
      1, // the [newValue] to be passed to functions below
      todo: (currentState, newValue) => currentState + newValue,
      undo: (currentState, oldValue) => currentState - oldValue,
    );

    // simulating an API call
    await Future.delayed(const Duration(seconds: 1));

    // three mutually exclusive ways to deal with result
    r.acceptAs(2); // [undo] original function, then [todo] with new value
    r.accept(); // accept the original optimistic update
    r.reject(); // reject the original optimistic update and [undo] original function

  },
  child: const Text("optimistically add 1"),
),

You can call useOptimistic.fn( ... ) multiple times with different todo and undo functions and it'll execute the proper todo/undo associated with fn at the moment you called it. This means you can call multiple separate useOptimistic.fn( ... )s safely together. It does not mean you can have a single fn like this (pseudo-code): useOptimistic.fn( if x todo: () => {...} else todo: () => {...} ) that has conditionally rendered todo/undo functions.

Listen to the state:

Text("current value: ${useOptimistic.state}"),

Extra

Libraries

use_optimistic