NOTE: This package is no longer being maintained. If you are interested in taking over as maintainer or are interested in the npm package name, get in touch by creating an issue. If you are looking for a React state managament library try Redux or MobX (or simply using React state).

Fynx (formerly known as Flox) is an architecture library for React loosely based on the Flux architecture and inspired by Reflux and Fluxxor. If React solves the V of your MVC application, Fynx provides the tools for the M and C.

Install

With NPM

npm install fynx

With Bower

bower install fynx

From source

git clone https://github.com/foss-haas/fynx.git
cd fynx
npm install
npm run dist

Overview

Fynx is loosely based on Flux and shares some of its terminology but differs in several important aspects. Like Flux, Fynx shares the notions of actions and stores, embracing React's unidirectional data flow.

Definitions

Actions are the core building blocks of every Fynx application. Conceptually actions represent the overarching behavior of your application that may alter the global state or involve requests to the server. Actions are listenable functions that emit to Listeners whatever data they are passed and return the processed result.

Stores represent the shared state of an application. Like Actions they are listenable functions that emit their data to Listeners but they retain the data that is written to them and can be read from subsequently. The data contained in stores should generally be treated as immutable, with changes to that data always requiring the store to be updated.

Listeners are ordinary JavaScript functions listening to Stores or Actions. They provide the implementation of the behavior actions represent and allow connecting different stores and actions with each other and the outside world.

The Router resolves URLs to Views relative to the application state. To avoid unnecessary coupling, Fynx does not require the use of any particular router and can easily be used alongside your router of choice, such as react-router. However you may want to give the promise-based Rotunda router a try as it is being developed alongside Fynx.

Views in Fynx are generally assumed to be React components, although nothing about Fynx limits you to using React for your views. Generally views should only contain state directly related to their appearance and propagate changes to the global application state by invoking Actions. It's possible to directly link React components to Fynx stores using mixins (for classic React components) or decorators (for ES2015 class-based React components) but views work best when they have no external dependencies.

API

createAction

Creates an action. Returns a function that will pass its argument to all of its listeners in sequence and return the result.

For a full documentation of this function, see the documentation of axn.

Arguments

• spec: any (optional)

  The axn spec for this action.

Examples

TODO

createActions

Creates an object providing multiple actions. Convenience wrapper around createAction for bulk creation of actions.

Arguments

• specs: Array<string>

  An array of action names to create on the returned object.

  If specs is an object instead, an action will be created for each property with the action name corresponding to the property name and the property value being used as the axn spec for the action.

Examples

TODO

createAsyncAction

Creates an asynchronous action. Returns a function that will pass its argument to all of its listeners in sequence and return a cancellable promise.

Note that React.renderToString is always synchronous so you should not rely on asynchronous actions being executed in your components during server-side rendering.

For a full documentation of this function, see the documentation of axn.async.

Arguments

• spec: any (optional)

  The axn spec for this asynchronous action.

Examples

TODO

createAsyncActions

Creates an object providing multiple asynchronous actions. Convenience wrapper around createAsyncAction for bulk creation of asynchronous actions.

Arguments

• specs: Array<string>

  An array of action names to create on the returned object.

  If specs is an object instead, an asynchronous action will be created for each property with the action name corresponding to the property name and the property value being used as the axn spec for the action.

Examples

TODO

createRawStore

Creates a raw store that can hold any value (other than undefined).

Returns a function with the following behaviour:

• when called without arguments (or undefined), returns the store's content.
• when called with null, resets the store's value to its initial value.
• when called with any other defined value, sets the store's value to that value

Whenever the store's value changes, the store's content will be passed to its listeners.

Arguments

• emptyValue: any (Default: null)

  The store's initial value. Note: the store's value can never be undefined as passing undefined to the store does not modify the store's value.

• prepare: function (optional)

  If provided, values other than null passed into the store will be passed to this function and its return value will be used as the store's new value instead.

• isEmpty: function (Default: Object.is)

  This function will be used to determine whether the store is currently empty. The function is passed exactly two arguments: the store's current value and the store's initial value. A return value that evaluates to the boolean value true indicates that the store should be considered empty.

Examples

TODO

store.listen

Registers a change listener with the store.

Returns a function that will remove the listener from the store when called.

Arguments

• listener: function

  A function that will be invoked whenever the store is written to.

  The listener will receive the store's new value.

• context: any (optional)

  The this context to which the listener will be bound when it is invoked.

Examples

TODO

store.listenOnce

Like store.listen but the listener will be automatically removed the first time it is invoked.

Arguments

• listener: function

  A function that will be invoked the next time the store is written to.

  The listener will receive the store's new value.

• context: any (optional)

  The this context to which the listener will be bound when it is invoked.

Examples

TODO

store.unlisten

Removes a change listener from the store. This has the same effect as calling the function returned by store.listen. If the listener was registered with a context, the same context must be used.

Arguments

• listener: function

  TODO

• context: any (optional)

  TODO

Examples

TODO

store.isEmpty

Returns true if the store's current value is equivalent to its emptyValue or false otherwise. This function takes no arguments.

Examples

TODO

store.isEmpty.listen

Like store.listen but receives a boolean value indicating whether the store is empty (i.e. the result of calling store.isEmpty()) instead of the store's new content.

Arguments

• listener: function

  TODO

• context: any (optional)

  TODO

Examples

TODO

store.isEmpty.listenOnce

Like store.isEmpty.listen but the listener will be automatically removed the first time it is invoked.

Arguments

• listener: function

  TODO

• context: any (optional)

  TODO

Examples

TODO

store.isEmpty.unlisten

Removes a change listener from store.isEmpty. This has the same effect as calling the function returned by store.isEmpty.listen. If the listener was registered with a context, the same context must be used.

Arguments

• listener: function

  TODO

• context: any (optional)

  TODO

Examples

TODO

store.toJSON

Returns a JSON-serializable representation of the store's current value by returning the result of the value's toJSON method if it exists or the value itself otherwise.

Examples

TODO

store.fromJSON

Sets the store's value from a JSON-serializable representation.

Arguments

• value: any

  A JSON-serializable representation of the store's value. By default this value is simply passed to the store itself.

Examples

TODO

createImmutableStore

Creates a store for immutable data. The store behaves identically to a raw store except it automatically converts its value using immutable.fromJS and emptiness checks are always perfor