acdlite/flummox

{"path":"api/flux","content":"`Flux`\n======\n\nCreate Flux containers by extending from the base `Flux` (or `Flummox`) class.\n\n```js\nclass Flux extends Flummox {\n  constructor() {\n    super();\n\n    // Create actions first so our store can reference them in\n    // its constructor\n    this.createActions('messages', MessageActions);\n\n    // Extra arguments are sent to the store's constructor. Here, we're\n    // passing a reference to this Flux instance\n    this.createStore('messages', MessageStore, this);\n  }\n}\n```\n\nEncapsulate your stores and actions\n-------------------------------------\n\nFlummox is designed to be used without singletons. Instead, create a Flux class that encapsulates the creation of all your application's stores and actions, so that you can create new instances on the fly.\n\n```js\nconst flux = new Flux();\n```\n\n(Note that there's nothing technically stopping you from using singletons if you wish, but why would you want to?)\n\n\nDebugging\n---------\n\nLike Stores, Flux instances are EventEmitters. A `dispatch` event is emitted on every dispatch. Listeners are sent the dispatched payload. This can be used during development for debugging.\n\n```js\nflux.addListener('dispatch', payload => {\n  console.log('Dispatch: ', payload);\n});\n```\n\nAdditionally, an `error` event is emitted when errors occur as a result of an async action. This is both for convenience and to prevent error gobbling.\n\nMethods\n-------\n\n### createActions\n\n```js\nActions createActions(string key, function ActionsClass [, ...constructorArgs])\n```\n\nCreates an instance of `ActionsClass` and saves a reference to it. `constructorArgs` are passed to the constructor of `ActionsClass` on creation.\n\n### createStore\n\n```js\nStore createStore(string key, function StoreClass [, ...constructorArgs])\n```\n\nCreates an instance of `StoreClass`, registers the store's handlers with the dispatcher, and saves a reference to it. `constructorArgs` are passed to the constructor of `ActionsClass` on creation.\n\n### getStore\n\n```js\nStore getStore(string key)\n```\n\nGets an store instance by key.\n\n### removeStore\n\n```js\nStore removeStore(string key)\n```\n\nDeletes an instance of `StoreClass`, unregisters the store's handlers from dispatcher, and removes all store listeners.\n\n### getActions\n\n```js\nActions getActions(string key)\n```\n\nGets an actions instance by key.\n\n### getActionIds\n\n```js\nActions getActionIds(string key)\n```\n\nGets action ids for the given actions key. Internally calls `Actions#getActionIds`.\n\nAlso available as `getConstants()`.\n\n### removeActions\n\n```js\nActions removeActions(string key)\n```\n\nDeletes an actions instance by key.\n\nDispatcher methods\n------------------\n\nEvery Flux instance has its own dispatcher. You should try to avoid interacting with the dispatcher directly, but it is available (primarily for testing purposes) as `this.dispatcher`. Some convenience methods are also provided:\n\n### dispatch\n```\ndispatch(string actionId [, * body])\n```\n\nSimilar to the `dispatch()` method of the dispatcher itself, except instead of passing a payload, the payload is constructed for you, in the form:\n\n```js\n{\n  actionId,\n  body\n}\n```\n\nThis is used internally by Flummox: the `actionId` field is used to identify the source action, and `body` contains the value passed to store handlers. In your tests, you can use it to simulate a dispatch to your stores.\n\n### waitFor\n\n```\nwaitFor(Store store)\n```\n\nSimilar to the `waitFor()` method of the dispatcher itself, this can be used within a handler to wait for a different store to respond to the dispatcher before continuing. The operation is synchronous.\n\nInstead of passing a store, you can also pass a dispatcher token, or an array of tokens and stores.\n\nUsing a custom dispatcher\n-------------------------\n\n**tl;dr** Flummox uses the flux dispatcher from Facebook, but you can switch out whatever api compatible dispatcher you want.\n\n***\n\nUsually the dispatcher provided by Facebook is sufficient, but you aren't limited to using it if you find you need more than it provides.  If you want to have custom behavior when dispatching actions, you can provide a wrapper for the Facebook dispatcher that does what you want.  Or use something else entirely.  It's up to you.\n\nTo substitute a different dispatcher object just change the `constructor()` function of your flux object like this:\n\n```js\n\nclass Flux extends Flummox {\n  constructor() {\n    super();\n\n    this.dispatcher = new MyCustomDispatcher();\n  }\n}\n\n```\n\nJust remember, whatever object you provide has to follow the same api as the dispatcher from Facebook.  The easiest way to do that is to extend the Facebook dispatcher in a new class, and then provide whatever alternate or extended functionality you desire.\n\nFor instance, say you want to allow the dispatcher to receive actions for dispatching while it is in the middle of another action dispatch.  The standard dispatcher will complain that you cannot dispatch an action during another action.  There are good reasons for this, but perhaps you just want to queue up that action and have it execute when the current action is completed.  One easy way to do this would be to use `setTimeout()`.  To do this you would provide a dispatcher with slightly different dispatch functionality, like this:\n\n```js\n\nclass MyCustomDispatcher extends Dispatcher {\n  dispatch(...args) {\n    if (!this.isDispatching()) {\n      super.dispatch(...args); // This will execute the Facebook dispatcher's dispatch function.\n    } else {\n      setTimeout(() => { // We are currently dispatching, so delay this action using setTimeout\n        super.dispatch(...args);\n      }, 0);\n    }\n  }\n}\n\n```\n\nSerialization/deserialization\n-------------------------------\n\nIf you're building an isomorphic application, it's often a good idea pass the initial state of your application from the server to the client to avoid unecessary/duplicate HTTP requests. This is easy with Flux, since all of your application state is located in your stores.\n\nThis feature is opt-in on a store-by-store basis, and requires some additional set-up.\n\n### serialize\n\n```\nstring serialize()\n```\n\nReturns a serialized string describing the entire state of your Flux application.\n\nInternally, it passes each store's current state to the store's static method `Store.serialize()`. The return value must be a string representing the given state. If a store does not have a static method `serialize()`, or if it returns a non-string, it is ignored.\n\n### deserialize\n\n```\ndeserialize(string stateString)\n```\n\nConverts a serialized state string (as returned from `Flux#serialize()`) to application state and updates the stores.\n\nInternally, it passes the state string for each store (as returned from `Store.serialize()`) to the store's static method `Store.deserialize()`. The return value must be a state object. It will be passed to `Store#replaceState()`. If a store does not have a static method `deserialize()`, it is ignored.\n"}