// Copyright 2021 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef INCLUDE_V8_OBJECT_H_
#define INCLUDE_V8_OBJECT_H_
#include "v8-local-handle.h" // NOLINT(build/include_directory)
#include "v8-maybe.h" // NOLINT(build/include_directory)
#include "v8-persistent-handle.h" // NOLINT(build/include_directory)
#include "v8-primitive.h" // NOLINT(build/include_directory)
#include "v8-traced-handle.h" // NOLINT(build/include_directory)
#include "v8-value.h" // NOLINT(build/include_directory)
#include "v8config.h" // NOLINT(build/include_directory)
namespace v8 {
class Array;
class Function;
class FunctionTemplate;
template
class PropertyCallbackInfo;
/**
* A private symbol
*
* This is an experimental feature. Use at your own risk.
*/
class V8_EXPORT Private : public Data {
public:
/**
* Returns the print name string of the private symbol, or undefined if none.
*/
Local Name() const;
/**
* Create a private symbol. If name is not empty, it will be the description.
*/
static Local New(Isolate* isolate,
Local name = Local());
/**
* Retrieve a global private symbol. If a symbol with this name has not
* been retrieved in the same isolate before, it is created.
* Note that private symbols created this way are never collected, so
* they should only be used for statically fixed properties.
* Also, there is only one global name space for the names used as keys.
* To minimize the potential for clashes, use qualified names as keys,
* e.g., "Class#property".
*/
static Local ForApi(Isolate* isolate, Local name);
V8_INLINE static Private* Cast(Data* data);
private:
Private();
static void CheckCast(Data* that);
};
/**
* An instance of a Property Descriptor, see Ecma-262 6.2.4.
*
* Properties in a descriptor are present or absent. If you do not set
* `enumerable`, `configurable`, and `writable`, they are absent. If `value`,
* `get`, or `set` are absent, but you must specify them in the constructor, use
* empty handles.
*
* Accessors `get` and `set` must be callable or undefined if they are present.
*
* \note Only query properties if they are present, i.e., call `x()` only if
* `has_x()` returns true.
*
* \code
* // var desc = {writable: false}
* v8::PropertyDescriptor d(Local()), false);
* d.value(); // error, value not set
* if (d.has_writable()) {
* d.writable(); // false
* }
*
* // var desc = {value: undefined}
* v8::PropertyDescriptor d(v8::Undefined(isolate));
*
* // var desc = {get: undefined}
* v8::PropertyDescriptor d(v8::Undefined(isolate), Local()));
* \endcode
*/
class V8_EXPORT PropertyDescriptor {
public:
// GenericDescriptor
PropertyDescriptor();
// DataDescriptor
explicit PropertyDescriptor(Local value);
// DataDescriptor with writable property
PropertyDescriptor(Local value, bool writable);
// AccessorDescriptor
PropertyDescriptor(Local get, Local set);
~PropertyDescriptor();
Local value() const;
bool has_value() const;
Local get() const;
bool has_get() const;
Local set() const;
bool has_set() const;
void set_enumerable(bool enumerable);
bool enumerable() const;
bool has_enumerable() const;
void set_configurable(bool configurable);
bool configurable() const;
bool has_configurable() const;
bool writable() const;
bool has_writable() const;
struct PrivateData;
PrivateData* get_private() const { return private_; }
PropertyDescriptor(const PropertyDescriptor&) = delete;
void operator=(const PropertyDescriptor&) = delete;
private:
PrivateData* private_;
};
/**
* PropertyAttribute.
*/
enum PropertyAttribute {
/** None. **/
None = 0,
/** ReadOnly, i.e., not writable. **/
ReadOnly = 1 << 0,
/** DontEnum, i.e., not enumerable. **/
DontEnum = 1 << 1,
/** DontDelete, i.e., not configurable. **/
DontDelete = 1 << 2
};
/**
* Accessor[Getter|Setter] are used as callback functions when
* setting|getting a particular property. See Object and ObjectTemplate's
* method SetAccessor.
*/
using AccessorGetterCallback =
void (*)(Local property, const PropertyCallbackInfo& info);
using AccessorNameGetterCallback =
void (*)(Local property, const PropertyCallbackInfo& info);
using AccessorSetterCallback = void (*)(Local property,
Local value,
const PropertyCallbackInfo& info);
using AccessorNameSetterCallback =
void (*)(Local property, Local value,
const PropertyCallbackInfo& info);
/**
* Access control specifications.
*
* Some accessors should be accessible across contexts. These
* accessors have an explicit access control parameter which specifies
* the kind of cross-context access that should be allowed.
*
*/
enum AccessControl {
DEFAULT = 0,
};
/**
* Property filter bits. They can be or'ed to build a composite filter.
*/
enum PropertyFilter {
ALL_PROPERTIES = 0,
ONLY_WRITABLE = 1,
ONLY_ENUMERABLE = 2,
ONLY_CONFIGURABLE = 4,
SKIP_STRINGS = 8,
SKIP_SYMBOLS = 16
};
/**
* Options for marking whether callbacks may trigger JS-observable side effects.
* Side-effect-free callbacks are allowlisted during debug evaluation with
* throwOnSideEffect. It applies when calling a Function, FunctionTemplate,
* or an Accessor callback. For Interceptors, please see
* PropertyHandlerFlags's kHasNoSideEffect.
* Callbacks that only cause side effects to the receiver are allowlisted if
* invoked on receiver objects that are created within the same debug-evaluate
* call, as these objects are temporary and the side effect does not escape.
*/
enum class SideEffectType {
kHasSideEffect,
kHasNoSideEffect,
kHasSideEffectToReceiver
};
/**
* Keys/Properties filter enums:
*
* KeyCollectionMode limits the range of collected properties. kOwnOnly limits
* the collected properties to the given Object only. kIncludesPrototypes will
* include all keys of the objects's prototype chain as well.
*/
enum class KeyCollectionMode { kOwnOnly, kIncludePrototypes };
/**
* kIncludesIndices allows for integer indices to be collected, while
* kSkipIndices will exclude integer indices from being collected.
*/
enum class IndexFilter { kIncludeIndices, kSkipIndices };
/**
* kConvertToString will convert integer indices to strings.
* kKeepNumbers will return numbers for integer indices.
*/
enum class KeyConversionMode { kConvertToString, kKeepNumbers, kNoNumbers };
/**
* Integrity level for objects.
*/
enum class IntegrityLevel { kFrozen, kSealed };
/**
* A JavaScript object (ECMA-262, 4.3.3)
*/
class V8_EXPORT Object : public Value {
public:
/**
* Set only return Just(true) or Empty(), so if it should never fail, use
* result.Check().
*/
V8_WARN_UNUSED_RESULT Maybe Set(Local context,
Local key, Local value);
V8_WARN_UNUSED_RESULT Maybe Set(Local context, uint32_t index,
Local value);
/**
* Implements CreateDataProperty(O, P, V), see
* https://tc39.es/ecma262/#sec-createdataproperty.
*
* Defines a configurable, writable, enumerable property with the given value
* on the object unless the property already exists and is not configurable
* or the object is not extensible.
*
* Returns true on success.
*/
V8_WARN_UNUSED_RESULT Maybe CreateDataProperty(Local context,
Local key,
Local value);
V8_WARN_UNUSED_RESULT Maybe CreateDataProperty(Local context,
uint32_t index,
Local value);
/**
* Implements [[DefineOwnProperty]] for data property case, see
* https://tc39.es/ecma262/#table-essential-internal-methods.
*
* In general, CreateDataProperty will be faster, however, does not allow
* for specifying attributes.
*
* Returns true on success.
*/
V8_WARN_UNUSED_RESULT Maybe DefineOwnProperty(
Local context, Local key, Local value,
PropertyAttribute attributes = None);
/**
* Implements Object.defineProperty(O, P, Attributes), see
* https://tc39.es/ecma262/#sec-object.defineproperty.
*
* The defineProperty function is used to add an own property or
* update the attributes of an existing own property of an object.
*
* Both data and accessor descriptors can be used.
*
* In general, CreateDataProperty is faster, however, does not allow
* for specifying attributes or an accessor descriptor.
*
* The PropertyDescriptor can change when redefining a property.
*
* Returns true on success.
*/
V8_WARN_UNUSED_RESULT Maybe DefineProperty(
Local context, Local key, PropertyDescriptor& descriptor);
V8_WARN_UNUSED_RESULT MaybeLocal Get(Local context,
Local key);
V8_WARN_UNUSED_RESULT MaybeLocal Get(Local context,
uint32_t index);
/**
* Gets the property attributes of a property which can be None or
* any combination of ReadOnly, DontEnum and DontDelete. Returns
* None when the property doesn't exist.
*/
V8_WARN_UNUSED_RESULT Maybe GetPropertyAttributes(
Local context, Local key);
/**
* Implements Object.getOwnPropertyDescriptor(O, P), see
* https://tc39.es/ecma262/#sec-object.getownpropertydescriptor.
*/
V8_WARN_UNUSED_RESULT MaybeLocal GetOwnPropertyDescriptor(
Local context, Local key);
/**
* Object::Has() calls the abstract operation HasProperty(O, P), see
* https://tc39.es/ecma262/#sec-hasproperty. Has() returns
* true, if the object has the property, either own or on the prototype chain.
* Interceptors, i.e., PropertyQueryCallbacks, are called if present.
*
* Has() has the same side effects as JavaScript's `variable in object`.
* For example, calling Has() on a revoked proxy will throw an exception.
*
* \note Has() converts the key to a name, which possibly calls back into
* JavaScript.
*
* See also v8::Object::HasOwnProperty() and
* v8::Object::HasRealNamedProperty().
*/
V8_WARN_UNUSED_RESULT Maybe Has(Local context,
Local key);
V8_WARN_UNUSED_RESULT Maybe Delete(Local context,
Local key);
V8_WARN_UNUSED_RESULT Maybe Has(Local context, uint32_t index);
V8_WARN_UNUSED_RESULT Maybe Delete(Local context,
uint32_t index);
V8_DEPRECATE_SOON("Use SetNativeDataProperty instead")
V8_WARN_UNUSED_RESULT Maybe SetAccessor(
Local context, Local name,
AccessorNameGetterCallback getter,
AccessorNameSetterCallback setter = nullptr,
MaybeLocal data = MaybeLocal(),
AccessControl deprecated_settings = DEFAULT,
PropertyAttribute attribute = None,
SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
void SetAccessorProperty(Local name, Local getter,
Local setter = Local(),
PropertyAttribute attributes = None);
/**
* Sets a native data property like Template::SetNativeDataProperty, but
* this method sets on this object directly.
*/
V8_WARN_UNUSED_RESULT Maybe SetNativeDataProperty(
Local context, Local name,
AccessorNameGetterCallback getter,
AccessorNameSetterCallback setter = nullptr,
Local data = Local(), PropertyAttribute attributes = None,
SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
/**
* Attempts to create a property with the given name which behaves like a data
* property, except that the provided getter is invoked (and provided with the
* data value) to supply its value the first time it is read. After the
* property is accessed once, it is replaced with an ordinary data property.
*
* Analogous to Template::SetLazyDataProperty.
*/
V8_WARN_UNUSED_RESULT Maybe SetLazyDataProperty(
Local context, Local name,
AccessorNameGetterCallback getter, Local data = Local(),
PropertyAttribute attributes = None,
SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
/**
* Functionality for private properties.
* This is an experimental feature, use at your own risk.
* Note: Private properties are not inherited. Do not rely on this, since it
* may change.
*/
Maybe HasPrivate(Local context, Local key);
Maybe SetPrivate(Local context, Local key,
Local value);
Maybe DeletePrivate(Local context, Local key);
MaybeLocal GetPrivate(Local context, Local key);
/**
* Returns an array containing the names of the enumerable properties
* of this object, including properties from prototype objects. The
* array returned by this method contains the same values as would
* be enumerated by a for-in statement over this object.
*/
V8_WARN_UNUSED_RESULT MaybeLocal GetPropertyNames(
Local context);
V8_WARN_UNUSED_RESULT MaybeLocal GetPropertyNames(
Local context, KeyCollectionMode mode,
PropertyFilter property_filter, IndexFilter index_filter,
KeyConversionMode key_conversion = KeyConversionMode::kKeepNumbers);
/**
* This function has the same functionality as GetPropertyNames but
* the returned array doesn't contain the names of properties from
* prototype objects.
*/
V8_WARN_UNUSED_RESULT MaybeLocal GetOwnPropertyNames(
Local context);
/**
* Returns an array containing the names of the filtered properties
* of this object, including properties from prototype objects. The
* array returned by this method contains the same values as would
* be enumerated by a for-in statement over this object.
*/
V8_WARN_UNUSED_RESULT MaybeLocal GetOwnPropertyNames(
Local context, PropertyFilter filter,
KeyConversionMode key_conversion = KeyConversionMode::kKeepNumbers);
/**
* Get the prototype object. This does not skip objects marked to
* be skipped by __proto__ and it does not consult the security
* handler.
*/
Local GetPrototype();
/**
* Set the prototype object. This does not skip objects marked to
* be skipped by __proto__ and it does not consult the security
* handler.
*/
V8_WARN_UNUSED_RESULT Maybe SetPrototype(Local context,
Local prototype);
/**
* Finds an instance of the given function template in the prototype
* chain.
*/
Local