refactor(ast/estree): define TS types for extra fields on converters

Author: overlookmotel

.github/.generated_ast_watch_list.yml

@@ -20,6 +20,7 @@ src:
   - 'crates/oxc_ast/src/generated/get_id.rs'
   - 'crates/oxc_ast/src/generated/visit.rs'
   - 'crates/oxc_ast/src/generated/visit_mut.rs'
+  - 'crates/oxc_ast/src/serialize.rs'
   - 'crates/oxc_ast_macros/src/generated/mod.rs'
   - 'crates/oxc_ast_macros/src/lib.rs'
   - 'crates/oxc_regular_expression/src/ast.rs'

crates/oxc_ast/src/ast/js.rs

@@ -493,7 +493,7 @@ pub use match_member_expression;
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(rename = "MemberExpression", add_fields(computed = True), add_ts = "computed: true")]
+#[estree(rename = "MemberExpression", add_fields(computed = True))]
 pub struct ComputedMemberExpression<'a> {
     pub span: Span,
     pub object: Expression<'a>,
@@ -508,7 +508,7 @@ pub struct ComputedMemberExpression<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(rename = "MemberExpression", add_fields(computed = False), add_ts = "computed: false")]
+#[estree(rename = "MemberExpression", add_fields(computed = False))]
 pub struct StaticMemberExpression<'a> {
     pub span: Span,
     pub object: Expression<'a>,
@@ -522,7 +522,7 @@ pub struct StaticMemberExpression<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(rename = "MemberExpression", add_fields(computed = False), add_ts = "computed: false")]
+#[estree(rename = "MemberExpression", add_fields(computed = False))]
 pub struct PrivateFieldExpression<'a> {
     pub span: Span,
     pub object: Expression<'a>,
@@ -644,7 +644,7 @@ pub struct UpdateExpression<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(add_fields(prefix = True), add_ts = "prefix: true")]
+#[estree(add_fields(prefix = True))]
 pub struct UnaryExpression<'a> {
     pub span: Span,
     pub operator: UnaryOperator,
@@ -668,7 +668,7 @@ pub struct BinaryExpression<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(rename = "BinaryExpression", add_fields(operator = In), add_ts = "operator: \"in\"")]
+#[estree(rename = "BinaryExpression", add_fields(operator = In))]
 pub struct PrivateInExpression<'a> {
     pub span: Span,
     pub left: PrivateIdentifier<'a>,
@@ -898,7 +898,6 @@ pub enum AssignmentTargetProperty<'a> {
 #[estree(
     rename = "Property",
     add_fields(kind = Init, method = False, shorthand = True, computed = False),
-    add_ts = "kind: \"init\"; method: false; shorthand: true; computed: false"
 )]
 pub struct AssignmentTargetPropertyIdentifier<'a> {
     pub span: Span,
@@ -918,11 +917,7 @@ pub struct AssignmentTargetPropertyIdentifier<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(
-    rename = "Property",
-    add_fields(kind = Init, method = False, shorthand = False),
-    add_ts = "kind: \"init\"; method: false; shorthand: false"
-)]
+#[estree(rename = "Property", add_fields(kind = Init, method = False, shorthand = False))]
 pub struct AssignmentTargetPropertyProperty<'a> {
     pub span: Span,
     /// The property key
@@ -1525,11 +1520,7 @@ pub struct ObjectPattern<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(
-    rename = "Property",
-    add_fields(kind = Init, method = False),
-    add_ts = "kind: \"init\"; method: false"
-)]
+#[estree(rename = "Property", add_fields(kind = Init, method = False))]
 pub struct BindingProperty<'a> {
     pub span: Span,
     pub key: PropertyKey<'a>,
@@ -1615,7 +1606,6 @@ pub struct BindingRestElement<'a> {
 #[estree(
     add_ts_def = "type ParamPattern = FormalParameter | FormalParameterRest",
     add_fields(expression = False),
-    add_ts = "expression: false"
 )]
 pub struct Function<'a> {
     pub span: Span,
@@ -1768,7 +1758,7 @@ pub struct FunctionBody<'a> {
 )]
 #[derive(Debug)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(add_fields(generator = False, id = Null), add_ts = "generator: false; id: null")]
+#[estree(add_fields(generator = False, id = Null))]
 pub struct ArrowFunctionExpression<'a> {
     pub span: Span,
     /// Is the function body an arrow expression? i.e. `() => expr` instead of `() => {}`

crates/oxc_ast/src/ast/literal.rs

