This module implements types and macros for writing asynchronous code for the JS backend. It provides tools for interaction with JavaScript async API-s and libraries, writing async procedures in Nim and converting callback-based code to promises.
A Nim procedure is asynchronous when it includes the {.async.} pragma. It should always have a Future[T] return type or not have a return type at all. A Future[void] return type is assumed by default.
This is roughly equivalent to the async keyword in JavaScript code.
proc loadGame(name: string): Future[Game] {.async.} = # code
should be equivalent to
async function loadGame(name) {
// code
}
A call to an asynchronous procedure usually needs await to wait for the completion of the Future.
var game = await loadGame(name)
Often, you might work with callback-based API-s. You can wrap them with asynchronous procedures using promises and newPromise:
proc loadGame(name: string): Future[Game] = var promise = newPromise() do (resolve: proc(response: Game)): cbBasedLoadGame(name) do (game: Game): resolve(game) return promise
Forward definitions work properly, you just need to always add the {.async.} pragma:
proc loadGame(name: string): Future[Game] {.async.}
JavaScript compatibility
Nim currently generates async/await JavaScript code which is supported in modern EcmaScript and most modern versions of browsers, Node.js and Electron. If you need to use this module with older versions of JavaScript, you can use a tool that backports the resulting JavaScript code, as babel.
Procs
proc catch[T](future: Future[T]; onReject: OnReject): Future[void]
-
See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch
Example: cmd: -r:off
from std/sugar import `=>` from std/strutils import contains proc fn(n: int): Future[int] {.async.} = if n >= 7: raise newException(ValueError, "foobar: " & $n) else: result = n * 2 proc main() {.async.} = var reason: Error await fn(6).catch((r: Error) => (reason = r)) # note: `()` are needed, `=> reason = r` would not work assert reason == nil await fn(7).catch((r: Error) => (reason = r)) assert reason != nil assert "foobar: 7" in $reason.message discard main()
Source Edit proc newPromise(handler: proc (resolve: proc ())): Future[void] {. importjs: "(new Promise(#))", ...raises: [], tags: [], forbids: [].}
- A helper for wrapping callback-based functions into promises and async procedures. Source Edit
proc newPromise[T](handler: proc (resolve: proc (response: T))): Future[T] {. importjs: "(new Promise(#))", ...raises: [], tags: [], forbids: [].}
- A helper for wrapping callback-based functions into promises and async procedures. Source Edit
proc then[T](future: Future[T]; onSuccess: proc; onReject: OnReject = nil): auto
-
See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then Returns a Future from the return type of onSuccess(T.default).
Example: cmd: -r:off
from std/sugar import `=>` proc fn(n: int): Future[int] {.async.} = if n >= 7: raise newException(ValueError, "foobar: " & $n) else: result = n * 2 proc asyncFact(n: int): Future[int] {.async.} = if n > 0: result = n * await asyncFact(n-1) else: result = 1 proc main() {.async.} = block: # then assert asyncFact(3).await == 3*2 assert asyncFact(3).then(asyncFact).await == 6*5*4*3*2 let x1 = await fn(3) assert x1 == 3 * 2 let x2 = await fn(4) .then((a: int) => a.float) .then((a: float) => $a) assert x2 == "8.0" block: # then with `onReject` callback var witness = 1 await fn(6).then((a: int) => (witness = 2), (r: Error) => (witness = 3)) assert witness == 2 await fn(7).then((a: int) => (witness = 2), (r: Error) => (witness = 3)) assert witness == 3
Source Edit