Merge branch 'main' into feat/bun-abort-basic

Author: tennisleng

docs/bundler/executables.mdx

@@ -413,34 +413,141 @@ cd /home/me/Desktop
 
 ## Embed assets & files
 
-Standalone executables support embedding files.
+Standalone executables support embedding files directly into the binary. This lets you ship a single executable that contains images, JSON configs, templates, or any other assets your application needs.
 
-To embed files into an executable with `bun build --compile`, import the file in your code.
+### How it works
+
+Use the `with { type: "file" }` [import attribute](https://github.com/tc39/proposal-import-attributes) to embed a file:
+
+```ts index.ts icon="/icons/typescript.svg"
+import icon from "./icon.png" with { type: "file" };
+
+console.log(icon);
+// During development: "./icon.png"
+// After compilation: "$bunfs/icon-a1b2c3d4.png" (internal path)
+```
+
+The import returns a **path string** that points to the embedded file. At build time, Bun:
+
+1. Reads the file contents
+2. Embeds the data into the executable
+3. Replaces the import with an internal path (prefixed with `$bunfs/`)
+
+You can then read this embedded file using `Bun.file()` or Node.js `fs` APIs.
+
+### Reading embedded files with Bun.file()
+
+`Bun.file()` is the recommended way to read embedded files:
 
 ```ts index.ts icon="/icons/typescript.svg"
-// this becomes an internal file path
 import icon from "./icon.png" with { type: "file" };
 import { file } from "bun";
 
+// Get file contents as different types
+const bytes = await file(icon).arrayBuffer(); // ArrayBuffer
+const text = await file(icon).text(); // string (for text files)
+const blob = file(icon); // Blob
+
+// Stream the file in a response
 export default {
   fetch(req) {
-    // Embedded files can be streamed from Response objects
-    return new Response(file(icon));
+    return new Response(file(icon), {
+      headers: { "Content-Type": "image/png" },
+    });
   },
 };
 ```
 
-Embedded files can be read using `Bun.file`'s functions or the Node.js `fs.readFile` function (in `"node:fs"`).
+### Reading embedded files with Node.js fs
 
-For example, to read the contents of the embedded file:
+Embedded files work seamlessly with Node.js file system APIs:
 
 ```ts index.ts icon="/icons/typescript.svg"
 import icon from "./icon.png" with { type: "file" };
+import config from "./config.json" with { type: "file" };
+import { readFileSync, promises as fs } from "node:fs";
+
+// Synchronous read
+const iconBuffer = readFileSync(icon);
+
+// Async read
+const configData = await fs.readFile(config, "utf-8");
+const parsed = JSON.parse(configData);
+
+// Check file stats
+const stats = await fs.stat(icon);
+console.log(`Icon size: ${stats.size} bytes`);
+```
+
+### Practical examples
+
+#### Embedding a JSON config file
+
+```ts index.ts icon="/icons/typescript.svg"
+import configPath from "./default-config.json" with { type: "file" };
+import { file } from "bun";
+
+// Load the embedded default configuration
+const defaultConfig = await file(configPath).json();
+
+// Merge with user config if it exists
+const userConfig = await file("./user-config.json")
+  .json()
+  .catch(() => ({}));
+const config = { ...defaultConfig, ...userConfig };
+```
+
+#### Serving static assets in an HTTP server
+
+Use `static` routes in `Bun.serve()` for efficient static file serving:
+
+```ts server.ts icon="/icons/typescript.svg"
+import favicon from "./favicon.ico" with { type: "file" };
+import logo from "./logo.png" with { type: "file" };
+import styles from "./styles.css" with { type: "file" };
+import { file, serve } from "bun";
+
+serve({
+  static: {
+    "/favicon.ico": file(favicon),
+    "/logo.png": file(logo),
+    "/styles.css": file(styles),
+  },
+  fetch(req) {
+    return new Response("Not found", { status: 404 });
+  },
+});
+```
+
+Bun automatically handles Content-Type headers and caching for static routes.
+
+#### Embedding templates
+
+```ts index.ts icon="/icons/typescript.svg"
+import templatePath from "./email-template.html" with { type: "file" };
+import { file } from "bun";
+
+async function sendWelcomeEmail(user: { name: string; email: string }) {
+  const template = await file(templatePath).text();
+  const html = template.replace("{{name}}", user.name).replace("{{email}}", user.email);
+
+  // Send email with the rendered template...
+}
+```
+
+#### Embedding binary files
+
+```ts index.ts icon="/icons/typescript.svg"
+import wasmPath from "./processor.wasm" with { type: "file" };
+import fontPath from "./font.ttf" with { type: "file" };
 import { file } from "bun";
 
-const bytes = await file(icon).arrayBuffer();
-// await fs.promises.readFile(icon)
-// fs.readFileSync(icon)
+// Load a WebAssembly module
+const wasmBytes = await file(wasmPath).arrayBuffer();
+const wasmModule = await WebAssembly.instantiate(wasmBytes);
+
+// Read binary font data
+const fontData = await file(fontPath).bytes();
 ```
 
 ### Embed SQLite databases
@@ -507,22 +614,57 @@ This is honestly a workaround, and we expect to improve this in the future with
 
 ### Listing embedded files
 
-To get a list of all embedded files, use `Bun.embeddedFiles`:
+`Bun.embeddedFiles` gives you access to all embedded files as `Blob` objects:
 
 ```ts index.ts icon="/icons/typescript.svg"
 import "./icon.png" with { type: "file" };
+import "./data.json" with { type: "file" };
+import "./template.html" with { type: "file" };
 import { embeddedFiles } from "bun";
 
-console.log(embeddedFiles[0].name); // `icon-${hash}.png`
+// List all embedded files
+for (const blob of embeddedFiles) {
+  console.log(`${blob.name} - ${blob.size} bytes`);
+}
+// Output:
+//   icon-a1b2c3d4.png - 4096 bytes
+//   data-e5f6g7h8.json - 256 bytes
+//   template-i9j0k1l2.html - 1024 bytes
 ```
 
-`Bun.embeddedFiles` returns an array of `Blob` objects which you can use to get the size, contents, and other properties of the files.
+Each item in `Bun.embeddedFiles` is a `Blob` with a `name` property:
 
 ```ts
-embeddedFiles: Blob[]
+embeddedFiles: ReadonlyArray<Blob>;
 ```
 
-The list of embedded files excludes bundled source code like `.ts` and `.js` files.
+This is useful for dynamically serving all embedded assets using `static` routes:
+
+```ts server.ts icon="/icons/typescript.svg"
+import "./public/favicon.ico" with { type: "file" };
+import "./public/logo.png" with { type: "file" };
+import "./public/styles.css" with { type: "file" };
+import { embeddedFiles, serve } from "bun";
+
+// Build static routes from all embedded files
+const staticRoutes: Record<string, Blob> = {};
+for (const blob of embeddedFiles) {
+  // Remove hash from filename: "icon-a1b2c3d4.png" -> "icon.png"
+  const name = blob.name.replace(/-[a-f0-9]+\./, ".");
+  staticRoutes[`/${name}`] = blob;
+}
+
+serve({
+  static: staticRoutes,
+  fetch(req) {
+    return new Response("Not found", { status: 404 });
+  },
+});
+```
+
+<Note>
+  `Bun.embeddedFiles` excludes bundled source code (`.ts`, `.js`, etc.) to help protect your application's source.
+</Note>
 
 #### Content hash
 

docs/runtime/http/server.mdx

@@ -193,15 +193,17 @@ This is the maximum amount of time a connection is allowed to be idle before the
 Thus far, the examples on this page have used the explicit `Bun.serve` API. Bun also supports an alternate syntax.
 
 ```ts server.ts
-import { type Serve } from "bun";
+import type { Serve } from "bun";
 
 export default {
   fetch(req) {
     return new Response("Bun!");
   },
-} satisfies Serve;
+} satisfies Serve.Options<undefined>;
 ```
 
+The type parameter `<undefined>` represents WebSocket data — if you add a `websocket` handler with custom data attached via `server.upgrade(req, { data: ... })`, replace `undefined` with your data type.
+
 Instead of passing the server options into `Bun.serve`, `export default` it. This file can be executed as-is; when Bun sees a file with a `default` export containing a `fetch` handler, it passes it into `Bun.serve` under the hood.
 
 ---

packages/bun-types/s3.d.ts

@@ -281,6 +281,24 @@ declare module "bun" {
      */
     type?: string;
 
+    /**
+     * The Content-Disposition header value.
+     * Controls how the file is presented when downloaded.
+     *
+     * @example
+     *    // Setting attachment disposition with filename
+     *     const file = s3.file("report.pdf", {
+     *       contentDisposition: "attachment; filename=\"quarterly-report.pdf\""
+     *     });
+     *
+     * @example
+     *    // Setting inline disposition
+     *     await s3.write("image.png", imageData, {
+     *       contentDisposition: "inline"
+     *     });
+     */
+    contentDisposition?: string | undefined;
+
     /**
      * By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects.
      *

src/ast/SideEffects.zig

@@ -277,7 +277,7 @@ pub const SideEffects = enum(u1) {
                                 }
                             }
 
-                            properties_slice[end] = prop_;
+                            properties_slice[end] = prop;
                             end += 1;
                         }
 

src/bun.js/webcore/Blob.zig

@@ -968,6 +968,7 @@ fn writeFileWithEmptySourceToDestination(ctx: *jsc.JSGlobalObject, destination_b
                 s3.path(),
                 "",
                 destination_blob.contentTypeOrMimeType(),
+                aws_options.content_disposition,
                 aws_options.acl,
                 proxy_url,
                 aws_options.storage_class,
@@ -1116,6 +1117,7 @@ pub fn writeFileWithSourceDestination(ctx: *jsc.JSGlobalObject, source_blob: *Bl
                             aws_options.acl,
                             aws_options.storage_class,
                             destination_blob.contentTypeOrMimeType(),
+                            aws_options.content_disposition,
                             proxy_url,
                             null,
                             undefined,
@@ -1154,6 +1156,7 @@ pub fn writeFileWithSourceDestination(ctx: *jsc.JSGlobalObject, source_blob: *Bl
                         s3.path(),
                         bytes.slice(),
                         destination_blob.contentTypeOrMimeType(),
+                        aws_options.content_disposition,
                         aws_options.acl,
                         proxy_url,
                         aws_options.storage_class,
@@ -1183,6 +1186,7 @@ pub fn writeFileWithSourceDestination(ctx: *jsc.JSGlobalObject, source_blob: *Bl
                         aws_options.acl,
                         aws_options.storage_class,
                         destination_blob.contentTypeOrMimeType(),
+                        aws_options.content_disposition,
                         proxy_url,
                         null,
                         undefined,
@@ -1387,6 +1391,7 @@ pub fn writeFileInternal(globalThis: *jsc.JSGlobalObject, path_or_blob_: *PathOr
                                 aws_options.acl,
                                 aws_options.storage_class,
                                 destination_blob.contentTypeOrMimeType(),
+                                aws_options.content_disposition,
                                 proxy_url,
                                 null,
                                 undefined,
@@ -1447,6 +1452,7 @@ pub fn writeFileInternal(globalThis: *jsc.JSGlobalObject, path_or_blob_: *PathOr
                                 aws_options.acl,
                                 aws_options.storage_class,
                                 destination_blob.contentTypeOrMimeType(),
+                                aws_options.content_disposition,
                                 proxy_url,
                                 null,
                                 undefined,
@@ -2402,6 +2408,7 @@ pub fn pipeReadableStreamToBlob(this: *Blob, globalThis: *jsc.JSGlobalObject, re
             aws_options.acl,
             aws_options.storage_class,
             this.contentTypeOrMimeType(),
+            aws_options.content_disposition,
             proxy_url,
             null,
             undefined,
@@ -2629,13 +2636,22 @@ pub fn getWriter(
                         }
                     }
                 }
+                var content_disposition_str: ?ZigString.Slice = null;
+                defer if (content_disposition_str) |cd| cd.deinit();
+                if (try options.getTruthy(globalThis, "contentDisposition")) |content_disposition| {
+                    if (!content_disposition.isString()) {
+                        return globalThis.throwInvalidArgumentType("write", "options.contentDisposition", "string");
+                    }
+                    content_disposition_str = try content_disposition.toSlice(globalThis, bun.default_allocator);
+                }
                 const credentialsWithOptions = try s3.getCredentialsWithOptions(options, globalThis);
                 return try S3.writableStream(
                     credentialsWithOptions.credentials.dupe(),
                     path,
                     globalThis,
                     credentialsWithOptions.options,
                     this.contentTypeOrMimeType(),
+                    if (content_disposition_str) |cd| cd.slice() else null,
                     proxy_url,
                     credentialsWithOptions.storage_class,
                 );
@@ -2647,6 +2663,7 @@ pub fn getWriter(
             globalThis,
             .{},
             this.contentTypeOrMimeType(),
+            null,
             proxy_url,
             null,
         );

src/bun.js/webcore/fetch.zig

@@ -1301,6 +1301,7 @@ pub fn Bun__fetch_(
                 credentialsWithOptions.acl,
                 credentialsWithOptions.storage_class,
                 if (headers) |h| (h.getContentType()) else null,
+                if (headers) |h| h.getContentDisposition() else null,
                 proxy_url,
                 @ptrCast(&Wrapper.resolve),
                 s3_stream,

src/http/Headers.zig

@@ -75,20 +75,12 @@ pub fn deinit(this: *Headers) void {
     this.entries.deinit(this.allocator);
     this.buf.clearAndFree(this.allocator);
 }
-pub fn getContentType(this: *const Headers) ?[]const u8 {
-    if (this.entries.len == 0 or this.buf.items.len == 0) {
-        return null;
-    }
-    const header_entries = this.entries.slice();
-    const header_names = header_entries.items(.name);
-    const header_values = header_entries.items(.value);
 
-    for (header_names, 0..header_names.len) |name, i| {
-        if (bun.strings.eqlCaseInsensitiveASCII(this.asStr(name), "content-type", true)) {
-            return this.asStr(header_values[i]);
-        }
-    }
-    return null;
+pub fn getContentDisposition(this: *const Headers) ?[]const u8 {
+    return this.get("content-disposition");
+}
+pub fn getContentType(this: *const Headers) ?[]const u8 {
+    return this.get("content-type");
 }
 pub fn asStr(this: *const Headers, ptr: api.StringPointer) []const u8 {
     return if (ptr.offset + ptr.length <= this.buf.items.len)