ezFlux

ezFlux is a simple, tiny and focused flux implementation.

At its center is the application state, guarded by one or more stores.
A store implements a minimal event emitter that may be subscribed to.
Stores may be nested, seamlessly reporting children changing.

The resulting benefits are immense:

• minimal file size: 1kb gzipped, no dependencies
• minimal brain load: no reducers, no dispatchers
• minimal boiler plate: no unnecessary ceremony

With improved run time, design time and decreased package size, ezFlux turns state management into a truely elegant, easy and fun experience!

• Install
• Usage
  • Getting Started
  • Mutable Store
  • Computed State
  • Store Methods
  • Store Nesting
• Using Plugins
• API Documentation
  • createStore
  • plugins
• Contributing

Install

NPM:

$ npm install ez-flux --save

Yarn:

$ yarn add ez-flux

Usage

Getting Started

A store saveguards a given state with getters/setter.
If a new value is assigned to the store, it will emit a change event. Stores are sealed by default - thus, adding new keys after creation, is not permitted.

import { createStore } from 'ez-flux';

const user = createStore({
  state: { name: 'John Doe' },
});

user.$on('change', () => console.log(user.name));

user.$assign({ name: 'Jane Doe'});

// console outs 'Jane Doe';

Mutable Store

Direct value assignment may be activated with the mutable option.
This works great in small encapsulations, where maintainability is of little concern.

import { createStore } from 'ez-flux';

const user = createStore({
  state: { name: 'John Doe' },
  mutable: true,
});

user.$on('change', () => console.log(user.name));

user.name = 'Jane Doe';

// console outs 'Jane Doe';

Computed State

Getters and/or setters may be defined directly.

import { createStore } from 'ez-flux';

const user = createStore({
  state: {
    firstName: 'John',
    lastName: 'Doe'
  },
  computed: {
    name: {
      get() {
        return `${this.firstName} ${this.lastName}`;
      },
      set(name) {
        const [firstName, lastName] = name.split(' ');

        this.$assign({ firstName, lastName });
      },
    },
  },
});

user.$on('change', () => console.log(user.name));

user.$assign({ name: 'Jane Doe' });

// console outs 'Jane Doe';

Store Methods

While methods do seem alot like actions, there is no obligation to use $assign within them.

import { createStore } from 'ez-flux';

const user = createStore({
  state: {
    name: 'John Doe',
  },
  methods: {
    safelySetName(name) {
      if (typeof name === 'string') this.$assign({ name });
    },
  },
});

user.$on('change', () => console.log(user.name));

user.safelySetName('Jane Doe');

// console outs 'Jane Doe';

Store Nesting

Stores may be nested useing the children option.
If a child changes, both the child and the parent will emit a change.
If the parent changes, only it will emit a change.

import { createStore } from 'ez-flux';

const user = createStore({
  state: { name: 'John Doe' },
});
const session = createStore({
  state: { sessionId: 0 },
  children: { user },
});

session.$on('change', () => console.log('session changed'));
user.$on('change', () => console.log('user changed'));

session.$assign({ sessionId: 1 });

// console outs 'session changed'

// You may access the user store through session as well
session.user.$assign({ name: 'Jane Doe' });

// console outs 'user changed'
// console outs 'session changed'

Please note that a store's children will be impacted by methods called on the parent:

• parent.$assign: will call $assign on any child that is mentionend in the object assigned to the parent.
• parent.$copy: will invoke $copy on all children in order to return a full copy.
  Attention: It will not deep clone any other nested states.
• parent.$reset: will invoke $reset on all children.

Plugins and Addons

Plugins

Plugins are an array of functions which is directly exported for you to edit.
They will be looped and executed after options have been handled and before store and state are sealed.
As a result, plugins may extend or limit the scope of the created store.

debug

The debug plugin is created by passing a callback to createDebugger.

import { plugins } from 'ez-flux';
import { createDebugger } from 'ez-flux/plugins/debug';

const debug = createDebugger(payload => console.log(payload));

plugins.push(debug);

Now, the given callback will be called on specific interactions:

type DebugPayload = {
  eventType: 'state change' | 'child change' | 'method called',
  storeName: string,
  childName?: string,
  methodName?: string,
  store: Store,
  state: Object,
};

Addons

ezReact

Useful if you wish to use ezFlux with React, Inferno, Preact or any other react-compatible library:

API Documentation

createStore

The store save-guards the state which consists of state-option and computed-option.
In addition to its own API and the state keys, a store will hold all keys from the methods-option and children-option on the top level.

parameters

• StoreOptions

    type StoreOptions = {
      state?: Object,
      computed?: { [string]: { get?: Function, set?: Function } },
      methods?: { [string]: Function },
      children?: { [string]: Store },
      mutable?: boolen,
      afterCreation: Function,
    };

returns

• Store

    type Store = {
      $assign: (Object, ...args: Object[]) => Store,
      $copy: () => Object,
      $keys: () => string[],
      $values: () => any[],
      $entries: () => [string, any][],
      $reset: () => Store,
      $on: (eventName: string, eventListener: Function) => Store,
      $once: (eventName: string, eventListener: Function) => Store,
      $off: (eventName: string, eventListener: Function) => Store,
      $emit: (name: string, ...payload?: any[]) => Store,
    };

Plugins

The Plugins array is exported for direct manipulation.

type Plugin = (State, Store, Options) => void;
type Plugins = Plugin[];

Contributing

Contributions of any kind are always welcome!

To run Linter, Flow, Bable and Mocha and have them watch src and test folders respectively:

$ npm start

To run Babel once:

$ npm run build

To autofix eslint issues

$ npm eslint:fix