Topics

#async #async-await #eventloop #libuv #lua #luv #neovim #promise

Language breakdown

No language data available.

▸ Files click to expand

README

promise-async

The goal of promise-async is to port [Promise][promise] & [Async][async] from JavaScript to Lua.

A value returned by async function in JavaScript is actually a Promise Object. It's incomplete and

inflexible for using an async function wrapped by bare coroutine without Promise in almost Lua

implementation.

Features
Demonstration

- Script - demo.lua - demo.js

Quickstart

- Requirements - Installation - As a plugin for Neovim platform - As a library from Luarocks

Documentation

- Summary - async

Development

- Neovim tips - Run tests - Improve completion experience - Customize EventLoop

Credit
Feedback
License

Features

API is similar to JavaScript's
Customize EventLoop in any platforms
Support Lua 5.1-5.4 and LuaJIT with an EventLoop module
Support Neovim platform

Demonstration

Script

demo.lua

demo.js

Quickstart

Requirements

Lua 5.1 or latter
Luv

Luv is a default EventLoop for promise-async. It doesn't mean promise-async must require it. In

fact, promise-async require a general EventLoop module which Luv like.

Installation

As a plugin for Neovim platform

Install with Packer.nvim:

As a normal plugin

use {'kevinhwang91/promise-async'}

or

As a Luarocks plugin

use_rocks {'promise-async'}

As a library from Luarocks

luarocks install promise-async
luarocks install luv or implement an EventLoop

interface to adapt your platform

Documentation

promise-async's API is based on [MDN-Promise][promise]. typings/promise.lua is the typings with documentation of Promise class.

Summary

Summary up the API different from JavaScript.

| JavaScript | Lua | | --------------------------------------------------- | ----------------------------------------------- | | new Promise | Promise:new/Promise | | Promise.then | Promise:thenCall, then is language keyword | | Promise.catch | Promise:catch | | Promise.finally | Promise:finally | | Promise.resolve | Promise.resolve | | Promise.reject | Promise.reject | | Promise.all: Symbol.iterator as iterator | Promise.all: pairs as iterator | | Promise.allSettled: Symbol.iterator as iterator | Promise.allSettled: pairs as iterator | | Promise.any: Symbol.iterator as iterator | Promise.any: pairs as iterator | | Promise.race: Symbol.iterator as iterator | Promise.race: pairs as iterator | | async: as keyword at the start of a function | Async/Async.sync: as a surrounding function | | await: as keyword | await/Async.wait as a function |

async

The environment in Async.sync function have been injected some new functions for compatibility or enhancement:

await: A reference of Async.wait function;
pcall: Be compatible with LuaJIT;
xpcall: Be compatible with LuaJIT;

async in JavaScript return Promise object only with single result, but may carry multiple results in Lua. The resolved result of Promise object return by async function will be packed into a table via {...}. However, the result handled by await will be unpacked and return multiple values.

local async = require('async')
local function f()     return 1, 2, 3 end
-- multiple results are packed into resolved result in Promise async(f):thenCall(function(v)     print(v[1], v[2], v[3]) -- output: 1 2 3 end)
-- results returned by await async(function()     local v1, v2, v3 = await(async(f))     print(v1, v2, v3) -- output: 1 2 3 end)
uv.run()

Development

Neovim tips

Promise.resolve():thenCall(cb) is almost equivalent to vim.schedule(cb).

Run tests

make test

Improve completion experience

Following typings/README.md

Customize EventLoop

TODO, refer to loop.lua

Credit

[promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise [async]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function

Feedback

If you get an issue or come up with an awesome idea, don't hesitate to open an issue in github.
If you think this plugin is useful or cool, consider rewarding it a star.

License

The project is licensed under a BSD-3-clause license. See LICENSE file for details.

🔗 More in this category