API reference

Wiki ▸ API reference

Create a new instance with var state = new Statesman( data ), where data (optional) represents your initial state.

Instance methods

state.set( keypath, value[, options ] )

Update part of the model, notifying any affected observers. If value is an object or an array, observers will be notified regardless of whether anything has actually changed. Returns this

• keypath string
  the location of the value to change
• value
  the value to change it to
• options
  • silent don't notify observers
  • force notify observers even if the value is the same (has no effect if silent is true)

state.set( map[, options ] )

Update multiple values simultaneously. Individual observers will only be notified once, even if the effect of multiple equivalent calls to state.set( keypath, value ) would have been multiple notifications. Returns this

• map
  an object mapping keypaths to values
• options
  as above

---

state.get( [ keypath ] )

Returns the value of keypath, if specified, or the model in its entirety if not.

• keypath string
  the location of the value to retrieve

---

state.observe( keypath, callback[, options ] )

Binds a callback to changes in the value of keypath, whether as a direct result of state.set( keypath, value ) or indirectly due to an ancestor or descendant being updated. Returns an array of observers

• keypath string
  the part of the model to observe
• callback function ( newValue, oldValue )
  the function called when keypath changes. In the case of objects and arrays, the arguments newValue and oldValue are identical
• options object
  • init Defaults to true. Whether or not to call the callback immediately. oldValue will be undefined if so
  • context The context that callbacks will called in. Defaults to state (or subset, if this is a subset)

---

state.observeOnce( keypath, callback[, options ] )

Binds a callback that will execute once, when the value of keypath first changes, then detach itself. Returns an array of observers

• keypath string
  the part of the model to observe
• callback function ( newValue, oldValue )
  the function called when keypath changes. In the case of objects and arrays, the arguments newValue and oldValue are identical
• options object
  • context The context the callback will be called in, as above

---

state.unobserve( observers )

Cancels the specified observers. Returns this

• observers array the observers, previously returned from state.observe( keypath, callback ) or state.observeOnce( keypath, callback ), to detach

---

state.compute( keypath, options )

Creates a computed value, which resides at keypath. Returns the current value.

• keypath string
  The location at which to store the computed value
• options
  • fn function ( triggerValue1, triggerValue2 ... triggerValueN )
    the function to calculate the value. Should not have side-effects. Receives the current values of any specified triggers, in the order in which they were specified
  • trigger / triggers string / array
    a string, or array of strings, of keypaths that affect the value. When they change, the value is recomputed, and observers of the computed value are notified
  • cache boolean
    defaults to true. If set to false, the value will be recomputed for each state.get( keypath ), otherwise it will be computed and cached when the triggers change. (Note: if there are no triggers, the value will never be cached)
  • readonly boolean defaults to true. If set to false, the value can be overridden with state.set( keypath, value ). It will revert the next time its triggers, if any, are changed
  • context
    defaults to state (or subset, as applicable)

---

state.removeComputedValue( keypath )

Stops computing the value of keypath and removes its trigger observers.

• keypath string
  The computed value to remove