q.javascript.txt

                                  ┏━━━━━━━┓
                                  ┃   Q   ┃
                                  ┗━━━━━━━┛

ALTERNATIVES ==>                  #See Bluebird

VERSION ==>                       #Node module (1.0.1)
                                 ##Differences with 2.0 are marked like this (many breaks)
                                  #Used for promises/deferred:
                                  #  - it is a series of chains of callbacks fired sequentially ("resolved"):
                                  #     - callbacks defined in a syntactic chain are fired together, other chains are fired
                                  #       in parallel, e.g. PROMISE.then(FUNC1a).then(FUNC2a); PROMISE.then(FUNC3a): FUNC1a
                                  #       and FUNC3a are fired together, then FUNC2a.
                                  #     - once the chain has been fully resolved (meaning either accepted|rejected), the chain
                                  #       can't be used. This is not the case for notifications.
                                  #     - "next resolution": when a chain depends the resolution of another chain (state and
                                  #       state value), it is always depending only of the next chain part resolution, not the
                                  #       full resolution.
                                  #       But if other chain is already fully resolved, take its final state.
                                  #  - each part of the chain is:
                                  #     - either a FUNC1, a FUNC2 or a FUNC3 according to the "state": accepted, rejected or
                                  #       notified
                                 ##     - FUNC3 are deprecated
                                  #     - associated with a state value (argument to FUNC)
                                  #  - the next state and state value depend on the current part FUNC:
                                  #     - when returning a VAL, state is accepted with VAL for FUNC1|2 and notified with VAL
                                  #       with FUNC3
                                  #       If nothing is returned nor thrown, it is like returning undefined
                                  #     - when throwing a VAL, state is rejected with VAL for FUNC1|2.
                                  #       However, for FUNC3, exceptions are just propagated.
                                  #     - when returning a PROMISE, chain stops, and is resolved with same state and state
                                  #       value as PROMISE "next resolution". The two chains then go their own ways.
                                  #     - default FUNC (when null|undefined) passes the same state and state value to the next
                                  #       part of the chain
                                  #  - Promises are a subpart of deferred:
                                  #     - deferred deal with firing the state, promise to register callbacks.
                                  #     - only promises are usually given to clients, encapsulating deferreds.
                                  #Async:
                                  #  - Callbacks are async., i.e. always return after end of current stack.
                                  #    This means it's possible to register callbacks after triggering a callback chain,
                                  #    if it's in the same code.
                                  #  - Goal: in async. code, cleaner than using callbacks and try/catch blocks.
                                  #Error handling:
                                  #  - throwing an exception does not propagate it in a FUNC1|2 (but does in a FUNC3). Instead
                                  #    it rejects the state with the exception as state value.
                                  #  - however, the last part of the chain should not silent exception: use PROMISE.done() here
                                  #  - exceptions propagated from PROMISE.done() can be caught with Q.onerror = FUNC(ERROR)

IN A NUTSHELL ==>                 #Basics:
                                  #  - Q.defer().resolve|reject|notify(VAL)
                                  #  - PROMISE.then(3 FUNC)....done([3 FUNC])
                                  #  - Q.all(PROMISE_ARR).spread(3 FUNC)
                                  #  - PROMISE.delay|timeout(NUM)
                                  #Converting (most of them deprecated):
                                  #  - SYNCFUNC -> PROMISE:  Q.fcall(FUNC(ARGS...), ARGS...) or Q.call(STR, OBJ, ARGS...)
                                  #  - ASYNCFUNC -> PROMISE: Q.nbind(FUNC)(VAL) instead of FUNC(VAL, ASYNCFUNC(ERROR,VAL))
                                  #  - PROMISE -> ASYNCFUNC: DEFERRED.makeNodeResolver()
                                  #  - PROMISE -> ASYNCFUNC+PROMISE: PROMISE.nodeify(FUNC(ERROR,VAL))

Q.defer()                         #Returns a DEFERRED
DEFERED.resolve|reject|notify(VAL)#resolve|reject() (not notify) can't be called again after fired once.
                                  #Using resolve(PROMISE) resolve|reject DEFERRED according to PROMISE "next resolution".
DEFERRED.promise                  #PROMISE

Q(VAL)                            #Returns a PROMISE:
                                  #  - if VAL is PROMISE2, use PROMISE2
                                  #  - otherwise, returns a PROMISE accepted directly with VAL
Q.reject(VAL)                     #Same but otherwise, returns a PROMISE rejected directly with VAL
Q.FUNC(VAL, ...)                  #Same as Q(VAL).FUNC(...)
                                  #Exceptions:
                                  #  - for then(), use when(): Q.when(VAL, ...) -> Q(VAL).then(...)
                                  #  - Q.delay(NUM) -> Q(undefined).delay(NUM)

PROMISE.then(FUNC1(VAL)[,FNC2(VAL)#FUNC1 is resolve callback, FUNC2 reject, FUNC3 notify.
[,FNC3(VAL)]])                    #Returns PROMISE.
PROMISE.spread(...)               #Same but:
                                  #  - VAL must be an ARR
                                  #  - ARR -> VAL...
