ldoc

Contents

• Functions
• Class Promise

Modules

• deferred

Module deferred

A+ promises in Lua.

Functions

Class Promise

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

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