Merge branch 'main' into jarred/skip-GetFinalPathnameByHandle

docs/api/hashing.md

@@ -112,6 +112,7 @@ Bun.hash.murmur64v2("data", 1234);
 `Bun.CryptoHasher` is a general-purpose utility class that lets you incrementally compute a hash of string or binary data using a range of cryptographic hash algorithms. The following algorithms are supported:
 
 - `"blake2b256"`
+- `"blake2b512"`
 - `"md4"`
 - `"md5"`
 - `"ripemd160"`
@@ -120,7 +121,12 @@ Bun.hash.murmur64v2("data", 1234);
 - `"sha256"`
 - `"sha384"`
 - `"sha512"`
+- `"sha512-224"`
 - `"sha512-256"`
+- `"sha3-224"`
+- `"sha3-256"`
+- `"sha3-384"`
+- `"sha3-512"`
 
 ```ts
 const hasher = new Bun.CryptoHasher("sha256");

docs/bundler/executables.md

@@ -21,21 +21,76 @@ Hello world!
 
 All imported files and packages are bundled into the executable, along with a copy of the Bun runtime. All built-in Bun and Node.js APIs are supported.
 
-{% callout %}
+## Cross-compile to other platforms
 
-**Note** — Currently, the `--compile` flag can only accept a single entrypoint at a time and does not support the following flags:
+The `--target` flag lets you compile your standalone executable for a different operating system, architecture, or version of Bun than the machine you're running `bun build` on.
 
-- `--outdir` — use `outfile` instead.
-- `--splitting`
-- `--public-path`
+To build for Linux x64 (most servers):
+
+```sh
+bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp
+
+# To support CPUs from before 2013, use the baseline version (nehalem)
+bun build --compile --target=bun-linux-x64-baseline ./index.ts --outfile myapp
+
+# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
+# modern is faster, but baseline is more compatible.
+bun build --compile --target=bun-linux-x64-modern ./index.ts --outfile myapp
+```
+
+To build for Linux ARM64 (e.g. Graviton or Raspberry Pi):
+
+```sh
+# Note: the default architecture is x64 if no architecture is specified.
+bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp
+```
+
+To build for Windows x64:
+
+```sh
+bun build --compile --target=bun-windows-x64 ./path/to/my/app.ts --outfile myapp
+
+# To support CPUs from before 2013, use the baseline version (nehalem)
+bun build --compile --target=bun-windows-x64-baseline ./path/to/my/app.ts --outfile myapp
+
+# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
+bun build --compile --target=bun-windows-x64-modern ./path/to/my/app.ts --outfile myapp
+
+# note: if no .exe extension is provided, Bun will automatically add it for Windows executables
+```
+
+To build for macOS arm64:
+
+```sh
+bun build --compile --target=bun-darwin-arm64 ./path/to/my/app.ts --outfile myapp
+```
 
-{% /callout %}
+To build for macOS x64:
+
+```sh
+bun build --compile --target=bun-darwin-x64 ./path/to/my/app.ts --outfile myapp
+```
+
+#### Supported targets
+
+The order of the `--target` flag does not matter, as long as they're delimited by a `-`.
+
+| --target              | Operating System | Architecture | Modern | Baseline |
+| --------------------- | ---------------- | ------------ | ------ | -------- |
+| bun-linux-x64         | Linux            | x64          | ✅     | ✅       |
+| bun-linux-arm64       | Linux            | arm64        | ✅     | N/A      |
+| bun-windows-x64       | Windows          | x64          | ✅     | ✅       |
+| ~~bun-windows-arm64~~ | Windows          | arm64        | ❌     | ❌       |
+| bun-darwin-x64        | macOS            | x64          | ✅     | ✅       |
+| bun-darwin-arm64      | macOS            | arm64        | ✅     | N/A      |
+
+On x64 platforms, Bun uses SIMD optimizations which require a modern CPU supporting AVX2 instructions. The `-baseline` build of Bun is for older CPUs that don't support these optimizations. Normally, when you install Bun we automatically detect which version to use but this can be harder to do when cross-compiling since you might not know the target CPU. You usually don't need to worry about it on Darwin x64, but it is relevant for Windows x64 and Linux x64. If you or your users see `"Illegal instruction"` errors, you might need to use the baseline version.
 
 ## Deploying to production
 
 Compiled executables reduce memory usage and improve Bun's start time.
 
-Normally, Bun reads and transpiles JavaScript and TypeScript files on `import` and `require`. This is part of what makes so much of Bun "just work", but it's not free. It costs time and memory to read files from disk, resolve file paths, parse, transpile, and print source code. 
+Normally, Bun reads and transpiles JavaScript and TypeScript files on `import` and `require`. This is part of what makes so much of Bun "just work", but it's not free. It costs time and memory to read files from disk, resolve file paths, parse, transpile, and print source code.
 
 With compiled executables, you can move that cost from runtime to build-time.
 
@@ -58,7 +113,7 @@ You can use `bun:sqlite` imports with `bun build --compile`.
 By default, the database is resolved relative to the current working directory of the process.
 
 ```js
