Description
edited to reflect completed tasks (@gabrielschulhof)
- Version: 8.1.3
- Subsystem: n-api
http://zzo38computer.org/textfile/miscellaneous/napi_ext
documentation
String lifetimes.
The document should specify if N-API copies the string, to make it clear.
(With SQLite, you can specify whether or not the string should be copied
and if not, what to call to free it.)
Examples of asynchronous working.
There aren't any example, and it does not explain many things such as
mutexes, calling JavaScript codes during the working, example of using
napi_make_callback(), thread safety, etc.
SQLite has support for multithreads too (if enabled), although there is
some confusion in the N-API documentation as to what exactly is allowed
when interfacing SQLite (and other stuff) with N-API when using the
asynchronous working.
External values.
The documentation should probably mention that an external value appears
as an object (sealed, frozen, with no properties and no prototype) to
JavaScript codes, even though it is a separate type to native codes.
Get property names.
The documentation for napi_get_property_names() does not say whether it
gets only enumerable properties or all properties, and does not say if it
includes symbols or not.
C++ wrapping.
What is the relation to C++ (I thought this is a C API?) and what is the
reason for the restrictions with napi_wrap()? Also, is it necessary to
call napi_wrap() only during the constructor callback, or is it OK to do
afterward too?
Throwing exceptions.
The document says that napi_throw() throws an Error provided. Is it
necessary for it to be an Error, or can you throw any value? You should be
allowed to throw any value, I should think.
Implementation
Retrieving new.target.
When a function is called as a constructor, new.target should be
retrievable. This may replace is_construct_call since you can do the same
thing with this anyways.
napi_get_new_target()
Executing JavaScript codes.
Some things aren't and perhaps shouldn't be defined in N-API, but it can
be useful to execute external JavaScript codes sometimes (during
initialization, especially) in order to do such things.
napi_run_script()
Further module arguments.
It currently (seems to) provide no way to get the "require", "__dirname",
and "__filename" arguments of a Node.js module. If the native code is a
Node.js module there should probably be some way to retrieve such values
(which may be used with the above "executing JavaScript codes" during the
initialization).
Retrieving the finalizer for a value.
For objects created using N-API, it would help to have a function to get
the finalizer callback for the value, for example:
napi_get_value_finalizer(napi_env env,napi_value val,napi_finalize*result)
This can be used to determine who created an object, by comparing the
finalizer function pointer (which will be a null pointer if there is no
finalizer callback defined) with the address of the native code's own
functions (there is no point calling the returned finalizer callback).
Reading strings of 8-bit characters.
The function napi_get_value_string_latin1() is missing. Not sure what to
do for strings having character codes that don't fit in 8-bits; it may be
defined to just use the low 8-bits, or it may be specified as undefined.
Support for WeakMap.
N-API can already create and manipulate a Array, but there is no support
to create and manipulate a WeakMap, which may sometimes be useful for
internally attaching extra data to arbitrary objects.
(You might be able to define your own finalizer callbacks also using a
WeakMap anyways, by giving a key for the object to check, and the value
being a external value with a finalizer callback defined, so that it will
be called when the key object is finalized; I don't know whether or not it
will work, but it seems like it is allowed to work, at least.)
Creating functions and objects.
When using napi_create_object() and napi_create_function(), you cannot
specify a finalizer callback, which probably should be allowed since it
can be useful to have.
Also, napi_create_object() should allow you to optionally specify the
prototype to use (which is a napi_value which is either null or a object;
if it is not specified then it can use the default Object.prototype).
napi_new_instance()
Exotic objects.
A suggestion is a new N-API function to create custom exotic objects (like
Proxy in JavaScript, but without the extra checking).
Generator functions.
A way to create generator functions with N-API functions. (You can already
fake it, but real generator functions may help a bit better, will work if
you use the actual generator methods rather than others with the same
name, and may be more efficient in some cases maybe.)
Attaching a finalizer callback to the generator object can also help.
Immediate garbage collection.
Sometimes you may wish to trigger garbage collection sooner in order to
make finalizer callbacks to be called. This will not necessarily be
guaranteed, although attempting it can nevertheless be useful sometimes.
(This should also be provided in the "v8" module so that it can be used
from JavaScript codes directly, too.)
Moving values into scopes.
Sometimes you might want to return a value that is not scoped and then to
delete the reference to it at the same time. In order to do this, it may
be useful to add the value to the scope so that it can be returned.
N-API might automatically do this; the documentation isn't quite clear. If
N-API does already do this, it should be explained, and the stuff in this
section need not be implemented.
Another alternative would be to provide another function to return values
from a native code rather than returning it directly.
Another possibility may be to create an array and add the value into that
array to prevent it from getting lost, and the array is automatically lost
when the function returns, but that seems a bit klugy to me.