v8-template.h

Go to the documentation of this file.

// 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_TEMPLATE_H_
#define INCLUDE_V8_TEMPLATE_H_
 
#include <cstddef>
#include <span>
#include <string_view>
 
#include "v8-data.h"               // NOLINT(build/include_directory)
#include "v8-exception.h"          // NOLINT(build/include_directory)
#include "v8-function-callback.h"  // NOLINT(build/include_directory)
#include "v8-local-handle.h"       // NOLINT(build/include_directory)
#include "v8-object.h"             // NOLINT(build/include_directory)
#include "v8config.h"              // NOLINT(build/include_directory)
 
namespace v8 {
 
class CFunction;
class FunctionTemplate;
class ObjectTemplate;
class Signature;
 
// --- Templates ---
 
#define V8_INTRINSICS_LIST(F)                                 \
  F(ArrayProto_entries, array_entries_iterator)               \
  F(ArrayProto_forEach, array_for_each_iterator)              \
  F(ArrayProto_keys, array_keys_iterator)                     \
  F(ArrayProto_values, array_values_iterator)                 \
  F(ArrayPrototype, initial_array_prototype)                  \
  F(AsyncIteratorPrototype, initial_async_iterator_prototype) \
  F(ErrorPrototype, initial_error_prototype)                  \
  F(IteratorPrototype, initial_iterator_prototype)            \
  F(MapIteratorPrototype, initial_map_iterator_prototype)     \
  F(ObjProto_valueOf, object_value_of_function)               \
  F(SetIteratorPrototype, initial_set_iterator_prototype)
 
enum Intrinsic {
#define V8_DECL_INTRINSIC(name, iname) k##name,
  V8_INTRINSICS_LIST(V8_DECL_INTRINSIC)
#undef V8_DECL_INTRINSIC
};
 
class V8_EXPORT Template : public Data {
 public:
  void Set(Local<Name> name, Local<Data> value,
           PropertyAttribute attributes = None);
  void SetPrivate(Local<Private> name, Local<Data> value,
                  PropertyAttribute attributes = None);
  V8_INLINE void Set(Isolate* isolate, const char* name, Local<Data> value,
                     PropertyAttribute attributes = None);
 
  void SetAccessorProperty(
      Local<Name> name,
      Local<FunctionTemplate> getter = Local<FunctionTemplate>(),
      Local<FunctionTemplate> setter = Local<FunctionTemplate>(),
      PropertyAttribute attribute = None);
 
