Module deferred

A+ promises in Lua.

Functions

new (options) Returns a new promise object.
all (args) Returns a new promise object that is resolved when all promises are resolved/rejected.
map (args, fn) Returns a new promise object that is resolved with the values of sequential application of function fn to each element in the list.
first (args) Returns a new promise object that is resolved as soon as the first of the promises gets resolved/rejected.

Class Promise

Promise:next (cb[, errcb]) Wait for the promise object.
Promise:resolve (value) Resolve promise object with value.
Promise:reject (value) Reject promise object with value.


Functions

new (options)
Returns a new promise object.

Parameters:

  • options

Returns:

    Promise New promise

Usage:

    local deferred = require('deferred')
    
    --
    -- Converting callback-based API into promise-based is very straightforward:
    --
    -- 1) Create promise object
    -- 2) Start your asynchronous action
    -- 3) Resolve promise object whenever action is finished (only first resolution
    --    is accepted, others are ignored)
    -- 4) Reject promise object whenever action is failed (only first rejection is
    --    accepted, others are ignored)
    -- 5) Return promise object letting calling side to add a chain of callbacks to
    --    your asynchronous function
    
    function read(f)
      local d = deferred.new()
      readasync(f, function(contents, err)
          if err == nil then
            d:resolve(contents)
          else
            d:reject(err)
          end
      end)
      return d
    end
    
    -- You can now use read() like this:
    read('file.txt'):next(function(s)
        print('File.txt contents: ', s)
      end, function(err)
        print('Error', err)
    end)
all (args)
Returns a new promise object that is resolved when all promises are resolved/rejected.

Parameters:

  • args list of promise

Returns:

    Promise New promise

Usage:

    deferred.all({
        http.get('http://example.com/first'),
        http.get('http://example.com/second'),
        http.get('http://example.com/third'),
      }):next(function(results)
          -- handle results here (all requests are finished and there has been
          -- no errors)
        end, function(results)
          -- handle errors here (all requests are finished and there has been
          -- at least one error)
      end)
map (args, fn)
Returns a new promise object that is resolved with the values of sequential application of function fn to each element in the list. fn is expected to return promise object.

Parameters:

  • args list of promise
  • fn promise used to resolve the list of promise

Returns:

    a new promise

Usage:

    local items = {'a.txt', 'b.txt', 'c.txt'}
    -- Read 3 files, one by one
    deferred.map(items, read):next(function(files)
        -- here files is an array of file contents for each of the files
      end, function(err)
        -- handle reading error
    end)
first (args)
Returns a new promise object that is resolved as soon as the first of the promises gets resolved/rejected.

Parameters:

  • args list of promise

Returns:

    Promise New promise

Usage:

    -- returns a promise that gets rejected after a certain timeout
    function timeout(sec)
      local d = deferred.new()
      settimeout(function()
          d:reject('Timeout')
        end, sec)
      return d
    end
    
    deferred.first({
        read(somefile), -- resolves promise with contents, or rejects with error
        timeout(5),
      }):next(function(result)
          -- file was read successfully...
        end, function(err)
          -- either timeout or I/O error...
      end)

Class Promise

A promise is an object that can store a value to be retrieved by a future object.
Promise:next (cb[, errcb])
Wait for the promise object.

Parameters:

  • cb function resolve callback (function(value) end)
  • errcb function rejection callback (function(reject_value) end) (optional)

Usage:

    -- Reading two files sequentially:
    read('first.txt'):next(function(s)
    	print('File file:', s)
    	return read('second.txt')
    end):next(function(s)
    	print('Second file:', s)
    end):next(nil, function(err)
    	-- error while reading first or second file
    	print('Error', err)
    end)
Promise:resolve (value)
Resolve promise object with value.

Parameters:

  • value promise value

Returns:

    resolved future result
Promise:reject (value)
Reject promise object with value.

Parameters:

  • value promise value

Returns:

    rejected future result
generated by LDoc 1.4.6 Last updated 2018-02-20 14:54:01