Await the result of an async evaluation task.

Delegates to Task.await/2. Use with tasks returned by eval_async/2, eval_ts_async/2, call_async/3, and call_async_decode/3.

Example

Denox.eval_async(rt, "export default await Promise.resolve(42)")
|> Denox.await()
#=> {:ok, "42"}

@spec call(runtime(), String.t(), list()) :: {:ok, String.t()} | {:error, String.t()}

Call a named JavaScript function with arguments.

Arguments are serialized to JSON. Returns {:ok, json_string} or {:error, message}.

@spec call_async(runtime(), String.t(), list()) :: Task.t()

Call a named async JavaScript function with arguments, returning a Task.

Use Task.await/2 to get the result.

Returns a Task that resolves to {:ok, json_string} or {:error, message}.

@spec call_async_decode(runtime(), String.t(), list()) :: Task.t()

Call a named async JavaScript function and decode the JSON result.

Returns a Task that resolves to {:ok, term()} or {:error, term()}.

@spec call_decode(runtime(), String.t(), list()) :: {:ok, term()} | {:error, term()}

Call a named JavaScript function and decode the JSON result.

@spec create_snapshot(
  String.t(),
  keyword()
) :: {:ok, binary()} | {:error, String.t()}

Create a V8 snapshot from setup code.

The snapshot captures all global state (variables, functions, etc.) after executing the setup code.

Options:

• :transpile - if true, transpile TypeScript before executing (default: false)

Returns {:ok, snapshot_bytes} or {:error, message}.

@spec eval(runtime(), String.t()) :: {:ok, String.t()} | {:error, String.t()}

Evaluate JavaScript code in the given runtime.

Pumps the event loop and resolves Promises automatically. Supports import(), setTimeout, and other async operations.

Returns {:ok, json_string} or {:error, message}.

@spec eval_async(runtime(), String.t()) :: Task.t()

Evaluate JavaScript code as an ES module, returning a Task.

The code is evaluated as a proper ES module, so static import/export declarations and top-level await work natively. Use export default to return a value.

Returns a Task that resolves to {:ok, json_string} or {:error, message}.

Example

task = Denox.eval_async(rt, "const status = (await fetch('https://httpbin.org/get')).status; export default status;")
{:ok, "200"} = Task.await(task)

# Static imports work:
task = Denox.eval_async(rt, """
  import { something } from './my_module.js';
  export default something;
""")

@spec eval_async_decode(runtime(), String.t()) :: Task.t()

Evaluate JavaScript code asynchronously and decode the JSON result.

Returns a Task that resolves to {:ok, term()} or {:error, term()}.

@spec eval_decode(runtime(), String.t()) :: {:ok, term()} | {:error, term()}

Evaluate JavaScript code and decode the JSON result to Elixir terms.

@spec eval_file(runtime(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, String.t()}

Read and evaluate a JavaScript or TypeScript file.

Simpler than eval_module/2 — no import/export support, just script execution. TypeScript files (.ts, .tsx) are automatically transpiled.

Returns {:ok, json_string} or {:error, message}.

@spec eval_file_async(runtime(), String.t(), keyword()) :: Task.t()

Read and evaluate a JavaScript or TypeScript file asynchronously.

Returns a Task that resolves to {:ok, json_string} or {:error, message}.

@spec eval_file_async_decode(runtime(), String.t(), keyword()) :: Task.t()

Read and evaluate a JavaScript or TypeScript file asynchronously and decode the JSON result.

Returns a Task that resolves to {:ok, term()} or {:error, term()}.

@spec eval_file_decode(runtime(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Read and evaluate a JavaScript or TypeScript file and decode the JSON result.

Returns {:ok, term()} or {:error, term()}.

@spec eval_module(runtime(), String.t()) :: {:ok, String.t()} | {:error, String.t()}

Load and evaluate an ES module file. Supports .ts/.js with import/export.

Returns {:ok, "undefined"} or {:error, message}.

@spec eval_ts(runtime(), String.t()) :: {:ok, String.t()} | {:error, String.t()}

Evaluate TypeScript code in the given runtime. Transpiles via deno_ast/swc then evaluates. No type-checking.

Pumps the event loop and resolves Promises automatically.

Returns {:ok, json_string} or {:error, message}.

@spec eval_ts_async(runtime(), String.t()) :: Task.t()

Evaluate TypeScript code as an ES module, returning a Task.

Supports static import/export declarations and top-level await. Use export default to return a value.

Returns a Task that resolves to {:ok, json_string} or {:error, message}.

@spec eval_ts_async_decode(runtime(), String.t()) :: Task.t()

Evaluate TypeScript code asynchronously and decode the JSON result.

Returns a Task that resolves to {:ok, term()} or {:error, term()}.

@spec eval_ts_decode(runtime(), String.t()) :: {:ok, term()} | {:error, term()}

Evaluate TypeScript code and decode the JSON result to Elixir terms.

@spec exec(runtime(), String.t()) :: :ok | {:error, String.t()}

Execute JavaScript code, ignoring the return value.

Returns :ok or {:error, message}.

@spec exec_ts(runtime(), String.t()) :: :ok | {:error, String.t()}

Execute TypeScript code, ignoring the return value.

Returns :ok or {:error, message}.

@spec runtime(keyword()) :: {:ok, runtime()} | {:error, String.t()}

Create a new JavaScript runtime.

Options:

• :base_dir - base directory for resolving relative module imports
• :sandbox - (deprecated) if true, deny all permissions. Use :permissions instead
• :permissions - permission mode:
  • :all — allow everything (default)
  • :none — deny everything (same as sandbox: true)
  • keyword list — granular permissions. Supports both allow_* and deny_* keys. E.g. [allow_net: true, allow_read: ["/tmp"], deny_env: true]. Values can be true (blanket) or a list of strings (specific paths/hosts). false entries are ignored. Unknown keys raise ArgumentError.
• :cache_dir - on-disk cache directory for remote module fetches
• :import_map - map of bare specifiers to resolved URLs/paths (e.g. %{"lodash" => "https://esm.sh/lodash"})
• :callback_pid - PID of the process that handles JS→Elixir callbacks (enables Denox.callback() in JS)
• :snapshot - V8 snapshot binary for faster cold start (created via create_snapshot/2)

Returns {:ok, runtime} or {:error, message}.