Module Jv

JavaScript values.

See the FFI manual and cookbook for a gentle introduction.

Values

type t

The type for JavaScript values. A value of this type represents a value of any JavaScript primitive type.

type jv = t

See t.

val equal : t -> t -> bool

equal v0 v1 is JavaScript == equality.

val strict_equal : t -> t -> bool

strict_equal v0 v1 is JavaScript's strict equality. OCaml's (==) is mapped on that equality.

val typeof : t -> Jstr.t

typeof is the JavaScript typeof operator.

val instanceof : t -> cons:t -> bool

instanceof o c is true if o is an instance of constructor c.

val repr : 'a -> t

repr v is the OCaml value v as its JavaScript value representation.

Null and undefined

val null : t

null is JavaScript null.

val undefined : t

null is JavaScript undefined.

val is_null : t -> bool

is_null v is true iff v is strictly equal to null.

val is_undefined : t -> bool

is_undefined v is true iff v is strictly equal to undefined.

val is_none : t -> bool

is_none v is is_null v || is_undefined v.

val is_some : t -> bool

is_some v is not (is_none v).

val to_option : (t -> 'a) -> t -> 'a option

to_option conv v is None if v is null or undefined and Some (conv v) if it is not.

val of_option : none:t -> ('a -> t) -> 'a option -> t

of_option ~none conv o is none if o is None and conv v if o is Some v.

Objects

val global : t

global refers to the global object.

Properties

type prop = string

The type for US-ASCII JavaScript object property names.

val get : t -> prop -> t

get o p is the property p of o. Warning, the result can be null or undefined. See also find.

val set : t -> prop -> t -> unit

set o p v sets property p of o to the value v.

val delete : t -> prop -> unit

delete o p deletes property p of o. The property p or o becomes undefined.

val find : t -> prop -> t option

find p o is property p of o. If the property is null or undefined, the result is None. See also get.

val find_map : (t -> 'a) -> t -> prop -> 'a option

find_map f p o is Option.map f (find p o).

val find_path : t -> prop list -> t option

find_path o p looks up the path l in o. This returns None if any segment is null or undefined. Note. Useful for probing for functionality but rather inefficient.

val set_if_some : t -> prop -> t option -> unit

set_if_some o p v sets property p of o if v is Some p. Otherwise the p is left untouched in o.

Creating

val obj : (prop * t) array -> t

obj props is an object with properties prop.

val new' : t -> t array -> t

new_obj c args creates an object with constructor function c and arguments args. constructor can be used to lookup a constructor function by name in the global object.

Methods

val call : t -> string -> t array -> t

call o m args calls the method named m on o with arguments m. m is assumed to be made of US-ASCII characters only, use call' if that is not the case.

Booleans

val true' : t

true is JavaScript true.

val false' : t

false' is JavaScript false.

val to_bool : t -> bool

to_bool v is the JavaScript Boolean value v as a bool value. This is unsafe, only use if v is guaranted to be a JavaScript boolean.

val of_bool : bool -> t

of_bool b is the bool value b as a JavaScript Boolean value.

module Bool : sig ... end

bool properties accessors.

Integers

val to_int : t -> int

to_int v is the JavaScript Number value v as an int value. The conversion is lossless provided v is integral. This is unsafe, only use if v is guaranteed to be a JavaScript number.

val of_int : int -> t

of_int i is the int value i as a JavaScript Number value. The conversion is lossess.

module Int : sig ... end

int properties accessors.

Floating points

val to_float : t -> float

to_float v is the JavaScript Number value v as a float value. The conversion is lossless.

val of_float : float -> t

of_float f is the float value f as a JavaScript Number value. The conversion is lossless.

module Float : sig ... end

float object properties.

JavaScript strings

val to_jstr : t -> Jstr.t

to_jstr v is the JavaScript string value v as a jstr value.

val of_jstr : Jstr.t -> t

of_jstr v is the jstr value v as a JavaScript value.

module Jstr : sig ... end

Jstr object properties.

OCaml strings

val of_string : string -> t

of_string v is a JavaScript string from the UTF-8 encoded OCaml string v. Shortcut for of_jstr (Jstr.v v).

val to_string : t -> string

to_string v is an UTF-8 encoded OCaml string from the JavaScript string v. Shortcut for Jstr.to_string (to_jstr v).

Arrays

val to_array : (t -> 'a) -> t -> 'a array

to_array conv a is an array value made of the JavaScript array a whose elements are converted with conv.

val of_array : ('a -> t) -> 'a array -> t

of_array conv a is a JavaScript Array value made of the array value a whose element are converted to JavaScript values with conv.

val to_list : (t -> 'a) -> t -> 'a list

to_list conv a is a list value made of the JavaScript array a whose elements are converted with conv.

val of_list : ('a -> t) -> 'a list -> t

of_list conv l is the JavaScript Array value made of the list value l whose element are converted to JavaScript values with conv.

Specialized conversions

Can be faster.

val to_jv_array : t -> t array

to_jv_array is to_array Fun.id.

val of_jv_array : t array -> t

of_jv_array is of_array Fun.id.

val to_jv_list : t -> t list

to_jv_list a is to_list Fun.id.

val of_jv_list : t list -> t

of_jv_array a is of_list Fun.id.

val to_jstr_array : t -> Jstr.t array

to_jstr_array is to_array to_jstr.

val of_jstr_array : Jstr.t array -> t

of_jstr_array a is of_array of_jstr.

val to_jstr_list : t -> Jstr.t list

to_jv_array a is a as list of JavaScript values.

val of_jstr_list : Jstr.t list -> t

of_jv_array a is a as a JavaScript array of JavaScript values.

JavaScript array manipulation

module Jarray : sig ... end

JavaScript arrays.

Functions

val apply : t -> t array -> t

apply f args calls function f with arguments args. func can be used to lookup a function by name in the global object.

Errors and exceptions

module Error : sig ... end

Error objects.

val of_error : Error.t -> t

of_error e is e as a JavaScript value.

val to_error : t -> Error.t

to_error v is v as a JavaScript error.

exception Error of Error.t

This OCaml exception represents any exception thrown by JavaScript code that is an instance of the Error exception. You should match on this exception in OCaml code to catch JavaScript exceptions.

val throw : ?⁠name:Jstr.t -> Jstr.t -> 'a

throw ?name msg throws a JavaScript exception with error object Jv.Error.v ?name msg.

Iterator protocol

module It : sig ... end

JavaScript iterator protocol.

Promises

module Promise : sig ... end

JavaScript promise support.

JavaScript Unicode identifiers

The functions above only work with US-ASCII OCaml string literals. If you hit general Unicode identifiers create JavaScript strings representing them with Jstr.v and use the following functions.

type prop' = Jstr.t

The type for full Unicode JavaScript object property names.

val get' : t -> prop' -> t

get' o p is the property p of o. Warning, the result can be null or undefined. See also find.

val set' : t -> prop' -> t -> unit

se't o p v sets property p of o to the value v.

val delete' : t -> prop' -> unit

delete' o p deletes property p of o. The property p or o becomes undefined.

val find' : t -> prop' -> t option

find' p o is property p of o. If the property is null or undefined, the result is None. See also get'.

val find_map' : (t -> 'a) -> t -> prop' -> 'a option

find_map' f p o is Option.map f (find' p o).

val obj' : (prop' * t) array -> t

obj props is an object with properties prop.

val call' : t -> Jstr.t -> t array -> 'a

call' o m args calls method m on o with arguments m. m must be a JavaScript string.

Entering the debugger

val debugger : unit -> unit

debugger () stops and enters the JavaScript debugger (if available).

Feature detection

val has : string -> 'a -> bool

has p v tests whether Jv.repr v has a member or method p

val defined : 'a -> bool

defined v is Jv.is_some (J.repr v). Tests whether v is neither null nor undefined.

Conversion interface

module type CONV = sig ... end

Abstract type conversion iterface.

module Id : sig ... end

Identity implementation of CONV.