node compat batch: callback-throw dispatch, Assert class + native deep-equality parity, Intl gate + URL/buffer fallout, compile cache, watch kill-signal, profilers (+98 tests)

docs/project/benchmarking.mdx

@@ -261,13 +261,19 @@ bun --cpu-prof --cpu-prof-dir ./profiles script.js
 
 ## Heap profiling
 
-Generate heap snapshots on exit to analyze memory usage and find memory leaks.
+Write a heap profile on exit to analyze memory usage and find memory leaks.
 
 ```sh terminal icon="terminal"
 bun --heap-prof script.js
 ```
 
-`--heap-prof` writes a V8 `.heapsnapshot` file you can load in Chrome DevTools (Memory tab → Load).
+`--heap-prof` writes a `.heapprofile` file using Node.js's filename format
+(`Heap.<yyyymmdd>.<hhmmss>.<pid>.<tid>.<seq>.heapprofile`). JavaScriptCore does not
+sample allocation call stacks, so the profile reports the live heap size on the
+`(root)` frame rather than a per-function allocation tree.
+
+For a full heap snapshot you can load in Chrome DevTools (Memory tab → Load), use
+`v8.writeHeapSnapshot()` or `Bun.generateHeapSnapshot("v8")` instead.
 
 ### Markdown output
 
@@ -282,13 +288,14 @@ bun --heap-prof-md script.js
 ### Options
 
 ```sh terminal icon="terminal"
-bun --heap-prof --heap-prof-name my-snapshot.heapsnapshot script.js
+bun --heap-prof --heap-prof-name my-profile.heapprofile script.js
 bun --heap-prof --heap-prof-dir ./profiles script.js
 ```
 
-| Flag                          | Description                                |
-| ----------------------------- | ------------------------------------------ |
-| `--heap-prof`                 | Generate a V8 `.heapsnapshot` file on exit |
-| `--heap-prof-md`              | Generate a markdown heap profile on exit   |
-| `--heap-prof-name <filename>` | Set output filename                        |
-| `--heap-prof-dir <dir>`       | Set output directory                       |
+| Flag                           | Description                                                  |
+| ------------------------------ | ------------------------------------------------------------ |
+| `--heap-prof`                  | Write a `.heapprofile` file on exit                          |
+| `--heap-prof-md`               | Generate a markdown heap profile on exit                     |
+| `--heap-prof-name <filename>`  | Set output filename                                          |
+| `--heap-prof-dir <dir>`        | Set output directory                                         |
+| `--heap-prof-interval <bytes>` | Accepted for Node.js compatibility (sampling is unsupported) |

docs/runtime/watch-mode.mdx

