bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/pm/workspaces.mdx

@@ -0,0 +1,109 @@
+---
+title: "Workspaces"
+description: "Develop complex monorepos with multiple independent packages"
+---
+
+Bun supports [`workspaces`](https://docs.npmjs.com/cli/v9/using-npm/workspaces?v=true#description) in `package.json`. Workspaces make it easy to develop complex software as a _monorepo_ consisting of several independent packages.
+
+It's common for a monorepo to have the following structure:
+
+```
+tree
+<root>
+├── README.md
+├── bun.lock
+├── package.json
+├── tsconfig.json
+└── packages
+    ├── pkg-a
+    │   ├── index.ts
+    │   ├── package.json
+    │   └── tsconfig.json
+    ├── pkg-b
+    │   ├── index.ts
+    │   ├── package.json
+    │   └── tsconfig.json
+    └── pkg-c
+        ├── index.ts
+        ├── package.json
+        └── tsconfig.json
+```
+
+In the root `package.json`, the `"workspaces"` key is used to indicate which subdirectories should be considered packages/workspaces within the monorepo. It's conventional to place all the workspace in a directory called `packages`.
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "workspaces": ["packages/*"],
+  "devDependencies": {
+    "example-package-in-monorepo": "workspace:*"
+  }
+}
+```
+
+<Note>
+  **Glob support** — Bun supports full glob syntax in `"workspaces"` (see [here](/runtime/glob#supported-glob-patterns)
+  for a comprehensive list of supported syntax), _except_ for exclusions (e.g. `!**/excluded/**`), which are not
+  implemented yet.
+</Note>
+
+Each workspace has it's own `package.json`. When referencing other packages in the monorepo, semver or workspace protocols (e.g. `workspace:*`) can be used as the version field in your `package.json`.
+
+```json
+{
+  "name": "pkg-a",
+  "version": "1.0.0",
+  "dependencies": {
+    "pkg-b": "workspace:*"
+  }
+}
+```
+
+`bun install` will install dependencies for all workspaces in the monorepo, de-duplicating packages if possible. If you only want to install dependencies for specific workspaces, you can use the `--filter` flag.
+
+```bash
+# Install dependencies for all workspaces starting with `pkg-` except for `pkg-c`
+bun install --filter "pkg-*" --filter "!pkg-c"
+
+# Paths can also be used. This is equivalent to the command above.
+bun install --filter "./packages/pkg-*" --filter "!pkg-c" # or --filter "!./packages/pkg-c"
+```
+
+When publishing, `workspace:` versions are replaced by the package's `package.json` version,
+
+```
+"workspace:*" -> "1.0.1"
+"workspace:^" -> "^1.0.1"
+"workspace:~" -> "~1.0.1"
+```
+
+Setting a specific version takes precedence over the package's `package.json` version,
+
+```
+"workspace:1.0.2" -> "1.0.2" // Even if current version is 1.0.1
+```
+
+Workspaces have a couple major benefits.
+
+- **Code can be split into logical parts.** If one package relies on another, you can simply add it as a dependency in `package.json`. If package `b` depends on `a`, `bun install` will install your local `packages/a` directory into `node_modules` instead of downloading it from the npm registry.
+- **Dependencies can be de-duplicated.** If `a` and `b` share a common dependency, it will be _hoisted_ to the root `node_modules` directory. This reduces redundant disk usage and minimizes "dependency hell" issues associated with having multiple versions of a package installed simultaneously.
+- **Run scripts in multiple packages.** You can use the [`--filter` flag](/pm/filter) to easily run `package.json` scripts in multiple packages in your workspace, , or `--workspaces` to run scripts across all workspaces.
+
+## Share versions with Catalogs
+
+When many packages need the same dependency versions, catalogs let you define
+those versions once in the root `package.json` and reference them from your
+workspaces using the `catalog:` protocol. Updating the catalog automatically
+updates every package that references it. See
+[Catalogs](/pm/catalogs) for details.
+
+<Note>
+⚡️ **Speed** — Installs are fast, even for big monorepos. Bun installs the [Remix](https://github.com/remix-run/remix) monorepo in about `500ms` on Linux.
+
+- 28x faster than `npm install`
+- 12x faster than `yarn install` (v1)
+- 8x faster than `pnpm install`
+
+<Image src="https://user-images.githubusercontent.com/709451/212829600-77df9544-7c9f-4d8d-a984-b2cd0fd2aa52.png" />
+</Note>

package/docs/project/benchmarking.mdx

@@ -0,0 +1,218 @@
+---
+title: Benchmarking
+description: How to benchmark Bun
+---
+
+Bun is designed for speed. Hot paths are extensively profiled and benchmarked. The source code for all of Bun's public benchmarks can be found in the [`/bench`](https://github.com/oven-sh/bun/tree/main/bench) directory of the Bun repo.
+
+## Measuring time
+
+To precisely measure time, Bun offers two runtime APIs functions:
+
+1. The Web-standard [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) function
+2. `Bun.nanoseconds()` which is similar to `performance.now()` except it returns the current time since the application started in nanoseconds. You can use `performance.timeOrigin` to convert this to a Unix timestamp.
+
+## Benchmarking tools
+
+When writing your own benchmarks, it's important to choose the right tool.
+
+- For microbenchmarks, a great general-purpose tool is [`mitata`](https://github.com/evanwashere/mitata).
+- For load testing, you _must use_ an HTTP benchmarking tool that is at least as fast as `Bun.serve()`, or your results will be skewed. Some popular Node.js-based benchmarking tools like [`autocannon`](https://github.com/mcollina/autocannon) are not fast enough. We recommend one of the following:
+  - [`bombardier`](https://github.com/codesenberg/bombardier)
+  - [`oha`](https://github.com/hatoo/oha)
+  - [`http_load_test`](https://github.com/uNetworking/uSockets/blob/master/examples/http_load_test.c)
+- For benchmarking scripts or CLI commands, we recommend [`hyperfine`](https://github.com/sharkdp/hyperfine).
+
+## Measuring memory usage
+
+Bun has two heaps. One heap is for the JavaScript runtime and the other heap is for everything else.
+
+### JavaScript heap stats
+
+The `bun:jsc` module exposes a few functions for measuring memory usage:
+
+```ts
+import { heapStats } from "bun:jsc";
+console.log(heapStats());
+```
+
+<Accordion title="View example statistics">
+
+```ts expandable icon="/icons/typescript.svg"
+{
+  heapSize: 1657575,
+  heapCapacity: 2872775,
+  extraMemorySize: 598199,
+  objectCount: 13790,
+  protectedObjectCount: 62,
+  globalObjectCount: 1,
+  protectedGlobalObjectCount: 1,
+  // A count of every object type in the heap
+  objectTypeCounts: {
+    CallbackObject: 25,
+    FunctionExecutable: 2078,
+    AsyncGeneratorFunction: 2,
+    'RegExp String Iterator': 1,
+    FunctionCodeBlock: 188,
+    ModuleProgramExecutable: 13,
+    String: 1,
+    UnlinkedModuleProgramCodeBlock: 13,
+    JSON: 1,
+    AsyncGenerator: 1,
+    Symbol: 1,
+    GetterSetter: 68,
+    ImportMeta: 10,
+    DOMAttributeGetterSetter: 1,
+    UnlinkedFunctionCodeBlock: 174,
+    RegExp: 52,
+    ModuleLoader: 1,
+    Intl: 1,
+    WeakMap: 4,
+    Generator: 2,
+    PropertyTable: 95,
+    'Array Iterator': 1,
+    JSLexicalEnvironment: 75,
+    UnlinkedFunctionExecutable: 2067,
+    WeakSet: 1,
+    console: 1,
+    Map: 23,
+    SparseArrayValueMap: 14,
+    StructureChain: 19,
+    Set: 18,
+    'String Iterator': 1,
+    FunctionRareData: 3,
+    JSGlobalLexicalEnvironment: 1,
+    Object: 481,
+    BigInt: 2,
+    StructureRareData: 55,
+    Array: 179,
+    AbortController: 2,
+    ModuleNamespaceObject: 11,
+    ShadowRealm: 1,
+    'Immutable Butterfly': 103,
+    Primordials: 1,
+    'Set Iterator': 1,
+    JSGlobalProxy: 1,
+    AsyncFromSyncIterator: 1,
+    ModuleRecord: 13,
+    FinalizationRegistry: 1,
+    AsyncIterator: 1,
+    InternalPromise: 22,
+    Iterator: 1,
+    CustomGetterSetter: 65,
+    Promise: 19,
+    WeakRef: 1,
+    InternalPromisePrototype: 1,
+    Function: 2381,
+    AsyncFunction: 2,
+    GlobalObject: 1,
+    ArrayBuffer: 2,
+    Boolean: 1,
+    Math: 1,
+    CallbackConstructor: 1,
+    Error: 2,
+    JSModuleEnvironment: 13,
+    WebAssembly: 1,
+    HashMapBucket: 300,
+    Callee: 3,
+    symbol: 37,
+    string: 2484,
+    Performance: 1,
+    ModuleProgramCodeBlock: 12,
+    JSSourceCode: 13,
+    JSPropertyNameEnumerator: 3,
+    NativeExecutable: 290,
+    Number: 1,
+    Structure: 1550,
+    SymbolTable: 108,
+    GeneratorFunction: 2,
+    'Map Iterator': 1
+  },
+  protectedObjectTypeCounts: {
+    CallbackConstructor: 1,
+    BigInt: 1,
+    RegExp: 2,
+    GlobalObject: 1,
+    UnlinkedModuleProgramCodeBlock: 13,
+    HashMapBucket: 2,
+    Structure: 41,
+    JSPropertyNameEnumerator: 1
+  }
+}
+```
+
+</Accordion>
+
+JavaScript is a garbage-collected language, not reference counted. It's normal and correct for objects to not be freed immediately in all cases, though it's not normal for objects to never be freed.
+
+To force garbage collection to run manually:
+
+```ts
+Bun.gc(true); // synchronous
+Bun.gc(false); // asynchronous
+```
+
+Heap snapshots let you inspect what objects are not being freed. You can use the `bun:jsc` module to take a heap snapshot and then view it with Safari or WebKit GTK developer tools. To generate a heap snapshot:
+
+```ts
+import { generateHeapSnapshot } from "bun";
+
+const snapshot = generateHeapSnapshot();
+await Bun.write("heap.json", JSON.stringify(snapshot, null, 2));
+```
+
+To view the snapshot, open the `heap.json` file in Safari's Developer Tools (or WebKit GTK)
+
+1. Open the Developer Tools
+2. Click "Timeline"
+3. Click "JavaScript Allocations" in the menu on the left. It might not be visible until you click the pencil icon to show all the timelines
+4. Click "Import" and select your heap snapshot JSON
+
+<Frame>
+  <img
+    src="https://user-images.githubusercontent.com/709451/204428943-ba999e8f-8984-4f23-97cb-b4e3e280363e.png"
+    alt="Importing a heap snapshot"
+  />
+</Frame>
+
+Once imported, you should see something like this:
+
+<Frame>
+  <img
+    alt="Viewing heap snapshot in Safari"
+    src="https://user-images.githubusercontent.com/709451/204429337-b0d8935f-3509-4071-b991-217794d1fb27.png"
+    caption="Viewing heap snapshot in Safari Dev Tools"
+  />
+</Frame>
+
+> The [web debugger](/runtime/debugger#inspect) also offers the timeline feature which allows you to track and examine the memory usage of the running debug session.
+
+### Native heap stats
+
+Bun uses mimalloc for the other heap. To report a summary of non-JavaScript memory usage, set the `MIMALLOC_SHOW_STATS=1` environment variable. and stats will print on exit.
+
+```sh terminal icon="terminal"
+MIMALLOC_SHOW_STATS=1 bun script.js
+```
+
+```txt
+heap stats:    peak      total      freed    current       unit      count
+  reserved:   64.0 MiB   64.0 MiB      0       64.0 MiB                        not all freed!
+ committed:   64.0 MiB   64.0 MiB      0       64.0 MiB                        not all freed!
+     reset:      0          0          0          0                            ok
+   touched:  128.5 KiB  128.5 KiB    5.4 MiB   -5.3 MiB                        ok
+  segments:      1          1          0          1                            not all freed!
+-abandoned:      0          0          0          0                            ok
+   -cached:      0          0          0          0                            ok
+     pages:      0          0         53        -53                            ok
+-abandoned:      0          0          0          0                            ok
+ -extended:      0
+ -noretire:      0
+     mmaps:      0
+   commits:      0
+   threads:      0          0          0          0                            ok
+  searches:     0.0 avg
+numa nodes:       1
+   elapsed:       0.068 s
+   process: user: 0.061 s, system: 0.014 s, faults: 0, rss: 57.4 MiB, commit: 64.0 MiB
+```

package/docs/project/bindgen.mdx

@@ -0,0 +1,223 @@
+---
+title: Bindgen
+description: Bindgen for Bun
+---
+
+<Note>This document is for maintainers and contributors to Bun, and describes internal implementation details.</Note>
+
+The new bindings generator, introduced to the codebase in Dec 2024, scans for
+`*.bind.ts` to find function and class definition, and generates glue code to
+interop between JavaScript and native code.
+
+There are currently other code generators and systems that achieve similar
+purposes. The following will all eventually be completely phased out in favor of
+this one:
+
+- "Classes generator", converting `*.classes.ts` for custom classes.
+- "JS2Native", allowing ad-hoc calls from `src/js` to native code.
+
+## Creating JS Functions in Zig
+
+Given a file implementing a simple function, such as `add`
+
+```zig src/bun.js/math.zig
+pub fn add(global: *jsc.JSGlobalObject, a: i32, b: i32) !i32 {
+    return std.math.add(i32, a, b) catch {
+        // Binding functions can return `error.OutOfMemory` and `error.JSError`.
+        // Others like `error.Overflow` from `std.math.add` must be converted.
+        // Remember to be descriptive.
+        return global.throwPretty("Integer overflow while adding", .{});
+    };
+}
+
+const gen = bun.gen.math; // "math" being this file's basename
+
+const std = @import("std");
+const bun = @import("bun");
+const jsc = bun.jsc;
+```
+
+Then describe the API schema using a `.bind.ts` function. The binding file goes next to the Zig file.
+
+```ts src/bun.js/math.bind.ts icon="/icons/typescript.svg"
+import { t, fn } from "bindgen";
+
+export const add = fn({
+  args: {
+    global: t.globalObject,
+    a: t.i32,
+    b: t.i32.default(1),
+  },
+  ret: t.i32,
+});
+```
+
+This function declaration is equivalent to:
+
+```ts
+/**
+ * Throws if zero arguments are provided.
+ * Wraps out of range numbers using modulo.
+ */
+declare function add(a: number, b: number = 1): number;
+```
+
+The code generator will provide `bun.gen.math.jsAdd`, which is the native
+function implementation. To pass to JavaScript, use
+`bun.gen.math.createAddCallback(global)`. JS files in `src/js/` may use
+`$bindgenFn("math.bind.ts", "add")` to get a handle to the implementation.
+
+## Strings
+
+The type for receiving strings is one of [`t.DOMString`](https://webidl.spec.whatwg.org/#idl-DOMString), [`t.ByteString`](https://webidl.spec.whatwg.org/#idl-ByteString), and [`t.USVString`](https://webidl.spec.whatwg.org/#idl-USVString). These map directly to their WebIDL counterparts, and have slightly different conversion logic. Bindgen will pass BunString to native code in all cases.
+
+When in doubt, use DOMString.
+
+`t.UTF8String` can be used in place of `t.DOMString`, but will call `bun.String.toUTF8`. The native callback gets `[]const u8` (WTF-8 data) passed to native code, freeing it after the function returns.
+
+TLDRs from WebIDL spec:
+
+- ByteString can only contain valid latin1 characters. It is not safe to assume bun.String is already in 8-bit format, but it is extremely likely.
+- USVString will not contain invalid surrogate pairs, aka text that can be represented correctly in UTF-8.
+- DOMString is the loosest but also most recommended strategy.
+
+## Function Variants
+
+A `variants` can specify multiple variants (also known as overloads).
+
+```ts src/bun.js/math.bind.ts icon="/icons/typescript.svg"
+import { t, fn } from "bindgen";
+
+export const action = fn({
+  variants: [
+    {
+      args: {
+        a: t.i32,
+      },
+      ret: t.i32,
+    },
+    {
+      args: {
+        a: t.DOMString,
+      },
+      ret: t.DOMString,
+    },
+  ],
+});
+```
+
+In Zig, each variant gets a number, based on the order the schema defines.
+
+```zig
+fn action1(a: i32) i32 {
+  return a;
+}
+
+fn action2(a: bun.String) bun.String {
+  return a;
+}
+```
+
+## `t.dictionary`
+
+A `dictionary` is a definition for a JavaScript object, typically as a function inputs. For function outputs, it is usually a smarter idea to declare a class type to add functions and destructuring.
+
+## Enumerations
+
+To use [WebIDL's enumeration](https://webidl.spec.whatwg.org/#idl-enums) type, use either:
+
+- `t.stringEnum`: Create and codegen a new enum type.
+- `t.zigEnum`: Derive a bindgen type off of an existing enum in the codebase.
+
+An example of `stringEnum` as used in `fmt.zig` / `bun:internal-for-testing`
+
+```ts
+export const Formatter = t.stringEnum("highlight-javascript", "escape-powershell");
+
+export const fmtString = fn({
+  args: {
+    global: t.globalObject,
+    code: t.UTF8String,
+    formatter: Formatter,
+  },
+  ret: t.DOMString,
+});
+```
+
+WebIDL strongly encourages using kebab case for enumeration values, to be consistent with existing Web APIs.
+
+### Deriving enums from Zig code
+
+TODO: zigEnum
+
+## `t.oneOf`
+
+A `oneOf` is a union between two or more types. It is represented by `union(enum)` in Zig.
+
+TODO:
+
+## Attributes
+
+There are set of attributes that can be chained onto `t.*` types. On all types there are:
+
+- `.required`, in dictionary parameters only
+- `.optional`, in function arguments only
+- `.default(T)`
+
+When a value is optional, it is lowered to a Zig optional.
+
+Depending on the type, there are more attributes available. See the type definitions in auto-complete for more details. Note that one of the above three can only be applied, and they must be applied at the end.
+
+### Integer Attributes
+
+Integer types allow customizing the overflow behavior with `clamp` or `enforceRange`
+
+```ts
+import { t, fn } from "bindgen";
+
+export const add = fn({
+  args: {
+    global: t.globalObject,
+    // enforce in i32 range
+    a: t.i32.enforceRange(),
+    // clamp to u16 range
+    b: t.u16,
+    // enforce in arbitrary range, with a default if not provided
+    c: t.i32.enforceRange(0, 1000).default(5),
+    // clamp to arbitrary range, or null
+    d: t.u16.clamp(0, 10).optional,
+  },
+  ret: t.i32,
+});
+```
+
+Various Node.js validator functions such as `validateInteger`, `validateNumber`, and more are available. Use these when implementing Node.js APIs, so the error messages match 1:1 what Node would do.
+
+Unlike `enforceRange`, which is taken from WebIDL, `validate*` functions are much more strict on the input they accept. For example, Node's numerical validator check `typeof value === 'number'`, while WebIDL uses `ToNumber` for lossy conversion.
+
+```ts
+import { t, fn } from "bindgen";
+
+export const add = fn({
+  args: {
+    global: t.globalObject,
+    // throw if not given a number
+    a: t.f64.validateNumber(),
+    // valid in i32 range
+    a: t.i32.validateInt32(),
+    // f64 within safe integer range
+    b: t.f64.validateInteger(),
+    // f64 in given range
+    c: t.f64.validateNumber(-10000, 10000),
+  },
+  ret: t.i32,
+});
+```
+
+## Callbacks
+
+TODO
+
+## Classes
+
+TODO

package/docs/project/building-windows.mdx

@@ -0,0 +1,133 @@
+---
+title: Building Windows
+description: Building Bun on Windows
+---
+
+This document describes the build process for Windows. If you run into problems, please join the [#contributing channel on our Discord](http://bun.com/discord) for help.
+
+It is strongly recommended to use [PowerShell 7 (`pwsh.exe`)](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4) instead of the default `powershell.exe`.
+
+## Prerequisites
+
+### Enable Scripts
+
+By default, running unverified scripts are blocked.
+
+```ps1
+> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted
+```
+
+### System Dependencies
+
+Bun v1.1 or later. We use Bun to run it's own code generators.
+
+```ps1
+> irm bun.com/install.ps1 | iex
+```
+
+[Visual Studio](https://visualstudio.microsoft.com) with the "Desktop Development with C++" workload. While installing, make sure to install Git as well, if Git for Windows is not already installed.
+
+Visual Studio can be installed graphically using the wizard or through WinGet:
+
+```ps1
+> winget install "Visual Studio Community 2022" --override "--add Microsoft.VisualStudio.Workload.NativeDesktop Microsoft.VisualStudio.Component.Git " -s msstore
+```
+
+After Visual Studio, you need the following:
+
+- LLVM 19.1.7
+- Go
+- Rust
+- NASM
+- Perl
+- Ruby
+- Node.js
+
+<Note>The Zig compiler is automatically downloaded, installed, and updated by the building process.</Note>
+
+[Scoop](https://scoop.sh) can be used to install these remaining tools easily.
+
+```ps1 Scoop
+> irm https://get.scoop.sh | iex
+> scoop install nodejs-lts go rust nasm ruby perl sccache
+# scoop seems to be buggy if you install llvm and the rest at the same time
+> scoop install llvm@19.1.7
+```
+
+<Note>
+  Please do not use WinGet/other package manager for these, as you will likely install Strawberry Perl instead of a more
+  minimal installation of Perl. Strawberry Perl includes many other utilities that get installed into `$Env:PATH` that
+  will conflict with MSVC and break the build.
+</Note>
+
+If you intend on building WebKit locally (optional), you should install these packages:
+
+```ps1 Scoop
+> scoop install make cygwin python
+```
+
+From here on out, it is **expected you use a PowerShell Terminal with `.\scripts\vs-shell.ps1` sourced**. This script is available in the Bun repository and can be loaded by executing it:
+
+```ps1
+> .\scripts\vs-shell.ps1
+```
+
+To verify, you can check for an MSVC-only command line such as `mt.exe`
+
+```ps1
+> Get-Command mt
+```
+
+<Note>
+  It is not recommended to install `ninja` / `cmake` into your global path, because you may run into a situation where
+  you try to build bun without .\scripts\vs-shell.ps1 sourced.
+</Note>
+
+## Building
+
+```ps1
+> bun run build
+
+# after the initial `bun run build` you can use the following to build
+> ninja -Cbuild/debug
+```
+
+If this was successful, you should have a `bun-debug.exe` in the `build/debug` folder.
+
+```ps1
+> .\build\debug\bun-debug.exe --revision
+```
+
+You should add this to `$Env:PATH`. The simplest way to do so is to open the start menu, type "Path", and then navigate the environment variables menu to add `C:\.....\bun\build\debug` to the user environment variable `PATH`. You should then restart your editor (if it does not update still, log out and log back in).
+
+## Extra paths
+
+- WebKit is extracted to `build/debug/cache/webkit/`
+- Zig is extracted to `build/debug/cache/zig/bin/zig.exe`
+
+## Tests
+
+You can run the test suite either using `bun test <path>` or by using the wrapper script `bun node:test <path>`. The `bun node:test` command runs every test file in a separate instance of bun.exe, to prevent a crash in the test runner from stopping the entire suite.
+
+```ps1
+# Setup
+> bun i --cwd packages\bun-internal-test
+
+# Run the entire test suite with reporter
+# the package.json script "test" uses "build/debug/bun-debug.exe" by default
+> bun run test
+
+# Run an individual test file:
+> bun-debug test node\fs
+> bun-debug test "C:\bun\test\js\bun\resolve\import-meta.test.js"
+```
+
+## Troubleshooting
+
+### .rc file fails to build
+
+`llvm-rc.exe` is odd. don't use it. use `rc.exe`, to do this make sure you are in a visual studio dev terminal, check `rc /?` to ensure it is `Microsoft Resource Compiler`
+
+### failed to write output 'bun-debug.exe': permission denied
+
+you cannot overwrite `bun-debug.exe` if it is already open. you likely have a running instance, maybe in the vscode debugger?