apply/js

Types

Function

opaque </>

Opaque marker for a JavaScript callable (counterpart of Function on the erlang side).

Usage: built by get_function_from_global, executed by try_catch. Note: opaque, cannot be constructed externally; internally it holds both the function itself and the this to call it with.

pub opaque type Function

JsError

</>

Single-layer error type shared by all entry points.

Property access / path parsing / fetching a function / invocation all return it directly; every leaf error is flattened onto this one layer, avoiding nesting like ApplyError -> JsGetFuncErl -> GetFuncError -> ....

pub type JsError(tupled_args) {
  AttrNameNotExist(attr_name: String, obj: JsObj)
  PrimitiveAttrError(obj: JsObj)
  PathIsNotFunction(path: String)
  RuntimeError(need: String, now: String)
  ArgsTypeError(args: tupled_args)
  FuncRunningError(
    func: Function,
    args: tupled_args,
    error_type: String,
    error_reason: String,
    error_stack: List(String),
  )
}

Constructors

AttrNameNotExist(attr_name: String, obj: JsObj)

```
PrimitiveAttrError(obj: JsObj)
```
```
PathIsNotFunction(path: String)
```
```
RuntimeError(need: String, now: String)
```
Wrong runtime (this function needs to run under need, but is running under now)
```
ArgsTypeError(args: tupled_args)
```
Arguments must be a tuple

FuncRunningError(
  func: Function,
  args: tupled_args,
  error_type: String,
  error_reason: String,
  error_stack: List(String),
)

The function threw while running; type / reason / stack are kept structured

JsObj

</>

Opaque marker for a JavaScript value (counterpart of ErlObj on the erlang side).

Usage: returned by get_obj_from_global / get etc., usable only through this module’s interface. Note: opaque, cannot be constructed externally and cannot be used as a concrete type.

pub type JsObj

JsValue

</>

Collapses any JavaScript value into a JsValue carrying the concrete value, by runtime type.

Usage: case js.classify(raw) { JsObject(o) -> ...; JsFunction(f) -> ... }, getting JsObj / Function directly and skipping to_custom_type. The parameter is untyped, so js.apply results and Dynamic collection elements can be passed as-is. Note: on JavaScript the tuple tag is an array, hence JsArray; local (Date / RegExp / Set / class instances, …) maps to JsObject; JsFunction / JsObject are precise / handle types, elements and keys of JsList / JsDict / JsArray are gleam/dynamic.Dynamic and can be read with gleam/dynamic decoders; an array can be split with js.tuple_to_list into List(JsObj) and classified element by element. It does no runtime checking — it trusts identify’s tags; JsValue is only meaningful on the JavaScript runtime — use erl.classify on Erlang.

pub type JsValue {
  JsBool(v: Bool)
  JsInt(v: Int)
  JsFloat(v: Float)
  JsString(v: String)
  JsBitArray(v: BitArray)
  JsList(v: List(dynamic.Dynamic))
  JsDict(v: dict.Dict(dynamic.Dynamic, dynamic.Dynamic))
  JsNil
  JsArray(v: dynamic.Dynamic)
  JsFunction(v: Function)
  JsObject(v: JsObj)
}

Constructors

```
JsBool(v: Bool)
```
```
JsInt(v: Int)
```
```
JsFloat(v: Float)
```
```
JsString(v: String)
```
```
JsBitArray(v: BitArray)
```
```
JsList(v: List(dynamic.Dynamic))
```

JsDict(v: dict.Dict(dynamic.Dynamic, dynamic.Dynamic))

```
JsNil
```
```
JsArray(v: dynamic.Dynamic)
```
```
JsFunction(v: Function)
```
```
JsObject(v: JsObj)
```

Values

apply

</>

pub fn apply(
  path: String,
  args: tupled_args,
) -> Result(a, JsError(tupled_args))

Fetches a function by path and runs it — get_function_from_global + try_catch.

