On this page:
7.1 Type Conversions
7.2 Checking Javascript Types and Values
7.3 Accessing Javascript Values
7.4 Calling Javascript Functions
Version: 5.0.1

7 Racket to Javascript FFI

 (require (planet dyoo/js-vm:1:9/ffi/ffi))

This API provides a foriegn function interface that allows javascript to be accessed directly and explicitly through racket. This allows access to native javascript functionality and allows external javascript APIs to be used in racket code without modifying the source code of the runtime infrastructure that evaluates the code.

The contents of this module need to run in a Javascript context.

7.1 Type Conversions

These procedures are designed to convert between racket and javascript types.

(racket->prim-js v)  js-value?
  v : (or/c boolean? char? real? string? symbol? vector?)
Converts a racket value to a javascript value using the following rules:

The racket->prim-js procedure cannot convert a procedure because racket procedures cannot be converted to javascript in a straightforward manner. When racket procedures are evaluated, they are evaluated in continuation passing style, and hence any javascript procedure constructed from a racket procedure must either be in CPS or must return void.

(procedure->cps-js-fun proc)  js-function?
  proc : procedure?
Converts a racket procedure to a javascript function. The javascript function returned is in continuation passing style and takes a continuation as its first argument. When called, the javascript function passes the return value of proc applied to all arguments but the first to the function’s first argument.

(procedure->void-js-fun proc)  js-function?
  proc : procedure?
Converts a racket procedure to a javascript function. The javascript function will apply proc to its arguments, and then ignore proc’s return value and return undefined (javascript’s version of returning void).

(prim-js->racket v)
  (or/c boolean? inexact-real? string? vector?)
  v : js-value?
Converts a javascript value to its corresponding racket value.

If v is not an array, boolean, function, number, or string, prim-js->racket will raise an exn:fail:contract exception.

7.2 Checking Javascript Types and Values

The following procedures are useful for checking the values and types of javascript values.

(js-value? x)  boolean?
  x : any/c
Returns #t if x is a javascript value, #f otherwise.

(js-object? x)  boolean?
  x : any/c
Returns #t if x is a javascript function, #f otherwise.

(js-function? x)  boolean?
  x : any/c
Returns #t if x is a javascript object, #f otherwise.

(js-=== v1 v2)  boolean?
  v1 : js-value?
  v2 : js-value?
Returns #t if v1 and v2 are equal according to javascript’s ===. Otherwise returns #f.

(js-typeof v)  string?
  v : js-value?
Returns a string representing the javascript type of v. The string is obtained by calling javascript’s typeof on v.

(js-instanceof v type)  boolean?
  v : js-value?
  type : js-function?
Returns #t if v is an instance of the javascript type type and #f otherwise.

(js-null? v)  boolean?
  v : js-value?
Produces true if v is null.

(js-undefined? v)  boolean?
  v : js-value?
Produces true if v is undefined.

7.3 Accessing Javascript Values

The following procedures are useful for accessing javascript values from external APIs as well as constructing new values to pass to other javascript functions.

(js-get-global-value name)  js-value?
  name : string?
Interprets name as an identifier, and returns the javascript value bound to that identifier in the global scope. If no such value exists, then a js-value containing javascript’s undefined is returned.

So, for example, (js-get-global-value "setTimeout") would return javascript’s setTimeout procedure.

(js-get-field obj selector ...+)  js-value?
  obj : js-value?
  selector : string?
Begins by accessing the field of obj named by the first selector, then accesses the field named by the second selector of that object, and so-on until there are no more selectors.

If at any point this action would result in accessing a field of a racket value or javascript’s undefined, js-get-field will raise an exn:fail:contract exception.

(js-set-field! obj field v)  void?
  obj : (or/c js-object? js-function?)
  field : string?
  v : any/c
Mutatively sets the field named field of obj to v and returns #<void>.

(js-new constructor args ...)  js-object?
  constructor : js-function?
  args : any/c
Constructs a new instance of constructor with args ... as arguments.

(js-make-hash [bindings])  js-object?
  bindings : (listof (list/c string? any/c)) = empty
Constructs a new javascript hash table. For each element of bindings, the element is put into the hash table with the first as the key and the second as the value. If multiple elements in bindings have firsts that are equal?, then only the last binding will exist (the others will be overwritten).

js-null : js-value?
The null value.
js-undefined : js-value?
The undefined value.

minimum-js-fixnum : "The minimum number that can  be exactly representable."
maximum-js-fixnum : "The maximum number that can be exactly representable."

7.4 Calling Javascript Functions

(js-call f this-arg args ...)  any
  f : js-function?
  this-arg : (or/c js-object? false?)
  args : any/c
Applies f to args ... with this-arg as the this object. If this-arg is #f, then javascript’s null is used. This is equivalent to javascript’s f.call(this-arg, args ...).