Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: de-emphasize wrapping in napi_define_class #36159

Closed
Closed
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 31 additions & 24 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -4738,14 +4738,15 @@ napi_status napi_define_class(napi_env env,
```

* `[in] env`: The environment that the API is invoked under.
* `[in] utf8name`: Name of the JavaScript constructor function; this is
not required to be the same as the C++ class name, though it is recommended
for clarity.
* `[in] utf8name`: Name of the JavaScript constructor function; When wrapping a
C++ class it is recommended for clarity that this name be the same as that of
gabrielschulhof marked this conversation as resolved.
Show resolved Hide resolved
the C++ class.
* `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH`
if it is null-terminated.
* `[in] constructor`: Callback function that handles constructing instances
of the class. This should be a static method on the class, not an actual
C++ constructor function. [`napi_callback`][] provides more details.
of the class. When wrapping a C++ class, this method must be a static member
with the [`napi_callback`][] signature. A C++ class constructor cannot be
used. [`napi_callback`][] provides more details.
* `[in] data`: Optional data to be passed to the constructor callback as
the `data` property of the callback info.
* `[in] property_count`: Number of items in the `properties` array argument.
Expand All @@ -4757,27 +4758,33 @@ napi_status napi_define_class(napi_env env,

Returns `napi_ok` if the API succeeded.

Defines a JavaScript class that corresponds to a C++ class, including:

* A JavaScript constructor function that has the class name and invokes the
provided C++ constructor callback.
* Properties on the constructor function corresponding to _static_ data
properties, accessors, and methods of the C++ class (defined by
property descriptors with the `napi_static` attribute).
* Properties on the constructor function's `prototype` object corresponding to
_non-static_ data properties, accessors, and methods of the C++ class
(defined by property descriptors without the `napi_static` attribute).

The C++ constructor callback should be a static method on the class that calls
the actual class constructor, then wraps the new C++ instance in a JavaScript
object, and returns the wrapper object. See `napi_wrap()` for details.
Defines a JavaScript class, including:

* A JavaScript constructor function that has the class name. When wrapping a
corresponding C++ class, the callback passed via `constructor` may be used to
gabrielschulhof marked this conversation as resolved.
Show resolved Hide resolved
instantiate a new C++ class instance, which can then be placed "inside" the
gabrielschulhof marked this conversation as resolved.
Show resolved Hide resolved
JavaScript object instance being constructed using [`napi_wrap`][].
* Properties on the constructor function whose implementation can call
corresponding _static_ data properties, accessors, and methods of the C++
class (defined by property descriptors with the `napi_static` attribute).
* Properties on the constructor function's `prototype` object. When wrapping a
C++ class, _non-static_ data properties, accessors, and methods of the C++
class can be called from the static functions given in the property
descriptors without the `napi_static` attribute after retrieving the C++ class
instance placed "inside" the JavaScript object instance by using
gabrielschulhof marked this conversation as resolved.
Show resolved Hide resolved
[`napi_unwrap`][].

When wrapping a C++ class, the C++ constructor callback passed via `constructor`
should be a static method on the class that calls the actual class constructor,
then wraps the new C++ instance in a JavaScript object, and returns the wrapper
object. See [`napi_wrap`][] for details.

The JavaScript constructor function returned from [`napi_define_class`][] is
often saved and used later, to construct new instances of the class from native
code, and/or check whether provided values are instances of the class. In that
case, to prevent the function value from being garbage-collected, create a
persistent reference to it using [`napi_create_reference`][] and ensure the
reference count is kept >= 1.
often saved and used later to construct new instances of the class from native
code, and/or to check whether provided values are instances of the class. In
that case, to prevent the function value from being garbage-collected, a
strong persistent reference to it can be created using
[`napi_create_reference`][], ensuring that the reference count is kept >= 1.

Any non-`NULL` data which is passed to this API via the `data` parameter or via
the `data` field of the `napi_property_descriptor` array items can be associated
Expand Down