Tutoriel pour apprendre à implémenter l'architecture flux avec React

En rouge sur le schéma.
Dans une architecture Flux, tout passe par les actions. On ne peut pas modifier l'affichage d'un composant ou déclencher un comportement sans action. C'est à partir d'une action qu'on pourra modifier le state d'un composant React par exemple. Si le code de l'action est complexe, on peut séparer sa création et l'instance elle-même (ce qui explique les deux briques du schéma). C'est dans ce composant qu'on s'interfacera avec des API externes à l'architecture Flux. Typiquement, les actions sont déclenchées par un clic dans une GUI, ou bien peuvent provenir du serveur via une websocket, par exemple.

En noir sur le schéma.
Le dispatcher est le composant unique qui reçoit toutes les actions de l'application. Son rôle est de notifier tous les stores via des callbacks que l'action a eu lieu.

En marron sur le schéma.
Les stores sont les composants de Flux qui vont contenir et gérer les states de l'application. Ils fournissent au dispatcher les callbaks exécutés lors de la notification d'une action. Il va donc contenir l'implémentation de toutes les règles de gestions du domaine qu'il couvre. Il va également gérer les actions qu'il veut traiter, car comme expliqué ci-dessus, le dispatcher notifie les stores de toutes les actions de l'application. Chaque store s'occupera d'une partie du fonctionnel de l'application et ne voudra donc pas traiter toutes les actions. Pour finir, les stores vont notifier par événement les changements d'état aux vues leur correspondant.

En bleu sur le schéma.
Les vues sont chargées d'afficher le state contenu dans le store associé. Elles s'enregistrent auprès du store pour être notifiées des changements de state, pour se mettre à jour en conséquence.

Finalement, si on reformule l'enchaînement de tout ça, il y a deux phases :

• à l'initialisation : le dispatcher est instancié de manière unique. Chaque store s'enregistre auprès de lui via un callback et choisit de traiter une liste d'actions prédéfinies. Chaque vue s'abonne à un événement dans le but de se mettre à jour pour refléter le changement de state du store ;
• suite à une action : une action est déclenchée et est envoyée au dispatcher, qui va exécuter tous les callbacks de tous les stores pour propager l'action en cours. Chaque store qui l'a prévu va exécuter les règles associées à cette action et mettre son state à jour en fonction. Si le state est mis à jour, un événement est déclenché pour dire aux vues associées au store de se rafraîchir pour traduire le changement de state du store.

Pour commencer, faisons l'inventaire des actions. On peut ajouter ou supprimer un article du panier, ce qui va entraîner une diminution ou une augmentation du stock. Donc nous aurons ADD_TO_BASKET, REMOVE_FROM_BASKET, FILL_STOCK et EMPTY_STOCK.

import FluxAppDispatcher from '../dispatcher/fluxAppDispatcher';
import Constants from '../constants';

export default class BasketAction {
  static addProduct(product) {
    const addBasketActionObject = {
      type: Constants.ADD_TO_BASKET,
      payload: product,
    };
    FluxAppDispatcher.dispatch(addBasketActionObject);
  }

  static removeProduct(product) {
    const removeBasketActionObject = {
      type: Constants.REMOVE_FROM_BASKET,
      payload: product,
    };
    FluxAppDispatcher.dispatch(removeBasketActionObject);
  }
}

import FluxAppDispatcher from '../dispatcher/fluxAppDispatcher';
import Constants from '../constants';

export default class StockAction {
  static increaseStock(stock) {
    const increaseStockActionObject = {
      type: Constants.FILL_STOCK,
      payload: stock,
    };
    FluxAppDispatcher.dispatch(increaseStockActionObject);
  }

  static decreaseStock(stock) {
    const decreaseStockActionObject = {
      type: Constants.EMPTY_STOCK,
      payload: stock,
    };
    FluxAppDispatcher.dispatch(decreaseStockActionObject);
  }
}

Dans le code, on voit la différence entre les ActionCreator (ici les classes elles-mêmes) et les actions à proprement parler. Les variables appelées actionPayload sont les objets modélisant les actions. Ici, ce sont de simples conteneurs.

Le dispatcher est le code le plus simple, puisqu'on utilise directement l'objet fourni par la dépendance « flux » de Facebook :

import Flux from 'flux';
export default new Flux.Dispatcher();

