Bring Rust JSG unions to parity with kj::OneOf

src/rust/jsg-compile-tests/non-coercible-type.rs

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// NonCoercible<T> takes only the types a value is otherwise coerced to (String, bool, f64
+// and the integers), as C++ JSG's takes only a CoercibleType. A union or a resource
+// would convert a value as it always does, coercion included, once its JavaScript type passed a
+// coarse check.
+
+use jsg::FromJS;
+use jsg::NonCoercible;
+use jsg_macros::jsg_oneof;
+use jsg_macros::jsg_resource;
+
+#[jsg_resource]
+pub struct Thing;
+
+#[jsg_resource]
+impl Thing {}
+
+#[jsg_oneof]
+pub enum ThingOrString {
+    Thing(jsg::Rc<Thing>),
+    String(String),
+}
+
+pub fn union_name() -> String {
+    <NonCoercible<ThingOrString> as FromJS<'static>>::type_name() //~ ERROR E0277
+}
+
+pub fn resource_name() -> String {
+    <NonCoercible<jsg::Rc<Thing>> as FromJS<'static>>::type_name() //~ ERROR E0277
+}

src/rust/jsg-compile-tests/ok-oneof.rs

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// The unions that Web IDL allows compile, including several resources, a handle of any type with
+// a dictionary, an object handle with primitives, and different resources and typed array handles
+// in a union and a union nested in it.
+
+use jsg::Nullable;
+use jsg::v8;
+use jsg_macros::jsg_oneof;
+use jsg_macros::jsg_resource;
+use jsg_macros::jsg_struct;
+
+#[jsg_struct]
+pub struct Point {
+    pub x: f64,
+}
+
+#[jsg_resource]
+pub struct First;
+
+#[jsg_resource]
+impl First {}
+
+#[jsg_resource]
+pub struct Second;
+
+#[jsg_resource]
+impl Second {}
+
+#[jsg_oneof]
+pub enum Everything<'s> {
+    First(jsg::Rc<First>),
+    Second(jsg::Rc<Second>),
+    Point(Point),
+    Numbers(Vec<f64>),
+    Bytes(v8::Local<'s, v8::Uint8Array>),
+    String(String),
+    Number(i32),
+    Bool(bool),
+    Date(std::time::SystemTime),
+}
+
+#[jsg_oneof]
+pub enum Handles<'s> {
+    Object(v8::Local<'s, v8::Object>),
+    String(Nullable<String>),
+    Number(v8::Local<'s, v8::BigInt>),
+    Function(v8::Local<'s, v8::Function>),
+}
+
+#[jsg_oneof]
+pub enum AnyOrPoint<'s> {
+    Any(v8::Local<'s, v8::Value>),
+    Point(Point),
+}
+
+#[jsg_oneof]
+pub enum SecondOrClamped<'s> {
+    Second(jsg::Rc<Second>),
+    Clamped(v8::Local<'s, v8::Uint8ClampedArray>),
+}
+
+#[jsg_oneof]
+pub enum FirstOrNested<'s> {
+    First(jsg::Rc<First>),
+    Bytes(v8::Local<'s, v8::Uint8Array>),
+    Nested(SecondOrClamped<'s>),
+}

src/rust/jsg-compile-tests/oneof-duplicate-types.rs

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// A #[jsg_oneof] union may not contain the same type twice, as C++ JSG's
+// webidl::UnionTypeValidator requires of a kj::OneOf, even of a kind it may have more than one
+// of, such as resources. As there, a nullable type counts as its inner type. Each union is
+// rejected twice: by conflicting trait impls, which point at the second variant, and because
+// the union's names contain the resource's twice.
+
+use jsg::Nullable;
+use jsg_macros::jsg_oneof;
+use jsg_macros::jsg_resource;
+
+#[jsg_resource]
+pub struct Thing;
+
+#[jsg_resource]
+impl Thing {}
+
+type SameThing = jsg::Rc<Thing>;
+
+#[jsg_oneof] //~ ERROR E0080: may not contain the same type twice
+pub enum SameResourceTwice {
+    First(jsg::Rc<Thing>),
+    Second(SameThing), //~ ERROR E0119
+}
+
+#[jsg_oneof] //~ ERROR E0080: may not contain the same type twice
+pub enum ResourceAndNullableResource {
+    Thing(jsg::Rc<Thing>),
+    Nullable(Nullable<jsg::Rc<Thing>>), //~ ERROR E0119
+}

src/rust/jsg-compile-tests/oneof-generic-parameters.rs

@@ -0,0 +1,23 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// A #[jsg_oneof] union, like a kj::OneOf, has no type parameters. It may have one lifetime
+// parameter, for the scope of the handles it holds.
+
+use jsg::v8;
+use jsg_macros::jsg_oneof;
+
+#[jsg_oneof]
+pub enum TypeParameter<T> {
+    //~^ ERROR only one lifetime parameter
+    Value(T),
+    String(String),
+}
+
+#[jsg_oneof]
+pub enum TwoLifetimes<'a, 'b> {
+    //~^ ERROR only one lifetime parameter
+    First(v8::Local<'a, v8::Object>),
+    Second(v8::Local<'b, v8::String>),
+}

src/rust/jsg-compile-tests/oneof-nested-duplicate-types.rs

@@ -0,0 +1,74 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// A #[jsg_oneof] union may not contain a type that a union nested in it also contains, as C++
+// JSG's webidl::FlattenedTypeTraits flattens a nested kj::OneOf before checking for duplicate
+// types. These types are in no Web IDL category with a limit, so only their names catch them.
+
+use std::time::SystemTime;
+
+use jsg::Nullable;
+use jsg::v8;
+use jsg_macros::jsg_oneof;
+use jsg_macros::jsg_resource;
+
+#[jsg_resource]
+pub struct Thing;
+
+#[jsg_resource]
+impl Thing {}
+
+#[jsg_oneof]
+pub enum ThingOrString {
+    Thing(jsg::Rc<Thing>),
+    String(String),
+}
+
+#[jsg_oneof] //~ ERROR E0080: may not contain the same type twice
+pub enum ResourceInNestedUnion {
+    Thing(jsg::Rc<Thing>),
+    Nested(ThingOrString),
+}
+
+#[jsg_oneof]
+pub enum NullableThingOrString {
+    Thing(Nullable<jsg::Rc<Thing>>),
+    String(String),
+}
+
+#[jsg_oneof] //~ ERROR E0080: may not contain the same type twice
+pub enum ResourceInNullableInNestedUnion {
+    Thing(jsg::Rc<Thing>),
+    Nested(NullableThingOrString),
+}
+
+#[jsg_oneof]
+pub enum BytesOrString<'s> {
+    Bytes(v8::Local<'s, v8::Uint8Array>),
+    String(String),
+}
+
+#[jsg_oneof] //~ ERROR E0080: may not contain the same type twice
+pub enum HandleInNestedUnion<'s> {
+    Bytes(v8::Local<'s, v8::Uint8Array>),
+    Nested(BytesOrString<'s>),
+}
+
+#[jsg_oneof]
+pub enum DateOrString {
+    Date(SystemTime),
+    String(String),
+}
+
+#[jsg_oneof]
+pub enum DateOrBool {
+    Date(SystemTime),
+    Bool(bool),
+}
+
+#[jsg_oneof] //~ ERROR E0080: may not contain the same type twice
+pub enum DateInTwoNestedUnions {
+    First(DateOrString),
+    Second(DateOrBool),
+}

src/rust/jsg-compile-tests/oneof-variant-type.rs

@@ -0,0 +1,15 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// A #[jsg_oneof] variant is a type that converts from JavaScript and that C++ JSG's kj::OneOf
+// could hold.
+
+use jsg_macros::jsg_oneof;
+
+#[jsg_oneof] //~ ERROR E0277
+pub enum FloatOrString {
+    Float(f32), //~ ERROR cannot be a `#[jsg_oneof]` variant
+    //~| ERROR E0277
+    String(String),
+}

src/rust/jsg-compile-tests/oneof-web-idl-rules.rs

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// A #[jsg_oneof] union follows Web IDL's rules for unions, as C++ JSG's
+// webidl::UnionTypeValidator checks a kj::OneOf at compile time: at most one type of each kind
+// that a value can't tell apart, counting the types of nested unions and nullable types.
+
+use jsg::Dict;
+use jsg::Nullable;
+use jsg::v8;
+use jsg_macros::jsg_oneof;
+use jsg_macros::jsg_resource;
+use jsg_macros::jsg_struct;
+
+#[jsg_struct]
+pub struct Point {
+    pub x: f64,
+}
+
+#[jsg_resource]
+pub struct Thing;
+
+#[jsg_resource]
+impl Thing {}
+
+#[jsg_oneof] //~ ERROR E0080: at most one boolean type
+pub enum TwoBooleans {
+    Bool(bool),
+    Strict(jsg::NonCoercible<bool>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: at most one numeric type
+pub enum TwoNumerics {
+    Number(f64),
+    Integer(u32),
+}
+
+#[jsg_oneof] //~ ERROR E0080: at most one string type
+pub enum TwoStrings<'s> {
+    String(String),
+    Handle(v8::Local<'s, v8::String>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: an object type only if
+pub enum ObjectAndResource<'s> {
+    Object(v8::Local<'s, v8::Object>),
+    Thing(jsg::Rc<Thing>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: an object type only if
+pub enum ObjectAndRecord<'s> {
+    Object(v8::Local<'s, v8::Object>),
+    Dict(Dict<f64>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: an object type only if
+pub enum ObjectAndSequence<'s> {
+    Object(v8::Local<'s, v8::Object>),
+    Sequence(Vec<f64>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: at most one dictionary-like type
+pub enum DictionaryAndRecord {
+    Point(Point),
+    Dict(Dict<f64>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: at most one sequence-like type
+pub enum TwoSequences {
+    Numbers(Vec<f64>),
+    Strings(Vec<String>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: at most one nullable or dictionary type
+pub enum NullableAndDictionary {
+    Number(Nullable<f64>),
+    Point(Point),
+}
+
+#[jsg_oneof] //~ ERROR E0080: at most one nullable or dictionary type
+pub enum TwoNullables {
+    Number(Nullable<f64>),
+    Integer(Nullable<String>),
+}
+
+#[jsg_oneof] //~ ERROR E0080: may not contain Option<T> or Lenient<T>
+pub enum Optional {
+    Number(Option<f64>),
+    String(String),
+}
+
+#[jsg_oneof]
+pub enum StringOrBool {
+    String(String),
+    Bool(bool),
+}
+
+// The nested union's string type counts as the outer union's.
+#[jsg_oneof] //~ ERROR E0080: at most one string type
+pub enum NestedStrings {
+    String(String),
+    Nested(StringOrBool),
+}

src/rust/jsg-compile-tests/owned-fromjs-bound-rejects-local.rs

@@ -3,12 +3,13 @@
 //     https://opensource.org/licenses/Apache-2.0
 
 // `T: for<'s> FromJS<'s, ResultType = T>` (used where a value must outlive the scope) excludes
-// handle types.
+// handle types. Compilers word the error differently: some report that the `FromJS` impl is not
+// general enough, others that the bound `for<'s> FromJS<'s>` is not satisfied (E0277).
 use jsg::FromJS;
 use jsg::v8;
 
 pub fn owned<T: for<'s> FromJS<'s, ResultType = T>>() {}
 
 pub fn t() {
-    owned::<v8::Local<'static, v8::Object>>(); //~ ERROR E0277
+    owned::<v8::Local<'static, v8::Object>>(); //~ ERROR FromJS
 }

src/rust/jsg-macros/README.md

@@ -414,11 +414,17 @@ impl Env {
 
 ## `#[jsg_oneof]`
 
-Generates `jsg::Type` and `jsg::FromJS` for a union enum — the Rust equivalent of
-`kj::OneOf<…>`. Each variant must be a single-field tuple whose inner type implements
-`jsg::Type` + `jsg::FromJS`. Variants are tried in declaration order using
-exact-type matching; if none matches, a `TypeError` is thrown listing all expected
-types.
+Generates `jsg::Type`, `jsg::FromJS` and `jsg::Traced` for a union enum — the Rust
+equivalent of `kj::OneOf<…>` — and `jsg::ToJS` when every variant implements it. Each
+variant must be a single-field tuple whose inner type converts from JavaScript and is
+`jsg::Type`. A union that holds handles has one lifetime parameter,
+their scope, and no `jsg::Traced` that can be used; a union has no other generic
+parameters. A value converts as it would to the equivalent `kj::OneOf`: variants are
+tried in passes that leave coercion for last, in declaration order within a pass. If no
+variant converts the value, a `TypeError` is thrown naming the expected types, such as
+`Expected string or number but got symbol`. Like `kj::OneOf`, a union that breaks Web
+IDL's rules for unions, such as one with two string types, doesn't compile. See
+[Union Types](../jsg/README.md#union-types).
 
 ```rust
 #[jsg_oneof]