@@ -20,7 +20,7 @@ use oxc_syntax::number::{BigintBase, NumberBase};
 #[ast(visit)]
 #[derive(Debug, Clone)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(rename = "Literal", add_fields(raw = BooleanLiteralRaw), add_ts = "raw: string | null")]
+#[estree(rename = "Literal", add_fields(raw = BooleanLiteralRaw))]
 pub struct BooleanLiteral {
     /// Node location in source code
     pub span: Span,
@@ -34,11 +34,7 @@ pub struct BooleanLiteral {
 #[ast(visit)]
 #[derive(Debug, Clone)]
 #[generate_derive(CloneIn, GetSpan, GetSpanMut, ContentEq, ESTree)]
-#[estree(
-    rename = "Literal",
-    add_fields(value = Null, raw = NullLiteralRaw),
-    add_ts = "value: null, raw: \"null\" | null",
-)]
+#[estree(rename = "Literal", add_fields(value = Null, raw = NullLiteralRaw))]
 pub struct NullLiteral {
     /// Node location in source code
     pub span: Span,
@@ -93,11 +89,7 @@ pub struct StringLiteral<'a> {
 #[ast(visit)]
 #[derive(Debug, Clone)]
 #[generate_derive(CloneIn, ContentEq, GetSpan, GetSpanMut, ESTree)]
-#[estree(
-    rename = "Literal",
-    add_fields(value = Null, bigint = BigIntLiteralBigint),
-    add_ts = "value: BigInt, bigint: string",
-)]
+#[estree(rename = "Literal", add_fields(value = BigIntLiteralValue, bigint = BigIntLiteralBigint))]
 pub struct BigIntLiteral<'a> {
     /// Node location in source code
     pub span: Span,
@@ -116,7 +108,7 @@ pub struct BigIntLiteral<'a> {
 #[ast(visit)]
 #[derive(Debug)]
 #[generate_derive(CloneIn, ContentEq, GetSpan, GetSpanMut, ESTree)]
-#[estree(rename = "Literal", add_fields(value = Null), add_ts = "value: RegExp | null")]
+#[estree(rename = "Literal", add_fields(value = RegExpLiteralValue))]
 pub struct RegExpLiteral<'a> {
     /// Node location in source code
     pub span: Span,

crates/oxc_ast/src/generated/derive_estree.rs

@@ -1969,7 +1969,7 @@ impl Serialize for BigIntLiteral<'_> {
         map.serialize_entry("start", &self.span.start)?;
         map.serialize_entry("end", &self.span.end)?;
         map.serialize_entry("raw", &self.raw)?;
-        map.serialize_entry("value", &crate::serialize::Null(self))?;
+        map.serialize_entry("value", &crate::serialize::BigIntLiteralValue(self))?;
         map.serialize_entry("bigint", &crate::serialize::BigIntLiteralBigint(self))?;
         map.end()
     }
@@ -1983,7 +1983,7 @@ impl Serialize for RegExpLiteral<'_> {
         map.serialize_entry("end", &self.span.end)?;
         map.serialize_entry("regex", &crate::serialize::RegExpLiteralRegex(self))?;
         map.serialize_entry("raw", &self.raw)?;
-        map.serialize_entry("value", &crate::serialize::Null(self))?;
+        map.serialize_entry("value", &crate::serialize::RegExpLiteralValue(self))?;
         map.end()
     }
 }

crates/oxc_ast/src/serialize.rs

@@ -7,6 +7,7 @@ use serde::{
 };
 
 use oxc_allocator::{Box as ArenaBox, Vec as ArenaVec};
+use oxc_ast_macros::ast_meta;
 use oxc_span::Span;
 
 use crate::ast::*;
@@ -83,6 +84,8 @@ impl serde_json::ser::Formatter for EcmaFormatter {
 // --------------------
 
 /// Serialized as `null`.
+#[ast_meta]
+#[estree(ts_type = "null")]
 pub struct Null<'b, T>(#[expect(dead_code)] pub &'b T);
 
 impl<T> Serialize for Null<'_, T> {
@@ -92,6 +95,8 @@ impl<T> Serialize for Null<'_, T> {
 }
 
 /// Serialized as `true`.
+#[ast_meta]
+#[estree(ts_type = "true")]
 pub struct True<'b, T>(#[expect(dead_code)] pub &'b T);
 
 impl<T> Serialize for True<'_, T> {
@@ -101,6 +106,8 @@ impl<T> Serialize for True<'_, T> {
 }
 
 /// Serialized as `false`.
