Merge pull request #1011 from neon-bindings/kv/1.0

Release 1.0.0

AUTHORS.md

@@ -19,6 +19,7 @@ Neon owes its existence to the contributions of these fine people.
 * [ComplexSpaces](https://github.com/complexspaces)
 * [Nathaniel Daniel](https://github.com/adumbidiot)
 * [John Darrington](https://github.com/DnOberon)
+* [erics118](https://github.com/erics118)
 * [Joey Ezechiëls](https://github.com/jjpe)
 * [Ryan Fitzgerald](https://github.com/rf-)
 * [Cory Forsyth](https://github.com/bantic)
@@ -74,4 +75,5 @@ Neon owes its existence to the contributions of these fine people.
 * [Chi Wang](https://github.com/patr0nus)
 * [wangcong](https://github.com/king6cong)
 * [Amila Welihinda](https://github.com/amilajack)
+* [xyloflake](https://github.com/xyloflake)
 * [Felix Yan](https://github.com/felixonmars)

README.md

@@ -25,12 +25,12 @@ Neon!
 See our [Neon fundamentals docs](https://neon-bindings.com/docs/intro) and
 our [API docs](https://docs.rs/neon/latest/neon).
 
-## Neon 0.10 Migration Guide
+## Neon 1.0.0 Migration Guide
 
-The latest version of Neon, 0.10, includes a few small breaking changes in order to clean up and improve the usability of our APIs.
+The latest version of Neon, 1.0.0, includes several breaking changes in order to fix unsoundness, improve consistency, and add features.
 
-**Read the new [migration guide](https://github.com/neon-bindings/neon/blob/main/doc/MIGRATION_GUIDE_0.10.md)** to learn how to port your 
-Neon projects to 0.10!
+**Read the new [migration guide](doc/MIGRATION_GUIDE_1.0.0.md)** to learn how to port your 
+Neon projects to 1.0.0!
 
 ## Platform Support
 

RELEASES.md

@@ -1,3 +1,31 @@
+# Version 1.0.0
+
+## Commitment to Compatibility
+
+The release of Neon 1.0 marks our commitment to backwards-compatibility: starting with 1.0.0, Neon users can be confident that future **upgrades to Neon 1.x versions should never require code changes** (with the possible exception of safety bugfixes, which we expect to be rare). We also do not anticipate releasing new major versions often and do not have any plans to do so for now.
+
+## Breaking Changes
+
+* Remove the generic parameter from `JsFunction` (https://github.com/neon-bindings/neon/pull/989)
+* `JsArray::new` takes a `usize` instead of a `u32` (https://github.com/neon-bindings/neon/pull/988)
+* Made `Context::global` read a key and added `Context::global_object` (https://github.com/neon-bindings/neon/pull/987)
+* Deprecated feature flags were removed
+
+## Bug fixes
+
+* Fix `unhandledRejection` with `JsPromise::to_future` (https://github.com/neon-bindings/neon/pull/1008)
+* Typo in `cargo-cp-artifact` help (https://github.com/neon-bindings/neon/pull/998)
+* Typo in README (https://github.com/neon-bindings/neon/pull/1012)
+
+## Other
+
+https://github.com/neon-bindings/neon/pull/1010
+
+* Relaxed error behavior on missing Node-API symbols. Neon will panic on first use instead of aborting the process at module load time.
+* Bumped dependency versions
+* Changed to edition 2021
+* Updated support matrix to Node 18, 20, and 21
+
 # Version 1.0.0-alpha.4
 
 Patch to enable new features flags in docs.rs.

crates/neon-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "neon-macros"
-version = "1.0.0-alpha.4"
+version = "1.0.0"
 authors = ["Dave Herman <[email protected]>"]
 description = "Procedural macros supporting Neon"
 repository = "https://github.com/neon-bindings/neon"

crates/neon/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "neon"
-version = "1.0.0-alpha.4"
+version = "1.0.0"
 authors = ["Dave Herman <[email protected]>"]
 description = "A safe abstraction layer for Node.js."
 readme = "../../README.md"
@@ -27,7 +27,7 @@ libloading = "0.8.1"
 semver = "1.0.20"
 smallvec = "1.11.2"
 once_cell = "1.18.0"
-neon-macros = { version = "=1.0.0-alpha.4", path = "../neon-macros" }
+neon-macros = { version = "=1.0.0", path = "../neon-macros" }
 aquamarine = { version = "0.3.2", optional = true }
 easy-cast = { version = "0.5.2", optional = true }
 doc-comment = { version = "0.3.3", optional = true }
@@ -40,7 +40,7 @@ features = ["sync"]
 optional = true
 
 [features]
-default = ["napi-1"]
+default = ["napi-8"]
 
 # Enable the creation of external binary buffers. This is disabled by default
 # since these APIs fail at runtime in environments that enable the V8 memory
@@ -75,17 +75,6 @@ napi-8 = ["napi-7", "getrandom"]
 napi-latest = ["napi-8"]
 napi-experimental = ["napi-8"]
 
-# DEPRECATED: These perform no action and will be removed in 1.0
-try-catch-api = []
-channel-api = []
-event-queue-api = []
-promise-api = []
-task-api = []
-
-# Feature flag to include procedural macros
-# DEPRECATED: This is always enabled and should be removed.
-proc-macros = []
-
 # Enables the optional dependencies that are only used for generating the API docs.
 doc-dependencies = ["doc-comment", "aquamarine", "easy-cast"]
 

crates/neon/src/context/mod.rs

@@ -284,10 +284,6 @@ pub trait Context<'a>: ContextInternal<'a> {
         }))
     }
 
-    #[cfg_attr(
-        feature = "try-catch-api",
-        deprecated = "`try-catch-api` feature has no impact and may be removed"
-    )]
     fn try_catch<T, F>(&mut self, f: F) -> Result<T, Handle<'a, JsValue>>
     where
         F: FnOnce(&mut Self) -> NeonResult<T>,
@@ -457,14 +453,6 @@ pub trait Context<'a>: ContextInternal<'a> {
     }
 
     #[cfg(feature = "napi-4")]
-    #[cfg_attr(
-        feature = "channel-api",
-        deprecated = "`channel-api` feature has no impact and may be removed"
-    )]
-    #[cfg_attr(
-        all(not(feature = "channel-api"), feature = "event-queue-api"),
-        deprecated = "`event-queue-api` feature has no impact and may be removed"
-    )]
     #[cfg_attr(docsrs, doc(cfg(feature = "napi-4")))]
     /// Returns an unbounded channel for scheduling events to be executed on the JavaScript thread.
     ///
@@ -480,10 +468,6 @@ pub trait Context<'a>: ContextInternal<'a> {
         channel
     }
 
-    #[cfg_attr(
-        feature = "promise-api",
-        deprecated = "`promise-api` feature has no impact and may be removed"
-    )]
     /// Creates a [`Deferred`] and [`JsPromise`] pair. The [`Deferred`] handle can be
     /// used to resolve or reject the [`JsPromise`].
     ///
@@ -502,10 +486,6 @@ pub trait Context<'a>: ContextInternal<'a> {
         JsPromise::new(self)
     }
 
-    #[cfg_attr(
-        feature = "task-api",
-        deprecated = "`task-api` feature has no impact and may be removed"
-    )]
     /// Creates a [`TaskBuilder`] which can be used to schedule the `execute`
     /// callback to asynchronously execute on the
     /// [Node worker pool](https://nodejs.org/en/docs/guides/dont-block-the-event-loop/).

crates/neon/src/event/channel.rs

@@ -90,14 +90,6 @@ type Callback = Box<dyn FnOnce(Env) + Send + 'static>;
 ///     Ok(cx.undefined())
 /// }
 /// ```
-#[cfg_attr(
-    feature = "channel-api",
-    deprecated = "`channel-api` feature has no impact and may be removed"
-)]
-#[cfg_attr(
-    all(not(feature = "channel-api"), feature = "event-queue-api"),
-    deprecated = "`event-queue-api` feature has no impact and may be removed"
-)]
 #[cfg_attr(docsrs, doc(cfg(feature = "napi-4")))]
 pub struct Channel {
     state: Arc<ChannelState>,

crates/neon/src/event/task.rs

@@ -8,10 +8,6 @@ use crate::{
     types::{Deferred, JsPromise, Value},
 };
 
-#[cfg_attr(
-    feature = "task-api",
-    deprecated = "`task-api` feature has no impact and may be removed"
-)]
 /// Node asynchronous task builder
 ///
 /// ```

crates/neon/src/sys/bindings/functions.rs

@@ -437,21 +437,36 @@ pub(crate) unsafe fn load(env: Env) -> Result<(), libloading::Error> {
 
     // This never fail since `get_version` is in N-API Version 1 and the module will fail
     // with `Error: Module did not self-register` if N-API does not exist.
-    let version = get_version(&host, env).expect("Failed to find N-API version");
+    let actual_version = get_version(&host, env).expect("Failed to find N-API version");
 
-    napi1::load(&host, version, 1);
+    let expected_version = match () {
+        _ if cfg!(feature = "napi-8") => 8,
+        _ if cfg!(feature = "napi-7") => 7,
+        _ if cfg!(feature = "napi-6") => 6,
+        _ if cfg!(feature = "napi-5") => 5,
+        _ if cfg!(feature = "napi-4") => 4,
+        _ if cfg!(feature = "napi-3") => 3,
+        _ if cfg!(feature = "napi-2") => 2,
+        _ => 1,
+    };
+
+    if actual_version < expected_version {
+        eprintln!("Minimum required Node-API version {expected_version}, found {actual_version}.\n\nSee the Node-API support matrix for more details: https://nodejs.org/api/n-api.html#node-api-version-matrix");
+    }
+
+    napi1::load(&host);
 
     #[cfg(feature = "napi-4")]
-    napi4::load(&host, version, 4);
+    napi4::load(&host);
 
     #[cfg(feature = "napi-5")]
-    napi5::load(&host, version, 5);
+    napi5::load(&host);
 
     #[cfg(feature = "napi-6")]
-    napi6::load(&host, version, 6);
+    napi6::load(&host);
 
     #[cfg(feature = "napi-8")]
-    napi8::load(&host, version, 8);
+    napi8::load(&host);
 
     Ok(())
 }

crates/neon/src/sys/bindings/mod.rs

@@ -137,18 +137,7 @@ macro_rules! generate {
             }
         };
 
-        pub(super) unsafe fn load(
-            host: &libloading::Library,
-            actual_napi_version: u32,
-            expected_napi_version: u32,
-        ) {
-            assert!(
-                actual_napi_version >= expected_napi_version,
-                "Minimum required Node-API version {}, found {}.",
-                expected_napi_version,
-                actual_napi_version,
-            );
-
+        pub(super) unsafe fn load(host: &libloading::Library) {
             let print_warn = |err| eprintln!("WARN: {}", err);
 
             NAPI = Napi {

crates/neon/src/types_impl/promise.rs

@@ -45,10 +45,6 @@ const BOUNDARY: FailureBoundary = FailureBoundary {
 
 #[derive(Debug)]
 #[repr(transparent)]
-#[cfg_attr(
-    feature = "promise-api",
-    deprecated = "`promise-api` feature has no impact and may be removed"
-)]
 /// The type of JavaScript
 /// [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
 /// objects.

doc/MIGRATION_GUIDE_1.0.0.md

@@ -0,0 +1,110 @@
+# Neon 1.0.0 Migration Guide
+
+> **Note:** This migration guide assumes a project is using Neon 0.10 without Node-API backend. If using an older version or the legacy backend, see the [previous migration guide](MIGRATION_GUIDE_0.10.md). 
+
+The Neon 1.0 has stabilized and brings a more consistent and ergonomic API. There are a few (minor) breaking changes and this guide will help walk through them! 
+
+## Removed Traits
+
+A few traits have been removed because they were either redundant or only used for features that no longer exist.
+
+### `Managed`
+
+The `Managed` trait marked values that were _managed_ by the JavaScript VM. It was redundant with the `Value` trait. Trait bounds referencing `Managed` may be either removed or replaced with `Value`.
+
+#### Before
+
+```rust
+fn example<V>(h: Handle<V>)
+where
+    V: Managed,
+{
+}
+```
+
+#### After
+
+```rust
+fn example<V>(h: Handle<V>)
+where
+    V: Value,
+{
+}
+```
+
+### `CallContext`, `This`, and `T` in `JsFunction<T>`
+
+The `This` trait marked values for `cx.this()` in `JsFunction`. However, it was not type checked and could result in a panic at runtime. Instead, `cx.this()` always returns a `JsValue`. Since, `JsFunction`'s `T` parameter had a default, in many cases no changes are necessary. In some cases, the `T` parameter will need to be removed and a `downcast` added.
+
+#### Before
+
+```rust
+// `CallContext<JsObject>` is equivalent to `FunctionContext`
+fn example(mut cx: CallContext<JsObject>) -> JsResult<JsUndefined> {
+    let a = cx.this().get::<JsValue, _, _>(&mut cx, "a")?;
+
+    Ok(cx.undefined())
+}
+```
+
+#### After
+
+```rust
+fn example(mut cx: FunctionContext) -> JsResult<JsUndefined> {
+    let a = cx.this::<JsObject>()?.get::<JsValue, _, _>(&mut cx, "a")?;
+
+    Ok(cx.undefined())
+}
+```
+
+### `JsResultExt`
+
+The `JsResultExt` trait provided a `.or_throw(&mut cx)` to allow converting a Rust error into a JavaScript exception. However, it required `T: Value`. It has been replaced with a more generic `ResultExt` trait. Most usages only require replacing `JsResultExt` with `ResultExt`. In some cases, an additional `T: Value` bound will need to be added or removed.
+
+#### Before
+
+```rust
+use neon::result::JsResultExt;
+```
+
+#### After
+
+```rust
+use neon::result::ResultExt;
+```
+
+## `usize` indexes and lengths
+
+Neon inconsistently used `u32`, `usize`, and sometimes even `i32` for indexes and lengths. For consistency with Rust, `usize` is used everywhere. Update explicit types to use `usize` and remove type casting. Implicit types do not need to be updated.
+
+#### Before
+
+```rust
+fn example(mut cx: FunctionContext) -> JsResult<JsUndefined> {
+    let arr = cx.empty_array();
+    let msg = cx.string("Hello!");
+
+    arr.set(&mut cx, 0u32, msg)?;
+
+    Ok(cx.undefined())
+}
+```
+
+#### After
+
+```rust
+fn example(mut cx: FunctionContext) -> JsResult<JsUndefined> {
+    let arr = cx.empty_array();
+    let msg = cx.string("Hello!");
+
+    arr.set(&mut cx, 0usize, msg)?;
+
+    Ok(cx.undefined())
+}
+```
+
+## Feature Flags
+
+Neon `0.10` made extensive use of feature flags for features that had not been stabilized (e.g., `try-catch-api`, `channel-api`). All features have been stabilized and the feature flags removed. Resolve by removing these features from the project's `Cargo.toml`.
+
+Two feature flags are still exist: `napi-N` for the Node-API version and `futures` for compatibility between Rust `Future` and JavaScript `Promise`.

pkgs/create-neon/data/versions.json

@@ -1,5 +1,5 @@
 {
-  "neon": "0.10",
+  "neon": "1.0.0",
   "napi": "8",
   "cargo-cp-artifact": "0.1"
 }