add support for jsg_constructor (#6353)

Author: anonrig

src/rust/jsg-macros/README.md

@@ -125,6 +125,25 @@ impl WebSocket {
 
 Per Web IDL, constants are `{writable: false, enumerable: true, configurable: false}`.
 
+## `#[jsg_constructor]`
+
+Marks a static method as the JavaScript constructor for a `#[jsg_resource]`. When JavaScript calls `new MyClass(args)`, V8 invokes this method, creates a `jsg::Rc<Self>`, and attaches it to the `this` object.
+
+```rust
+#[jsg_resource]
+impl MyResource {
+    #[jsg_constructor]
+    fn constructor(name: String) -> Self {
+        Self { name }
+    }
+}
+// JS: let r = new MyResource("hello");
+```
+
+The method must be static (no `self` receiver) and must return `Self`. Only one `#[jsg_constructor]` is allowed per impl block. The first parameter may be `&mut Lock` if the constructor needs isolate access — it is not exposed as a JS argument.
+
+If no `#[jsg_constructor]` is present, `new MyClass()` throws an `Illegal constructor` error.
+
 ## `#[jsg_oneof]`
 
 Generates `jsg::Type` and `jsg::FromJS` implementations for union types. Use this to accept parameters that can be one of several JavaScript types.

src/rust/jsg-macros/lib.rs

@@ -510,6 +510,10 @@ fn generate_resource_impl(impl_block: &ItemImpl) -> TokenStream {
         })
         .collect();
 
+    let constructor_registration = generate_constructor_registration(impl_block, self_ty);
+
+    let constructor_vec: Vec<_> = constructor_registration.into_iter().collect();
+
     quote! {
         #impl_block
 
@@ -520,6 +524,7 @@ fn generate_resource_impl(impl_block: &ItemImpl) -> TokenStream {
                 Self: Sized,
             {
                 vec![
+                    #(#constructor_vec,)*
                     #(#method_registrations,)*
                     #(#constant_registrations,)*
                 ]
@@ -529,6 +534,129 @@ fn generate_resource_impl(impl_block: &ItemImpl) -> TokenStream {
     .into()
 }
 
+/// Scans an impl block for a `#[jsg_constructor]` attribute and generates the
+/// constructor callback registration. Returns `None` if no constructor is defined.
+fn generate_constructor_registration(
+    impl_block: &ItemImpl,
+    self_ty: &syn::Type,
+) -> Option<quote::__private::TokenStream> {
+    let constructors: Vec<_> = impl_block
+        .items
+        .iter()
+        .filter_map(|item| match item {
+            syn::ImplItem::Fn(m) if m.attrs.iter().any(|a| is_attr(a, "jsg_constructor")) => {
+                Some(m)
+            }
+            _ => None,
+        })
+        .collect();
+
+    if constructors.len() > 1 {
+        return Some(quote! {
+            compile_error!("only one #[jsg_constructor] is allowed per impl block");
+        });
+    }
+
+    constructors
+        .into_iter()
+        .map(|method| {
+            let rust_method_name = &method.sig.ident;
+            let callback_name = syn::Ident::new(
+                &format!("{rust_method_name}_constructor_callback"),
+                rust_method_name.span(),
+            );
+
+            // Constructor must NOT have a self receiver.
+            let has_self = method
+                .sig
+                .inputs
+                .iter()
+                .any(|arg| matches!(arg, FnArg::Receiver(_)));
+            if has_self {
+                return quote! {
+                    compile_error!("#[jsg_constructor] must be a static method (no self receiver)");
+                };
+            }
+
+            // Constructor must return Self.
+            let returns_self = matches!(&method.sig.output,
+                syn::ReturnType::Type(_, ty) if matches!(&**ty,
+                    syn::Type::Path(p) if p.path.is_ident("Self")
+                )
+            );
+            if !returns_self {
+                return quote! {
+                    compile_error!("#[jsg_constructor] must return Self");
+                };
+            }
+
+            // Extract parameters (same pattern as jsg_method).
+            let params: Vec<_> = method
+                .sig
+                .inputs
+                .iter()
+                .filter_map(|arg| {
+                    if let FnArg::Typed(pat_type) = arg {
+                        Some((*pat_type.ty).clone())
+                    } else {
+                        None
+                    }
+                })
+                .collect();
+
+            let has_lock_param = params.first().is_some_and(is_lock_ref);
+            let js_arg_offset = usize::from(has_lock_param);
+
+            let (unwraps, arg_exprs): (Vec<_>, Vec<_>) = params
+            .iter()
+            .enumerate()
+            .skip(js_arg_offset)
+            .map(|(i, ty)| {
+                let js_index = i - js_arg_offset;
+                let var = syn::Ident::new(&format!("arg{js_index}"), method.sig.ident.span());
+                let unwrap = quote! {
+                    let #var = match <#ty as jsg::FromJS>::from_js(&mut lock, args.get(#js_index)) {
+                        Ok(v) => v,
+                        Err(e) => {
+                            lock.throw_exception(&e);
+                            return;
+                        }
+                    };
+                };
+                (unwrap, quote! { #var })
+            })
+            .unzip();
+
+            let lock_arg = if has_lock_param {
+                quote! { &mut lock, }
+            } else {
+                quote! {}
+            };
+
+            quote! {
+                jsg::Member::Constructor {
+                    callback: {
+                        unsafe extern "C" fn #callback_name(
+                            info: *mut jsg::v8::ffi::FunctionCallbackInfo,
+                        ) {
+                            // SAFETY: info is a valid V8 FunctionCallbackInfo from the constructor call.
+                            let mut args = unsafe { jsg::v8::FunctionCallbackInfo::from_ffi(info) };
+                            let mut lock = unsafe { jsg::Lock::from_args(info) };
+
+                            #(#unwraps)*
+
+                            let resource = #self_ty::#rust_method_name(#lock_arg #(#arg_exprs),*);
+                            let rc = jsg::Rc::new(resource);
+                            rc.attach_to_this(&mut args);
+                        }
+                        #callback_name
+                    },
+                }
+            }
+        })
+        .next()
+}
+
 /// Extracts named fields from a struct, returning an empty list for unit structs.
 /// Returns `Err` with a compile error for tuple structs or non-struct data.
 fn extract_named_fields(
@@ -634,6 +762,30 @@ pub fn jsg_static_constant(_attr: TokenStream, item: TokenStream) -> TokenStream
     item
 }
 
+/// Marks a static method as the JavaScript constructor for a `#[jsg_resource]`.
+///
+/// The method must be a static function (no `self` receiver) that returns `Self`.
+/// When JavaScript calls `new MyResource(args)`, V8 invokes this method,
+/// wraps the returned resource, and attaches it to the `this` object.
+///
+/// ```ignore
+/// #[jsg_resource]
+/// impl MyResource {
+///     #[jsg_constructor]
+///     fn constructor(name: String) -> Self {
+///         Self { name }
+///     }
+/// }
+/// // JS: let obj = new MyResource("hello");
+/// ```
+///
+/// Only one `#[jsg_constructor]` is allowed per impl block.
+#[proc_macro_attribute]
+pub fn jsg_constructor(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    // Marker attribute — the actual registration is handled by #[jsg_resource] on the impl block.
+    item
+}
+
 /// Returns true if the type is `&mut Lock` or `&mut jsg::Lock`.
 ///
 /// When a method's first typed parameter matches this pattern, the macro passes the

src/rust/jsg-test/tests/resource_callback.rs

@@ -15,6 +15,7 @@ use std::rc::Rc;
 use jsg::ExceptionType;
 use jsg::Number;
 use jsg::ToJS;
+use jsg_macros::jsg_constructor;
 use jsg_macros::jsg_method;
 use jsg_macros::jsg_resource;
 use jsg_macros::jsg_static_constant;
@@ -413,3 +414,146 @@ fn static_constant_coexists_with_methods() {
         Ok(())
     });
 }
+
+// =============================================================================
+// Constructor tests
+// =============================================================================
+
+#[jsg_resource]
+struct Greeting {
+    message: String,
+}
+
+#[jsg_resource]
+impl Greeting {
+    #[jsg_constructor]
+    fn constructor(message: String) -> Self {
+        Self { message }
+    }
+
+    #[jsg_method]
+    fn get_message(&self) -> String {
+        self.message.clone()
+    }
+}
+
+/// Resources without `#[jsg_constructor]` should throw when called with `new`.
+#[test]
+fn resource_without_constructor_throws() {
+    let harness = crate::Harness::new();
+    harness.run_in_context(|lock, ctx| {
+        let constructor = jsg::resource::function_template_of::<EchoResource>(lock);
+        ctx.set_global("EchoResource", constructor.into());
+
+        let result: Result<Number, _> = ctx.eval(lock, "new EchoResource('hi')");
+        assert!(result.is_err(), "should throw illegal constructor");
+        Ok(())
+    });
+}
+
+/// A `#[jsg_constructor]` method is callable from JavaScript via `new`.
+#[test]
+fn constructor_creates_instance() {
+    let harness = crate::Harness::new();
+    harness.run_in_context(|lock, ctx| {
+        let constructor = jsg::resource::function_template_of::<Greeting>(lock);
+        ctx.set_global("Greeting", constructor.into());
+
+        let result: String = ctx
+            .eval(lock, "new Greeting('hello').getMessage()")
+            .unwrap();
+        assert_eq!(result, "hello");
+        Ok(())
+    });
+}
+
+/// Constructor arguments are converted from JS types via `FromJS`.
+#[test]
+fn constructor_converts_arguments() {
+    let harness = crate::Harness::new();
+    harness.run_in_context(|lock, ctx| {
+        let constructor = jsg::resource::function_template_of::<Greeting>(lock);
+        ctx.set_global("Greeting", constructor.into());
+
+        // Number is coerced to string by V8
+        let result: String = ctx
+            .eval(lock, "new Greeting(String(42)).getMessage()")
+            .unwrap();
+        assert_eq!(result, "42");
+        Ok(())
+    });
+}
+
+/// Multiple `new` calls create distinct JS objects.
+#[test]
+fn constructor_creates_distinct_objects() {
+    let harness = crate::Harness::new();
+    harness.run_in_context(|lock, ctx| {
+        let constructor = jsg::resource::function_template_of::<Greeting>(lock);
+        ctx.set_global("Greeting", constructor.into());
+
+        let result: String = ctx
+            .eval(
+                lock,
+                "let a = new Greeting('one'); let b = new Greeting('two'); \
+                 a.getMessage() + ',' + b.getMessage()",
+            )
+            .unwrap();
+        assert_eq!(result, "one,two");
+        Ok(())
+    });
+}
+
+/// `instanceof` works correctly for constructor-created instances.
+#[test]
+fn constructor_instanceof_works() {
+    let harness = crate::Harness::new();
+    harness.run_in_context(|lock, ctx| {
+        let constructor = jsg::resource::function_template_of::<Greeting>(lock);
+        ctx.set_global("Greeting", constructor.into());
+
+        let result: String = ctx
+            .eval(
+                lock,
+                "let g = new Greeting('test'); \
+                 String(g instanceof Greeting)",
+            )
+            .unwrap();
+        assert_eq!(result, "true");
+        Ok(())
+    });
+}
+
+// Constructor with Lock parameter
+
+#[jsg_resource]
+struct Counter {
+    value: Number,
+}
+
+#[jsg_resource]
+impl Counter {
+    #[jsg_constructor]
+    fn constructor(_lock: &mut jsg::Lock, value: Number) -> Self {
+        Self { value }
+    }
+
+    #[jsg_method]
+    fn get_value(&self) -> Number {
+        self.value
+    }
+}
+
+/// `#[jsg_constructor]` with a `Lock` parameter works.
+#[test]
+fn constructor_with_lock_parameter() {
+    let harness = crate::Harness::new();
+    harness.run_in_context(|lock, ctx| {
+        let constructor = jsg::resource::function_template_of::<Counter>(lock);
+        ctx.set_global("Counter", constructor.into());
+
+        let result: Number = ctx.eval(lock, "new Counter(99).getValue()").unwrap();
+        assert!((result.value() - 99.0).abs() < f64::EPSILON);
+        Ok(())
+    });
+}