Le dispatcher devant être unique, on exporte une instance du Dispatcher et non le prototype seul. C'est cette instance qui sera utilisée tout au long de la durée de vie de l'application.

Nous allons construire deux stores : un pour gérer l'état du panier, l'autre pour gérer l'état du rayon. Regardons deux implémentations différentes. La première reposera sur l'EventEmmitter de NodeJS pour gérer les événements envoyés aux vues. La seconde exploitera directement la classe FluxStore exposée en tant que Store par le module flux/utils.

import Constants from '../constants';
import Dispatcher from '../dispatcher/fluxAppDispatcher';
import EventEmmiter from 'events';
import initProduct from '../data.json';
const products = initProduct;

class ShelfStore extends EventEmmiter {

  emitChange() {
    this.emit(Constants.CHANGE_EVENT);
  }

  addChangeListener(callback) {
    this.on(Constants.CHANGE_EVENT, callback);
  }

  removeChangeListener(callback) {
    this.removeListener(Constants.CHANGE_EVENT, callback);
  }

  getState() {
    return products;
  }
}

const shelfStore = new ShelfStore();

shelfStore.token = Dispatcher.register((actionPayload) => {
  console.log('ShelfStore', actionPayload);
  const product = products.find(item => item.id === actionPayload.payload.id);
  if (actionPayload.type === Constants.FILL_STOCK) {
    product.quantity += 1;
    shelfStore.emitChange();
  } else if (actionPayload.type === Constants.EMPTY_STOCK) {
    product.quantity -= 1;
    shelfStore.emitChange();
  }
});

export default shelfStore;

On voit ici les différents mécanismes de gestion des événements implémentés à la main. ShelfStore hérite de EventEmmiter. La méthode d'émission de l'événement, l'ajout et la suppression des listeners du store permettent d'encapsuler les appels aux méthodes de la classe EventEmmiter.

Le callback enregistré auprès du dispatcher est ajouté sur l'instance du store créée directement avec la définition de la classe. A priori, on n'a pas besoin de plus d'une instance de ce store. C'est dans ce callback qu'on définit les actions qui seront traitées et le code associé. Ici, on traitera les deux actions permettant de gérer le stock de produits dans le rayon FILL_STOCK et EMPTY_STOCK. L'instruction console.log est ajoutée à des fins pédagogiques, pour illustrer le fonctionnement global du flux de données.

import Constants from '../constants';
import { Store } from 'flux/utils';
import { remove } from 'lodash';
const products = [];

export default class BasketStore extends Store {
  getState() {
    return products;
  }

  __onDispatch(actionPayload) {
    console.log('BasketStore', actionPayload);
    if (actionPayload.type === Constants.ADD_TO_BASKET) {
      const product = products.find(item => item.id === actionPayload.payload.id);
      if (product) {
        // already in basket
        product.quantity += 1;
      } else {
        // new in basket
        const newProduct = actionPayload.payload;
        newProduct.quantity = 1;
        products.push(newProduct);
      }
      this.__emitChange();
    } else if (actionPayload.type === Constants.REMOVE_FROM_BASKET) {
      const product = products.find(item => item.id === actionPayload.payload.id);
      if (product.quantity > 1) {
        product.quantity -= 1;
      } else {
        // delete from basket
        remove(products, item => item.id === product.id);
      }
      this.__emitChange();
    }
  }
}

BasketStore, en revanche, est construit en tirant parti des flux utils et hérite de la classe Store. Comme décrit dans la documentation de flux utils, on passe en paramètre l'instance du dispatcher en paramètre du constructeur, ce qui permet de déléguer la partie technique à la classe Store. Il nous suffit simplement de fournir l'implémentation du callback enregistré auprès du Dispatcher, ici en surchargeant la méthode onDispatch et en appelant emitChange pour déclencher l'événement.

Ce store gère les actions liées au panier. On a donc le code qui traite ADD_TO_BASKET et REMOVE_FROM_BASKET.
Si besoin, les flux utils proposent d'autres implémentations de stores en fonction du besoin au travers des classes ReduceStore et MapStore.

Je décrirai uniquement les vues en interaction directe avec les autres composants de l'architecture flux.
Commençons par les composants React qui déclenchent les actions :

import React from 'react';
import Product from './product';
import ItemProduct from './itemProduct';
import BasketAction from '../actions/basketAction';
import StockAction from '../actions/stockAction';
import { cloneDeep } from 'lodash';

export default class Shelf extends React.Component {

