Class macro #1117

dherman · 2025-09-02T18:49:43Z

Example:

#[derive(Debug, Clone)]
pub struct Point {
    x: u32,
    y: u32,
}

#[neon::class]
impl Point {
    pub fn new(x: u32, y: u32) -> Self {
        Self { x, y }
    }

    pub fn x(&self) -> u32 {
        self.x
    }

    pub fn y(&self) -> u32 {
        self.y
    }

    pub fn distance(&self, other: &Self) -> f64 {
        let dx = (self.x as i32 - other.x as i32).pow(2);
        let dy = (self.y as i32 - other.y as i32).pow(2);
        ((dx + dy) as f64).sqrt()
    }
}

Tasks:

#[neon::export(class)] shortcut
auto-JS-ify method names
include other export(function) bells & whistles like JSON, async, task
support const declarations
can we support some amount of subclassing?
rustdocs
cleanup

…cros

- Class trait - #[neon::class] macro - Instance extractor - supports ability to construct instances both from JS and Rust - a couple of unit tests remaining to do: - how much subclassing can we support? - #[neon::export(class)] shorthand - cleanup

- allow #[neon(name = "foobar")] explicit renames in method attributes

- implementation of async and task methods

- doesn't yet work in conjunction with async fn

- takes &self - doesn't implicitly clone - added a couple of tests

- channel not yet working

- add tests for subclassing - suppress unused_variables warning in test

- bugfix: async fn with json attribute now works - add missing files that I meant to add in earlier commits!

- clarifications in export macro rustdocs - suppress lint warnings for auto-generated hidden exports

codecov · 2025-10-08T01:33:23Z

Codecov Report

❌ Patch coverage is 84.55115% with 148 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.24%. Comparing base (5793b62) to head (0676c28).

Files with missing lines	Patch %	Lines
crates/neon-macros/src/class/mod.rs	88.88%	56 Missing and 5 partials ⚠️
crates/neon/src/object/wrap.rs	79.81%	22 Missing ⚠️
crates/neon-macros/src/class/meta.rs	71.18%	13 Missing and 4 partials ⚠️
crates/neon/src/types_impl/extract/error.rs	0.00%	14 Missing ⚠️
crates/neon-macros/src/export/class/meta.rs	56.66%	9 Missing and 4 partials ⚠️
crates/neon-macros/src/export/class.rs	78.57%	5 Missing and 1 partial ⚠️
crates/neon/src/types_impl/extract/mod.rs	57.14%	3 Missing and 3 partials ⚠️
crates/neon-macros/src/name.rs	96.26%	3 Missing and 1 partial ⚠️
crates/neon/src/macro_internal/mod.rs	55.55%	3 Missing and 1 partial ⚠️
crates/neon-macros/src/export/mod.rs	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1117      +/-   ##
==========================================
+ Coverage   82.85%   83.24%   +0.38%     
==========================================
  Files          74       81       +7     
  Lines        4701     5610     +909     
  Branches     4701     5610     +909     
==========================================
+ Hits         3895     4670     +775     
- Misses        713      830     +117     
- Partials       93      110      +17

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

- automatically wrap RefCell<T> instead of T - no longer require Clone unless class includes async or task methods

kjvalencik · 2025-10-10T16:21:38Z

test/napi/src/js/export.rs

+    value: String,
+}
+
+#[neon::export(class, name = "RenamedClass")]


name is a bit ambiguous here. Are we renaming the class or are we renaming the export? Should we have two different name fields?

// #[neon::export(class, name = "RenamedClass")] // impl CustomNamedClass {} // equivalent to... export const RenamedClass = class CustomNamedClass {} // #[neon::export(class(name = "RenamedClass"))] // impl CustomNamedClass {} // equivalent to... export const CustomNamedClass = class RenamedClass {} // #[neon::export(class(name = "RenamedClass"), name = "RenamedClass")] // impl CustomNamedClass {} // equivalent to... export class RenamedClass {}

Possibly to avoid duplication in the common case of renaming both:

// #[neon::export(class, name = "RenamedClass")] // impl CustomNamedClass {} // equivalent to... export const RenamedClass = class CustomNamedClass {} // #[neon::export(class(name = "RenamedClass"))] // impl CustomNamedClass {} // equivalent to... export class RenamedClass {} // #[neon::export(class(name = "RenamedClass"), name = "CustomNamedClass")] // impl CustomNamedClass {} // equivalent to... export const CustomNamedClass = class RenamedClass {}

After discussing, we came to this conclusion:

// CASE 1: renames both to RenamedClass, but we won't document this #[neon::export(class, name = "RenamedClass")] impl CustomNamedClass {} // CASE 2: renames both to RenamedClass, we will document this #[neon::export(class(name = "RenamedClass"))] impl CustomNamedClass {} // CASE 3: renames class to RenamedClass and export to ExportedRenamedClass, we will document this #[neon::export(class(name = "RenamedClass"), name = "ExportedRenamedClass"] impl CustomNamedClass {}

Rationale:

Case 1 mirrors JS syntax and avoids accidentally leaking the internal Rust implementation details

Case 2 is nicely compositional

Case 3 is probably rare but again it's compositional

- Instance has been deleted - updated docs

dherman · 2025-10-13T16:52:21Z

Plan:

~~add back extractor for TryFromJs for explicit clones~~
UPDATE: we don't need an extractor! we can use this hack to use a "non-trivial bound" where for<'a> Self: Clone
don't need extractor for TryIntoJs
add TryFromJs for & and &mut as well, no extractor needed

