A JSClass describes a class of JavaScript objects. A C/C++ program can use a JSClass with the JS_InitClass and JS_NewObject APIs to create objects that have custom methods and properties implemented in C/C++.

Syntax

struct JSClass {
    const char          *name;
    uint32_t            flags;

    /* Optional since SpiderMonkey 37 */
    JSPropertyOp        addProperty;
    JSDeletePropertyOp  delProperty;
    JSPropertyOp        getProperty;
    JSStrictPropertyOp  setProperty;
    JSEnumerateOp       enumerate;
    JSResolveOp         resolve;

    JSConvertOp         convert;      /* Obsolete since SpiderMonkey 44 */

    /* Optional since SpiderMonkey 25 */
    JSFinalizeOp        finalize;

    /* Optional */
    JSClassInternal     reserved0;    /* Obsolete since SpiderMonkey 13 */
    JSCheckAccessOp     checkAccess;  /* Obsolete since SpiderMonkey 29 */
    JSNative            call;
    JSHasInstanceOp     hasInstance;
    JSNative            construct;
    JSXDRObjectOp       xdrObject;    /* Obsolete since SpiderMonkey 13 */
    JSTraceOp           trace;        /* Added in SpiderMonkey 17 */

    JSClassInternal     reserved1;    /* Obsolete since SpiderMonkey 13 */
    void                *reserved[N]; /* sizeof 'reserved' depends on version */
};
Name Type Description
name const char * Class name
flags uint32_t Class flags. This field is the bitwise OR of one or more of the JSCLASS_* constants described in JSClass.flags.
addProperty JSPropertyOp

A hook called just after adding a new property. May modify the new property value.

Use NULL or JS_PropertyStub (SpiderMonkey 31 or older) for default behavior.
delProperty JSDeletePropertyOp

A hook called when deleting a property. May veto.

Use NULL or JS_DeletePropertyStub (SpiderMonkey 31 or older) for default behavior.
getProperty JSPropertyOp

A hook called when getting a property. This is the default getter for the class.

Use NULL or JS_PropertyStub (SpiderMonkey 31 or older) for default behavior.
setProperty JSStrictPropertyOp

A hook called when setting a property. This is the default setter for the class. When a script creates a new property, this is called after addProperty.

Use NULL or JS_StrictPropertyStub (SpiderMonkey 31 or older) for default behavior.
enumerate JSEnumerateOp

Method for enumerating object properties.

Use NULL or JS_EnumerateStub (SpiderMonkey 31 or older) for default behavior.

Obsolete since JSAPI 37 The JSCLASS_NEW_ENUMERATE flag instructs SpiderMonkey to call this as a JSNewEnumerateOp.
resolve JSResolveOp

Hook for implementing lazy properties. See JSClass.resolve for details.

Use NULL or JS_ResolveStub (SpiderMonkey 31 or older) for default behavior.

Obsolete since JSAPI 36 The JSCLASS_NEW_RESOLVE flag instructs SpiderMonkey to call this as a JSNewResolveOp.

Obsolete since JSAPI 16The JSCLASS_NEW_RESOLVE_GETS_START flag further affects this hook.
convert JSConvertOp

This hook specifies how objects of this class are converted to a primitive value.  It implements the object's [[DefaultValue]] hook, which is invoked by JavaScript when the object must be converted to a string, number, or primitive value. Obsolete since JSAPI 44

Use NULL or JS_ConvertStub (SpiderMonkey 31 or older) for default behavior, which is equivalent to that defined by ECMAScript in §8.12.8.
finalize JSFinalizeOp

The object finalizer hook. This is called at some point after the object becomes unreachable, and can be used to free any additional resources associated with the object.

