Optional Value Boxes

[legendecas]

Napi::Value can be empty. Many of N-API will return napi_invalid_arg on empty Napi::Value as a parameter (e.g. napi_get_property). We can introduce a Maybe value box to node-addon-api to early detect these conditions and provide a clean way to indicate whether a parameter Napi::Value is optional.

[legendecas]

I'd believe this can be a better solution for #544.

[devsnek]

Napi::Value already provides IsEmpty(). Maybe<> in the V8 API is used to represent things that throw, not things that are optional.

[legendecas]

Yeah, there is already an IsEmpty on Napi::Value. Still, there is no ability to provide a strong type guarantee that a Napi::SomeType is absolutely not empty, i.e. compiler will complain about the code on build time.

If Maybe is not an appropriate name for the situation, I'm ok with another name that fits.

[devsnek]

Adding Maybe wouldn't fix the issue that there's no way to guarantee a value is not empty because the Value in the Maybe can still be empty. I do agree it would be cool if it were possible but that might be outside the bounds of the language we've chosen to work with here.

[legendecas]

The idea is to distinguish empty-able parameters and return values at build time.

In the example of #544, originally we have to use a trick to achieve what we expect:

Function callback; // this one is empty since it's not initialized with any napi_value
auto tsfn = ThreadSafeFunction::New(env, callback, resource_name, 1, 1);

With optional boxes, we can make Napi::Value not constructible in the way above, and use Optional::Empty instead:

auto tsfn = ThreadSafeFunction::New(env, Napi::Optional::Empty(), resource_name, 1, 1);

If we do have a callback value:

Napi::Function callback = Napi::Function::New(env, some_callback);
auto tsfn = ThreadSafeFunction::New(env, Napi::Optional::Just(callback), resource_name, 1, 1);

Or make it implicit:

Napi::Function callback = Napi::Function::New(env, some_callback);
auto tsfn = ThreadSafeFunction::New(env, callback, resource_name, 1, 1);

In this way, we can make our API stronger than just empty-able Napi::Value, with which compiler doesn't complain if it's empty where it should not be empty.

Optional is available in stl since C++ 17, so maybe we can use stl optional directly.

[github-actions]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.

[github-actions]

This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.