Property Access

These functions provide access to JavaScript object properties from C code. Properties can be accessed using atoms, strings, or numeric indices.

Getting Properties

JS_GetProperty

Gets a property value using an atom.

JS_EXTERN JSValue JS_GetProperty(JSContext *ctx, JSValueConst this_obj, JSAtom prop);

Parameters:

ctx - JavaScript context
this_obj - Object to get property from
prop - Property name as atom

Returns: Property value, or JS_EXCEPTION on error Example:

JSAtom prop_atom = JS_NewAtom(ctx, "length");
JSValue length = JS_GetProperty(ctx, array_obj, prop_atom);
JS_FreeAtom(ctx, prop_atom);
if (JS_IsException(length))
    return JS_EXCEPTION;
JS_FreeValue(ctx, length);

JS_GetPropertyStr

Gets a property value using a C string.

JS_EXTERN JSValue JS_GetPropertyStr(JSContext *ctx, JSValueConst this_obj, const char *prop);

Parameters:

ctx - JavaScript context
this_obj - Object to get property from
prop - Property name as null-terminated string

Returns: Property value, or JS_EXCEPTION on error Example:

JSValue proto = JS_GetPropertyStr(ctx, new_target, "prototype");
if (JS_IsException(proto))
    goto fail;
JSValue obj = JS_NewObjectProtoClass(ctx, proto, js_point_class_id);
JS_FreeValue(ctx, proto);

JS_GetPropertyUint32

Gets a property value using a numeric index.

JS_EXTERN JSValue JS_GetPropertyUint32(JSContext *ctx, JSValueConst this_obj, uint32_t idx);

Parameters:

ctx - JavaScript context
this_obj - Object to get property from
idx - Property index (0-based)

Returns: Property value, or JS_EXCEPTION on error Example:

JSValue first_elem = JS_GetPropertyUint32(ctx, array_obj, 0);
if (JS_IsException(first_elem))
    return JS_EXCEPTION;
JS_FreeValue(ctx, first_elem);

JS_GetPropertyInt64

Gets a property value using a 64-bit integer index.

JS_EXTERN JSValue JS_GetPropertyInt64(JSContext *ctx, JSValueConst this_obj, int64_t idx);

Parameters:

ctx - JavaScript context
this_obj - Object to get property from
idx - Property index

Returns: Property value, or JS_EXCEPTION on error

Setting Properties

JS_SetProperty

Sets a property value using an atom.

JS_EXTERN int JS_SetProperty(JSContext *ctx, JSValueConst this_obj, JSAtom prop, JSValue val);

Parameters:

ctx - JavaScript context
this_obj - Object to set property on
prop - Property name as atom
val - Value to set (ownership transferred)

Returns:

1 on success
0 on failure
-1 on exception

Note: This function takes ownership of val. Do not call JS_FreeValue() on it. Example:

JSAtom prop_atom = JS_NewAtom(ctx, "name");
int ret = JS_SetProperty(ctx, obj, prop_atom, JS_NewString(ctx, "example"));
JS_FreeAtom(ctx, prop_atom);
if (ret < 0)
    return JS_EXCEPTION;

JS_SetPropertyStr

Sets a property value using a C string.

JS_EXTERN int JS_SetPropertyStr(JSContext *ctx, JSValueConst this_obj, const char *prop, JSValue val);

Parameters:

ctx - JavaScript context
this_obj - Object to set property on
prop - Property name as null-terminated string
val - Value to set (ownership transferred)

Returns:

1 on success
0 on failure
-1 on exception

Example:

JSValue obj = JS_NewObject(ctx);
JS_SetPropertyStr(ctx, obj, "foo", JS_NewString(ctx, "bar"));
JS_SetPropertyStr(ctx, obj, "count", JS_NewInt32(ctx, 42));

JS_SetPropertyUint32

Sets a property value using a numeric index.

JS_EXTERN int JS_SetPropertyUint32(JSContext *ctx, JSValueConst this_obj, uint32_t idx, JSValue val);

Parameters:

ctx - JavaScript context
this_obj - Object to set property on
idx - Property index (0-based)
val - Value to set (ownership transferred)

Returns:

1 on success
0 on failure
-1 on exception

Example:

JSValue arr = JS_NewArray(ctx);
JS_SetPropertyUint32(ctx, arr, 0, JS_NewInt32(ctx, 1));
JS_SetPropertyUint32(ctx, arr, 1, JS_NewInt32(ctx, 2));
JS_SetPropertyUint32(ctx, arr, 2, JS_NewInt32(ctx, 3));

JS_SetPropertyInt64

Sets a property value using a 64-bit integer index.

JS_EXTERN int JS_SetPropertyInt64(JSContext *ctx, JSValueConst this_obj, int64_t idx, JSValue val);

Parameters:

ctx - JavaScript context
this_obj - Object to set property on
idx - Property index
val - Value to set (ownership transferred)