PROMISE.done(...)                 #Same except throwing an error doesn't reject state. Instead exceptions are just propagated.
                                  #Should be used at the end of the chain, to avoid silencing exceptions.
PROMISE["finally"](FUNC())        #Like PROMISE.then(FUNC, FUNC), except FUNC:
                                  #  - doesn't take any state value
                                  #  - passes current state and state value to next member of the chain
                                  #Weird syntax is because it is reserved word in IE8.
PROMISE["catch"](FUNC2(VAL))      #Like PROMISE.then(null, FUNC2(VAL))
PROMISE.progress(FUNC2(VAL))      #Like PROMISE.then(null, null, FUNC3(VAL))

PROMISE.isFulfilled|Rejected|
Pending()                         #
PROMISE.inspect()                 #Returns state and state value as PROMISEOBJ, with members:
                                  #  - state "pending|fulfilled|rejected"
                                  #  - value|reason VAL: only if fulfilled|rejected
Q.isPromise[Alike](VAL)           #

Q.all(PROMISE2_ARR)               #Returns a PROMISE which state is resolved according to all PROMISE2_ARR "next resolutions":
                                  #  - first PROMISE2 rejection rejects PROMISE with same state value
                                  #  - if all PROMISE2 are accepted, PROMISE is accepted with all state values as VAL_ARR
                                  #  - notifications on PROMISE2 notifies PROMISE with { index NUM, value: VAL }, where VAL
                                  #    is the state value and NUM the position in PROMISE2_ARR
Q.allSettled(PROMISE2_ARR)        #Same except is always accepted, with state value OBJ_ARR, where OBJ is PROMISE2.inspect()

PROMISE.fapply([ARGS_ARRAY])      #Same as PROMISE.then(function(FUNC){ return FUNC.apply(null, ARGS); })
                                  #Allows to wrap a sync. FUNC as a PROMISE: Q.fapply(FUNC(ARGS), ARGS) is a PROMISE directly
                                  #firing FUNC(ARGS) and which state depends on FUNC() return value|exception thrown.
                                 ##Deprecated
PROMISE.fcall([ARGS...])          #Same with FUNC.call() instead of FUNC.apply()
                                 ##Deprecated
PROMISE.post(STR[, ARGS_ARRAY])   #
                                 ##Deprecated
PROMISE.call(STR[, ARGS...])      #Same with OBJ[STR]() instead of FUNC()

PROMISE.thenResolve(VAL)          #Same as PROMISE.then(function(){ return VAL; })
PROMISE.thenReject(VAL)           #Same as PROMISE.then(function(){ throw VAL; })
PROMISE.get(STR)                  #Same as PROMISE.then(function(OBJ){ return OBJ[STR]; })
PROMISE.keys()                    #Same as PROMISE.then(function(OBJ){ return Object.keys(OBJ); })

PROMISE.timeout(NUM[, STR])       #Rejects PROMISE with state value STR (déf: "Timeout after NUM ms") if at least the first
                                  #callback has not been fulfilled|rejected after NUM ms
PROMISE.delay(NUM)                #If PROMISE gets fulfilled|rejected, within a NUM ms time window, the resolution gets delayed
                                  #until the end of the time window.

DEFERRED.makeNodeResolver()       #Returns a FUNC(ERROR, VAL):
                                  #  - if fired with ERROR, fire DEFERRED.reject(ERROR)
                                  #  - otherwise, fire DEFERRED.resolve(VAL)
                                  #Use to transform a DEFERRED into a Node.js-style callback.
                                 ##Deprecated
PROMISE.nodeify([FUNC(ERROR,VAL)])#If FUNC is undefined, returns PROMISE.
                                  #Otherwise, will fire FUNC(ERROR) when PROMISE is rejected or FUNC(null,VAL) when PROMISE
                                  #is accepted (with the state value).
                                  #Goal is to create dual Promise/CALLBACK APIs:
                                  #  FUNC(CALLBACK) { return PROMISE.nodeify(CALLBACK) }
                                  #Will return as PROMISE or as CALLBACK depending on whether CALLBACK is supplied.

Q.nbind(FUNC(VAL,                 #Returns FUNC, except that can use as a PROMISE instead of passing a FUNC2():
FUNC2(ERROR, VAL2))[,OBJ,ARGS...])#  Q.nbind(FUNC)(VAL).then(FUNC3(VAL2), FUNC3(ERROR))
                                  #instead of:
                                  #  FUNC(VAL, FUNC2(ERROR, VAL2))
                                  #If OBJ, does a FUNC.bind(OBJ,ARGS) before returning.
                                 ##ARGS: Deprecated
Q.denodeify(FUNC(...)[, ARGS])    #Same as Q.nbind(FUNC(...), null, ARGS)
Q.nfapply(FUNC(...), ARR)         #Same as Q.nbind(FUNC(...)), but directly calls FUNC.apply(null, ARR) afterwards
Q.nfcall(FUNC(...), ARGS...)      #Same but with FUNC.call(null, ARGS...)
Q.npost(OBJ, STR, ARR)            #Same as Q.nfapply|nfcall, but with OBJ[STR]() instead of FUNC(), calling
Q.ninvoke(OBJ, STR, ARGS...)      #FUNC.apply|call(OBJ) afterwards