+#[ast_meta]
+#[estree(ts_type = "false")]
 pub struct False<'b, T>(#[expect(dead_code)] pub &'b T);
 
 impl<T> Serialize for False<'_, T> {
@@ -110,6 +117,8 @@ impl<T> Serialize for False<'_, T> {
 }
 
 /// Serialized as `"in"`.
+#[ast_meta]
+#[estree(ts_type = "'in'")]
 pub struct In<'b, T>(#[expect(dead_code)] pub &'b T);
 
 impl<T> Serialize for In<'_, T> {
@@ -119,6 +128,8 @@ impl<T> Serialize for In<'_, T> {
 }
 
 /// Serialized as `"init"`.
+#[ast_meta]
+#[estree(ts_type = "'init'")]
 pub struct Init<'b, T>(#[expect(dead_code)] pub &'b T);
 
 impl<T> Serialize for Init<'_, T> {
@@ -132,6 +143,8 @@ impl<T> Serialize for Init<'_, T> {
 // --------------------
 
 /// Serializer for `raw` field of `BooleanLiteral`.
+#[ast_meta]
+#[estree(ts_type = "string | null")]
 pub struct BooleanLiteralRaw<'b>(pub &'b BooleanLiteral);
 
 impl Serialize for BooleanLiteralRaw<'_> {
@@ -148,6 +161,8 @@ impl Serialize for BooleanLiteralRaw<'_> {
 }
 
 /// Serializer for `raw` field of `NullLiteral`.
+#[ast_meta]
+#[estree(ts_type = "'null' | null")]
 pub struct NullLiteralRaw<'b>(pub &'b NullLiteral);
 
 impl Serialize for NullLiteralRaw<'_> {
@@ -158,6 +173,8 @@ impl Serialize for NullLiteralRaw<'_> {
 }
 
 /// Serializer for `bigint` field of `BigIntLiteral`.
+#[ast_meta]
+#[estree(ts_type = "string")]
 pub struct BigIntLiteralBigint<'a, 'b>(pub &'b BigIntLiteral<'a>);
 
 impl Serialize for BigIntLiteralBigint<'_, '_> {
@@ -167,6 +184,19 @@ impl Serialize for BigIntLiteralBigint<'_, '_> {
     }
 }
 
+/// Serializer for `value` field of `BigIntLiteral`.
+///
+/// Serialized as `null` in JSON, but updated on JS side to contain a `BigInt`.
+#[ast_meta]
+#[estree(ts_type = "BigInt")]
+pub struct BigIntLiteralValue<'a, 'b>(#[expect(dead_code)] pub &'b BigIntLiteral<'a>);
+
+impl Serialize for BigIntLiteralValue<'_, '_> {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_none()
+    }
+}
+
 /// Serializer for `regex` field of `RegExpLiteral`.
 pub struct RegExpLiteralRegex<'a, 'b>(pub &'b RegExpLiteral<'a>);
 
@@ -190,6 +220,19 @@ impl Serialize for RegExpLiteralRegex<'_, '_> {
     }
 }
 
+/// Serializer for `value` field of `RegExpLiteral`.
+///
+/// Serialized as `null` in JSON, but updated on JS side to contain a `RegExp` if the regexp is valid.
+#[ast_meta]
+#[estree(ts_type = "RegExp | null")]
+pub struct RegExpLiteralValue<'a, 'b>(#[expect(dead_code)] pub &'b RegExpLiteral<'a>);
+
+impl Serialize for RegExpLiteralValue<'_, '_> {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_none()
+    }
+}
+
 impl Serialize for RegExpFlags {
     fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
         serializer.serialize_str(&self.to_string())

tasks/ast_tools/src/derives/estree.rs

@@ -8,7 +8,7 @@ use syn::{parse_str, Expr};
 
 use crate::{
     schema::{Def, EnumDef, FieldDef, Schema, StructDef, TypeDef, VariantDef, Visibility},
-    utils::{create_ident, number_lit},
+    utils::number_lit,
     Result,
 };
 
@@ -34,14 +34,17 @@ impl Derive for DeriveESTree {
         "estree".to_string()
     }
 
-    /// Register that accept `#[estree]` attr on structs, enums, struct fields, or enum variants.
+    /// Register that accept `#[estree]` attr on structs, enums, struct fields, enum variants,
+    /// or meta types.
     /// Allow attr on structs and enums which don't derive this trait.
     /// Also accept `#[ts]` attr on struct fields and enum variants.
     fn attrs(&self) -> &[(&'static str, AttrPositions)] {
         &[
             (
                 "estree",
-                attr_positions!(StructMaybeDerived | EnumMaybeDerived | StructField | EnumVariant),
+                attr_positions!(
+                    StructMaybeDerived | EnumMaybeDerived | StructField | EnumVariant | Meta
+                ),
             ),
             ("ts", attr_positions!(StructField | EnumVariant)),
         ]
@@ -118,7 +121,6 @@ fn parse_estree_attr(location: AttrLocation, part: AttrPart) -> Result<()> {
                     struct_def.estree.add_fields.push((name, value));
                 }
             }
-            AttrPart::String("add_ts", value) => struct_def.estree.add_ts = Some(value),
             AttrPart::String("custom_ts_def", value) => {
                 struct_def.estree.custom_ts_def = Some(value);
             }
@@ -184,6 +186,11 @@ fn parse_estree_attr(location: AttrLocation, part: AttrPart) -> Result<()> {
             }
             _ => return Err(()),
         },
+        // `#[estree]` attr on meta type
+        AttrLocation::Meta(meta) => match part {
+            AttrPart::String("ts_type", ts_type) => meta.estree.ts_type = Some(ts_type),
+            _ => return Err(()),
+        },
         _ => unreachable!(),
     }
 
