apply

Call Erlang and JavaScript runtime functions at runtime, by string path — no @external + hand-written *_ffi.erl / *_ffi.mjs boilerplate for every function you want to reach. One path string, one tuple of arguments, one default value — done.

import apply

pub fn main() {
  // Erlang target
  let assert Ok(3) = apply.apply("erlang:length", #([1, 2, 3]), 0)

  // JavaScript target
  let assert Ok(5) = apply.apply("Math.max", #(1, 5), 0)
}

Why?

Calling into the runtime from Gleam normally means, per function:

• an @external declaration in Gleam,
• a matching entry in a hand-written *_ffi.erl / *_ffi.mjs,
• dealing with any-typed results, exceptions and odd return values (undefined, false, {error, _}, …) on your own.

apply collapses all of that into two FFI files total for the whole library (src/erl_ffi.erl + src/jst_ffi.mjs), one path-based API, and a type-checked Result(a, String) that pins the return type for you. You write ordinary Gleam; the path string is the only “FFI”.

How it works

The runtime is decided by your project’s target in gleam.toml, not by this library — the path format simply follows that runtime.

Installation

gleam add apply@2.0.0

API overview

get_erl_func / get_js_obj are runtime-specific: calling them on the other runtime returns a runtime error. apply/3 and unwrap/2 work on both.

Usage

The path format follows the runtime your project targets; args must be a tuple, its elements are spread as call arguments in order; default anchors the expected return type.

Erlang

import apply

pub fn main() {
  let assert Ok(3) = apply.apply("erlang:length", #([1, 2, 3]), 0)
  let assert Ok(10) = apply.apply("erlang:max", #(10, 2), 0)
  let assert Ok("123") = apply.apply("erlang:integer_to_binary", #(123), "")

  // Non-tuple arguments return an error
  let assert Error(_) = apply.apply("erlang:length", "not a tuple", 0)
}

JavaScript

import apply

pub fn main() {
  let assert Ok(5) = apply.apply("Math.max", #(1, 5), 0)
  let assert Ok("123") = apply.apply("JSON.stringify", #(123), "")

  // A path that does not exist on this runtime returns an error
  let assert Error(_) = apply.apply("erlang:length", #([1, 2, 3]), 0)
}

Multi-type return values

Runtime functions are untyped from Gleam’s point of view: the same path can return an Int on one call and a Float/Bool/String on another, and “abnormal” values (undefined, null, false, nil, {error, _}, …) are just values too. Gleam has no way to know which one you got — so it types everything as any. apply/3 and unwrap/2 resolve this with a runtime type judgement against default:

• apply.apply(path, args, default) returns Result(a, String) — type-safe, no raw any ever reaches your code:

let assert Ok(3) = apply.apply("erlang:length", #([1, 2, 3]), 0)   // Int

let assert Error(msg) = apply.apply("erlang:is_atom", #(1), 0)
// msg == "erlang:is_atom/1 returned false (type boolean), expected type int"

• unwrap(value, default) returns a plain a — value when the types match, default otherwise. Handy when you call a fetched function yourself:

let dynamic = apply.call_js("JSON.parse")("123") // any
let int = apply.unwrap(dynamic, 0)               // Int or 0
let text = apply.unwrap(dynamic, "")             // String or ""

Type judgement rules

Any value whose type does not match default becomes an Error (for apply) or the default (for unwrap) — you decide what is “normal” per call by choosing the default.

Note: on Erlang 5.0 is a Float literal, while on JavaScript 5.0 is the number 5 and therefore judged an Int (the round-then-subtract precision trick cannot see a float with an integral value).

Fetching function references

// Erlang runtime: export checked against arity; errors list existing arities
let assert Ok(f) = apply.get_erl_func("lists:map", 2)

let assert Error(msg) = apply.get_erl_func("lists:map", 3)
// msg == "lists:map/3 is not exported in erlang (existing arities: 2)"

// JavaScript runtime: resolve a dotted path on globalThis (no arity check)
let assert Ok(_) = apply.get_js_obj("Math.max")
let assert Ok(3.141592653589793) = apply.get_js_obj("Math.PI")

Runtime checks

apply.platform_name()          // "erlang" or "javascript"
apply.is_tuple(#(1, 2))        // True
apply.is_function(fn() { 1 })  // True

Error message format

Both runtimes share a path/arity + reason style:

Notes:

• The Erlang get checks exports against the arity and lists the existing arities on mismatch; the JavaScript get only resolves the path and can return any object (not just functions).
• Erlang exception reasons are not limited to atoms (throw/exit can carry any term) and are formatted in a readable way.

Development (maintaining this library)

gleam run   # Run the project
gleam test  # Run the tests

Both test files can stay enabled — tests skip themselves based on the runtime:

• test/apply_test.gleam (24 tests) — runs only on the javascript target
• test/apply_erlang_test.gleam (31 tests) — runs only on the erlang target

gleam test defaults to the Erlang target; pass --target to be explicit:

gleam test --target erlang
gleam test --target javascript

The Erlang toolchain (erl, erlc, escript) and/or Node.js must be on PATH for the target you test. Consumers never need any of this — it only affects this library’s own tests.

Further documentation can be found at https://hexdocs.pm/apply/.