Skip to main content

nodejs/stdlib/
events.rs

1//! Node `events` module: `EventEmitter`. The emitter is an object tagged
2//! `@@native = "EventEmitter"` with a hidden `@@on` map (event name → the
3//! ordered RAW listener array: a `once` registration is stored as node's
4//! `_onceWrap` wrapper, whose `.listener` is the function registered). `emit` collects listeners, releases the host borrow, then
5//! invokes each so callbacks can re-enter the host.
6
7use super::arg_str;
8use crate::host::{call_method, invoke, with_host, JsObj};
9use fusevm::Value;
10use indexmap::IndexMap;
11
12/// Construct a fresh `EventEmitter`.
13pub fn new_emitter() -> Value {
14    with_host(|h| {
15        let on = h.new_object(IndexMap::new());
16        let mut m = IndexMap::new();
17        m.insert("@@native".into(), h.new_str("EventEmitter"));
18        m.insert("@@on".into(), on);
19        h.new_object(m)
20    })
21}
22
23/// The EventEmitter method names, exposed so `EventEmitter.prototype` can be
24/// enumerated / copied (express does `mixin(app, EventEmitter.prototype)` to make
25/// its `app` *function* an emitter).
26pub const METHODS: &[&str] = &[
27    "on",
28    "addListener",
29    "prependListener",
30    "once",
31    "prependOnceListener",
32    "emit",
33    "removeListener",
34    "off",
35    "removeAllListeners",
36    "listenerCount",
37    "listeners",
38    "rawListeners",
39    "eventNames",
40    "setMaxListeners",
41    "getMaxListeners",
42];
43
44/// Whether `name` is one of `EventEmitter.prototype`'s methods (measured:
45/// `CLASS_PROTO_ARITY`, which also makes an alias the method it is, so
46/// `EventEmitter.prototype.on === EventEmitter.prototype.addListener`).
47pub fn is_proto_method(name: &str) -> bool {
48    let key = format!("@proto:EventEmitter:{name}");
49    crate::core_arity::CLASS_PROTO_ARITY
50        .binary_search_by(|(k, _, _)| (*k).cmp(key.as_str()))
51        .is_ok()
52}
53
54/// Whether an emitter-backed native instance tagged `tag` inherits `name` from
55/// `EventEmitter.prototype` — so reading it gives that very function — rather
56/// than from a class that overrides it (a Readable's `on`, measured:
57/// `EMITTER_OVERRIDES`).
58pub fn inherits_proto_method(tag: &str, name: &str) -> bool {
59    let t = crate::core_arity::EMITTER_OVERRIDES;
60    match t.binary_search_by(|(k, _)| (*k).cmp(tag)) {
61        Ok(i) => !t[i].1.contains(&name) && is_proto_method(name),
62        Err(_) => false,
63    }
64}
65
66/// The internal key an event name registers under.
67///
68/// `ToPropertyKey`, not `String(name)`: a SYMBOL event name is a distinct key
69/// (`@@sym:<id>`), so `on(sym, f)` and `on("Symbol(desc)", f)` are different
70/// events and `eventNames()` can hand the symbol itself back. Rendering it
71/// collapsed the two and made every symbol listener unremovable by its symbol.
72fn event_key(args: &[Value]) -> String {
73    with_host(|h| h.property_key(args.first().unwrap_or(&Value::Undef)))
74}
75
76pub fn instance_call(recv: &Value, method: &str, args: Vec<Value>) -> Result<Value, String> {
77    match method {
78        // Both the event-name coercion and the listener lookup re-enter the host,
79        // so they must resolve BEFORE the `with_host` that allocates the array —
80        // nesting them inside it panics with `RefCell already borrowed`. That was
81        // latent until `listeners` became reachable on a socket/request/stream.
82        // `rawListeners` is the stored list, once-WRAPPERS included;
83        // `listeners` unwraps each one (`unwrapListeners`).
84        "rawListeners" => {
85            let items = listeners(recv, &event_key(&args));
86            Ok(with_host(|h| h.new_array(items)))
87        }
88        "listeners" => {
89            let items = unwrapped_listeners(recv, &event_key(&args))?;
90            Ok(with_host(|h| h.new_array(items)))
91        }
92        // The cap is not enforced (nothing here warns on listener count), but it
93        // must still read back what was set — `setMaxListeners` used to discard
94        // the value and `getMaxListeners` always answered the default 10.
95        "setMaxListeners" => {
96            // `validateNumber(n, 'setMaxListeners', 0)`.
97            let arg = args.first().cloned().unwrap_or(Value::Undef);
98            let n = match arg {
99                Value::Float(n) => n,
100                Value::Int(n) => n as f64,
101                _ => {
102                    return Err(crate::host::invalid_arg_type(
103                        "setMaxListeners",
104                        "argument",
105                        "number",
106                        &arg,
107                    ))
108                }
109            };
110            if n.is_nan() || n < 0.0 {
111                return Err(crate::host::coded_error(
112                    "RangeError",
113                    "ERR_OUT_OF_RANGE",
114                    &format!(
115                        "The value of \"setMaxListeners\" is out of range. It must be >= 0. Received {}",
116                        crate::host::fmt_number(n)
117                    ),
118                ));
119            }
120            with_host(|h| {
121                let nv = Value::Float(n);
122                match h.get_mut(recv) {
123                    Some(JsObj::Object(p)) => {
124                        p.insert("@@maxListeners".into(), nv);
125                    }
126                    _ => h.set_fn_prop(recv, "@@maxListeners", nv),
127                }
128            });
129            Ok(recv.clone())
130        }
131        "getMaxListeners" => Ok(with_host(|h| match named_map(h, recv, "@@maxListeners") {
132            Some(v @ (Value::Float(_) | Value::Int(_))) => v,
133            _ => Value::Float(10.0),
134        })),
135        "on" | "addListener" | "prependListener" | "once" | "prependOnceListener" => {
136            let once = matches!(method, "once" | "prependOnceListener");
137            let prepend = method.starts_with("prepend");
138            let name = event_key(&args);
139            let event = args.first().cloned().unwrap_or(Value::Undef);
140            let mut f = args.get(1).cloned().unwrap_or(Value::Undef);
141            check_listener(&f)?;
142            // `once` registers `_onceWrap(this, type, listener)` in the
143            // listener's place, so `rawListeners` sees the wrapper.
144            if once {
145                f = once_wrap(recv, &event, &f)?;
146            }
147            // `newListener` fires BEFORE the listener is added, so a handler for
148            // it sees the emitter without the new listener and can add its own
149            // ahead of it. It is handed `listener.listener ?? listener`.
150            if name != "newListener" && !listeners(recv, "newListener").is_empty() {
151                let shown = original_listener(&f)?;
152                emit(recv, "newListener", &[event, shown])?;
153            }
154            add_to_list(recv, &name, f, prepend);
155            warn_max_listeners(recv, &name, args.first().unwrap_or(&Value::Undef));
156            Ok(recv.clone())
157        }
158        "emit" => emit(
159            recv,
160            &event_key(&args),
161            &args.get(1..).map(|s| s.to_vec()).unwrap_or_default(),
162        ),
163        "removeListener" | "off" => {
164            let event = args.first().cloned().unwrap_or(Value::Undef);
165            let f = args.get(1).cloned().unwrap_or(Value::Undef);
166            check_listener(&f)?;
167            remove_listener(recv, &event_key(&args), event, &f)?;
168            Ok(recv.clone())
169        }
170        "removeAllListeners" => {
171            if args.is_empty() {
172                remove_all_listeners(recv, None)?;
173            } else {
174                let event = args.first().cloned().unwrap_or(Value::Undef);
175                remove_all_listeners(recv, Some((event_key(&args), event)))?;
176            }
177            Ok(recv.clone())
178        }
179        // `listenerCount(type, listener)` counts the registrations of one
180        // function, a once-wrapper counting for the function it wraps.
181        "listenerCount" => {
182            let list = listeners(recv, &event_key(&args));
183            let wanted = args.get(1).cloned().unwrap_or(Value::Undef);
184            if with_host(|h| h.is_nullish(&wanted)) {
185                return Ok(Value::Float(list.len() as f64));
186            }
187            let mut matching = 0;
188            for l in &list {
189                if *l == wanted || crate::builtins::get_property(l, "listener")? == wanted {
190                    matching += 1;
191                }
192            }
193            Ok(Value::Float(matching as f64))
194        }
195        // A SYMBOL event name comes back as the symbol itself, not as its
196        // `Symbol(desc)` rendering — `emitter.on(sym, f)` then `eventNames()`
197        // has to hand back something `emitter.off(name, f)` accepts. Strings
198        // come first, then symbols, which is the own-key order node reports.
199        "eventNames" => Ok(with_host(|h| {
200            let mut keys: Vec<String> = Vec::new();
201            if let Some(JsObj::Object(p)) = named_map(h, recv, "@@on").and_then(|v| h.get(&v)) {
202                keys.extend(p.keys().cloned());
203            }
204            let (syms, strs): (Vec<String>, Vec<String>) = keys
205                .into_iter()
206                .partition(|k| crate::host::is_symbol_key(k));
207            let mut names: Vec<Value> = strs.into_iter().map(|k| h.new_str(k)).collect();
208            names.extend(
209                syms.iter()
210                    .filter_map(|k| h.symbol_of_key(k))
211                    .collect::<Vec<Value>>(),
212            );
213            h.new_array(names)
214        })),
215        _ => Err(crate::host::type_error(&format!(
216            "emitter.{method} is not a function"
217        ))),
218    }
219}
220
221/// `_addListener`'s leak check: once an event has more listeners than the
222/// emitter's cap (`setMaxListeners`, default 10; `0` disables it), emit ONE
223/// `MaxListenersExceededWarning` for that event. The cap used to be stored and
224/// never consulted.
225fn warn_max_listeners(recv: &Value, key: &str, event: &Value) {
226    let max = with_host(|h| match named_map(h, recv, "@@maxListeners") {
227        Some(v @ (Value::Float(_) | Value::Int(_))) => h.to_number(&v),
228        _ => 10.0,
229    });
230    let count = listeners(recv, key).len();
231    if max <= 0.0 || count as f64 <= max {
232        return;
233    }
234    let marker = format!("@@warned:{key}");
235    if with_host(|h| named_map(h, recv, &marker).is_some()) {
236        return;
237    }
238    with_host(|h| match h.get_mut(recv) {
239        Some(JsObj::Object(p)) => {
240            p.insert(marker, Value::Bool(true));
241        }
242        _ => h.set_fn_prop(recv, &marker, Value::Bool(true)),
243    });
244    let (event, target) = with_host(|h| {
245        let event = h.str_of(event);
246        let target = if crate::host::is_callable(h, recv) {
247            format!("[Function: {}]", h.callable_name(recv))
248        } else {
249            match h.ctor_name(recv) {
250                n if n.is_empty() => "[EventEmitter]".to_string(),
251                n => format!("[{n}]"),
252            }
253        };
254        (event, target)
255    });
256    super::process::emit_warning(
257        "MaxListenersExceededWarning",
258        None,
259        &format!(
260            "Possible EventEmitter memory leak detected. {count} {event} listeners added to {target}. \
261             MaxListeners is {}. Use emitter.setMaxListeners() to increase limit",
262            crate::host::fmt_number(max)
263        ),
264        None,
265    );
266}
267
268/// Read a hidden emitter field (`@@on`, `@@maxListeners`). Works for a plain emitter
269/// object AND for a function/class receiver (express's `app` is a function whose
270/// emitter maps live in the fn-prop side table).
271fn named_map(h: &crate::host::JsHost, recv: &Value, which: &str) -> Option<Value> {
272    match h.get(recv) {
273        Some(JsObj::Object(p)) => p.get(which).cloned(),
274        Some(JsObj::Func(_)) | Some(JsObj::Class(_)) => h.fn_prop(recv, which),
275        _ => None,
276    }
277}
278
279/// Store a hidden emitter field, routing to props or the fn-prop table.
280fn set_named_map(h: &mut crate::host::JsHost, recv: &Value, which: &str, val: Value) {
281    match h.get(recv) {
282        Some(JsObj::Func(_)) | Some(JsObj::Class(_)) => h.set_fn_prop(recv, which, val),
283        _ => {
284            if let Some(JsObj::Object(p)) = h.get_mut(recv) {
285                p.insert(which.to_string(), val);
286            }
287        }
288    }
289}
290
291/// Register `f` for `name`. Every listener — a once-wrapper included — goes
292/// into the one ordered `@@on` list, so registration order is firing order.
293fn add_to_list(recv: &Value, name: &str, f: Value, prepend: bool) {
294    with_host(|h| {
295        // Lazily create the listener map (a mixed-in function emitter has none).
296        let map = match named_map(h, recv, "@@on") {
297            Some(m) => m,
298            None => {
299                let m = h.new_object(IndexMap::new());
300                set_named_map(h, recv, "@@on", m.clone());
301                m
302            }
303        };
304        // Ensure `map[name]` is an array, then push.
305        let arr = match h.get(&map) {
306            Some(JsObj::Object(p)) => p.get(name).cloned(),
307            _ => None,
308        };
309        let arr = match arr {
310            Some(a) if matches!(h.get(&a), Some(JsObj::Array(_))) => a,
311            _ => {
312                let a = h.new_array(Vec::new());
313                if let Some(JsObj::Object(p)) = h.get_mut(&map) {
314                    p.insert(name.to_string(), a.clone());
315                }
316                a
317            }
318        };
319        if let Some(JsObj::Array(items)) = h.get_mut(&arr) {
320            // `prependListener` puts the handler FIRST.
321            if prepend {
322                items.insert(0, f);
323            } else {
324                items.push(f);
325            }
326        }
327    });
328}
329
330/// Drop the entry at `index` from `name`'s listener list.
331fn remove_at(recv: &Value, name: &str, index: usize) {
332    with_host(|h| {
333        let Some(map) = named_map(h, recv, "@@on") else {
334            return;
335        };
336        let arr = match h.get(&map) {
337            Some(JsObj::Object(p)) => p.get(name).cloned(),
338            _ => None,
339        };
340        let mut emptied = false;
341        if let Some(JsObj::Array(items)) = arr.and_then(|a| h.get_mut(&a)) {
342            if index < items.len() {
343                items.remove(index);
344            }
345            emptied = items.is_empty();
346        }
347        // An emptied list must take its KEY with it, or `eventNames()` keeps
348        // reporting an event nothing is listening for.
349        if emptied {
350            if let Some(JsObj::Object(p)) = h.get_mut(&map) {
351                p.shift_remove(name);
352            }
353        }
354    });
355}
356
357/// The RAW listener list for `name` (`rawListeners`): once-wrappers as stored.
358fn listeners(recv: &Value, name: &str) -> Vec<Value> {
359    with_host(|h| {
360        let mut out = Vec::new();
361        if let Some(map) = named_map(h, recv, "@@on") {
362            if let Some(JsObj::Object(p)) = h.get(&map) {
363                if let Some(a) = p.get(name) {
364                    if let Some(JsObj::Array(items)) = h.get(a) {
365                        out.extend(items.iter().cloned());
366                    }
367                }
368            }
369        }
370        out
371    })
372}
373
374/// `unwrapListeners`: each entry's `.listener`, or the entry itself.
375fn unwrapped_listeners(recv: &Value, name: &str) -> Result<Vec<Value>, String> {
376    listeners(recv, name)
377        .iter()
378        .map(original_listener)
379        .collect()
380}
381
382/// `listener.listener || listener` — the function a once-wrapper stands for.
383fn original_listener(f: &Value) -> Result<Value, String> {
384    let inner = crate::builtins::get_property(f, "listener")?;
385    Ok(if with_host(|h| h.truthy(&inner)) {
386        inner
387    } else {
388        f.clone()
389    })
390}
391
392/// `_onceWrap(target, type, listener)` from `lib/events.js`, verbatim: a
393/// closure that removes itself before its first call and ignores any later
394/// one, carrying the wrapped function as `.listener`.
395const ONCE_WRAP_SRC: &str = "(function _onceWrap(target, type, listener) {\n\
396  let fired = false;\n\
397  function wrapper(...args) {\n\
398    if (fired) return;\n\
399    fired = true;\n\
400    target.removeListener(type, wrapper);\n\
401    return Reflect.apply(listener, target, args);\n\
402  }\n\
403  wrapper.listener = listener;\n\
404  return wrapper;\n\
405})";
406
407fn once_wrap(target: &Value, event: &Value, f: &Value) -> Result<Value, String> {
408    thread_local! {
409        static FACTORY: std::cell::RefCell<Option<Value>> = const { std::cell::RefCell::new(None) };
410    }
411    let factory = match FACTORY.with(|c| c.borrow().clone()) {
412        Some(f) => f,
413        None => {
414            let made = crate::eval_internal(ONCE_WRAP_SRC)?;
415            FACTORY.with(|c| *c.borrow_mut() = Some(made.clone()));
416            made
417        }
418    };
419    invoke(
420        &factory,
421        vec![target.clone(), event.clone(), f.clone()],
422        None,
423    )
424}
425
426/// `removeListener(type, listener)`, ported from `lib/events.js`. A lone
427/// listener is matched by itself or its `.listener`, and the `removeListener`
428/// event is handed `list.listener || listener`; in a longer list the LAST
429/// match goes, and the event is handed `listener` exactly as passed — which
430/// is the wrapper when a once-wrapper removes itself.
431fn remove_listener(recv: &Value, name: &str, event: Value, f: &Value) -> Result<(), String> {
432    let list = listeners(recv, name);
433    let removed = if list.len() == 1 {
434        let inner = if list[0] == *f {
435            None
436        } else {
437            Some(crate::builtins::get_property(&list[0], "listener")?)
438        };
439        match inner {
440            None => Some(original_listener(&list[0])?),
441            Some(inner) if inner == *f => Some(original_listener(&list[0])?),
442            Some(_) => None,
443        }
444        .inspect(|_| remove_at(recv, name, 0))
445    } else {
446        let mut position = None;
447        for (i, l) in list.iter().enumerate().rev() {
448            if *l == *f || crate::builtins::get_property(l, "listener")? == *f {
449                position = Some(i);
450                break;
451            }
452        }
453        position.map(|i| {
454            remove_at(recv, name, i);
455            f.clone()
456        })
457    };
458    // `removeListener` fires AFTER the removal, and only when one happened.
459    if let Some(shown) = removed {
460        if !listeners(recv, "removeListener").is_empty() {
461            emit(recv, "removeListener", &[event, shown])?;
462        }
463    }
464    Ok(())
465}
466
467/// `removeAllListeners([type])`, ported from `lib/events.js`. With nobody
468/// listening for `removeListener` the lists are simply dropped; otherwise
469/// every listener goes through `removeListener` (LIFO within an event), every
470/// event but `removeListener` first, so each removal is announced.
471fn remove_all_listeners(recv: &Value, event: Option<(String, Value)>) -> Result<(), String> {
472    if listeners(recv, "removeListener").is_empty() {
473        with_host(|h| {
474            if let Some(map) = named_map(h, recv, "@@on") {
475                if let Some(JsObj::Object(p)) = h.get_mut(&map) {
476                    match &event {
477                        Some((name, _)) => {
478                            p.shift_remove(name);
479                        }
480                        None => p.clear(),
481                    }
482                }
483            }
484        });
485        return Ok(());
486    }
487    let Some((name, event)) = event else {
488        let keys: Vec<(String, Value)> = with_host(|h| {
489            let names: Vec<String> = match named_map(h, recv, "@@on").and_then(|m| h.get(&m)) {
490                Some(JsObj::Object(p)) => p.keys().cloned().collect(),
491                _ => Vec::new(),
492            };
493            // `ReflectOwnKeys` order: string keys, then symbols.
494            let (syms, strs): (Vec<String>, Vec<String>) = names
495                .into_iter()
496                .partition(|k| crate::host::is_symbol_key(k));
497            strs.into_iter()
498                .chain(syms)
499                .filter(|k| k != "removeListener")
500                .map(|k| {
501                    let v = h.symbol_of_key(&k).unwrap_or_else(|| h.new_str(k.clone()));
502                    (k, v)
503                })
504                .collect()
505        });
506        for key in keys {
507            remove_all_listeners(recv, Some(key))?;
508        }
509        let rl = with_host(|h| h.new_str("removeListener"));
510        remove_all_listeners(recv, Some(("removeListener".into(), rl)))?;
511        return remove_all_listeners(recv, None);
512    };
513    for f in listeners(recv, &name).iter().rev() {
514        remove_listener(recv, &name, event.clone(), f)?;
515    }
516    Ok(())
517}
518
519/// `checkListener`: every registration and removal refuses a non-function.
520fn check_listener(f: &Value) -> Result<(), String> {
521    if with_host(|h| crate::host::is_callable(h, f)) {
522        return Ok(());
523    }
524    Err(crate::host::invalid_arg_type(
525        "listener", "argument", "function", f,
526    ))
527}
528
529fn emit(recv: &Value, name: &str, args: &[Value]) -> Result<Value, String> {
530    // `EventEmitter.errorMonitor` listeners see every `error` FIRST, without
531    // counting as a handler: an error with only a monitor still throws.
532    if name == "error" {
533        let monitor = with_host(|h| {
534            let sym = h.internal_symbol("events.errorMonitor");
535            h.property_key(&sym)
536        });
537        if !listeners(recv, &monitor).is_empty() {
538            emit(recv, &monitor, args)?;
539        }
540    }
541    let to_call = listeners(recv, name);
542    // An `error` event with no listener THROWS rather than being dropped. This
543    // is how node surfaces a failed socket, stream or request, and swallowing
544    // it turned every such failure into silence.
545    if name == "error" && to_call.is_empty() {
546        let err = args.first().cloned().unwrap_or(Value::Undef);
547        // Only an `Error` is thrown as itself; anything else is wrapped in
548        // ERR_UNHANDLED_ERROR quoting its inspection, with the value kept as
549        // `context` (lib/events.js).
550        let error_ctor = crate::builtins::global_binding("Error").unwrap_or(Value::Undef);
551        if !crate::host::instance_of(&err, &error_ctor).unwrap_or(false) {
552            let shown = crate::host::inspect_js(&err)?;
553            let msg = crate::host::coded_error(
554                "Error",
555                "ERR_UNHANDLED_ERROR",
556                &format!("Unhandled error. ({shown})"),
557            );
558            let wrapped = with_host(|h| crate::builtins::synth_error(h, &msg));
559            crate::builtins::set_property_pub(&wrapped, "context", err)?;
560            with_host(|h| h.exc = Some(wrapped));
561            return Err(msg);
562        }
563        let msg = with_host(|h| {
564            h.exc = Some(err.clone());
565            crate::builtins::error_string(h, &err)
566        });
567        return Err(msg);
568    }
569    let had = !to_call.is_empty();
570    for f in to_call {
571        invoke(&f, args.to_vec(), Some(recv.clone()))?;
572    }
573    // Settle any `events.once(emitter, name)` promise waiters for this event.
574    resolve_waiters(recv, name, args);
575    Ok(Value::Bool(had))
576}
577
578// ── `events.once` promise waiters ───────────────────────────────────────────
579//
580// `once(emitter, name)` returns a real Promise. We cannot register a Rust
581// closure as a JS listener (listeners must be callable Values), so instead a
582// pending promise is parked under the emitter's hidden `@@waiters` map keyed by
583// event name; `emit` (above) settles them. On `error`, waiters of every other
584// event reject with the error, mirroring Node's `once` semantics.
585
586/// Park `promise` to be resolved when `name` next fires on `recv`.
587fn add_waiter(recv: &Value, name: &str, promise: Value) {
588    with_host(|h| {
589        let map = match waiter_map(h, recv) {
590            Some(m) => m,
591            None => {
592                let m = h.new_object(IndexMap::new());
593                if let Some(JsObj::Object(p)) = h.get_mut(recv) {
594                    p.insert("@@waiters".into(), m.clone());
595                }
596                m
597            }
598        };
599        let existing = match h.get(&map) {
600            Some(JsObj::Object(p)) => p.get(name).cloned(),
601            _ => None,
602        };
603        let arr = match existing {
604            Some(a) if matches!(h.get(&a), Some(JsObj::Array(_))) => a,
605            _ => {
606                let a = h.new_array(Vec::new());
607                if let Some(JsObj::Object(p)) = h.get_mut(&map) {
608                    p.insert(name.to_string(), a.clone());
609                }
610                a
611            }
612        };
613        if let Some(JsObj::Array(items)) = h.get_mut(&arr) {
614            items.push(promise);
615        }
616    });
617}
618
619fn waiter_map(h: &crate::host::JsHost, recv: &Value) -> Option<Value> {
620    match h.get(recv) {
621        Some(JsObj::Object(p)) => p.get("@@waiters").cloned(),
622        _ => None,
623    }
624}
625
626/// Remove and return the promises parked on `name`.
627fn take_waiters(recv: &Value, name: &str) -> Vec<Value> {
628    with_host(|h| {
629        let Some(map) = waiter_map(h, recv) else {
630            return Vec::new();
631        };
632        let arr = match h.get_mut(&map) {
633            Some(JsObj::Object(p)) => p.shift_remove(name),
634            _ => None,
635        };
636        let Some(arr) = arr else { return Vec::new() };
637        match h.get(&arr) {
638            Some(JsObj::Array(items)) => items.clone(),
639            _ => Vec::new(),
640        }
641    })
642}
643
644/// Remove and return every parked promise except those on `keep`.
645fn take_waiters_except(recv: &Value, keep: &str) -> Vec<Value> {
646    with_host(|h| {
647        let Some(map) = waiter_map(h, recv) else {
648            return Vec::new();
649        };
650        let keys: Vec<String> = match h.get(&map) {
651            Some(JsObj::Object(p)) => p.keys().filter(|k| k.as_str() != keep).cloned().collect(),
652            _ => Vec::new(),
653        };
654        let mut out = Vec::new();
655        for k in keys {
656            let arr = match h.get_mut(&map) {
657                Some(JsObj::Object(p)) => p.shift_remove(&k),
658                _ => None,
659            };
660            if let Some(arr) = arr {
661                if let Some(JsObj::Array(items)) = h.get(&arr) {
662                    out.extend(items.iter().cloned());
663                }
664            }
665        }
666        out
667    })
668}
669
670fn resolve_waiters(recv: &Value, name: &str, args: &[Value]) {
671    let waiting = take_waiters(recv, name);
672    if !waiting.is_empty() {
673        let arr = with_host(|h| h.new_array(args.to_vec()));
674        for p in &waiting {
675            if let Some(id) = with_host(|h| h.promise_id(p)) {
676                crate::host::resolve_promise_val(id, arr.clone());
677            }
678        }
679    }
680    if name == "error" {
681        let err = args.first().cloned().unwrap_or(Value::Undef);
682        for p in take_waiters_except(recv, "error") {
683            if let Some(id) = with_host(|h| h.promise_id(&p)) {
684                crate::host::reject_promise_val(id, err.clone());
685            }
686        }
687    }
688}
689
690// ── static module functions (`require('events').once`, `.listenerCount`, …) ──
691
692/// Static functions on the `events` module namespace. `EventEmitter` (the
693/// self-ref ctor) and `EventEmitterAsyncResource` are handled by the parent.
694pub const STATIC_METHODS: &[&str] = &[
695    "once",
696    "on",
697    "listenerCount",
698    "getEventListeners",
699    "getMaxListeners",
700    "setMaxListeners",
701    "addAbortListener",
702    "init",
703];
704
705/// Dispatch a static `events.<method>(...)`. Returns `None` for names this
706/// module does not own (e.g. `EventEmitter`) so the parent's specific arm wins.
707pub fn static_call(method: &str, args: &[Value]) -> Option<Result<Value, String>> {
708    let emitter = args.first().cloned().unwrap_or(Value::Undef);
709    Some(match method {
710        "once" => Ok(once_static(emitter, &arg_str(args, 1))),
711        "on" => events_on(args),
712        "listenerCount" => Ok(Value::Float(
713            listeners(&emitter, &arg_str(args, 1)).len() as f64
714        )),
715        // `listeners` takes the host, so calling it INSIDE `with_host` borrowed
716        // the same RefCell twice and aborted the process with "RefCell already
717        // borrowed" — a Rust panic, not a throw, so no JS `try` caught it.
718        // Collect first, then borrow to build the array.
719        "getEventListeners" => {
720            let found = match unwrapped_listeners(&emitter, &arg_str(args, 1)) {
721                Ok(found) => found,
722                Err(e) => return Some(Err(e)),
723            };
724            Ok(with_host(|h| h.new_array(found)))
725        }
726        // No per-emitter cap is tracked; report Node's default and accept sets.
727        "getMaxListeners" => Ok(Value::Float(10.0)),
728        "setMaxListeners" => Ok(Value::Undef),
729        "addAbortListener" => Ok(add_abort_listener(args)),
730        "init" => Ok(init_emitter(emitter)),
731        _ => return None,
732    })
733}
734
735/// `events.once(emitter, name)` → a Promise resolving with the event args (or
736/// rejecting with the error if `error` fires first).
737fn once_static(emitter: Value, name: &str) -> Value {
738    let p = with_host(|h| h.new_promise());
739    add_waiter(&emitter, name, p.clone());
740    p
741}
742
743/// `EventEmitter.init(emitter)` — ensure the hidden emitter maps exist on
744/// `emitter` (used when mixing the emitter surface into a plain object).
745fn init_emitter(emitter: Value) -> Value {
746    with_host(|h| {
747        let has = matches!(h.get(&emitter), Some(JsObj::Object(p)) if p.contains_key("@@on"));
748        if !has {
749            let on = h.new_object(IndexMap::new());
750            let native = h.new_str("EventEmitter");
751            if let Some(JsObj::Object(p)) = h.get_mut(&emitter) {
752                p.entry("@@native".to_string()).or_insert(native);
753                p.insert("@@on".to_string(), on);
754            }
755        }
756    });
757    emitter
758}
759
760/// `events.addAbortListener(signal, listener)`: a one-time `abort` listener on
761/// the signal, or — if it is already aborted — `listener` on a microtask. The
762/// returned disposable is a plain object: this runtime has no `Symbol.dispose`.
763fn add_abort_listener(args: &[Value]) -> Value {
764    let signal = args.first().cloned().unwrap_or(Value::Undef);
765    let listener = args.get(1).cloned().unwrap_or(Value::Undef);
766    let aborted = crate::builtins::get_property(&signal, "aborted").unwrap_or(Value::Undef);
767    if with_host(|h| h.truthy(&aborted)) {
768        with_host(|h| h.queue_micro(listener, Vec::new()));
769    } else {
770        let name = with_host(|h| h.new_str("abort"));
771        let once = with_host(|h| {
772            let mut m = IndexMap::new();
773            m.insert("once".into(), Value::Bool(true));
774            h.new_object(m)
775        });
776        let _ = call_method(&signal, "addEventListener", vec![name, listener, once]);
777    }
778    with_host(|h| h.new_object(IndexMap::new()))
779}
780
781/// `events.on(emitter, event[, options])` — the port in `events_on.js`,
782/// evaluated once.
783fn events_on(args: &[Value]) -> Result<Value, String> {
784    thread_local! {
785        static ON: std::cell::RefCell<Option<Value>> = const { std::cell::RefCell::new(None) };
786    }
787    let on = match ON.with(|o| o.borrow().clone()) {
788        Some(f) => f,
789        None => {
790            let factory = crate::eval_internal(include_str!("events_on.js"))?;
791            let node_error = with_host(|h| h.alloc(JsObj::Builtin("util.@@nodeError".into())));
792            let made = invoke(&factory, vec![node_error], None)?;
793            ON.with(|o| *o.borrow_mut() = Some(made.clone()));
794            made
795        }
796    };
797    invoke(&on, args.to_vec(), None)
798}