macros: read a returned Bun.file() on the transpiling thread and inline its bytes

docs/bundler/macros.mdx

@@ -171,6 +171,17 @@ export function getObject() {
 }
 ```
 
+`Bun.file()` returns a `Blob`, so a macro can return a file. Bun reads the file when it inlines the macro call. The `type` comes from the file extension, unless you pass one to `Bun.file()`.
+
+```ts title="macro.ts" icon="/icons/typescript.svg"
+export function getLogo() {
+  // inlined as "data:image/png;base64,..."
+  return Bun.file(import.meta.dir + "/logo.png");
+}
+```
+
+To inline a text or JSON file with a fixed path, import the file instead. See [loaders](/bundler/loaders). The build fails if the path is not a regular file that Bun can read. Bun does not read an S3 file that a macro returns. Read it in the macro and return the result, for example `await file.text()`.
+
 Functions and instances of most classes (except those listed earlier) are not serializable.
 
 ```ts title="macro.ts" icon="/icons/typescript.svg"

src/js_parser_jsc/Macro.rs

@@ -742,10 +742,62 @@ impl<'a> Run<'a> {
                 if let Some(blob) = blob_ {
                     // SAFETY: `blob` (a JS cell) is pinned for the call; the
                     // shared-view/content-type slices borrow its store.
-                    let (bytes, ct) =
-                        unsafe { ((*blob).shared_view(), (*blob).content_type_slice()) };
-                    return expr_from_blob(bytes, self.bump, ct, self.log, self.caller.loc)
-                        .map_err(|_| MacroError::MacroFailed);
+                    let blob = unsafe { &*blob };
+                    let read: Vec<u8>;
+                    let mut path: Option<&[u8]> = None;
+                    let bytes: &[u8] = match blob.in_memory_view() {
+                        Some(view) => view,
+                        None if blob.is_s3() => {
+                            self.log.add_range_error_fmt_with_notes(
+                                Some(self.source),
+                                Range {
+                                    loc: self.caller.loc,
+                                    ..Default::default()
+                                },
+                                Box::new([bun_ast::range_data(
+                                    None,
+                                    Range::NONE,
+                                    "read the file in the macro and return the result, for example \"await file.text()\" or \"await file.json()\"",
+                                )]),
+                                format_args!(
+                                    "cannot inline S3 file {} returned by this macro",
+                                    bun_core::fmt::quote(blob.store_path().unwrap_or_default()),
+                                ),
+                            );
+                            return Err(MacroError::MacroFailed);
+                        }
+                        None => {
+                            let hooks = runtime_hooks().expect("RuntimeHooks not installed");
+                            read = match (hooks.blob_read_bytes_sync)(blob) {
+                                Ok(bytes) => bytes,
+                                Err(err) => {
+                                    self.log.add_error_fmt(
+                                        Some(self.source),
+                                        self.caller.loc,
+                                        format_args!(
+                                            "failed to read the file returned by this macro: {}",
+                                            err.to_system_error().message,
+                                        ),
+                                    );
+                                    return Err(MacroError::MacroFailed);
+                                }
+                            };
+                            // Line and column of a slice that starts later would not be those of the file.
+                            if blob.offset.get() == 0 {
+                                path = blob.store_path();
+                            }
+                            &read
+                        }
+                    };
+                    return expr_from_blob(
+                        bytes,
+                        self.bump,
+                        blob.content_type_slice(),
+                        path,
+                        self.log,
+                        self.caller.loc,
+                    )
+                    .map_err(|_| MacroError::MacroFailed);
                 }
 
                 return Ok(Expr::init(E::EString::EMPTY, self.caller.loc));
@@ -1129,6 +1181,7 @@ fn expr_from_blob(
     bytes: &[u8],
     bump: &bun_alloc::Arena,
     content_type: &[u8],
+    path: Option<&[u8]>,
     log: &mut Log,
     loc: bun_ast::Loc,
 ) -> crate::Result<Expr> {
@@ -1145,7 +1198,19 @@ fn expr_from_blob(
     let is_json = essence.ends_with(b"/json") || essence.ends_with(b"+json");
 
     if is_json {
-        let source = &Source::init_path_string(b"fetch.json", bytes);
+        // The parsed strings borrow the source bytes; keep them in `bump`.
+        let bytes: &[u8] = match strings::BOM::detect_and_split(bytes) {
+            (Some(strings::BOM::Utf16Le), body) => {
+                bump.alloc_slice_copy(&strings::to_utf8_alloc_from_le_bytes(body))
+            }
+            _ => bump.alloc_slice_copy(bytes),
+        };
+        // A diagnostic keeps the name of its source, so the name goes into `bump` too.
+        let name: &[u8] = match path {
+            Some(path) => bump.alloc_slice_copy(path),
+            None => b"fetch.json",
+        };
+        let source = &Source::init_path_string(name, bytes);
         let mut out_expr: Expr = match bun_parsers::json::parse_for_macro(source, log, bump) {
             Ok(e) => e,
             Err(_) => return Err(crate::Error::MacroFailed),
@@ -1169,24 +1234,7 @@ fn expr_from_blob(
         );
 
     if is_text_like {
-        let mut output = bun_core::MutableString::init_empty();
-        bun_core::quote_for_json(bytes, &mut output, true)?;
-        let owned = output.to_owned_slice();
-        // strip the surrounding quotes; copy into the bump arena so the
-        // `E.String` data outlives `owned`.
-        let unquoted: &[u8] = if owned.len() >= 2 {
-            &owned[1..owned.len() - 1]
-        } else {
-            &owned[..]
-        };
-        let data = Str::new(bump.alloc_slice_copy(unquoted));
-        return Ok(Expr::init(
-            E::String {
-                data,
-                ..Default::default()
-            },
-            loc,
-        ));
+        return Ok(Expr::init(blob_text(bytes, bump), loc));
     }
 
     // Fallback: base64 data URL.
@@ -1212,3 +1260,19 @@ fn expr_from_blob(
         loc,
     ))
 }
+
+/// The string `blob.text()` returns for `bytes`.
+fn blob_text(bytes: &[u8], bump: &bun_alloc::Arena) -> E::EString {
+    let (bom, text) = strings::BOM::detect_and_split(bytes);
+    if bom == Some(strings::BOM::Utf16Le) {
+        let (units, _) = text.as_chunks::<2>();
+        return E::EString::init_utf16(
+            bump.alloc_slice_fill_iter(units.iter().map(|unit| u16::from_le_bytes(*unit))),
+        );
+    }
+    if strings::first_non_ascii(text).is_none() {
+        return E::EString::init(bump.alloc_slice_copy(text));
+    }
+    // Not ASCII: `init_re_encode_utf8` stores UTF-16 in `bump`, as the lexer does for a literal.
+    E::EString::init_re_encode_utf8(text, bump)
+}

src/jsc/VirtualMachine.rs

@@ -2943,6 +2943,8 @@ pub struct RuntimeHooks {
     /// `ResolveMessage` arms in `Macro::Run::coerce`.
     pub body_mixin_get_blob:
         fn(value: JSValue, global: &JSGlobalObject) -> JsResult<Option<JSValue>>,
+    /// `BlobExt::read_bytes_sync`, for `Macro::Run::coerce` (the `Blob` read paths are in `bun_runtime`).
+    pub blob_read_bytes_sync: fn(blob: &crate::webcore_types::Blob) -> bun_sys::Result<Vec<u8>>,
     /// `process.exit(global, code)`. Main-thread is `noreturn`; in a worker
     /// it returns and the caller `panic!`s. Lives in `bun_runtime::node`
     /// (forward-dep cycle), so [`uncaught_exception`] reaches it through this

src/jsc/webcore_types.rs

@@ -403,6 +403,14 @@ impl Blob {
         matches!(self.store.get().as_deref(), Some(s) if matches!(s.data, store::Data::File(_)))
     }
 
+    /// The Blob's bytes, or `None` for a file- or S3-backed Blob, which has to be read first.
+    pub fn in_memory_view(&self) -> Option<&[u8]> {
+        if self.needs_to_read_file() || self.is_s3() {
+            return None;
+        }
+        Some(self.shared_view())
+    }
+
     /// A usable filename: a non-empty `name`, else [`store_path`]. (`file.name`
     /// itself may be `""`; that is not a filename.)
     ///

src/runtime/jsc_hooks.rs

@@ -1371,6 +1371,10 @@ fn body_mixin_get_blob(
     Ok(None)
 }
 
+fn blob_read_bytes_sync(blob: &crate::webcore::Blob) -> bun_sys::Result<Vec<u8>> {
+    blob.read_bytes_sync()
+}
+
 /// `process.exit(code)`. Main-thread is `noreturn`; in a
 /// worker it returns and the caller `panic!`s.
 ///
@@ -1523,6 +1527,7 @@ static __BUN_RUNTIME_HOOKS: RuntimeHooks = RuntimeHooks {
     create_node_fs,
     has_blob_url,
     body_mixin_get_blob,
+    blob_read_bytes_sync,
     process_exit,
     console_on_before_print,
     console_print_runtime_object,

src/runtime/webcore/Blob.rs

@@ -282,8 +282,8 @@ pub(crate) trait BlobExt {
     where
         Self: Sized;
     fn shared_view_raw(&self) -> *mut [u8];
-    /// The Blob's bytes, or `None` for a file- or S3-backed Blob, which has to be read first.
-    fn in_memory_view(&self) -> Option<&[u8]>;
+    /// The Blob's bytes, read on the calling thread. Fails for S3 and for a path that is not a regular file.
+    fn read_bytes_sync(&self) -> bun_sys::Result<Vec<u8>>;
     fn set_is_ascii_flag(&self, is_all_ascii: bool);
     /// # Safety
     /// `raw_bytes` must be valid for reads for the duration of the call; when
@@ -2286,11 +2286,104 @@ impl BlobExt for Blob {
         }
     }
 
-    fn in_memory_view(&self) -> Option<&[u8]> {
-        if self.needs_to_read_file() || self.is_s3() {
-            return None;
+    fn read_bytes_sync(&self) -> bun_sys::Result<Vec<u8>> {
+        let file = match self.store().map(|store| &store.data) {
+            Some(store::Data::File(file)) => file,
+            Some(store::Data::S3(_)) => {
+                return Err(bun_sys::Error::from_code(
+                    bun_sys::E::ENOTSUP,
+                    bun_sys::Tag::read,
+                ));
+            }
+            Some(store::Data::Bytes(_)) | None => return Ok(self.shared_view().to_vec()),
+        };
+        let with_target = |err: bun_sys::Error| match &file.pathlike {
+            PathOrFileDescriptor::Path(path) => err.with_path(path.slice()),
+            PathOrFileDescriptor::Fd(fd) => err.with_fd(*fd),
+        };
+
+        let opened: bun_sys::File;
+        let fd = match &file.pathlike {
+            PathOrFileDescriptor::Fd(fd) => *fd,
+            PathOrFileDescriptor::Path(path) => {
+                // A FIFO with no writer blocks a plain open. It is rejected below.
+                #[cfg(unix)]
+                let flags = bun_sys::O::RDONLY
+                    | bun_sys::O::CLOEXEC
+                    | bun_sys::O::NONBLOCK
+                    | bun_sys::O::NOCTTY;
+                #[cfg(not(unix))]
+                let flags = bun_sys::O::RDONLY | bun_sys::O::CLOEXEC;
+                let mut buf = bun_paths::path_buffer_pool::get();
+                opened =
+                    bun_sys::File::open(path.slice_z(&mut buf), flags, 0).map_err(with_target)?;
+                opened.handle()
+            }
+        };
+
+        let stat = bun_sys::fstat(fd).map_err(with_target)?;
+        if !bun_sys::S::ISREG(stat.st_mode as _) {
+            // A pipe or a device has no end that a blocking read is sure to reach.
+            let code = if bun_sys::S::ISDIR(stat.st_mode as _) {
+                bun_sys::E::EISDIR
+            } else {
+                bun_sys::E::ENODEV
+            };
+            return Err(with_target(bun_sys::Error::from_code(
+                code,
+                bun_sys::Tag::read,
+            )));
+        }
+
+        let (offset, size) = (self.offset.get(), self.size.get());
+        // procfs reports a size of 0 for a file that has content, so only a known size can end the window.
+        let file_size = (stat.st_size as i64).max(0) as u64;
+        if size == 0 || (file_size > 0 && offset >= file_size) {
+            return Ok(Vec::new());
+        }
+        // A file system rejects an offset that no file of its kind can reach: that window is empty too.
+        if offset > 0 && bun_sys::set_file_offset(fd, offset).is_err() {
+            return Ok(Vec::new());
+        }
+
+        let mut node_fs = node::fs::NodeFS::default();
+        // `ReadFile` has `Drop`; can't use FRU `..Default::default()`.
+        let mut args = node::fs::args::ReadFile::default();
+        args.path = PathOrFileDescriptor::Fd(fd);
+        args.max_size = (size != MAX_SIZE).then_some(size);
+        args.limit_size_for_javascript = true;
+        let mut read = |args: &node::fs::args::ReadFile<'_>| -> bun_sys::Result<Vec<u8>> {
+            match node_fs
+                .read_file_with_options(
+                    args,
+                    node::fs::Flavor::Sync,
+                    node::fs::ReadFileStringType::NullTerminated,
+                )
+                .map_err(with_target)?
+            {
+                node::fs::ret::ReadFileWithOptions::NullTerminated(bytes) => {
+                    let mut bytes = bytes.into_vec_with_nul();
+                    bytes.pop();
+                    Ok(bytes)
+                }
+                _ => unreachable!(
+                    "ReadFileStringType::NullTerminated always yields the NullTerminated variant"
+                ),
+            }
+        };
+        let mut bytes = read(&args)?;
+        // With a `max_size` the reader stops at the size that `fstat` reports, and procfs reports 0: ask again until the window is full or the file ends.
+        if file_size == 0 && size != MAX_SIZE && !bytes.is_empty() {
+            while (bytes.len() as u64) < size {
+                args.max_size = Some(size - bytes.len() as u64);
+                let more = read(&args)?;
+                if more.is_empty() {
+                    break;
+                }
+                bytes.extend_from_slice(&more);
+            }
         }
-        Some(self.shared_view())
+        Ok(bytes)
     }
 
     fn set_is_ascii_flag(&self, is_all_ascii: bool) {