Returns:

1 on success
0 on failure
-1 on exception

Checking Properties

JS_HasProperty

Checks if an object has a property.

JS_EXTERN int JS_HasProperty(JSContext *ctx, JSValueConst this_obj, JSAtom prop);

Parameters:

ctx - JavaScript context
this_obj - Object to check
prop - Property name as atom

Returns:

1 if property exists
0 if property does not exist
-1 on exception

Example:

JSAtom prop_atom = JS_NewAtom(ctx, "toString");
int has_prop = JS_HasProperty(ctx, obj, prop_atom);
JS_FreeAtom(ctx, prop_atom);
if (has_prop < 0)
    return JS_EXCEPTION;
if (has_prop) {
    // Property exists
}

JS_DeleteProperty

Deletes a property from an object.

JS_EXTERN int JS_DeleteProperty(JSContext *ctx, JSValueConst obj, JSAtom prop, int flags);

Parameters:

ctx - JavaScript context
obj - Object to delete property from
prop - Property name as atom
flags - Combination of JS_PROP_* flags

Returns:

1 on success
0 on failure
-1 on exception

Advanced Property Operations

JS_DefineProperty

Defines a property with a descriptor.

JS_EXTERN int JS_DefineProperty(JSContext *ctx, JSValueConst this_obj,
                               JSAtom prop, JSValueConst val,
                               JSValueConst getter, JSValueConst setter,
                               int flags);

Parameters:

ctx - JavaScript context
this_obj - Object to define property on
prop - Property name as atom
val - Property value (or JS_UNDEFINED)
getter - Getter function (or JS_UNDEFINED)
setter - Setter function (or JS_UNDEFINED)
flags - Property flags (see below)

Returns:

0 on success
-1 on exception

Flags:

JS_PROP_CONFIGURABLE  // Property can be deleted or modified
JS_PROP_WRITABLE      // Property value can be changed
JS_PROP_ENUMERABLE    // Property shows up in enumeration
JS_PROP_C_W_E         // All three flags combined

JS_DefinePropertyValue

Defines a data property with a value.

JS_EXTERN int JS_DefinePropertyValue(JSContext *ctx, JSValueConst this_obj,
                                    JSAtom prop, JSValue val, int flags);

Parameters:

ctx - JavaScript context
this_obj - Object to define property on
prop - Property name as atom
val - Property value (ownership transferred)
flags - Property flags

Returns:

0 on success
-1 on exception

JS_DefinePropertyValueStr

Defines a data property with a value using a string name.

JS_EXTERN int JS_DefinePropertyValueStr(JSContext *ctx, JSValueConst this_obj,
                                       const char *prop, JSValue val, int flags);

Parameters:

ctx - JavaScript context
this_obj - Object to define property on
prop - Property name as null-terminated string
val - Property value (ownership transferred)
flags - Property flags

Returns:

0 on success
-1 on exception

JS_DefinePropertyValueUint32

Defines a data property with a value using a numeric index.

JS_EXTERN int JS_DefinePropertyValueUint32(JSContext *ctx, JSValueConst this_obj,
                                          uint32_t idx, JSValue val, int flags);

Parameters:

ctx - JavaScript context
this_obj - Object to define property on
idx - Property index
val - Property value (ownership transferred)
flags - Property flags

Returns:

0 on success
-1 on exception

JS_DefinePropertyGetSet

Defines an accessor property with getter and setter.

JS_EXTERN int JS_DefinePropertyGetSet(JSContext *ctx, JSValueConst this_obj,
                                     JSAtom prop, JSValue getter, JSValue setter,
                                     int flags);

Parameters:

ctx - JavaScript context
this_obj - Object to define property on
prop - Property name as atom
getter - Getter function (ownership transferred)
setter - Setter function (ownership transferred)
flags - Property flags

Returns:

0 on success
-1 on exception

JS_GetOwnProperty

Gets the property descriptor for an own property.

JS_EXTERN int JS_GetOwnProperty(JSContext *ctx, JSPropertyDescriptor *desc,
                               JSValueConst obj, JSAtom prop);

Parameters:

ctx - JavaScript context
desc - Pointer to property descriptor structure
obj - Object to query
prop - Property name as atom

Returns:

1 if property exists
0 if property does not exist
-1 on exception

Property Descriptor:

typedef struct JSPropertyDescriptor {
    int flags;
    JSValue value;
    JSValue getter;
    JSValue setter;
} JSPropertyDescriptor;

JS_GetOwnPropertyNames

Gets an array of property names from an object.

JS_EXTERN int JS_GetOwnPropertyNames(JSContext *ctx, JSPropertyEnum **ptab,
                                    uint32_t *plen, JSValueConst obj,
                                    int flags);

Parameters:

ctx - JavaScript context
ptab - Pointer to receive property array
plen - Pointer to receive property count
obj - Object to query
flags - Combination of JS_GPN_* flags

