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.