@@ -233,9 +240,10 @@ fn generate_body_for_struct(struct_def: &StructDef, schema: &Schema) -> TokenStr
     };
 
     // Add any additional manually-defined fields
-    let add_fields = struct_def.estree.add_fields.iter().map(|(name, converter)| {
-        let converter = create_ident(converter);
-        quote!( map.serialize_entry(#name, &crate::serialize::#converter(self))?; )
+    let add_fields = struct_def.estree.add_fields.iter().map(|(name, converter_name)| {
+        let converter = schema.meta_by_name(converter_name);
+        let converter_path = converter.import_path_from_crate(krate, schema);
+        quote!( map.serialize_entry(#name, &#converter_path(self))?; )
     });
 
     let stmts = gen.stmts;

tasks/ast_tools/src/generators/typescript.rs

@@ -113,8 +113,12 @@ fn generate_ts_type_def_for_struct(struct_def: &StructDef, schema: &Schema) -> O
         }
     }
 
-    if let Some(add_ts) = struct_def.estree.add_ts.as_deref() {
-        fields_str.push_str(&format!("\n\t{add_ts};"));
+    for (add_field_name, converter_name) in &struct_def.estree.add_fields {
+        let converter = schema.meta_by_name(converter_name);
+        let Some(add_field_ts_type) = &converter.estree.ts_type else {
+            panic!("No `ts_type` provided for ESTree converter `{}`", converter.name());
+        };
+        fields_str.push_str(&format!("\n\t{add_field_name}: {add_field_ts_type};"));
     }
 
     let ts_def = if extends.is_empty() {

tasks/ast_tools/src/main.rs

@@ -212,6 +212,7 @@ static SOURCE_PATHS: &[&str] = &[
     "crates/oxc_ast/src/ast/jsx.rs",
     "crates/oxc_ast/src/ast/ts.rs",
     "crates/oxc_ast/src/ast/comment.rs",
+    "crates/oxc_ast/src/serialize.rs",
     "crates/oxc_syntax/src/lib.rs",
     "crates/oxc_syntax/src/number.rs",
     "crates/oxc_syntax/src/operator.rs",

tasks/ast_tools/src/schema/extensions/estree.rs

@@ -10,10 +10,8 @@ pub struct ESTreeStruct {
     pub custom_serialize: bool,
     /// Additional fields to add to struct in ESTree AST.
     /// `(name, converter)` where `name` is the name of the field, and `converter` is name of
-    /// a converter type in the same crate, accessible as `crate::serialize::<converter>`.
+    /// a converter meta type.
     pub add_fields: Vec<(String, String)>,
-    /// Additional fields to add to TS type definition
-    pub add_ts: Option<String>,
     /// TS alias.
     /// e.g. `#[estree(ts_alias = "null")]` means this type won't have a type def generated,
     /// and any struct / enum referencing it will substitute `null` as the type.
@@ -64,3 +62,9 @@ pub struct ESTreeEnumVariant {
     pub rename: Option<String>,
     pub is_ts: bool,
 }
+
+/// Configuration for ESTree generator on a meta type.
+#[derive(Default, Debug)]
+pub struct ESTreeMeta {
+    pub ts_type: Option<String>,
+}