-import db from './my.db' with {type: "sqlite"};
+import db from "./my.db" with { type: "sqlite" };
 
 console.log(db.query("select * from users LIMIT 1").get());
 ```
@@ -70,42 +125,49 @@ $ cd /home/me/Desktop
 $ ./hello
 ```
 
-## Embedding files
+## Embed assets & files
 
 Standalone executables support embedding files.
 
 To embed files into an executable with `bun build --compile`, import the file in your code
 
-```js
+```ts
 // this becomes an internal file path
-import icon from "./icon.png";
-
+import icon from "./icon.png" with { type: "file" };
 import { file } from "bun";
 
 export default {
   fetch(req) {
+    // Embedded files can be streamed from Response objects
     return new Response(file(icon));
   },
 };
 ```
 
-You may need to specify a `--loader` for it to be treated as a `"file"` loader (so you get back a file path).
-
 Embedded files can be read using `Bun.file`'s functions or the Node.js `fs.readFile` function (in `"node:fs"`).
 
-### Embedding SQLite databases
+For example, to read the contents of the embedded file:
+
+```js
+import icon from "./icon.png" with { type: "file" };
+import { file } from "bun";
+
+const bytes = await file(icon).arrayBuffer();
+```
+
+### Embed SQLite databases
 
 If your application wants to embed a SQLite database, set `type: "sqlite"` in the import attribute and the `embed` attribute to `"true"`.
 
 ```js
-import myEmbeddedDb from "./my.db" with {type: "sqlite", embed: "true"};
+import myEmbeddedDb from "./my.db" with { type: "sqlite", embed: "true" };
 
 console.log(myEmbeddedDb.query("select * from users LIMIT 1").get());
 ```
 
 This database is read-write, but all changes are lost when the executable exits (since it's stored in memory).
 
-### Embedding N-API Addons
+### Embed N-API Addons
 
 As of Bun v1.0.23, you can embed `.node` files into executables.
 
@@ -120,3 +182,14 @@ Unfortunately, if you're using `@mapbox/node-pre-gyp` or other similar tools, yo
 ## Minification
 
 To trim down the size of the executable a little, pass `--minify` to `bun build --compile`. This uses Bun's minifier to reduce the code size. Overall though, Bun's binary is still way too big and we need to make it smaller.
+
+## Unsupported CLI arguments
+
+Currently, the `--compile` flag can only accept a single entrypoint at a time and does not support the following flags:
+
+- `--outdir` — use `outfile` instead.
+- `--splitting`
+- `--public-path`
+- `--target=node` or `--target=browser`
+- `--format` - always outputs a binary executable. Internally, it's almost esm.
+- `--no-bundle` - we always bundle everything into the executable.

docs/bundler/loaders.md

@@ -80,6 +80,9 @@ TOML files can be directly imported. Bun will parse them with its fast native TO
 ```ts
 import config from "./bunfig.toml";
 config.logLevel; // => "debug"
+
+// via import attribute:
+// import myCustomTOML from './my.config' with {type: "toml"};
 ```
 
 During bundling, the parsed TOML is inlined into the bundle as a JavaScript object.
@@ -122,6 +125,10 @@ Text files can be directly imported. The file is read and returned as a string.
 ```ts
 import contents from "./file.txt";
 console.log(contents); // => "Hello, world!"