Usage: apply("Math.max", #(9, 2)). Note: any failure in path parsing, function detection, or execution returns JsError; the success value is a generic a, asserted for the use case (used directly as a concrete type, or as JsObj handed to js.classify); when a function can return several types, branch with js.classify.

classify

</>

pub fn classify(value: any) -> JsValue

See JsValue. Dispatches on boundary.identify’s tag and does an identity cast.

Usage: js.classify(raw); raw usually comes from js.apply / js.try_catch, or from a JsObj element of an outer JsValue. Note: unrecognized tags fall back to JsObject.

console_log

</>

pub fn console_log(v: any) -> Result(Nil, Nil)

Calls JavaScript’s console.log.

Usage: console_log(1); mainly for debugging and examples. Note: returns Result(Nil, Nil); if console.log throws or on non-JavaScript runtimes it returns Error(Nil).

format_error

</>

pub fn format_error(error: JsError(a)) -> String

Renders any JsError as one readable, detailed error message.

Usage: the apply.call facade uses it to flatten errors to String; you can also call it yourself for logging. Note: values (objects, arguments) are rendered via boundary.debug_string, whose representation differs per runtime, e.g. a string is "x" on js and <<"x">> on erl.

format_func_running_error

</>

pub fn format_func_running_error(
  error_type: String,
  error_reason: String,
  error_stack: List(String),
) -> String

Joins the structured type / reason / stack into one readable error message.

Usage: usually not called directly; format_error takes this path for FuncRunningError. Note: same signature as the identically named function on the Erlang side; when a stack is present the output is multi-line.

get

</>

pub fn get(
  obj: JsObj,
  attr_name: String,
) -> Result(JsObj, JsError(a))

Reads property attr_name of obj.

Usage: get(obj, "PI"); internally calls has then reflects the value. Note: after has passes, reflect_get may still fail if a getter throws; the let assert here panics in that edge case (property exists but is unreadable, not yet surfaced as an error).

get_function_from_global

</>

pub fn get_function_from_global(
  path: String,
) -> Result(Function, JsError(a))

Fetches a function from the global object by dotted path, e.g. "Math.max".

Usage: get_function_from_global("Math.max"), pass the result to try_catch. Note: returns RuntimeError on non-JavaScript runtimes; PathIsNotFunction when the last segment is not a function; the non-empty-list invariant of path_parse is guarded by a panic.

get_javascript_global

</>

pub fn get_javascript_global() -> Result(JsObj, Nil)

Returns the JavaScript global object (globalThis).

Usage: with get_obj_from_global / get_function_from_global to fetch values from the global by path. Note: only available on the JavaScript runtime; the Erlang runtime falls back to Error(Nil).

get_obj_from_global

</>

pub fn get_obj_from_global(
  path: String,
) -> Result(JsObj, JsError(a))

Fetches an object from the global object by dotted path, e.g. "Math.PI".

Usage: get_obj_from_global("Math.PI"). Note: returns RuntimeError on non-JavaScript runtimes; when a path segment is missing it returns AttrNameNotExist (for the last segment) etc.

has

</>

pub fn has(
  obj: JsObj,
  attr_name: String,
) -> Result(Nil, JsError(a))

Returns whether property attr_name exists on obj.

Usage: Ok(Nil) when present; AttrNameNotExist when missing. Note: returns PrimitiveAttrError when obj is a primitive (cannot be reflected).

try_catch

</>

pub fn try_catch(
  func func: Function,
  args args: tupled_args,
) -> Result(a, JsError(tupled_args))

Runs func with the tuple args, capturing exceptions.

Usage: try_catch(get_function_from_global("Math.max"), #(1, 2)). Note: the success value is a generic a, asserted by the caller for the use case (used directly as a concrete type, or as JsObj handed to js.classify); args must be a tuple or ArgsTypeError is returned; when the function throws a structured FuncRunningError (type / reason / stack) is returned instead of propagating.

tuple_to_list

</>

pub fn tuple_to_list(obj: any) -> Result(List(JsObj), Nil)

Splits a JavaScript array into List(JsObj) for per-element dispatch.

Usage: on JavaScript an array is a Gleam tuple (the tuple tag of classify). First js.classify(raw) to get JsArray(_), then split it with this function and classify each element to branch by type; elements can also be read one by one with gleam/dynamic decoders. Counterpart of erl.tuple_to_list.

Note: accepts only arrays and returns Error(Nil) otherwise; elements are opaque JsObj, classify them when you need a concrete type; JavaScript runtime only, other runtimes return Error(Nil).

tuple_to_values

</>

pub fn tuple_to_values(obj: any) -> Result(List(JsValue), Nil)

Splits a JavaScript array (a Gleam tuple) into List(JsValue): tuple_to_list then classify each element.

Usage: case js.tuple_to_values(raw) { Ok([JsInt(n), ..]) -> ...; _ -> ... }; elements are already JsValue, so you can match constructors directly without classifying each. Note: accepts only arrays, otherwise Error(Nil); unclassifiable elements fall back to JsObject, so end your match with _.