- macro generates a `where Self: Clone` clause to conditionally require Clone only if a function takes the class type as a parameter - use a compiler workaround hack to enable this functionality -- see rust-lang/rust#48214 (comment)

…d object

…ing them with ObjectExpected errors

- added better error messages for type errors in method arguments

internal(neon): Implement wrap and unwrap as doc hidden for use in ma…

3b3943e

…cros

dherman marked this pull request as ready for review September 25, 2025 02:35

dherman requested a review from kjvalencik September 25, 2025 02:36

dherman changed the title ~~[WIP] Class macro~~ Class macro Sep 25, 2025

kjvalencik changed the base branch from kv/wrap to main September 26, 2025 19:06

dherman added 25 commits September 26, 2025 15:15

initial implementation:

678eafb

- Class trait - #[neon::class] macro - Instance extractor - supports ability to construct instances both from JS and Rust - a couple of unit tests remaining to do: - how much subclassing can we support? - #[neon::export(class)] shorthand - cleanup

some cleanup

01b8d18

cleanup

61c95e7

- auto-rename methods to idiomatic JS names

bd75e37

- allow #[neon(name = "foobar")] explicit renames in method attributes

- add all the attributes to match #[neon::export]

21a4cd8

- implementation of async and task methods

preliminary JSON implementation

4cacb47

- doesn't yet work in conjunction with async fn

Correct the #[neon(async)] implementation:

a1b5145

- takes &self - doesn't implicitly clone - added a couple of tests

preliminary implementation of context support

732e25e

- channel not yet working

add channel tests

53506d4

Preliminary support for this-parameter

b62401e

polish: testing and cleaned-up compiler error messages

c53aace

Tests:

5236ed1

- add tests for subclassing - suppress unused_variables warning in test

style nits and lint fixes

57db02d

basic support for const properties

28e6ddd

const tests

573cd2b

error handling

b5cb2b0

cleanup

e9a4983

rely on default attributes in Object.defineProperty()

1d34f8e

- add support for #[export(class)] and #[export(class, name = "FooBar")]

2113158

- bugfix: async fn with json attribute now works - add missing files that I meant to add in earlier commits!

Add sub-heading to #[export(async)] docs

ed1d687

more export doc cleanup

24f7a5b

- class macro rustdocs

d9846d3

- clarifications in export macro rustdocs - suppress lint warnings for auto-generated hidden exports

clean up some error handling logic

d84a971

add mention of #[neon::export(class)] to export docs

81821a9

move is_valid_js_identifier to name module

ad90d98

dherman added 6 commits October 7, 2025 16:22

lint fix

b5487b6

remove Finalize implementations from rustdoc examples

6876d75

feature-gate the class macro on napi-6 feature

75f5121

bugfix in doc test

d2b5974

test bugfix: Point::midpoint

5571823

more doctest bugfixes

2451b4d

dherman added 4 commits October 7, 2025 19:32

Allow &mut self methods:

a473c1c

- automatically wrap RefCell<T> instead of T - no longer require Clone unless class includes async or task methods

bugfix for doctest

03e114e

simplify examples in #[neon::class] rustdocs

ca18cdc

rustdoc improvements

83cd735

kjvalencik reviewed Oct 10, 2025

View reviewed changes

- no need for Instance anymore

78a5abb

- Instance has been deleted - updated docs

dherman added 7 commits October 13, 2025 13:47

conditionally require Clone:

5dae985

- macro generates a `where Self: Clone` clause to conditionally require Clone only if a function takes the class type as a parameter - use a compiler workaround hack to enable this functionality -- see rust-lang/rust#48214 (comment)

TryFromJsRef trait to allow method args to be & references

32044ed

trait TryFromJsRefMut and support for &mut method parameters

92502f2

API docs for reference parameters

12e01e7

feature gates

7218cf6

cargo fmt --all

64411f4

style nits

c10108a

dherman requested a review from kjvalencik October 28, 2025 22:24

dherman added 8 commits November 3, 2025 09:28

Avoid duplicate type checks by not requiring unwrap to take a verifie…

8fb76aa

…d object

properly pass WrapErrors through in TryFromJs et al instead of replac…

99b1903

…ing them with ObjectExpected errors

cargo fmt

fa44317

add some trybuild error tests

a027648

more class macro failure tests

764e0eb

import prelude to eliminate irrelevant errors in trybuild tests

a9c06cd

- added dynamic type checking tests

592e943

- added better error messages for type errors in method arguments

add tests for different ways of constructing instances

0676c28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Class macro #1117

Class macro #1117

dherman commented Sep 2, 2025 •

edited

Loading

Uh oh!

codecov bot commented Oct 8, 2025 •

edited

Loading

Uh oh!

kjvalencik Oct 10, 2025

Uh oh!

kjvalencik Oct 10, 2025

Uh oh!

dherman Oct 13, 2025

Uh oh!

dherman Oct 13, 2025

Uh oh!

dherman commented Oct 13, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Class macro #1117

Are you sure you want to change the base?

Class macro #1117

Conversation

dherman commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

kjvalencik Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

kjvalencik Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

dherman Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

dherman Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

dherman commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dherman commented Sep 2, 2025 •

edited

Loading

codecov bot commented Oct 8, 2025 •

edited

Loading

dherman commented Oct 13, 2025 •

edited

Loading