    import Store from 'f.lux/src/Store.js'

public class | source

# 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. The`transients`property is a <span><a href="class/src/TransientProperty.js~TransientShadow.html">TransientShadow</a></span> exposes a`Map` 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.

#### See:

- TransientManager
- Store#transients
- TransientsProperty
- TransientProperty

## 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

#### See:

- Logger

## 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.

#### See:

- Store.setPromise
- Store.setTick
- Store.getPromise
- Store.clearInterval
- Store.clearTimeout
- Store.setInterval
- Store.setTimeout
- Store.all
- Store.promise
- Store.reject
- Store.resolve

## Static Method Summary

Static Public Methods
public static | all(promises: *): * |
public static | clearInterval(intervalId: *): * |
public static | clearTimeout(timerId: *): * |
public static | getPromise(): * |
public static | promise(callback: *): * |
public static | reject(error: *): * |
public static | resolve(params: ...*): * |
public static | setInterval(callback: *, time: *, params: ...*): * |
public static | setPromise(promise: *) |
public static | setTick(ticker: *) |
public static | setTimeout(callback: *, time: *, params: ...*): * |

## Constructor Summary

Public Constructor
public | constructor(root: Property, state: Object | Array, useTransients: boolean) Creates a new f.lux store for managing the application state. |

## Member Summary

Public Members
public get | root: Property: * Gets the top-level `Property` used for shadowing the application state. |
public get | rootImpl: ShadowImpl: * Gets the ShadowImpl backing the Store#shadow. |
public get | shadow: Shadow: * Gets the current f.lux shadow state. |
public get | state: Object | Array: * Gets the current, actual application state. |
public get | transients: TransientsShadow: * Gets the `transients` objects |

## Method Summary

Public Methods
public | addListener(listener: Object) Adds a listener object to monitor state changes. |
public | changeState(state: Object | Array, newRoot: boolean, time: number) Set a new value for the application state. |
public | dispatchUpdate(action: function(time: number)) Schedules an action to update the application state. |
public | findByPath(path: Array): Shadow Gets the shadow state property based on array of property keys. |
public | isScheduled(): boolean Gets if an update action has been registered with the store. |
public | isolated(): * |
public | removeListener(listener: *) Removes a listener object from monitoring state changes. |
public | schedule() Schedules pending tasks to execute. |
public | setRootProperty(root: Property, state: Object | Array) Changes the top-level `Property` and application state. |
public | subscribe(callback: function(store: Store, shadow: Shadow, prevShadow: Shadow)) Adds a callback to be invoked after each application state change. |
public | unsubscribe(callback: *) Removes a callback to be invoked after each state change. |
public | updateNow(syncExec: function()) Executes all pending updates and waitFor() requests synchronously (immediately) and then invokes an optional callback once the shadow state is updated. |
public | waitFor(callback: function()) Registers a one-time no argument callback to be invoked after the next state change. |
public | waitThen(): Promise Returns a `Promise` that is resolved following the next state change. |

## Static Public Methods

### public static all(promises: *): * source

#### Params:

Name | Type | Attribute | Description
promises | * |  |

#### Return:

*

### public static clearInterval(intervalId: *): * source

#### Params:

Name | Type | Attribute | Description
intervalId | * |  |

#### Return:

*

### public static clearTimeout(timerId: *): * source

#### Params:

Name | Type | Attribute | Description
timerId | * |  |

#### Return:

*

### public static getPromise(): * source

#### Return:

*

### public static promise(callback: *): * source

#### Params:

Name | Type | Attribute | Description
callback | * |  |

#### Return:

*

### public static reject(error: *): * source

#### Params:

Name | Type | Attribute | Description
error | * |  |

#### Return:

*

### public static resolve(params: ...*): * source

#### Params:

Name | Type | Attribute | Description
params | ...* |  |

#### Return:

*

### public static setInterval(callback: *, time: *, params: ...*): * source

#### Params:

Name | Type | Attribute | Description
callback | * |  |
time | * |  |
params | ...* |  |

#### Return:

*

### public static setPromise(promise: *) source

#### Params:

Name | Type | Attribute | Description
promise | * |  |

### public static setTick(ticker: *) source

#### Params:

Name | Type | Attribute | Description
ticker | * |  |

### public static setTimeout(callback: *, time: *, params: ...*): * source

#### Params:

Name | Type | Attribute | Description
callback | * |  |
time | * |  |
params | ...* |  |

