Store

A f.lux based application uses a single store for managing all state. A Store instance is created by specifying a root Property and the initial state. The property must be a Property subclass and the state a json compatible value of appropriate type for the root Property. The store manages changes to the state through the shadow state. The shadow state proxies the actual state and each shadow state property is immutable and modifications to the shadow state, whether through function calls or direct assignment, are reflected asynchronously in the next javascript interpreter 'tick'.

The Store class contains some advanced features useful for implementing complex business logic, loggers, and memory efficient master/detail user interfaces. Most of the time, however, your application will create a f.lux store and utilize the f.lux-react module for accessing the store's shadow state properties.

Subscribing to store changes

Entities can subscribe to state changes resulting from actions on the shadow state. Subscription callbacks are registered/unregistered using the methods:

• subscribe(callback) - adds a callback to the subscriber list
• unsubscribe(callback) - removes a callback from the subscriber list

The callback has the form:

callback(store, shadow, prevShadow)

Update and wait

Shadow state action changes to the actual state occur asynchronously. Usually, this works out well since your event and network processing will want to work with a single, consistent state. Certain situations occur where your code performs some actions on the shadow state and then needs to perform additional calculations/changes on the updated state. The f.lux store exposes several methods to make this process easy:

• updateNow(syncExec) - performs any pending actions synchronously and then invokes the syncExec callback which does not take any parameters.
• waitFor(callback) - registers a one-time no argument callback to be invoked after the next state change.
• waitThen() - returns a Promise that will be resolved following the next state change.

Transients

F.lux store's transient objects are used for managing applications data that is used for short periods of time. Transients are expecially useful for implementing master/detail user interfaces. The master list is typically long lived while the detail records are rapidly inspected and discarded.

Transient shadow objects are available through the {@link Store#transients} method. Thetransientsproperty is a <span><a href="class/src/TransientProperty.js~TransientShadow.html">TransientShadow</a></span> exposes aMap` interface for adding, accessing, and removing transient objects.

The transient shadow properties are swept after each state change and non-locked properties are removed from the transients object relieving your code of the responsibility of proactively removing objects when no longer required.

The normal flow of working with a transient is:

1. Create a Property
2. Pick a transient object ID (transId)
3. Obtain Store.transients
4. var trans = transients.set(transId, property) - returns a TransientProperty
5. Do somethings with the transient object: trans.data()
6. trans.lock()
7. `trans.unlock(transId

The f.lux-react module contains the TransientManager class that is useful for managing transient data in a React component.

Listener API

The Store class exposes a listener api for monitoring state changes. The f.lux module ships with one listener called Logger that tracks state changes and provides time travel debugging. A listener is registered/unregsitered using:

• Store#addListener
• Store#removeListener

Where the listener parameter is an object that can implement the following methos:

• onError(msg, error) - an error occurred during a Store operation
• onPreStateUpdate(action, impl) - invoked before a shadow property executes an action
• onPostStateUpdate(action, impl) - invoked after a shadow property executes an action
• onPreUpdate(currState, time) - invoked before the store's state is updated
• onPostUpdate(time, currState, prevState) - invoked after the store's state is updated

Promise and timers

Some environments require special handling for timers, such as React Native. Additionally, developers may desire to utilize specific Promise libraries in order to take advantage of specialized features. The Store class provides methods for setting the timer functions and Promise module to be utilized by f.lux.