New Features

• Class macro
• impl TryFromJs for i32 and u32
• impl TryIntoJs for LazyLock
• Deferred::settle() and Deferred::try_settle()

New Features

• Class macro
• impl TryFromJs for i32 and u32
• impl TryIntoJs for LazyLock
• Deferred::settle() and Deferred::try_settle()

Hotfix for Node-API versions lower than 5 (#1106).

Continued Commitment to Compatibility

Our strong commitment to compatibility since the 1.0 release remains unchanged. New functionality that has not yet stabilized is published under feature flags, so the only breaking changes that we expect to publish are those that affect the unstable features, or, as always, safety bugfixes.

Version 1.1.1

Hotfix for Node-API versions lower than 5 (https://github.com/neon-bindings/neon/pull/1106).

Version 1.1.0

New Features

• Extractors API
• #[export] macro
• npm init neon -- --lib
• JsBox::deref()
• Handle<'_, JsBox>::as_inner()

Bugfixes

• Fix panic when borrowing empty buffer or typed array (https://github.com/neon-bindings/neon/pull/1058)
• Fix build script behavior based on cargo diagnostics format change (https://github.com/neon-bindings/neon/pull/1039)

Version 1.1.0-alpha.2

Breaking Changes (unstable features only)

• Convert snake_case to camelCase when exporting functions (https://github.com/neon-bindings/neon/pull/1084)
• Remove FromArgs impl on T: TryFromJs and add cx.{arg, arg_opt} (https://github.com/neon-bindings/neon/pull/1096)

Other

• Relax lifetime constraints on With (https://github.com/neon-bindings/neon/pull/1086)
• Add JsBox::{deref, as_inner} to get long-lived reference to JsBox contents (https://github.com/neon-bindings/neon/pull/1087)
• Add extractors for TypedArrays (https://github.com/neon-bindings/neon/pull/1089)
• Add extractors for common container types (https://github.com/neon-bindings/neon/pull/1091)

Version 1.1.0-alpha.1

Breaking Changes (unstable features only)

• TryIntoJs and TryFromJs take Cx instead of generic Context (https://github.com/neon-bindings/neon/pull/1062)

Bugfixes

• Fix panic when borrowing empty buffer or typed array (https://github.com/neon-bindings/neon/pull/1058)

Other

• More reliable checking for Result types in #[export] (https://github.com/neon-bindings/neon/pull/1057)
• Allow users to take Cx instead of generic Context (https://github.com/neon-bindings/neon/pull/1048)
• Introduce With for TryIntoJs (https://github.com/neon-bindings/neon/pull/1059)
• Add tokio async runtime support to #[export] (https://github.com/neon-bindings/neon/pull/1055)
• Add TryIntoJs and TryFromJs for common container types (https://github.com/neon-bindings/neon/pull/1066)
• Allow Cx in exported functions (https://github.com/neon-bindings/neon/pull/1068)

Version 1.1.0-alpha.0

Bugfixes

• Fix build script behavior based on cargo diagnostics format change (https://github.com/neon-bindings/neon/pull/1039)

Other

• Added Extractors API (https://github.com/neon-bindings/neon/pull/1024)
• Added #[export] macro (https://github.com/neon-bindings/neon/pull/1025)
• Added npm init neon --lib (https://github.com/neon-bindings/neon/pull/1014 and https://github.com/neon-bindings/neon/pull/1041)

Version 1.1.0-alpha.2

Breaking Changes (unstable features only)

• Convert snake_case to camelCase when exporting functions (#1084)
• Remove FromArgs impl on T: TryFromJs and add cx.{arg, arg_opt} (#1096)

Other

• Relax lifetime constraints on With (#1086)
• Add JsBox::{deref, as_inner} to get long-lived reference to JsBox contents (#1087)
• Add extractors for TypedArrays (#1089)
• Add extractors for common container types (#1091)

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 (#989)
• JsArray::new takes a usize instead of a u32 (#988)
• Made Context::global read a key and added Context::global_object (#987)
• Deprecated feature flags were removed

Bug fixes

• Fix unhandledRejection with JsPromise::to_future (#1008)
• Typo in cargo-cp-artifact help (#998)
• Typo in README (#1012)

Other

#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

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

Patch to enable new feature flags in docs.rs.

Patch to enable new features flags in docs.rs.

Breaking Changes

• Removed Managed trait

Improvements

• Added JsBigInt (#963).
• Added UTF-16 functions to JsString (#944).
• Relaxed Send constraints (#979)
• Lifecycle support for 32-bit (#977)
• Added sys feature (#970)

Bug Fixes

• Fix a scope leak in release builds (#952).

Docs

• Examples added for many types ((#942)).

cargo-cp-artifact

0.1.8 fixes sending additional arguments on Windows (#972).

Breaking Changes

• Removed Managed trait

Improvements

• Added JsBigInt (https://github.com/neon-bindings/neon/pull/963).
• Added UTF-16 functions to JsString (https://github.com/neon-bindings/neon/pull/944).
• Relaxed Send constraints (https://github.com/neon-bindings/neon/pull/979)
• Lifecycle support for 32-bit (https://github.com/neon-bindings/neon/pull/977)
• Added sys feature (https://github.com/neon-bindings/neon/pull/970)

Bug Fixes

• Fix a scope leak in release builds (https://github.com/neon-bindings/neon/pull/952).

Docs

• Examples added for many types ((https://github.com/neon-bindings/neon/pull/942)).

cargo-cp-artifact

0.1.8 fixes sending additional arguments on Windows (https://github.com/neon-bindings/neon/pull/972).

Breaking Changes

neon::object::This

#918

Trait neon::object::This has been removed. This was primarily added for use with the declare_types! macro to generate classes. The macro was removed and This is no longer needed. Additionally, the This argument on JsFunction was found to be invalid because it asserted at compile time a type for this that could change at runtime. (Note that this was not unsound because the type would be checked by Node-API and result in a panic.)

JsFunction::this

#918

JsFunction::this was changed to perform a downcast and be fallible. This is in line with similar APIs (e.g., Object::get). Additionally, an infallible version, JsValue::this_value was added that does not perform a downcast.

Added Feature flag for external buffers

#937

Electron began using pointer compression on JavaScript values that is incompatible with external buffers. As a preventative measure, JsArrayBuffer::external and JsBuffer::external have been placed behind a feature flag that warns of Electron incompatibility.

Improvements

• Lifetimes were relaxed on execute_scoped to allow valid code to compile. (#919)
• Added a from_slice helper on TypedArray (#925)
• JsTypedArray construction and type aliases (#909)

Bug Fixes

• Fixed a panic on VM shutdown when using Channel (#934)
• Type tags were added to JsBox to prevent undefined behavior when multiple native add-ons are used (#907)

Docs

• Significantly improved documentation of TypedArray (#909)
• Removed unused values in Channel docs (#925)

cargo-cp-artifact

0.1.7 includes a fix to unlink .node files before copying to address common code signing errors on macOS (#921).

Breaking Changes

neon::object::This

https://github.com/neon-bindings/neon/pull/918

Trait neon::object::This has been removed. This was primarily added for use with the declare_types! macro to generate classes. The macro was removed and This is no longer needed. Additionally, the This argument on JsFunction was found to be invalid because it asserted at compile time a type for this that could change at runtime. (Note that this was not unsound because the type would be checked by Node-API and result in a panic.)

JsFunction::this

https://github.com/neon-bindings/neon/pull/918

JsFunction::this was changed to perform a downcast and be fallible. This is in line with similar APIs (e.g., Object::get). Additionally, an infallible version, JsValue::this_value was added that does not perform a downcast.

Added Feature flag for external buffers

https://github.com/neon-bindings/neon/pull/937

Electron began using pointer compression on JavaScript values that is incompatible with external buffers. As a preventative measure, JsArrayBuffer::external and JsBuffer::external have been placed behind a feature flag that warns of Electron incompatibility.

Improvements

• Lifetimes were relaxed on execute_scoped to allow valid code to compile. (https://github.com/neon-bindings/neon/pull/919)
• Added a from_slice helper on TypedArray (https://github.com/neon-bindings/neon/pull/925)
• JsTypedArray construction and type aliases (https://github.com/neon-bindings/neon/pull/909)

Bug Fixes

• Fixed a panic on VM shutdown when using Channel (https://github.com/neon-bindings/neon/pull/934)
• Type tags were added to JsBox to prevent undefined behavior when multiple native add-ons are used (https://github.com/neon-bindings/neon/pull/907)

Docs

• Significantly improved documentation of TypedArray (https://github.com/neon-bindings/neon/pull/909)
• Removed unused values in Channel docs (https://github.com/neon-bindings/neon/pull/925)

cargo-cp-artifact

0.1.7 includes a fix to unlink .node files before copying to address common code signing errors on macOS (https://github.com/neon-bindings/neon/pull/921).

Pre-release of a major milestone for Neon. 1.0.

Breaking Changes

Major

• Removed the legacy backend; only Node-API is supported going forward (#881)
• Removed neon::result::JsResultExt in favor of more general neon::result::ResultExt (#904)

Minor

• Length APIs (argument, argument_ops, len) use usize instead of i32 (#889)
• Deprecate feature flags for accepted RFCs (#872)
• neon::meta::version returns semver@1 version instead of 0.9 (#912)

Features

• Add Object.freeze and Object.seal (#891)
• Futures RFC (#872) Implementation (#874)
  • Await JoinHandle from sending an event on a Channel
  • Adapt JsPromise to JsFuture
• API for thread-local data (i.e., instance data) (#902)
• Add Object::call_with() convenience method to call a method on an object (#879)

Bug Fixes

• Relax the lifetime constraints on TypedArray borrows (#877)
• Allowing missing symbols at load time to support bun (#914)
• Prevent a panic when an async event is called after the JavaScript runtime has stopped (#913)
• Fix a soundness hole in JsArrayBuffer::external and JsBuffer::external (#897)

Docs

• Fixed mistake in Object::get docs (#903)
• Fixed link in README to migration guide (#895)

Internal

• Moved cargo-cp-artirfact into the monorepo (#905)
• Decreased the size of the Neon build matrix (#893)
• Removed scope abstraction from legacy backend (#888)
• Improved the monorepo structure of neon (#884)

Pre-release of a major milestone for Neon. 1.0.

Breaking Changes

Major

• Removed the legacy backend; only Node-API is supported going forward (https://github.com/neon-bindings/neon/pull/881)
• Removed neon::result::JsResultExt in favor of more general neon::result::ResultExt (https://github.com/neon-bindings/neon/pull/904)

Minor

• Length APIs (argument, argument_ops, len) use usize instead of i32 (https://github.com/neon-bindings/neon/pull/889)
• Deprecate feature flags for accepted RFCs (https://github.com/neon-bindings/neon/pull/872)
• neon::meta::version returns semver@1 version instead of 0.9 (https://github.com/neon-bindings/neon/pull/912)

Features

• Add Object.freeze and Object.seal (https://github.com/neon-bindings/neon/pull/891)
• Futures RFC (https://github.com/neon-bindings/neon/pull/872) Implementation (https://github.com/neon-bindings/neon/pull/874)
  • Await JoinHandle from sending an event on a Channel
  • Adapt JsPromise to JsFuture
• API for thread-local data (i.e., instance data) (https://github.com/neon-bindings/neon/pull/902)
• Add Object::call_with() convenience method to call a method on an object (https://github.com/neon-bindings/neon/pull/879)

Bug Fixes

• Relax the lifetime constraints on TypedArray borrows (https://github.com/neon-bindings/neon/pull/877)
• Allowing missing symbols at load time to support bun (https://github.com/neon-bindings/neon/pull/914)
• Prevent a panic when an async event is called after the JavaScript runtime has stopped (https://github.com/neon-bindings/neon/pull/913)
• Fix a soundness hole in JsArrayBuffer::external and JsBuffer::external (https://github.com/neon-bindings/neon/pull/897)

Docs

• Fixed mistake in Object::get docs (https://github.com/neon-bindings/neon/pull/903)
• Fixed link in README to migration guide (https://github.com/neon-bindings/neon/pull/895)

Internal

• Moved cargo-cp-artirfact into the monorepo (https://github.com/neon-bindings/neon/pull/905)
• Decreased the size of the Neon build matrix (https://github.com/neon-bindings/neon/pull/893)
• Removed scope abstraction from legacy backend (https://github.com/neon-bindings/neon/pull/888)
• Improved the monorepo structure of neon (https://github.com/neon-bindings/neon/pull/884)

Fix a soundness hole in JsArrayBuffer::external
and JsBuffer::external (#897).

Thanks to @Cassy343 for finding the issue!

In previous versions of Neon, it was possible to create a JsArrayBuffer or JsBuffer that references data without the 'static lifetime.

pub fn soundness_hole(mut cx: FunctionContext) -> JsResult<JsArrayBuffer> {
    let mut data = vec![0u8, 1, 2, 3];

    // Creating an external from `&mut [u8]` instead of `Vec<u8>` since there is a blanket impl
    // of `AsMut<T> for &mut T`
    let buf = JsArrayBuffer::external(&mut cx, data.as_mut_slice());

    // `buf` is still holding a reference to `data`!
    drop(data);

    Ok(buf)
}

Fix a soundness hole in JsArrayBuffer::external and JsBuffer::external (https://github.com/neon-bindings/neon/pull/897).

Thanks to @Cassy343 for finding the issue!

In previous versions of Neon, it was possible to create a JsArrayBuffer or JsBuffer that references data without the 'static lifetime.

pub fn soundness_hole(mut cx: FunctionContext) -> JsResult<JsArrayBuffer> {
    let mut data = vec![0u8, 1, 2, 3];

    // Creating an external from `&mut [u8]` instead of `Vec<u8>` since there is a blanket impl
    // of `AsMut<T> for &mut T`
    let buf = JsArrayBuffer::external(&mut cx, data.as_mut_slice());

    // `buf` is still holding a reference to `data`!
    drop(data);

    Ok(buf)
}

• Expose the Finalize trait as neon::types::Finalize so that docs are visible
• Improved docs and build scripts in create-neon to make release builds more discoverable (https://github.com/neon-bindings/neon/pull/771)
• Update nan to fix an Electron 13 incompatibility (https://github.com/neon-bindings/neon/pull/778)

Performance

Channel, formerly EventQueue, are now cloneable. Clones share a backing queue to take advantage of an optimization in Node threadsafe functions. Additionally, when specifying Node API 6 or higher (napi-6), calling cx.channel() will return a shared queue (https://github.com/neon-bindings/neon/pull/739).

The change may cause a performance regression in some pathological use cases (https://github.com/neon-bindings/neon/issues/762).

Deprecation

EventQueue and EventQueueError have been renamed to Channel and ChannelError respectively to clarify their function and similarity to Rust channels. The types are available as deprecated aliases (https://github.com/neon-bindings/neon/pull/752).

Docs

• Document error causes for Channel::try_send docs (https://github.com/neon-bindings/neon/pull/767)
• Document neon::object (https://github.com/neon-bindings/neon/pull/740)

Fixes

• Fix usage of a removed API in legacy buffers (https://github.com/neon-bindings/neon/pull/769)

• Fix crash caused by non-thread safety in napi_threadsafefunction on early termination (https://github.com/neon-bindings/neon/pull/744)
• Fix memory leak in Root (https://github.com/neon-bindings/neon/pull/750)

• More docs improvements
• Added a deprecation warning to neon new (https://github.com/neon-bindings/neon/pull/722)

• Fix legacy-backend for Node 16 (https://github.com/neon-bindings/neon/pull/715)
• Various docs improvements

Fixes

• as_slice and as_mut_slice properly handle a null pointer from an empty buffer (https://github.com/neon-bindings/neon/pull/681)
• Global drop queue added to avoid panics on N-API 6+ when dropping a Root (https://github.com/neon-bindings/neon/pull/700)

Features

• Added neon::reflect::eval (https://github.com/neon-bindings/neon/pull/692)
• Added create-neon for creating an N-API project (https://github.com/neon-bindings/neon/pull/690)
• Added details to the README.md generated by create-neon (https://github.com/neon-bindings/neon/pull/697)

Improvements

• Switched N-API tests to cargo-cp-artifact (https://github.com/neon-bindings/neon/pull/687)
• Added impl<T: Finalize> Finalize for Option<T> (https://github.com/neon-bindings/neon/pull/680)
• Added a N-API migration guide (https://github.com/neon-bindings/neon/pull/685)

Housekeeping

• Lint fixes (https://github.com/neon-bindings/neon/pull/609)
• Lint CI enforcement and cargo fmt (https://github.com/neon-bindings/neon/pull/698)

Features

• Added JsDate to N-API backend (https://github.com/neon-bindings/neon/pull/639)
• Implement JsBuffer::unitialized for N-API backend (https://github.com/neon-bindings/neon/pull/664)

Fixes

• Do not panic if a Root is leaked after the event loop has stopped (https://github.com/neon-bindings/neon/pull/677)
• Stubs for features that will not be implemented in the N-API backend are removed (https://github.com/neon-bindings/neon/pull/663)
• Fix doc URL link (https://github.com/neon-bindings/neon/pull/663)

N-API

Version Selection

Neon supports a large number of different Node versions which may have different N-API requirements. Neon now supports selecting the minimum required N-API version required by a module. For example, for N-API Version 4:

neon = { version = "0.7", default-features = false, features = ["napi-4"] }

If the Neon module is loaded in an older version of Node that does not support that N-API version, a panic message will inform the user.

Threadsafe Functions

A prerelease version of EventQueue for calling into the main JavaScript thread from Rust threads can be enabled with the event-queue-api feature flag. The API is considered unstable and may change in the future until the RFC is merged.

The cx.try_catch(..) API has been updated to return T: Sized instead of T: Value (https://github.com/neon-bindings/neon/pull/631). This API is strictly more powerful and allows users to return both JavaScript and Rust values from try_catch closures.

N-API

• N-API symbols are now loaded dynamically (https://github.com/neon-bindings/neon/pull/646)
• Build process for N-API is greatly simplified by leveraging dynamic loading (https://github.com/neon-bindings/neon/pull/647)

Bug Fixes

Upgrade node-gyp (https://github.com/neon-bindings/neon/pull/623)

• Fix Windows Node 15
• Fix Apple M1

Features

Added neon::main macro as a replacement for register_module! (https://github.com/neon-bindings/neon/pull/636)

Known Issues

Builds occassionally fail with Windows, Node 15 and npm 7 (https://github.com/neon-bindings/neon/issues/642)