#### Return:

*

## Public Constructors

### public constructor(root: Property, state: Object | Array, useTransients: boolean) source

Creates a new f.lux store for managing the application state.

#### Params:

Name | Type | Attribute | Description
root | Property |  | the top-level `Property` used to shadow the application state

state

Object | Array

- optional
- default: root.initialState()

the initial application state

useTransients

boolean

- optional
- default: false

`true` to enable transient state

## Public Members

### public get root: Property: * source

Gets the top-level `Property` used for shadowing the application state.

#### Return:

Property

#### See:

- Store#state

### public get rootImpl: ShadowImpl: * source

Gets the ShadowImpl backing the Store#shadow.

#### Return:

ShadowImpl

### public get shadow: Shadow: * source

Gets the current f.lux shadow state.

#### Return:

Shadow

### public get state: Object | Array: * source

Gets the current, actual application state.

#### Return:

Object | Array

### public get transients: TransientsShadow: * source

Gets the `transients` objects

#### Return:

TransientsShadow

## Public Methods

### public addListener(listener: Object) source

Adds a listener object to monitor state changes. A `listener` 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

#### Params:

Name | Type | Attribute | Description
listener | Object |  | object with methods to be invoked on state changes.

#### See:

- Logger

### public changeState(state: Object | Array, newRoot: boolean, time: number) source

Set a new value for the application state. This will totally replace the current state and trigger a reshadowing. The root `Property` instance will be reused.

This method is used by Logger to implement time travel debugging.

#### Params:

Name | Type | Attribute | Description
state | Object | Array |  | the new application state

newRoot

boolean

- optional
- default: false

`true` if the state object represents an entirely new state. `false` implies the root object is the same but child properties have been updated.

time

number

- optional
- default: tick()

the f.lux time for the change.

### public dispatchUpdate(action: function(time: number)) source

Schedules an action to update the application state. This method is utilized by root ShadowImpl to trigger the reshadow process and custom properties, listeners, and application logic should never need to explicitly invoke it.

#### Params:

Name | Type | Attribute | Description
action | function(time: number) |  | the callback will normally trigger a reshadow.

#### Throw:

Error | f.lux store already scheduled to perform an update.

### public findByPath(path: Array): Shadow source

Gets the shadow state property based on array of property keys.

#### Params:

Name | Type | Attribute | Description
path | Array |  | array of property keys from the root to the desired property.

#### Return:

Shadow | the shadow state property if property exists.

### public isScheduled(): boolean source

Gets if an update action has been registered with the store.

#### Return:

boolean

### public isolated(): * source

#### Return:

*

### public removeListener(listener: *) source

Removes a listener object from monitoring state changes.

#### Params:

Name | Type | Attribute | Description
listener | * |  |

### public schedule() source

Schedules pending tasks to execute. This method should not need to be called by code external to the class.

### public setRootProperty(root: Property, state: Object | Array) source

Changes the top-level `Property` and application state.

#### Params:

Name | Type | Attribute | Description
root | Property |  | the top-level `Property` used to shadow the application state

state

Object | Array

- optional
- default: root.initialState()

the initial application state

### public subscribe(callback: function(store: Store, shadow: Shadow, prevShadow: Shadow)) source

Adds a callback to be invoked after each application state change. The `callback` has the form:

    callback(store, shadow, prevShadow)

#### Params:

Name | Type | Attribute | Description
callback | function(store: Store, shadow: Shadow, prevShadow: Shadow) |  | called after each state update

### public unsubscribe(callback: *) source

Removes a callback to be invoked after each state change.

#### Params:

Name | Type | Attribute | Description
callback | * |  |

### public updateNow(syncExec: function()) source

Executes all pending updates and waitFor() requests synchronously (immediately) and then invokes an optional callback once the shadow state is updated.

This method is useful when custom properties change the shadow state and need these changes to be reflected before performing additional processing.

#### Params:

Name | Type | Attribute | Description
syncExec | function() |  | a callback to be invoked after all pending changes have been reflected in the shadow state.

### public waitFor(callback: function()) source

Registers a one-time no argument callback to be invoked after the next state change.

#### Params:

Name | Type | Attribute | Description
callback | function() |  | a callback to be invoked after all pending changes have been reflected in the shadow state.

### public waitThen(): Promise source

Returns a `Promise` that is resolved following the next state change.

#### Return:

Promise