bun-types 1.1.37-canary.20241123T140655 → 1.1.37-canary.20241125T140601

package/docs/api/workers.md

@@ -0,0 +1,230 @@
+{% callout %}
+**🚧** — The `Worker` API is still experimental and should not be considered ready for production.
+{% /callout %}
+
+[`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) lets you start and communicate with a new JavaScript instance running on a separate thread while sharing I/O resources with the main thread.
+
+Bun implements a minimal version of the [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) with extensions that make it work better for server-side use cases. Like the rest of Bun, `Worker` in Bun support CommonJS, ES Modules, TypeScript, JSX, TSX and more out of the box. No extra build steps are necessary.
+
+## Creating a `Worker`
+
+Like in browsers, [`Worker`](https://developer.mozilla.org/en-US/docs/Web/API/Worker) is a global. Use it to create a new worker thread.
+
+### From the main thread
+
+```js#Main_thread
+const worker = new Worker("./worker.ts");
+
+worker.postMessage("hello");
+worker.onmessage = event => {
+  console.log(event.data);
+};
+```
+
+### Worker thread
+
+```ts#worker.ts_(Worker_thread)
+// prevents TS errors
+declare var self: Worker;
+
+self.onmessage = (event: MessageEvent) => {
+  console.log(event.data);
+  postMessage("world");
+};
+```
+
+To prevent TypeScript errors when using `self`, add this line to the top of your worker file.
+
+```ts
+declare var self: Worker;
+```
+
+You can use `import` and `export` syntax in your worker code. Unlike in browsers, there's no need to specify `{type: "module"}` to use ES Modules.
+
+To simplify error handling, the initial script to load is resolved at the time `new Worker(url)` is called.
+
+```js
+const worker = new Worker("/not-found.js");
+// throws an error immediately
+```
+
+The specifier passed to `Worker` is resolved relative to the project root (like typing `bun ./path/to/file.js`).
+
+### `preload` - load modules before the worker starts
+
+You can pass an array of module specifiers to the `preload` option to load modules before the worker starts. This is useful when you want to ensure some code is always loaded before the application starts, like loading OpenTelemetry, Sentry, DataDog, etc.
+
+```js
+const worker = new Worker("./worker.ts", {
+  preload: ["./load-sentry.js"],
+});
+```
+
+Like the `--preload` CLI argument, the `preload` option is processed before the worker starts.
+
+You can also pass a single string to the `preload` option:
+
+```js
+const worker = new Worker("./worker.ts", {
+  preload: "./load-sentry.js",
+});
+```
+
+This feature was added in Bun v1.1.35.
+
+### `blob:` URLs
+
+As of Bun v1.1.13, you can also pass a `blob:` URL to `Worker`. This is useful for creating workers from strings or other sources.
+
+```js
+const blob = new Blob(
+  [
+    `
+  self.onmessage = (event: MessageEvent) => postMessage(event.data)`,
+  ],
+  {
+    type: "application/typescript",
+  },
+);
+const url = URL.createObjectURL(blob);
+const worker = new Worker(url);
+```
+
+Like the rest of Bun, workers created from `blob:` URLs support TypeScript, JSX, and other file types out of the box. You can communicate it should be loaded via typescript either via `type` or by passing a `filename` to the `File` constructor.
+
+```js
+const file = new File(
+  [
+    `
+  self.onmessage = (event: MessageEvent) => postMessage(event.data)`,
+  ],
+  "worker.ts",
+);
+const url = URL.createObjectURL(file);
+const worker = new Worker(url);
+```
+
+### `"open"`
+
+The `"open"` event is emitted when a worker is created and ready to receive messages. This can be used to send an initial message to a worker once it's ready. (This event does not exist in browsers.)
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+worker.addEventListener("open", () => {
+  console.log("worker is ready");
+});
+```
+
+Messages are automatically enqueued until the worker is ready, so there is no need to wait for the `"open"` event to send messages.
+
+## Messages with `postMessage`
+
+To send messages, use [`worker.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage) and [`self.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). This leverages the [HTML Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+
+```js
+// On the worker thread, `postMessage` is automatically "routed" to the parent thread.
+postMessage({ hello: "world" });
+
+// On the main thread
+worker.postMessage({ hello: "world" });
+```
+
+To receive messages, use the [`message` event handler](https://developer.mozilla.org/en-US/docs/Web/API/Worker/message_event) on the worker and main thread.
+
+```js
+// Worker thread:
+self.addEventListener("message", event => {
+  console.log(event.data);
+});
+// or use the setter:
+// self.onmessage = fn
+
+// if on the main thread
+worker.addEventListener("message", event => {
+  console.log(event.data);
+});
+// or use the setter:
+// worker.onmessage = fn
+```
+
+## Terminating a worker
+
+A `Worker` instance terminates automatically once it's event loop has no work left to do. Attaching a `"message"` listener on the global or any `MessagePort`s will keep the event loop alive. To forcefully terminate a `Worker`, call `worker.terminate()`.
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+// ...some time later
+worker.terminate();
+```
+
+This will cause the worker's to exit as soon as possible.
+
+### `process.exit()`
+
+A worker can terminate itself with `process.exit()`. This does not terminate the main process. Like in Node.js, `process.on('beforeExit', callback)` and `process.on('exit', callback)` are emitted on the worker thread (and not on the main thread), and the exit code is passed to the `"close"` event.
+
+### `"close"`
+
+The `"close"` event is emitted when a worker has been terminated. It can take some time for the worker to actually terminate, so this event is emitted when the worker has been marked as terminated. The `CloseEvent` will contain the exit code passed to `process.exit()`, or 0 if closed for other reasons.
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+
+worker.addEventListener("close", event => {
+  console.log("worker is being closed");
+});
+```
+
+This event does not exist in browsers.
+
+## Managing lifetime
+
+By default, an active `Worker` will keep the main (spawning) process alive, so async tasks like `setTimeout` and promises will keep the process alive. Attaching `message` listeners will also keep the `Worker` alive.
+
+### `worker.unref()`
+
+To stop a running worker from keeping the process alive, call `worker.unref()`. This decouples the lifetime of the worker to the lifetime of the main process, and is equivalent to what Node.js' `worker_threads` does.
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+worker.unref();
+```
+
+Note: `worker.unref()` is not available in browsers.
+
+### `worker.ref()`
+
+To keep the process alive until the `Worker` terminates, call `worker.ref()`. A ref'd worker is the default behavior, and still needs something going on in the event loop (such as a `"message"` listener) for the worker to continue running.
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href);
+worker.unref();
+// later...
+worker.ref();
+```
+
+Alternatively, you can also pass an `options` object to `Worker`:
+
+```ts
+const worker = new Worker(new URL("worker.ts", import.meta.url).href, {
+  ref: false,
+});
+```
+
+Note: `worker.ref()` is not available in browsers.
+
+## Memory usage with `smol`
+
+JavaScript instances can use a lot of memory. Bun's `Worker` supports a `smol` mode that reduces memory usage, at a cost of performance. To enable `smol` mode, pass `smol: true` to the `options` object in the `Worker` constructor.
+
+```js
+const worker = new Worker("./i-am-smol.ts", {
+  smol: true,
+});
+```
+
+{% details summary="What does `smol` mode actually do?" %}
+Setting `smol: true` sets `JSC::HeapSize` to be `Small` instead of the default `Large`.
+{% /details %}

package/docs/benchmarks.md

@@ -0,0 +1,120 @@
+Bun.js focuses on performance, developer experience, and compatibility with the JavaScript ecosystem.
+
+## HTTP Requests
+
+```ts
+// http.ts
+export default {
+  port: 3000,
+  fetch(request: Request) {
+    return new Response("Hello World");
+  },
+};
+
+// bun ./http.ts
+```
+
+| Requests per second                                                    | OS    | CPU                            | Bun version |
+| ---------------------------------------------------------------------- | ----- | ------------------------------ | ----------- |
+| [260,000](https://twitter.com/jarredsumner/status/1512040623200616449) | macOS | Apple Silicon M1 Max           | 0.0.76      |
+| [160,000](https://twitter.com/jarredsumner/status/1511988933587976192) | Linux | AMD Ryzen 5 3600 6-Core 2.2ghz | 0.0.76      |
+
+{% details summary="See benchmark details" %}
+Measured with [`http_load_test`](https://github.com/uNetworking/uSockets/blob/master/examples/http_load_test.c) by running:
+
+```bash
+$ ./http_load_test  20 127.0.0.1 3000
+```
+
+{% /details %}
+
+## File System
+
+`cat` clone that runs [2x faster than GNU cat](https://twitter.com/jarredsumner/status/1511707890708586496) for large files on Linux
+
+```js
+// cat.js
+import { resolve } from "path";
+import { write, stdout, file, argv } from "bun";
+
+const path = resolve(argv.at(-1));
+
+await write(
+  // stdout is a Blob
+  stdout,
+  // file(path) returns a Blob - https://developer.mozilla.org/en-US/docs/Web/API/Blob
+  file(path),
+);
+```
+
+Run this with `bun cat.js /path/to/big/file`.
+
+## Reading from standard input
+
+```ts
+for await (const line of console) {
+  // line of text from stdin
+  console.log(line);
+}
+```
+
+## React SSR
+
+```js
+import { renderToReadableStream } from "react-dom/server";
+
+const dt = new Intl.DateTimeFormat();
+
+export default {
+  port: 3000,
+  async fetch(request: Request) {
+    return new Response(
+      await renderToReadableStream(
+        <html>
+          <head>
+            <title>Hello World</title>
+          </head>
+          <body>
+            <h1>Hello from React!</h1>
+            <p>The date is {dt.format(new Date())}</p>
+          </body>
+        </html>,
+      ),
+    );
+  },
+};
+```
+
+Write to stdout with `console.write`:
+
+```js
+// no trailing newline
+// works with strings and typed arrays
+console.write("Hello World!");
+```
+
+There are some more examples in the [examples](./examples) folder.
+
+PRs adding more examples are very welcome!
+
+## Fast paths for Web APIs
+
+Bun.js has fast paths for common use cases that make Web APIs live up to the performance demands of servers and CLIs.
+
+`Bun.file(path)` returns a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) that represents a lazily-loaded file.
+
+When you pass a file blob to `Bun.write`, Bun automatically uses a faster system call:
+
+```js
+const blob = Bun.file("input.txt");
+await Bun.write("output.txt", blob);
+```
+
+On Linux, this uses the [`copy_file_range`](https://man7.org/linux/man-pages/man2/copy_file_range.2.html) syscall and on macOS, this becomes `clonefile` (or [`fcopyfile`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/copyfile.3.html)).
+
+`Bun.write` also supports [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects. It automatically converts to a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
+
+```js
+// Eventually, this will stream the response to disk but today it buffers
+await Bun.write("index.html", await fetch("https://example.com"));
+```

package/docs/bun-flavored-toml.md

@@ -0,0 +1,42 @@
+[TOML](https://toml.io/) is a minimal configuration file format designed to be easy for humans to read.
+
+Bun implements a TOML parser with a few tweaks designed for better interoperability with INI files and with JavaScript.
+
+### ; and # are comments
+
+In Bun-flavored TOML, comments start with `#` or `;`
+
+```ini
+# This is a comment
+; This is also a comment
+```
+
+This matches the behavior of INI files.
+
+In TOML, comments start with `#`
+
+```toml
+# This is a comment
+```
+
+### String escape characters
+
+Bun-flavored adds a few more escape sequences to TOML to work better with JavaScript strings.
+
+```
+# Bun-flavored TOML extras
+\x{XX}     - ASCII           (U+00XX)
+\u{x+}     - unicode         (U+0000000X) - (U+XXXXXXXX)
+\v         - vertical tab
+
+# Regular TOML
+\b         - backspace       (U+0008)
+\t         - tab             (U+0009)
+\n         - linefeed        (U+000A)
+\f         - form feed       (U+000C)
+\r         - carriage return (U+000D)
+\"         - quote           (U+0022)
+\\         - backslash       (U+005C)
+\uXXXX     - unicode         (U+XXXX)
+\UXXXXXXXX - unicode         (U+XXXXXXXX)
+```

package/docs/bundler/executables.md

@@ -0,0 +1,291 @@
+Bun's bundler implements a `--compile` flag for generating a standalone binary from a TypeScript or JavaScript file.
+
+{% codetabs %}
+
+```bash
+$ bun build ./cli.ts --compile --outfile mycli
+```
+
+```ts#cli.ts
+console.log("Hello world!");
+```
+
+{% /codetabs %}
+
+This bundles `cli.ts` into an executable that can be executed directly:
+
+```
+$ ./mycli
+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.
+
+## Cross-compile to other platforms
+
+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.
+
+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
+```
+
+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.
+
+With compiled executables, you can move that cost from runtime to build-time.
+
+When deploying to production, we recommend the following:
+
+```sh
+bun build --compile --minify --sourcemap ./path/to/my/app.ts --outfile myapp
+```
+
+### Bytecode compilation
+
+To improve startup time, enable bytecode compilation:
+
+```sh
+bun build --compile --minify --sourcemap --bytecode ./path/to/my/app.ts --outfile myapp
+```
+
+Using bytecode compilation, `tsc` starts 2x faster:
+
+{% image src="https://github.com/user-attachments/assets/dc8913db-01d2-48f8-a8ef-ac4e984f9763" width="689" /%}
+
+Bytecode compilation moves parsing overhead for large input files from runtime to bundle time. Your app starts faster, in exchange for making the `bun build` command a little slower. It doesn't obscure source code.
+
+**Experimental:** Bytecode compilation is an experimental feature introduced in Bun v1.1.30. Only `cjs` format is supported (which means no top-level-await). Let us know if you run into any issues!
+
+### What do these flags do?
+
+The `--minify` argument optimizes the size of the transpiled output code. If you have a large application, this can save megabytes of space. For smaller applications, it might still improve start time a little.
+
+The `--sourcemap` argument embeds a sourcemap compressed with zstd, so that errors & stacktraces point to their original locations instead of the transpiled location. Bun will automatically decompress & resolve the sourcemap when an error occurs.
+
+The `--bytecode` argument enables bytecode compilation. Every time you run JavaScript code in Bun, JavaScriptCore (the engine) will compile your source code into bytecode. We can move this parsing work from runtime to bundle time, saving you startup time.
+
+## Worker
+
+To use workers in a standalone executable, add the worker's entrypoint to the CLI arguments:
+
+```sh
+$ bun build --compile ./index.ts ./my-worker.ts --outfile myapp
+```
+
+Then, reference the worker in your code:
+
+```ts
+console.log("Hello from Bun!");
+
+// Any of these will work:
+new Worker("./my-worker.ts");
+new Worker(new URL("./my-worker.ts", import.meta.url));
+new Worker(new URL("./my-worker.ts", import.meta.url).href);
+```
+
+As of Bun v1.1.25, when you add multiple entrypoints to a standalone executable, they will be bundled separately into the executable.
+
+In the future, we may automatically detect usages of statically-known paths in `new Worker(path)` and then bundle those into the executable, but for now, you'll need to add it to the shell command manually like the above example.
+
+If you use a relative path to a file not included in the standalone executable, it will attempt to load that path from disk relative to the current working directory of the process (and then error if it doesn't exist).
+
+## SQLite
+
+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" };
+
+console.log(db.query("select * from users LIMIT 1").get());
+```
+
+That means if the executable is located at `/usr/bin/hello`, the user's terminal is located at `/home/me/Desktop`, it will look for `/home/me/Desktop/my.db`.
+
+```
+$ cd /home/me/Desktop
+$ ./hello
+```
+
+## Embed assets & files
+
+Standalone executables support embedding files.
+
+To embed files into an executable with `bun build --compile`, import the file in your code
+
+```ts
+// this becomes an internal file path
+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));
+  },
+};
+```
+
+Embedded files can be read using `Bun.file`'s functions or the Node.js `fs.readFile` function (in `"node:fs"`).
+
+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" };
+
+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).
+
+### Embed N-API Addons
+
+As of Bun v1.0.23, you can embed `.node` files into executables.
+
+```js
+const addon = require("./addon.node");
+
+console.log(addon.hello());
+```
+
+Unfortunately, if you're using `@mapbox/node-pre-gyp` or other similar tools, you'll need to make sure the `.node` file is directly required or it won't bundle correctly.
+
+### Embed directories
+
+To embed a directory with `bun build --compile`, use a shell glob in your `bun build` command:
+
+```sh
+$ bun build --compile ./index.ts ./public/**/*.png
+```
+
+Then, you can reference the files in your code:
+
+```ts
+import icon from "./public/assets/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));
+  },
+};
+```
+
+This is honestly a workaround, and we expect to improve this in the future with a more direct API.
+
+### Listing embedded files
+
+To get a list of all embedded files, use `Bun.embeddedFiles`:
+
+```js
+import "./icon.png" with { type: "file" };
+import { embeddedFiles } from "bun";
+
+console.log(embeddedFiles[0].name); // `icon-${hash}.png`
+```
+
+`Bun.embeddedFiles` returns an array of `Blob` objects which you can use to get the size, contents, and other properties of the files.
+
+```ts
+embeddedFiles: Blob[]
+```
+
+The list of embedded files excludes bundled source code like `.ts` and `.js` files.
+
+#### Content hash
+
+By default, embedded files have a content hash appended to their name. This is useful for situations where you want to serve the file from a URL or CDN and have fewer cache invalidation issues. But sometimes, this is unexpected and you might want the original name instead:
+
+To disable the content hash, pass `--asset-naming` to `bun build --compile` like this:
+
+```sh
+$ bun build --compile --asset-naming="[name].[ext]" ./index.ts
+```
+
+## 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.