JS_PreventExtensions

Syntax

// Added in SpiderMonkey 45

bool
JS_PreventExtensions(JSContext *cx, JS::HandleObject obj, JS::ObjectOpResult &result);

// Obsolete since JSAPI 39

bool
JS_PreventExtensions(JSContext *cx, JS::HandleObject obj, bool *succeeded);

Description

All JavaScript objects recognize the concept of extensibility: whether new properties may be added to the object.  In some situations, it may be convenient to prohibit new properties.  In JavaScript this may be accomplished using the Object.preventExtensions method.  The similar JSAPI method is JS_PreventExtensions.

Unlike Object.preventExtensions, JS_PreventExtensions doesn't necessarily throw a TypeError if the object couldn't be made non-extensible.  There are instead two modes of failure: through internal error, and because the object denied the attempt.

The first case occurs when something went wrong internally, not necessarily because the object chose not to become non-extensible.  For example, if making the object requires an allocation, and that allocation fails, out-of-memory might be reported, and JS_PreventExtensions would return false.  This might also occur if the object is a proxy, and some internal state of the proxy means that no coherent behavior is possible.  For example, if the object is a revocable proxy that has been revoked, it makes no sense to say that an attempt to prevent extensions either succeeded or failed: it's a category error.  Thus in this case JS_PreventExtensions will throw an error.

var target = {};
var handler = {};
var pair = Proxy.revocable(target, handler);

var proxy = pair.proxy;
var revoke = pair.revoke;

revoke();

// bool succeeded;
// bool rv = JS_PreventExtensions(cx, proxy, &succeeded);
// // rv == false, succeeded is indeterminate

The second case occurs when no internal error is encountered, but the object simply refuses to be made non-extensible.  For example, a proxy might refuse to be made non-extensible; this refusal would show up in the post-call value of *succeeded.

var target = {};
var handler = { preventExtensions: function(obj) { return false; } };
var obj = new Proxy(target, handler);

// bool succeeded;
// bool rv = JS_PreventExtensions(cx, obj, &succeeded);
// // rv == true, succeeded == false

Note that as with most JSAPI methods, *succeeded is only set if JS_PreventExtensions returns true (that is, does not fail).  Thus you should always check the return value of JS_PreventExtensions, and only if that is true check the value of *succeeded.

See Also

• MXR ID Search for JS_PreventExtensions
• bug 1113369 -- added result parameter