If objects of this class do not need finalization, use NULL.
checkAccess JSCheckAccessOp Optional method for access checks. Implements JS_CheckAccess. If your application does not use the JSAPI's security features, use NULL. Obsolete since JSAPI 29
call JSNative This is called when a script calls an object as though it were a function: obj(). If objects of your class shouldn't be callable, use NULL. Most objects are not callable.
hasInstance JSHasInstanceOp Pointer to an optional hasInstance method for this object. If you do not provide a method for hasInstance, set this pointer to NULL.
construct JSNative This is called when a script uses an object as though it were a constructor: new obj().  If objects of your class shouldn't be callable this way, use NULL. Most custom objects are not intended to be used as constructors.
xdrObject JSXDRObjectOp Implements object serialization. If you do not use JSXDR, set this pointer to NULL. Obsolete since JSAPI 13
trace JSTraceOp

The GC trace hook.

Description

Use JSClass to define a custom class of JavaScript objects. A JSClass has a name, flags, and several callback functions for advanced customization of object behavior.

Simple classes

A simple custom class does not require any special JSClass callbacks. Instead, all the native code is in JSPropertyOps (property getters and setters) and JSNatives or JSFastNatives (methods). The code for such a class is simple:

/* SpiderMonkey 38 */
static JSClass robot_class = {
    "Robot",  /* name */
    0         /* flags */
};

/* SpiderMonkey 31 or older */
static JSClass robot_class = {
    "Robot",  /* name */
    0,        /* flags */
    JS_PropertyStub, JS_PropertyStub, JS_PropertyStub, JS_PropertyStub,
    JS_EnumerateStub, JS_ResolveStub, JS_ConvertStub, NULL,
    JSCLASS_NO_OPTIONAL_MEMBERS
};

To expose this class to scripts, and to attach methods and properties to it, use JS_InitClass.

Private data

Custom classes very often need to store private C/C++ data that should not be visible to scripts. To do this, use the JSCLASS_HAS_PRIVATE (JSCLASS_CONSTRUCT_PROTOTYPE wad removed) flags. Implement a JSNative constructor function that allocates this private data and stores it in the new object using JS_SetPrivate. Implement a JSClass.finalize callback that frees the private data. Each native getter, setter, or method can access the private data using JS_GetInstancePrivate.

When initializing the class, pass the JSNative constructor function to JS_InitClass.

(This example uses the C++ new and delete keywords, but the application can allocate the memory for private data however it likes. The JavaScript engine never touches the private data; it is for the application's use only.)

void
printer_finalize(JSContext *cx, JSObject *obj)
{
    MyPrinter *p = (MyPrinter *) JS_GetPrivate(cx, obj);
    delete p;
}

static JSClass printer_class = {
    "Printer",
    JSCLASS_HAS_PRIVATE,
    NULL, NULL, NULL, NULL,
    NULL, NULL, NULL, printer_finalize
};

/* SpiderMonkey 31 or older
 * static JSClass printer_class = {
 *     "Printer",
 *     JSCLASS_HAS_PRIVATE,
 *     JS_PropertyStub, JS_PropertyStub, JS_PropertyStub, JS_StrictPropertyStub,
 *     JS_EnumerateStub, JS_ResolveStub, JS_ConvertStub, printer_finalize,
 *     JSCLASS_NO_OPTIONAL_MEMBERS
 * };
 */

bool
printer_construct(JSContext *cx, unsigned argc, jsval *vp)
{
    JS::CallArgs args = JS::CallArgsFromVp(argc, vp);
    JSObject *obj = JS_NewObjectForConstructor(cx, &printer_class, args);
    /* SpiderMonkey 31 or older
     * JSObject *obj = JS_NewObjectForConstructor(cx, &printer_class, vp);
     */
    if (!obj)
        return false;

    MyPrinter *p = new MyPrinter;
    if (p == NULL) {
        JS_ReportOutOfMemory(cx);
        return false;
    }
    JS_SetPrivate(cx, obj, p);

    args.rval().setObject(*obj);
    /* SpiderMonkey 31 or older
     * JS_SET_RVAL(cx, vp, OBJECT_TO_JSVAL(obj));
     */
    return true;
}

{
  JS_InitClass(cx, global, JS::NULL(), &printer_class, printer_construct, 1,
               NULL, NULL, NULL, NULL);
}

See also