@@ -76,6 +76,12 @@ bun --watch test
   --no-clear-screen`.
 </Note>
 
+<Note>
+  Before each restart, `bun run --watch` runs the handlers your script registered for the kill signal (default
+  `SIGTERM`, matching the signal Node.js sends its watched process). Use **`--watch-kill-signal`** to pick a different
+  signal, e.g. `bun --watch --watch-kill-signal SIGINT index.ts`.
+</Note>
+
 ---
 
 ## `--hot` mode

docs/snippets/cli/run.mdx

@@ -105,6 +105,10 @@ bun run <file or script>
   Automatically restart the process on file change
 </ParamField>
 
+<ParamField path="--watch-kill-signal" type="string" default="SIGTERM">
+  Signal whose handlers run when --watch restarts the process
+</ParamField>
+
 <ParamField path="--hot" type="boolean">
   Enable auto reload in the Bun runtime, test runner, or bundler
 </ParamField>

src/bun_core/Global.rs

@@ -289,6 +289,60 @@ macro_rules! __define_signal_code {
 }
 for_each_signal!(__define_signal_code);
 
+impl SignalCode {
+    /// This table uses Linux numbering; returns the current platform's number
+    /// (they differ on macOS/BSD), or `None` when the platform lacks the signal.
+    pub fn platform_number(self) -> Option<i32> {
+        #[cfg(unix)]
+        {
+            use SignalCode as S;
+            Some(match self {
+                S::SIGHUP => libc::SIGHUP,
+                S::SIGINT => libc::SIGINT,
+                S::SIGQUIT => libc::SIGQUIT,
+                S::SIGILL => libc::SIGILL,
+                S::SIGTRAP => libc::SIGTRAP,
+                S::SIGABRT => libc::SIGABRT,
+                S::SIGBUS => libc::SIGBUS,
+                S::SIGFPE => libc::SIGFPE,
+                S::SIGKILL => libc::SIGKILL,
+                S::SIGUSR1 => libc::SIGUSR1,
+                S::SIGSEGV => libc::SIGSEGV,
+                S::SIGUSR2 => libc::SIGUSR2,
+                S::SIGPIPE => libc::SIGPIPE,
+                S::SIGALRM => libc::SIGALRM,
+                S::SIGTERM => libc::SIGTERM,
+                S::SIG16 => return None,
+                S::SIGCHLD => libc::SIGCHLD,
+                S::SIGCONT => libc::SIGCONT,
+                S::SIGSTOP => libc::SIGSTOP,
+                S::SIGTSTP => libc::SIGTSTP,
+                S::SIGTTIN => libc::SIGTTIN,
+                S::SIGTTOU => libc::SIGTTOU,
+                S::SIGURG => libc::SIGURG,
+                S::SIGXCPU => libc::SIGXCPU,
+                S::SIGXFSZ => libc::SIGXFSZ,
+                S::SIGVTALRM => libc::SIGVTALRM,
+                S::SIGPROF => libc::SIGPROF,
+                S::SIGWINCH => libc::SIGWINCH,
+                S::SIGIO => libc::SIGIO,
+                #[cfg(target_os = "linux")]
+                S::SIGPWR => libc::SIGPWR,
+                #[cfg(not(target_os = "linux"))]
+                S::SIGPWR => return None,
+                S::SIGSYS => libc::SIGSYS,
+            })
+        }
+        #[cfg(not(unix))]
+        {
+            match self {
+                Self::SIG16 => None,
+                _ => Some(self as u8 as i32),
+            }
+        }
+    }
+}
+
 // ─── analytics::features (MOVE_DOWN from bun_analytics) ───────────────────
 // Atomic counters so cross-thread `.fetch_add` is sound. Only the
 // counters are tier-0; `builtin_modules` (EnumSet over jsc HardcodedModule)

src/bun_core/env_var.rs

@@ -144,10 +144,15 @@ new!(pub NODE_CHANNEL_FD: string, "NODE_CHANNEL_FD", {});
 // A string, not a boolean: node suppresses warnings only when the value is
 // exactly "1" (lib/internal/process/pre_execution.js).
 new!(pub NODE_NO_WARNINGS: string, "NODE_NO_WARNINGS", {});
+new!(pub NODE_COMPILE_CACHE: string, "NODE_COMPILE_CACHE", {});
+new!(pub NODE_COMPILE_CACHE_PORTABLE: string, "NODE_COMPILE_CACHE_PORTABLE", {});
+new!(pub NODE_DEBUG_NATIVE: string, "NODE_DEBUG_NATIVE", {});
+new!(pub NODE_DISABLE_COMPILE_CACHE: string, "NODE_DISABLE_COMPILE_CACHE", {});
 // Set by HostProcess.rs when spawning the WebView host subprocess. The
 // child's CLI entrypoint checks this before anything else and hands off to
 // C++ Bun__WebView__hostMain. Never returns — no JSC, no VM.
 new!(pub BUN_INTERNAL_WEBVIEW_HOST: string, "BUN_INTERNAL_WEBVIEW_HOST", {});
+new!(pub NODE_PENDING_DEPRECATION: string, "NODE_PENDING_DEPRECATION", {});
 new!(pub NODE_PRESERVE_SYMLINKS_MAIN: boolean, "NODE_PRESERVE_SYMLINKS_MAIN", { default: false });
 new!(pub NODE_USE_SYSTEM_CA: boolean, "NODE_USE_SYSTEM_CA", { default: false });
 new!(pub npm_lifecycle_event: string, "npm_lifecycle_event", {});

src/bun_core/lib.rs

@@ -2601,6 +2601,9 @@ pub mod ffi {
     unsafe impl Zeroable for libc::pollfd {}
     // SAFETY: C POD (integer/array/raw-pointer fields only); all-zero is valid.
     #[cfg(unix)]
+    unsafe impl Zeroable for libc::tm {}
+    // SAFETY: C POD (integer/array/raw-pointer fields only); all-zero is valid.
+    #[cfg(unix)]
     unsafe impl Zeroable for libc::Dl_info {}
     // SAFETY: C POD (integer/array/raw-pointer fields only); all-zero is valid.
     #[cfg(unix)]

src/bun_core/util.rs

@@ -4247,6 +4247,34 @@ pub fn intern_argv(v: Vec<&'static ZStr>) -> &'static [&'static ZStr] {
 /// Writes the current working directory into the caller's `PathBuffer` and
 /// returns the NUL-terminated slice on success.
 pub fn getcwd(buf: &mut PathBuffer) -> crate::CrateResult<&ZStr> {
+    let len = getcwd_len(buf)?;
+    Ok(ZStr::from_buf(&buf.0, len))
+}
+
+/// `getcwd` tolerating an unreachable cwd (e.g. deleted while we run): falls
+/// back to the executable's directory like Node's `Environment::GetCwd`, so
+/// startup proceeds and `process.cwd()` surfaces the real error later.
+pub fn getcwd_or_exe_dir(buf: &mut PathBuffer) -> &ZStr {
+    let len = match getcwd_len(buf) {
+        Ok(n) => n,
+        Err(_) => {
+            let dir: &[u8] = self_exe_path()
+                .ok()
+                .and_then(|p| dirname(p.as_bytes()))
+                // Reject a dir that can't fit with its NUL (paths from
+                // /proc/self/exe are not bounded by MAX_PATH_BYTES).
+                .filter(|d| d.len() < buf.0.len())
+                .unwrap_or(if cfg!(windows) { b"C:\\" } else { b"/" });
+            buf.0[..dir.len()].copy_from_slice(dir);
+            buf.0[dir.len()] = 0;
+            dir.len()
+        }
+    };
+    ZStr::from_buf(&buf.0, len)
+}
+
+/// Length-returning core of [`getcwd`]; `buf` holds the NUL-terminated path.
+fn getcwd_len(buf: &mut PathBuffer) -> crate::CrateResult<usize> {
     #[cfg(unix)]
     // SAFETY: `buf` provides `MAX_PATH_BYTES` writable bytes for `getcwd`; on
     // success the returned pointer aliases `buf` and is NUL-terminated, so
@@ -4256,8 +4284,7 @@ pub fn getcwd(buf: &mut PathBuffer) -> crate::CrateResult<&ZStr> {
         if p.is_null() {
             return Err(crate::CrateError::Unexpected);
         }
-        let len = libc::strlen(p);
-        Ok(ZStr::from_buf(&buf.0, len))
+        Ok(libc::strlen(p))
     }
     #[cfg(windows)]
     {
@@ -4293,7 +4320,7 @@ pub fn getcwd(buf: &mut PathBuffer) -> crate::CrateResult<&ZStr> {
             bi += nb;
         }
         out[bi] = 0;
-        Ok(ZStr::from_buf(&buf.0[..], bi))
+        Ok(bi)
     }
     #[cfg(not(any(unix, windows)))]
     {

src/clap/comptime.rs

@@ -543,6 +543,7 @@ impl<Id> ComptimeClap<Id> {
             diagnostic: opt.diagnostic,
             state: streaming::State::Normal,
             positional: None,
+            short_aliases: opt.short_aliases,
         };
 
         while let Some(arg) = stream.next()? {

src/clap/lib.rs

@@ -413,6 +413,10 @@ impl Default for Help {
 pub struct ParseOptions<'a> {
     pub diagnostic: Option<&'a mut Diagnostic>,
     pub stop_after_positional_at: usize,
+    /// Whole-token rewrites applied only where a token is being classified as a
+    /// flag, never to an option's value or a `--` target. Node keeps its own
+    /// aliases on exactly that branch (node_options-inl.h).
+    pub short_aliases: &'static [(&'static [u8], &'static [u8])],
 }
 
 // Help/usage/error rendering — none of this is on the cold-start hot chain
@@ -506,6 +510,7 @@ pub fn parse<Id: 'static>(
         ParseOptions {
             diagnostic: opt.diagnostic,
             stop_after_positional_at: opt.stop_after_positional_at,
+            short_aliases: opt.short_aliases,
         },
     )?;
     Ok(Args { clap, exe_arg })
@@ -526,6 +531,7 @@ pub fn parse_with_table<Id: 'static>(
         ParseOptions {
             diagnostic: opt.diagnostic,
             stop_after_positional_at: opt.stop_after_positional_at,
+            short_aliases: opt.short_aliases,
         },
     )?;
     Ok(Args { clap, exe_arg })

src/clap/streaming.rs

@@ -61,6 +61,7 @@ pub struct StreamingClap<'p, 'a, Id, ArgIterator> {
     pub state: State<'a>,
     pub positional: Option<&'p clap::Param<Id>>,
     pub diagnostic: Option<&'p mut clap::Diagnostic>,
+    pub short_aliases: &'static [(&'static [u8], &'static [u8])],
 }
 
 // ArgIterator is the
@@ -300,9 +301,22 @@ where
     }
 
     fn parse_next_arg(&mut self) -> Result<Option<ArgInfo<'a>>, ArgError> {
-        let Some(full_arg) = self.iter.next() else {
+        let Some(mut full_arg) = self.iter.next() else {
             return Ok(None);
         };
+        // Only tokens reaching here are being read as flags: option values and
+        // `--` targets are pulled straight off `iter`, so they stay verbatim.
+        // Restrict rewrites to flag-shaped tokens so a mapping can never touch
+        // the `-`/`--` sentinels or a positional, per the contract on
+        // `ParseOptions::short_aliases`.
+        if full_arg.starts_with(b"-") && full_arg != b"-" && full_arg != b"--" {
+            for (from, to) in self.short_aliases {
+                if full_arg == *from {
+                    full_arg = to;
+                    break;
+                }
+            }
+        }
         if full_arg == b"--" || full_arg == b"-" {
             return Ok(Some(ArgInfo {
                 arg: full_arg,
@@ -354,6 +368,7 @@ mod tests {
             remain: args_strings,
         };
         let mut c = StreamingClap::<u8, args::SliceIterator> {
+            short_aliases: &[],
             params,
             iter: &mut iter,
             state: State::Normal,
@@ -386,6 +401,7 @@ mod tests {
             remain: args_strings,
         };
         let mut c = StreamingClap::<u8, args::SliceIterator> {
+            short_aliases: &[],
             params,
             iter: &mut iter,
             state: State::Normal,

src/codegen/class-definitions.ts

@@ -152,6 +152,11 @@ export class ClassDefinition {
    * The instances of this class are intended to be inside the this of a bound function.
    */
   forBind?: boolean;
+  /**
+   * Parent of the generated prototype object. "Error" puts Error.prototype in
+   * the chain so instances satisfy `instanceof Error`. Default: Object.prototype.
+   */
+  prototypeBase?: "Error";
   /**
    * ## IMPORTANT
    * You _must_ free the pointer to your native class!

src/codegen/generate-classes.ts

@@ -1837,7 +1837,13 @@ ${
 
 JSObject* ${name}::createPrototype(VM& vm, JSDOMGlobalObject* globalObject)
 {
-    auto *structure = ${prototypeName(typeName)}::createStructure(vm, globalObject, ${obj.forBind ? "globalObject->functionPrototype()" : "globalObject->objectPrototype()"});
+    auto *structure = ${prototypeName(typeName)}::createStructure(vm, globalObject, ${
+      obj.forBind
+        ? "globalObject->functionPrototype()"
+        : obj.prototypeBase === "Error"
+          ? "globalObject->errorPrototype()"
+          : "globalObject->objectPrototype()"
+    });
     structure->setMayBePrototype(true);
     return ${prototypeName(typeName)}::create(vm, globalObject, structure);
 }

src/errno/lib.rs

@@ -45,36 +45,40 @@ macro_rules! __decl_uv_e {
     ( $( $ident:ident = $value:expr => $display:literal ),+ $(,)? ) => {
         $( pub const $ident: i32 = $value; )+
 
+        /// The full (negated code, name) table for this target —
+        /// target-independent libuv-synthetic codes (values from
+        /// vendor/libuv/include/uv/errno.h) first, then the per-OS rows.
+        /// Consumed by `name()` and node:util's `getSystemErrorMap()`.
+        pub static ENTRIES: &[(i32, &'static str)] = &[
+            (-4095, "EOF"),
+            (-4094, "UNKNOWN"),
+            (-3000, "EAI_ADDRFAMILY"),
+            (-3001, "EAI_AGAIN"),
+            (-3002, "EAI_BADFLAGS"),
+            (-3003, "EAI_CANCELED"),
+            (-3004, "EAI_FAIL"),
+            (-3005, "EAI_FAMILY"),
+            (-3006, "EAI_MEMORY"),
+            (-3007, "EAI_NODATA"),
+            (-3008, "EAI_NONAME"),
+            (-3009, "EAI_OVERFLOW"),
+            (-3010, "EAI_SERVICE"),
+            (-3011, "EAI_SOCKTYPE"),
+            (-3013, "EAI_BADHINTS"),
+            (-3014, "EAI_PROTOCOL"),
+            $( (-($ident), $display) ),+
+        ];
+
         /// Negated libuv error code (`-UV_E*`) → user-visible name.
         /// `None` for unmapped values (caller falls back to
-        /// `"Unknown system error N"`). Input is the raw signed value as
-        /// returned to JS — i.e. `-uv_e::FOO`.
+        /// `"Unknown system error N"`). First match wins, mirroring the
+        /// duplicate-value tolerance of the old `if`-chain (EAGAIN aliases).
         pub fn name(neg_uv_err: i32) -> Option<&'static str> {
-            // Target-independent libuv-synthetic codes (no `uv_e::*` const).
-            // Values from vendor/libuv/include/uv/errno.h.
-            match neg_uv_err {
-                -4095 => return Some("EOF"),
-                -4094 => return Some("UNKNOWN"),
-                -3000 => return Some("EAI_ADDRFAMILY"),
-                -3001 => return Some("EAI_AGAIN"),
-                -3002 => return Some("EAI_BADFLAGS"),
-                -3003 => return Some("EAI_CANCELED"),
-                -3004 => return Some("EAI_FAIL"),
-                -3005 => return Some("EAI_FAMILY"),
-                -3006 => return Some("EAI_MEMORY"),
-                -3007 => return Some("EAI_NODATA"),
-                -3008 => return Some("EAI_NONAME"),
-                -3009 => return Some("EAI_OVERFLOW"),
-                -3010 => return Some("EAI_SERVICE"),
-                -3011 => return Some("EAI_SOCKTYPE"),
-                -3013 => return Some("EAI_BADHINTS"),
-                -3014 => return Some("EAI_PROTOCOL"),
-                _ => {}
+            for &(code, name) in ENTRIES {
+                if code == neg_uv_err {
+                    return Some(name);
+                }
             }
-            // Per-OS rows. `if`-chain (not `match`) because two `$value`s may
-            // resolve to the same integer on some targets (e.g. EAGAIN ==
-            // EWOULDBLOCK), which `match` rejects as an unreachable pattern.
-            $( if neg_uv_err == -($ident) { return Some($display); } )+
             None
         }
     };

src/event_loop/ConcurrentTask.rs

@@ -91,6 +91,7 @@ pub mod task_tag {
         Futimes,
         GetAddrInfoRequestTask,
         HotReloadTask,
+        WatchReloadTask,
         ImmediateObject,
         JSCDeferredWorkTask,
         Lchmod,