musix-oss/node_modules/nan/doc/methods.md

JavaScript-accessible methods

A template is a blueprint for JavaScript functions and objects in a context. You can use a template to wrap C++ functions and data structures within JavaScript objects so that they can be manipulated from JavaScript. See the V8 Embedders Guide section on Templates for further information.

In order to expose functionality to JavaScript via a template, you must provide it to V8 in a form that it understands. Across the versions of V8 supported by NAN, JavaScript-accessible method signatures vary widely, NAN fully abstracts method declaration and provides you with an interface that is similar to the most recent V8 API but is backward-compatible with older versions that still use the now-deceased v8::Argument type.

• Method argument types

• Nan::FunctionCallbackInfo
• Nan::PropertyCallbackInfo
• Nan::ReturnValue

• Method declarations

• Method declaration
• Getter declaration
• Setter declaration
• Property getter declaration
• Property setter declaration
• Property enumerator declaration
• Property deleter declaration
• Property query declaration
• Index getter declaration
• Index setter declaration
• Index enumerator declaration
• Index deleter declaration
• Index query declaration

• Method and template helpers

• Nan::SetMethod()
• Nan::SetPrototypeMethod()
• Nan::SetAccessor()
• Nan::SetNamedPropertyHandler()
• Nan::SetIndexedPropertyHandler()
• Nan::SetTemplate()
• Nan::SetPrototypeTemplate()
• Nan::SetInstanceTemplate()
• Nan::SetCallHandler()
• Nan::SetCallAsFunctionHandler()

Nan::FunctionCallbackInfo

Nan::FunctionCallbackInfo should be used in place of v8::FunctionCallbackInfo, even with older versions of Node where v8::FunctionCallbackInfo does not exist.

Definition:

template<typename T> class FunctionCallbackInfo {
 public:
  ReturnValue<T> GetReturnValue() const;
  v8::Local<v8::Function> Callee(); // NOTE: Not available in NodeJS >= 10.0.0
  v8::Local<v8::Value> Data();
  v8::Local<v8::Object> Holder();
  bool IsConstructCall();
  int Length() const;
  v8::Local<v8::Value> operator[](int i) const;
  v8::Local<v8::Object> This() const;
  v8::Isolate *GetIsolate() const;
};

See the v8::FunctionCallbackInfo documentation for usage details on these. See Nan::ReturnValue for further information on how to set a return value from methods.

Note: FunctionCallbackInfo::Callee is removed in Node.js after 10.0.0 because it is was deprecated in V8. Consider using info.Data() to pass any information you need.

Nan::PropertyCallbackInfo

Nan::PropertyCallbackInfo should be used in place of v8::PropertyCallbackInfo, even with older versions of Node where v8::PropertyCallbackInfo does not exist.

Definition:

template<typename T> class PropertyCallbackInfo : public PropertyCallbackInfoBase<T> {
 public:
  ReturnValue<T> GetReturnValue() const;
  v8::Isolate* GetIsolate() const;
  v8::Local<v8::Value> Data() const;
  v8::Local<v8::Object> This() const;
  v8::Local<v8::Object> Holder() const;
};

See the v8::PropertyCallbackInfo documentation for usage details on these. See Nan::ReturnValue for further information on how to set a return value from property accessor methods.

Nan::ReturnValue

Nan::ReturnValue is used in place of v8::ReturnValue on both Nan::FunctionCallbackInfo and Nan::PropertyCallbackInfo as the return type of GetReturnValue().

Example usage:

void EmptyArray(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  info.GetReturnValue().Set(Nan::New<v8::Array>());
}

Definition:

template<typename T> class ReturnValue {
 public:
  // Handle setters
  template <typename S> void Set(const v8::Local<S> &handle);
  template <typename S> void Set(const Nan::Global<S> &handle);

  // Fast primitive setters
  void Set(bool value);
  void Set(double i);
  void Set(int32_t i);
  void Set(uint32_t i);

  // Fast JS primitive setters
  void SetNull();
  void SetUndefined();
  void SetEmptyString();

  // Convenience getter for isolate
  v8::Isolate *GetIsolate() const;
};

See the documentation on v8::ReturnValue for further information on this.

Method declaration

JavaScript-accessible methods should be declared with the following signature to form a Nan::FunctionCallback:

typedef void(*FunctionCallback)(const FunctionCallbackInfo<v8::Value>&);

Example:

void MethodName(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  ...
}

You do not need to declare a new HandleScope within a method as one is implicitly created for you.

Example usage

// .h:
class Foo : public Nan::ObjectWrap {
  ...

  static void Bar(const Nan::FunctionCallbackInfo<v8::Value>& info);
  static void Baz(const Nan::FunctionCallbackInfo<v8::Value>& info);
}


// .cc:
void Foo::Bar(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  ...
}

