chemistry 0.0.1

A new Flutter package project.

flutter_recoil

About

Chemistry is a state management library highly inspired by Recoil for React. It aims to be easy to use and integrate well with the Flutter platform.

Chemistry separates pure state from derived state. Pure state is called Atoms and derived state is called Molecules. A store, called Chemistry, is provided where all atoms and molecules can be stored and accessed anywhere in the program. This allows state to be accessed and modified in any widget without passing any state as parameters between them.

See the example for an example.

Installation

pub flutter pub add chemistry

Usage

Importing

import 'package:chemistry/chemistry.dart';

Atom

An atom is a pure state. It's a generic class that should be provided with the type of the data to be stored. It requires a default value and a key. The key must be globally unique among all atoms. Most of the time, the key will be the same as the name of the atom.

Creating an atom:

var myAtom = Atom<String>(defaultValue: 'Welcome', key: 'myAtom');

The value of an atom can be accessed with the .state getter.

print(myAtom.state);

Changes to the state can be listened to with the .stateStream getter. This stream will emit an event every time the state of the atom changes.

myAtom.stateStream.listen((state) => print(state));

The state of the atom can be changed with the .setState() method.

myAtom.setState('Chemistry');

Atom Chemistry

The Chemistry() class is a singleton that can store atoms and molecules. This allows it to be initialized anywhere in the program and all instances of it will be the same.

Adding an atom to the store:

var chemistry = Chemistry();
chemistry.addAtom<String>(myAtom);

Removing an atom from the store (note that the key of the atom to remove is passed as the argument):

chemistry.removeAtom('myAtom');

Getting an atom from the store (note that the key of the atom to get is passed as the argument):

var myAtom = chemistry.getAtom<String>('myAtom');

The .getAtom() method will return the atom if it exists, otherwise it will return null.

Molecule

A molecule is state derived from one or multiple atoms. It's a generic class that should be provided with the type of the data to be stored. It requires a list of atom keys, computer function and a key. The key must be globally unique among all atoms. Most of the time, the key will be the same as the name of the atom.

The list of atom keys are used to retreive the atoms from the Chemistry store. These are then passed to the computer function.

The computer function is a function that takes one argument: a map of all atoms the molecule depends on and is expected to return the value calculated.

Note that all atom keys supplied with the atomKeys argument must exist in the Chemistry store. If they do not, this will throw an exception.

Creating a molecule:

var myMolecule = Molecule<int>(
    atomKeys: <String>['firstAtom', 'secondAtom'],
    computer: (atoms) => atoms.values.fold<int>(
        0, (previousValue, atom) => previousValue + atom.state),
    key: 'myMolecule');

The value of a molecule can be accessed with the .state getter.

print(myMolecule.state);

Changes to the state can be listened to with the .stateStream getter. This stream will emit an event every time the state of the molecule changes.

myMolecule.stateStream.listen((state) => print(state));

Molecule Chemistry

Similar to how atoms can be stored in the Chemistry store, molecules can also be stored in the Chemistry store.

Adding a molecule to the store:

var chemistry = Chemistry();
chemistry.addMolecule<int>(myMolecule);

Removing a molecule from the store (note that the key of the molecule to remove is passed as the argument):

chemistry.removeMolecule('myMolecule');

Getting a molecule from the store (note that the key of the molecule to get is passed as the argument):

var myMolecule = chemistry.getMolecule<String>('myMolecule');

The .getMolecule() method will return the molecule if it exists, otherwise it will return null.

AtomBuilder

AtomBuilders are similar to StreamBuilders. It is a widget that is called with an atom and a function that receives the value of the atom as a parameter and is expected to return a widget. The widget returned is the child of the AtomBuilder. The widget automatically rebuilds and the builder function will be called with the new value when the state of the atom changes.

Example:

// Somewhere before the build method.
var myAtom = Atom<String>(defaultValue: 'Hello', key: 'myAtom');

// In the build method.
AtomBuilder<String>(
    atom: myAtom,
    builder: (context, value) => Text(value),)

MoleculeBuilder

These work just like AtomBuilder but for molecules.

Example:

// Somewhere before the build method.
var myMolecule = Molecule<int>(
    atomKeys: <String>['firstAtom', 'secondAtom'],
    computer: (atoms) => atoms.values.fold<int>(
        0, (previousValue, atom) => previousValue + atom.state),
    key: 'myMolecule');

// In the build method.
AtomBuilder<int>(
    molecule: myMolecule,
    builder: (context, value) => Text(value.toString()),)