diff --git a/AUTHORS.md b/AUTHORS.md index c8d6f404a..65ea80c77 100644 --- a/AUTHORS.md +++ b/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) diff --git a/Cargo.lock b/Cargo.lock index 16a419408..d580048ce 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -345,7 +345,7 @@ dependencies = [ [[package]] name = "neon" -version = "1.0.0-alpha.4" +version = "1.0.0" dependencies = [ "anyhow", "aquamarine", @@ -367,7 +367,7 @@ dependencies = [ [[package]] name = "neon-macros" -version = "1.0.0-alpha.4" +version = "1.0.0" dependencies = [ "quote", "syn 2.0.39", diff --git a/README.md b/README.md index 5ff0fbe7a..a2b9a5689 100644 --- a/README.md +++ b/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 diff --git a/RELEASES.md b/RELEASES.md index 20669524e..6d808accd 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -1,3 +1,26 @@ +# Version 1.0.0 + +## 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 + +* 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. diff --git a/crates/neon-macros/Cargo.toml b/crates/neon-macros/Cargo.toml index 020e3b53c..fe6033c0f 100644 --- a/crates/neon-macros/Cargo.toml +++ b/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 "] description = "Procedural macros supporting Neon" repository = "https://github.com/neon-bindings/neon" diff --git a/crates/neon/Cargo.toml b/crates/neon/Cargo.toml index 3c35ed16c..4988d3f5b 100644 --- a/crates/neon/Cargo.toml +++ b/crates/neon/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "neon" -version = "1.0.0-alpha.4" +version = "1.0.0" authors = ["Dave Herman "] 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 } @@ -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"] diff --git a/crates/neon/src/context/mod.rs b/crates/neon/src/context/mod.rs index cef7d467e..33517db5a 100644 --- a/crates/neon/src/context/mod.rs +++ b/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(&mut self, f: F) -> Result> where F: FnOnce(&mut Self) -> NeonResult, @@ -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/). diff --git a/crates/neon/src/event/channel.rs b/crates/neon/src/event/channel.rs index b4c961dd2..a665e0a82 100644 --- a/crates/neon/src/event/channel.rs +++ b/crates/neon/src/event/channel.rs @@ -90,14 +90,6 @@ type Callback = Box; /// 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, diff --git a/crates/neon/src/event/task.rs b/crates/neon/src/event/task.rs index 0e59329ba..925bacd53 100644 --- a/crates/neon/src/event/task.rs +++ b/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 /// /// ``` diff --git a/crates/neon/src/types_impl/promise.rs b/crates/neon/src/types_impl/promise.rs index e523e6f38..625d247e3 100644 --- a/crates/neon/src/types_impl/promise.rs +++ b/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. diff --git a/doc/MIGRATION_GUIDE_1.0.0.md b/doc/MIGRATION_GUIDE_1.0.0.md new file mode 100644 index 000000000..628ad380d --- /dev/null +++ b/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(h: Handle) +where + V: Managed, +{ +} +``` + +#### After + +```rust +fn example(h: Handle) +where + V: Value, +{ +} +``` + +### `CallContext`, `This`, and `T` in `JsFunction` + +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` is equivalent to `FunctionContext` +fn example(mut cx: CallContext) -> JsResult { + let a = cx.this().get::(&mut cx, "a")?; + + Ok(cx.undefined()) +} +``` + +#### After + +```rust +fn example(mut cx: FunctionContext) -> JsResult { + let a = cx.this::()?.get::(&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 { + 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 { + 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`. diff --git a/pkgs/create-neon/data/versions.json b/pkgs/create-neon/data/versions.json index 05e851a2a..901698990 100644 --- a/pkgs/create-neon/data/versions.json +++ b/pkgs/create-neon/data/versions.json @@ -1,5 +1,5 @@ { - "neon": "0.10", + "neon": "1.0.0", "napi": "8", "cargo-cp-artifact": "0.1" } diff --git a/test/electron/Cargo.toml b/test/electron/Cargo.toml index 4fac8c5ee..20da7016d 100644 --- a/test/electron/Cargo.toml +++ b/test/electron/Cargo.toml @@ -9,5 +9,5 @@ license = "MIT/Apache-2.0" crate-type = ["cdylib"] [dependencies.neon] -version = "1.0.0-alpha.4" +version = "1.0.0" path = "../../crates/neon" diff --git a/test/napi/Cargo.toml b/test/napi/Cargo.toml index 03ade1cd4..36439d990 100644 --- a/test/napi/Cargo.toml +++ b/test/napi/Cargo.toml @@ -15,6 +15,6 @@ once_cell = "1.18.0" tokio = { version = "1.34.0", features = ["rt-multi-thread"] } [dependencies.neon] -version = "1.0.0-alpha.4" +version = "1.0.0" path = "../../crates/neon" features = ["futures", "napi-experimental", "external-buffers"]