[nathanwhit]

The main motivation is explicitness, particularly when handling the value, followed by reducing the syntactic noise for a common case. This came up in discussions with @mikea

Consider Option<Nullable<T>>:

fn foo(val: Option<Nullable<bool>>) {

 match val {
    Some(Nullable::Some(v)) => println!("got a value: {}", v),
    Some(Nullable::Null)) => println!("got null"),
    None => println!("got undefined")
 }
}

vs NullOrUndefined<T>:

fn foo(val: NullOrUndefined<bool>) {

 match val {
    NullOrUndefined::Some(v) => println!("got a value: {}", v),
    NullOrUndefined::Null => println!("got null"),
    NullOrUndefined::Undefined => println!("got undefined")
 }
}

The semantics and meaning of NullOrUndefined are immediately clear, whereas the meaning of None being undefined is non-obvious.

This PR adds the type and makes it the recommended way to represent T | null | undefined in Rust JSG. Option<Nullable<T>> remains but is not advertised as prominently in the docs.

Feel free to bikeshed the naming, names are hard.

[clanky-the-clanker]

✅ Approved — The changes since the last review (the macro's handling of optional fields and the new unit tests) are correct, and nothing in the pull request raises a correctness, security, performance or documentation concern.

_{The decision is advisory: this comment never approves, blocks or requests changes on the pull request.}

---

✅ All checks passed

🔒 Security: ✅ LGTM

The change adds a plain Rust enum, its conversions and its macro handling. It adds no trust boundary and does not touch secrets, injection or authorization paths.

---

📖 AGENTS.md: ✅ LGTM

The src/rust/AGENTS.md update matches the change.

---

📋 Code Quality: ✅ LGTM

• Field presence: the macro checks is_some() for Option and !is_undefined() for NullOrUndefined.
• Data-property path: it calls ToJS::to_js for every field. Both types convert to undefined, so the output is unchanged.
• Set() path: it still skips absent optional fields.
• Empty dictionary: the Default::default() fallback works for both types. The derived Default does not require T: Default.
• Lenient::to_parts: it now returns NullOrUndefined<T>, and its callers have been updated.
• Conversions: the From impls keep all three states, and FromJS keeps null and undefined apart from a value.
• GC tracing: the Traced impl visits only Some.

---

⚡ Performance: ✅ LGTM

The change adds a plain enum, its conversions and its macro handling. None of it adds work per request that could slow things down.

---

📝 Documentation: ✅ LGTM

The README, the jsg-macros README and the review checklist describe the new type accurately.

---

_{Reviewed commit: a56bdff8}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 97 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.24%. Comparing base (9792d03) to head (a56bdff).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rust/jsg/null_or_undefined.rs	0.00%	41 Missing ⚠️
src/rust/jsg/wrappable.rs	0.00%	39 Missing ⚠️
src/rust/jsg/lenient.rs	0.00%	17 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8080      +/-   ##
==========================================
- Coverage   69.38%   69.24%   -0.14%     
==========================================
  Files         696      698       +2     
  Lines      181869   182494     +625     
  Branches    29215    29223       +8     
==========================================
+ Hits       126188   126376     +188     
- Misses      38612    39046     +434     
- Partials    17069    17072       +3     

☔ View full report in Codecov by Harness.
📢 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.