+
+// To import an html file as text
+// The "type' attribute can be used to override the default loader.
+import html from "./index.html" with { type: "text" };
 ```
 
 When referenced during a build, the contents are into the bundle as a string.

docs/guides/runtime/define-constant.md

@@ -0,0 +1,145 @@
+---
+name: Define and replace static globals & constants
+---
+
+The `--define` flag lets you declare statically-analyzable constants and globals. It replace all usages of an identifier or property in a JavaScript or TypeScript file with a constant value. This feature is supported at runtime and also in `bun build`. This is sort of similar to `#define` in C/C++, except for JavaScript.
+
+```ts
+bun --define:process.env.NODE_ENV="'production'" src/index.ts # Runtime
+bun build --define:process.env.NODE_ENV="'production'" src/index.ts # Build
+```
+
+---
+
+These statically-known values are used by Bun for dead code elimination and other optimizations.
+
+```ts
+if (process.env.NODE_ENV === "production") {
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+Before the code reaches the JavaScript engine, Bun replaces `process.env.NODE_ENV` with `"production"`.
+
+```ts
+if ("production" === "production") {
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+It doesn't stop there. Bun's optimizing transpiler is smart enough to do some basic constant folding.
+
+Since `"production" === "production"` is always `true`, Bun replaces the entire expression with the `true` value.
+
+```ts
+if (true) {
+  console.log("Production mode");
+} else {
+  console.log("Development mode");
+}
+```
+
+---
+
+And finally, Bun detects the `else` branch is not reachable, and eliminates it.
+
+```ts
+console.log("Production mode");
+```
+
+---
+
+## What types of values are supported?
+
+Values can be strings, identifiers, properties, or JSON.
+
+### Replace global identifiers
+
+To make all usages of `window` be `undefined`, you can use the following command.
+
+```sh
+bun --define window="undefined" src/index.ts
+```
+
+This can be useful when Server-Side Rendering (SSR) or when you want to make sure that the code doesn't depend on the `window` object.
+
+```js
+if (typeof window !== "undefined") {
+  console.log("Client-side code");
+} else {
+  console.log("Server-side code");
+}
+```
+
+You can also set the value to be another identifier. For example, to make all usages of `global` be `globalThis`, you can use the following command.
+
+```sh
+bun --define global="globalThis" src/index.ts
+```
+
+`global` is a global object in Node.js, but not in web browsers. So, you can use this to fix some cases where the code assumes that `global` is available.
+
+### Replace values with JSON
+
+`--define` can also be used to replace values with JSON objects and arrays.
+
+To replace all usages of `AWS` with the JSON object `{"ACCESS_KEY":"abc","SECRET_KEY":"def"}`, you can use the following command.
+
+```sh
+# JSON
+bun --define:AWS='{"ACCESS_KEY":"abc","SECRET_KEY":"def"}' src/index.ts
+```
+
+Those will be transformed into the equivalent JavaScript code.
+
+From:
+
+```ts
+console.log(AWS.ACCESS_KEY); // => "abc"
+```
+
+To:
+
+```ts
+console.log("abc");
+```
+
+### Replace values with other properties
+
+You can also pass properties to the `--define` flag.
+
+For example, to replace all usages of `console.write` with `console.log`, you can use the following command (requires Bun v1.1.5 or later)
+
+```sh
+bun --define:console.write=console.log src/index.ts
+```
+
+That transforms the following input:
+
+```ts
+console.write("Hello, world!");
+```
+
+Into the following output:
+
+```ts
+console.log("Hello, world!");
+```
+
+## How is this different than setting a variable?
+
+You can also set `process.env.NODE_ENV` to `"production"` in your code, but that won't help with dead code elimination. In JavaScript, property accesses can have side effects. Getters & setters can be functions, and even dynamically defined (due to prototype chains and Proxy). Even if you set `process.env.NODE_ENV` to `"production"`, on the next line, it is not safe for static analysis tools to assume that `process.env.NODE_ENV`is`"production"`.
+
+## How is this different than find-and-replace or string replacement?
+
+The `--define` flag operates on the AST (Abstract Syntax Tree) level, not on the text level. It happens during the transpilation process, which means it can be used in optimizations like dead code elimination.
+
+String replacement tools tend to have escaping issues and replace unintended parts of the code.

docs/guides/runtime/import-html.md

@@ -0,0 +1,15 @@
+---
+name: Import HTML file as text
+---
+
+To import a `.html` file in Bun as a text file, use the `type: "text"` attribute in the import statement.
+
+```ts
+import html from "./file.html" with { type: "text" };
+
+console.log(html); // <!DOCTYPE html><html><head>...
+```
+
+This can also be used with hot module reloading and/or watch mode to force Bun to reload whenever the `./file.html` file changes.
+
+This feature was added in Bun v1.1.5.

packages/bun-types/bun.d.ts

@@ -3065,6 +3065,7 @@ declare module "bun" {
 
   type SupportedCryptoAlgorithms =
     | "blake2b256"
+    | "blake2b512"
     | "md4"
     | "md5"
     | "ripemd160"
@@ -3073,7 +3074,13 @@ declare module "bun" {
     | "sha256"
     | "sha384"
     | "sha512"
-    | "sha512-256";
+    | "sha512-224"
+    | "sha512-256"
+    | "sha3-224"
+    | "sha3-256"
+    | "sha3-384"
+    | "sha3-512";
+
   /**
    * Hardware-accelerated cryptographic hash functions
    *