void Foo::Baz(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  ...
}

A helper macro NAN_METHOD(methodname) exists, compatible with NAN v1 method declarations.

Example usage with NAN_METHOD(methodname)

// .h:
class Foo : public Nan::ObjectWrap {
  ...

  static NAN_METHOD(Bar);
  static NAN_METHOD(Baz);
}


// .cc:
NAN_METHOD(Foo::Bar) {
  ...
}

NAN_METHOD(Foo::Baz) {
  ...
}

Use Nan::SetPrototypeMethod to attach a method to a JavaScript function prototype or Nan::SetMethod to attach a method directly on a JavaScript object.

Getter declaration

JavaScript-accessible getters should be declared with the following signature to form a Nan::GetterCallback:

typedef void(*GetterCallback)(v8::Local<v8::String>,
                              const PropertyCallbackInfo<v8::Value>&);

Example:

void GetterName(v8::Local<v8::String> property,
                const Nan::PropertyCallbackInfo<v8::Value>& info) {
  ...
}

You do not need to declare a new HandleScope within a getter as one is implicitly created for you.

A helper macro NAN_GETTER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on Accessors.

Setter declaration

JavaScript-accessible setters should be declared with the following signature to form a Nan::SetterCallback:

typedef void(*SetterCallback)(v8::Local<v8::String>,
                              v8::Local<v8::Value>,
                              const PropertyCallbackInfo<void>&);

Example:

void SetterName(v8::Local<v8::String> property,
                v8::Local<v8::Value> value,
                const Nan::PropertyCallbackInfo<void>& info) {
  ...
}

You do not need to declare a new HandleScope within a setter as one is implicitly created for you.

A helper macro NAN_SETTER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on Accessors.

Property getter declaration

JavaScript-accessible property getters should be declared with the following signature to form a Nan::PropertyGetterCallback:

typedef void(*PropertyGetterCallback)(v8::Local<v8::String>,
                                      const PropertyCallbackInfo<v8::Value>&);

Example:

void PropertyGetterName(v8::Local<v8::String> property,
                        const Nan::PropertyCallbackInfo<v8::Value>& info) {
  ...
}

You do not need to declare a new HandleScope within a property getter as one is implicitly created for you.

A helper macro NAN_PROPERTY_GETTER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on named property Interceptors.

Property setter declaration

JavaScript-accessible property setters should be declared with the following signature to form a Nan::PropertySetterCallback:

typedef void(*PropertySetterCallback)(v8::Local<v8::String>,
                                      v8::Local<v8::Value>,
                                      const PropertyCallbackInfo<v8::Value>&);

Example:

void PropertySetterName(v8::Local<v8::String> property,
                        v8::Local<v8::Value> value,
                        const Nan::PropertyCallbackInfo<v8::Value>& info);

You do not need to declare a new HandleScope within a property setter as one is implicitly created for you.

A helper macro NAN_PROPERTY_SETTER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on named property Interceptors.

Property enumerator declaration

JavaScript-accessible property enumerators should be declared with the following signature to form a Nan::PropertyEnumeratorCallback:

typedef void(*PropertyEnumeratorCallback)(const PropertyCallbackInfo<v8::Array>&);

Example:

void PropertyEnumeratorName(const Nan::PropertyCallbackInfo<v8::Array>& info);

You do not need to declare a new HandleScope within a property enumerator as one is implicitly created for you.

