/ld26

-- Class: Promise

-- This is a way to communicate with an asynchronous function call that

-- is modeled after the Promises/A CommonJS spec <http://wiki.commonjs.org/wiki/Promises/A>.

-- The main difference is that instead of then(), it uses andThen() as the connecting

-- method name, since 'then' is a reserved word in Lua.

--

-- A function that is asynchronous in nature can return a new Promise instance.

-- The caller can then register callbacks via the promise's andThen() method, which

-- are called when the asynchronous operation completes (in the parlance, fulfilling

-- the promise) or fails (rejecting the promise). A promise can have many callbacks attached

-- by repeatedly calling andThen() on the same promise. All callbacks will fire simultaneously.

--

-- If a promise has already failed or been fulfilled, you can still call andThen() on it.

-- If this happens, the callbacks trigger immediately. This may not be what you expect, so

-- beware.

--

-- This implementation is based heavily on RSVP.js <https://github.com/tildeio/rsvp.js>.

 

Promise = Class:extend

{

        -- Property: state

        -- Current state of the promise: may be 'unfulfilled', 'fulfilled', or 'failed'.

        -- This property should be considered read-only. Use resolve() or reject() to change

        -- the state of the promise.

        state = 'unfulfilled',

 

        -- private property: _onFulfills

        -- A table of functions to call when the promise is fulfilled.

        _onFulfills = {},

        

        -- private property: _onFails

        -- A table of functions to call when the promise is rejected.

        _onFails = {},

 

        -- private property: _onProgresses

        -- A function that receives calls periodically as progress is made towards completing

        -- the promise. It's up to whatever asynchronous function that owns the promise to make

        -- these calls; promises do not call this by themselves.

        _onProgresses = {},

 

        -- Method: fulfill

        -- Fulfills the promise, notifying all registered fulfillment handlers (e.g. via <andThen>).

        --

        -- Arguments:

        --              Multiple, will be passed to fulfillment handlers

        --

        -- Returns:

        --              nothing

 

        fulfill = function (self, ...)

                if STRICT then

                        assert(self.state == 'unfulfilled', 'Tried to fulfill a promise whose state is ' .. (self.state or 'nil'))

                end

 

                self.state = 'fulfilled'

                self._fulfilledWith = {...}

 

                for _, func in pairs(self._onFulfills) do

                        func(...)

                end

        end,

        

        -- Method: progress

        -- Notifies all registered progress handlers.

        --

        -- Arguments:

        --              Multiple, will be passed to progress handlers

        --

        -- Returns:

        --              nothing

        

        progress = function (self, ...)

                if STRICT then

                        assert(self.state == 'unfulfilled', 'Tried to send progress on a promise whose state is ' .. (self.state or 'nil'))

                end

 

                for _, func in pairs(self._onProgresses) do

                        func(...)

                end

        end,

 

        -- Method: fail

        -- Fails the promise, notifying all registered failure handlers (e.g. via <andThen>).

        --

        -- Arguments:

        --              errorMessage - error message, will be passed to failure handlers

        --

        -- Returns:

        --              nothing

        

        fail = function (self, errorMessage)

                if STRICT then

                        assert(self.state == 'unfulfilled', 'Attempted to fail a promise whose state is ' .. (self.state or 'nil'))

                end

 

                self.state = 'failed'

                self._failedWith = errorMessage

 

                for _, func in pairs(self._onFails) do

                        func(errorMessage)

                end

        end,

 

        -- Method: andThen

        -- Registers fulfillment, failure, and progress handlers for a promise. This can be called

        -- repeatedly to register several handlers on the same event, and all handlers are optional.

        --

        --

        -- Arguments:

        --              onFulfill - function to call when this promise is fulfiled

        --              onFail - function to call when this promise fails

        --              onProgress - function to call when this promise makes progress

        --

        -- Returns:

        --              A new promise that fulfills or fails after the passed onFulfill or onFail handlers

        --              complete. If either a onFulfill or onFail returns a promise, this new promise will

        --              not fulfill or fail until that returned promise does the same. This way, you can chain

        --              together promises.

 

        andThen = function (self, onFulfill, onFail, onProgress)

                if STRICT then

                        local tFulfill = type(onFulfill)

                        local tFail = type(onFail)

                        local tProgress = type(onProgress)

 

                        assert(tFulfill == 'function' or tFulfill == 'nil', 'Fulfilled handler for promise is ' .. tFulfill ..', not a function')

                        assert(tFail == 'function' or tFail == 'nil', 'Failed handler for promise is ' .. tFail .. ', not a function')

                        assert(tProgress == 'function' or tProgress == 'nil', 'Progress handler for promise is ' .. tProgress ..', not a function')

                end

 

                local childPromise = Promise:new()

 

                -- we add entries, even with nil callbacks, so that

                -- fulfillments and failures propagate up the chain

 

                table.insert(self._onFulfills, function (...)

                        childPromise:_complete(onFulfill, 'fulfill', ...)

                end)

 

                table.insert(self._onFails, function (errorMessage)

                        childPromise:_complete(onFail, 'fail', errorMessage)

                end)

 

                table.insert(self._onProgresses, onProgress)

 

                -- immediately trigger callbacks if we are already fulfilled or failed

 

                if self.state == 'fulfilled' and onFulfill then

                        if self._fulfilledWith then

                                childPromise:_complete(onFulfill, 'fulfill', unpack(self._fulfilledWith))

                        else

                                childPromise:_complete(onFulfill, 'fulfill')

                        end

                end

 

                if self.state == 'failed' and onFail then

                        childPromise:_complete(onFail, 'fail', self._failedWith)

                end

 

                return childPromise

        end,

 

        -- Method: andAlways

        -- A shortcut method that adds both fulfillment and failure handlers

        -- to a promise.

        --

        -- Arguments:

        --              func - function to call when this promise is fulfiled or failed

        --

        -- Returns:

        --              A new promise that fulfills or fails after the handler

        --              complete. If the handler returns a promise, this new promise will

        --              not fulfill or fail until that returned promise does the same.

        --              This way, you can chain together promises.

 

        andAlways = function (self, func)

                return self:andThen(func, func)

        end,

 

        -- internal method: _complete

        -- Handles fulfilling or failing a promise so that chaining works properly,

        -- and that errors are passed to the promise's fail method. 

        --

        -- arguments:

        --              callback - callback to call, can be nil

        --              defaultAction - if unsure as to whether to fulfill or fail, use this

        --              ... - values to pass to the callback

 

        _complete = function (self, callback, defaultAction, ...)

                local results, errorMessage

 

                -- call the callback

 

                if callback then

                        results = { pcall(callback, ...) }

 

                        -- if the call succeeded, peel off that flag

 

                        if results[1] then

                                table.remove(results, 1)

                        else

                                errorMessage = results[2]

                                results = nil

                        end

                end

 

                -- if the callback returned a new promise, we link the current promise to it

 

                if results and type(results[1]) == 'table' and results[1].instanceOf and results[1]:instanceOf(Promise) then

                        results[1]:andThen(function(...) self:fulfill(...) end, function(errorMessage) self:fail(errorMessage) end)

 

                -- if the callback returned a regular value, fulfill the promise

 

                elseif callback and results then

                        if #results > 1 then

                                self:fulfill(unpack(results))

                        else

                                self:fulfill(results[1])

                        end

 

                -- if there was any kind of error, fail

 

                elseif errorMessage then

                        self:fail(errorMessage)

                        error(errorMessage)

 

                -- and if we did not actually have a callback, fall back to the default action

                -- (we have to simulate colon calling syntax here)

 

                else

                        self[defaultAction](self, ...)

                end

        end

}