From d664cf32ace06b0bfd6ffc8ccf7d18a2b3a7ae44 Mon Sep 17 00:00:00 2001 From: Fedor Indutny <238531+indutny@users.noreply.github.com> Date: Tue, 11 Jul 2023 17:22:02 -0700 Subject: [PATCH 1/5] doc: clarify use of Uint8Array for n-api `napi_get_buffer_info` always supported receiving `Uint8Array` as a `value` argument because `node::Buffer` is a subclass of `Uint8Array` and the underlying V8 APIs don't distinguish between two. With this change we mark both types as supported by the API so that the user code doesn't have to unknowingly use oficially unsupported type of the `value` argument. --- doc/api/n-api.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 873c8bdce4a492..8aeaee7264931c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3122,9 +3122,10 @@ napi_status napi_get_buffer_info(napi_env env, ``` * `[in] env`: The environment that the API is invoked under. -* `[in] value`: `napi_value` representing the `node::Buffer` being queried. -* `[out] data`: The underlying data buffer of the `node::Buffer`. - If length is `0`, this may be `NULL` or any other pointer value. +* `[in] value`: `napi_value` representing the `node::Buffer` or `Uint8Array` + being queried. +* `[out] data`: The underlying data buffer of the `node::Buffer` or + `Uint8Array`. If length is `0`, this may be `NULL` or any other pointer value. * `[out] length`: Length in bytes of the underlying data buffer. Returns `napi_ok` if the API succeeded. @@ -3879,8 +3880,8 @@ napi_status napi_is_buffer(napi_env env, napi_value value, bool* result) * `[in] env`: The environment that the API is invoked under. * `[in] value`: The JavaScript value to check. -* `[out] result`: Whether the given `napi_value` represents a `node::Buffer` - object. +* `[out] result`: Whether the given `napi_value` represents a `node::Buffer` or + `Uint8Array` object. Returns `napi_ok` if the API succeeded. From 0bc66ea77f2f2ce84006e41d9ef937fd48d7d0c5 Mon Sep 17 00:00:00 2001 From: Fedor Indutny <238531+indutny@users.noreply.github.com> Date: Fri, 28 Jul 2023 09:21:19 -0700 Subject: [PATCH 2/5] Update doc/api/n-api.md Co-authored-by: Chengzhong Wu --- doc/api/n-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 8aeaee7264931c..70b1427e9d4c54 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3130,6 +3130,8 @@ napi_status napi_get_buffer_info(napi_env env, Returns `napi_ok` if the API succeeded. +This method returns the identical `data` and `byte_length` as [`napi_get_typedarray_info`][]. And `napi_get_typedarray_info` accepts a `node::Buffer` (a Uint8Array) as the value too. + This API is used to retrieve the underlying data buffer of a `node::Buffer` and its length. From 2fbc2f10ca465305a844883f8cc214180796820d Mon Sep 17 00:00:00 2001 From: Fedor Indutny <238531+indutny@users.noreply.github.com> Date: Fri, 28 Jul 2023 09:23:37 -0700 Subject: [PATCH 3/5] update --- doc/api/n-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 70b1427e9d4c54..a0f9e6c74caa65 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3887,7 +3887,9 @@ napi_status napi_is_buffer(napi_env env, napi_value value, bool* result) Returns `napi_ok` if the API succeeded. -This API checks if the `Object` passed in is a buffer. +This API checks if the `Object` passed in is a buffer or Uint8Array. +[`napi_is_typedarray`][] should be preferred if the caller needs to check if the +value is a Uint8Array. ### `napi_is_date` @@ -6562,6 +6564,7 @@ the add-on's file name during loading. [`napi_instanceof`]: #napi_instanceof [`napi_is_error`]: #napi_is_error [`napi_is_exception_pending`]: #napi_is_exception_pending +[`napi_is_typedarray`]: #napi_is_typedarray [`napi_make_callback`]: #napi_make_callback [`napi_open_callback_scope`]: #napi_open_callback_scope [`napi_open_escapable_handle_scope`]: #napi_open_escapable_handle_scope From 24b6365cebef07935c0f45b72278463d3cf2db3b Mon Sep 17 00:00:00 2001 From: Fedor Indutny <238531+indutny@users.noreply.github.com> Date: Fri, 18 Aug 2023 09:48:20 -0700 Subject: [PATCH 4/5] format --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index a0f9e6c74caa65..e41165546727c0 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3130,7 +3130,7 @@ napi_status napi_get_buffer_info(napi_env env, Returns `napi_ok` if the API succeeded. -This method returns the identical `data` and `byte_length` as [`napi_get_typedarray_info`][]. And `napi_get_typedarray_info` accepts a `node::Buffer` (a Uint8Array) as the value too. +This method returns the identical `data` and `byte_length` as \[`napi_get_typedarray_info`]\[]. And `napi_get_typedarray_info` accepts a `node::Buffer` (a Uint8Array) as the value too. This API is used to retrieve the underlying data buffer of a `node::Buffer` and its length. From 4ba8e6f34e2706c88142319a48a13433f3f5f6df Mon Sep 17 00:00:00 2001 From: Fedor Indutny <238531+indutny@users.noreply.github.com> Date: Fri, 18 Aug 2023 09:49:47 -0700 Subject: [PATCH 5/5] fix lint --- doc/api/n-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index e41165546727c0..4eabe9e3b38ea9 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3130,7 +3130,9 @@ napi_status napi_get_buffer_info(napi_env env, Returns `napi_ok` if the API succeeded. -This method returns the identical `data` and `byte_length` as \[`napi_get_typedarray_info`]\[]. And `napi_get_typedarray_info` accepts a `node::Buffer` (a Uint8Array) as the value too. +This method returns the identical `data` and `byte_length` as +[`napi_get_typedarray_info`][]. And `napi_get_typedarray_info` accepts a +`node::Buffer` (a Uint8Array) as the value too. This API is used to retrieve the underlying data buffer of a `node::Buffer` and its length. @@ -6559,6 +6561,7 @@ the add-on's file name during loading. [`napi_get_last_error_info`]: #napi_get_last_error_info [`napi_get_property`]: #napi_get_property [`napi_get_reference_value`]: #napi_get_reference_value +[`napi_get_typedarray_info`]: #napi_get_typedarray_info [`napi_get_value_external`]: #napi_get_value_external [`napi_has_property`]: #napi_has_property [`napi_instanceof`]: #napi_instanceof