  triggerActions(product) {
    StockAction.decreaseStock(product);
    BasketAction.addProduct(product);
  }

  render() {
    const products = this.props.products.map(
      (product, index) =>
        <ItemProduct key={index} onAdd={this.triggerActions.bind(this, cloneDeep(product))}>
          <Product product={product} withStock={true} />
        </ItemProduct>
    );
    if (!products.length) {
      return null;
    }
    return (
      <div className="shelf col-lg-6">
        <h2>Product list</h2>
        {products}
      </div>
    );
  }
}

Shelf.propTypes = {
  products: React.PropTypes.arrayOf(React.PropTypes.object).isRequired,
};

import React from 'react';
import Product from './product';
import BasketProduct from './basketProduct';
import BasketAction from '../actions/basketAction';
import StockAction from '../actions/stockAction';
import { cloneDeep } from 'lodash';

export default class Basket extends React.Component {

  triggerActions(product) {
    BasketAction.removeProduct(product);
    StockAction.increaseStock(product);
  }

  render() {
    const products = this.props.products.map(
      (product, index) =>
        // cloneDeep to have a separate instance of product in emitted action
        <BasketProduct key={index} onDelete={this.triggerActions.bind(this, cloneDeep(product))}>
          <Product product={product} />
        </BasketProduct>
    );
    if (!products.length) {
      return null;
    }
    return (
      <div className="basket col-lg-6">
        <h2>My basket</h2>
        {products}
      </div>
    );
  }
}

Basket.propTypes = {
  products: React.PropTypes.arrayOf(React.PropTypes.object).isRequired,
};

La gestion des actions est très simple : on ajoute l'import et on déclenche l'action sur les événements natifs du DOM (onChange, onClick, etc.). Ici, lorsqu'on cliquera sur le bouton « add », on déclenchera les actions ADD_TO_BASKET pour ajouter le produit au panier et EMPTY_STOCK pour enlever un item du stock de produits via les méthodes addProduct et addProduct. On procède exactement de la même manière dans le fichier basket.js pour les actions REMOVE_FROM_BASKET et FILL_STOCK.

Passons aux vues qui sont en interaction avec les stores. En fait, les stores gérant les states au sens flux, il est logique que les interactions se passent avec les vues possédant le state au sens React :

import React from 'react';
import ShelfStore from '../stores/ShelfStore';
import Shelf from './Shelf';

export default class ShelfContainer extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      products: ShelfStore.getState(),
    };
  }

  componentDidMount() {
    ShelfStore.addChangeListener(this.onChange.bind(this));
  }

  componentWillUnmount() {
    ShelfStore.removeChangeListener(this.onChange.bind(this));
  }

  onChange() {
    this.setState({
      products: ShelfStore.getState(),
    });
  }

  render() {
    return <Shelf products={this.state.products} />;
  }
}

import React from 'react';
import Dispatcher from '../dispatcher/fluxAppDispatcher';
import BasketStore from '../stores/basketStore';
import Basket from './basket';

export default class BasketContainer extends React.Component {
  constructor(props) {
    super(props);
    this.store = new BasketStore(Dispatcher);
    this.state = {
      products: this.store.getState(),
    };
  }

  componentDidMount() {
    this.listener = this.store.addListener(this.onChange.bind(this));
  }

  componentWillUnmount() {
    this.listener.remove();
  }

  onChange() {
    this.setState({
      products: this.store.getState(),
    });
  }

  render() {
    return <Basket products={this.state.products} />;
  }
}

On retrouve, dans ces deux composants racines, la différence d'implémentation au niveau des stores, notamment au niveau des méthodes d'ajouts et suppressions en tant que listener.

On propose également ici d'avoir deux modèles : on importe l'instance du store (ShelfStore) ou bien la classe que l'on instancie dans le constructeur de la vue (BasketStore).
Ces composants React sont en fait les fameux controller-views évoqués sur le schéma du paragraphe suivant.

Voici un autre angle moins détaillé que le premier schéma pour appréhender flux :

Je ne paraphraserai pas la description faite précédemment. J'insisterai juste sur le fait qu'il n'y a qu'une seule instance du dispatcher dans cette architecture et que les stores sont notifiés de toutes les actions. Le code de cet article inclut des logs pour mettre en exergue ce point. Par ailleurs, j'invite le lecteur à manipuler un PoC disponible sur le github prévu à cet effet.