Extractors allow quickly getting JavaScript arguments as Rust values. In addition to immediate ergonomics and performance improvements, extractors set a foundation for future proc macros.
The Neon API surface area increases by two traits:
TryFromJs
FromArgs
TryFromJs
The TryFromJs trait provides a standardized way of extracting a Rust value from a JsValue. It is initially Sealed while we determine if changes are needed. In a future release, we will likely make it available for users to implement.
FromArgs
The FromArgs trait is an implementation detail and will remainSealed. It is implemented by a macro for tuples up to size 32.
Extractors
TryFromJs is implemented for many standard library values (f64, String) and wrapper types (Option). It also has blanket implementations for Handle and NeonResult. Additionally, I introduce the concept of an "extractor". The idea is inspired by axum. These extractors allow for specialization where extracted types would otherwise overlap. For example, getting an f64 from a Date.
Most extractors are implemented using the sys crate directly in order to avoid duplicate type checks. In the future, we will likely want to convert existing functions to use the TryFromJs implementations.
Json
As found previously, serialization to JSON is nearly always faster than manually reading JavaScript objects. Working with JSON, thanks to serde, is also much easier. Community crates like neon-serde have demonstrated a high demand for this functionality.
The Json extractor leverages serde and serde_json to convert to a Rust type. The ✨ magic ✨ is that it doesn't require the value to already be stringified on the JavaScript side. It leverage's Neon's new LocalKey functionality for fast access to JSON.stringify. JSON.stringify and serde_json::from_str are implicitly called when extracting.
Extractors allow quickly getting JavaScript arguments as Rust values. In addition to immediate ergonomics and performance improvements, extractors set a foundation for future proc macros.
The Neon API surface area increases by two traits:
TryFromJsFromArgsTryFromJsThe
TryFromJstrait provides a standardized way of extracting aRustvalue from aJsValue. It is initiallySealedwhile we determine if changes are needed. In a future release, we will likely make it available for users to implement.FromArgsThe
FromArgstrait is an implementation detail and will remainSealed. It is implemented by a macro for tuples up to size 32.Extractors
TryFromJsis implemented for many standard library values (f64,String) and wrapper types (Option). It also has blanket implementations forHandleandNeonResult. Additionally, I introduce the concept of an "extractor". The idea is inspired byaxum. These extractors allow for specialization where extracted types would otherwise overlap. For example, getting anf64from aDate.Most extractors are implemented using the
syscrate directly in order to avoid duplicate type checks. In the future, we will likely want to convert existing functions to use theTryFromJsimplementations.JsonAs found previously, serialization to JSON is nearly always faster than manually reading JavaScript objects. Working with JSON, thanks to
serde, is also much easier. Community crates likeneon-serdehave demonstrated a high demand for this functionality.The
Jsonextractor leveragesserdeandserde_jsonto convert to a Rust type. The ✨ magic ✨ is that it doesn't require the value to already be stringified on the JavaScript side. It leverage's Neon's newLocalKeyfunctionality for fast access toJSON.stringify.JSON.stringifyandserde_json::from_strare implicitly called when extracting.