From 50cc5389030923acf62bd9581068b7a6d4fe6557 Mon Sep 17 00:00:00 2001 From: h7lin Date: Mon, 30 Sep 2019 22:08:27 +0800 Subject: [PATCH] =?UTF-8?q?=E5=8D=87=E7=BA=A7=E5=88=B0=20v12.11.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...ssert_deepequal_actual_expected_message.md | 1 + .../assert_equal_actual_expected_message.md | 1 + ..._expected_message_operator_stackstartfn.md | 1 + ...rt_notdeepequal_actual_expected_message.md | 1 + ...assert_notequal_actual_expected_message.md | 1 + .../async_hooks_createhook_callbacks.md | 1 + async_hooks/asyncresource_triggerasyncid.md | 1 + ...e_zero_fill_buffers_command_line_option.md | 2 +- .../spawning_bat_and_cmd_files_on_windows.md | 2 +- cli/coverage_output.md | 16 ++ cli/http_parser_library.md | 4 +- cli/node_options_options.md | 140 +++++++++--------- cli/node_v8_coverage_dir.md | 21 +-- cli/source_map_cache.md | 40 +++++ cli/uv_threadpool_size_size.md | 9 +- cluster/cluster.md | 2 +- cluster/worker_exitedafterdisconnect.md | 9 +- crypto/ccm_mode.md | 16 +- crypto/certificate_exportchallenge_spkac_1.md | 1 + crypto/certificate_exportpublickey_spkac.md | 1 + ...tificate_exportpublickey_spkac_encoding.md | 1 + crypto/certificate_verifyspkac_spkac_1.md | 1 + crypto/cipher_setaad_buffer_options.md | 3 +- crypto/crypto_constants.md | 1 + ...createcipheriv_algorithm_key_iv_options.md | 1 + ...eatedecipheriv_algorithm_key_iv_options.md | 1 + ...imeencoding_generator_generatorencoding.md | 1 + ...eatediffiehellman_primelength_generator.md | 1 + crypto/crypto_createecdh_curvename.md | 1 + crypto/crypto_createhash_algorithm_options.md | 1 + ...crypto_createhmac_algorithm_key_options.md | 1 + crypto/crypto_createprivatekey_key.md | 9 +- crypto/crypto_createpublickey_key.md | 7 +- crypto/crypto_createsecretkey_key.md | 1 + crypto/crypto_createsign_algorithm_options.md | 1 + .../crypto_createverify_algorithm_options.md | 1 + ...o_generatekeypair_type_options_callback.md | 19 +-- ...crypto_generatekeypairsync_type_options.md | 17 ++- crypto/crypto_getciphers.md | 1 + crypto/crypto_getcurves.md | 1 + crypto/crypto_getdiffiehellman_groupname.md | 1 + crypto/crypto_getfips.md | 1 + crypto/crypto_gethashes.md | 1 + ..._salt_iterations_keylen_digest_callback.md | 5 +- ..._password_salt_iterations_keylen_digest.md | 1 + ...crypto_privatedecrypt_privatekey_buffer.md | 8 +- ...crypto_privateencrypt_privatekey_buffer.md | 7 +- crypto/crypto_publicdecrypt_key_buffer.md | 5 +- crypto/crypto_publicencrypt_key_buffer.md | 12 +- ...t_password_salt_keylen_options_callback.md | 19 +-- ...scryptsync_password_salt_keylen_options.md | 15 +- crypto/crypto_setengine_engine_flags.md | 1 + crypto/crypto_setfips_bool.md | 1 + crypto/crypto_sign_algorithm_data_key.md | 1 + crypto/crypto_timingsafeequal_a_b.md | 1 + ...pto_verify_algorithm_data_key_signature.md | 1 + crypto/decipher_setaad_buffer_options.md | 3 +- crypto/decipher_setauthtag_buffer.md | 1 + crypto/decipher_setautopadding_autopadding.md | 1 + ...rpublickey_inputencoding_outputencoding.md | 1 + crypto/diffiehellman_generatekeys_encoding.md | 1 + crypto/diffiehellman_getgenerator_encoding.md | 1 + crypto/diffiehellman_getprime_encoding.md | 1 + .../diffiehellman_getprivatekey_encoding.md | 1 + crypto/diffiehellman_getpublickey_encoding.md | 1 + ...llman_setprivatekey_privatekey_encoding.md | 1 + ...hellman_setpublickey_publickey_encoding.md | 1 + ...rpublickey_inputencoding_outputencoding.md | 1 + crypto/ecdh_generatekeys_encoding_format.md | 1 + crypto/ecdh_getprivatekey_encoding.md | 1 + crypto/ecdh_getpublickey_encoding_format.md | 1 + .../ecdh_setprivatekey_privatekey_encoding.md | 1 + crypto/hmac_digest_encoding.md | 1 + crypto/hmac_update_data_inputencoding.md | 1 + crypto/keyobject_asymmetrickeytype.md | 1 + crypto/keyobject_export_options.md | 1 + crypto/keyobject_symmetrickeysize.md | 1 + crypto/keyobject_type.md | 1 + crypto/sign_sign_privatekey_outputencoding.md | 5 +- crypto/sign_update_data_inputencoding.md | 1 + ...port_for_weak_or_compromised_algorithms.md | 6 +- crypto/verify_update_data_inputencoding.md | 1 + ...rify_object_signature_signatureencoding.md | 5 +- debugger/breakpoints.md | 2 +- debugger/debugger.md | 4 +- .../v8_inspector_integration_for_node_js.md | 2 +- ...requiring_bundled_internal_dependencies.md | 26 ++-- dns/dns.md | 60 ++++---- dns/dnspromises_lookup_hostname_options.md | 9 +- dns/dnspromises_lookupservice_address_port.md | 1 + dns/dnspromises_resolve4_hostname_options.md | 3 +- dns/dnspromises_resolve6_hostname_options.md | 3 +- dns/dnspromises_resolve_hostname_rrtype.md | 1 + dns/dnspromises_resolveany_hostname.md | 1 + dns/dnspromises_resolvecname_hostname.md | 1 + dns/dnspromises_resolvemx_hostname.md | 1 + dns/dnspromises_resolvenaptr_hostname.md | 1 + dns/dnspromises_resolvens_hostname.md | 1 + dns/dnspromises_resolveptr_hostname.md | 1 + dns/dnspromises_resolvesoa_hostname.md | 1 + dns/dnspromises_resolvesrv_hostname.md | 1 + dns/dnspromises_resolvetxt_hostname.md | 1 + dns/dnspromises_reverse_ip.md | 1 + dns/dnspromises_setservers_servers.md | 1 + errors/err_inspector_not_connected.md | 2 +- errors/err_inspector_not_worker.md | 5 + errors/err_vm_module_already_linked.md | 6 +- ..._package_json_code_code_type_code_field.md | 6 + ..._with_commonjs_only_versions_of_node_js.md | 40 +++++ ...zing_esm_specifier_resolution_algorithm.md | 1 + esm/enabling.md | 12 +- esm/package_entry_points.md | 8 +- esm/package_exports.md | 27 ++++ esm/package_scope_and_file_extensions.md | 4 +- esm/packages.md | 1 + esm/resolve_hook.md | 24 ++- esm/resolver_algorithm.md | 17 +++ esm/terminology.md | 8 +- ...emitter_listenercount_emitter_eventname.md | 1 + events/events_once_emitter_name.md | 5 +- fs/file_open_constants.md | 14 +- fs/file_system.md | 2 +- http/message_url.md | 2 +- http2/headers_object.md | 19 +-- ...ttp2_connect_authority_options_listener.md | 34 ++--- ...tesecureserver_options_onrequesthandler.md | 34 ++--- ...2_createserver_options_onrequesthandler.md | 34 ++--- http2/http2stream_buffersize.md | 1 + http2/request_complete.md | 9 ++ http2/request_url.md | 2 +- ...nse_createpushresponse_headers_callback.md | 1 + http2/server_close_callback.md | 1 + http2/server_close_callback_1.md | 1 + inspector/session_connect.md | 4 +- inspector/session_connecttomainthread.md | 7 + .../detecting_internationalization_support.md | 4 +- intl/internationalization_support.md | 24 +-- intl/options_for_building_node_js.md | 8 +- modules/cycles.md | 2 +- n-api/implications_of_abi_stability.md | 1 + n-api/n_api.md | 9 +- n-api/n_api_version_matrix.md | 17 ++- n-api/napi_acquire_threadsafe_function.md | 2 +- n-api/napi_add_finalizer.md | 25 ++-- n-api/napi_adjust_external_memory.md | 6 +- n-api/napi_async_destroy.md | 4 +- n-api/napi_async_execute_callback.md | 12 +- n-api/napi_async_init.md | 8 +- n-api/napi_call_function.md | 12 +- n-api/napi_call_threadsafe_function.md | 6 +- n-api/napi_cancel_async_work.md | 4 +- n-api/napi_close_callback_scope.md | 4 +- n-api/napi_close_escapable_handle_scope.md | 4 +- n-api/napi_close_handle_scope.md | 4 +- n-api/napi_coerce_to_bool.md | 6 +- n-api/napi_coerce_to_number.md | 6 +- n-api/napi_coerce_to_object.md | 6 +- n-api/napi_coerce_to_string.md | 6 +- n-api/napi_create_array.md | 4 +- n-api/napi_create_array_with_length.md | 6 +- n-api/napi_create_arraybuffer.md | 8 +- n-api/napi_create_async_work.md | 14 +- n-api/napi_create_bigint_int64.md | 6 +- n-api/napi_create_bigint_uint64.md | 6 +- n-api/napi_create_bigint_words.md | 10 +- n-api/napi_create_buffer.md | 8 +- n-api/napi_create_buffer_copy.md | 10 +- n-api/napi_create_dataview.md | 10 +- n-api/napi_create_date.md | 11 +- n-api/napi_create_double.md | 6 +- n-api/napi_create_error.md | 8 +- n-api/napi_create_external.md | 10 +- n-api/napi_create_external_arraybuffer.md | 12 +- n-api/napi_create_external_buffer.md | 12 +- n-api/napi_create_function.md | 12 +- n-api/napi_create_int32.md | 6 +- n-api/napi_create_int64.md | 6 +- n-api/napi_create_object.md | 4 +- n-api/napi_create_promise.md | 6 +- n-api/napi_create_range_error.md | 8 +- n-api/napi_create_reference.md | 8 +- n-api/napi_create_string_latin1.md | 8 +- n-api/napi_create_string_utf16.md | 8 +- n-api/napi_create_string_utf8.md | 8 +- n-api/napi_create_symbol.md | 6 +- n-api/napi_create_threadsafe_function.md | 22 +-- n-api/napi_create_type_error.md | 8 +- n-api/napi_create_typedarray.md | 12 +- n-api/napi_create_uint32.md | 6 +- n-api/napi_define_class.md | 51 +++---- n-api/napi_define_properties.md | 8 +- n-api/napi_delete_async_work.md | 4 +- n-api/napi_delete_element.md | 8 +- n-api/napi_delete_property.md | 8 +- n-api/napi_delete_reference.md | 4 +- n-api/napi_escape_handle.md | 8 +- n-api/napi_extended_error_info.md | 8 +- n-api/napi_fatal_error.md | 8 +- n-api/napi_fatal_exception.md | 4 +- n-api/napi_get_and_clear_last_exception.md | 4 +- n-api/napi_get_array_length.md | 6 +- n-api/napi_get_arraybuffer_info.md | 8 +- n-api/napi_get_boolean.md | 6 +- n-api/napi_get_buffer_info.md | 8 +- n-api/napi_get_cb_info.md | 12 +- n-api/napi_get_dataview_info.md | 12 +- n-api/napi_get_date_value.md | 11 +- n-api/napi_get_element.md | 8 +- n-api/napi_get_global.md | 4 +- n-api/napi_get_instance_data.md | 4 +- n-api/napi_get_last_error_info.md | 4 +- n-api/napi_get_named_property.md | 8 +- n-api/napi_get_new_target.md | 6 +- n-api/napi_get_node_version.md | 4 +- n-api/napi_get_null.md | 4 +- n-api/napi_get_property.md | 8 +- n-api/napi_get_property_names.md | 6 +- n-api/napi_get_prototype.md | 6 +- n-api/napi_get_reference_value.md | 7 +- n-api/napi_get_threadsafe_function_context.md | 4 +- n-api/napi_get_typedarray_info.md | 14 +- n-api/napi_get_undefined.md | 4 +- n-api/napi_get_uv_event_loop.md | 4 +- n-api/napi_get_value_bigint_int64.md | 8 +- n-api/napi_get_value_bigint_uint64.md | 8 +- n-api/napi_get_value_bigint_words.md | 10 +- n-api/napi_get_value_bool.md | 6 +- n-api/napi_get_value_double.md | 6 +- n-api/napi_get_value_external.md | 6 +- n-api/napi_get_value_int32.md | 6 +- n-api/napi_get_value_int64.md | 6 +- n-api/napi_get_value_string_latin1.md | 10 +- n-api/napi_get_value_string_utf16.md | 10 +- n-api/napi_get_value_string_utf8.md | 10 +- n-api/napi_get_value_uint32.md | 6 +- n-api/napi_get_version.md | 4 +- n-api/napi_has_element.md | 8 +- n-api/napi_has_named_property.md | 8 +- n-api/napi_has_own_property.md | 8 +- n-api/napi_has_property.md | 8 +- n-api/napi_instanceof.md | 8 +- n-api/napi_is_array.md | 6 +- n-api/napi_is_arraybuffer.md | 6 +- n-api/napi_is_buffer.md | 6 +- n-api/napi_is_dataview.md | 6 +- n-api/napi_is_date.md | 8 +- n-api/napi_is_error.md | 6 +- n-api/napi_is_error_1.md | 6 +- n-api/napi_is_exception_pending.md | 4 +- n-api/napi_is_promise.md | 6 +- n-api/napi_is_typedarray.md | 6 +- n-api/napi_make_callback.md | 14 +- n-api/napi_new_instance.md | 10 +- n-api/napi_open_callback_scope.md | 8 +- n-api/napi_open_escapable_handle_scope.md | 4 +- n-api/napi_open_handle_scope.md | 4 +- n-api/napi_property_attributes.md | 10 +- n-api/napi_property_descriptor.md | 16 +- n-api/napi_queue_async_work.md | 4 +- n-api/napi_ref_threadsafe_function.md | 4 +- n-api/napi_reference_ref.md | 6 +- n-api/napi_reference_unref.md | 6 +- n-api/napi_reject_deferred.md | 6 +- n-api/napi_release_threadsafe_function.md | 4 +- n-api/napi_remove_wrap.md | 6 +- n-api/napi_resolve_deferred.md | 6 +- n-api/napi_run_script.md | 6 +- n-api/napi_set_element.md | 8 +- n-api/napi_set_instance_data.md | 8 +- n-api/napi_set_named_property.md | 8 +- n-api/napi_set_property.md | 8 +- n-api/napi_strict_equals.md | 8 +- n-api/napi_threadsafe_function_call_js.md | 8 +- n-api/napi_throw.md | 4 +- n-api/napi_throw_error.md | 6 +- n-api/napi_throw_range_error.md | 6 +- n-api/napi_throw_type_error.md | 6 +- n-api/napi_typeof.md | 9 +- n-api/napi_unref_threadsafe_function.md | 4 +- n-api/napi_unwrap.md | 6 +- n-api/napi_wrap.md | 20 +-- n-api/object_wrap.md | 6 +- n-api/return_values.md | 8 +- n-api/working_with_javascript_functions.md | 7 +- n-api/working_with_javascript_properties.md | 9 +- n-api/working_with_javascript_values.md | 1 + ...h_javascript_values_abstract_operations.md | 1 + net/net_connect_options_connectlistener.md | 2 + net/net_connect_path_connectlistener.md | 2 + net/net_connect_port_host_connectlistener.md | 2 + ...ateconnection_port_host_connectlistener.md | 2 +- net/server_connections.md | 2 + net/server_maxconnections.md | 2 + net/socket_buffersize.md | 2 + net/socket_bytesread.md | 2 + net/socket_byteswritten.md | 2 + net/socket_connecting.md | 2 + net/socket_localaddress.md | 2 + net/socket_localport.md | 2 + net/socket_remoteaddress.md | 2 + net/socket_remotefamily.md | 2 + net/socket_remoteport.md | 2 + .../performanceobserver_observe_options.md | 1 + process/event_warning.md | 4 +- process/process_config.md | 2 +- process/process_hrtime_bigint.md | 8 +- process/process_resourceusage.md | 78 +++++----- process/process_throwdeprecation.md | 23 ++- repl/replserver_definecommand_keyword_cmd.md | 2 +- stream/event_readable.md | 2 +- stream/implementing_a_writable_stream.md | 4 +- ...o_writable_streams_from_async_iterators.md | 28 +++- stream/readable_destroy_error.md | 8 +- stream/readable_readableflowing.md | 9 ++ ...stream_finished_stream_options_callback.md | 30 ++-- stream/stream_pipeline_streams_callback.md | 22 +-- stream/transform_destroy_error.md | 2 +- stream/writable_destroy_error.md | 4 +- ...ritable_write_chunk_encoding_callback_1.md | 8 +- tls/certificate_object.md | 2 + tls/tls_createsecurecontext_options.md | 10 ++ tls/tlssocket_getcipher.md | 2 +- tls/tlssocket_getsharedsigalgs.md | 11 ++ url/url_format_urlobject.md | 6 +- util/textencoder_encodeinto_src_dest.md | 17 +++ util/util_extend_target_source.md | 1 + util/util_format_format_args.md | 5 +- ..._inspect_object_showhidden_depth_colors.md | 20 ++- ...or_new_vm_sourcetextmodule_code_options.md | 12 +- vm/module_evaluate_options.md | 4 +- vm/module_link_linker.md | 8 +- vm/module_linkingstatus.md | 8 +- vm/module_status.md | 16 +- worker_threads/class_worker.md | 24 +-- .../port_postmessage_value_transferlist.md | 11 +- worker_threads/worker_threads.md | 2 +- zlib/for_brotli_based_streams.md | 4 +- ..._brotlicompress_buffer_options_callback.md | 1 + .../zlib_brotlicompresssync_buffer_options.md | 1 + ...rotlidecompress_buffer_options_callback.md | 1 + ...lib_brotlidecompresssync_buffer_options.md | 1 + zlib/zlib_deflate_buffer_options_callback.md | 1 + 342 files changed, 1482 insertions(+), 1040 deletions(-) create mode 100644 cli/coverage_output.md create mode 100644 cli/source_map_cache.md create mode 100644 errors/err_inspector_not_worker.md create mode 100644 esm/compatibility_with_commonjs_only_versions_of_node_js.md create mode 100644 esm/packages.md create mode 100644 http2/request_complete.md create mode 100644 inspector/session_connecttomainthread.md create mode 100644 stream/readable_readableflowing.md create mode 100644 tls/tlssocket_getsharedsigalgs.md create mode 100644 util/textencoder_encodeinto_src_dest.md diff --git a/assert/assert_deepequal_actual_expected_message.md b/assert/assert_deepequal_actual_expected_message.md index 6fba4e0c..830d57b2 100644 --- a/assert/assert_deepequal_actual_expected_message.md +++ b/assert/assert_deepequal_actual_expected_message.md @@ -21,6 +21,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/5910 description: Handle non-`Uint8Array` typed arrays correctly. --> + * `actual` {any} * `expected` {any} * `message` {string|Error} diff --git a/assert/assert_equal_actual_expected_message.md b/assert/assert_equal_actual_expected_message.md index fa763d66..ae0873eb 100644 --- a/assert/assert_equal_actual_expected_message.md +++ b/assert/assert_equal_actual_expected_message.md @@ -1,6 +1,7 @@ + * `actual` {any} * `expected` {any} * `message` {string|Error} diff --git a/assert/assert_fail_actual_expected_message_operator_stackstartfn.md b/assert/assert_fail_actual_expected_message_operator_stackstartfn.md index c7771a4b..c4b36f22 100644 --- a/assert/assert_fail_actual_expected_message_operator_stackstartfn.md +++ b/assert/assert_fail_actual_expected_message_operator_stackstartfn.md @@ -6,6 +6,7 @@ changes: description: Calling `assert.fail()` with more than one argument is deprecated and emits a warning. --> + * `actual` {any} * `expected` {any} * `message` {string|Error} diff --git a/assert/assert_notdeepequal_actual_expected_message.md b/assert/assert_notdeepequal_actual_expected_message.md index 51fafc94..73d01490 100644 --- a/assert/assert_notdeepequal_actual_expected_message.md +++ b/assert/assert_notdeepequal_actual_expected_message.md @@ -17,6 +17,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/5910 description: Handle non-`Uint8Array` typed arrays correctly. --> + * `actual` {any} * `expected` {any} * `message` {string|Error} diff --git a/assert/assert_notequal_actual_expected_message.md b/assert/assert_notequal_actual_expected_message.md index 2f9a846e..76ec0977 100644 --- a/assert/assert_notequal_actual_expected_message.md +++ b/assert/assert_notequal_actual_expected_message.md @@ -1,6 +1,7 @@ + * `actual` {any} * `expected` {any} * `message` {string|Error} diff --git a/async_hooks/async_hooks_createhook_callbacks.md b/async_hooks/async_hooks_createhook_callbacks.md index f45c45f0..a459b911 100644 --- a/async_hooks/async_hooks_createhook_callbacks.md +++ b/async_hooks/async_hooks_createhook_callbacks.md @@ -8,6 +8,7 @@ added: v8.1.0 * `before` {Function} The [`before` callback][]. * `after` {Function} The [`after` callback][]. * `destroy` {Function} The [`destroy` callback][]. + * `promiseResolve` {Function} The [`promiseResolve` callback][]. * Returns: {AsyncHook} Instance used for disabling and enabling hooks Registers functions to be called for different lifetime events of each async diff --git a/async_hooks/asyncresource_triggerasyncid.md b/async_hooks/asyncresource_triggerasyncid.md index 20e00cd7..b6cd2e94 100644 --- a/async_hooks/asyncresource_triggerasyncid.md +++ b/async_hooks/asyncresource_triggerasyncid.md @@ -10,3 +10,4 @@ + diff --git a/buffer/the_zero_fill_buffers_command_line_option.md b/buffer/the_zero_fill_buffers_command_line_option.md index ff524953..e814f500 100644 --- a/buffer/the_zero_fill_buffers_command_line_option.md +++ b/buffer/the_zero_fill_buffers_command_line_option.md @@ -8,7 +8,7 @@ added: v5.10.0 使用这个选项可能会对性能产生重大的负面影响。 建议仅在需要强制新分配的 `Buffer` 实例不能包含可能敏感的旧数据时，才使用 `--zero-fill-buffers` 选项。 -```txt +```console $ node --zero-fill-buffers > Buffer.allocUnsafe(5); diff --git a/child_process/spawning_bat_and_cmd_files_on_windows.md b/child_process/spawning_bat_and_cmd_files_on_windows.md index 549d503b..839aba83 100644 --- a/child_process/spawning_bat_and_cmd_files_on_windows.md +++ b/child_process/spawning_bat_and_cmd_files_on_windows.md @@ -25,7 +25,7 @@ bat.on('exit', (code) => { ```js // 或： -const { exec } = require('child_process'); +const { exec, spawn } = require('child_process'); exec('my.bat', (err, stdout, stderr) => { if (err) { console.error(err); diff --git a/cli/coverage_output.md b/cli/coverage_output.md new file mode 100644 index 00000000..d0758b00 --- /dev/null +++ b/cli/coverage_output.md @@ -0,0 +1,16 @@ + +Coverage is output as an array of [ScriptCoverage][] objects on the top-level +key `result`: + +```json +{ + "result": [ + { + "scriptId": "67", + "url": "internal/tty.js", + "functions": [] + } + ] +} +``` + diff --git a/cli/http_parser_library.md b/cli/http_parser_library.md index b51e27cb..3013c951 100644 --- a/cli/http_parser_library.md +++ b/cli/http_parser_library.md @@ -4,8 +4,8 @@ added: v11.4.0 Chooses an HTTP parser library. Available values are: -- `llhttp` for https://llhttp.org/ -- `legacy` for https://github.com/nodejs/http-parser +* `llhttp` for https://llhttp.org/ +* `legacy` for https://github.com/nodejs/http-parser The default is `llhttp`, unless otherwise specified when building Node.js. diff --git a/cli/node_options_options.md b/cli/node_options_options.md index 12569081..6ff6d60e 100644 --- a/cli/node_options_options.md +++ b/cli/node_options_options.md @@ -35,79 +35,79 @@ node --require "./a.js" --require "./b.js" Node.js options that are allowed are: -- `--enable-fips` -- `--es-module-specifier-resolution` -- `--experimental-exports` -- `--experimental-modules` -- `--experimental-policy` -- `--experimental-repl-await` -- `--experimental-report` -- `--experimental-vm-modules` -- `--experimental-wasm-modules` -- `--force-fips` -- `--frozen-intrinsics` -- `--heapsnapshot-signal` -- `--http-parser` -- `--http-server-default-timeout` -- `--icu-data-dir` -- `--input-type` -- `--inspect-brk` -- `--inspect-port`, `--debug-port` -- `--inspect-publish-uid` -- `--inspect` -- `--loader` -- `--max-http-header-size` -- `--napi-modules` -- `--no-deprecation` -- `--no-force-async-hooks-checks` -- `--no-warnings` -- `--openssl-config` -- `--pending-deprecation` -- `--policy-integrity` -- `--preserve-symlinks-main` -- `--preserve-symlinks` -- `--prof-process` -- `--redirect-warnings` -- `--report-directory` -- `--report-filename` -- `--report-on-fatalerror` -- `--report-on-signal` -- `--report-signal` -- `--report-uncaught-exception` -- `--require`, `-r` -- `--throw-deprecation` -- `--title` -- `--tls-cipher-list` -- `--tls-max-v1.2` -- `--tls-max-v1.3` -- `--tls-min-v1.0` -- `--tls-min-v1.1` -- `--tls-min-v1.2` -- `--tls-min-v1.3` -- `--trace-deprecation` -- `--trace-event-categories` -- `--trace-event-file-pattern` -- `--trace-events-enabled` -- `--trace-sync-io` -- `--trace-tls` -- `--trace-warnings` -- `--track-heap-objects` -- `--unhandled-rejections` -- `--use-bundled-ca` -- `--use-openssl-ca` -- `--v8-pool-size` -- `--zero-fill-buffers` +* `--enable-fips` +* `--es-module-specifier-resolution` +* `--experimental-exports` +* `--experimental-modules` +* `--experimental-policy` +* `--experimental-repl-await` +* `--experimental-report` +* `--experimental-vm-modules` +* `--experimental-wasm-modules` +* `--force-fips` +* `--frozen-intrinsics` +* `--heapsnapshot-signal` +* `--http-parser` +* `--http-server-default-timeout` +* `--icu-data-dir` +* `--input-type` +* `--inspect-brk` +* `--inspect-port`, `--debug-port` +* `--inspect-publish-uid` +* `--inspect` +* `--loader` +* `--max-http-header-size` +* `--napi-modules` +* `--no-deprecation` +* `--no-force-async-hooks-checks` +* `--no-warnings` +* `--openssl-config` +* `--pending-deprecation` +* `--policy-integrity` +* `--preserve-symlinks-main` +* `--preserve-symlinks` +* `--prof-process` +* `--redirect-warnings` +* `--report-directory` +* `--report-filename` +* `--report-on-fatalerror` +* `--report-on-signal` +* `--report-signal` +* `--report-uncaught-exception` +* `--require`, `-r` +* `--throw-deprecation` +* `--title` +* `--tls-cipher-list` +* `--tls-max-v1.2` +* `--tls-max-v1.3` +* `--tls-min-v1.0` +* `--tls-min-v1.1` +* `--tls-min-v1.2` +* `--tls-min-v1.3` +* `--trace-deprecation` +* `--trace-event-categories` +* `--trace-event-file-pattern` +* `--trace-events-enabled` +* `--trace-sync-io` +* `--trace-tls` +* `--trace-warnings` +* `--track-heap-objects` +* `--unhandled-rejections` +* `--use-bundled-ca` +* `--use-openssl-ca` +* `--v8-pool-size` +* `--zero-fill-buffers` V8 options that are allowed are: -- `--abort-on-uncaught-exception` -- `--interpreted-frames-native-stack` -- `--max-old-space-size` -- `--perf-basic-prof-only-functions` -- `--perf-basic-prof` -- `--perf-prof-unwinding-info` -- `--perf-prof` -- `--stack-trace-limit` +* `--abort-on-uncaught-exception` +* `--interpreted-frames-native-stack` +* `--max-old-space-size` +* `--perf-basic-prof-only-functions` +* `--perf-basic-prof` +* `--perf-prof-unwinding-info` +* `--perf-prof` +* `--stack-trace-limit` diff --git a/cli/node_v8_coverage_dir.md b/cli/node_v8_coverage_dir.md index 6cb3e075..b363a8ce 100644 --- a/cli/node_v8_coverage_dir.md +++ b/cli/node_v8_coverage_dir.md @@ -1,25 +1,10 @@ -When set, Node.js will begin outputting [V8 JavaScript code coverage][] to the -directory provided as an argument. Coverage is output as an array of - - -```json -{ - "result": [ - { - "scriptId": "67", - "url": "internal/tty.js", - "functions": [] - } - ] -} -``` +When set, Node.js will begin outputting [V8 JavaScript code coverage][] and +[Source Map][] data to the directory provided as an argument (coverage +information is written as JSON to files with a `coverage` prefix). `NODE_V8_COVERAGE` will automatically propagate to subprocesses, making it easier to instrument applications that call the `child_process.spawn()` family of functions. `NODE_V8_COVERAGE` can be set to an empty string, to prevent propagation. -At this time coverage is only collected in the main thread and will not be -output for code executed by worker threads. - diff --git a/cli/source_map_cache.md b/cli/source_map_cache.md new file mode 100644 index 00000000..7488036e --- /dev/null +++ b/cli/source_map_cache.md @@ -0,0 +1,40 @@ + +> Stability: 1 - Experimental + +If found, Source Map data is appended to the top-level key `source-map-cache` +on the JSON coverage object. + +`source-map-cache` is an object with keys representing the files source maps +were extracted from, and the values include the raw source-map URL +(in the key `url`) and the parsed Source Map V3 information (in the key `data`). + +```json +{ + "result": [ + { + "scriptId": "68", + "url": "file:///absolute/path/to/source.js", + "functions": [] + } + ], + "source-map-cache": { + "file:///absolute/path/to/source.js": { + "url": "./path-to-map.json", + "data": { + "version": 3, + "sources": [ + "file:///absolute/path/to/original.js" + ], + "names": [ + "Foo", + "console", + "info" + ], + "mappings": "MAAMA,IACJC,YAAaC", + "sourceRoot": "./" + } + } + } +} +``` + diff --git a/cli/uv_threadpool_size_size.md b/cli/uv_threadpool_size_size.md index ce1eefc8..f5d10287 100644 --- a/cli/uv_threadpool_size_size.md +++ b/cli/uv_threadpool_size_size.md @@ -5,12 +5,12 @@ Asynchronous system APIs are used by Node.js whenever possible, but where they do not exist, libuv's threadpool is used to create asynchronous node APIs based on synchronous system APIs. Node.js APIs that use the threadpool are: -- all `fs` APIs, other than the file watcher APIs and those that are explicitly +* all `fs` APIs, other than the file watcher APIs and those that are explicitly synchronous -- asynchronous crypto APIs such as `crypto.pbkdf2()`, `crypto.scrypt()`, +* asynchronous crypto APIs such as `crypto.pbkdf2()`, `crypto.scrypt()`, `crypto.randomBytes()`, `crypto.randomFill()`, `crypto.generateKeyPair()` -- `dns.lookup()` -- all `zlib` APIs, other than those that are explicitly synchronous +* `dns.lookup()` +* all `zlib` APIs, other than those that are explicitly synchronous Because libuv's threadpool has a fixed size, it means that if for whatever reason any of these APIs takes a long time, other (seemingly unrelated) APIs @@ -38,4 +38,5 @@ greater than `4` (its current default value). For more information, see the + diff --git a/cluster/cluster.md b/cluster/cluster.md index df22c223..673437c8 100644 --- a/cluster/cluster.md +++ b/cluster/cluster.md @@ -38,7 +38,7 @@ if (cluster.isMaster) { 运行代码，则工作进程会共享 8000 端口： -```txt +```console $ node server.js 主进程 3596 正在运行 工作进程 4324 已启动 diff --git a/cluster/worker_exitedafterdisconnect.md b/cluster/worker_exitedafterdisconnect.md index 0a176727..aeacc8d3 100644 --- a/cluster/worker_exitedafterdisconnect.md +++ b/cluster/worker_exitedafterdisconnect.md @@ -4,14 +4,17 @@ added: v6.0.0 * {boolean} -当调用 `.kill()` 或者 `.disconnect()` 方法时被设置，在这之前都是 `undefined`。 +如果工作进程由于 `.kill()` 或 `.disconnect()` 而退出，则此属性为 `true`。 +如果工作进程以任何其他方式退出，则为 `false`。 +如果工作进程尚未退出，则为 `undefined`。 + +[`worker.exitedAfterDisconnect`] 可以用于区分自发退出还是被动退出，主进程可以根据这个值决定是否重新衍生工作进程。 -[`worker.exitedAfterDisconnect`] 可以用于区分自发退出还是被动退出，主进程可以根据这个值决定是否重新衍生新的工作进程。 ```js cluster.on('exit', (worker, code, signal) => { if (worker.exitedAfterDisconnect === true) { - console.log('这是自发退出，无需担心。'); + console.log('这是自发退出，无需担心'); } }); diff --git a/crypto/ccm_mode.md b/crypto/ccm_mode.md index 90b2d43f..7dfd68e4 100644 --- a/crypto/ccm_mode.md +++ b/crypto/ccm_mode.md @@ -2,24 +2,24 @@ CCM is one of the supported [AEAD algorithms][]. Applications which use this mode must adhere to certain restrictions when using the cipher API: -- The authentication tag length must be specified during cipher creation by +* The authentication tag length must be specified during cipher creation by setting the `authTagLength` option and must be one of 4, 6, 8, 10, 12, 14 or 16 bytes. -- The length of the initialization vector (nonce) `N` must be between 7 and 13 +* The length of the initialization vector (nonce) `N` must be between 7 and 13 bytes (`7 ≤ N ≤ 13`). -- The length of the plaintext is limited to `2 ** (8 * (15 - N))` bytes. -- When decrypting, the authentication tag must be set via `setAuthTag()` before +* The length of the plaintext is limited to `2 ** (8 * (15 - N))` bytes. +* When decrypting, the authentication tag must be set via `setAuthTag()` before calling `update()`. Otherwise, decryption will fail and `final()` will throw an error in compliance with section 2.6 of [RFC 3610][]. -- Using stream methods such as `write(data)`, `end(data)` or `pipe()` in CCM +* Using stream methods such as `write(data)`, `end(data)` or `pipe()` in CCM mode might fail as CCM cannot handle more than one chunk of data per instance. -- When passing additional authenticated data (AAD), the length of the actual +* When passing additional authenticated data (AAD), the length of the actual message in bytes must be passed to `setAAD()` via the `plaintextLength` option. This is not necessary if no AAD is used. -- As CCM processes the whole message at once, `update()` can only be called +* As CCM processes the whole message at once, `update()` can only be called once. -- Even though calling `update()` is sufficient to encrypt/decrypt the message, +* Even though calling `update()` is sufficient to encrypt/decrypt the message, applications *must* call `final()` to compute or verify the authentication tag. diff --git a/crypto/certificate_exportchallenge_spkac_1.md b/crypto/certificate_exportchallenge_spkac_1.md index 08ecac51..4a3143d7 100644 --- a/crypto/certificate_exportchallenge_spkac_1.md +++ b/crypto/certificate_exportchallenge_spkac_1.md @@ -1,6 +1,7 @@ + * `spkac` {string | Buffer | TypedArray | DataView} * Returns: {Buffer} The challenge component of the `spkac` data structure, which includes a public key and a challenge. diff --git a/crypto/certificate_exportpublickey_spkac.md b/crypto/certificate_exportpublickey_spkac.md index 631fc6cb..5a4a507c 100644 --- a/crypto/certificate_exportpublickey_spkac.md +++ b/crypto/certificate_exportpublickey_spkac.md @@ -1,6 +1,7 @@ + * `spkac` {string | Buffer | TypedArray | DataView} * Returns: {Buffer} The public key component of the `spkac` data structure, which includes a public key and a challenge. diff --git a/crypto/certificate_exportpublickey_spkac_encoding.md b/crypto/certificate_exportpublickey_spkac_encoding.md index 0c79ac0c..817c6b36 100644 --- a/crypto/certificate_exportpublickey_spkac_encoding.md +++ b/crypto/certificate_exportpublickey_spkac_encoding.md @@ -1,6 +1,7 @@ + * `spkac` {string | Buffer | TypedArray | DataView} * `encoding` {string} The [encoding][] of the `spkac` string. * Returns: {Buffer} The public key component of the `spkac` data structure, diff --git a/crypto/certificate_verifyspkac_spkac_1.md b/crypto/certificate_verifyspkac_spkac_1.md index 70ba15bc..a818e6ab 100644 --- a/crypto/certificate_verifyspkac_spkac_1.md +++ b/crypto/certificate_verifyspkac_spkac_1.md @@ -1,6 +1,7 @@ + * `spkac` {Buffer | TypedArray | DataView} * Returns: {boolean} `true` if the given `spkac` data structure is valid, `false` otherwise. diff --git a/crypto/cipher_setaad_buffer_options.md b/crypto/cipher_setaad_buffer_options.md index 4bbbdd69..ca430882 100644 --- a/crypto/cipher_setaad_buffer_options.md +++ b/crypto/cipher_setaad_buffer_options.md @@ -1,9 +1,10 @@ + * `buffer` {Buffer} * `options` {Object} [`stream.transform` options][] - - `plaintextLength` {number} + * `plaintextLength` {number} * Returns: {Cipher} for method chaining. When using an authenticated encryption mode (`GCM`, `CCM` and `OCB` are diff --git a/crypto/crypto_constants.md b/crypto/crypto_constants.md index a229d1e9..2fff481b 100644 --- a/crypto/crypto_constants.md +++ b/crypto/crypto_constants.md @@ -1,6 +1,7 @@ + * Returns: {Object} An object containing commonly used constants for crypto and security related operations. The specific constants currently defined are described in [Crypto Constants][]. diff --git a/crypto/crypto_createcipheriv_algorithm_key_iv_options.md b/crypto/crypto_createcipheriv_algorithm_key_iv_options.md index a3c8429e..fa593a99 100644 --- a/crypto/crypto_createcipheriv_algorithm_key_iv_options.md +++ b/crypto/crypto_createcipheriv_algorithm_key_iv_options.md @@ -19,6 +19,7 @@ changes: description: The `iv` parameter may now be `null` for ciphers which do not need an initialization vector. --> + * `algorithm` {string} * `key` {string | Buffer | TypedArray | DataView | KeyObject} * `iv` {string | Buffer | TypedArray | DataView} diff --git a/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md b/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md index 4c9484bd..bfa4749f 100644 --- a/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md +++ b/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md @@ -19,6 +19,7 @@ changes: description: The `iv` parameter may now be `null` for ciphers which do not need an initialization vector. --> + * `algorithm` {string} * `key` {string | Buffer | TypedArray | DataView} * `iv` {string | Buffer | TypedArray | DataView} diff --git a/crypto/crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding.md b/crypto/crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding.md index 7cfeff5e..913f3b4c 100644 --- a/crypto/crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding.md +++ b/crypto/crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding.md @@ -12,6 +12,7 @@ changes: description: The default for the encoding parameters changed from `binary` to `utf8`. --> + * `prime` {string | Buffer | TypedArray | DataView} * `primeEncoding` {string} The [encoding][] of the `prime` string. * `generator` {number | string | Buffer | TypedArray | DataView} **Default:** diff --git a/crypto/crypto_creatediffiehellman_primelength_generator.md b/crypto/crypto_creatediffiehellman_primelength_generator.md index 674631dd..a2c898ab 100644 --- a/crypto/crypto_creatediffiehellman_primelength_generator.md +++ b/crypto/crypto_creatediffiehellman_primelength_generator.md @@ -1,6 +1,7 @@ + * `primeLength` {number} * `generator` {number | string | Buffer | TypedArray | DataView} **Default:** `2` diff --git a/crypto/crypto_createecdh_curvename.md b/crypto/crypto_createecdh_curvename.md index d9da8f3b..2f2c6f76 100644 --- a/crypto/crypto_createecdh_curvename.md +++ b/crypto/crypto_createecdh_curvename.md @@ -1,6 +1,7 @@ + * `curveName` {string} * Returns: {ECDH} diff --git a/crypto/crypto_createhash_algorithm_options.md b/crypto/crypto_createhash_algorithm_options.md index 8699f71c..3de1c630 100644 --- a/crypto/crypto_createhash_algorithm_options.md +++ b/crypto/crypto_createhash_algorithm_options.md @@ -5,6 +5,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/28805 description: The `outputLength` option was added for XOF hash functions. --> + * `algorithm` {string} * `options` {Object} [`stream.transform` options][] * Returns: {Hash} diff --git a/crypto/crypto_createhmac_algorithm_key_options.md b/crypto/crypto_createhmac_algorithm_key_options.md index 49a7c27b..5b4cdeac 100644 --- a/crypto/crypto_createhmac_algorithm_key_options.md +++ b/crypto/crypto_createhmac_algorithm_key_options.md @@ -5,6 +5,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/24234 description: The `key` argument can now be a `KeyObject`. --> + * `algorithm` {string} * `key` {string | Buffer | TypedArray | DataView | KeyObject} * `options` {Object} [`stream.transform` options][] diff --git a/crypto/crypto_createprivatekey_key.md b/crypto/crypto_createprivatekey_key.md index cfa3c37d..ea848182 100644 --- a/crypto/crypto_createprivatekey_key.md +++ b/crypto/crypto_createprivatekey_key.md @@ -1,12 +1,13 @@ + * `key` {Object | string | Buffer} - - `key`: {string | Buffer} The key material, either in PEM or DER format. - - `format`: {string} Must be `'pem'` or `'der'`. **Default:** `'pem'`. - - `type`: {string} Must be `'pkcs1'`, `'pkcs8'` or `'sec1'`. This option is + * `key`: {string | Buffer} The key material, either in PEM or DER format. + * `format`: {string} Must be `'pem'` or `'der'`. **Default:** `'pem'`. + * `type`: {string} Must be `'pkcs1'`, `'pkcs8'` or `'sec1'`. This option is required only if the `format` is `'der'` and ignored if it is `'pem'`. - - `passphrase`: {string | Buffer} The passphrase to use for decryption. + * `passphrase`: {string | Buffer} The passphrase to use for decryption. * Returns: {KeyObject} Creates and returns a new key object containing a private key. If `key` is a diff --git a/crypto/crypto_createpublickey_key.md b/crypto/crypto_createpublickey_key.md index c4c14649..d6ca2797 100644 --- a/crypto/crypto_createpublickey_key.md +++ b/crypto/crypto_createpublickey_key.md @@ -9,10 +9,11 @@ changes: pr-url: https://github.com/nodejs/node/pull/25217 description: The `key` argument can now be a private key. --> + * `key` {Object | string | Buffer | KeyObject} - - `key`: {string | Buffer} - - `format`: {string} Must be `'pem'` or `'der'`. **Default:** `'pem'`. - - `type`: {string} Must be `'pkcs1'` or `'spki'`. This option is required + * `key`: {string | Buffer} + * `format`: {string} Must be `'pem'` or `'der'`. **Default:** `'pem'`. + * `type`: {string} Must be `'pkcs1'` or `'spki'`. This option is required only if the `format` is `'der'`. * Returns: {KeyObject} diff --git a/crypto/crypto_createsecretkey_key.md b/crypto/crypto_createsecretkey_key.md index 6b958039..e55f576e 100644 --- a/crypto/crypto_createsecretkey_key.md +++ b/crypto/crypto_createsecretkey_key.md @@ -1,6 +1,7 @@ + * `key` {Buffer} * Returns: {KeyObject} diff --git a/crypto/crypto_createsign_algorithm_options.md b/crypto/crypto_createsign_algorithm_options.md index 35a1a4f3..3fae7e89 100644 --- a/crypto/crypto_createsign_algorithm_options.md +++ b/crypto/crypto_createsign_algorithm_options.md @@ -1,6 +1,7 @@ + * `algorithm` {string} * `options` {Object} [`stream.Writable` options][] * Returns: {Sign} diff --git a/crypto/crypto_createverify_algorithm_options.md b/crypto/crypto_createverify_algorithm_options.md index 69dac4f9..4ccc6e86 100644 --- a/crypto/crypto_createverify_algorithm_options.md +++ b/crypto/crypto_createverify_algorithm_options.md @@ -1,6 +1,7 @@ + * `algorithm` {string} * `options` {Object} [`stream.Writable` options][] * Returns: {Verify} diff --git a/crypto/crypto_generatekeypair_type_options_callback.md b/crypto/crypto_generatekeypair_type_options_callback.md index 62f20c9d..9dd7de50 100644 --- a/crypto/crypto_generatekeypair_type_options_callback.md +++ b/crypto/crypto_generatekeypair_type_options_callback.md @@ -12,19 +12,20 @@ changes: description: The `generateKeyPair` and `generateKeyPairSync` functions now produce key objects if no encoding was specified. --> + * `type`: {string} Must be `'rsa'`, `'dsa'`, `'ec'`, `'ed25519'`, `'ed448'`, `'x25519'`, or `'x448'`. * `options`: {Object} - - `modulusLength`: {number} Key size in bits (RSA, DSA). - - `publicExponent`: {number} Public exponent (RSA). **Default:** `0x10001`. - - `divisorLength`: {number} Size of `q` in bits (DSA). - - `namedCurve`: {string} Name of the curve to use (EC). - - `publicKeyEncoding`: {Object} See [`keyObject.export()`][]. - - `privateKeyEncoding`: {Object} See [`keyObject.export()`][]. + * `modulusLength`: {number} Key size in bits (RSA, DSA). + * `publicExponent`: {number} Public exponent (RSA). **Default:** `0x10001`. + * `divisorLength`: {number} Size of `q` in bits (DSA). + * `namedCurve`: {string} Name of the curve to use (EC). + * `publicKeyEncoding`: {Object} See [`keyObject.export()`][]. + * `privateKeyEncoding`: {Object} See [`keyObject.export()`][]. * `callback`: {Function} - - `err`: {Error} - - `publicKey`: {string | Buffer | KeyObject} - - `privateKey`: {string | Buffer | KeyObject} + * `err`: {Error} + * `publicKey`: {string | Buffer | KeyObject} + * `privateKey`: {string | Buffer | KeyObject} Generates a new asymmetric key pair of the given `type`. RSA, DSA, EC, Ed25519 and Ed448 are currently supported. diff --git a/crypto/crypto_generatekeypairsync_type_options.md b/crypto/crypto_generatekeypairsync_type_options.md index d8e17c27..6e81d3eb 100644 --- a/crypto/crypto_generatekeypairsync_type_options.md +++ b/crypto/crypto_generatekeypairsync_type_options.md @@ -9,17 +9,18 @@ changes: description: The `generateKeyPair` and `generateKeyPairSync` functions now produce key objects if no encoding was specified. --> + * `type`: {string} Must be `'rsa'`, `'dsa'`, `'ec'`, `'ed25519'`, or `'ed448'`. * `options`: {Object} - - `modulusLength`: {number} Key size in bits (RSA, DSA). - - `publicExponent`: {number} Public exponent (RSA). **Default:** `0x10001`. - - `divisorLength`: {number} Size of `q` in bits (DSA). - - `namedCurve`: {string} Name of the curve to use (EC). - - `publicKeyEncoding`: {Object} See [`keyObject.export()`][]. - - `privateKeyEncoding`: {Object} See [`keyObject.export()`][]. + * `modulusLength`: {number} Key size in bits (RSA, DSA). + * `publicExponent`: {number} Public exponent (RSA). **Default:** `0x10001`. + * `divisorLength`: {number} Size of `q` in bits (DSA). + * `namedCurve`: {string} Name of the curve to use (EC). + * `publicKeyEncoding`: {Object} See [`keyObject.export()`][]. + * `privateKeyEncoding`: {Object} See [`keyObject.export()`][]. * Returns: {Object} - - `publicKey`: {string | Buffer | KeyObject} - - `privateKey`: {string | Buffer | KeyObject} + * `publicKey`: {string | Buffer | KeyObject} + * `privateKey`: {string | Buffer | KeyObject} Generates a new asymmetric key pair of the given `type`. RSA, DSA, EC, Ed25519 and Ed448 are currently supported. diff --git a/crypto/crypto_getciphers.md b/crypto/crypto_getciphers.md index 5cf9ff93..bd1b32c1 100644 --- a/crypto/crypto_getciphers.md +++ b/crypto/crypto_getciphers.md @@ -1,6 +1,7 @@ + * Returns: {string[]} An array with the names of the supported cipher algorithms. diff --git a/crypto/crypto_getcurves.md b/crypto/crypto_getcurves.md index a6eff7f3..d549489c 100644 --- a/crypto/crypto_getcurves.md +++ b/crypto/crypto_getcurves.md @@ -1,6 +1,7 @@ + * Returns: {string[]} An array with the names of the supported elliptic curves. ```js diff --git a/crypto/crypto_getdiffiehellman_groupname.md b/crypto/crypto_getdiffiehellman_groupname.md index 46e89de0..0885aa56 100644 --- a/crypto/crypto_getdiffiehellman_groupname.md +++ b/crypto/crypto_getdiffiehellman_groupname.md @@ -1,6 +1,7 @@ + * `groupName` {string} * Returns: {DiffieHellman} diff --git a/crypto/crypto_getfips.md b/crypto/crypto_getfips.md index a37fa282..f391d70f 100644 --- a/crypto/crypto_getfips.md +++ b/crypto/crypto_getfips.md @@ -1,6 +1,7 @@ + * Returns: {boolean} `true` if and only if a FIPS compliant crypto provider is currently in use. diff --git a/crypto/crypto_gethashes.md b/crypto/crypto_gethashes.md index 8450ebb5..ba681957 100644 --- a/crypto/crypto_gethashes.md +++ b/crypto/crypto_gethashes.md @@ -1,6 +1,7 @@ + * Returns: {string[]} An array of the names of the supported hash algorithms, such as `'RSA-SHA256'`. Hash algorithms are also called "digest" algorithms. diff --git a/crypto/crypto_pbkdf2_password_salt_iterations_keylen_digest_callback.md b/crypto/crypto_pbkdf2_password_salt_iterations_keylen_digest_callback.md index 5002a1be..80c3906d 100644 --- a/crypto/crypto_pbkdf2_password_salt_iterations_keylen_digest_callback.md +++ b/crypto/crypto_pbkdf2_password_salt_iterations_keylen_digest_callback.md @@ -13,14 +13,15 @@ changes: description: The default encoding for `password` if it is a string changed from `binary` to `utf8`. --> + * `password` {string|Buffer|TypedArray|DataView} * `salt` {string|Buffer|TypedArray|DataView} * `iterations` {number} * `keylen` {number} * `digest` {string} * `callback` {Function} - - `err` {Error} - - `derivedKey` {Buffer} + * `err` {Error} + * `derivedKey` {Buffer} Provides an asynchronous Password-Based Key Derivation Function 2 (PBKDF2) implementation. A selected HMAC digest algorithm specified by `digest` is diff --git a/crypto/crypto_pbkdf2sync_password_salt_iterations_keylen_digest.md b/crypto/crypto_pbkdf2sync_password_salt_iterations_keylen_digest.md index 892e8b5a..e31bf70c 100644 --- a/crypto/crypto_pbkdf2sync_password_salt_iterations_keylen_digest.md +++ b/crypto/crypto_pbkdf2sync_password_salt_iterations_keylen_digest.md @@ -10,6 +10,7 @@ changes: description: The default encoding for `password` if it is a string changed from `binary` to `utf8`. --> + * `password` {string|Buffer|TypedArray|DataView} * `salt` {string|Buffer|TypedArray|DataView} * `iterations` {number} diff --git a/crypto/crypto_privatedecrypt_privatekey_buffer.md b/crypto/crypto_privatedecrypt_privatekey_buffer.md index 9c9e4846..f91d3202 100644 --- a/crypto/crypto_privatedecrypt_privatekey_buffer.md +++ b/crypto/crypto_privatedecrypt_privatekey_buffer.md @@ -1,6 +1,9 @@ + * `privateKey` {Object | string | Buffer | KeyObject} - - `oaepHash` {string} The hash function to use for OAEP padding. + * `oaepHash` {string} The hash function to use for OAEP padding. **Default:** `'sha1'` - - `padding` {crypto.constants} An optional padding value defined in + * `padding` {crypto.constants} An optional padding value defined in `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`, `crypto.constants.RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`. diff --git a/crypto/crypto_privateencrypt_privatekey_buffer.md b/crypto/crypto_privateencrypt_privatekey_buffer.md index a24e3be0..bf9c353c 100644 --- a/crypto/crypto_privateencrypt_privatekey_buffer.md +++ b/crypto/crypto_privateencrypt_privatekey_buffer.md @@ -5,10 +5,11 @@ changes: pr-url: https://github.com/nodejs/node/pull/24234 description: This function now supports key objects. --> + * `privateKey` {Object | string | Buffer | KeyObject} - - `key` {string | Buffer | KeyObject} A PEM encoded private key. - - `passphrase` {string | Buffer} An optional passphrase for the private key. - - `padding` {crypto.constants} An optional padding value defined in + * `key` {string | Buffer | KeyObject} A PEM encoded private key. + * `passphrase` {string | Buffer} An optional passphrase for the private key. + * `padding` {crypto.constants} An optional padding value defined in `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or `crypto.constants.RSA_PKCS1_PADDING`. * `buffer` {Buffer | TypedArray | DataView} diff --git a/crypto/crypto_publicdecrypt_key_buffer.md b/crypto/crypto_publicdecrypt_key_buffer.md index e98773e9..40d73227 100644 --- a/crypto/crypto_publicdecrypt_key_buffer.md +++ b/crypto/crypto_publicdecrypt_key_buffer.md @@ -5,9 +5,10 @@ changes: pr-url: https://github.com/nodejs/node/pull/24234 description: This function now supports key objects. --> + * `key` {Object | string | Buffer | KeyObject} - - `passphrase` {string | Buffer} An optional passphrase for the private key. - - `padding` {crypto.constants} An optional padding value defined in + * `passphrase` {string | Buffer} An optional passphrase for the private key. + * `padding` {crypto.constants} An optional padding value defined in `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING` or `crypto.constants.RSA_PKCS1_PADDING`. * `buffer` {Buffer | TypedArray | DataView} diff --git a/crypto/crypto_publicencrypt_key_buffer.md b/crypto/crypto_publicencrypt_key_buffer.md index 4a32526c..f771256f 100644 --- a/crypto/crypto_publicencrypt_key_buffer.md +++ b/crypto/crypto_publicencrypt_key_buffer.md @@ -1,6 +1,9 @@ + * `key` {Object | string | Buffer | KeyObject} - - `key` {string | Buffer | KeyObject} A PEM encoded public or private key. - - `oaepHash` {string} The hash function to use for OAEP padding. + * `key` {string | Buffer | KeyObject} A PEM encoded public or private key. + * `oaepHash` {string} The hash function to use for OAEP padding. **Default:** `'sha1'` - - `passphrase` {string | Buffer} An optional passphrase for the private key. - - `padding` {crypto.constants} An optional padding value defined in + * `passphrase` {string | Buffer} An optional passphrase for the private key. + * `padding` {crypto.constants} An optional padding value defined in `crypto.constants`, which may be: `crypto.constants.RSA_NO_PADDING`, `crypto.constants.RSA_PKCS1_PADDING`, or `crypto.constants.RSA_PKCS1_OAEP_PADDING`. diff --git a/crypto/crypto_scrypt_password_salt_keylen_options_callback.md b/crypto/crypto_scrypt_password_salt_keylen_options_callback.md index 5d199d0a..6f35641b 100644 --- a/crypto/crypto_scrypt_password_salt_keylen_options_callback.md +++ b/crypto/crypto_scrypt_password_salt_keylen_options_callback.md @@ -9,22 +9,23 @@ changes: description: The `cost`, `blockSize` and `parallelization` option names have been added. --> + * `password` {string|Buffer|TypedArray|DataView} * `salt` {string|Buffer|TypedArray|DataView} * `keylen` {number} * `options` {Object} - - `cost` {number} CPU/memory cost parameter. Must be a power of two greater + * `cost` {number} CPU/memory cost parameter. Must be a power of two greater than one. **Default:** `16384`. - - `blockSize` {number} Block size parameter. **Default:** `8`. - - `parallelization` {number} Parallelization parameter. **Default:** `1`. - - `N` {number} Alias for `cost`. Only one of both may be specified. - - `r` {number} Alias for `blockSize`. Only one of both may be specified. - - `p` {number} Alias for `parallelization`. Only one of both may be specified. - - `maxmem` {number} Memory upper bound. It is an error when (approximately) + * `blockSize` {number} Block size parameter. **Default:** `8`. + * `parallelization` {number} Parallelization parameter. **Default:** `1`. + * `N` {number} Alias for `cost`. Only one of both may be specified. + * `r` {number} Alias for `blockSize`. Only one of both may be specified. + * `p` {number} Alias for `parallelization`. Only one of both may be specified. + * `maxmem` {number} Memory upper bound. It is an error when (approximately) `128 * N * r > maxmem`. **Default:** `32 * 1024 * 1024`. * `callback` {Function} - - `err` {Error} - - `derivedKey` {Buffer} + * `err` {Error} + * `derivedKey` {Buffer} Provides an asynchronous [scrypt][] implementation. Scrypt is a password-based key derivation function that is designed to be expensive computationally and diff --git a/crypto/crypto_scryptsync_password_salt_keylen_options.md b/crypto/crypto_scryptsync_password_salt_keylen_options.md index 40f293c1..1fe87303 100644 --- a/crypto/crypto_scryptsync_password_salt_keylen_options.md +++ b/crypto/crypto_scryptsync_password_salt_keylen_options.md @@ -9,18 +9,19 @@ changes: description: The `cost`, `blockSize` and `parallelization` option names have been added. --> + * `password` {string|Buffer|TypedArray|DataView} * `salt` {string|Buffer|TypedArray|DataView} * `keylen` {number} * `options` {Object} - - `cost` {number} CPU/memory cost parameter. Must be a power of two greater + * `cost` {number} CPU/memory cost parameter. Must be a power of two greater than one. **Default:** `16384`. - - `blockSize` {number} Block size parameter. **Default:** `8`. - - `parallelization` {number} Parallelization parameter. **Default:** `1`. - - `N` {number} Alias for `cost`. Only one of both may be specified. - - `r` {number} Alias for `blockSize`. Only one of both may be specified. - - `p` {number} Alias for `parallelization`. Only one of both may be specified. - - `maxmem` {number} Memory upper bound. It is an error when (approximately) + * `blockSize` {number} Block size parameter. **Default:** `8`. + * `parallelization` {number} Parallelization parameter. **Default:** `1`. + * `N` {number} Alias for `cost`. Only one of both may be specified. + * `r` {number} Alias for `blockSize`. Only one of both may be specified. + * `p` {number} Alias for `parallelization`. Only one of both may be specified. + * `maxmem` {number} Memory upper bound. It is an error when (approximately) `128 * N * r > maxmem`. **Default:** `32 * 1024 * 1024`. * Returns: {Buffer} diff --git a/crypto/crypto_setengine_engine_flags.md b/crypto/crypto_setengine_engine_flags.md index a74bd49c..d1a03ec6 100644 --- a/crypto/crypto_setengine_engine_flags.md +++ b/crypto/crypto_setengine_engine_flags.md @@ -1,6 +1,7 @@ + * `engine` {string} * `flags` {crypto.constants} **Default:** `crypto.constants.ENGINE_METHOD_ALL` diff --git a/crypto/crypto_setfips_bool.md b/crypto/crypto_setfips_bool.md index b4c35d64..9e098ccf 100644 --- a/crypto/crypto_setfips_bool.md +++ b/crypto/crypto_setfips_bool.md @@ -1,6 +1,7 @@ + * `bool` {boolean} `true` to enable FIPS mode. Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. diff --git a/crypto/crypto_sign_algorithm_data_key.md b/crypto/crypto_sign_algorithm_data_key.md index e3d05180..7c845413 100644 --- a/crypto/crypto_sign_algorithm_data_key.md +++ b/crypto/crypto_sign_algorithm_data_key.md @@ -1,6 +1,7 @@ + * `algorithm` {string | null | undefined} * `data` {Buffer | TypedArray | DataView} * `key` {Object | string | Buffer | KeyObject} diff --git a/crypto/crypto_timingsafeequal_a_b.md b/crypto/crypto_timingsafeequal_a_b.md index 879357b5..bd483dbc 100644 --- a/crypto/crypto_timingsafeequal_a_b.md +++ b/crypto/crypto_timingsafeequal_a_b.md @@ -1,6 +1,7 @@ + * `a` {Buffer | TypedArray | DataView} * `b` {Buffer | TypedArray | DataView} * Returns: {boolean} diff --git a/crypto/crypto_verify_algorithm_data_key_signature.md b/crypto/crypto_verify_algorithm_data_key_signature.md index 0b62bca0..90215fce 100644 --- a/crypto/crypto_verify_algorithm_data_key_signature.md +++ b/crypto/crypto_verify_algorithm_data_key_signature.md @@ -1,6 +1,7 @@ + * `algorithm` {string | null | undefined} * `data` {Buffer | TypedArray | DataView} * `key` {Object | string | Buffer | KeyObject} diff --git a/crypto/decipher_setaad_buffer_options.md b/crypto/decipher_setaad_buffer_options.md index a0fe481e..5e15f4c9 100644 --- a/crypto/decipher_setaad_buffer_options.md +++ b/crypto/decipher_setaad_buffer_options.md @@ -5,9 +5,10 @@ changes: pr-url: https://github.com/nodejs/node/pull/9398 description: This method now returns a reference to `decipher`. --> + * `buffer` {Buffer | TypedArray | DataView} * `options` {Object} [`stream.transform` options][] - - `plaintextLength` {number} + * `plaintextLength` {number} * Returns: {Decipher} for method chaining. When using an authenticated encryption mode (`GCM`, `CCM` and `OCB` are diff --git a/crypto/decipher_setauthtag_buffer.md b/crypto/decipher_setauthtag_buffer.md index 34b59ccc..0215b619 100644 --- a/crypto/decipher_setauthtag_buffer.md +++ b/crypto/decipher_setauthtag_buffer.md @@ -8,6 +8,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/9398 description: This method now returns a reference to `decipher`. --> + * `buffer` {Buffer | TypedArray | DataView} * Returns: {Decipher} for method chaining. diff --git a/crypto/decipher_setautopadding_autopadding.md b/crypto/decipher_setautopadding_autopadding.md index 134a0eb3..178b18ba 100644 --- a/crypto/decipher_setautopadding_autopadding.md +++ b/crypto/decipher_setautopadding_autopadding.md @@ -1,6 +1,7 @@ + * `autoPadding` {boolean} **Default:** `true` * Returns: {Decipher} for method chaining. diff --git a/crypto/diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding.md b/crypto/diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding.md index e184c24d..8f06dbe2 100644 --- a/crypto/diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding.md +++ b/crypto/diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding.md @@ -1,6 +1,7 @@ + * `otherPublicKey` {string | Buffer | TypedArray | DataView} * `inputEncoding` {string} The [encoding][] of an `otherPublicKey` string. * `outputEncoding` {string} The [encoding][] of the return value. diff --git a/crypto/diffiehellman_generatekeys_encoding.md b/crypto/diffiehellman_generatekeys_encoding.md index ce15db74..60881ac6 100644 --- a/crypto/diffiehellman_generatekeys_encoding.md +++ b/crypto/diffiehellman_generatekeys_encoding.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} diff --git a/crypto/diffiehellman_getgenerator_encoding.md b/crypto/diffiehellman_getgenerator_encoding.md index af183122..f1cda26f 100644 --- a/crypto/diffiehellman_getgenerator_encoding.md +++ b/crypto/diffiehellman_getgenerator_encoding.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} diff --git a/crypto/diffiehellman_getprime_encoding.md b/crypto/diffiehellman_getprime_encoding.md index 86c69b03..b7bb3d8d 100644 --- a/crypto/diffiehellman_getprime_encoding.md +++ b/crypto/diffiehellman_getprime_encoding.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} diff --git a/crypto/diffiehellman_getprivatekey_encoding.md b/crypto/diffiehellman_getprivatekey_encoding.md index 7549926f..28de2fee 100644 --- a/crypto/diffiehellman_getprivatekey_encoding.md +++ b/crypto/diffiehellman_getprivatekey_encoding.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} diff --git a/crypto/diffiehellman_getpublickey_encoding.md b/crypto/diffiehellman_getpublickey_encoding.md index d8336b64..5188dfe5 100644 --- a/crypto/diffiehellman_getpublickey_encoding.md +++ b/crypto/diffiehellman_getpublickey_encoding.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} diff --git a/crypto/diffiehellman_setprivatekey_privatekey_encoding.md b/crypto/diffiehellman_setprivatekey_privatekey_encoding.md index 10756ae2..d32ade58 100644 --- a/crypto/diffiehellman_setprivatekey_privatekey_encoding.md +++ b/crypto/diffiehellman_setprivatekey_privatekey_encoding.md @@ -1,6 +1,7 @@ + * `privateKey` {string | Buffer | TypedArray | DataView} * `encoding` {string} The [encoding][] of the `privateKey` string. diff --git a/crypto/diffiehellman_setpublickey_publickey_encoding.md b/crypto/diffiehellman_setpublickey_publickey_encoding.md index 4f2b6d6b..f3f1a79b 100644 --- a/crypto/diffiehellman_setpublickey_publickey_encoding.md +++ b/crypto/diffiehellman_setpublickey_publickey_encoding.md @@ -1,6 +1,7 @@ + * `publicKey` {string | Buffer | TypedArray | DataView} * `encoding` {string} The [encoding][] of the `publicKey` string. diff --git a/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md b/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md index d52ae2f8..a72cecdf 100644 --- a/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md +++ b/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md @@ -9,6 +9,7 @@ changes: description: Changed error format to better support invalid public key error --> + * `otherPublicKey` {string | Buffer | TypedArray | DataView} * `inputEncoding` {string} The [encoding][] of the `otherPublicKey` string. * `outputEncoding` {string} The [encoding][] of the return value. diff --git a/crypto/ecdh_generatekeys_encoding_format.md b/crypto/ecdh_generatekeys_encoding_format.md index 8f02b814..dae55edd 100644 --- a/crypto/ecdh_generatekeys_encoding_format.md +++ b/crypto/ecdh_generatekeys_encoding_format.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * `format` {string} **Default:** `'uncompressed'` * Returns: {Buffer | string} diff --git a/crypto/ecdh_getprivatekey_encoding.md b/crypto/ecdh_getprivatekey_encoding.md index 3dfd7222..6a91be26 100644 --- a/crypto/ecdh_getprivatekey_encoding.md +++ b/crypto/ecdh_getprivatekey_encoding.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} The EC Diffie-Hellman in the specified `encoding`. diff --git a/crypto/ecdh_getpublickey_encoding_format.md b/crypto/ecdh_getpublickey_encoding_format.md index 305ddcc9..31aec839 100644 --- a/crypto/ecdh_getpublickey_encoding_format.md +++ b/crypto/ecdh_getpublickey_encoding_format.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * `format` {string} **Default:** `'uncompressed'` * Returns: {Buffer | string} The EC Diffie-Hellman public key in the specified diff --git a/crypto/ecdh_setprivatekey_privatekey_encoding.md b/crypto/ecdh_setprivatekey_privatekey_encoding.md index 4c6d41e6..6214c0ee 100644 --- a/crypto/ecdh_setprivatekey_privatekey_encoding.md +++ b/crypto/ecdh_setprivatekey_privatekey_encoding.md @@ -1,6 +1,7 @@ + * `privateKey` {string | Buffer | TypedArray | DataView} * `encoding` {string} The [encoding][] of the `privateKey` string. diff --git a/crypto/hmac_digest_encoding.md b/crypto/hmac_digest_encoding.md index 034215e8..8c61350f 100644 --- a/crypto/hmac_digest_encoding.md +++ b/crypto/hmac_digest_encoding.md @@ -1,6 +1,7 @@ + * `encoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} diff --git a/crypto/hmac_update_data_inputencoding.md b/crypto/hmac_update_data_inputencoding.md index b27ca0fd..840a2d06 100644 --- a/crypto/hmac_update_data_inputencoding.md +++ b/crypto/hmac_update_data_inputencoding.md @@ -5,6 +5,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/5522 description: The default `inputEncoding` changed from `binary` to `utf8`. --> + * `data` {string | Buffer | TypedArray | DataView} * `inputEncoding` {string} The [encoding][] of the `data` string. diff --git a/crypto/keyobject_asymmetrickeytype.md b/crypto/keyobject_asymmetrickeytype.md index 41899078..1aa0e814 100644 --- a/crypto/keyobject_asymmetrickeytype.md +++ b/crypto/keyobject_asymmetrickeytype.md @@ -15,6 +15,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/26319 description: Added support for `'ed25519'` and `'ed448'`. --> + * {string} For asymmetric keys, this property represents the type of the key. Supported key diff --git a/crypto/keyobject_export_options.md b/crypto/keyobject_export_options.md index 8b38d524..99ca821f 100644 --- a/crypto/keyobject_export_options.md +++ b/crypto/keyobject_export_options.md @@ -1,6 +1,7 @@ + * `options`: {Object} * Returns: {string | Buffer} diff --git a/crypto/keyobject_symmetrickeysize.md b/crypto/keyobject_symmetrickeysize.md index a021e001..e7e8a455 100644 --- a/crypto/keyobject_symmetrickeysize.md +++ b/crypto/keyobject_symmetrickeysize.md @@ -1,6 +1,7 @@ + * {number} For secret keys, this property represents the size of the key in bytes. This diff --git a/crypto/keyobject_type.md b/crypto/keyobject_type.md index 2d83f5e6..71fe480f 100644 --- a/crypto/keyobject_type.md +++ b/crypto/keyobject_type.md @@ -1,6 +1,7 @@ + * {string} Depending on the type of this `KeyObject`, this property is either diff --git a/crypto/sign_sign_privatekey_outputencoding.md b/crypto/sign_sign_privatekey_outputencoding.md index 0fb3f63e..c8d0873c 100644 --- a/crypto/sign_sign_privatekey_outputencoding.md +++ b/crypto/sign_sign_privatekey_outputencoding.md @@ -11,9 +11,10 @@ changes: pr-url: https://github.com/nodejs/node/pull/11705 description: Support for RSASSA-PSS and additional options was added. --> + * `privateKey` {Object | string | Buffer | KeyObject} - - `padding` {integer} - - `saltLength` {integer} + * `padding` {integer} + * `saltLength` {integer} * `outputEncoding` {string} The [encoding][] of the return value. * Returns: {Buffer | string} diff --git a/crypto/sign_update_data_inputencoding.md b/crypto/sign_update_data_inputencoding.md index a91863c1..3d8bf3bd 100644 --- a/crypto/sign_update_data_inputencoding.md +++ b/crypto/sign_update_data_inputencoding.md @@ -5,6 +5,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/5522 description: The default `inputEncoding` changed from `binary` to `utf8`. --> + * `data` {string | Buffer | TypedArray | DataView} * `inputEncoding` {string} The [encoding][] of the `data` string. diff --git a/crypto/support_for_weak_or_compromised_algorithms.md b/crypto/support_for_weak_or_compromised_algorithms.md index b2e36263..341d9bfd 100644 --- a/crypto/support_for_weak_or_compromised_algorithms.md +++ b/crypto/support_for_weak_or_compromised_algorithms.md @@ -9,12 +9,12 @@ algorithm and key size according to their security requirements. Based on the recommendations of [NIST SP 800-131A][]: -- MD5 and SHA-1 are no longer acceptable where collision resistance is +* MD5 and SHA-1 are no longer acceptable where collision resistance is required such as digital signatures. -- The key used with RSA, DSA, and DH algorithms is recommended to have +* The key used with RSA, DSA, and DH algorithms is recommended to have at least 2048 bits and that of the curve of ECDSA and ECDH at least 224 bits, to be safe to use for several years. -- The DH groups of `modp1`, `modp2` and `modp5` have a key size +* The DH groups of `modp1`, `modp2` and `modp5` have a key size smaller than 2048 bits and are not recommended. See the reference for other recommendations and details. diff --git a/crypto/verify_update_data_inputencoding.md b/crypto/verify_update_data_inputencoding.md index e2e17753..cad444d4 100644 --- a/crypto/verify_update_data_inputencoding.md +++ b/crypto/verify_update_data_inputencoding.md @@ -5,6 +5,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/5522 description: The default `inputEncoding` changed from `binary` to `utf8`. --> + * `data` {string | Buffer | TypedArray | DataView} * `inputEncoding` {string} The [encoding][] of the `data` string. diff --git a/crypto/verify_verify_object_signature_signatureencoding.md b/crypto/verify_verify_object_signature_signatureencoding.md index 14d4be0e..c2868c75 100644 --- a/crypto/verify_verify_object_signature_signatureencoding.md +++ b/crypto/verify_verify_object_signature_signatureencoding.md @@ -11,9 +11,10 @@ changes: pr-url: https://github.com/nodejs/node/pull/11705 description: Support for RSASSA-PSS and additional options was added. --> + * `object` {Object | string | Buffer | KeyObject} - - `padding` {integer} - - `saltLength` {integer} + * `padding` {integer} + * `saltLength` {integer} * `signature` {string | Buffer | TypedArray | DataView} * `signatureEncoding` {string} The [encoding][] of the `signature` string. * Returns: {boolean} `true` or `false` depending on the validity of the diff --git a/debugger/breakpoints.md b/debugger/breakpoints.md index 392f68b7..dd85fc18 100644 --- a/debugger/breakpoints.md +++ b/debugger/breakpoints.md @@ -7,7 +7,7 @@ 也可以在尚未加载的文件（模块）中设置断点： -```txt +```console $ node inspect main.js < Debugger listening on ws://127.0.0.1:9229/4e3db158-9791-4274-8909-914f7facf3bd < For help, see: https://nodejs.org/en/docs/inspector diff --git a/debugger/debugger.md b/debugger/debugger.md index 4dc61b63..612e61de 100644 --- a/debugger/debugger.md +++ b/debugger/debugger.md @@ -9,7 +9,7 @@ Node.js 包括一个进程外的调试实用程序，可通过[V8检查器][V8 I 要使用它，请使用 `inspect` 参数启动 Node.js，然后使用要调试的脚本的路径。 将显示一个提示，表明调试器成功启动： -```txt +```console $ node inspect myscript.js < Debugger listening on ws://127.0.0.1:9229/80e7a814-7cd3-49fb-921a-2e02228cd5ba < For help, see: https://nodejs.org/en/docs/inspector @@ -39,7 +39,7 @@ console.log('你好'); 运行调试器后，第 3 行将出现断点： -```txt +```console $ node inspect myscript.js < Debugger listening on ws://127.0.0.1:9229/80e7a814-7cd3-49fb-921a-2e02228cd5ba < For help, see: https://nodejs.org/en/docs/inspector diff --git a/debugger/v8_inspector_integration_for_node_js.md b/debugger/v8_inspector_integration_for_node_js.md index 5fa82256..d1f8ce74 100644 --- a/debugger/v8_inspector_integration_for_node_js.md +++ b/debugger/v8_inspector_integration_for_node_js.md @@ -7,7 +7,7 @@ V8 检查器集成允许将 Chrome 开发者工具附加到 Node.js 实例以进 要在应用代码的第一行断开，请传入 `--inspect-brk` 标志而不是 `--inspect`。 -```txt +```console $ node --inspect index.js Debugger listening on 127.0.0.1:9229. To start debugging, open the following URL in Chrome: diff --git a/deprecations/dep0084_requiring_bundled_internal_dependencies.md b/deprecations/dep0084_requiring_bundled_internal_dependencies.md index 398e8c13..e34461d0 100644 --- a/deprecations/dep0084_requiring_bundled_internal_dependencies.md +++ b/deprecations/dep0084_requiring_bundled_internal_dependencies.md @@ -14,19 +14,19 @@ Since Node.js versions 4.4.0 and 5.2.0, several modules only intended for internal usage were mistakenly exposed to user code through `require()`. These modules were: -- `v8/tools/codemap` -- `v8/tools/consarray` -- `v8/tools/csvparser` -- `v8/tools/logreader` -- `v8/tools/profile_view` -- `v8/tools/profile` -- `v8/tools/SourceMap` -- `v8/tools/splaytree` -- `v8/tools/tickprocessor-driver` -- `v8/tools/tickprocessor` -- `node-inspect/lib/_inspect` (from 7.6.0) -- `node-inspect/lib/internal/inspect_client` (from 7.6.0) -- `node-inspect/lib/internal/inspect_repl` (from 7.6.0) +* `v8/tools/codemap` +* `v8/tools/consarray` +* `v8/tools/csvparser` +* `v8/tools/logreader` +* `v8/tools/profile_view` +* `v8/tools/profile` +* `v8/tools/SourceMap` +* `v8/tools/splaytree` +* `v8/tools/tickprocessor-driver` +* `v8/tools/tickprocessor` +* `node-inspect/lib/_inspect` (from 7.6.0) +* `node-inspect/lib/internal/inspect_client` (from 7.6.0) +* `node-inspect/lib/internal/inspect_repl` (from 7.6.0) The `v8/*` modules do not have any exports, and if not imported in a specific order would in fact throw errors. As such there are virtually no legitimate use diff --git a/dns/dns.md b/dns/dns.md index cc925561..c5f4d428 100644 --- a/dns/dns.md +++ b/dns/dns.md @@ -5,46 +5,46 @@ `dns` 模块包含属于两个不同类别的函数： -1) 使用底层操作系统工具执行名称解析但不一定执行任何网络通信的函数。 -此类别仅包含一个函数：[`dns.lookup()`]。 -希望以与同一操作系统上的其他应用程序相同的方式执行名称解析的开发者应使用 [`dns.lookup()`]。 +1. 使用底层操作系统工具执行名称解析但不一定执行任何网络通信的函数。 + 此类别仅包含一个函数：[`dns.lookup()`]。 + 希望以与同一操作系统上的其他应用程序相同的方式执行名称解析的开发者应使用 [`dns.lookup()`]。 -示例，查找 `iana.org`： + 示例，查找 `iana.org`： -```js -const dns = require('dns'); + ```js + const dns = require('dns'); -dns.lookup('iana.org', (err, address, family) => { - console.log('地址: %j 地址族: IPv%s', address, family); -}); -// 地址: "192.0.43.8" 地址族: IPv4 -``` + dns.lookup('iana.org', (err, address, family) => { + console.log('地址: %j 地址族: IPv%s', address, family); + }); + // 地址: "192.0.43.8" 地址族: IPv4 + ``` -2) 连接到实际 DNS 服务器以执行名称解析并始终使用网络执行 DNS 查询的函数。 -此类别包含 `dns` 模块中除 [`dns.lookup()`] 之外的所有函数。 -这些函数不使用与 [`dns.lookup()`] 使用的同一组配置文件（例如 `/etc/hosts`）。 -这些函数应该由不希望使用底层操作系统的工具进行名称解析、而希望始终执行 DNS 查询的开发者使用，。 +2. 连接到实际 DNS 服务器以执行名称解析并始终使用网络执行 DNS 查询的函数。 + 此类别包含 `dns` 模块中除 [`dns.lookup()`] 之外的所有函数。 + 这些函数不使用与 [`dns.lookup()`] 使用的同一组配置文件（例如 `/etc/hosts`）。 + 这些函数应该由不希望使用底层操作系统的工具进行名称解析、而希望始终执行 DNS 查询的开发者使用，。 -示例，解析 `'archive.org'` 然后逆向解析返回的 IP 地址： + 示例，解析 `'archive.org'` 然后逆向解析返回的 IP 地址： -```js -const dns = require('dns'); + ```js + const dns = require('dns'); -dns.resolve4('archive.org', (err, addresses) => { - if (err) throw err; + dns.resolve4('archive.org', (err, addresses) => { + if (err) throw err; - console.log(`地址: ${JSON.stringify(addresses)}`); + console.log(`地址: ${JSON.stringify(addresses)}`); - addresses.forEach((a) => { - dns.reverse(a, (err, hostnames) => { - if (err) { - throw err; - } - console.log(`地址 ${a} 逆向解析到域名: ${JSON.stringify(hostnames)}`); + addresses.forEach((a) => { + dns.reverse(a, (err, hostnames) => { + if (err) { + throw err; + } + console.log(`地址 ${a} 逆向解析到域名: ${JSON.stringify(hostnames)}`); + }); + }); }); - }); -}); -``` + ``` 两类函数有微妙的差别，详见[实现的注意事项][Implementation considerations section]。 diff --git a/dns/dnspromises_lookup_hostname_options.md b/dns/dnspromises_lookup_hostname_options.md index 7a58ca30..e2ee3243 100644 --- a/dns/dnspromises_lookup_hostname_options.md +++ b/dns/dnspromises_lookup_hostname_options.md @@ -1,16 +1,17 @@ + * `hostname` {string} * `options` {integer | Object} - - `family` {integer} The record family. Must be `4`, `6`, or `0`. The value + * `family` {integer} The record family. Must be `4`, `6`, or `0`. The value `0` indicates that IPv4 and IPv6 addresses are both returned. **Default:** `0`. - - `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple + * `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple flags may be passed by bitwise `OR`ing their values. - - `all` {boolean} When `true`, the `Promise` is resolved with all addresses in + * `all` {boolean} When `true`, the `Promise` is resolved with all addresses in an array. Otherwise, returns a single address. **Default:** `false`. - - `verbatim` {boolean} When `true`, the `Promise` is resolved with IPv4 and + * `verbatim` {boolean} When `true`, the `Promise` is resolved with IPv4 and IPv6 addresses in the order the DNS resolver returned them. When `false`, IPv4 addresses are placed before IPv6 addresses. **Default:** currently `false` (addresses are reordered) but this is diff --git a/dns/dnspromises_lookupservice_address_port.md b/dns/dnspromises_lookupservice_address_port.md index a6b834ce..5fee10be 100644 --- a/dns/dnspromises_lookupservice_address_port.md +++ b/dns/dnspromises_lookupservice_address_port.md @@ -1,6 +1,7 @@ + * `address` {string} * `port` {number} diff --git a/dns/dnspromises_resolve4_hostname_options.md b/dns/dnspromises_resolve4_hostname_options.md index c1578011..76187c41 100644 --- a/dns/dnspromises_resolve4_hostname_options.md +++ b/dns/dnspromises_resolve4_hostname_options.md @@ -1,9 +1,10 @@ + * `hostname` {string} Hostname to resolve. * `options` {Object} - - `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. + * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. When `true`, the `Promise` is resolved with an array of `{ address: '1.2.3.4', ttl: 60 }` objects rather than an array of strings, with the TTL expressed in seconds. diff --git a/dns/dnspromises_resolve6_hostname_options.md b/dns/dnspromises_resolve6_hostname_options.md index 6563c55c..cce087b9 100644 --- a/dns/dnspromises_resolve6_hostname_options.md +++ b/dns/dnspromises_resolve6_hostname_options.md @@ -1,9 +1,10 @@ + * `hostname` {string} Hostname to resolve. * `options` {Object} - - `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. + * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. When `true`, the `Promise` is resolved with an array of `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }` objects rather than an array of strings, with the TTL expressed in seconds. diff --git a/dns/dnspromises_resolve_hostname_rrtype.md b/dns/dnspromises_resolve_hostname_rrtype.md index 8cad5af3..1db3c4a8 100644 --- a/dns/dnspromises_resolve_hostname_rrtype.md +++ b/dns/dnspromises_resolve_hostname_rrtype.md @@ -1,6 +1,7 @@ + * `hostname` {string} Hostname to resolve. * `rrtype` {string} Resource record type. **Default:** `'A'`. diff --git a/dns/dnspromises_resolveany_hostname.md b/dns/dnspromises_resolveany_hostname.md index 5a6550f1..cf73c718 100644 --- a/dns/dnspromises_resolveany_hostname.md +++ b/dns/dnspromises_resolveany_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query). diff --git a/dns/dnspromises_resolvecname_hostname.md b/dns/dnspromises_resolvecname_hostname.md index c354d2b2..b87a008c 100644 --- a/dns/dnspromises_resolvecname_hostname.md +++ b/dns/dnspromises_resolvecname_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve `CNAME` records for the `hostname`. On success, diff --git a/dns/dnspromises_resolvemx_hostname.md b/dns/dnspromises_resolvemx_hostname.md index 51bbd2e8..778f39da 100644 --- a/dns/dnspromises_resolvemx_hostname.md +++ b/dns/dnspromises_resolvemx_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve mail exchange records (`MX` records) for the diff --git a/dns/dnspromises_resolvenaptr_hostname.md b/dns/dnspromises_resolvenaptr_hostname.md index ad188f6e..26962cc9 100644 --- a/dns/dnspromises_resolvenaptr_hostname.md +++ b/dns/dnspromises_resolvenaptr_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve regular expression based records (`NAPTR` diff --git a/dns/dnspromises_resolvens_hostname.md b/dns/dnspromises_resolvens_hostname.md index 8ad63d66..c90defc9 100644 --- a/dns/dnspromises_resolvens_hostname.md +++ b/dns/dnspromises_resolvens_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve name server records (`NS` records) for the diff --git a/dns/dnspromises_resolveptr_hostname.md b/dns/dnspromises_resolveptr_hostname.md index 0b498660..bb133eda 100644 --- a/dns/dnspromises_resolveptr_hostname.md +++ b/dns/dnspromises_resolveptr_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve pointer records (`PTR` records) for the diff --git a/dns/dnspromises_resolvesoa_hostname.md b/dns/dnspromises_resolvesoa_hostname.md index b87d1c98..02b5ca59 100644 --- a/dns/dnspromises_resolvesoa_hostname.md +++ b/dns/dnspromises_resolvesoa_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve a start of authority record (`SOA` record) for diff --git a/dns/dnspromises_resolvesrv_hostname.md b/dns/dnspromises_resolvesrv_hostname.md index 864d2450..4984d883 100644 --- a/dns/dnspromises_resolvesrv_hostname.md +++ b/dns/dnspromises_resolvesrv_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve service records (`SRV` records) for the diff --git a/dns/dnspromises_resolvetxt_hostname.md b/dns/dnspromises_resolvetxt_hostname.md index e69e5499..85260514 100644 --- a/dns/dnspromises_resolvetxt_hostname.md +++ b/dns/dnspromises_resolvetxt_hostname.md @@ -1,6 +1,7 @@ + * `hostname` {string} Uses the DNS protocol to resolve text queries (`TXT` records) for the diff --git a/dns/dnspromises_reverse_ip.md b/dns/dnspromises_reverse_ip.md index b3b6c08d..af704434 100644 --- a/dns/dnspromises_reverse_ip.md +++ b/dns/dnspromises_reverse_ip.md @@ -1,6 +1,7 @@ + * `ip` {string} Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an diff --git a/dns/dnspromises_setservers_servers.md b/dns/dnspromises_setservers_servers.md index 208bab67..b6675a45 100644 --- a/dns/dnspromises_setservers_servers.md +++ b/dns/dnspromises_setservers_servers.md @@ -1,6 +1,7 @@ + * `servers` {string[]} array of [RFC 5952][] formatted addresses Sets the IP address and port of servers to be used when performing DNS diff --git a/errors/err_inspector_not_connected.md b/errors/err_inspector_not_connected.md index 7186cf4a..d11c9da8 100644 --- a/errors/err_inspector_not_connected.md +++ b/errors/err_inspector_not_connected.md @@ -2,4 +2,4 @@ While using the `inspector` module, an attempt was made to use the inspector before it was connected. - + diff --git a/errors/err_inspector_not_worker.md b/errors/err_inspector_not_worker.md new file mode 100644 index 00000000..ee368102 --- /dev/null +++ b/errors/err_inspector_not_worker.md @@ -0,0 +1,5 @@ + +An API was called on the main thread that can only be used from +the worker thread. + + diff --git a/errors/err_vm_module_already_linked.md b/errors/err_vm_module_already_linked.md index c56024d9..82da7e9a 100644 --- a/errors/err_vm_module_already_linked.md +++ b/errors/err_vm_module_already_linked.md @@ -2,8 +2,8 @@ The module attempted to be linked is not eligible for linking, because of one of the following reasons: -- It has already been linked (`linkingStatus` is `'linked'`) -- It is being linked (`linkingStatus` is `'linking'`) -- Linking has failed for this module (`linkingStatus` is `'errored'`) +* It has already been linked (`linkingStatus` is `'linked'`) +* It is being linked (`linkingStatus` is `'linking'`) +* Linking has failed for this module (`linkingStatus` is `'errored'`) diff --git a/esm/code_package_json_code_code_type_code_field.md b/esm/code_package_json_code_code_type_code_field.md index ab3b8b1d..1404c758 100644 --- a/esm/code_package_json_code_code_type_code_field.md +++ b/esm/code_package_json_code_code_type_code_field.md @@ -34,3 +34,9 @@ if the nearest parent `package.json` contains `"type": "module"`. import './startup.js'; // Loaded as ES module because of package.json ``` +Package authors should include the `"type"` field, even in packages where all +sources are CommonJS. Being explicit about the `type` of the package will +future-proof the package in case the default type of Node.js ever changes, and +it will also make things easier for build tools and loaders to determine how the +files in the package should be interpreted. + diff --git a/esm/compatibility_with_commonjs_only_versions_of_node_js.md b/esm/compatibility_with_commonjs_only_versions_of_node_js.md new file mode 100644 index 00000000..c5f13c5d --- /dev/null +++ b/esm/compatibility_with_commonjs_only_versions_of_node_js.md @@ -0,0 +1,40 @@ + +Prior to the introduction of support for ES modules in Node.js, it was a common +pattern for package authors to include both CommonJS and ES module JavaScript +sources in their package, with `package.json` `"main"` specifying the CommonJS +entry point and `package.json` `"module"` specifying the ES module entry point. +This enabled Node.js to run the CommonJS entry point while build tools such as +bundlers used the ES module entry point, since Node.js ignored (and still +ignores) `"module"`. + +Node.js can now run ES module entry points, but it remains impossible for a +package to define separate CommonJS and ES module entry points. This is for good +reason: the `pkg` variable created from `import pkg from 'pkg'` is not the same +singleton as the `pkg` variable created from `const pkg = require('pkg')`, so if +both are referenced within the same app (including dependencies), unexpected +behavior might occur. + +There are two general approaches to addressing this limitation while still +publishing a package that contains both CommonJS and ES module sources: + +1. Document a new ES module entry point that’s not the package `"main"`, e.g. + `import pkg from 'pkg/module.mjs'` (or `import 'pkg/esm'`, if using [package + exports][]). The package `"main"` would still point to a CommonJS file, and + thus the package would remain compatible with older versions of Node.js that + lack support for ES modules. + +1. Switch the package `"main"` entry point to an ES module file as part of a + breaking change version bump. This version and above would only be usable on + ES module-supporting versions of Node.js. If the package still contains a + CommonJS version, it would be accessible via a path within the package, e.g. + `require('pkg/commonjs')`; this is essentially the inverse of the previous + approach. Package consumers who are using CommonJS-only versions of Node.js + would need to update their code from `require('pkg')` to e.g. + `require('pkg/commonjs')`. + +Of course, a package could also include only CommonJS or only ES module sources. +An existing package could make a semver major bump to an ES module-only version, +that would only be supported in ES module-supporting versions of Node.js (and +other runtimes). New packages could be published containing only ES module +sources, and would be compatible only with ES module-supporting runtimes. + diff --git a/esm/customizing_esm_specifier_resolution_algorithm.md b/esm/customizing_esm_specifier_resolution_algorithm.md index af60efb2..b25daa19 100644 --- a/esm/customizing_esm_specifier_resolution_algorithm.md +++ b/esm/customizing_esm_specifier_resolution_algorithm.md @@ -34,3 +34,4 @@ success! + diff --git a/esm/enabling.md b/esm/enabling.md index 1175f71a..f003e5f4 100644 --- a/esm/enabling.md +++ b/esm/enabling.md @@ -8,13 +8,13 @@ Once enabled, Node.js will treat the following as ES modules when passed to `node` as the initial input, or when referenced by `import` statements within ES module code: -- Files ending in `.mjs`. +* Files ending in `.mjs`. -- Files ending in `.js`, or extensionless files, when the nearest parent +* Files ending in `.js`, or extensionless files, when the nearest parent `package.json` file contains a top-level field `"type"` with a value of `"module"`. -- Strings passed in as an argument to `--eval` or `--print`, or piped to +* Strings passed in as an argument to `--eval` or `--print`, or piped to `node` via `STDIN`, with the flag `--input-type=module`. Node.js will treat as CommonJS all other forms of input, such as `.js` files @@ -25,12 +25,12 @@ CommonJS and ES modules, it is best to be explicit whenever possible. Node.js will treat the following as CommonJS when passed to `node` as the initial input, or when referenced by `import` statements within ES module code: -- Files ending in `.cjs`. +* Files ending in `.cjs`. -- Files ending in `.js`, or extensionless files, when the nearest parent +* Files ending in `.js`, or extensionless files, when the nearest parent `package.json` file contains a top-level field `"type"` with a value of `"commonjs"`. -- Strings passed in as an argument to `--eval` or `--print`, or piped to +* Strings passed in as an argument to `--eval` or `--print`, or piped to `node` via `STDIN`, with the flag `--input-type=commonjs`. diff --git a/esm/package_entry_points.md b/esm/package_entry_points.md index 0d62a1d1..4587284b 100644 --- a/esm/package_entry_points.md +++ b/esm/package_entry_points.md @@ -32,11 +32,5 @@ be interpreted as CommonJS. The `"main"` field can point to exactly one file, regardless of whether the package is referenced via `require` (in a CommonJS context) or `import` (in an -ES module context). Package authors who want to publish a package to be used in -both contexts can do so by setting `"main"` to point to the CommonJS entry point -and informing the package’s users of the path to the ES module entry point. Such -a package would be accessible like `require('pkg')` and `import -'pkg/module.mjs'`. Alternatively the package `"main"` could point to the ES -module entry point and legacy users could be informed of the CommonJS entry -point path, e.g. `require('pkg/commonjs')`. +ES module context). diff --git a/esm/package_exports.md b/esm/package_exports.md index 97c99ccd..c53804a0 100644 --- a/esm/package_exports.md +++ b/esm/package_exports.md @@ -50,6 +50,33 @@ If a package has no exports, setting `"exports": false` can be used instead of `"exports": {}` to indicate the package does not intend for submodules to be exposed. +Exports can also be used to map the main entry point of a package: + + +```js +// ./node_modules/es-module-package/package.json +{ + "exports": { + ".": "./main.js" + } +} +``` + +where the "." indicates loading the package without any subpath. Exports will +always override any existing `"main"` value for both CommonJS and +ES module packages. + +For packages with only a main entry point, an `"exports"` value of just +a string is also supported: + + +```js +// ./node_modules/es-module-package/package.json +{ + "exports": "./main.js" +} +``` + Any invalid exports entries will be ignored. This includes exports not starting with `"./"` or a missing trailing `"/"` for directory exports. diff --git a/esm/package_scope_and_file_extensions.md b/esm/package_scope_and_file_extensions.md index 89d3b11b..f2a91c3f 100644 --- a/esm/package_scope_and_file_extensions.md +++ b/esm/package_scope_and_file_extensions.md @@ -46,12 +46,12 @@ import 'commonjs-package/src/index.mjs'; The `.mjs` and `.cjs` extensions may be used to mix types within the same package scope: -- Within a `"type": "module"` package scope, Node.js can be instructed to +* Within a `"type": "module"` package scope, Node.js can be instructed to interpret a particular file as CommonJS by naming it with a `.cjs` extension (since both `.js` and `.mjs` files are treated as ES modules within a `"module"` package scope). -- Within a `"type": "commonjs"` package scope, Node.js can be instructed to +* Within a `"type": "commonjs"` package scope, Node.js can be instructed to interpret a particular file as an ES module by naming it with an `.mjs` extension (since both `.js` and `.cjs` files are treated as CommonJS within a `"commonjs"` package scope). diff --git a/esm/packages.md b/esm/packages.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/esm/packages.md @@ -0,0 +1 @@ + diff --git a/esm/resolve_hook.md b/esm/resolve_hook.md index 1cf4eb1c..61bf0a4a 100644 --- a/esm/resolve_hook.md +++ b/esm/resolve_hook.md @@ -3,8 +3,14 @@ The resolve hook returns the resolved file URL and module format for a given module specifier and parent file URL: ```js -const baseURL = new URL(`${process.cwd()}/`, 'file://'); - +import { URL, pathToFileURL } from 'url'; +const baseURL = pathToFileURL(process.cwd()).href; + +/** + * @param {string} specifier + * @param {string} parentModuleURL + * @param {function} defaultResolver + */ export async function resolve(specifier, parentModuleURL = baseURL, defaultResolver) { @@ -42,13 +48,21 @@ be written: import path from 'path'; import process from 'process'; import Module from 'module'; +import { URL, pathToFileURL } from 'url'; const builtins = Module.builtinModules; const JS_EXTENSIONS = new Set(['.js', '.mjs']); -const baseURL = new URL(`${process.cwd()}/`, 'file://'); +const baseURL = pathToFileURL(process.cwd()).href; -export function resolve(specifier, parentModuleURL = baseURL, defaultResolve) { +/** + * @param {string} specifier + * @param {string} parentModuleURL + * @param {function} defaultResolver + */ +export async function resolve(specifier, + parentModuleURL = baseURL, + defaultResolver) { if (builtins.includes(specifier)) { return { url: specifier, @@ -57,7 +71,7 @@ export function resolve(specifier, parentModuleURL = baseURL, defaultResolve) { } if (/^\.{0,2}[/]/.test(specifier) !== true && !specifier.startsWith('file:')) { // For node_modules support: - // return defaultResolve(specifier, parentModuleURL); + // return defaultResolver(specifier, parentModuleURL); throw new Error( `imports must begin with '/', './', or '../'; '${specifier}' does not`); } diff --git a/esm/resolver_algorithm.md b/esm/resolver_algorithm.md index 89582766..91fc67b6 100644 --- a/esm/resolver_algorithm.md +++ b/esm/resolver_algorithm.md @@ -18,6 +18,7 @@ _isMain_ is **true** when resolving the Node.js application entry point. Resolver algorithm specification **ESM_RESOLVE**(_specifier_, _parentURL_, _isMain_) + > 1. Let _resolvedURL_ be **undefined**. > 1. If _specifier_ is a valid URL, then > 1. Set _resolvedURL_ to the result of parsing and reserializing @@ -41,6 +42,7 @@ _isMain_ is **true** when resolving the Node.js application entry point. > 1. Load _resolvedURL_ as module format, _format_. **PACKAGE_RESOLVE**(_packageSpecifier_, _parentURL_) + > 1. Let _packageName_ be *undefined*. > 1. Let _packageSubpath_ be *undefined*. > 1. If _packageSpecifier_ is an empty string, then @@ -87,8 +89,18 @@ _isMain_ is **true** when resolving the Node.js application entry point. > 1. Throw a _Module Not Found_ error. **PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_) + > 1. If _pjson_ is **null**, then > 1. Throw a _Module Not Found_ error. +> 1. If _pjson.exports_ is not **null** or **undefined**, then +> 1. If _pjson.exports_ is a String or Array, then +> 1. Return _PACKAGE_EXPORTS_TARGET_RESOLVE(packageURL, pjson.exports, +> "")_. +> 1. If _pjson.exports is an Object, then +> 1. If _pjson.exports_ contains a _"."_ property, then +> 1. Let _mainExport_ be the _"."_ property in _pjson.exports_. +> 1. Return _PACKAGE_EXPORTS_TARGET_RESOLVE(packageURL, mainExport, +> "")_. > 1. If _pjson.main_ is a String, then > 1. Let _resolvedMain_ be the URL resolution of _packageURL_, "/", and > _pjson.main_. @@ -102,6 +114,7 @@ _isMain_ is **true** when resolving the Node.js application entry point. > 1. Return _legacyMainURL_. **PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _packagePath_, _exports_) + > 1. If _exports_ is an Object, then > 1. Set _packagePath_ to _"./"_ concatenated with _packagePath_. > 1. If _packagePath_ is a key of _exports_, then @@ -120,6 +133,7 @@ _isMain_ is **true** when resolving the Node.js application entry point. > 1. Throw a _Module Not Found_ error. **PACKAGE_EXPORTS_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_) + > 1. If _target_ is a String, then > 1. If _target_ does not start with _"./"_, throw a _Module Not Found_ > error. @@ -145,6 +159,7 @@ _isMain_ is **true** when resolving the Node.js application entry point. > 1. Throw a _Module Not Found_ error. **ESM_FORMAT**(_url_, _isMain_) + > 1. Assert: _url_ corresponds to an existing file. > 1. Let _pjson_ be the result of **READ_PACKAGE_SCOPE**(_url_). > 1. If _url_ ends in _".mjs"_, then @@ -162,6 +177,7 @@ _isMain_ is **true** when resolving the Node.js application entry point. > 1. Throw an _Unsupported File Extension_ error. **READ_PACKAGE_SCOPE**(_url_) + > 1. Let _scopeURL_ be _url_. > 1. While _scopeURL_ is not the file system root, > 1. If _scopeURL_ ends in a _"node_modules"_ path segment, return **null**. @@ -172,6 +188,7 @@ _isMain_ is **true** when resolving the Node.js application entry point. > 1. Return **null**. **READ_PACKAGE_JSON**(_packageURL_) + > 1. Let _pjsonURL_ be the resolution of _"package.json"_ within _packageURL_. > 1. If the file at _pjsonURL_ does not exist, then > 1. Return **null**. diff --git a/esm/terminology.md b/esm/terminology.md index 0963a5f9..3f08b501 100644 --- a/esm/terminology.md +++ b/esm/terminology.md @@ -5,16 +5,16 @@ e.g. `'path'` in `import { sep } from 'path'`. Specifiers are also used in There are four types of specifiers: -- _Bare specifiers_ like `'some-package'`. They refer to an entry point of a +* _Bare specifiers_ like `'some-package'`. They refer to an entry point of a package by the package name. -- _Deep import specifiers_ like `'some-package/lib/shuffle.mjs'`. They refer to +* _Deep import specifiers_ like `'some-package/lib/shuffle.mjs'`. They refer to a path within a package prefixed by the package name. -- _Relative specifiers_ like `'./startup.js'` or `'../config.mjs'`. They refer +* _Relative specifiers_ like `'./startup.js'` or `'../config.mjs'`. They refer to a path relative to the location of the importing file. -- _Absolute specifiers_ like `'file:///opt/nodejs/config.js'`. They refer +* _Absolute specifiers_ like `'file:///opt/nodejs/config.js'`. They refer directly and explicitly to a full path. Bare specifiers, and the bare specifier portion of deep import specifiers, are diff --git a/events/eventemitter_listenercount_emitter_eventname.md b/events/eventemitter_listenercount_emitter_eventname.md index c29d389c..3d926d4c 100644 --- a/events/eventemitter_listenercount_emitter_eventname.md +++ b/events/eventemitter_listenercount_emitter_eventname.md @@ -2,6 +2,7 @@ added: v0.9.12 deprecated: v4.0.0 --> + * `emitter` {EventEmitter} The emitter to query * `eventName` {string|symbol} The event name diff --git a/events/events_once_emitter_name.md b/events/events_once_emitter_name.md index c3d8df92..d7a9a418 100644 --- a/events/events_once_emitter_name.md +++ b/events/events_once_emitter_name.md @@ -1,6 +1,7 @@ + * `emitter` {EventEmitter} * `name` {string} * 返回: {Promise} @@ -8,6 +9,8 @@ added: v11.13.0 创建一个 `Promise`，当 `EventEmitter` 触发给定的事件时则会被解决，当 `EventEmitter` 触发 `'error'` 时则会被拒绝。 解决 `Promise` 时将会带上触发到给定事件的所有参数的数组。 +此方法是有意通用的，并且可与 Web 平台的 [EventTarget][WHATWG-EventTarget] 接口一起使用，该接口没有特殊的 `'error'` 事件语义且不监听 `'error'` 事件。 + ```js const { once, EventEmitter } = require('events'); @@ -21,7 +24,7 @@ async function run() { const [value] = await once(ee, 'myevent'); console.log(value); - const err = new Error('kaboom'); + const err = new Error('错误信息'); process.nextTick(() => { ee.emit('error', err); }); diff --git a/fs/file_open_constants.md b/fs/file_open_constants.md index 669049ce..a6008010 100644 --- a/fs/file_open_constants.md +++ b/fs/file_open_constants.md @@ -28,7 +28,7 @@ O_NOCTTY - 表明如果路径是终端设备，则打开该路径不应该造成该终端变成进程的控制终端（如果进程还没有终端）。 + 表明如果路径表示终端设备，则打开该路径不应该造成该终端变成进程的控制终端（如果进程还没有终端）。 O_TRUNC @@ -36,7 +36,7 @@ O_APPEND - 表明数据将追加到文件末尾。 + 表明数据将会追加到文件的末尾。 O_DIRECTORY @@ -53,11 +53,11 @@ O_SYNC - 表明文件是为同步 I/O 打开的，写入操作将等待文件的完整性。 + 表明文件是为同步 I/O 打开的，写入操作将会等待文件的完整性。 O_DSYNC - 表明文件是为同步 I/O 打开的，写入操作将等待数据的完整性 + 表明文件是为同步 I/O 打开的，写入操作将会等待数据的完整性 O_SYMLINK @@ -71,5 +71,11 @@ O_NONBLOCK 表明在可能的情况下以非阻塞模式打开文件。 + + UV_FS_O_FILEMAP + 当设置后，将会使用内存文件的映射来访问文件。 + 此标志仅在 Windows 操作系统上可用。 + 在其他操作系统上，此标志会被忽略。 + diff --git a/fs/file_system.md b/fs/file_system.md index 53c718a7..dc67a62e 100644 --- a/fs/file_system.md +++ b/fs/file_system.md @@ -77,7 +77,7 @@ fs.rename('/tmp/hello', '/tmp/world', (err) => { 不推荐在异步的 fs 函数上省略回调函数，因为可能导致将来抛出错误。 -```txt +```console $ cat script.js function bad() { require('fs').readFile('/'); diff --git a/http/message_url.md b/http/message_url.md index 11cd60ee..36621987 100644 --- a/http/message_url.md +++ b/http/message_url.md @@ -45,7 +45,7 @@ Url { 要从查询字符串中提取参数，可以使用 `require('querystring').parse` 函数，或者可以将 `true` 作为第二个参数传递给 `require('url').parse`： -```txt +```console $ node > require('url').parse('/status?name=ryan', true) Url { diff --git a/http2/headers_object.md b/http2/headers_object.md index cbd8ae6c..8760f52c 100644 --- a/http2/headers_object.md +++ b/http2/headers_object.md @@ -20,17 +20,18 @@ means that normal JavaScript object methods such as not work. For incoming headers: + * The `:status` header is converted to `number`. * Duplicates of `:status`, `:method`, `:authority`, `:scheme`, `:path`, -`:protocol`, `age`, `authorization`, `access-control-allow-credentials`, -`access-control-max-age`, `access-control-request-method`, `content-encoding`, -`content-language`, `content-length`, `content-location`, `content-md5`, -`content-range`, `content-type`, `date`, `dnt`, `etag`, `expires`, `from`, -`if-match`, `if-modified-since`, `if-none-match`, `if-range`, -`if-unmodified-since`, `last-modified`, `location`, `max-forwards`, -`proxy-authorization`, `range`, `referer`,`retry-after`, `tk`, -`upgrade-insecure-requests`, `user-agent` or `x-content-type-options` are -discarded. + `:protocol`, `age`, `authorization`, `access-control-allow-credentials`, + `access-control-max-age`, `access-control-request-method`, `content-encoding`, + `content-language`, `content-length`, `content-location`, `content-md5`, + `content-range`, `content-type`, `date`, `dnt`, `etag`, `expires`, `from`, + `if-match`, `if-modified-since`, `if-none-match`, `if-range`, + `if-unmodified-since`, `last-modified`, `location`, `max-forwards`, + `proxy-authorization`, `range`, `referer`,`retry-after`, `tk`, + `upgrade-insecure-requests`, `user-agent` or `x-content-type-options` are + discarded. * `set-cookie` is always an array. Duplicates are added to the array. * For duplicate `cookie` headers, the values are joined together with '; '. * For all other headers, the values are joined together with ', '. diff --git a/http2/http2_connect_authority_options_listener.md b/http2/http2_connect_authority_options_listener.md index ff3e08b5..056f5f78 100644 --- a/http2/http2_connect_authority_options_listener.md +++ b/http2/http2_connect_authority_options_listener.md @@ -39,23 +39,23 @@ changes: exceed this limit will result in a `'frameError'` event being emitted and the stream being closed and destroyed. * `paddingStrategy` {number} Identifies the strategy used for determining the - amount of padding to use for `HEADERS` and `DATA` frames. **Default:** - `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: - * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is - to be applied. - * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum - amount of padding, as determined by the internal implementation, is to - be applied. - * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user - provided `options.selectPadding()` callback is to be used to determine - the amount of padding. - * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply - enough padding to ensure that the total frame length, including the - 9-byte header, is a multiple of 8. For each frame, however, there is a - maximum allowed number of padding bytes that is determined by current - flow control state and settings. If this maximum is less than the - calculated amount needed to ensure alignment, the maximum will be used - and the total frame length will *not* necessarily be aligned at 8 bytes. + amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: + * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is + to be applied. + * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum + amount of padding, as determined by the internal implementation, is to + be applied. + * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. + * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply + enough padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, however, there is a + maximum allowed number of padding bytes that is determined by current + flow control state and settings. If this maximum is less than the + calculated amount needed to ensure alignment, the maximum will be used + and the total frame length will *not* necessarily be aligned at 8 bytes. * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a `SETTINGS` frame had been received. Will be overridden if the remote peer sets its own value for diff --git a/http2/http2_createsecureserver_options_onrequesthandler.md b/http2/http2_createsecureserver_options_onrequesthandler.md index 8a82d045..9cd01916 100644 --- a/http2/http2_createsecureserver_options_onrequesthandler.md +++ b/http2/http2_createsecureserver_options_onrequesthandler.md @@ -40,23 +40,23 @@ changes: exceed this limit will result in a `'frameError'` event being emitted and the stream being closed and destroyed. * `paddingStrategy` {number} Identifies the strategy used for determining the - amount of padding to use for `HEADERS` and `DATA` frames. **Default:** - `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: - * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is - to be applied. - * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum - amount of padding, as determined by the internal implementation, is to - be applied. - * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user - provided `options.selectPadding()` callback is to be used to determine - the amount of padding. - * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply - enough padding to ensure that the total frame length, including the - 9-byte header, is a multiple of 8. For each frame, however, there is a - maximum allowed number of padding bytes that is determined by current - flow control state and settings. If this maximum is less than the - calculated amount needed to ensure alignment, the maximum will be used - and the total frame length will *not* necessarily be aligned at 8 bytes. + amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: + * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is + to be applied. + * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum + amount of padding, as determined by the internal implementation, is to + be applied. + * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. + * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply + enough padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, however, there is a + maximum allowed number of padding bytes that is determined by current + flow control state and settings. If this maximum is less than the + calculated amount needed to ensure alignment, the maximum will be used + and the total frame length will *not* necessarily be aligned at 8 bytes. * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a `SETTINGS` frame had been received. Will be overridden if the remote peer sets its own value for diff --git a/http2/http2_createserver_options_onrequesthandler.md b/http2/http2_createserver_options_onrequesthandler.md index 04b8a72f..d04af0d8 100644 --- a/http2/http2_createserver_options_onrequesthandler.md +++ b/http2/http2_createserver_options_onrequesthandler.md @@ -40,23 +40,23 @@ changes: exceed this limit will result in a `'frameError'` event being emitted and the stream being closed and destroyed. * `paddingStrategy` {number} Identifies the strategy used for determining the - amount of padding to use for `HEADERS` and `DATA` frames. **Default:** - `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: - * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is - to be applied. - * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum - amount of padding, as determined by the internal implementation, is to - be applied. - * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user - provided `options.selectPadding()` callback is to be used to determine - the amount of padding. - * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply - enough padding to ensure that the total frame length, including the - 9-byte header, is a multiple of 8. For each frame, however, there is a - maximum allowed number of padding bytes that is determined by current - flow control state and settings. If this maximum is less than the - calculated amount needed to ensure alignment, the maximum will be used - and the total frame length will *not* necessarily be aligned at 8 bytes. + amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: + * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is + to be applied. + * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum + amount of padding, as determined by the internal implementation, is to + be applied. + * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. + * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply + enough padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, however, there is a + maximum allowed number of padding bytes that is determined by current + flow control state and settings. If this maximum is less than the + calculated amount needed to ensure alignment, the maximum will be used + and the total frame length will *not* necessarily be aligned at 8 bytes. * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent streams for the remote peer as if a `SETTINGS` frame had been received. Will be overridden if the remote peer sets its own value for diff --git a/http2/http2stream_buffersize.md b/http2/http2stream_buffersize.md index b0ff93d5..b6b89df1 100644 --- a/http2/http2stream_buffersize.md +++ b/http2/http2stream_buffersize.md @@ -1,6 +1,7 @@ + * {number} This property shows the number of characters currently buffered to be written. diff --git a/http2/request_complete.md b/http2/request_complete.md new file mode 100644 index 00000000..9776915a --- /dev/null +++ b/http2/request_complete.md @@ -0,0 +1,9 @@ + + +* {boolean} + +The `request.complete` property will be `true` if the request has +been completed, aborted, or destroyed. + diff --git a/http2/request_url.md b/http2/request_url.md index 5e5b1c65..f4d1ada7 100644 --- a/http2/request_url.md +++ b/http2/request_url.md @@ -45,7 +45,7 @@ To extract the parameters from the query string, the `require('querystring').parse` function can be used, or `true` can be passed as the second argument to `require('url').parse`. -```txt +```console $ node > require('url').parse('/status?name=ryan', true) Url { diff --git a/http2/response_createpushresponse_headers_callback.md b/http2/response_createpushresponse_headers_callback.md index 7d643dd2..a1e7bf15 100644 --- a/http2/response_createpushresponse_headers_callback.md +++ b/http2/response_createpushresponse_headers_callback.md @@ -1,6 +1,7 @@ + * `headers` {HTTP/2 Headers Object} An object describing the headers * `callback` {Function} Called once `http2stream.pushStream()` is finished, or either when the attempt to create the pushed `Http2Stream` has failed or diff --git a/http2/server_close_callback.md b/http2/server_close_callback.md index 458bc589..f8240de4 100644 --- a/http2/server_close_callback.md +++ b/http2/server_close_callback.md @@ -1,6 +1,7 @@ + * `callback` {Function} Stops the server from establishing new sessions. This does not prevent new diff --git a/http2/server_close_callback_1.md b/http2/server_close_callback_1.md index 6697c1f8..19405b43 100644 --- a/http2/server_close_callback_1.md +++ b/http2/server_close_callback_1.md @@ -1,6 +1,7 @@ + * `callback` {Function} Stops the server from establishing new sessions. This does not prevent new diff --git a/inspector/session_connect.md b/inspector/session_connect.md index c6cb1d49..d0799810 100644 --- a/inspector/session_connect.md +++ b/inspector/session_connect.md @@ -2,7 +2,5 @@ added: v8.0.0 --> -Connects a session to the inspector back-end. An exception will be thrown -if there is already a connected session established either through the API or by -a front-end connected to the Inspector WebSocket port. +Connects a session to the inspector back-end. diff --git a/inspector/session_connecttomainthread.md b/inspector/session_connecttomainthread.md new file mode 100644 index 00000000..3be08b37 --- /dev/null +++ b/inspector/session_connecttomainthread.md @@ -0,0 +1,7 @@ + + +Connects a session to the main thread inspector back-end. An exception will +be thrown if this API was not called on a Worker thread. + diff --git a/intl/detecting_internationalization_support.md b/intl/detecting_internationalization_support.md index e3183c51..d66c3eae 100644 --- a/intl/detecting_internationalization_support.md +++ b/intl/detecting_internationalization_support.md @@ -31,9 +31,9 @@ const hasFullICU = (() => { For more verbose tests for `Intl` support, the following resources may be found to be helpful: -- [btest402][]: Generally used to check whether Node.js with `Intl` support is +* [btest402][]: Generally used to check whether Node.js with `Intl` support is built correctly. -- [Test262][]: ECMAScript's official conformance test suite includes a section +* [Test262][]: ECMAScript's official conformance test suite includes a section dedicated to ECMA-402. diff --git a/intl/internationalization_support.md b/intl/internationalization_support.md index 471d7d86..edf669b0 100644 --- a/intl/internationalization_support.md +++ b/intl/internationalization_support.md @@ -5,21 +5,21 @@ Node.js has many features that make it easier to write internationalized programs. Some of them are: -- Locale-sensitive or Unicode-aware functions in the [ECMAScript Language +* Locale-sensitive or Unicode-aware functions in the [ECMAScript Language Specification][ECMA-262]: - - [`String.prototype.normalize()`][] - - [`String.prototype.toLowerCase()`][] - - [`String.prototype.toUpperCase()`][] -- All functionality described in the [ECMAScript Internationalization API + * [`String.prototype.normalize()`][] + * [`String.prototype.toLowerCase()`][] + * [`String.prototype.toUpperCase()`][] +* All functionality described in the [ECMAScript Internationalization API Specification][ECMA-402] (aka ECMA-402): - - [`Intl`][] object - - Locale-sensitive methods like [`String.prototype.localeCompare()`][] and + * [`Intl`][] object + * Locale-sensitive methods like [`String.prototype.localeCompare()`][] and [`Date.prototype.toLocaleString()`][] -- The [WHATWG URL parser][]'s [internationalized domain names][] (IDNs) support -- [`require('buffer').transcode()`][] -- More accurate [REPL][] line editing -- [`require('util').TextDecoder`][] -- [`RegExp` Unicode Property Escapes][] +* The [WHATWG URL parser][]'s [internationalized domain names][] (IDNs) support +* [`require('buffer').transcode()`][] +* More accurate [REPL][] line editing +* [`require('util').TextDecoder`][] +* [`RegExp` Unicode Property Escapes][] Node.js (and its underlying V8 engine) uses [ICU][] to implement these features in native C/C++ code. However, some of them require a very large ICU data file diff --git a/intl/options_for_building_node_js.md b/intl/options_for_building_node_js.md index dfb9f26f..d946220f 100644 --- a/intl/options_for_building_node_js.md +++ b/intl/options_for_building_node_js.md @@ -3,10 +3,10 @@ To control how ICU is used in Node.js, four `configure` options are available during compilation. Additional details on how to compile Node.js are documented in [BUILDING.md][]. -- `--with-intl=none`/`--without-intl` -- `--with-intl=system-icu` -- `--with-intl=small-icu` (default) -- `--with-intl=full-icu` +* `--with-intl=none`/`--without-intl` +* `--with-intl=system-icu` +* `--with-intl=small-icu` (default) +* `--with-intl=full-icu` An overview of available Node.js and JavaScript features for each `configure` option: diff --git a/modules/cycles.md b/modules/cycles.md index 85f01cf5..69282055 100644 --- a/modules/cycles.md +++ b/modules/cycles.md @@ -44,7 +44,7 @@ console.log('在 main 中，a.done=%j，b.done=%j', a.done, b.done); 当 `main.js` 加载这两个模块时，它们都已经完成加载。 因此，该程序的输出会是： -```txt +```console $ node main.js main 开始 a 开始 diff --git a/n-api/implications_of_abi_stability.md b/n-api/implications_of_abi_stability.md index b5bc0477..52c28ba5 100644 --- a/n-api/implications_of_abi_stability.md +++ b/n-api/implications_of_abi_stability.md @@ -3,6 +3,7 @@ Although N-API provides an ABI stability guarantee, other parts of Node.js do not, and any external libraries used from the addon may not. In particular, none of the following APIs provide an ABI stability guarantee across major versions: + * the Node.js C++ APIs available via any of ```C++ diff --git a/n-api/n_api.md b/n-api/n_api.md index 326533a3..4c54d349 100644 --- a/n-api/n_api.md +++ b/n-api/n_api.md @@ -23,12 +23,13 @@ APIs exposed by N-API are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA-262 Language Specification. The APIs have the following properties: -- All N-API calls return a status code of type `napi_status`. This + +* All N-API calls return a status code of type `napi_status`. This status indicates whether the API call succeeded or failed. -- The API's return value is passed via an out parameter. -- All JavaScript values are abstracted behind an opaque type named +* The API's return value is passed via an out parameter. +* All JavaScript values are abstracted behind an opaque type named `napi_value`. -- In case of an error status code, additional information can be obtained +* In case of an error status code, additional information can be obtained using `napi_get_last_error_info`. More information can be found in the error handling section [Error Handling][]. diff --git a/n-api/n_api_version_matrix.md b/n-api/n_api_version_matrix.md index 37605ea5..bd275892 100644 --- a/n-api/n_api_version_matrix.md +++ b/n-api/n_api_version_matrix.md @@ -5,14 +5,15 @@ from version 3 with some additions. This means that it is not necessary to recompile for new versions of Node.js which are listed as supporting a later version. -| | 1 | 2 | 3 | 4 | -|:-----:|:-------:|:--------:|:--------:|:--------:| -| v6.x | | | v6.14.2* | | -| v8.x | v8.0.0* | v8.10.0* | v8.11.2 | v8.16.0 | -| v9.x | v9.0.0* | v9.3.0* | v9.11.0* | | -| v10.x | | | v10.0.0 | | -| v11.x | | | v11.0.0 | v11.8.0 | -| v12.x | | | | v12.0.0 | +| | 1 | 2 | 3 | 4 | 5 | +|:-----:|:-------:|:--------:|:--------:|:--------:|:---------:| +| v6.x | | | v6.14.2* | | | +| v8.x | v8.0.0* | v8.10.0* | v8.11.2 | v8.16.0 | | +| v9.x | v9.0.0* | v9.3.0* | v9.11.0* | | | +| v10.x | | | v10.0.0 | | | +| v11.x | | | v11.0.0 | v11.8.0 | | +| v12.x | | | | v12.0.0 | v12.11.0 | +| v13.x | | | | | | \* Indicates that the N-API version was released as experimental diff --git a/n-api/napi_acquire_threadsafe_function.md b/n-api/napi_acquire_threadsafe_function.md index 4f5dcf3e..8bace032 100644 --- a/n-api/napi_acquire_threadsafe_function.md +++ b/n-api/napi_acquire_threadsafe_function.md @@ -9,7 +9,7 @@ NAPI_EXTERN napi_status napi_acquire_threadsafe_function(napi_threadsafe_function func); ``` -- `[in] func`: The asynchronous thread-safe JavaScript function to start making +* `[in] func`: The asynchronous thread-safe JavaScript function to start making use of. A thread should call this API before passing `func` to any other thread-safe diff --git a/n-api/napi_add_finalizer.md b/n-api/napi_add_finalizer.md index 22e71f4f..a1cf2c65 100644 --- a/n-api/napi_add_finalizer.md +++ b/n-api/napi_add_finalizer.md @@ -1,6 +1,4 @@ -> Stability: 1 - Experimental - @@ -14,22 +12,23 @@ napi_status napi_add_finalizer(napi_env env, napi_ref* result); ``` - - `[in] env`: The environment that the API is invoked under. - - `[in] js_object`: The JavaScript object to which the native data will be - attached. - - `[in] native_object`: The native data that will be attached to the JavaScript - object. - - `[in] finalize_cb`: Native callback that will be used to free the - native data when the JavaScript object is ready for garbage-collection. - - `[in] finalize_hint`: Optional contextual hint that is passed to the - finalize callback. - - `[out] result`: Optional reference to the JavaScript object. +* `[in] env`: The environment that the API is invoked under. +* `[in] js_object`: The JavaScript object to which the native data will be + attached. +* `[in] native_object`: The native data that will be attached to the JavaScript + object. +* `[in] finalize_cb`: Native callback that will be used to free the + native data when the JavaScript object is ready for garbage-collection. +* `[in] finalize_hint`: Optional contextual hint that is passed to the + finalize callback. +* `[out] result`: Optional reference to the JavaScript object. Returns `napi_ok` if the API succeeded. Adds a `napi_finalize` callback which will be called when the JavaScript object in `js_object` is ready for garbage collection. This API is similar to -`napi_wrap()` except that +`napi_wrap()` except that: + * the native data cannot be retrieved later using `napi_unwrap()`, * nor can it be removed later using `napi_remove_wrap()`, and * the API can be called multiple times with different data items in order to diff --git a/n-api/napi_adjust_external_memory.md b/n-api/napi_adjust_external_memory.md index 6c3f6beb..5b8cd4e0 100644 --- a/n-api/napi_adjust_external_memory.md +++ b/n-api/napi_adjust_external_memory.md @@ -9,10 +9,10 @@ NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env, int64_t* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] change_in_bytes`: The change in externally allocated memory that is +* `[in] env`: The environment that the API is invoked under. +* `[in] change_in_bytes`: The change in externally allocated memory that is kept alive by JavaScript objects. -- `[out] result`: The adjusted value +* `[out] result`: The adjusted value Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_async_destroy.md b/n-api/napi_async_destroy.md index c996bb73..2f4c9865 100644 --- a/n-api/napi_async_destroy.md +++ b/n-api/napi_async_destroy.md @@ -8,8 +8,8 @@ napi_status napi_async_destroy(napi_env env, napi_async_context async_context); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] async_context`: The async context to be destroyed. +* `[in] env`: The environment that the API is invoked under. +* `[in] async_context`: The async context to be destroyed. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_async_execute_callback.md b/n-api/napi_async_execute_callback.md index 77f113bd..221cd99f 100644 --- a/n-api/napi_async_execute_callback.md +++ b/n-api/napi_async_execute_callback.md @@ -9,10 +9,10 @@ operations. Callback functions must satisfy the following signature: typedef void (*napi_async_execute_callback)(napi_env env, void* data); ``` -Implementations of this type of function should avoid making any N-API calls -that could result in the execution of JavaScript or interaction with -JavaScript objects. Most often, any code that needs to make N-API -calls should be made in `napi_async_complete_callback` instead. -Avoid using the `napi_env` parameter in the execute callback as -it will likely execute JavaScript. +Implementations of this function must avoid making N-API calls +that execute JavaScript or interact with +JavaScript objects. N-API +calls should be in the `napi_async_complete_callback` instead. +Do not use the `napi_env` parameter as it will likely +result in execution of JavaScript. diff --git a/n-api/napi_async_init.md b/n-api/napi_async_init.md index dc509c82..759aa813 100644 --- a/n-api/napi_async_init.md +++ b/n-api/napi_async_init.md @@ -10,13 +10,13 @@ napi_status napi_async_init(napi_env env, napi_async_context* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] async_resource`: An optional object associated with the async work +* `[in] env`: The environment that the API is invoked under. +* `[in] async_resource`: An optional object associated with the async work that will be passed to possible `async_hooks` [`init` hooks][]. -- `[in] async_resource_name`: Identifier for the kind of resource +* `[in] async_resource_name`: Identifier for the kind of resource that is being provided for diagnostic information exposed by the `async_hooks` API. -- `[out] result`: The initialized async context. +* `[out] result`: The initialized async context. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_call_function.md b/n-api/napi_call_function.md index f5e7735e..f843942c 100644 --- a/n-api/napi_call_function.md +++ b/n-api/napi_call_function.md @@ -12,14 +12,14 @@ napi_status napi_call_function(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] recv`: The `this` object passed to the called function. -- `[in] func`: `napi_value` representing the JavaScript function +* `[in] env`: The environment that the API is invoked under. +* `[in] recv`: The `this` object passed to the called function. +* `[in] func`: `napi_value` representing the JavaScript function to be invoked. -- `[in] argc`: The count of elements in the `argv` array. -- `[in] argv`: Array of `napi_values` representing JavaScript values passed +* `[in] argc`: The count of elements in the `argv` array. +* `[in] argv`: Array of `napi_values` representing JavaScript values passed in as arguments to the function. -- `[out] result`: `napi_value` representing the JavaScript object returned. +* `[out] result`: `napi_value` representing the JavaScript object returned. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_call_threadsafe_function.md b/n-api/napi_call_threadsafe_function.md index e1d1d0ef..b995a55f 100644 --- a/n-api/napi_call_threadsafe_function.md +++ b/n-api/napi_call_threadsafe_function.md @@ -11,10 +11,10 @@ napi_call_threadsafe_function(napi_threadsafe_function func, napi_threadsafe_function_call_mode is_blocking); ``` -- `[in] func`: The asynchronous thread-safe JavaScript function to invoke. -- `[in] data`: Data to send into JavaScript via the callback `call_js_cb` +* `[in] func`: The asynchronous thread-safe JavaScript function to invoke. +* `[in] data`: Data to send into JavaScript via the callback `call_js_cb` provided during the creation of the thread-safe JavaScript function. -- `[in] is_blocking`: Flag whose value can be either `napi_tsfn_blocking` to +* `[in] is_blocking`: Flag whose value can be either `napi_tsfn_blocking` to indicate that the call should block if the queue is full or `napi_tsfn_nonblocking` to indicate that the call should return immediately with a status of `napi_queue_full` whenever the queue is full. diff --git a/n-api/napi_cancel_async_work.md b/n-api/napi_cancel_async_work.md index b2531058..3f829e93 100644 --- a/n-api/napi_cancel_async_work.md +++ b/n-api/napi_cancel_async_work.md @@ -8,8 +8,8 @@ napi_status napi_cancel_async_work(napi_env env, napi_async_work work); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] work`: The handle returned by the call to `napi_create_async_work`. +* `[in] env`: The environment that the API is invoked under. +* `[in] work`: The handle returned by the call to `napi_create_async_work`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_close_callback_scope.md b/n-api/napi_close_callback_scope.md index 0ff8a346..9878db23 100644 --- a/n-api/napi_close_callback_scope.md +++ b/n-api/napi_close_callback_scope.md @@ -8,8 +8,8 @@ NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, napi_callback_scope scope) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] scope`: The scope to be closed. +* `[in] env`: The environment that the API is invoked under. +* `[in] scope`: The scope to be closed. This API can be called even if there is a pending JavaScript exception. diff --git a/n-api/napi_close_escapable_handle_scope.md b/n-api/napi_close_escapable_handle_scope.md index 8bd71aa2..a422408f 100644 --- a/n-api/napi_close_escapable_handle_scope.md +++ b/n-api/napi_close_escapable_handle_scope.md @@ -9,8 +9,8 @@ NAPI_EXTERN napi_status napi_handle_scope scope); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] scope`: `napi_value` representing the scope to be closed. +* `[in] env`: The environment that the API is invoked under. +* `[in] scope`: `napi_value` representing the scope to be closed. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_close_handle_scope.md b/n-api/napi_close_handle_scope.md index c648ddfa..d7981c57 100644 --- a/n-api/napi_close_handle_scope.md +++ b/n-api/napi_close_handle_scope.md @@ -8,8 +8,8 @@ NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, napi_handle_scope scope); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] scope`: `napi_value` representing the scope to be closed. +* `[in] env`: The environment that the API is invoked under. +* `[in] scope`: `napi_value` representing the scope to be closed. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_coerce_to_bool.md b/n-api/napi_coerce_to_bool.md index 6f03ebf6..3b4ebcd0 100644 --- a/n-api/napi_coerce_to_bool.md +++ b/n-api/napi_coerce_to_bool.md @@ -9,9 +9,9 @@ napi_status napi_coerce_to_bool(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: The JavaScript value to coerce. -- `[out] result`: `napi_value` representing the coerced JavaScript `Boolean`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The JavaScript value to coerce. +* `[out] result`: `napi_value` representing the coerced JavaScript `Boolean`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_coerce_to_number.md b/n-api/napi_coerce_to_number.md index 6b2d7e9f..27433f1b 100644 --- a/n-api/napi_coerce_to_number.md +++ b/n-api/napi_coerce_to_number.md @@ -9,9 +9,9 @@ napi_status napi_coerce_to_number(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: The JavaScript value to coerce. -- `[out] result`: `napi_value` representing the coerced JavaScript `Number`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The JavaScript value to coerce. +* `[out] result`: `napi_value` representing the coerced JavaScript `Number`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_coerce_to_object.md b/n-api/napi_coerce_to_object.md index ee3397e7..4e452232 100644 --- a/n-api/napi_coerce_to_object.md +++ b/n-api/napi_coerce_to_object.md @@ -9,9 +9,9 @@ napi_status napi_coerce_to_object(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: The JavaScript value to coerce. -- `[out] result`: `napi_value` representing the coerced JavaScript `Object`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The JavaScript value to coerce. +* `[out] result`: `napi_value` representing the coerced JavaScript `Object`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_coerce_to_string.md b/n-api/napi_coerce_to_string.md index a9693747..83e5183e 100644 --- a/n-api/napi_coerce_to_string.md +++ b/n-api/napi_coerce_to_string.md @@ -9,9 +9,9 @@ napi_status napi_coerce_to_string(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: The JavaScript value to coerce. -- `[out] result`: `napi_value` representing the coerced JavaScript `String`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The JavaScript value to coerce. +* `[out] result`: `napi_value` representing the coerced JavaScript `String`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_array.md b/n-api/napi_create_array.md index 64d7310e..15ad761b 100644 --- a/n-api/napi_create_array.md +++ b/n-api/napi_create_array.md @@ -7,8 +7,8 @@ napiVersion: 1 napi_status napi_create_array(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[out] result`: A `napi_value` representing a JavaScript `Array`. +* `[in] env`: The environment that the N-API call is invoked under. +* `[out] result`: A `napi_value` representing a JavaScript `Array`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_array_with_length.md b/n-api/napi_create_array_with_length.md index d4b3a75a..0c1e84b0 100644 --- a/n-api/napi_create_array_with_length.md +++ b/n-api/napi_create_array_with_length.md @@ -9,9 +9,9 @@ napi_status napi_create_array_with_length(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] length`: The initial length of the `Array`. -- `[out] result`: A `napi_value` representing a JavaScript `Array`. +* `[in] env`: The environment that the API is invoked under. +* `[in] length`: The initial length of the `Array`. +* `[out] result`: A `napi_value` representing a JavaScript `Array`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_arraybuffer.md b/n-api/napi_create_arraybuffer.md index 35d99bb0..de99f455 100644 --- a/n-api/napi_create_arraybuffer.md +++ b/n-api/napi_create_arraybuffer.md @@ -10,10 +10,10 @@ napi_status napi_create_arraybuffer(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] length`: The length in bytes of the array buffer to create. -- `[out] data`: Pointer to the underlying byte buffer of the `ArrayBuffer`. -- `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`. +* `[in] env`: The environment that the API is invoked under. +* `[in] length`: The length in bytes of the array buffer to create. +* `[out] data`: Pointer to the underlying byte buffer of the `ArrayBuffer`. +* `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_async_work.md b/n-api/napi_create_async_work.md index 110aa2f8..e6f1eed9 100644 --- a/n-api/napi_create_async_work.md +++ b/n-api/napi_create_async_work.md @@ -17,20 +17,20 @@ napi_status napi_create_async_work(napi_env env, napi_async_work* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] async_resource`: An optional object associated with the async work +* `[in] env`: The environment that the API is invoked under. +* `[in] async_resource`: An optional object associated with the async work that will be passed to possible `async_hooks` [`init` hooks][]. -- `[in] async_resource_name`: Identifier for the kind of resource that is +* `[in] async_resource_name`: Identifier for the kind of resource that is being provided for diagnostic information exposed by the `async_hooks` API. -- `[in] execute`: The native function which should be called to execute +* `[in] execute`: The native function which should be called to execute the logic asynchronously. The given function is called from a worker pool thread and can execute in parallel with the main event loop thread. -- `[in] complete`: The native function which will be called when the +* `[in] complete`: The native function which will be called when the asynchronous logic is completed or is cancelled. The given function is called from the main event loop thread. -- `[in] data`: User-provided data context. This will be passed back into the +* `[in] data`: User-provided data context. This will be passed back into the execute and complete functions. -- `[out] result`: `napi_async_work*` which is the handle to the newly created +* `[out] result`: `napi_async_work*` which is the handle to the newly created async work. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_bigint_int64.md b/n-api/napi_create_bigint_int64.md index f13eecf4..a0310c93 100644 --- a/n-api/napi_create_bigint_int64.md +++ b/n-api/napi_create_bigint_int64.md @@ -10,9 +10,9 @@ napi_status napi_create_bigint_int64(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: Integer value to be represented in JavaScript. -- `[out] result`: A `napi_value` representing a JavaScript `BigInt`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: Integer value to be represented in JavaScript. +* `[out] result`: A `napi_value` representing a JavaScript `BigInt`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_bigint_uint64.md b/n-api/napi_create_bigint_uint64.md index 59050f58..8bbcd84c 100644 --- a/n-api/napi_create_bigint_uint64.md +++ b/n-api/napi_create_bigint_uint64.md @@ -10,9 +10,9 @@ napi_status napi_create_bigint_uint64(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: Unsigned integer value to be represented in JavaScript. -- `[out] result`: A `napi_value` representing a JavaScript `BigInt`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: Unsigned integer value to be represented in JavaScript. +* `[out] result`: A `napi_value` representing a JavaScript `BigInt`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_bigint_words.md b/n-api/napi_create_bigint_words.md index 940c5555..7c7f1a81 100644 --- a/n-api/napi_create_bigint_words.md +++ b/n-api/napi_create_bigint_words.md @@ -12,12 +12,12 @@ napi_status napi_create_bigint_words(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] sign_bit`: Determines if the resulting `BigInt` will be positive or +* `[in] env`: The environment that the API is invoked under. +* `[in] sign_bit`: Determines if the resulting `BigInt` will be positive or negative. -- `[in] word_count`: The length of the `words` array. -- `[in] words`: An array of `uint64_t` little-endian 64-bit words. -- `[out] result`: A `napi_value` representing a JavaScript `BigInt`. +* `[in] word_count`: The length of the `words` array. +* `[in] words`: An array of `uint64_t` little-endian 64-bit words. +* `[out] result`: A `napi_value` representing a JavaScript `BigInt`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_buffer.md b/n-api/napi_create_buffer.md index 1a96cd53..897b18dd 100644 --- a/n-api/napi_create_buffer.md +++ b/n-api/napi_create_buffer.md @@ -10,10 +10,10 @@ napi_status napi_create_buffer(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] size`: Size in bytes of the underlying buffer. -- `[out] data`: Raw pointer to the underlying buffer. -- `[out] result`: A `napi_value` representing a `node::Buffer`. +* `[in] env`: The environment that the API is invoked under. +* `[in] size`: Size in bytes of the underlying buffer. +* `[out] data`: Raw pointer to the underlying buffer. +* `[out] result`: A `napi_value` representing a `node::Buffer`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_buffer_copy.md b/n-api/napi_create_buffer_copy.md index c8ed286e..442eb330 100644 --- a/n-api/napi_create_buffer_copy.md +++ b/n-api/napi_create_buffer_copy.md @@ -11,12 +11,12 @@ napi_status napi_create_buffer_copy(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] size`: Size in bytes of the input buffer (should be the same as the +* `[in] env`: The environment that the API is invoked under. +* `[in] size`: Size in bytes of the input buffer (should be the same as the size of the new buffer). -- `[in] data`: Raw pointer to the underlying buffer to copy from. -- `[out] result_data`: Pointer to the new `Buffer`'s underlying data buffer. -- `[out] result`: A `napi_value` representing a `node::Buffer`. +* `[in] data`: Raw pointer to the underlying buffer to copy from. +* `[out] result_data`: Pointer to the new `Buffer`'s underlying data buffer. +* `[out] result`: A `napi_value` representing a `node::Buffer`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_dataview.md b/n-api/napi_create_dataview.md index de6ba97f..31d80444 100644 --- a/n-api/napi_create_dataview.md +++ b/n-api/napi_create_dataview.md @@ -11,12 +11,12 @@ napi_status napi_create_dataview(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] length`: Number of elements in the `DataView`. -- `[in] arraybuffer`: `ArrayBuffer` underlying the `DataView`. -- `[in] byte_offset`: The byte offset within the `ArrayBuffer` from which to +* `[in] env`: The environment that the API is invoked under. +* `[in] length`: Number of elements in the `DataView`. +* `[in] arraybuffer`: `ArrayBuffer` underlying the `DataView`. +* `[in] byte_offset`: The byte offset within the `ArrayBuffer` from which to start projecting the `DataView`. -- `[out] result`: A `napi_value` representing a JavaScript `DataView`. +* `[out] result`: A `napi_value` representing a JavaScript `DataView`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_date.md b/n-api/napi_create_date.md index 270eefbf..6d43efe6 100644 --- a/n-api/napi_create_date.md +++ b/n-api/napi_create_date.md @@ -2,20 +2,21 @@ added: v11.11.0 --> -> Stability: 1 - Experimental - ```C napi_status napi_create_date(napi_env env, double time, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] time`: ECMAScript time value in milliseconds since 01 January, 1970 UTC. -- `[out] result`: A `napi_value` representing a JavaScript `Date`. +* `[in] env`: The environment that the API is invoked under. +* `[in] time`: ECMAScript time value in milliseconds since 01 January, 1970 UTC. +* `[out] result`: A `napi_value` representing a JavaScript `Date`. Returns `napi_ok` if the API succeeded. +This API does not observe leap seconds; they are ignored, as +ECMAScript aligns with POSIX time specification. + This API allocates a JavaScript `Date` object. JavaScript `Date` objects are described in diff --git a/n-api/napi_create_double.md b/n-api/napi_create_double.md index 97802953..4d7ece98 100644 --- a/n-api/napi_create_double.md +++ b/n-api/napi_create_double.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_create_double(napi_env env, double value, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: Double-precision value to be represented in JavaScript. -- `[out] result`: A `napi_value` representing a JavaScript `Number`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: Double-precision value to be represented in JavaScript. +* `[out] result`: A `napi_value` representing a JavaScript `Number`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_error.md b/n-api/napi_create_error.md index 69d8b2e7..6b524ad8 100644 --- a/n-api/napi_create_error.md +++ b/n-api/napi_create_error.md @@ -10,12 +10,12 @@ NAPI_EXTERN napi_status napi_create_error(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] code`: Optional `napi_value` with the string for the error code to +* `[in] env`: The environment that the API is invoked under. +* `[in] code`: Optional `napi_value` with the string for the error code to be associated with the error. -- `[in] msg`: `napi_value` that references a JavaScript `String` to be +* `[in] msg`: `napi_value` that references a JavaScript `String` to be used as the message for the `Error`. -- `[out] result`: `napi_value` representing the error created. +* `[out] result`: `napi_value` representing the error created. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_external.md b/n-api/napi_create_external.md index 2ffc7322..d01c6a58 100644 --- a/n-api/napi_create_external.md +++ b/n-api/napi_create_external.md @@ -11,13 +11,13 @@ napi_status napi_create_external(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] data`: Raw pointer to the external data. -- `[in] finalize_cb`: Optional callback to call when the external value +* `[in] env`: The environment that the API is invoked under. +* `[in] data`: Raw pointer to the external data. +* `[in] finalize_cb`: Optional callback to call when the external value is being collected. -- `[in] finalize_hint`: Optional hint to pass to the finalize callback +* `[in] finalize_hint`: Optional hint to pass to the finalize callback during collection. -- `[out] result`: A `napi_value` representing an external value. +* `[out] result`: A `napi_value` representing an external value. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_external_arraybuffer.md b/n-api/napi_create_external_arraybuffer.md index 21a500b6..57b4fe03 100644 --- a/n-api/napi_create_external_arraybuffer.md +++ b/n-api/napi_create_external_arraybuffer.md @@ -13,15 +13,15 @@ napi_create_external_arraybuffer(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] external_data`: Pointer to the underlying byte buffer of the +* `[in] env`: The environment that the API is invoked under. +* `[in] external_data`: Pointer to the underlying byte buffer of the `ArrayBuffer`. -- `[in] byte_length`: The length in bytes of the underlying buffer. -- `[in] finalize_cb`: Optional callback to call when the `ArrayBuffer` is +* `[in] byte_length`: The length in bytes of the underlying buffer. +* `[in] finalize_cb`: Optional callback to call when the `ArrayBuffer` is being collected. -- `[in] finalize_hint`: Optional hint to pass to the finalize callback +* `[in] finalize_hint`: Optional hint to pass to the finalize callback during collection. -- `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`. +* `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_external_buffer.md b/n-api/napi_create_external_buffer.md index 96862529..33cc90cc 100644 --- a/n-api/napi_create_external_buffer.md +++ b/n-api/napi_create_external_buffer.md @@ -12,15 +12,15 @@ napi_status napi_create_external_buffer(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] length`: Size in bytes of the input buffer (should be the same as +* `[in] env`: The environment that the API is invoked under. +* `[in] length`: Size in bytes of the input buffer (should be the same as the size of the new buffer). -- `[in] data`: Raw pointer to the underlying buffer to copy from. -- `[in] finalize_cb`: Optional callback to call when the `ArrayBuffer` is +* `[in] data`: Raw pointer to the underlying buffer to copy from. +* `[in] finalize_cb`: Optional callback to call when the `ArrayBuffer` is being collected. -- `[in] finalize_hint`: Optional hint to pass to the finalize callback +* `[in] finalize_hint`: Optional hint to pass to the finalize callback during collection. -- `[out] result`: A `napi_value` representing a `node::Buffer`. +* `[out] result`: A `napi_value` representing a `node::Buffer`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_function.md b/n-api/napi_create_function.md index 27b7c020..231d9cfb 100644 --- a/n-api/napi_create_function.md +++ b/n-api/napi_create_function.md @@ -12,16 +12,16 @@ napi_status napi_create_function(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] utf8Name`: The name of the function encoded as UTF8. This is visible +* `[in] env`: The environment that the API is invoked under. +* `[in] utf8Name`: The name of the function encoded as UTF8. This is visible within JavaScript as the new function object's `name` property. -- `[in] length`: The length of the `utf8name` in bytes, or +* `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. -- `[in] cb`: The native function which should be called when this function +* `[in] cb`: The native function which should be called when this function object is invoked. -- `[in] data`: User-provided data context. This will be passed back into the +* `[in] data`: User-provided data context. This will be passed back into the function when invoked later. -- `[out] result`: `napi_value` representing the JavaScript function object for +* `[out] result`: `napi_value` representing the JavaScript function object for the newly created function. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_int32.md b/n-api/napi_create_int32.md index dbc3d5a9..60944b58 100644 --- a/n-api/napi_create_int32.md +++ b/n-api/napi_create_int32.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: Integer value to be represented in JavaScript. -- `[out] result`: A `napi_value` representing a JavaScript `Number`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: Integer value to be represented in JavaScript. +* `[out] result`: A `napi_value` representing a JavaScript `Number`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_int64.md b/n-api/napi_create_int64.md index 8b966b87..0af4d61f 100644 --- a/n-api/napi_create_int64.md +++ b/n-api/napi_create_int64.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: Integer value to be represented in JavaScript. -- `[out] result`: A `napi_value` representing a JavaScript `Number`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: Integer value to be represented in JavaScript. +* `[out] result`: A `napi_value` representing a JavaScript `Number`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_object.md b/n-api/napi_create_object.md index 1941b23b..2b5ceff4 100644 --- a/n-api/napi_create_object.md +++ b/n-api/napi_create_object.md @@ -7,8 +7,8 @@ napiVersion: 1 napi_status napi_create_object(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: A `napi_value` representing a JavaScript `Object`. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: A `napi_value` representing a JavaScript `Object`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_promise.md b/n-api/napi_create_promise.md index 50c808c9..b567b7f7 100644 --- a/n-api/napi_create_promise.md +++ b/n-api/napi_create_promise.md @@ -9,11 +9,11 @@ napi_status napi_create_promise(napi_env env, napi_value* promise); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] deferred`: A newly created deferred object which can later be passed to +* `[in] env`: The environment that the API is invoked under. +* `[out] deferred`: A newly created deferred object which can later be passed to `napi_resolve_deferred()` or `napi_reject_deferred()` to resolve resp. reject the associated promise. -- `[out] promise`: The JavaScript promise associated with the deferred object. +* `[out] promise`: The JavaScript promise associated with the deferred object. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_range_error.md b/n-api/napi_create_range_error.md index bc2307ed..189513a2 100644 --- a/n-api/napi_create_range_error.md +++ b/n-api/napi_create_range_error.md @@ -10,12 +10,12 @@ NAPI_EXTERN napi_status napi_create_range_error(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] code`: Optional `napi_value` with the string for the error code to +* `[in] env`: The environment that the API is invoked under. +* `[in] code`: Optional `napi_value` with the string for the error code to be associated with the error. -- `[in] msg`: `napi_value` that references a JavaScript `String` to be +* `[in] msg`: `napi_value` that references a JavaScript `String` to be used as the message for the `Error`. -- `[out] result`: `napi_value` representing the error created. +* `[out] result`: `napi_value` representing the error created. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_reference.md b/n-api/napi_create_reference.md index 0560054b..dfa7881a 100644 --- a/n-api/napi_create_reference.md +++ b/n-api/napi_create_reference.md @@ -10,11 +10,11 @@ NAPI_EXTERN napi_status napi_create_reference(napi_env env, napi_ref* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing the `Object` to which we want +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing the `Object` to which we want a reference. -- `[in] initial_refcount`: Initial reference count for the new reference. -- `[out] result`: `napi_ref` pointing to the new reference. +* `[in] initial_refcount`: Initial reference count for the new reference. +* `[out] result`: `napi_ref` pointing to the new reference. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_string_latin1.md b/n-api/napi_create_string_latin1.md index 5b6e1949..d926f97c 100644 --- a/n-api/napi_create_string_latin1.md +++ b/n-api/napi_create_string_latin1.md @@ -10,11 +10,11 @@ napi_status napi_create_string_latin1(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] str`: Character buffer representing an ISO-8859-1-encoded string. -- `[in] length`: The length of the string in bytes, or +* `[in] env`: The environment that the API is invoked under. +* `[in] str`: Character buffer representing an ISO-8859-1-encoded string. +* `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. -- `[out] result`: A `napi_value` representing a JavaScript `String`. +* `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_string_utf16.md b/n-api/napi_create_string_utf16.md index 56544a52..351271f5 100644 --- a/n-api/napi_create_string_utf16.md +++ b/n-api/napi_create_string_utf16.md @@ -10,11 +10,11 @@ napi_status napi_create_string_utf16(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] str`: Character buffer representing a UTF16-LE-encoded string. -- `[in] length`: The length of the string in two-byte code units, or +* `[in] env`: The environment that the API is invoked under. +* `[in] str`: Character buffer representing a UTF16-LE-encoded string. +* `[in] length`: The length of the string in two-byte code units, or `NAPI_AUTO_LENGTH` if it is null-terminated. -- `[out] result`: A `napi_value` representing a JavaScript `String`. +* `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_string_utf8.md b/n-api/napi_create_string_utf8.md index ed2744a2..d6393956 100644 --- a/n-api/napi_create_string_utf8.md +++ b/n-api/napi_create_string_utf8.md @@ -10,11 +10,11 @@ napi_status napi_create_string_utf8(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] str`: Character buffer representing a UTF8-encoded string. -- `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` +* `[in] env`: The environment that the API is invoked under. +* `[in] str`: Character buffer representing a UTF8-encoded string. +* `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. -- `[out] result`: A `napi_value` representing a JavaScript `String`. +* `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_symbol.md b/n-api/napi_create_symbol.md index 6ea89fcd..8a3fb327 100644 --- a/n-api/napi_create_symbol.md +++ b/n-api/napi_create_symbol.md @@ -9,10 +9,10 @@ napi_status napi_create_symbol(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] description`: Optional `napi_value` which refers to a JavaScript +* `[in] env`: The environment that the API is invoked under. +* `[in] description`: Optional `napi_value` which refers to a JavaScript `String` to be set as the description for the symbol. -- `[out] result`: A `napi_value` representing a JavaScript `Symbol`. +* `[out] result`: A `napi_value` representing a JavaScript `Symbol`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_threadsafe_function.md b/n-api/napi_create_threadsafe_function.md index 140a2dca..d1f4cb08 100644 --- a/n-api/napi_create_threadsafe_function.md +++ b/n-api/napi_create_threadsafe_function.md @@ -23,25 +23,25 @@ napi_create_threadsafe_function(napi_env env, napi_threadsafe_function* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] func`: An optional JavaScript function to call from another thread. +* `[in] env`: The environment that the API is invoked under. +* `[in] func`: An optional JavaScript function to call from another thread. It must be provided if `NULL` is passed to `call_js_cb`. -- `[in] async_resource`: An optional object associated with the async work that +* `[in] async_resource`: An optional object associated with the async work that will be passed to possible `async_hooks` [`init` hooks][]. -- `[in] async_resource_name`: A JavaScript string to provide an identifier for +* `[in] async_resource_name`: A JavaScript string to provide an identifier for the kind of resource that is being provided for diagnostic information exposed by the `async_hooks` API. -- `[in] max_queue_size`: Maximum size of the queue. `0` for no limit. -- `[in] initial_thread_count`: The initial number of threads, including the main +* `[in] max_queue_size`: Maximum size of the queue. `0` for no limit. +* `[in] initial_thread_count`: The initial number of threads, including the main thread, which will be making use of this function. -- `[in] thread_finalize_data`: Optional data to be passed to `thread_finalize_cb`. -- `[in] thread_finalize_cb`: Optional function to call when the +* `[in] thread_finalize_data`: Optional data to be passed to `thread_finalize_cb`. +* `[in] thread_finalize_cb`: Optional function to call when the `napi_threadsafe_function` is being destroyed. -- `[in] context`: Optional data to attach to the resulting +* `[in] context`: Optional data to attach to the resulting `napi_threadsafe_function`. -- `[in] call_js_cb`: Optional callback which calls the JavaScript function in +* `[in] call_js_cb`: Optional callback which calls the JavaScript function in response to a call on a different thread. This callback will be called on the main thread. If not given, the JavaScript function will be called with no parameters and with `undefined` as its `this` value. -- `[out] result`: The asynchronous thread-safe JavaScript function. +* `[out] result`: The asynchronous thread-safe JavaScript function. diff --git a/n-api/napi_create_type_error.md b/n-api/napi_create_type_error.md index 63070401..bc1aa484 100644 --- a/n-api/napi_create_type_error.md +++ b/n-api/napi_create_type_error.md @@ -10,12 +10,12 @@ NAPI_EXTERN napi_status napi_create_type_error(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] code`: Optional `napi_value` with the string for the error code to +* `[in] env`: The environment that the API is invoked under. +* `[in] code`: Optional `napi_value` with the string for the error code to be associated with the error. -- `[in] msg`: `napi_value` that references a JavaScript `String` to be +* `[in] msg`: `napi_value` that references a JavaScript `String` to be used as the message for the `Error`. -- `[out] result`: `napi_value` representing the error created. +* `[out] result`: `napi_value` representing the error created. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_typedarray.md b/n-api/napi_create_typedarray.md index 48503903..1974a376 100644 --- a/n-api/napi_create_typedarray.md +++ b/n-api/napi_create_typedarray.md @@ -12,13 +12,13 @@ napi_status napi_create_typedarray(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] type`: Scalar datatype of the elements within the `TypedArray`. -- `[in] length`: Number of elements in the `TypedArray`. -- `[in] arraybuffer`: `ArrayBuffer` underlying the typed array. -- `[in] byte_offset`: The byte offset within the `ArrayBuffer` from which to +* `[in] env`: The environment that the API is invoked under. +* `[in] type`: Scalar datatype of the elements within the `TypedArray`. +* `[in] length`: Number of elements in the `TypedArray`. +* `[in] arraybuffer`: `ArrayBuffer` underlying the typed array. +* `[in] byte_offset`: The byte offset within the `ArrayBuffer` from which to start projecting the `TypedArray`. -- `[out] result`: A `napi_value` representing a JavaScript `TypedArray`. +* `[out] result`: A `napi_value` representing a JavaScript `TypedArray`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_create_uint32.md b/n-api/napi_create_uint32.md index c4166aaf..7e1e25bc 100644 --- a/n-api/napi_create_uint32.md +++ b/n-api/napi_create_uint32.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: Unsigned integer value to be represented in JavaScript. -- `[out] result`: A `napi_value` representing a JavaScript `Number`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: Unsigned integer value to be represented in JavaScript. +* `[out] result`: A `napi_value` representing a JavaScript `Number`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_define_class.md b/n-api/napi_define_class.md index 06135250..3bc978b3 100644 --- a/n-api/napi_define_class.md +++ b/n-api/napi_define_class.md @@ -14,35 +14,36 @@ napi_status napi_define_class(napi_env env, napi_value* result); ``` - - `[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] 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.) - - `[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. - - `[in] properties`: Array of property descriptors describing static and - instance data properties, accessors, and methods on the class - See `napi_property_descriptor`. - - `[out] result`: A `napi_value` representing the constructor function for - the class. +* `[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] 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.) +* `[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. +* `[in] properties`: Array of property descriptors describing static and + instance data properties, accessors, and methods on the class + See `napi_property_descriptor`. +* `[out] result`: A `napi_value` representing the constructor function for + the class. 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). + +* 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 diff --git a/n-api/napi_define_properties.md b/n-api/napi_define_properties.md index 8943d353..ed1c4aae 100644 --- a/n-api/napi_define_properties.md +++ b/n-api/napi_define_properties.md @@ -10,10 +10,10 @@ napi_status napi_define_properties(napi_env env, const napi_property_descriptor* properties); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object from which to retrieve the properties. -- `[in] property_count`: The number of elements in the `properties` array. -- `[in] properties`: The array of property descriptors. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object from which to retrieve the properties. +* `[in] property_count`: The number of elements in the `properties` array. +* `[in] properties`: The array of property descriptors. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_delete_async_work.md b/n-api/napi_delete_async_work.md index 57b3b4e9..bab09112 100644 --- a/n-api/napi_delete_async_work.md +++ b/n-api/napi_delete_async_work.md @@ -8,8 +8,8 @@ napi_status napi_delete_async_work(napi_env env, napi_async_work work); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] work`: The handle returned by the call to `napi_create_async_work`. +* `[in] env`: The environment that the API is invoked under. +* `[in] work`: The handle returned by the call to `napi_create_async_work`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_delete_element.md b/n-api/napi_delete_element.md index 132cb817..9a26959a 100644 --- a/n-api/napi_delete_element.md +++ b/n-api/napi_delete_element.md @@ -10,10 +10,10 @@ napi_status napi_delete_element(napi_env env, bool* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object to query. -- `[in] index`: The index of the property to delete. -- `[out] result`: Whether the element deletion succeeded or not. `result` can +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object to query. +* `[in] index`: The index of the property to delete. +* `[out] result`: Whether the element deletion succeeded or not. `result` can optionally be ignored by passing `NULL`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_delete_property.md b/n-api/napi_delete_property.md index 8c9d996a..eabe2d0d 100644 --- a/n-api/napi_delete_property.md +++ b/n-api/napi_delete_property.md @@ -10,10 +10,10 @@ napi_status napi_delete_property(napi_env env, bool* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object to query. -- `[in] key`: The name of the property to delete. -- `[out] result`: Whether the property deletion succeeded or not. `result` can +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object to query. +* `[in] key`: The name of the property to delete. +* `[out] result`: Whether the property deletion succeeded or not. `result` can optionally be ignored by passing `NULL`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_delete_reference.md b/n-api/napi_delete_reference.md index 3b551a9a..017d3955 100644 --- a/n-api/napi_delete_reference.md +++ b/n-api/napi_delete_reference.md @@ -7,8 +7,8 @@ napiVersion: 1 NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] ref`: `napi_ref` to be deleted. +* `[in] env`: The environment that the API is invoked under. +* `[in] ref`: `napi_ref` to be deleted. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_escape_handle.md b/n-api/napi_escape_handle.md index b948fc33..44b11c4d 100644 --- a/n-api/napi_escape_handle.md +++ b/n-api/napi_escape_handle.md @@ -10,11 +10,11 @@ napi_status napi_escape_handle(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] scope`: `napi_value` representing the current scope. -- `[in] escapee`: `napi_value` representing the JavaScript `Object` to be +* `[in] env`: The environment that the API is invoked under. +* `[in] scope`: `napi_value` representing the current scope. +* `[in] escapee`: `napi_value` representing the JavaScript `Object` to be escaped. -- `[out] result`: `napi_value` representing the handle to the escaped +* `[out] result`: `napi_value` representing the handle to the escaped `Object` in the outer scope. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_extended_error_info.md b/n-api/napi_extended_error_info.md index 24f40d16..d363d76d 100644 --- a/n-api/napi_extended_error_info.md +++ b/n-api/napi_extended_error_info.md @@ -12,13 +12,13 @@ typedef struct { } napi_extended_error_info; ``` -- `error_message`: UTF8-encoded string containing a VM-neutral description of +* `error_message`: UTF8-encoded string containing a VM-neutral description of the error. -- `engine_reserved`: Reserved for VM-specific error details. This is currently +* `engine_reserved`: Reserved for VM-specific error details. This is currently not implemented for any VM. -- `engine_error_code`: VM-specific error code. This is currently +* `engine_error_code`: VM-specific error code. This is currently not implemented for any VM. -- `error_code`: The N-API status code that originated with the last error. +* `error_code`: The N-API status code that originated with the last error. See the [Error Handling][] section for additional information. diff --git a/n-api/napi_fatal_error.md b/n-api/napi_fatal_error.md index 5a20e0df..cdfadc59 100644 --- a/n-api/napi_fatal_error.md +++ b/n-api/napi_fatal_error.md @@ -10,11 +10,11 @@ NAPI_NO_RETURN void napi_fatal_error(const char* location, size_t message_len); ``` -- `[in] location`: Optional location at which the error occurred. -- `[in] location_len`: The length of the location in bytes, or +* `[in] location`: Optional location at which the error occurred. +* `[in] location_len`: The length of the location in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. -- `[in] message`: The message associated with the error. -- `[in] message_len`: The length of the message in bytes, or +* `[in] message`: The message associated with the error. +* `[in] message_len`: The length of the message in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. diff --git a/n-api/napi_fatal_exception.md b/n-api/napi_fatal_exception.md index 52e0865f..f32afa5a 100644 --- a/n-api/napi_fatal_exception.md +++ b/n-api/napi_fatal_exception.md @@ -7,8 +7,8 @@ napiVersion: 3 napi_status napi_fatal_exception(napi_env env, napi_value err); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] err`: The error that is passed to `'uncaughtException'`. +* `[in] env`: The environment that the API is invoked under. +* `[in] err`: The error that is passed to `'uncaughtException'`. Trigger an `'uncaughtException'` in JavaScript. Useful if an async callback throws an exception with no way to recover. diff --git a/n-api/napi_get_and_clear_last_exception.md b/n-api/napi_get_and_clear_last_exception.md index e968c174..6b435ce1 100644 --- a/n-api/napi_get_and_clear_last_exception.md +++ b/n-api/napi_get_and_clear_last_exception.md @@ -8,8 +8,8 @@ napi_status napi_get_and_clear_last_exception(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: The exception if one is pending, NULL otherwise. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: The exception if one is pending, NULL otherwise. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_array_length.md b/n-api/napi_get_array_length.md index 200207f9..4f240d22 100644 --- a/n-api/napi_get_array_length.md +++ b/n-api/napi_get_array_length.md @@ -9,10 +9,10 @@ napi_status napi_get_array_length(napi_env env, uint32_t* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing the JavaScript `Array` whose length is +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing the JavaScript `Array` whose length is being queried. -- `[out] result`: `uint32` representing length of the array. +* `[out] result`: `uint32` representing length of the array. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_arraybuffer_info.md b/n-api/napi_get_arraybuffer_info.md index 62300533..f5988b13 100644 --- a/n-api/napi_get_arraybuffer_info.md +++ b/n-api/napi_get_arraybuffer_info.md @@ -10,10 +10,10 @@ napi_status napi_get_arraybuffer_info(napi_env env, size_t* byte_length) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] arraybuffer`: `napi_value` representing the `ArrayBuffer` being queried. -- `[out] data`: The underlying data buffer of the `ArrayBuffer`. -- `[out] byte_length`: Length in bytes of the underlying data buffer. +* `[in] env`: The environment that the API is invoked under. +* `[in] arraybuffer`: `napi_value` representing the `ArrayBuffer` being queried. +* `[out] data`: The underlying data buffer of the `ArrayBuffer`. +* `[out] byte_length`: Length in bytes of the underlying data buffer. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_boolean.md b/n-api/napi_get_boolean.md index a2bf9b32..ce3851ba 100644 --- a/n-api/napi_get_boolean.md +++ b/n-api/napi_get_boolean.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_get_boolean(napi_env env, bool value, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: The value of the boolean to retrieve. -- `[out] result`: `napi_value` representing JavaScript `Boolean` singleton to +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The value of the boolean to retrieve. +* `[out] result`: `napi_value` representing JavaScript `Boolean` singleton to retrieve. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_buffer_info.md b/n-api/napi_get_buffer_info.md index e78dacc3..5ed01073 100644 --- a/n-api/napi_get_buffer_info.md +++ b/n-api/napi_get_buffer_info.md @@ -10,10 +10,10 @@ napi_status napi_get_buffer_info(napi_env env, size_t* length) ``` -- `[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`. -- `[out] length`: Length in bytes of the underlying data buffer. +* `[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`. +* `[out] length`: Length in bytes of the underlying data buffer. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_cb_info.md b/n-api/napi_get_cb_info.md index de3ed0d9..5c6dba9d 100644 --- a/n-api/napi_get_cb_info.md +++ b/n-api/napi_get_cb_info.md @@ -12,17 +12,17 @@ napi_status napi_get_cb_info(napi_env env, void** data) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] cbinfo`: The callback info passed into the callback function. -- `[in-out] argc`: Specifies the size of the provided `argv` array +* `[in] env`: The environment that the API is invoked under. +* `[in] cbinfo`: The callback info passed into the callback function. +* `[in-out] argc`: Specifies the size of the provided `argv` array and receives the actual count of arguments. -- `[out] argv`: Buffer to which the `napi_value` representing the +* `[out] argv`: Buffer to which the `napi_value` representing the arguments are copied. If there are more arguments than the provided count, only the requested number of arguments are copied. If there are fewer arguments provided than claimed, the rest of `argv` is filled with `napi_value` values that represent `undefined`. -- `[out] this`: Receives the JavaScript `this` argument for the call. -- `[out] data`: Receives the data pointer for the callback. +* `[out] this`: Receives the JavaScript `this` argument for the call. +* `[out] data`: Receives the data pointer for the callback. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_dataview_info.md b/n-api/napi_get_dataview_info.md index 268000dc..70d6fe1f 100644 --- a/n-api/napi_get_dataview_info.md +++ b/n-api/napi_get_dataview_info.md @@ -12,13 +12,13 @@ napi_status napi_get_dataview_info(napi_env env, size_t* byte_offset) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] dataview`: `napi_value` representing the `DataView` whose +* `[in] env`: The environment that the API is invoked under. +* `[in] dataview`: `napi_value` representing the `DataView` whose properties to query. -- `[out] byte_length`: `Number` of bytes in the `DataView`. -- `[out] data`: The data buffer underlying the `DataView`. -- `[out] arraybuffer`: `ArrayBuffer` underlying the `DataView`. -- `[out] byte_offset`: The byte offset within the data buffer from which +* `[out] byte_length`: `Number` of bytes in the `DataView`. +* `[out] data`: The data buffer underlying the `DataView`. +* `[out] arraybuffer`: `ArrayBuffer` underlying the `DataView`. +* `[out] byte_offset`: The byte offset within the data buffer from which to start projecting the `DataView`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_date_value.md b/n-api/napi_get_date_value.md index 7cfc77b6..0d625b86 100644 --- a/n-api/napi_get_date_value.md +++ b/n-api/napi_get_date_value.md @@ -2,19 +2,20 @@ added: v11.11.0 --> -> Stability: 1 - Experimental - ```C napi_status napi_get_date_value(napi_env env, napi_value value, double* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing a JavaScript `Date`. -- `[out] result`: Time value as a `double` represented as milliseconds +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing a JavaScript `Date`. +* `[out] result`: Time value as a `double` represented as milliseconds since midnight at the beginning of 01 January, 1970 UTC. +This API does not observe leap seconds; they are ignored, as +ECMAScript aligns with POSIX time specification. + Returns `napi_ok` if the API succeeded. If a non-date `napi_value` is passed in it returns `napi_date_expected`. diff --git a/n-api/napi_get_element.md b/n-api/napi_get_element.md index 8623f2f5..d268562b 100644 --- a/n-api/napi_get_element.md +++ b/n-api/napi_get_element.md @@ -10,10 +10,10 @@ napi_status napi_get_element(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object from which to retrieve the property. -- `[in] index`: The index of the property to get. -- `[out] result`: The value of the property. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object from which to retrieve the property. +* `[in] index`: The index of the property to get. +* `[out] result`: The value of the property. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_global.md b/n-api/napi_get_global.md index 17241b12..1614c873 100644 --- a/n-api/napi_get_global.md +++ b/n-api/napi_get_global.md @@ -7,8 +7,8 @@ napiVersion: 1 napi_status napi_get_global(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: `napi_value` representing JavaScript `global` object. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: `napi_value` representing JavaScript `global` object. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_instance_data.md b/n-api/napi_get_instance_data.md index bb0548a7..6e5e27a4 100644 --- a/n-api/napi_get_instance_data.md +++ b/n-api/napi_get_instance_data.md @@ -7,8 +7,8 @@ napi_status napi_get_instance_data(napi_env env, void** data); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[out] data`: The data item that was previously associated with the currently +* `[in] env`: The environment that the N-API call is invoked under. +* `[out] data`: The data item that was previously associated with the currently running Agent by a call to `napi_set_instance_data()`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_last_error_info.md b/n-api/napi_get_last_error_info.md index 915216d6..1d2ef321 100644 --- a/n-api/napi_get_last_error_info.md +++ b/n-api/napi_get_last_error_info.md @@ -9,8 +9,8 @@ napi_get_last_error_info(napi_env env, const napi_extended_error_info** result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: The `napi_extended_error_info` structure with more +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: The `napi_extended_error_info` structure with more information about the error. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_named_property.md b/n-api/napi_get_named_property.md index 7b027032..ea4d3955 100644 --- a/n-api/napi_get_named_property.md +++ b/n-api/napi_get_named_property.md @@ -10,10 +10,10 @@ napi_status napi_get_named_property(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object from which to retrieve the property. -- `[in] utf8Name`: The name of the property to get. -- `[out] result`: The value of the property. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object from which to retrieve the property. +* `[in] utf8Name`: The name of the property to get. +* `[out] result`: The value of the property. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_new_target.md b/n-api/napi_get_new_target.md index 34d0e803..be099f2c 100644 --- a/n-api/napi_get_new_target.md +++ b/n-api/napi_get_new_target.md @@ -9,9 +9,9 @@ napi_status napi_get_new_target(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] cbinfo`: The callback info passed into the callback function. -- `[out] result`: The `new.target` of the constructor call. +* `[in] env`: The environment that the API is invoked under. +* `[in] cbinfo`: The callback info passed into the callback function. +* `[out] result`: The `new.target` of the constructor call. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_node_version.md b/n-api/napi_get_node_version.md index 49795719..0fc2576b 100644 --- a/n-api/napi_get_node_version.md +++ b/n-api/napi_get_node_version.md @@ -15,8 +15,8 @@ napi_status napi_get_node_version(napi_env env, const napi_node_version** version); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] version`: A pointer to version information for Node.js itself. +* `[in] env`: The environment that the API is invoked under. +* `[out] version`: A pointer to version information for Node.js itself. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_null.md b/n-api/napi_get_null.md index 798b9792..f634d67e 100644 --- a/n-api/napi_get_null.md +++ b/n-api/napi_get_null.md @@ -7,8 +7,8 @@ napiVersion: 1 napi_status napi_get_null(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: `napi_value` representing JavaScript `null` object. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: `napi_value` representing JavaScript `null` object. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_property.md b/n-api/napi_get_property.md index b91e7a6f..0a3b7fe0 100644 --- a/n-api/napi_get_property.md +++ b/n-api/napi_get_property.md @@ -10,10 +10,10 @@ napi_status napi_get_property(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object from which to retrieve the property. -- `[in] key`: The name of the property to retrieve. -- `[out] result`: The value of the property. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object from which to retrieve the property. +* `[in] key`: The name of the property to retrieve. +* `[out] result`: The value of the property. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_property_names.md b/n-api/napi_get_property_names.md index 641691a4..bd8173bd 100644 --- a/n-api/napi_get_property_names.md +++ b/n-api/napi_get_property_names.md @@ -9,9 +9,9 @@ napi_status napi_get_property_names(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object from which to retrieve the properties. -- `[out] result`: A `napi_value` representing an array of JavaScript values +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object from which to retrieve the properties. +* `[out] result`: A `napi_value` representing an array of JavaScript values that represent the property names of the object. The API can be used to iterate over `result` using [`napi_get_array_length`][] and [`napi_get_element`][]. diff --git a/n-api/napi_get_prototype.md b/n-api/napi_get_prototype.md index 295133ac..bc8c5876 100644 --- a/n-api/napi_get_prototype.md +++ b/n-api/napi_get_prototype.md @@ -9,11 +9,11 @@ napi_status napi_get_prototype(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] object`: `napi_value` representing JavaScript `Object` whose prototype +* `[in] env`: The environment that the API is invoked under. +* `[in] object`: `napi_value` representing JavaScript `Object` whose prototype to return. This returns the equivalent of `Object.getPrototypeOf` (which is not the same as the function's `prototype` property). -- `[out] result`: `napi_value` representing prototype of the given object. +* `[out] result`: `napi_value` representing prototype of the given object. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_reference_value.md b/n-api/napi_get_reference_value.md index 44327c61..d024b31b 100644 --- a/n-api/napi_get_reference_value.md +++ b/n-api/napi_get_reference_value.md @@ -11,9 +11,10 @@ NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, the `napi_value passed` in or out of these methods is a handle to the object to which the reference is related. -- `[in] env`: The environment that the API is invoked under. -- `[in] ref`: `napi_ref` for which we requesting the corresponding `Object`. -- `[out] result`: The `napi_value` for the `Object` referenced by the + +* `[in] env`: The environment that the API is invoked under. +* `[in] ref`: `napi_ref` for which we requesting the corresponding `Object`. +* `[out] result`: The `napi_value` for the `Object` referenced by the `napi_ref`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_threadsafe_function_context.md b/n-api/napi_get_threadsafe_function_context.md index 1d855d83..e1f00fdb 100644 --- a/n-api/napi_get_threadsafe_function_context.md +++ b/n-api/napi_get_threadsafe_function_context.md @@ -10,8 +10,8 @@ napi_get_threadsafe_function_context(napi_threadsafe_function func, void** result); ``` -- `[in] func`: The thread-safe function for which to retrieve the context. -- `[out] result`: The location where to store the context. +* `[in] func`: The thread-safe function for which to retrieve the context. +* `[out] result`: The location where to store the context. This API may be called from any thread which makes use of `func`. diff --git a/n-api/napi_get_typedarray_info.md b/n-api/napi_get_typedarray_info.md index 2cf66891..8d7de24e 100644 --- a/n-api/napi_get_typedarray_info.md +++ b/n-api/napi_get_typedarray_info.md @@ -13,16 +13,16 @@ napi_status napi_get_typedarray_info(napi_env env, size_t* byte_offset) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] typedarray`: `napi_value` representing the `TypedArray` whose +* `[in] env`: The environment that the API is invoked under. +* `[in] typedarray`: `napi_value` representing the `TypedArray` whose properties to query. -- `[out] type`: Scalar datatype of the elements within the `TypedArray`. -- `[out] length`: The number of elements in the `TypedArray`. -- `[out] data`: The data buffer underlying the `TypedArray` adjusted by +* `[out] type`: Scalar datatype of the elements within the `TypedArray`. +* `[out] length`: The number of elements in the `TypedArray`. +* `[out] data`: The data buffer underlying the `TypedArray` adjusted by the `byte_offset` value so that it points to the first element in the `TypedArray`. -- `[out] arraybuffer`: The `ArrayBuffer` underlying the `TypedArray`. -- `[out] byte_offset`: The byte offset within the underlying native array +* `[out] arraybuffer`: The `ArrayBuffer` underlying the `TypedArray`. +* `[out] byte_offset`: The byte offset within the underlying native array at which the first element of the arrays is located. The value for the data parameter has already been adjusted so that data points to the first element in the array. Therefore, the first byte of the native array would be at diff --git a/n-api/napi_get_undefined.md b/n-api/napi_get_undefined.md index d004b31b..46656f40 100644 --- a/n-api/napi_get_undefined.md +++ b/n-api/napi_get_undefined.md @@ -7,8 +7,8 @@ napiVersion: 1 napi_status napi_get_undefined(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: `napi_value` representing JavaScript Undefined value. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: `napi_value` representing JavaScript Undefined value. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_uv_event_loop.md b/n-api/napi_get_uv_event_loop.md index 38c23cc7..89179cf6 100644 --- a/n-api/napi_get_uv_event_loop.md +++ b/n-api/napi_get_uv_event_loop.md @@ -10,8 +10,8 @@ NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, uv_loop_t** loop); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] loop`: The current libuv loop instance. +* `[in] env`: The environment that the API is invoked under. +* `[out] loop`: The current libuv loop instance. diff --git a/n-api/napi_get_value_bigint_int64.md b/n-api/napi_get_value_bigint_int64.md index dc9755ce..f1fe203a 100644 --- a/n-api/napi_get_value_bigint_int64.md +++ b/n-api/napi_get_value_bigint_int64.md @@ -11,11 +11,11 @@ napi_status napi_get_value_bigint_int64(napi_env env, bool* lossless); ``` -- `[in] env`: The environment that the API is invoked under -- `[in] value`: `napi_value` representing JavaScript `BigInt`. -- `[out] result`: C `int64_t` primitive equivalent of the given JavaScript +* `[in] env`: The environment that the API is invoked under +* `[in] value`: `napi_value` representing JavaScript `BigInt`. +* `[out] result`: C `int64_t` primitive equivalent of the given JavaScript `BigInt`. -- `[out] lossless`: Indicates whether the `BigInt` value was converted +* `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly. Returns `napi_ok` if the API succeeded. If a non-`BigInt` is passed in it diff --git a/n-api/napi_get_value_bigint_uint64.md b/n-api/napi_get_value_bigint_uint64.md index 43cb60d1..6aa71e8f 100644 --- a/n-api/napi_get_value_bigint_uint64.md +++ b/n-api/napi_get_value_bigint_uint64.md @@ -11,11 +11,11 @@ napi_status napi_get_value_bigint_uint64(napi_env env, bool* lossless); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript `BigInt`. -- `[out] result`: C `uint64_t` primitive equivalent of the given JavaScript +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript `BigInt`. +* `[out] result`: C `uint64_t` primitive equivalent of the given JavaScript `BigInt`. -- `[out] lossless`: Indicates whether the `BigInt` value was converted +* `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly. Returns `napi_ok` if the API succeeded. If a non-`BigInt` is passed in it diff --git a/n-api/napi_get_value_bigint_words.md b/n-api/napi_get_value_bigint_words.md index fdbfe3d7..34fd7f12 100644 --- a/n-api/napi_get_value_bigint_words.md +++ b/n-api/napi_get_value_bigint_words.md @@ -12,14 +12,14 @@ napi_status napi_get_value_bigint_words(napi_env env, uint64_t* words); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript `BigInt`. -- `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript `BigInt`. +* `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive or negative. -- `[in/out] word_count`: Must be initialized to the length of the `words` +* `[in/out] word_count`: Must be initialized to the length of the `words` array. Upon return, it will be set to the actual number of words that would be needed to store this `BigInt`. -- `[out] words`: Pointer to a pre-allocated 64-bit word array. +* `[out] words`: Pointer to a pre-allocated 64-bit word array. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_get_value_bool.md b/n-api/napi_get_value_bool.md index 53492002..4cacf8e1 100644 --- a/n-api/napi_get_value_bool.md +++ b/n-api/napi_get_value_bool.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript `Boolean`. -- `[out] result`: C boolean primitive equivalent of the given JavaScript +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript `Boolean`. +* `[out] result`: C boolean primitive equivalent of the given JavaScript `Boolean`. Returns `napi_ok` if the API succeeded. If a non-boolean `napi_value` is diff --git a/n-api/napi_get_value_double.md b/n-api/napi_get_value_double.md index b420f39e..393b7e03 100644 --- a/n-api/napi_get_value_double.md +++ b/n-api/napi_get_value_double.md @@ -9,9 +9,9 @@ napi_status napi_get_value_double(napi_env env, double* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript `Number`. -- `[out] result`: C double primitive equivalent of the given JavaScript +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript `Number`. +* `[out] result`: C double primitive equivalent of the given JavaScript `Number`. Returns `napi_ok` if the API succeeded. If a non-number `napi_value` is passed diff --git a/n-api/napi_get_value_external.md b/n-api/napi_get_value_external.md index 082b71f8..c1b12b4a 100644 --- a/n-api/napi_get_value_external.md +++ b/n-api/napi_get_value_external.md @@ -9,9 +9,9 @@ napi_status napi_get_value_external(napi_env env, void** result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript external value. -- `[out] result`: Pointer to the data wrapped by the JavaScript external value. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript external value. +* `[out] result`: Pointer to the data wrapped by the JavaScript external value. Returns `napi_ok` if the API succeeded. If a non-external `napi_value` is passed in it returns `napi_invalid_arg`. diff --git a/n-api/napi_get_value_int32.md b/n-api/napi_get_value_int32.md index 23aa6fff..00882ec7 100644 --- a/n-api/napi_get_value_int32.md +++ b/n-api/napi_get_value_int32.md @@ -9,9 +9,9 @@ napi_status napi_get_value_int32(napi_env env, int32_t* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript `Number`. -- `[out] result`: C `int32` primitive equivalent of the given JavaScript +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript `Number`. +* `[out] result`: C `int32` primitive equivalent of the given JavaScript `Number`. Returns `napi_ok` if the API succeeded. If a non-number `napi_value` diff --git a/n-api/napi_get_value_int64.md b/n-api/napi_get_value_int64.md index b25f9619..db34fb24 100644 --- a/n-api/napi_get_value_int64.md +++ b/n-api/napi_get_value_int64.md @@ -9,9 +9,9 @@ napi_status napi_get_value_int64(napi_env env, int64_t* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript `Number`. -- `[out] result`: C `int64` primitive equivalent of the given JavaScript +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript `Number`. +* `[out] result`: C `int64` primitive equivalent of the given JavaScript `Number`. Returns `napi_ok` if the API succeeded. If a non-number `napi_value` diff --git a/n-api/napi_get_value_string_latin1.md b/n-api/napi_get_value_string_latin1.md index cdbd84ee..57c0fec9 100644 --- a/n-api/napi_get_value_string_latin1.md +++ b/n-api/napi_get_value_string_latin1.md @@ -11,13 +11,13 @@ napi_status napi_get_value_string_latin1(napi_env env, size_t* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript string. -- `[in] buf`: Buffer to write the ISO-8859-1-encoded string into. If NULL is +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript string. +* `[in] buf`: Buffer to write the ISO-8859-1-encoded string into. If NULL is passed in, the length of the string (in bytes) is returned. -- `[in] bufsize`: Size of the destination buffer. When this value is +* `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -- `[out] result`: Number of bytes copied into the buffer, excluding the null +* `[out] result`: Number of bytes copied into the buffer, excluding the null terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` diff --git a/n-api/napi_get_value_string_utf16.md b/n-api/napi_get_value_string_utf16.md index 2483f4e8..8d9679b1 100644 --- a/n-api/napi_get_value_string_utf16.md +++ b/n-api/napi_get_value_string_utf16.md @@ -11,13 +11,13 @@ napi_status napi_get_value_string_utf16(napi_env env, size_t* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript string. -- `[in] buf`: Buffer to write the UTF16-LE-encoded string into. If NULL is +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript string. +* `[in] buf`: Buffer to write the UTF16-LE-encoded string into. If NULL is passed in, the length of the string (in 2-byte code units) is returned. -- `[in] bufsize`: Size of the destination buffer. When this value is +* `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -- `[out] result`: Number of 2-byte code units copied into the buffer, excluding +* `[out] result`: Number of 2-byte code units copied into the buffer, excluding the null terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` diff --git a/n-api/napi_get_value_string_utf8.md b/n-api/napi_get_value_string_utf8.md index 9753e627..1a50fafe 100644 --- a/n-api/napi_get_value_string_utf8.md +++ b/n-api/napi_get_value_string_utf8.md @@ -11,13 +11,13 @@ napi_status napi_get_value_string_utf8(napi_env env, size_t* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript string. -- `[in] buf`: Buffer to write the UTF8-encoded string into. If NULL is passed +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript string. +* `[in] buf`: Buffer to write the UTF8-encoded string into. If NULL is passed in, the length of the string (in bytes) is returned. -- `[in] bufsize`: Size of the destination buffer. When this value is +* `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -- `[out] result`: Number of bytes copied into the buffer, excluding the null +* `[out] result`: Number of bytes copied into the buffer, excluding the null terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` diff --git a/n-api/napi_get_value_uint32.md b/n-api/napi_get_value_uint32.md index c446f8d6..5c728faf 100644 --- a/n-api/napi_get_value_uint32.md +++ b/n-api/napi_get_value_uint32.md @@ -9,9 +9,9 @@ napi_status napi_get_value_uint32(napi_env env, uint32_t* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: `napi_value` representing JavaScript `Number`. -- `[out] result`: C primitive equivalent of the given `napi_value` as a +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: `napi_value` representing JavaScript `Number`. +* `[out] result`: C primitive equivalent of the given `napi_value` as a `uint32_t`. Returns `napi_ok` if the API succeeded. If a non-number `napi_value` diff --git a/n-api/napi_get_version.md b/n-api/napi_get_version.md index 0af1ffe4..08116d3a 100644 --- a/n-api/napi_get_version.md +++ b/n-api/napi_get_version.md @@ -8,8 +8,8 @@ napi_status napi_get_version(napi_env env, uint32_t* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: The highest version of N-API supported. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: The highest version of N-API supported. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_has_element.md b/n-api/napi_has_element.md index 5f97131d..a41e6234 100644 --- a/n-api/napi_has_element.md +++ b/n-api/napi_has_element.md @@ -10,10 +10,10 @@ napi_status napi_has_element(napi_env env, bool* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object to query. -- `[in] index`: The index of the property whose existence to check. -- `[out] result`: Whether the property exists on the object or not. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object to query. +* `[in] index`: The index of the property whose existence to check. +* `[out] result`: Whether the property exists on the object or not. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_has_named_property.md b/n-api/napi_has_named_property.md index 4d18ce5e..63f85809 100644 --- a/n-api/napi_has_named_property.md +++ b/n-api/napi_has_named_property.md @@ -10,10 +10,10 @@ napi_status napi_has_named_property(napi_env env, bool* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object to query. -- `[in] utf8Name`: The name of the property whose existence to check. -- `[out] result`: Whether the property exists on the object or not. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object to query. +* `[in] utf8Name`: The name of the property whose existence to check. +* `[out] result`: Whether the property exists on the object or not. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_has_own_property.md b/n-api/napi_has_own_property.md index 48c5ba6d..37ab0994 100644 --- a/n-api/napi_has_own_property.md +++ b/n-api/napi_has_own_property.md @@ -10,10 +10,10 @@ napi_status napi_has_own_property(napi_env env, bool* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object to query. -- `[in] key`: The name of the own property whose existence to check. -- `[out] result`: Whether the own property exists on the object or not. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object to query. +* `[in] key`: The name of the own property whose existence to check. +* `[out] result`: Whether the own property exists on the object or not. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_has_property.md b/n-api/napi_has_property.md index 5fb63b3c..653fa5cc 100644 --- a/n-api/napi_has_property.md +++ b/n-api/napi_has_property.md @@ -10,10 +10,10 @@ napi_status napi_has_property(napi_env env, bool* result); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object to query. -- `[in] key`: The name of the property whose existence to check. -- `[out] result`: Whether the property exists on the object or not. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object to query. +* `[in] key`: The name of the property whose existence to check. +* `[out] result`: Whether the property exists on the object or not. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_instanceof.md b/n-api/napi_instanceof.md index d56fce36..daf68b71 100644 --- a/n-api/napi_instanceof.md +++ b/n-api/napi_instanceof.md @@ -10,11 +10,11 @@ napi_status napi_instanceof(napi_env env, bool* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] object`: The JavaScript value to check. -- `[in] constructor`: The JavaScript function object of the constructor +* `[in] env`: The environment that the API is invoked under. +* `[in] object`: The JavaScript value to check. +* `[in] constructor`: The JavaScript function object of the constructor function to check against. -- `[out] result`: Boolean that is set to true if `object instanceof constructor` +* `[out] result`: Boolean that is set to true if `object instanceof constructor` is true. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_array.md b/n-api/napi_is_array.md index b408753a..de000c13 100644 --- a/n-api/napi_is_array.md +++ b/n-api/napi_is_array.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_is_array(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 object is an array. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The JavaScript value to check. +* `[out] result`: Whether the given object is an array. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_arraybuffer.md b/n-api/napi_is_arraybuffer.md index bf61712b..67f042d3 100644 --- a/n-api/napi_is_arraybuffer.md +++ b/n-api/napi_is_arraybuffer.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_is_arraybuffer(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 object is an `ArrayBuffer`. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The JavaScript value to check. +* `[out] result`: Whether the given object is an `ArrayBuffer`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_buffer.md b/n-api/napi_is_buffer.md index 78275b9c..b5419125 100644 --- a/n-api/napi_is_buffer.md +++ b/n-api/napi_is_buffer.md @@ -7,9 +7,9 @@ napiVersion: 1 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` +* `[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. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_dataview.md b/n-api/napi_is_dataview.md index 51ff64eb..4c611e32 100644 --- a/n-api/napi_is_dataview.md +++ b/n-api/napi_is_dataview.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_is_dataview(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 `DataView`. +* `[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 `DataView`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_date.md b/n-api/napi_is_date.md index 0ee0dbb8..3c1da76c 100644 --- a/n-api/napi_is_date.md +++ b/n-api/napi_is_date.md @@ -2,15 +2,13 @@ added: v11.11.0 --> -> Stability: 1 - Experimental - ```C napi_status napi_is_date(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 JavaScript `Date` +* `[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 JavaScript `Date` object. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_error.md b/n-api/napi_is_error.md index e23efd87..c7d00839 100644 --- a/n-api/napi_is_error.md +++ b/n-api/napi_is_error.md @@ -9,9 +9,9 @@ NAPI_EXTERN napi_status napi_is_error(napi_env env, bool* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: The `napi_value` to be checked. -- `[out] result`: Boolean value that is set to true if `napi_value` represents +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The `napi_value` to be checked. +* `[out] result`: Boolean value that is set to true if `napi_value` represents an error, false otherwise. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_error_1.md b/n-api/napi_is_error_1.md index 0b2f3079..84694c61 100644 --- a/n-api/napi_is_error_1.md +++ b/n-api/napi_is_error_1.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_is_error(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 an `Error` object. +* `[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 an `Error` object. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_exception_pending.md b/n-api/napi_is_exception_pending.md index e4114a49..53bd69df 100644 --- a/n-api/napi_is_exception_pending.md +++ b/n-api/napi_is_exception_pending.md @@ -7,8 +7,8 @@ napiVersion: 1 napi_status napi_is_exception_pending(napi_env env, bool* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: Boolean value that is set to true if an exception is pending. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: Boolean value that is set to true if an exception is pending. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_is_promise.md b/n-api/napi_is_promise.md index f2839d50..477587da 100644 --- a/n-api/napi_is_promise.md +++ b/n-api/napi_is_promise.md @@ -9,8 +9,8 @@ napi_status napi_is_promise(napi_env env, bool* is_promise); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] promise`: The promise to examine -- `[out] is_promise`: Flag indicating whether `promise` is a native promise +* `[in] env`: The environment that the API is invoked under. +* `[in] promise`: The promise to examine +* `[out] is_promise`: Flag indicating whether `promise` is a native promise object - that is, a promise object created by the underlying engine. diff --git a/n-api/napi_is_typedarray.md b/n-api/napi_is_typedarray.md index 2effe38e..3971552b 100644 --- a/n-api/napi_is_typedarray.md +++ b/n-api/napi_is_typedarray.md @@ -7,9 +7,9 @@ napiVersion: 1 napi_status napi_is_typedarray(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 `TypedArray`. +* `[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 `TypedArray`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_make_callback.md b/n-api/napi_make_callback.md index fa4de144..6af792f7 100644 --- a/n-api/napi_make_callback.md +++ b/n-api/napi_make_callback.md @@ -16,19 +16,19 @@ napi_status napi_make_callback(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] async_context`: Context for the async operation that is +* `[in] env`: The environment that the API is invoked under. +* `[in] async_context`: Context for the async operation that is invoking the callback. This should normally be a value previously obtained from [`napi_async_init`][]. However `NULL` is also allowed, which indicates the current async context (if any) is to be used for the callback. -- `[in] recv`: The `this` object passed to the called function. -- `[in] func`: `napi_value` representing the JavaScript function +* `[in] recv`: The `this` object passed to the called function. +* `[in] func`: `napi_value` representing the JavaScript function to be invoked. -- `[in] argc`: The count of elements in the `argv` array. -- `[in] argv`: Array of JavaScript values as `napi_value` +* `[in] argc`: The count of elements in the `argv` array. +* `[in] argv`: Array of JavaScript values as `napi_value` representing the arguments to the function. -- `[out] result`: `napi_value` representing the JavaScript object returned. +* `[out] result`: `napi_value` representing the JavaScript object returned. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_new_instance.md b/n-api/napi_new_instance.md index 68d05fc7..4823f535 100644 --- a/n-api/napi_new_instance.md +++ b/n-api/napi_new_instance.md @@ -11,13 +11,13 @@ napi_status napi_new_instance(napi_env env, napi_value* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] cons`: `napi_value` representing the JavaScript function +* `[in] env`: The environment that the API is invoked under. +* `[in] cons`: `napi_value` representing the JavaScript function to be invoked as a constructor. -- `[in] argc`: The count of elements in the `argv` array. -- `[in] argv`: Array of JavaScript values as `napi_value` +* `[in] argc`: The count of elements in the `argv` array. +* `[in] argv`: Array of JavaScript values as `napi_value` representing the arguments to the constructor. -- `[out] result`: `napi_value` representing the JavaScript object returned, +* `[out] result`: `napi_value` representing the JavaScript object returned, which in this case is the constructed object. This method is used to instantiate a new JavaScript value using a given diff --git a/n-api/napi_open_callback_scope.md b/n-api/napi_open_callback_scope.md index 9154908a..c3f1b644 100644 --- a/n-api/napi_open_callback_scope.md +++ b/n-api/napi_open_callback_scope.md @@ -10,13 +10,13 @@ NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env, napi_callback_scope* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] resource_object`: An object associated with the async work +* `[in] env`: The environment that the API is invoked under. +* `[in] resource_object`: An object associated with the async work that will be passed to possible `async_hooks` [`init` hooks][]. -- `[in] context`: Context for the async operation that is +* `[in] context`: Context for the async operation that is invoking the callback. This should be a value previously obtained from [`napi_async_init`][]. -- `[out] result`: The newly created scope. +* `[out] result`: The newly created scope. There are cases (for example, resolving promises) where it is necessary to have the equivalent of the scope associated with a callback diff --git a/n-api/napi_open_escapable_handle_scope.md b/n-api/napi_open_escapable_handle_scope.md index 8ce067ac..b21aaf98 100644 --- a/n-api/napi_open_escapable_handle_scope.md +++ b/n-api/napi_open_escapable_handle_scope.md @@ -9,8 +9,8 @@ NAPI_EXTERN napi_status napi_handle_scope* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: `napi_value` representing the new scope. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: `napi_value` representing the new scope. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_open_handle_scope.md b/n-api/napi_open_handle_scope.md index f5787cc8..f3f9268d 100644 --- a/n-api/napi_open_handle_scope.md +++ b/n-api/napi_open_handle_scope.md @@ -8,8 +8,8 @@ NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, napi_handle_scope* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[out] result`: `napi_value` representing the new scope. +* `[in] env`: The environment that the API is invoked under. +* `[out] result`: `napi_value` representing the new scope. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_property_attributes.md b/n-api/napi_property_attributes.md index c4d86a73..b1c26420 100644 --- a/n-api/napi_property_attributes.md +++ b/n-api/napi_property_attributes.md @@ -18,14 +18,14 @@ attributes listed in [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. They can be one or more of the following bitflags: -- `napi_default` - Used to indicate that no explicit attributes are set on the +* `napi_default` - Used to indicate that no explicit attributes are set on the given property. By default, a property is read only, not enumerable and not configurable. -- `napi_writable` - Used to indicate that a given property is writable. -- `napi_enumerable` - Used to indicate that a given property is enumerable. -- `napi_configurable` - Used to indicate that a given property is configurable, +* `napi_writable` - Used to indicate that a given property is writable. +* `napi_enumerable` - Used to indicate that a given property is enumerable. +* `napi_configurable` - Used to indicate that a given property is configurable, as defined in [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. -- `napi_static` - Used to indicate that the property will be defined as +* `napi_static` - Used to indicate that the property will be defined as a static property on a class as opposed to an instance property, which is the default. This is used only by [`napi_define_class`][]. It is ignored by `napi_define_properties`. diff --git a/n-api/napi_property_descriptor.md b/n-api/napi_property_descriptor.md index 47c4d64e..2b3213fe 100644 --- a/n-api/napi_property_descriptor.md +++ b/n-api/napi_property_descriptor.md @@ -15,31 +15,31 @@ typedef struct { } napi_property_descriptor; ``` -- `utf8name`: Optional `String` describing the key for the property, +* `utf8name`: Optional `String` describing the key for the property, encoded as UTF8. One of `utf8name` or `name` must be provided for the property. -- `name`: Optional `napi_value` that points to a JavaScript string or symbol +* `name`: Optional `napi_value` that points to a JavaScript string or symbol to be used as the key for the property. One of `utf8name` or `name` must be provided for the property. -- `value`: The value that's retrieved by a get access of the property if the +* `value`: The value that's retrieved by a get access of the property if the property is a data property. If this is passed in, set `getter`, `setter`, `method` and `data` to `NULL` (since these members won't be used). -- `getter`: A function to call when a get access of the property is performed. +* `getter`: A function to call when a get access of the property is performed. If this is passed in, set `value` and `method` to `NULL` (since these members won't be used). The given function is called implicitly by the runtime when the property is accessed from JavaScript code (or if a get on the property is performed using a N-API call). -- `setter`: A function to call when a set access of the property is performed. +* `setter`: A function to call when a set access of the property is performed. If this is passed in, set `value` and `method` to `NULL` (since these members won't be used). The given function is called implicitly by the runtime when the property is set from JavaScript code (or if a set on the property is performed using a N-API call). -- `method`: Set this to make the property descriptor object's `value` +* `method`: Set this to make the property descriptor object's `value` property to be a JavaScript function represented by `method`. If this is passed in, set `value`, `getter` and `setter` to `NULL` (since these members won't be used). -- `attributes`: The attributes associated with the particular property. +* `attributes`: The attributes associated with the particular property. See [`napi_property_attributes`](#n_api_napi_property_attributes). -- `data`: The callback data passed into `method`, `getter` and `setter` if +* `data`: The callback data passed into `method`, `getter` and `setter` if this function is invoked. diff --git a/n-api/napi_queue_async_work.md b/n-api/napi_queue_async_work.md index 6e956fd5..3c1fb6be 100644 --- a/n-api/napi_queue_async_work.md +++ b/n-api/napi_queue_async_work.md @@ -8,8 +8,8 @@ napi_status napi_queue_async_work(napi_env env, napi_async_work work); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] work`: The handle returned by the call to `napi_create_async_work`. +* `[in] env`: The environment that the API is invoked under. +* `[in] work`: The handle returned by the call to `napi_create_async_work`. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_ref_threadsafe_function.md b/n-api/napi_ref_threadsafe_function.md index ddc931cd..bbb0b9de 100644 --- a/n-api/napi_ref_threadsafe_function.md +++ b/n-api/napi_ref_threadsafe_function.md @@ -9,8 +9,8 @@ NAPI_EXTERN napi_status napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] func`: The thread-safe function to reference. +* `[in] env`: The environment that the API is invoked under. +* `[in] func`: The thread-safe function to reference. This API is used to indicate that the event loop running on the main thread should not exit until `func` has been destroyed. Similar to [`uv_ref`][] it is diff --git a/n-api/napi_reference_ref.md b/n-api/napi_reference_ref.md index e4a5ba1c..d49a8b51 100644 --- a/n-api/napi_reference_ref.md +++ b/n-api/napi_reference_ref.md @@ -9,9 +9,9 @@ NAPI_EXTERN napi_status napi_reference_ref(napi_env env, int* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] ref`: `napi_ref` for which the reference count will be incremented. -- `[out] result`: The new reference count. +* `[in] env`: The environment that the API is invoked under. +* `[in] ref`: `napi_ref` for which the reference count will be incremented. +* `[out] result`: The new reference count. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_reference_unref.md b/n-api/napi_reference_unref.md index a95d123a..8222da1a 100644 --- a/n-api/napi_reference_unref.md +++ b/n-api/napi_reference_unref.md @@ -9,9 +9,9 @@ NAPI_EXTERN napi_status napi_reference_unref(napi_env env, int* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] ref`: `napi_ref` for which the reference count will be decremented. -- `[out] result`: The new reference count. +* `[in] env`: The environment that the API is invoked under. +* `[in] ref`: `napi_ref` for which the reference count will be decremented. +* `[out] result`: The new reference count. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_reject_deferred.md b/n-api/napi_reject_deferred.md index e83e1675..30f99280 100644 --- a/n-api/napi_reject_deferred.md +++ b/n-api/napi_reject_deferred.md @@ -9,9 +9,9 @@ napi_status napi_reject_deferred(napi_env env, napi_value rejection); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] deferred`: The deferred object whose associated promise to resolve. -- `[in] rejection`: The value with which to reject the promise. +* `[in] env`: The environment that the API is invoked under. +* `[in] deferred`: The deferred object whose associated promise to resolve. +* `[in] rejection`: The value with which to reject the promise. This API rejects a JavaScript promise by way of the deferred object with which it is associated. Thus, it can only be used to reject JavaScript diff --git a/n-api/napi_release_threadsafe_function.md b/n-api/napi_release_threadsafe_function.md index 55d16669..5eb86d7a 100644 --- a/n-api/napi_release_threadsafe_function.md +++ b/n-api/napi_release_threadsafe_function.md @@ -10,9 +10,9 @@ napi_release_threadsafe_function(napi_threadsafe_function func, napi_threadsafe_function_release_mode mode); ``` -- `[in] func`: The asynchronous thread-safe JavaScript function whose reference +* `[in] func`: The asynchronous thread-safe JavaScript function whose reference count to decrement. -- `[in] mode`: Flag whose value can be either `napi_tsfn_release` to indicate +* `[in] mode`: Flag whose value can be either `napi_tsfn_release` to indicate that the current thread will make no further calls to the thread-safe function, or `napi_tsfn_abort` to indicate that in addition to the current thread, no other thread should make any further calls to the thread-safe function. If set diff --git a/n-api/napi_remove_wrap.md b/n-api/napi_remove_wrap.md index c0f70468..9bd6491c 100644 --- a/n-api/napi_remove_wrap.md +++ b/n-api/napi_remove_wrap.md @@ -9,9 +9,9 @@ napi_status napi_remove_wrap(napi_env env, void** result); ``` - - `[in] env`: The environment that the API is invoked under. - - `[in] js_object`: The object associated with the native instance. - - `[out] result`: Pointer to the wrapped native instance. +* `[in] env`: The environment that the API is invoked under. +* `[in] js_object`: The object associated with the native instance. +* `[out] result`: Pointer to the wrapped native instance. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_resolve_deferred.md b/n-api/napi_resolve_deferred.md index 46f658d3..63130fd0 100644 --- a/n-api/napi_resolve_deferred.md +++ b/n-api/napi_resolve_deferred.md @@ -9,9 +9,9 @@ napi_status napi_resolve_deferred(napi_env env, napi_value resolution); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] deferred`: The deferred object whose associated promise to resolve. -- `[in] resolution`: The value with which to resolve the promise. +* `[in] env`: The environment that the API is invoked under. +* `[in] deferred`: The deferred object whose associated promise to resolve. +* `[in] resolution`: The value with which to resolve the promise. This API resolves a JavaScript promise by way of the deferred object with which it is associated. Thus, it can only be used to resolve JavaScript diff --git a/n-api/napi_run_script.md b/n-api/napi_run_script.md index caa78813..79994789 100644 --- a/n-api/napi_run_script.md +++ b/n-api/napi_run_script.md @@ -9,7 +9,7 @@ NAPI_EXTERN napi_status napi_run_script(napi_env env, napi_value* result); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] script`: A JavaScript string containing the script to execute. -- `[out] result`: The value resulting from having executed the script. +* `[in] env`: The environment that the API is invoked under. +* `[in] script`: A JavaScript string containing the script to execute. +* `[out] result`: The value resulting from having executed the script. diff --git a/n-api/napi_set_element.md b/n-api/napi_set_element.md index 46d71a73..1f8ed335 100644 --- a/n-api/napi_set_element.md +++ b/n-api/napi_set_element.md @@ -10,10 +10,10 @@ napi_status napi_set_element(napi_env env, napi_value value); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object from which to set the properties. -- `[in] index`: The index of the property to set. -- `[in] value`: The property value. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object from which to set the properties. +* `[in] index`: The index of the property to set. +* `[in] value`: The property value. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_set_instance_data.md b/n-api/napi_set_instance_data.md index dfc8125e..4d26cfc7 100644 --- a/n-api/napi_set_instance_data.md +++ b/n-api/napi_set_instance_data.md @@ -9,11 +9,11 @@ napi_status napi_set_instance_data(napi_env env, void* finalize_hint); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] data`: The data item to make available to bindings of this instance. -- `[in] finalize_cb`: The function to call when the environment is being torn +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] data`: The data item to make available to bindings of this instance. +* `[in] finalize_cb`: The function to call when the environment is being torn down. The function receives `data` so that it might free it. -- `[in] finalize_hint`: Optional hint to pass to the finalize callback +* `[in] finalize_hint`: Optional hint to pass to the finalize callback during collection. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_set_named_property.md b/n-api/napi_set_named_property.md index 921e8076..bf84111a 100644 --- a/n-api/napi_set_named_property.md +++ b/n-api/napi_set_named_property.md @@ -10,10 +10,10 @@ napi_status napi_set_named_property(napi_env env, napi_value value); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object on which to set the property. -- `[in] utf8Name`: The name of the property to set. -- `[in] value`: The property value. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object on which to set the property. +* `[in] utf8Name`: The name of the property to set. +* `[in] value`: The property value. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_set_property.md b/n-api/napi_set_property.md index 8c0eb3e6..d27535c6 100644 --- a/n-api/napi_set_property.md +++ b/n-api/napi_set_property.md @@ -10,10 +10,10 @@ napi_status napi_set_property(napi_env env, napi_value value); ``` -- `[in] env`: The environment that the N-API call is invoked under. -- `[in] object`: The object on which to set the property. -- `[in] key`: The name of the property to set. -- `[in] value`: The property value. +* `[in] env`: The environment that the N-API call is invoked under. +* `[in] object`: The object on which to set the property. +* `[in] key`: The name of the property to set. +* `[in] value`: The property value. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_strict_equals.md b/n-api/napi_strict_equals.md index 63efd83d..6fb35983 100644 --- a/n-api/napi_strict_equals.md +++ b/n-api/napi_strict_equals.md @@ -10,10 +10,10 @@ napi_status napi_strict_equals(napi_env env, bool* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] lhs`: The JavaScript value to check. -- `[in] rhs`: The JavaScript value to check against. -- `[out] result`: Whether the two `napi_value` objects are equal. +* `[in] env`: The environment that the API is invoked under. +* `[in] lhs`: The JavaScript value to check. +* `[in] rhs`: The JavaScript value to check against. +* `[out] result`: Whether the two `napi_value` objects are equal. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_threadsafe_function_call_js.md b/n-api/napi_threadsafe_function_call_js.md index cae034f5..5e6dc023 100644 --- a/n-api/napi_threadsafe_function_call_js.md +++ b/n-api/napi_threadsafe_function_call_js.md @@ -26,14 +26,14 @@ typedef void (*napi_threadsafe_function_call_js)(napi_env env, void* data); ``` -- `[in] env`: The environment to use for API calls, or `NULL` if the thread-safe +* `[in] env`: The environment to use for API calls, or `NULL` if the thread-safe function is being torn down and `data` may need to be freed. -- `[in] js_callback`: The JavaScript function to call, or `NULL` if the +* `[in] js_callback`: The JavaScript function to call, or `NULL` if the thread-safe function is being torn down and `data` may need to be freed. It may also be `NULL` if the thread-safe function was created without `js_callback`. -- `[in] context`: The optional data with which the thread-safe function was +* `[in] context`: The optional data with which the thread-safe function was created. -- `[in] data`: Data created by the secondary thread. It is the responsibility of +* `[in] data`: Data created by the secondary thread. It is the responsibility of the callback to convert this native data to JavaScript values (with N-API functions) that can be passed as parameters when `js_callback` is invoked. This pointer is managed entirely by the threads and this callback. Thus this callback diff --git a/n-api/napi_throw.md b/n-api/napi_throw.md index 675320f5..1089ebad 100644 --- a/n-api/napi_throw.md +++ b/n-api/napi_throw.md @@ -7,8 +7,8 @@ napiVersion: 1 NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] error`: The JavaScript value to be thrown. +* `[in] env`: The environment that the API is invoked under. +* `[in] error`: The JavaScript value to be thrown. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_throw_error.md b/n-api/napi_throw_error.md index 8f71d334..54859220 100644 --- a/n-api/napi_throw_error.md +++ b/n-api/napi_throw_error.md @@ -9,9 +9,9 @@ NAPI_EXTERN napi_status napi_throw_error(napi_env env, const char* msg); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] code`: Optional error code to be set on the error. -- `[in] msg`: C string representing the text to be associated with +* `[in] env`: The environment that the API is invoked under. +* `[in] code`: Optional error code to be set on the error. +* `[in] msg`: C string representing the text to be associated with the error. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_throw_range_error.md b/n-api/napi_throw_range_error.md index 2f94c3a0..74dcd3e2 100644 --- a/n-api/napi_throw_range_error.md +++ b/n-api/napi_throw_range_error.md @@ -9,9 +9,9 @@ NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, const char* msg); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] code`: Optional error code to be set on the error. -- `[in] msg`: C string representing the text to be associated with +* `[in] env`: The environment that the API is invoked under. +* `[in] code`: Optional error code to be set on the error. +* `[in] msg`: C string representing the text to be associated with the error. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_throw_type_error.md b/n-api/napi_throw_type_error.md index 6b4fc977..f4e742fa 100644 --- a/n-api/napi_throw_type_error.md +++ b/n-api/napi_throw_type_error.md @@ -9,9 +9,9 @@ NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, const char* msg); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] code`: Optional error code to be set on the error. -- `[in] msg`: C string representing the text to be associated with +* `[in] env`: The environment that the API is invoked under. +* `[in] code`: Optional error code to be set on the error. +* `[in] msg`: C string representing the text to be associated with the error. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_typeof.md b/n-api/napi_typeof.md index e6d5a584..2bb78798 100644 --- a/n-api/napi_typeof.md +++ b/n-api/napi_typeof.md @@ -7,12 +7,13 @@ napiVersion: 1 napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result) ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] value`: The JavaScript value whose type to query. -- `[out] result`: The type of the JavaScript value. +* `[in] env`: The environment that the API is invoked under. +* `[in] value`: The JavaScript value whose type to query. +* `[out] result`: The type of the JavaScript value. Returns `napi_ok` if the API succeeded. -- `napi_invalid_arg` if the type of `value` is not a known ECMAScript type and + +* `napi_invalid_arg` if the type of `value` is not a known ECMAScript type and `value` is not an External value. This API represents behavior similar to invoking the `typeof` Operator on diff --git a/n-api/napi_unref_threadsafe_function.md b/n-api/napi_unref_threadsafe_function.md index 5abd863e..6d8e67ca 100644 --- a/n-api/napi_unref_threadsafe_function.md +++ b/n-api/napi_unref_threadsafe_function.md @@ -9,8 +9,8 @@ NAPI_EXTERN napi_status napi_unref_threadsafe_function(napi_env env, napi_threadsafe_function func); ``` -- `[in] env`: The environment that the API is invoked under. -- `[in] func`: The thread-safe function to unreference. +* `[in] env`: The environment that the API is invoked under. +* `[in] func`: The thread-safe function to unreference. This API is used to indicate that the event loop running on the main thread may exit before `func` is destroyed. Similar to [`uv_unref`][] it is also diff --git a/n-api/napi_unwrap.md b/n-api/napi_unwrap.md index f3b8a2c7..55e726eb 100644 --- a/n-api/napi_unwrap.md +++ b/n-api/napi_unwrap.md @@ -9,9 +9,9 @@ napi_status napi_unwrap(napi_env env, void** result); ``` - - `[in] env`: The environment that the API is invoked under. - - `[in] js_object`: The object associated with the native instance. - - `[out] result`: Pointer to the wrapped native instance. +* `[in] env`: The environment that the API is invoked under. +* `[in] js_object`: The object associated with the native instance. +* `[out] result`: Pointer to the wrapped native instance. Returns `napi_ok` if the API succeeded. diff --git a/n-api/napi_wrap.md b/n-api/napi_wrap.md index ca6c606f..4bb68f11 100644 --- a/n-api/napi_wrap.md +++ b/n-api/napi_wrap.md @@ -12,16 +12,16 @@ napi_status napi_wrap(napi_env env, napi_ref* result); ``` - - `[in] env`: The environment that the API is invoked under. - - `[in] js_object`: The JavaScript object that will be the wrapper for the - native object. - - `[in] native_object`: The native instance that will be wrapped in the - JavaScript object. - - `[in] finalize_cb`: Optional native callback that can be used to free the - native instance when the JavaScript object is ready for garbage-collection. - - `[in] finalize_hint`: Optional contextual hint that is passed to the - finalize callback. - - `[out] result`: Optional reference to the wrapped object. +* `[in] env`: The environment that the API is invoked under. +* `[in] js_object`: The JavaScript object that will be the wrapper for the + native object. +* `[in] native_object`: The native instance that will be wrapped in the + JavaScript object. +* `[in] finalize_cb`: Optional native callback that can be used to free the + native instance when the JavaScript object is ready for garbage-collection. +* `[in] finalize_hint`: Optional contextual hint that is passed to the + finalize callback. +* `[out] result`: Optional reference to the wrapped object. Returns `napi_ok` if the API succeeded. diff --git a/n-api/object_wrap.md b/n-api/object_wrap.md index 925f0cf3..8600fe39 100644 --- a/n-api/object_wrap.md +++ b/n-api/object_wrap.md @@ -2,13 +2,13 @@ N-API offers a way to "wrap" C++ classes and instances so that the class constructor and methods can be called from JavaScript. - 1. The [`napi_define_class`][] API defines a JavaScript class with constructor, +1. The [`napi_define_class`][] API defines a JavaScript class with constructor, static properties and methods, and instance properties and methods that correspond to the C++ class. - 2. When JavaScript code invokes the constructor, the constructor callback +2. When JavaScript code invokes the constructor, the constructor callback uses [`napi_wrap`][] to wrap a new C++ instance in a JavaScript object, then returns the wrapper object. - 3. When JavaScript code invokes a method or property accessor on the class, +3. When JavaScript code invokes a method or property accessor on the class, the corresponding `napi_callback` C++ function is invoked. For an instance callback, [`napi_unwrap`][] obtains the C++ instance that is the target of the call. diff --git a/n-api/return_values.md b/n-api/return_values.md index cd702750..7c33a627 100644 --- a/n-api/return_values.md +++ b/n-api/return_values.md @@ -38,10 +38,10 @@ typedef struct napi_extended_error_info { }; ``` -- `error_message`: Textual representation of the error that occurred. -- `engine_reserved`: Opaque handle reserved for engine use only. -- `engine_error_code`: VM specific error code. -- `error_code`: n-api status code for the last error. +* `error_message`: Textual representation of the error that occurred. +* `engine_reserved`: Opaque handle reserved for engine use only. +* `engine_error_code`: VM specific error code. +* `error_code`: n-api status code for the last error. [`napi_get_last_error_info`][] returns the information for the last N-API call that was made. diff --git a/n-api/working_with_javascript_functions.md b/n-api/working_with_javascript_functions.md index 30ff3a73..26ddddb4 100644 --- a/n-api/working_with_javascript_functions.md +++ b/n-api/working_with_javascript_functions.md @@ -6,9 +6,10 @@ the `napi_callback` type. When the JavaScript VM calls back to native code, the `napi_callback` function provided is invoked. The APIs documented in this section allow the callback function to do the following: -- Get information about the context in which the callback was invoked. -- Get the arguments passed into the callback. -- Return a `napi_value` back from the callback. + +* Get information about the context in which the callback was invoked. +* Get the arguments passed into the callback. +* Return a `napi_value` back from the callback. Additionally, N-API provides a set of functions which allow calling JavaScript functions from native code. One can either call a function diff --git a/n-api/working_with_javascript_properties.md b/n-api/working_with_javascript_properties.md index ef7f79db..a2a139f2 100644 --- a/n-api/working_with_javascript_properties.md +++ b/n-api/working_with_javascript_properties.md @@ -7,10 +7,11 @@ objects. Some of these types are documented under Properties in JavaScript are represented as a tuple of a key and a value. Fundamentally, all property keys in N-API can be represented in one of the following forms: -- Named: a simple UTF8-encoded string -- Integer-Indexed: an index value represented by `uint32_t` -- JavaScript value: these are represented in N-API by `napi_value`. This can -be a `napi_value` representing a `String`, `Number`, or `Symbol`. + +* Named: a simple UTF8-encoded string +* Integer-Indexed: an index value represented by `uint32_t` +* JavaScript value: these are represented in N-API by `napi_value`. This can + be a `napi_value` representing a `String`, `Number`, or `Symbol`. N-API values are represented by the type `napi_value`. Any N-API call that requires a JavaScript value takes in a `napi_value`. diff --git a/n-api/working_with_javascript_values.md b/n-api/working_with_javascript_values.md index b837ad06..45cd18b8 100644 --- a/n-api/working_with_javascript_values.md +++ b/n-api/working_with_javascript_values.md @@ -4,6 +4,7 @@ Some of these types are documented under of the [ECMAScript Language Specification][]. Fundamentally, these APIs are used to do one of the following: + 1. Create a new JavaScript object 2. Convert from a primitive C type to an N-API value 3. Convert from N-API value to a primitive C type diff --git a/n-api/working_with_javascript_values_abstract_operations.md b/n-api/working_with_javascript_values_abstract_operations.md index 00e42821..19b9bb43 100644 --- a/n-api/working_with_javascript_values_abstract_operations.md +++ b/n-api/working_with_javascript_values_abstract_operations.md @@ -5,6 +5,7 @@ values. Some of these operations are documented under of the [ECMAScript Language Specification][]. These APIs support doing one of the following: + 1. Coerce JavaScript values to specific JavaScript types (such as `Number` or `String`). 2. Check the type of a JavaScript value. diff --git a/net/net_connect_options_connectlistener.md b/net/net_connect_options_connectlistener.md index 3a91fedb..cf55670d 100644 --- a/net/net_connect_options_connectlistener.md +++ b/net/net_connect_options_connectlistener.md @@ -1,8 +1,10 @@ + * `options` {Object} * `connectListener` {Function} +* 返回: {net.Socket} [`net.createConnection(options[, connectListener])`][`net.createConnection(options)`] 的别名。 diff --git a/net/net_connect_path_connectlistener.md b/net/net_connect_path_connectlistener.md index c71479e3..617a33ce 100644 --- a/net/net_connect_path_connectlistener.md +++ b/net/net_connect_path_connectlistener.md @@ -1,8 +1,10 @@ + * `path` {string} * `connectListener` {Function} +* 返回: {net.Socket} [`net.createConnection(path[, connectListener])`][`net.createConnection(path)`] 的别名。 diff --git a/net/net_connect_port_host_connectlistener.md b/net/net_connect_port_host_connectlistener.md index 0c1f76a2..3e81f9c0 100644 --- a/net/net_connect_port_host_connectlistener.md +++ b/net/net_connect_port_host_connectlistener.md @@ -1,9 +1,11 @@ + * `port` {number} * `host` {string} * `connectListener` {Function} +* 返回: {net.Socket} [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`] 的别名。 diff --git a/net/net_createconnection_port_host_connectlistener.md b/net/net_createconnection_port_host_connectlistener.md index 26b35450..a49cf033 100644 --- a/net/net_createconnection_port_host_connectlistener.md +++ b/net/net_createconnection_port_host_connectlistener.md @@ -4,7 +4,7 @@ added: v0.1.90 * `port` {number} 套接字应该连接的端口号。会传给[`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`]。 * `host` {string} 套接字应该连接的主机名。会传给[`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`]。**默认值:** `'localhost'`。 -* `connectListener` {Function} [`net.createConnection()`][] 的常见参数，在初始化套接字时对`'connect'` 事件的单次监听器，会传给[`socket.connect(path[, connectListener])`][`socket.connect(port, host)`]。 +* `connectListener` {Function} [`net.createConnection()`][] 的常见参数，在初始化套接字时对`'connect'` 事件的单次监听器，会传给 [`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`]。 * 返回: {net.Socket} 用于开启连接的新创建的套接字。 初始化一个 TCP 连接。 diff --git a/net/server_connections.md b/net/server_connections.md index 5198bbc8..cdd56109 100644 --- a/net/server_connections.md +++ b/net/server_connections.md @@ -5,6 +5,8 @@ deprecated: v0.9.7 > Stability: 0 - Deprecated: Use [`server.getConnections()`][] instead. +* {integer|null} + The number of concurrent connections on the server. This becomes `null` when sending a socket to a child with diff --git a/net/server_maxconnections.md b/net/server_maxconnections.md index 9fe86c74..9905f0b4 100644 --- a/net/server_maxconnections.md +++ b/net/server_maxconnections.md @@ -2,6 +2,8 @@ added: v0.2.0 --> +* {integer} + 设置该属性使得当 server 连接数过多时拒绝连接。 一旦将一个 socket 发送给 [`child_process.fork()`][] 生成的子进程，就不推荐使用该选项。 diff --git a/net/socket_buffersize.md b/net/socket_buffersize.md index 0c5df058..ee2ec006 100644 --- a/net/socket_buffersize.md +++ b/net/socket_buffersize.md @@ -2,6 +2,8 @@ added: v0.3.8 --> +* {integer} + `net.Socket` 具有该属性，`socket.write()` 工作时需要。它可以帮助用户快速启动和运行。计算机（处理速度）不能总是跟上 socket 的写入速度 - 网络连接可能太慢了。 Node.js 内部将维护一个写入 socket 的数据队列，并在可能的时候将数据发送出去。（内部实现是对 socket 的文件描述符进行轮询其是否是可写状态。） 使用内部缓冲的结果是可能造成内存的增长。此属性显示当前即将被写入的缓冲的字符数。（字符串的数目大致等于即将被写入的字节，但缓冲可能包含字符串，而字符串是惰性编码的，所以实际的字节数是不知道的。） diff --git a/net/socket_bytesread.md b/net/socket_bytesread.md index 4f76bd0c..f1134314 100644 --- a/net/socket_bytesread.md +++ b/net/socket_bytesread.md @@ -2,5 +2,7 @@ added: v0.5.3 --> +* {integer} + 接收的字节数量。 diff --git a/net/socket_byteswritten.md b/net/socket_byteswritten.md index e71c20e7..de50a573 100644 --- a/net/socket_byteswritten.md +++ b/net/socket_byteswritten.md @@ -2,4 +2,6 @@ added: v0.5.3 --> +* {integer} + 发送的字节数量。 diff --git a/net/socket_connecting.md b/net/socket_connecting.md index 92b396db..ad2a853c 100644 --- a/net/socket_connecting.md +++ b/net/socket_connecting.md @@ -2,6 +2,8 @@ added: v6.1.0 --> +* {boolean} + 如果为 `true` 则 [`socket.connect(options[, connectListener])`][`socket.connect(options)`] 被调用但还未结束。 它将保持为真，直到 socket 连接，然后设置为 `false` 并触发 `'connect'` 事件。 注意，[`socket.connect(options[, connectListener])`][`socket.connect(options)`] 的回调是 `'connect'` 事件的监听器。 diff --git a/net/socket_localaddress.md b/net/socket_localaddress.md index f23e6156..2ed513a7 100644 --- a/net/socket_localaddress.md +++ b/net/socket_localaddress.md @@ -2,4 +2,6 @@ added: v0.9.6 --> +* {string} + 远程客户端连接的本地 IP 地址字符串。例如，一个服务端正在连接到 `'0.0.0.0'`，客户端连接到的是 `'192.168.1.1'`，则 `socket.localAddress` 的值是 `'192.168.1.1'`。 diff --git a/net/socket_localport.md b/net/socket_localport.md index 803b2104..cd77fd7c 100644 --- a/net/socket_localport.md +++ b/net/socket_localport.md @@ -2,5 +2,7 @@ added: v0.9.6 --> +* {integer} + 用数字表示的本地端口。例如 `80` 或 `21`。 diff --git a/net/socket_remoteaddress.md b/net/socket_remoteaddress.md index 6e78dd30..f650db85 100644 --- a/net/socket_remoteaddress.md +++ b/net/socket_remoteaddress.md @@ -2,4 +2,6 @@ added: v0.5.10 --> +* {string} + 用字符串表示的远程 IP 地址。例如 `'74.125.127.100'` 或 `'2001:4860:a005::68'`。如果 socket 被销毁了（如客户端已经失去连接）则其值为 `undefined`。 diff --git a/net/socket_remotefamily.md b/net/socket_remotefamily.md index 26e8fcef..ee0a125c 100644 --- a/net/socket_remotefamily.md +++ b/net/socket_remotefamily.md @@ -2,4 +2,6 @@ added: v0.11.14 --> +* {string} + 用字符串表示的远程 IP 协议族。`'IPv4'` 或 `'IPv6'`。 diff --git a/net/socket_remoteport.md b/net/socket_remoteport.md index 9431525c..d15b76c5 100644 --- a/net/socket_remoteport.md +++ b/net/socket_remoteport.md @@ -2,5 +2,7 @@ added: v0.5.10 --> +* {integer} + 用数字表示的远程端口。例如 `80` 或 `21`。 diff --git a/perf_hooks/performanceobserver_observe_options.md b/perf_hooks/performanceobserver_observe_options.md index d72a9c16..914badf5 100644 --- a/perf_hooks/performanceobserver_observe_options.md +++ b/perf_hooks/performanceobserver_observe_options.md @@ -1,6 +1,7 @@ + * `options` {Object} * `entryTypes` {string[]} An array of strings identifying the types of `PerformanceEntry` instances the observer is interested in. If not diff --git a/process/event_warning.md b/process/event_warning.md index 652c06e5..1839875f 100644 --- a/process/event_warning.md +++ b/process/event_warning.md @@ -26,7 +26,7 @@ process.on('warning', (warning) => { 下面的例子展示了当一个事件绑定了太多的监听器时，输出到`stderr`的告警。 -```txt +```console $ node > events.defaultMaxListeners = 1; > process.on('foo', () => {}); @@ -37,7 +37,7 @@ detected. 2 foo listeners added. Use emitter.setMaxListeners() to increase limit 与上述相反，如下例子关闭了默认的告警输出，并且给`'warning'`事件添加了一个定制的处理器。 -```txt +```console $ node --no-warnings > const p = process.on('warning', (warning) => console.warn('Do not do that!')); > events.defaultMaxListeners = 1; diff --git a/process/process_config.md b/process/process_config.md index 1612a791..723a8f05 100644 --- a/process/process_config.md +++ b/process/process_config.md @@ -21,7 +21,7 @@ added: v0.7.7 variables: { host_arch: 'x64', - napi_build_version: 4, + napi_build_version: 5, node_install_npm: 'true', node_prefix: '', node_shared_cares: 'false', diff --git a/process/process_hrtime_bigint.md b/process/process_hrtime_bigint.md index f1e20ddd..44613994 100644 --- a/process/process_hrtime_bigint.md +++ b/process/process_hrtime_bigint.md @@ -4,9 +4,9 @@ added: v10.7.0 * 返回: {bigint} -[`process.hrtime()`] 方法的 `bigint` 版本在 `bigint` 中返回当前的高精度实时。 +[`process.hrtime()`] 方法的 `bigint` 版本，返回当前的高精度实际时间（以纳秒为单位的 `bigint` 型）。 -与 [`process.hrtime()`] 不同，它不支持额外的 `time` 参数，因为差异可以直接通过减去两个 `bigint` 来计算。 +与 [`process.hrtime()`] 不同，它不支持额外的 `time` 参数，因为可以直接通过两个 `bigint` 相减来计算差异。 ```js const start = process.hrtime.bigint(); @@ -16,8 +16,8 @@ setTimeout(() => { const end = process.hrtime.bigint(); // 191052633396993n - console.log(`基准工具 ${end - start} 纳秒`); - // 基准工具 1154389282 纳秒 + console.log(`基准测试耗时 ${end - start} 纳秒`); + // 基准测试耗时 1154389282 纳秒 }, 1000); ``` diff --git a/process/process_resourceusage.md b/process/process_resourceusage.md index d88b8425..89fb6aac 100644 --- a/process/process_resourceusage.md +++ b/process/process_resourceusage.md @@ -5,45 +5,45 @@ added: v12.6.0 * Returns: {Object} the resource usage for the current process. All of these values come from the `uv_getrusage` call which returns a [`uv_rusage_t` struct][uv_rusage_t]. - * `userCPUTime` {integer} maps to `ru_utime` computed in microseconds. - It is the same value as [`process.cpuUsage().user`][process.cpuUsage]. - * `systemCPUTime` {integer} maps to `ru_stime` computed in microseconds. - It is the same value as [`process.cpuUsage().system`][process.cpuUsage]. - * `maxRSS` {integer} maps to `ru_maxrss` which is the maximum resident set - size used in kilobytes. - * `sharedMemorySize` {integer} maps to `ru_ixrss` but is not supported by - any platform. - * `unsharedDataSize` {integer} maps to `ru_idrss` but is not supported by - any platform. - * `unsharedStackSize` {integer} maps to `ru_isrss` but is not supported by - any platform. - * `minorPageFault` {integer} maps to `ru_minflt` which is the number of - minor page faults for the process, see - [this article for more details][wikipedia_minor_fault]. - * `majorPageFault` {integer} maps to `ru_majflt` which is the number of - major page faults for the process, see - [this article for more details][wikipedia_major_fault]. This field is not - supported on Windows. - * `swappedOut` {integer} maps to `ru_nswap` but is not supported by any - platform. - * `fsRead` {integer} maps to `ru_inblock` which is the number of times the - file system had to perform input. - * `fsWrite` {integer} maps to `ru_oublock` which is the number of times the - file system had to perform output. - * `ipcSent` {integer} maps to `ru_msgsnd` but is not supported by any - platform. - * `ipcReceived` {integer} maps to `ru_msgrcv` but is not supported by any - platform. - * `signalsCount` {integer} maps to `ru_nsignals` but is not supported by any - platform. - * `voluntaryContextSwitches` {integer} maps to `ru_nvcsw` which is the - number of times a CPU context switch resulted due to a process voluntarily - giving up the processor before its time slice was completed (usually to - await availability of a resource). This field is not supported on Windows. - * `involuntaryContextSwitches` {integer} maps to `ru_nivcsw` which is the - number of times a CPU context switch resulted due to a higher priority - process becoming runnable or because the current process exceeded its - time slice. This field is not supported on Windows. + * `userCPUTime` {integer} maps to `ru_utime` computed in microseconds. + It is the same value as [`process.cpuUsage().user`][process.cpuUsage]. + * `systemCPUTime` {integer} maps to `ru_stime` computed in microseconds. + It is the same value as [`process.cpuUsage().system`][process.cpuUsage]. + * `maxRSS` {integer} maps to `ru_maxrss` which is the maximum resident set + size used in kilobytes. + * `sharedMemorySize` {integer} maps to `ru_ixrss` but is not supported by + any platform. + * `unsharedDataSize` {integer} maps to `ru_idrss` but is not supported by + any platform. + * `unsharedStackSize` {integer} maps to `ru_isrss` but is not supported by + any platform. + * `minorPageFault` {integer} maps to `ru_minflt` which is the number of + minor page faults for the process, see + [this article for more details][wikipedia_minor_fault]. + * `majorPageFault` {integer} maps to `ru_majflt` which is the number of + major page faults for the process, see + [this article for more details][wikipedia_major_fault]. This field is not + supported on Windows. + * `swappedOut` {integer} maps to `ru_nswap` but is not supported by any + platform. + * `fsRead` {integer} maps to `ru_inblock` which is the number of times the + file system had to perform input. + * `fsWrite` {integer} maps to `ru_oublock` which is the number of times the + file system had to perform output. + * `ipcSent` {integer} maps to `ru_msgsnd` but is not supported by any + platform. + * `ipcReceived` {integer} maps to `ru_msgrcv` but is not supported by any + platform. + * `signalsCount` {integer} maps to `ru_nsignals` but is not supported by any + platform. + * `voluntaryContextSwitches` {integer} maps to `ru_nvcsw` which is the + number of times a CPU context switch resulted due to a process voluntarily + giving up the processor before its time slice was completed (usually to + await availability of a resource). This field is not supported on Windows. + * `involuntaryContextSwitches` {integer} maps to `ru_nivcsw` which is the + number of times a CPU context switch resulted due to a higher priority + process becoming runnable or because the current process exceeded its + time slice. This field is not supported on Windows. ```js console.log(process.resourceUsage()); diff --git a/process/process_throwdeprecation.md b/process/process_throwdeprecation.md index 0b14c925..a51b1980 100644 --- a/process/process_throwdeprecation.md +++ b/process/process_throwdeprecation.md @@ -4,5 +4,24 @@ added: v0.9.12 * {boolean} -`process.throwDeprecation` 属性表示 `--throw-deprecation` 标记是否被设置到当前 Node.js 进程上。 -请查看 [`'warning'` 事件][process_warning]和 [`emitWarning()` 方法][process_emit_warning]的文档来获取这个标记行为的更多信息。 +`process.throwDeprecation` 的初始值表明是否在当前的 Node.js 进程上设置了 `--throw-deprecation` 标志。 +`process.throwDeprecation` 是可变的，因此可以在运行时设置废弃警告是否应该导致错误。 +有关更多信息，参见 [`'warning'` 事件][process_warning]和 [`emitWarning()` 方法][process_emit_warning] 的文档。 + +```console +$ node --throw-deprecation -p "process.throwDeprecation" +true +$ node -p "process.throwDeprecation" +undefined +$ node +> process.emitWarning('test', 'DeprecationWarning'); +undefined +> (node:26598) DeprecationWarning: test +> process.throwDeprecation = true; +true +> process.emitWarning('test', 'DeprecationWarning'); +抛出: +{ [DeprecationWarning: test] name: 'DeprecationWarning' } +``` + + diff --git a/repl/replserver_definecommand_keyword_cmd.md b/repl/replserver_definecommand_keyword_cmd.md index 4979c25b..0b80991b 100644 --- a/repl/replserver_definecommand_keyword_cmd.md +++ b/repl/replserver_definecommand_keyword_cmd.md @@ -34,7 +34,7 @@ replServer.defineCommand('saybye', function saybye() { 在 REPL 实例中使用新的命令： -```txt +```console > .sayhello Node.js中文网 你好，Node.js中文网！ > .saybye diff --git a/stream/event_readable.md b/stream/event_readable.md index 2e99faa6..c19006a2 100644 --- a/stream/event_readable.md +++ b/stream/event_readable.md @@ -45,7 +45,7 @@ rr.on('end', () => { 运行上面的脚本输出如下： -```txt +```console $ node test.js 读取的数据: null 结束 diff --git a/stream/implementing_a_writable_stream.md b/stream/implementing_a_writable_stream.md index 174de6b3..d0d06203 100644 --- a/stream/implementing_a_writable_stream.md +++ b/stream/implementing_a_writable_stream.md @@ -1,5 +1,5 @@ -`stream.Writable` 类可用于实现可写流。 +`stream.Writable` 类可用于实现 [`Writable`] 流。 -自定义的可写流必须调用 `new stream.Writable([options])` 构造函数并实现 `writable._write()` 方法，`writable._writev()` 方法是可选的。 +自定义的 `Writable` 流必须调用 `new stream.Writable([options])` 构造函数并实现 `writable._write()` 和/或 `writable._writev()` 方法。 diff --git a/stream/piping_to_writable_streams_from_async_iterators.md b/stream/piping_to_writable_streams_from_async_iterators.md index 8d25df92..6f53a9e6 100644 --- a/stream/piping_to_writable_streams_from_async_iterators.md +++ b/stream/piping_to_writable_streams_from_async_iterators.md @@ -1,8 +1,9 @@ -在从异步迭代器写入可写流的场景中，确保正确处理背压和错误非常重要。 +在从异步迭代器写入可写流的场景中，确保正确地处理背压和错误非常重要。 ```js const { once } = require('events'); +const finished = util.promisify(stream.finished); const writable = fs.createWriteStream('./file'); @@ -14,16 +15,18 @@ const writable = fs.createWriteStream('./file'); } writable.end(); // 确保完成没有错误。 - await once(writable, 'finish'); + await finished(writable); })(); ``` -在以上示例中，两个 `once()` 监听器会捕获并抛出可写流上的错误，因 `once()` 也会处理 `'error'` 事件。 +在上面的示例中，`once()` 监听器会为 `'drain'` 事件捕获并抛出 `write()` 上的错误，因为 `once()` 也会处理 `'error'` 事件。 +为了确保写入流的完成且没有错误，使用上面的 `finished()` 方法比使用 `'finish'` 事件的 `once()` 监听器更为安全。 +在某些情况下，`'finish'` 之后可写流可能会触发 `'error'` 事件，并且 `once()` 将会在处理 `'finish'` 事件时释放 `'error'` 处理程序，这可能导致未处理的错误。 -或者，可读流可以用 `Readable.from()` 封装，然后通过 `.pipe()` 传送： +另外，可读流可以用 `Readable.from()` 封装，然后通过 `.pipe()` 传送： ```js -const { once } = require('events'); +const finished = util.promisify(stream.finished); const writable = fs.createWriteStream('./file'); @@ -31,7 +34,20 @@ const writable = fs.createWriteStream('./file'); const readable = Readable.from(iterator); readable.pipe(writable); // 确保完成没有错误。 - await once(writable, 'finish'); + await finished(writable); +})(); +``` + +或者，使用 `stream.pipeline()` 传送流： + +```js +const pipeline = util.promisify(stream.pipeline); + +const writable = fs.createWriteStream('./file'); + +(async function() { + const readable = Readable.from(iterator); + await pipeline(readable, writable); })(); ``` diff --git a/stream/readable_destroy_error.md b/stream/readable_destroy_error.md index 445a8bf5..6c7477ec 100644 --- a/stream/readable_destroy_error.md +++ b/stream/readable_destroy_error.md @@ -2,11 +2,11 @@ added: v8.0.0 --> -* `error` {Error} 传给 `'error'` 事件的错误对象。 +* `error` {Error} 将会在 `'error'` 事件中作为负载传入的错误。 * 返回: {this} 销毁流。 -可选地触发 `'error'` 事件，并触发 `'close'` 事件除非 `emitClose` 设置为 `false`。 -在此调用之后，可读流将释放任何内部资源，并且将忽略对 `push()` 的后续调用。 -实现者不应该重写此方法，而是实现 [`readable._destroy()`][readable-_destroy]。 +可选地触发 `'error'` 事件，并触发 `'close'` 事件（除非将 `emitClose` 设置为 `false`）。 +在此调用之后，可读流将会释放所有内部的资源，并且将会忽略对 `push()` 的后续调用。 +实现者不应该重写此方法，而应该实现 [`readable._destroy()`][readable-_destroy]。 diff --git a/stream/readable_readableflowing.md b/stream/readable_readableflowing.md new file mode 100644 index 00000000..f1a819a6 --- /dev/null +++ b/stream/readable_readableflowing.md @@ -0,0 +1,9 @@ + + +* {boolean} + +This property reflects the current state of a `Readable` stream as described +in the [Stream Three States][] section. + diff --git a/stream/stream_finished_stream_options_callback.md b/stream/stream_finished_stream_options_callback.md index e53d25eb..60e7279a 100644 --- a/stream/stream_finished_stream_options_callback.md +++ b/stream/stream_finished_stream_options_callback.md @@ -2,14 +2,15 @@ added: v10.0.0 --> -* `stream` {Stream} 可读流或可写流。 +* `stream` {Stream} 可读和/或可写流。 * `options` {Object} * `error` {boolean} 如果设置为 `false`，则对 `emit('error', err)` 的调用不会被视为已完成。 **默认值**: `true`。 * `readable` {boolean} 当设置为 `false` 时，即使流可能仍然可读，当流结束时也将会调用回调。**默认值**: `true`。 * `writable` {boolean} 当设置为 `false` 时，即使流可能仍然可写，当流结束时也将会调用回调。**默认值**: `true`。 * `callback` {Function} 带有可选错误参数的回调函数。 +* 返回: {Function} 清理函数，它会移除所有已注册的监听器。 -当流不再可读、可写、或遇到错误、或过早关闭事件时，该函数会获得通知。 +当流不再可读、可写、或遇到错误、或过早关闭事件时，则该函数会获得通知。 ```js const { finished } = require('stream'); @@ -18,18 +19,18 @@ const rs = fs.createReadStream('archive.tar'); finished(rs, (err) => { if (err) { - console.error('流发生错误', err); + console.error('流读取失败', err); } else { - console.log('流已读取完'); + console.log('流已完成读取'); } }); -rs.resume(); // 开始读取流。 +rs.resume(); // 排空流。 ``` -主要用于处理流被提前销毁（如 HTTP 请求被中止）等异常情况，此时流不会触发 `'end'` 或 `'finish'` 事件。 +在错误处理场景中特别有用，该场景中的流会被过早地销毁（例如被终止的 HTTP 请求），并且不会触发 `'end'` 或 `'finish'` 事件。 -`finished` 接口也可以 Promise 化： +`finished` API 也可以 promise 化： ```js const finished = util.promisify(stream.finished); @@ -38,10 +39,21 @@ const rs = fs.createReadStream('archive.tar'); async function run() { await finished(rs); - console.log('流已读取完'); + console.log('流已完成读取'); } run().catch(console.error); -rs.resume(); // 开始读取流。 +rs.resume(); // 排空流。 +``` + +在调用 `callback` 之后，`stream.finished()` 会留下悬挂的事件监听器（特别是 `'error'`、`'end'`、`'finish'` 和 `'close'`）。 +这样做的原因是，意外的 `'error'` 事件（由于错误的流实现）不会导致意外的崩溃。 +如果这是不想要的行为，则需要在回调中调用返回的清理函数： + +```js +const cleanup = finished(...streams, (err) => { + cleanup(); + // ... +}); ``` diff --git a/stream/stream_pipeline_streams_callback.md b/stream/stream_pipeline_streams_callback.md index 8ed264b1..bd25575e 100644 --- a/stream/stream_pipeline_streams_callback.md +++ b/stream/stream_pipeline_streams_callback.md @@ -2,19 +2,20 @@ added: v10.0.0 --> -* `...streams` {Stream} 要用管道连接的两个或多个流。 -* `callback` {Function} 在管道完全完成时调用。 +* `...streams` {Stream} 要使用管道传送的两个或多个流。 +* `callback` {Function} 当管道完全地完成时调用。 * `err` {Error} -使用管道连接多个流，并传递错误与完成清理工作，当管道连接完成时通知回调函数。 +一个模块方法，使用管道传送多个流，并转发错误和正确地清理，当管道完成时提供回调。 ```js const { pipeline } = require('stream'); const fs = require('fs'); const zlib = require('zlib'); -// 使用 pipeline 接口连接多个流，并在管道连接完成时获得通知。 -// 使用 pipeline 可以高效地压缩一个可能很大的 tar 文件： +// 使用 pipeline API 轻松地将一系列的流通过管道一起传送，并在管道完全地完成时获得通知。 + +// 使用 pipeline 可以有效地压缩一个可能很大的 tar 文件： pipeline( fs.createReadStream('archive.tar'), @@ -22,15 +23,15 @@ pipeline( fs.createWriteStream('archive.tar.gz'), (err) => { if (err) { - console.error('管道连接失败', err); + console.error('管道传送失败', err); } else { - console.log('管道连接成功'); + console.log('管道传送成功'); } } ); ``` -`pipeline` 接口也可以 Promise 化： +`pipeline` API 也可以 promise 化： ```js const pipeline = util.promisify(stream.pipeline); @@ -41,9 +42,12 @@ async function run() { zlib.createGzip(), fs.createWriteStream('archive.tar.gz') ); - console.log('管道连接成功'); + console.log('管道传送成功'); } run().catch(console.error); ``` +在调用 `callback` 之后，`stream.pipeline()` 会将悬挂的事件监听器留在流上。 +在失败后重新使用流的情况下，这可能导致事件监听器泄漏和误吞的错误。 + diff --git a/stream/transform_destroy_error.md b/stream/transform_destroy_error.md index bb4d4ecc..e025110c 100644 --- a/stream/transform_destroy_error.md +++ b/stream/transform_destroy_error.md @@ -6,6 +6,6 @@ added: v8.0.0 销毁流，并可选地触发 `'error'` 事件。 调用该方法后，transform 流会释放全部内部资源。 -实现者不要重写该方法，而应该实现 [`readable._destroy()`][readable-_destroy]。 +实现者不应该重写此方法，而应该实现 [`readable._destroy()`][readable-_destroy]。 `Transform` 流的 `_destroy()` 方法的默认实现会触发 `'close'` 事件，除非 `emitClose` 被设置为 `false`。 diff --git a/stream/writable_destroy_error.md b/stream/writable_destroy_error.md index e7f37270..e6b92df0 100644 --- a/stream/writable_destroy_error.md +++ b/stream/writable_destroy_error.md @@ -6,10 +6,10 @@ added: v8.0.0 * 返回: {this} 销毁流。 -可选地触发 `'error'`，并且触发 `'close'` 事件触发 `emitClose` 设置为 `false`。 +可选地触发 `'error'`，并且触发 `'close'` 事件（除非将 `emitClose` 设置为 `false`）。 调用该方法后，可写流就结束了，之后再调用 `write()` 或 `end()` 都会导致 `ERR_STREAM_DESTROYED` 错误。 这是销毁流的最直接的方式。 前面对 `write()` 的调用可能没有耗尽，并且可能触发 `ERR_STREAM_DESTROYED` 错误。 如果数据在关闭之前应该刷新，则使用 `end()` 而不是销毁，或者在销毁流之前等待 `'drain'` 事件。 -实现流时不应该重写这个方法，而是重写 [`writable._destroy()`][writable-_destroy]。 +实现者不应该重写此方法，而应该实现 [`writable._destroy()`][writable-_destroy]。 diff --git a/stream/writable_write_chunk_encoding_callback_1.md b/stream/writable_write_chunk_encoding_callback_1.md index 5aabbe86..5354f0c2 100644 --- a/stream/writable_write_chunk_encoding_callback_1.md +++ b/stream/writable_write_chunk_encoding_callback_1.md @@ -1,3 +1,9 @@ + * `chunk` {Buffer|string|any} 要写入的 `Buffer`，从传给 [`stream.write()`][stream-write] 的 `string` 转换而来。 如果流的 `decodeStrings` 选项为 `false` 或者流在对象模式下运行，则数据块将不会被转换，并且将是传给 [`stream.write()`][stream-write] 的任何内容。 @@ -5,7 +11,7 @@ 如果 `chunk` 是 `Buffer` 或者流处于对象模式，则无视该选项。 * `callback` {Function} 当数据块被处理完成后的回调函数。 -所有可写流的实现必须提供 [`writable._write()`][stream-_write] 方法将数据发送到底层资源。 +所有可写流的实现必须提供 [`writable._write()`][stream-_write] 和/或 [`writable._writev()`][stream-_writev] 方法将数据发送到底层资源。 [`Transform`] 流会提供自身实现的 [`writable._write()`][stream-_write]。 diff --git a/tls/certificate_object.md b/tls/certificate_object.md index 49b2770c..67387d59 100644 --- a/tls/certificate_object.md +++ b/tls/certificate_object.md @@ -37,6 +37,7 @@ The certificate may contain information about the public key, depending on the key type. For RSA keys, the following properties may be defined: + * `bits` {number} The RSA bit size. Example: `1024`. * `exponent` {string} The RSA exponent, as a string in hexadecimal number notation. Example: `'0x010001'`. @@ -45,6 +46,7 @@ For RSA keys, the following properties may be defined: * `pubkey` {Buffer} The public key. For EC keys, the following properties may be defined: + * `pubkey` {Buffer} The public key. * `bits` {number} The key size in bits. Example: `256`. * `asn1Curve` {string} (Optional) The ASN.1 name of the OID of the elliptic diff --git a/tls/tls_createsecurecontext_options.md b/tls/tls_createsecurecontext_options.md index b8c86a70..b8aca6be 100644 --- a/tls/tls_createsecurecontext_options.md +++ b/tls/tls_createsecurecontext_options.md @@ -1,6 +1,10 @@ + +* Returns: {Array} List of signature algorithms shared between the server and +the client in the order of decreasing preference. + +See + +for more information. + diff --git a/url/url_format_urlobject.md b/url/url_format_urlobject.md index a9de8dab..f8e10067 100644 --- a/url/url_format_urlobject.md +++ b/url/url_format_urlobject.md @@ -46,9 +46,9 @@ The formatting process operates as follows: colon (`:`) character, the literal string `:` will be appended to `result`. * If either of the following conditions is true, then the literal string `//` will be appended to `result`: - * `urlObject.slashes` property is true; - * `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or - `file`; + * `urlObject.slashes` property is true; + * `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or + `file`; * If the value of the `urlObject.auth` property is truthy, and either `urlObject.host` or `urlObject.hostname` are not `undefined`, the value of `urlObject.auth` will be coerced into a string and appended to `result` diff --git a/util/textencoder_encodeinto_src_dest.md b/util/textencoder_encodeinto_src_dest.md new file mode 100644 index 00000000..5f45e57b --- /dev/null +++ b/util/textencoder_encodeinto_src_dest.md @@ -0,0 +1,17 @@ + +* `src` {string} The text to encode. +* `dest` {Uint8Array} The array to hold the encode result. +* Returns: {Object} + * `read` {number} The read Unicode code units of src. + * `written` {number} The written UTF-8 bytes of dest. + +UTF-8 encodes the `src` string to the `dest` Uint8Array and returns an object +containing the read Unicode code units and written UTF-8 bytes. + +```js +const encoder = new TextEncoder(); +const src = 'this is some data'; +const dest = new Uint8Array(10); +const { read, written } = encoder.encodeInto(src, dest); +``` + diff --git a/util/util_extend_target_source.md b/util/util_extend_target_source.md index 8f073a47..637812b3 100644 --- a/util/util_extend_target_source.md +++ b/util/util_extend_target_source.md @@ -2,6 +2,7 @@ added: v0.7.5 deprecated: v6.0.0 --> + * `target` {Object} * `source` {Object} diff --git a/util/util_format_format_args.md b/util/util_format_format_args.md index fbd6eb66..c02acc60 100644 --- a/util/util_format_format_args.md +++ b/util/util_format_format_args.md @@ -1,6 +1,9 @@ -> Stability: 1 - Experimental +> Stability: 2 - Stable The `worker_threads` module enables the use of threads that execute JavaScript in parallel. To access it: diff --git a/zlib/for_brotli_based_streams.md b/zlib/for_brotli_based_streams.md index b9e40938..7f765960 100644 --- a/zlib/for_brotli_based_streams.md +++ b/zlib/for_brotli_based_streams.md @@ -2,8 +2,8 @@ There are equivalents to the zlib options for Brotli-based streams, although these options have different ranges than the zlib ones: -- zlib’s `level` option matches Brotli’s `BROTLI_PARAM_QUALITY` option. -- zlib’s `windowBits` option matches Brotli’s `BROTLI_PARAM_LGWIN` option. +* zlib’s `level` option matches Brotli’s `BROTLI_PARAM_QUALITY` option. +* zlib’s `windowBits` option matches Brotli’s `BROTLI_PARAM_LGWIN` option. See [below][Brotli parameters] for more details on Brotli-specific options. diff --git a/zlib/zlib_brotlicompress_buffer_options_callback.md b/zlib/zlib_brotlicompress_buffer_options_callback.md index 8d924ede..4ec7db97 100644 --- a/zlib/zlib_brotlicompress_buffer_options_callback.md +++ b/zlib/zlib_brotlicompress_buffer_options_callback.md @@ -1,6 +1,7 @@ + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {brotli options} * `callback` {Function} diff --git a/zlib/zlib_brotlicompresssync_buffer_options.md b/zlib/zlib_brotlicompresssync_buffer_options.md index e5da671e..b36510a0 100644 --- a/zlib/zlib_brotlicompresssync_buffer_options.md +++ b/zlib/zlib_brotlicompresssync_buffer_options.md @@ -1,6 +1,7 @@ + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {brotli options} diff --git a/zlib/zlib_brotlidecompress_buffer_options_callback.md b/zlib/zlib_brotlidecompress_buffer_options_callback.md index 8d924ede..4ec7db97 100644 --- a/zlib/zlib_brotlidecompress_buffer_options_callback.md +++ b/zlib/zlib_brotlidecompress_buffer_options_callback.md @@ -1,6 +1,7 @@ + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {brotli options} * `callback` {Function} diff --git a/zlib/zlib_brotlidecompresssync_buffer_options.md b/zlib/zlib_brotlidecompresssync_buffer_options.md index 791d305d..f07efc7e 100644 --- a/zlib/zlib_brotlidecompresssync_buffer_options.md +++ b/zlib/zlib_brotlidecompresssync_buffer_options.md @@ -1,6 +1,7 @@ + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {brotli options} diff --git a/zlib/zlib_deflate_buffer_options_callback.md b/zlib/zlib_deflate_buffer_options_callback.md index e23b60db..788d1d68 100644 --- a/zlib/zlib_deflate_buffer_options_callback.md +++ b/zlib/zlib_deflate_buffer_options_callback.md @@ -11,6 +11,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/12001 description: The `buffer` parameter can be an `Uint8Array` now. --> + * `buffer` {Buffer|TypedArray|DataView|ArrayBuffer|string} * `options` {zlib options} * `callback` {Function}