Async.Promise: Add "chain" function

Vim does not have async/await syntax support thus it's a bit tough work
to write similar function as below (js)

    for (const url of urls) {
        const r = await request(url);
        console.log(r)
    }

With this commit, equivalent code of above can be written as

    let fs = map(urls, { url -> { -> request(url).then({ r -> execute('echo r', '') }) })
    call s:Promise.chain(fs)

Async.Promise: Fix docs of chain

Author: lambdalisue

autoload/vital/__vital__/Async/Promise.vim

@@ -270,6 +270,27 @@ function! s:wait(promise, ...) abort
   endif
 endfunction
 
+function! s:chain(promise_factories) abort
+  return s:_chain(copy(a:promise_factories), [])
+endfunction
+
+function! s:_chain(promise_factories, results) abort
+  if len(a:promise_factories) is# 0
+    return s:resolve(a:results)
+  endif
+  let Factory = remove(a:promise_factories, 0)
+  try
+    return Factory()
+          \.then({ v -> add(a:results, v) })
+          \.then({ -> s:_chain(a:promise_factories, a:results) })
+  catch
+    return s:reject({
+          \ 'exception': v:exception,
+          \ 'throwpoint': v:throwpoint,
+          \})
+  endtry
+endfunction
+
 let s:_on_unhandled_rejection = s:NOOP
 function! s:on_unhandled_rejection(on_unhandled_rejection) abort
   let s:_on_unhandled_rejection = a:on_unhandled_rejection

doc/vital/Async/Promise.txt

@@ -377,6 +377,42 @@ wait({promise}[, {options}])		*Vital.Async.Promise.wait()*
 	call Promise.wait(p, 1000)
 	" Is equivalent to call Promise.wait(p, {'timeout': 1000})
 >
+chain({promise_factories})		*Vital.Async.Promise.chain()*
+	Chain promises produced by {promise_factories} (|List| of |Function|)
+	and return a result |List| which contains result of each produced
+	promises.
+	It is like an asynchronous sequential call. It rejects when one of
+	function in {promise_factories} has failed or produced promises
+	rejects. Note that it stops producing promises by functions after
+	rejection.
+>
+	let fs = [
+	      \ { -> Promise.new({ r -> timer_start(50, { -> r('1') })})},
+	      \ { -> Promise.new({ r -> timer_start(50, { -> r('2') })})},
+	      \ { -> Promise.new({ r -> timer_start(50, { -> r('3') })})},
+	      \]
+	call Promise.chain(fs)
+	" --------1--------2--------3----> RESOLVE
+	"         50ms     100ms    150ms
+
+	let fs = [
+	      \ { -> Promise.new({ r -> timer_start(50, { -> r('1') })})},
+	      \ { -> execute('throw "Error"') },
+	      \ { -> Promise.new({ r -> timer_start(50, { -> r('3') })})},
+	      \]
+	call Promise.chain(fs)
+	" --------1----> REJECT
+	"         50ms
+
+	let fs = [
+	      \ { -> Promise.new({ r -> timer_start(50, { -> r('1') })})},
+	      \ { -> Promise.new({ _, rj -> timer_start(50, { -> rj('2') })})},
+	      \ { -> Promise.new({ r -> timer_start(50, { -> r('3') })})},
+	      \]
+	call Promise.chain(fs)
+	" --------1--------2----> REJECT
+	"         50ms     100ms
+<
 on_unhandled_rejection({callback})	*Vital.Async.Promise.on_unhandled_rejection*
 
  	Set callback to catch all unhandled rejected promise's result.

test/Async/Promise.vimspec

@@ -805,6 +805,66 @@ Describe Async.Promise
     End
   End
 
+  Describe .chain()
+    It returns a promise which resolves to an empty List when an empty factories has specified
+      let l = l:
+      let p = P.chain([]).then({ v -> extend(l, { 'result': v })})
+      call s:wait_has_key(l, 'result')
+      Assert Equals(result, [])
+      Assert Equals(p._state, FULFILLED)
+    End
+
+    It sequentially calls functions in factories and resolves promises
+      let l = l:
+      let fs = [
+            \ { -> P.resolve('Hello') },
+            \ { -> P.resolve('World') },
+            \ { -> P.resolve('Goodbye') },
+            \]
+      let p = P.chain(fs).then({ v -> extend(l, { 'result': v })})
+      call s:wait_has_key(l, 'result')
+      Assert Equals(result, ['Hello', 'World', 'Goodbye'])
+      Assert Equals(p._state, FULFILLED)
+    End
+
+    It sequentially calls functions in factories but reject promises if intermediate function call fails
+      let l = l:
+      call P.on_unhandled_rejection({ result -> extend(l, { 'result': result }) })
+
+      let fs = [
+            \ { -> P.resolve('Hello').then({ -> extend(l, { 'Hello': 1 }) }) },
+            \ { -> execute('throw HOGE') },
+            \ { -> P.resolve('Goodbye').then({ -> extend(l, { 'Goodbye': 1 }) }) },
+            \]
+      let p = P.chain(fs).then({ -> execute('throw "error"') })
+      call s:wait_has_key(l, 'result')
+      Assert HasKey(result, 'exception')
+      Assert HasKey(result, 'throwpoint')
+      Assert Equals(p._state, REJECTED)
+      Assert HasKey(l, 'Hello')
+      Assert KeyNotExists(l, 'Goodbye')
+    End
+
+    It sequentially calls functions in factories but reject promises if intermediate promise reject
+      let l = l:
+      call P.on_unhandled_rejection({ result -> extend(l, { 'result': result }) })
+
+      let fs = [
+            \ { -> P.resolve('Hello').then({ -> extend(l, { 'Hello': 1 }) }) },
+            \ { -> P.resolve('World').then({ -> extend(l, { 'World': 1 }) }).then({ -> P.reject('Wow')}) },
+            \ { -> P.resolve('Goodbye').then({ -> extend(l, { 'Goodbye': 1 }) }) },
+            \]
+      let p = P.chain(fs).then({ -> execute('throw "error"') })
+      call s:wait_has_key(l, 'result')
+      Assert Equals(result, 'Wow')
+      Assert Equals(p._state, REJECTED)
+      Assert HasKey(l, 'Hello')
+      Assert HasKey(l, 'World')
+      Assert KeyNotExists(l, 'Goodbye')
+    End
+
+  End
+
   Describe .on_unhandled_rejection
 
     After each