  void SetNativeDataProperty(
      Local<Name> name, AccessorNameGetterCallback getter,
      AccessorNameSetterCallbackV2 setter = nullptr,
      Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
      SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
      SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
 
  void SetLazyDataProperty(
      Local<Name> name, AccessorNameGetterCallback getter,
      Local<Value> data = Local<Value>(), PropertyAttribute attribute = None,
      SideEffectType getter_side_effect_type = SideEffectType::kHasSideEffect,
      SideEffectType setter_side_effect_type = SideEffectType::kHasSideEffect);
 
  void SetIntrinsicDataProperty(Local<Name> name, Intrinsic intrinsic,
                                PropertyAttribute attribute = None);
 
 private:
  Template();
 
  friend class ObjectTemplate;
  friend class FunctionTemplate;
};
 
enum class Intercepted : uint32_t { kNo = 1, kYes = 0 };
 
using NamedPropertyGetterCallback = Intercepted (*)(
    Local<Name> property, const PropertyCallbackInfo<Value>& info);
 
using NamedPropertySetterCallbackV2 =
    Intercepted (*)(Local<Name> property, Local<Value> value,
                    const PropertyCallbackInfo<Boolean>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using NamedPropertySetterCallback  //
    V8_DEPRECATE_SOON("Use NamedPropertySetterCallbackV2 instead.") =
        Intercepted (*)(Local<Name> property, Local<Value> value,
                        const PropertyCallbackInfo<void>& info);
 
using NamedPropertyQueryCallback = Intercepted (*)(
    Local<Name> property, const PropertyCallbackInfo<Integer>& info);
 
using NamedPropertyDeleterCallback = Intercepted (*)(
    Local<Name> property, const PropertyCallbackInfo<Boolean>& info);
 
using NamedPropertyEnumeratorCallback =
    void (*)(const PropertyCallbackInfo<Array>& info);
 
using NamedPropertyDefinerCallbackV2 =
    Intercepted (*)(Local<Name> property, const PropertyDescriptor& desc,
                    const PropertyCallbackInfo<Boolean>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using NamedPropertyDefinerCallback  //
    V8_DEPRECATE_SOON("Use NamedPropertyDefinerCallbackV2 instead.") =
        Intercepted (*)(Local<Name> property, const PropertyDescriptor& desc,
                        const PropertyCallbackInfo<void>& info);
 
using NamedPropertyDescriptorCallback = Intercepted (*)(
    Local<Name> property, const PropertyCallbackInfo<Value>& info);
 
using IndexedPropertyGetterCallback =
    Intercepted (*)(uint32_t index, const PropertyCallbackInfo<Value>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using IndexedPropertyGetterCallbackV2  //
    V8_DEPRECATE_SOON("Use IndexedPropertyGetterCallback instead.") =
        IndexedPropertyGetterCallback;
 
using IndexedPropertySetterCallback =
    Intercepted (*)(uint32_t index, Local<Value> value,
                    const PropertyCallbackInfo<Boolean>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using IndexedPropertySetterCallbackV2  //
    V8_DEPRECATE_SOON("Use IndexedPropertySetterCallback instead.") =
        Intercepted (*)(uint32_t index, Local<Value> value,
                        const PropertyCallbackInfo<void>& info);
 
using IndexedPropertyQueryCallback =
    Intercepted (*)(uint32_t index, const PropertyCallbackInfo<Integer>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using IndexedPropertyQueryCallbackV2  //
    V8_DEPRECATE_SOON("Use IndexedPropertyQueryCallback instead.") =
        IndexedPropertyQueryCallback;
 
using IndexedPropertyDeleterCallback =
    Intercepted (*)(uint32_t index, const PropertyCallbackInfo<Boolean>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using IndexedPropertyDeleterCallbackV2  //
    V8_DEPRECATE_SOON("Use IndexedPropertyDeleterCallback instead.") =
        IndexedPropertyDeleterCallback;
 
using IndexedPropertyEnumeratorCallback =
    void (*)(const PropertyCallbackInfo<Array>& info);
 
using IndexedPropertyDefinerCallback =
    Intercepted (*)(uint32_t index, const PropertyDescriptor& desc,
                    const PropertyCallbackInfo<Boolean>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using IndexedPropertyDefinerCallbackV2  //
    V8_DEPRECATE_SOON("Use IndexedPropertyDefinerCallback instead.") =
        Intercepted (*)(uint32_t index, const PropertyDescriptor& desc,
                        const PropertyCallbackInfo<void>& info);
 
using IndexedPropertyDescriptorCallback =
    Intercepted (*)(uint32_t index, const PropertyCallbackInfo<Value>& info);
// TODO(https://crbug.com/348660658): deprecate and remove.
using IndexedPropertyDescriptorCallbackV2  //
    V8_DEPRECATE_SOON("Use IndexedPropertyDescriptorCallback instead.") =
        IndexedPropertyDescriptorCallback;
 
using IndexedPropertyIndexOfCallback =
    uint32_t (*)(Local<Value> value, uint32_t start_index, uint32_t end_index,
                 uint32_t* out_length, const PropertyCallbackInfo<void>& info);
 
using IndexedPropertyIterableToListCallback =
    void (*)(const PropertyCallbackInfo<Value>& info);
 
using AccessCheckCallback = bool (*)(Local<Context> accessing_context,
                                     Local<Object> accessed_object,
                                     Local<Value> data);
 
enum class ConstructorBehavior { kThrow, kAllow };
 
class V8_EXPORT FunctionTemplate : public Template {
 public:
  static Local<FunctionTemplate> New(
      Isolate* isolate, FunctionCallback callback = nullptr,
      Local<Value> data = Local<Value>(),
      Local<Signature> signature = Local<Signature>(), int length = 0,
      ConstructorBehavior behavior = ConstructorBehavior::kAllow,
      SideEffectType side_effect_type = SideEffectType::kHasSideEffect,
      const CFunction* c_function = nullptr, uint16_t instance_type = 0,
      uint16_t allowed_receiver_instance_type_range_start = 0,
      uint16_t allowed_receiver_instance_type_range_end = 0);
 
  static Local<FunctionTemplate> NewWithCFunctionOverloads(
      Isolate* isolate, FunctionCallback callback = nullptr,
      Local<Value> data = Local<Value>(),
      Local<Signature> signature = Local<Signature>(), int length = 0,
      ConstructorBehavior behavior = ConstructorBehavior::kAllow,
      SideEffectType side_effect_type = SideEffectType::kHasSideEffect,
      const std::span<const CFunction>& c_function_overloads = {});
 
  static Local<FunctionTemplate> NewWithCache(
      Isolate* isolate, FunctionCallback callback,
      Local<Private> cache_property, Local<Value> data = Local<Value>(),
      Local<Signature> signature = Local<Signature>(), int length = 0,
      SideEffectType side_effect_type = SideEffectType::kHasSideEffect);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Function> GetFunction(
      Local<Context> context);
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewRemoteInstance();
 
  void SetCallHandler(
      FunctionCallback callback, Local<Data> data = {},
      SideEffectType side_effect_type = SideEffectType::kHasSideEffect,
      const std::span<const CFunction>& c_function_overloads = {});
 
  void SetLength(int length);
 
  Local<ObjectTemplate> InstanceTemplate();
 
  void Inherit(Local<FunctionTemplate> parent);
 
  Local<ObjectTemplate> PrototypeTemplate();
 
  void SetPrototypeProviderTemplate(Local<FunctionTemplate> prototype_provider);
 
  void SetClassName(Local<String> name);
 
  void SetInterfaceName(Local<String> name);
 
  void SetExceptionContext(ExceptionContext context);
 
  void SetAcceptAnyReceiver(bool value);
 
  void ReadOnlyPrototype();
 
  void RemovePrototype();
 
  bool HasInstance(Local<Value> object);
 
  bool IsLeafTemplateForApiObject(v8::Local<v8::Value> value) const;
 
  void SealAndPrepareForPromotionToReadOnly();
 
  V8_INLINE static FunctionTemplate* Cast(Data* data);
 
 private:
  FunctionTemplate();
 
  static void CheckCast(Data* that);
  friend class Context;
  friend class ObjectTemplate;
};
 
enum class PropertyHandlerFlags {
  kNone = 0,
 
  kNonMasking = 1,
 
  kOnlyInterceptStrings = 1 << 1,
 
  kHasNoSideEffect = 1 << 2,
 
  kHasDontDeleteProperty = 1 << 3,
 
  kInternalNewCallbacksSignatures = 1 << 10,
};
 
struct NamedPropertyHandlerConfiguration {
 private:
  static constexpr PropertyHandlerFlags WithNewSignatureFlag(
      PropertyHandlerFlags flags) {
    return static_cast<PropertyHandlerFlags>(
        static_cast<int>(flags) |
        static_cast<int>(
            PropertyHandlerFlags::kInternalNewCallbacksSignatures));
  }
 
 public:
  NamedPropertyHandlerConfiguration(
      NamedPropertyGetterCallback getter,          //
      NamedPropertySetterCallbackV2 setter,        //
      NamedPropertyQueryCallback query,            //
      NamedPropertyDeleterCallback deleter,        //
      NamedPropertyEnumeratorCallback enumerator,  //
      NamedPropertyDefinerCallbackV2 definer,      //
      NamedPropertyDescriptorCallback descriptor,  //
      Local<Value> data = Local<Value>(),
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(query),
        deleter(deleter),
        enumerator(enumerator),
        definer(definer),
        descriptor(descriptor),
        data(data),
        flags(flags) {}
 
  explicit NamedPropertyHandlerConfiguration(
      NamedPropertyGetterCallback getter,                    //
      NamedPropertySetterCallbackV2 setter = nullptr,        //
      NamedPropertyQueryCallback query = nullptr,            //
      NamedPropertyDeleterCallback deleter = nullptr,        //
      NamedPropertyEnumeratorCallback enumerator = nullptr,  //
      Local<Value> data = Local<Value>(),
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(query),
        deleter(deleter),
        enumerator(enumerator),
        definer(nullptr),
        descriptor(nullptr),
        data(data),
        flags(flags) {}
 
  NamedPropertyHandlerConfiguration(
      NamedPropertyGetterCallback getter,          //
      NamedPropertySetterCallbackV2 setter,        //
      NamedPropertyDescriptorCallback descriptor,  //
      NamedPropertyDeleterCallback deleter,        //
      NamedPropertyEnumeratorCallback enumerator,  //
      NamedPropertyDefinerCallbackV2 definer,      //
      Local<Value> data = Local<Value>(),
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(nullptr),
        deleter(deleter),
        enumerator(enumerator),
        definer(definer),
        descriptor(descriptor),
        data(data),
        flags(flags) {}
 
  NamedPropertyGetterCallback getter;
  NamedPropertySetterCallbackV2 setter;
  NamedPropertyQueryCallback query;
  NamedPropertyDeleterCallback deleter;
  NamedPropertyEnumeratorCallback enumerator;
  NamedPropertyDefinerCallbackV2 definer;
  NamedPropertyDescriptorCallback descriptor;
  Local<Value> data;
  PropertyHandlerFlags flags;
};
 
struct IndexedPropertyHandlerConfiguration {
 private:
  static constexpr PropertyHandlerFlags WithNewSignatureFlag(
      PropertyHandlerFlags flags) {
    return static_cast<PropertyHandlerFlags>(
        static_cast<int>(flags) |
        static_cast<int>(
            PropertyHandlerFlags::kInternalNewCallbacksSignatures));
  }
 
 public:
  IndexedPropertyHandlerConfiguration(
      IndexedPropertyGetterCallback getter,          //
      IndexedPropertySetterCallback setter,          //
      IndexedPropertyQueryCallback query,            //
      IndexedPropertyDeleterCallback deleter,        //
      IndexedPropertyEnumeratorCallback enumerator,  //
      IndexedPropertyDefinerCallback definer,        //
      IndexedPropertyDescriptorCallback descriptor,  //
      Local<Value> data = Local<Value>(),
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(query),
        deleter(deleter),
        enumerator(enumerator),
        definer(definer),
        descriptor(descriptor),
        data(data),
        flags(flags) {}
 
  explicit IndexedPropertyHandlerConfiguration(
      IndexedPropertyGetterCallback getter = nullptr,          //
      IndexedPropertySetterCallback setter = nullptr,          //
      IndexedPropertyQueryCallback query = nullptr,            //
      IndexedPropertyDeleterCallback deleter = nullptr,        //
      IndexedPropertyEnumeratorCallback enumerator = nullptr,  //
      Local<Value> data = Local<Value>(),                      //
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(query),
        deleter(deleter),
        enumerator(enumerator),
        definer(nullptr),
        descriptor(nullptr),
        data(data),
        flags(flags) {}
 
  IndexedPropertyHandlerConfiguration(
      IndexedPropertyGetterCallback getter,          //
      IndexedPropertySetterCallback setter,          //
      IndexedPropertyDescriptorCallback descriptor,  //
      IndexedPropertyDeleterCallback deleter,        //
      IndexedPropertyEnumeratorCallback enumerator,  //
      IndexedPropertyDefinerCallback definer,        //
      Local<Value> data = Local<Value>(),
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(nullptr),
        deleter(deleter),
        enumerator(enumerator),
        definer(definer),
        descriptor(descriptor),
        data(data),
        flags(flags) {}
 
  V8_DEPRECATE_SOON(
      "Use IndexedPropertyHandlerConfiguration with iterable_to_list")
  IndexedPropertyHandlerConfiguration(
      IndexedPropertyGetterCallback getter,          //
      IndexedPropertySetterCallback setter,          //
      IndexedPropertyQueryCallback query,            //
      IndexedPropertyDeleterCallback deleter,        //
      IndexedPropertyEnumeratorCallback enumerator,  //
      IndexedPropertyDefinerCallback definer,        //
      IndexedPropertyDescriptorCallback descriptor,  //
      IndexedPropertyIndexOfCallback index_of,       //
      Local<Value> data = Local<Value>(),
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(query),
        deleter(deleter),
        enumerator(enumerator),
        definer(definer),
        descriptor(descriptor),
        index_of(index_of),
        iterable_to_list(nullptr),
        data(data),
        flags(flags) {}
 
  IndexedPropertyHandlerConfiguration(
      IndexedPropertyGetterCallback getter,          //
      IndexedPropertySetterCallback setter,          //
      IndexedPropertyQueryCallback query,            //
      IndexedPropertyDeleterCallback deleter,        //
      IndexedPropertyEnumeratorCallback enumerator,  //
      IndexedPropertyDefinerCallback definer,        //
      IndexedPropertyDescriptorCallback descriptor,  //
      IndexedPropertyIndexOfCallback index_of,       //
      IndexedPropertyIterableToListCallback iterable_to_list,
      Local<Value> data = Local<Value>(),
      PropertyHandlerFlags flags = PropertyHandlerFlags::kNone)
      : getter(getter),
        setter(setter),
        query(query),
        deleter(deleter),
        enumerator(enumerator),
        definer(definer),
        descriptor(descriptor),
        index_of(index_of),
        iterable_to_list(iterable_to_list),
        data(data),
        flags(flags) {}
 
  IndexedPropertyGetterCallback getter;
  IndexedPropertySetterCallback setter;
  IndexedPropertyQueryCallback query;
  IndexedPropertyDeleterCallback deleter;
  IndexedPropertyEnumeratorCallback enumerator;
  IndexedPropertyDefinerCallback definer;
  IndexedPropertyDescriptorCallback descriptor;
  IndexedPropertyIndexOfCallback index_of = nullptr;
  IndexedPropertyIterableToListCallback iterable_to_list = nullptr;
  Local<Value> data;
  PropertyHandlerFlags flags;
};
 
class V8_EXPORT ObjectTemplate : public Template {
 public:
  static Local<ObjectTemplate> New(
      Isolate* isolate,
      Local<FunctionTemplate> constructor = Local<FunctionTemplate>());
 
  V8_WARN_UNUSED_RESULT MaybeLocal<Object> NewInstance(Local<Context> context);
 
  void SetHandler(const NamedPropertyHandlerConfiguration& configuration);
 
  void SetHandler(const IndexedPropertyHandlerConfiguration& configuration);
 
  void SetCallAsFunctionHandler(FunctionCallback callback,
                                Local<Value> data = Local<Value>());
 
  void MarkAsUndetectable();
 
  void SetAccessCheckCallback(AccessCheckCallback callback,
                              Local<Value> data = Local<Value>());
 
  void SetAccessCheckCallbackAndHandler(
      AccessCheckCallback callback,
      const NamedPropertyHandlerConfiguration& named_handler,
      const IndexedPropertyHandlerConfiguration& indexed_handler,
      Local<Value> data = Local<Value>());
 
  int InternalFieldCount() const;
 
  void SetInternalFieldCount(int value);
 
  bool IsImmutableProto() const;
 
  void SetImmutableProto();
 
  void SetCodeLike();
  bool IsCodeLike() const;
 
  void SealAndPrepareForPromotionToReadOnly();
 
  V8_INLINE static ObjectTemplate* Cast(Data* data);
 
 private:
  ObjectTemplate();
 
  static void CheckCast(Data* that);
  friend class FunctionTemplate;
};
 
class V8_EXPORT DictionaryTemplate final : public Data {
 public:
  static Local<DictionaryTemplate> New(Isolate* isolate,
                                       std::span<const std::string_view> names);
 
  V8_WARN_UNUSED_RESULT Local<Object> NewInstance(
      Local<Context> context, std::span<MaybeLocal<Value>> property_values);
 
  V8_INLINE static DictionaryTemplate* Cast(Data* data);
 
 private:
  static void CheckCast(Data* that);
 
  DictionaryTemplate();
};
 
class V8_EXPORT Signature : public Data {
 public:
  static Local<Signature> New(
      Isolate* isolate,
      Local<FunctionTemplate> receiver = Local<FunctionTemplate>());
 
  V8_INLINE static Signature* Cast(Data* data);
 
 private:
  Signature();
 
  static void CheckCast(Data* that);
};
 
// --- Implementation ---
 
void Template::Set(Isolate* isolate, const char* name, Local<Data> value,
                   PropertyAttribute attributes) {
  Set(String::NewFromUtf8(isolate, name, NewStringType::kInternalized)
          .ToLocalChecked(),
      value, attributes);
}
 
FunctionTemplate* FunctionTemplate::Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return reinterpret_cast<FunctionTemplate*>(data);
}
 
ObjectTemplate* ObjectTemplate::Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return reinterpret_cast<ObjectTemplate*>(data);
}
 
DictionaryTemplate* DictionaryTemplate::Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return reinterpret_cast<DictionaryTemplate*>(data);
}
 
Signature* Signature::Cast(Data* data) {
#ifdef V8_ENABLE_CHECKS
  CheckCast(data);
#endif
  return reinterpret_cast<Signature*>(data);
}
 
}  // namespace v8
 
#endif  // INCLUDE_V8_TEMPLATE_H_