ball-and-chain

ball-and-chain

Chainable API builder with state transition.

Install

npm install --save ball-and-chain

Quick Examples

Chainable = require 'ball-and-chain'

c = new Chainable()

# Config methods/properties for state "foo", which is reachable from
# "ready" or "bar" state
c.config("foo", ['ready', 'bar'])
  .method("a", (next, num) ->
    # `num` is a user argument
    console.log(num)
    # Transit to "bar" state
    next("bar")
    )
  # "bar" state
  .config("bar")
  .property("done", get: (next) ->
    # Call next without a state name will break the chain
    next()
    # Return value will be used instead of this
    return 1
  )
  # Methods/properties that can be called from any states
  .config()
  .method("whatever", (next) ->)
  # Finish config and goto "ready" state
  .finish()

# c is now in `ready` state
# throw error. `done` is in "bar" state, which is not reachable from "ready"
c.done
# OK. `whatever` has no state constraints
c.whatever('dude')
# OK. `a` is in "foo" state, which is reachable from "ready"
# User arguments are pased after `next`
c.a(1)
# Now in "bar" state, done can be called
# Break chain, return 1, back to "ready" state
ret = c.done
# Or chained together
ret = c.whatever('dude').a(1).done
# output "1"
console.log ret

One can also inherit Chainable class

class C extends Chainable
  constructor: ->
    # Call `super` before config
    super()
    @config()
      #...
      .finish()

c = new C()

In JavaScript:

var C = Chainable.extends({
  constructor: function() {
    // super is called internally

    this.config()
      //...
      .finish()
  }
});

var c = new C()

API

config([state], [deps], [handlers])

Configure chainable object.

State	Reachable From	Transits To
'init'	'config'	'config'

Argument	Type	Description
state	string	State name (optional)
deps	Array<string>	State names (optional)
handlers	object	Handlers (optional)

State and deps

A chainable object has internal states. When state is specified, the methods and properties attached with handlers or consequent method/property calls can only be accessible when the chainable object is in that state.

When current state is one of the states in deps (if specified), the chainable object will transit to state first (thus make the methods/properties accessible).

If state and deps are not provided, the methods and properties attached can be accessed all the time.

There are 3 built in states:

init ===this.config()===> config ===this.finish()===> ready

You should make sure one of your state's deps contains 'ready'.

Handlers

handlers is a key-value map that contains methods or properties to be attached. The keys are method/property names and the values are corresponding function body.

handlers =
  name: handler
  # others

There are 2 kinds of handlers:

• method_handler(next, args...)

• prop_handler = {get: getter(next)}

Their this context are binded to the chainable instances.

next([next_state_name: string]) is a callback function for state transition. Any user arguments are passed in order after next.

Normally you won't need to return any thing since the chianable class will return this by default (thus making it chainable). If next is called without the name of next state, the return value of that handler will be used (thus break the chain).

method(name, method_handler)

Attach a method to current state.

State	Reachable From	Transits To
'config'

property(name, prop_handler)

Attach a property to current state.

State	Reachable From	Transits To
'config'

finish()

Finish configuration.

This method must be called after all configuration is done to 'seal' the chianable object to prevent the user from alter it at run-time.

State	Reachable From	Transits To
'config'		'ready'

this.flag(key, [value])

Get/set a flag.

This method is used to store and pass internal state along the call chain.

Argument	Type	Description
key	string	Key
value	object	Value (optional). If specified, sets the value. Otherwise gets the value.

Chinable.extend(proto)

Helper for pure JavaScript usage that creates derived class.