Returns:

0 on success
-1 on exception

Flags:

JS_GPN_STRING_MASK   // Include string properties
JS_GPN_SYMBOL_MASK   // Include symbol properties
JS_GPN_PRIVATE_MASK  // Include private properties
JS_GPN_ENUM_ONLY     // Only enumerable properties
JS_GPN_SET_ENUM      // Set is_enumerable field

Example:

JSPropertyEnum *tab;
uint32_t len;
if (JS_GetOwnPropertyNames(ctx, &tab, &len, obj, JS_GPN_STRING_MASK | JS_GPN_ENUM_ONLY) < 0)
    return JS_EXCEPTION;

for (uint32_t i = 0; i < len; i++) {
    // Use tab[i].atom
}
JS_FreePropertyEnum(ctx, tab, len);

JS_FreePropertyEnum

Frees a property enumeration array.

JS_EXTERN void JS_FreePropertyEnum(JSContext *ctx, JSPropertyEnum *tab, uint32_t len);

Parameters:

ctx - JavaScript context
tab - Property array to free
len - Number of properties

Special Property Operations

JS_GetPrototype

Gets the prototype of an object.

JS_EXTERN JSValue JS_GetPrototype(JSContext *ctx, JSValueConst val);

Parameters:

ctx - JavaScript context
val - Object to get prototype from

Returns: The prototype object, or JS_EXCEPTION on error

JS_SetPrototype

Sets the prototype of an object.

JS_EXTERN int JS_SetPrototype(JSContext *ctx, JSValueConst obj, JSValueConst proto_val);

Parameters:

ctx - JavaScript context
obj - Object to set prototype on
proto_val - New prototype object or JS_NULL

Returns:

0 on success
-1 on exception

JS_GetLength

Gets the length property of an object.

JS_EXTERN int JS_GetLength(JSContext *ctx, JSValueConst obj, int64_t *pres);

Parameters:

ctx - JavaScript context
obj - Object to get length from
pres - Pointer to store the length

Returns:

0 on success
-1 on exception

JS_SetLength

Sets the length property of an object.

JS_EXTERN int JS_SetLength(JSContext *ctx, JSValueConst obj, int64_t len);

Parameters:

ctx - JavaScript context
obj - Object to set length on
len - New length value

Returns:

0 on success
-1 on exception

Runtime Management

Context Management

Value Operations

Function Calls

Object Operations

Script Evaluation

Exception Handling

Atoms

Property Access

Property Access

Getting Properties

JS_GetProperty

JS_GetPropertyStr

JS_GetPropertyUint32

JS_GetPropertyInt64

Setting Properties

JS_SetProperty

JS_SetPropertyStr

JS_SetPropertyUint32

JS_SetPropertyInt64

Checking Properties

JS_HasProperty

JS_DeleteProperty

Advanced Property Operations

JS_DefineProperty

JS_DefinePropertyValue

JS_DefinePropertyValueStr

JS_DefinePropertyValueUint32

JS_DefinePropertyGetSet

JS_GetOwnProperty

JS_GetOwnPropertyNames

JS_FreePropertyEnum

Special Property Operations

JS_GetPrototype

JS_SetPrototype

JS_GetLength

JS_SetLength

​Property Access

​Getting Properties

​JS_GetProperty

​JS_GetPropertyStr

​JS_GetPropertyUint32

​JS_GetPropertyInt64

​Setting Properties

​JS_SetProperty

​JS_SetPropertyStr

​JS_SetPropertyUint32

​JS_SetPropertyInt64

​Checking Properties

​JS_HasProperty

​JS_DeleteProperty

​Advanced Property Operations

​JS_DefineProperty

​JS_DefinePropertyValue

​JS_DefinePropertyValueStr

​JS_DefinePropertyValueUint32

​JS_DefinePropertyGetSet

​JS_GetOwnProperty

​JS_GetOwnPropertyNames

​JS_FreePropertyEnum

​Special Property Operations

​JS_GetPrototype

​JS_SetPrototype

​JS_GetLength

​JS_SetLength

Property Access

Getting Properties

JS_GetProperty

JS_GetPropertyStr

JS_GetPropertyUint32

JS_GetPropertyInt64

Setting Properties

JS_SetProperty

JS_SetPropertyStr

JS_SetPropertyUint32

JS_SetPropertyInt64

Checking Properties

JS_HasProperty

JS_DeleteProperty

Advanced Property Operations

JS_DefineProperty

JS_DefinePropertyValue

JS_DefinePropertyValueStr

JS_DefinePropertyValueUint32

JS_DefinePropertyGetSet

JS_GetOwnProperty

JS_GetOwnPropertyNames

JS_FreePropertyEnum

Special Property Operations

JS_GetPrototype

JS_SetPrototype

JS_GetLength

JS_SetLength