A helper macro NAN_PROPERTY_ENUMERATOR(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on named property Interceptors.

Property deleter declaration

JavaScript-accessible property deleters should be declared with the following signature to form a Nan::PropertyDeleterCallback:

typedef void(*PropertyDeleterCallback)(v8::Local<v8::String>,
                                       const PropertyCallbackInfo<v8::Boolean>&);

Example:

void PropertyDeleterName(v8::Local<v8::String> property,
                         const Nan::PropertyCallbackInfo<v8::Boolean>& info);

You do not need to declare a new HandleScope within a property deleter as one is implicitly created for you.

A helper macro NAN_PROPERTY_DELETER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on named property Interceptors.

Property query declaration

JavaScript-accessible property query methods should be declared with the following signature to form a Nan::PropertyQueryCallback:

typedef void(*PropertyQueryCallback)(v8::Local<v8::String>,
                                     const PropertyCallbackInfo<v8::Integer>&);

Example:

void PropertyQueryName(v8::Local<v8::String> property,
                       const Nan::PropertyCallbackInfo<v8::Integer>& info);

You do not need to declare a new HandleScope within a property query method as one is implicitly created for you.

A helper macro NAN_PROPERTY_QUERY(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on named property Interceptors.

Index getter declaration

JavaScript-accessible index getter methods should be declared with the following signature to form a Nan::IndexGetterCallback:

typedef void(*IndexGetterCallback)(uint32_t,
                                   const PropertyCallbackInfo<v8::Value>&);

Example:

void IndexGetterName(uint32_t index, const PropertyCallbackInfo<v8::Value>& info);

You do not need to declare a new HandleScope within a index getter as one is implicitly created for you.

A helper macro NAN_INDEX_GETTER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on indexed property Interceptors.

Index setter declaration

JavaScript-accessible index setter methods should be declared with the following signature to form a Nan::IndexSetterCallback:

typedef void(*IndexSetterCallback)(uint32_t,
                                   v8::Local<v8::Value>,
                                   const PropertyCallbackInfo<v8::Value>&);

Example:

void IndexSetterName(uint32_t index,
                     v8::Local<v8::Value> value,
                     const PropertyCallbackInfo<v8::Value>& info);

You do not need to declare a new HandleScope within a index setter as one is implicitly created for you.

A helper macro NAN_INDEX_SETTER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on indexed property Interceptors.

Index enumerator declaration

JavaScript-accessible index enumerator methods should be declared with the following signature to form a Nan::IndexEnumeratorCallback:

typedef void(*IndexEnumeratorCallback)(const PropertyCallbackInfo<v8::Array>&);

Example:

void IndexEnumeratorName(const PropertyCallbackInfo<v8::Array>& info);

You do not need to declare a new HandleScope within a index enumerator as one is implicitly created for you.

A helper macro NAN_INDEX_ENUMERATOR(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on indexed property Interceptors.

Index deleter declaration

JavaScript-accessible index deleter methods should be declared with the following signature to form a Nan::IndexDeleterCallback:

typedef void(*IndexDeleterCallback)(uint32_t,
                                    const PropertyCallbackInfo<v8::Boolean>&);

Example:

void IndexDeleterName(uint32_t index, const PropertyCallbackInfo<v8::Boolean>& info);

You do not need to declare a new HandleScope within a index deleter as one is implicitly created for you.

A helper macro NAN_INDEX_DELETER(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on indexed property Interceptors.

Index query declaration

JavaScript-accessible index query methods should be declared with the following signature to form a Nan::IndexQueryCallback:

typedef void(*IndexQueryCallback)(uint32_t,
                                  const PropertyCallbackInfo<v8::Integer>&);

Example:

void IndexQueryName(uint32_t index, const PropertyCallbackInfo<v8::Integer>& info);

You do not need to declare a new HandleScope within a index query method as one is implicitly created for you.

A helper macro NAN_INDEX_QUERY(methodname) exists, compatible with NAN v1 method declarations.

Also see the V8 Embedders Guide documentation on indexed property Interceptors.

Nan::SetMethod()

Sets a method with a given name directly on a JavaScript object where the method has the Nan::FunctionCallback signature (see Method declaration).

Signature:

void Nan::SetMethod(v8::Local<v8::Object> recv,
                    const char *name,
                    Nan::FunctionCallback callback)
void Nan::SetMethod(v8::Local<v8::Template> templ,
                    const char *name,
                    Nan::FunctionCallback callback)

Nan::SetPrototypeMethod()

Sets a method with a given name on a FunctionTemplate's prototype where the method has the Nan::FunctionCallback signature (see Method declaration).

Signature:

void Nan::SetPrototypeMethod(v8::Local<v8::FunctionTemplate> recv,
                             const char* name,
                             Nan::FunctionCallback callback)

Nan::SetAccessor()

Sets getters and setters for a property with a given name on an ObjectTemplate or a plain Object. Accepts getters with the Nan::GetterCallback signature (see Getter declaration) and setters with the Nan::SetterCallback signature (see Setter declaration).

Signature:

void SetAccessor(v8::Local<v8::ObjectTemplate> tpl,
                 v8::Local<v8::String> name,
                 Nan::GetterCallback getter,
                 Nan::SetterCallback setter = 0,
                 v8::Local<v8::Value> data = v8::Local<v8::Value>(),
                 v8::AccessControl settings = v8::DEFAULT,
                 v8::PropertyAttribute attribute = v8::None,
                 imp::Sig signature = imp::Sig());
bool SetAccessor(v8::Local<v8::Object> obj,
                 v8::Local<v8::String> name,
                 Nan::GetterCallback getter,
                 Nan::SetterCallback setter = 0,
                 v8::Local<v8::Value> data = v8::Local<v8::Value>(),
                 v8::AccessControl settings = v8::DEFAULT,
                 v8::PropertyAttribute attribute = v8::None)

See the V8 ObjectTemplate#SetAccessor() and Object#SetAccessor() for further information about how to use Nan::SetAccessor().

Nan::SetNamedPropertyHandler()

Sets named property getters, setters, query, deleter and enumerator methods on an ObjectTemplate. Accepts:

• Property getters with the Nan::PropertyGetterCallback signature (see Property getter declaration)
• Property setters with the Nan::PropertySetterCallback signature (see Property setter declaration)
• Property query methods with the Nan::PropertyQueryCallback signature (see Property query declaration)
• Property deleters with the Nan::PropertyDeleterCallback signature (see Property deleter declaration)
• Property enumerators with the Nan::PropertyEnumeratorCallback signature (see Property enumerator declaration)

Signature:

void SetNamedPropertyHandler(v8::Local<v8::ObjectTemplate> tpl,
                             Nan::PropertyGetterCallback getter,
                             Nan::PropertySetterCallback setter = 0,
                             Nan::PropertyQueryCallback query = 0,
                             Nan::PropertyDeleterCallback deleter = 0,
                             Nan::PropertyEnumeratorCallback enumerator = 0,
                             v8::Local<v8::Value> data = v8::Local<v8::Value>())

See the V8 ObjectTemplate#SetNamedPropertyHandler() for further information about how to use Nan::SetNamedPropertyHandler().

Nan::SetIndexedPropertyHandler()

Sets indexed property getters, setters, query, deleter and enumerator methods on an ObjectTemplate. Accepts:

• Indexed property getters with the Nan::IndexGetterCallback signature (see Index getter declaration)
• Indexed property setters with the Nan::IndexSetterCallback signature (see Index setter declaration)
• Indexed property query methods with the Nan::IndexQueryCallback signature (see Index query declaration)
• Indexed property deleters with the Nan::IndexDeleterCallback signature (see Index deleter declaration)
• Indexed property enumerators with the Nan::IndexEnumeratorCallback signature (see Index enumerator declaration)

Signature:

void SetIndexedPropertyHandler(v8::Local<v8::ObjectTemplate> tpl,
                               Nan::IndexGetterCallback getter,
                               Nan::IndexSetterCallback setter = 0,
                               Nan::IndexQueryCallback query = 0,
                               Nan::IndexDeleterCallback deleter = 0,
                               Nan::IndexEnumeratorCallback enumerator = 0,
                               v8::Local<v8::Value> data = v8::Local<v8::Value>())

See the V8 ObjectTemplate#SetIndexedPropertyHandler() for further information about how to use Nan::SetIndexedPropertyHandler().

Nan::SetTemplate()

Adds properties on an Object's or Function's template.

Signature:

void Nan::SetTemplate(v8::Local<v8::Template> templ,
                      const char *name,
                      v8::Local<v8::Data> value);
void Nan::SetTemplate(v8::Local<v8::Template> templ,
                      v8::Local<v8::String> name,
                      v8::Local<v8::Data> value,
                      v8::PropertyAttribute attributes)

Calls the Template's Set().

Nan::SetPrototypeTemplate()

Adds properties on an Object's or Function's prototype template.

Signature:

void Nan::SetPrototypeTemplate(v8::Local<v8::FunctionTemplate> templ,
                               const char *name,
                               v8::Local<v8::Data> value);
void Nan::SetPrototypeTemplate(v8::Local<v8::FunctionTemplate> templ,
                               v8::Local<v8::String> name,
                               v8::Local<v8::Data> value,
                               v8::PropertyAttribute attributes)

Calls the FunctionTemplate's PrototypeTemplate's Set().

Nan::SetInstanceTemplate()

Use to add instance properties on FunctionTemplate's.

Signature:

void Nan::SetInstanceTemplate(v8::Local<v8::FunctionTemplate> templ,
                              const char *name,
                              v8::Local<v8::Data> value);
void Nan::SetInstanceTemplate(v8::Local<v8::FunctionTemplate> templ,
                              v8::Local<v8::String> name,
                              v8::Local<v8::Data> value,
                              v8::PropertyAttribute attributes)

Calls the FunctionTemplate's InstanceTemplate's Set().

Nan::SetCallHandler()

Set the call-handler callback for a v8::FunctionTemplate. This callback is called whenever the function created from this FunctionTemplate is called.

Signature:

void Nan::SetCallHandler(v8::Local<v8::FunctionTemplate> templ, Nan::FunctionCallback callback, v8::Local<v8::Value> data = v8::Local<v8::Value>())

Calls the FunctionTemplate's SetCallHandler().

Nan::SetCallAsFunctionHandler()

Sets the callback to be used when calling instances created from the v8::ObjectTemplate as a function. If no callback is set, instances behave like normal JavaScript objects that cannot be called as a function.

Signature:

void Nan::SetCallAsFunctionHandler(v8::Local<v8::ObjectTemplate> templ, Nan::FunctionCallback callback, v8::Local<v8::Value> data = v8::Local<v8::Value>())

Calls the ObjectTemplate's SetCallAsFunctionHandler().