Repository files navigation

A human-friendly standard for Flux action objects. Feedback welcome.

It's much easier to work with Flux actions if we can make certain assumptions about their shape. For example, essentially all Flux actions have an identifier field, such astype,actionType, oractionId. Many Flux implementations also include a way for actions to indicate success or failure, especially as the result of a data-fetching operation. Defining a minimal, common standard for these patterns enables the creation of useful tools and abstractions.

Flux actions can be thought of as an asynchronous sequence of values. It is important for asynchronous sequences to deal with errors. Currently, many Flux implementations don't do this, and instead define separate action types likeLOAD_SUCCESS andLOAD_FAILURE. This is less than ideal, because it overloads two separate concerns: disambiguating actions of a certain type from the "global" action sequence, and indicating whether or not an action represents an error. FSA treats errors as a first class concept.

• Human-friendly. FSA actions should be easy to read and write by humans.
• Useful. FSA actions should enable the creation of useful tools and abstractions.
• Simple. FSA should be simple, straightforward, and flexible in its design.

A basic Flux Standard Action:

{type:'ADD_TODO',payload:{text:'Do something.'}}

An FSA that represents an error, analogous to a rejected Promise:

{type:'ADD_TODO',payload:newError(),error:true}

An action MUST

• be a plain JavaScript object.
• have atype property.

An action MAY

• have anerror property.
• have apayload property.
• have ameta property.

An action MUST NOT include properties other thantype,payload,error, andmeta.

Thetype of an action identifies to the consumer the nature of the action that has occurred.type is a string constant. If two types are the same, they MUST be strictly equivalent (using===).

The optionalpayload property MAY be any type of value. It represents the payload of the action. Any information about the action that is not thetype or status of the action should be part of thepayload field.

By convention, iferror istrue, thepayload SHOULD be an error object. This is akin to rejecting a promise with an error object.

The optionalerror property MAY be set totrue if the action represents an error.

An action whoseerror is true is analogous to a rejected Promise. By convention, thepayload SHOULD be an error object.

Iferror has any other value besidestrue, includingundefined andnull, the action MUST NOT be interpreted as an error.

The optionalmeta property MAY be any type of value. It is intended for any extra information that is not part of the payload.

The moduleflux-standard-action is available on npm. It exports a few utility functions.

import{isFSA}from'flux-standard-action';

Returns true ifaction is FSA compliant.

import{isError}from'flux-standard-action';

Returns true ifaction represents an error.

• redux-actions - a set of helpers for creating and handling FSA actions in Redux.
• redux-promise - Redux promise middleware that supports FSA actions.
• redux-rx - RxJS utilities for Redux, including a middleware that supports FSA actions.