JSAPI reference

The JSAPI is the C++ API for the SpiderMonkey JavaScript engine. To learn how to use the JSAPI, see the JSAPI User Guide and the JSAPI Cookbook.

Note: The FOSS wiki page contains a few links to other libraries and programs that can make life easier when using SpiderMonkey and the JSAPI.
A note on versioning: Up until the release of Firefox 4, SpiderMonkey, and thus the JSAPI, was versioned in an ad-hoc way, with releases happening at times that roughly, but not really, corresponded to Firefox releases. In the fall of 2012, the SpiderMonkey team decided to align releases with those of Firefox. The reference applies this versioning scheme retroactively starting with Firefox 5. Firefox 4 is the last release that has a corresponding SpiderMonkey release with the old scheme, where the JSAPI has the version 1.8.5.

Runtimes and contexts

Compartments:

Locale callbacks:

Locale callback types:

Scripts

Just running some JavaScript code is straightforward:

You can instead compile JavaScript code into a JSScript which you can then execute multiple times.

You can also compile JavaScript code into a function:

Error handling

The following functions allow C/C++ functions to throw and catch JavaScript exceptions:

These functions translate errors into exceptions and vice versa:

Values and types

JS::Value constructors:

JS::Value constants:

jsval constants:

Function and macros for checking the type of a jsval:

All of the following are deprecated. See JS::Value for their modern replacements.

High-level type-conversion routines for packing and unpacking function arguments.

The following functions convert JS values to various types. They can be safely applied to jsvals of any type. They may return new objects. For example, JS_ValueToObject(cx, s) where s is a string creates a new String wrapper object. These functions may call JavaScript methods. For example, JS_ValueToString(cx, obj) may call obj.toString().

Fast, unchecked type-casting macros. These macros must not be applied to values that are not known to be the right type. Like C casts, they may cause crashes if applied to incorrect values. They never create new objects or call into JavaScript code.

A function that behaves like typeof:

And functions that behave like the equality operators:

Memory management

These functions act like the Standard C malloc family of functions, except that errors are reported using the SpiderMonkey error APIs rather than errno. These functions also allow SpiderMonkey to account the number of bytes allocated:

JavaScript objects, strings, and floating-point numbers are garbage collected. These functions provide access to the garbage collector:

The rest of these APIs help protect objects from being destroyed by the garbage collector before the application is done using them.

If a variable is a root, then anything it points to will not be freed by the garbage collector. Failure to root objects is a very common cause of mysterious crashes.

Local root scopes were another way of protecting objects from the garbage collector. They have been removed in JS 1.8.5, though

Added in SpiderMonkey 1.8 If an object contains references to other GC things that are not stored in SpiderMonkey data structures ("slots"), it must implement the JSTraceOp hook to enable the garbage collector to traverse those references. Otherwise the garbage collector will not find all reachable objects and may collect objects that are still reachable, leading to a crash. (In SpiderMonkey 1.7 and earlier, the JSMarkOp hook was used instead. This has since been removed.)

The tracing APIs are used by the garbage collector and JSTraceOp hooks. JSAPI applications may also use them to examine the object graph. (For example, these APIs support very smooth integration between the JS garbage collector and other garbage collectors.)

Miscellaneous GC APIs:

Numbers

Strings

Interning strings tells the SpiderMonkey engine to reuse existing string objects when possible.

The character data for external strings is stored in memory provided by the application. Applications can use this to avoid copying data back and forth between SpiderMonkey's heap and application memory.

Objects

Standard Objects

Date

Intl API

Properties

These functions correspond directly to the ways scripts access object properties:

The following functions are lower-level, allowing the JSAPI application more access to details of how properties are implemented. "Define" is a lower-level version of "set" that provides access to extra settings and does not call setters. Similarly, "lookup" is a lower-level version of "get" that offers extra options and does not call getters.

The following functions behave like JS_GetProperty and JS_GetPropertyById except when operating on E4X XML objects.

A SpiderMonkey extension allows a native function to return an lvalue—that is, a reference to a property of an object:

Id

A jsid is an identifier for a property or method of an object.

jsid constants:

Function for checking and converting the type of a jsid:

Classes

These API features are used to define custom classes—object types that are implemented in C/C++ code but accessible from JavaScript.

Adding native properties and methods to classes:

The behavior of a JSClass can be customized using these flags:

The behavior of a JSClass and its instances can be customized in many ways using callback functions.

JSClass method types:

These stub functions can be used when creating a custom JSClass:

JSExtendedClass method types:

In JS 1.8.5, JSExtendedClass has made private.

JSObjectOps method types:

In JS 1.8.5, JSObjectOps has been made private.

JSXMLObjectOps method types:

In JS 1.8.5, JSXMLObjectOps has been made private.

Arrays

Functions

Calling a function or a method of an object:

Function accessors:

Creating functions:

RegExps

Serialization

  • struct JSStructuredCloneCallbacks
  • JS_SetStructuredCloneCallbacks
  • JS_ReadStructuredClone
  • JS_WriteStructuredClone
  • JS_StructuredClone
  • JS_ReadUint32Pair
  • JS_ReadBytes
  • JS_WriteUint32Pair
  • JS_WriteBytes

Security

Added in SpiderMonkey 1.8.1 Security callbacks are set per-runtime.

Threading

The following functions support the SpiderMonkey threading model.

Note: JS_THREADSAFE is now permanently on and the JSRuntime is single-threaded. To execute more than one JS script at once, use multiple JSRuntimes.

JSAPI 1.7 and earlier They are only available in JS_THREADSAFE builds.

Added in SpiderMonkey 1.8 These functions are always available, but in non-JS_THREADSAFE builds, they do nothing.

The following functions are always available, but in non-JS_THREADSAFE builds, they do nothing:

Time

Callback Types

Native function types:

Other callback types:

See also Classes, above.

Macros

C++ features

Tracing and debugging