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

package/docs/project/benchmarking.md

@@ -0,0 +1,203 @@
+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.
+
+{% anchor id="bunjsc" /%}
+
+### JavaScript heap stats
+
+The `bun:jsc` module exposes a few functions for measuring memory usage:
+
+```ts
+import { heapStats } from "bun:jsc";
+console.log(heapStats());
+```
+
+{% details summary="View example statistics"  %}
+
+```ts
+{
+  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
+  }
+}
+```
+
+{% /details %}
+
+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:
+
+```js
+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
+
+{% image alt="Import heap json" src="https://user-images.githubusercontent.com/709451/204428943-ba999e8f-8984-4f23-97cb-b4e3e280363e.png" caption="Importing a heap snapshot" /%}
+
+Once imported, you should see something like this:
+
+{% image 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" /%}
+
+> The [web debugger](https://bun.sh/docs/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.
+
+```js
+MIMALLOC_SHOW_STATS=1 bun script.js
+
+# will show something like this:
+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/building-windows.md

@@ -0,0 +1,162 @@
+This document describes the build process for Windows. If you run into problems, please join the [#contributing channel on our Discord](http://bun.sh/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
+
+<!--
+{% details summary="Extra notes for Bun Core Team Members" %}
+
+Here are the extra steps I ran on my fresh windows machine (some of these are a little opiniated)
+
+- Change user to a local account (set username to `window` and 'bun!')
+- Set Windows Terminal as default terminal
+- Install latest version of Powershell
+- Display scale to 100%
+- Remove McAfee and enable Windows Defender (default antivirus, does not nag you)
+- Install Software
+  - OpenSSH server (run these in an elevated terminal)
+    - `Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0`
+    - `Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0`
+    - `Start-Service sshd`
+    - `Set-Service -Name sshd -StartupType 'Automatic'`
+    - `New-ItemProperty -Path "HKLM:\SOFTWARE\OpenSSH" -Name DefaultShell -Value "C:\Program Files\PowerShell\7\pwsh.exe" -PropertyType String -Force`
+    - Configure in `C:\ProgramData\ssh`
+    - Add ssh keys (in ProgramData because it is an admin account)
+  - Tailscale (login with GitHub so it joins the team tailnet)
+  - Visual Studio Code
+- Configure `git`
+  - `git config user.name "your name"`
+  - `git config user.email "your@email"`
+- Disable sleep mode and the lid switch by going to "Power Options" and configuring everything there.
+
+I recommend using VSCode through SSH instead of Tunnels or the Tailscale extension, it seems to be more reliable.
+
+{% /details %} -->
+
+### 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.sh/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 18.1.8
+- Go
+- Rust
+- NASM
+- Perl
+- Ruby
+- Node.js
+- Ccache
+
+{% callout %}
+**Note** – The Zig compiler is automatically downloaded, installed, and updated by the building process.
+{% /callout %}
+
+[Scoop](https://scoop.sh) can be used to install these remaining tools easily.
+
+{% codetabs group="a" %}
+
+```ps1#Scoop
+> irm https://get.scoop.sh | iex
+> scoop install nodejs-lts go rust nasm ruby perl ccache
+# scoop seems to be buggy if you install llvm and the rest at the same time
+> scoop install llvm@18.1.8
+```
+
+{% /codetabs %}
+
+{% callout %}
+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.
+{% /callout %}
+
+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
+```
+
+{% callout %}
+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.
+{% /callout %}
+
+## 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 `packages\bun-internal-test`. The internal test package is a wrapper cli to run 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?

package/docs/project/internals/build-process-for-ci.md

@@ -0,0 +1,75 @@
+There are four parts to the CI build:
+
+- Dependencies: should be cached across builds as much as possible, it depends on git submodule hashes
+- Zig Object: depends on \*.zig and src/js
+- C++ Object: depends on \*.cpp and src/js
+- Linking: depends on the above three
+
+Utilizing multiple GitHub Action runners allows us to do a lot of work in parallel.
+
+## Dependencies
+
+```sh
+BUN_DEPS_OUT_DIR="/optional/out/dir" bash ./scripts/all-dependencies.sh
+```
+
+## Zig Object
+
+This does not have a dependency on WebKit or any of the dependencies at all. It can be compiled without checking out submodules, but you will need to have bun install run. It can be very easily cross compiled. Note that the zig object is always `bun-zig.o`.
+
+```sh
+BUN_REPO=/path/to/oven-sh/bun
+
+cd tmp1
+
+cmake $BUN_REPO \
+  -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCPU_TARGET="native" \
+  -DZIG_TARGET="native" \
+  -DBUN_ZIG_OBJ_DIR="./build"
+
+ninja ./build/bun-zig.o
+# -> bun-zig.o
+```
+
+## C++ Object
+
+Note: if WEBKIT_DIR is not passed, it is automatically downloaded from GitHub releases. This depends on the headers from submodules but not necessarily the build copies of them, .a files, etc.
+
+```sh
+cd tmp2
+
+cmake $BUN_REPO \
+  -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DBUN_CPP_ONLY=1 \
+
+bash compile-cpp-only.sh
+# -> bun-cpp-objects.a
+```
+
+## Linking
+
+The goal is you run both stages from above on different machines, so that they can build in parallel. Zig build is slow, and MacOS build runners are slower on average than the linux ones. With both artifacts from above, you can link them together:
+
+```sh
+cd tmp3
+
+cmake $BUN_REPO \
+  -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DBUN_LINK_ONLY=1 \
+  -DBUN_ZIG_OBJ_DIR="/path/to/bun-zig-dir" \
+  -DBUN_CPP_ARCHIVE="/path/to/bun-cpp-objects.a"
+
+ninja
+
+# optional:
+#   -DBUN_DEPS_OUT_DIR=... custom deps dir, use this to cache the built deps between rebuilds
+#   -DWEBKIT_DIR=... same thing, but it's probably fast enough to pull from github releases
+
+# -> bun
+# -> bun-profile
+# -> bun.dSYM/
+```

package/docs/project/roadmap.md

@@ -0,0 +1,87 @@
+Bun is a project with an incredibly large scope and is still in its early days. Long-term, Bun aims to provide an all-in-one toolkit to replace the complex, fragmented toolchains common today: Node.js, Jest, Webpack, esbuild, Babel, yarn, PostCSS, etc.
+
+Refer to [Bun's Roadmap](https://github.com/oven-sh/bun/issues/159) on GitHub to learn more about the project's long-term plans and priorities.
+
+<!--
+{% table %}
+
+- Feature
+- Implemented in
+
+---
+
+- Web Streams with HTMLRewriter
+- Bun.js
+
+---
+
+- Source Maps (unbundled is supported)
+- JS Bundler
+
+---
+
+- Source Maps
+- CSS
+
+---
+
+- JavaScript Minifier
+- JS Transpiler
+
+---
+
+- CSS Minifier
+- CSS
+
+---
+
+- CSS Parser (it only bundles)
+- CSS
+
+---
+
+- Tree-shaking
+- JavaScript
+
+---
+
+- Tree-shaking
+- CSS
+
+---
+
+- [TypeScript Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
+- TS Transpiler
+
+---
+
+- `@jsxPragma` comments
+- JS Transpiler
+
+---
+
+- Sharing `.bun` files
+- Bun
+
+---
+
+- Dates & timestamps
+- TOML parser
+
+---
+
+- [Hash components for Fast Refresh](https://github.com/oven-sh/bun/issues/18)
+- JSX Transpiler
+
+{% /table %} -->
+
+<!-- ## Limitations & intended usage
+
+Today, Bun is mostly focused on Bun.js: the JavaScript runtime.
+
+While you could use Bun's bundler & transpiler separately to build for browsers or node, Bun doesn't have a minifier or support tree-shaking yet. For production browser builds, you probably should use a tool like esbuild or swc.
+
+## Upcoming breaking changes
+
+- Bun's CLI flags will change to better support Bun as a JavaScript runtime. They were chosen when Bun was just a frontend development tool.
+- Bun's bundling format will change to accommodate production browser bundles and on-demand production bundling -->

package/docs/quickstart.md

@@ -0,0 +1,144 @@
+Let's write a simple HTTP server using the built-in `Bun.serve` API. First, create a fresh directory.
+
+```bash
+$ mkdir quickstart
+$ cd quickstart
+```
+
+Run `bun init` to scaffold a new project. It's an interactive tool; for this tutorial, just press `enter` to accept the default answer for each prompt.
+
+```bash
+$ bun init
+bun init helps you get started with a minimal project and tries to
+guess sensible defaults. Press ^C anytime to quit.
+
+package name (quickstart):
+entry point (index.ts):
+
+Done! A package.json file was saved in the current directory.
+ + index.ts
+ + .gitignore
+ + tsconfig.json (for editor auto-complete)
+ + README.md
+
+To get started, run:
+  bun run index.ts
+```
+
+Since our entry point is a `*.ts` file, Bun generates a `tsconfig.json` for you. If you're using plain JavaScript, it will generate a [`jsconfig.json`](https://code.visualstudio.com/docs/languages/jsconfig) instead.
+
+## Run a file
+
+Open `index.ts` and paste the following code snippet, which implements a simple HTTP server with [`Bun.serve`](https://bun.sh/docs/api/http).
+
+```ts
+const server = Bun.serve({
+  port: 3000,
+  fetch(req) {
+    return new Response("Bun!");
+  },
+});
+
+console.log(`Listening on http://localhost:${server.port} ...`);
+```
+
+{% details summary="Seeing TypeScript errors on `Bun`?" %}
+If you used `bun init`, Bun will have automatically installed Bun's TypeScript declarations and configured your `tsconfig.json`. If you're trying out Bun in an existing project, you may see a type error on the `Bun` global.
+
+To fix this, first install `@types/bun` as a dev dependency.
+
+```sh
+$ bun add -d @types/bun
+```
+
+Then add the following to your `compilerOptions` in `tsconfig.json`:
+
+```json#tsconfig.json
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+  }
+}
+```
+
+{% /details %}
+
+Run the file from your shell.
+
+```bash
+$ bun index.ts
+Listening on http://localhost:3000 ...
+```
+
+Visit [http://localhost:3000](http://localhost:3000) to test the server. You should see a simple page that says "Bun!".
+
+## Run a script
+
+Bun can also execute `"scripts"` from your `package.json`. Add the following script:
+
+```json-diff
+  {
+    "name": "quickstart",
+    "module": "index.ts",
+    "type": "module",
++   "scripts": {
++     "start": "bun run index.ts"
++   },
+    "devDependencies": {
+      "@types/bun": "^1.0.0"
+    }
+  }
+```
+
+Then run it with `bun run start`.
+
+```bash
+$ bun run start
+  $ bun run index.ts
+  Listening on http://localhost:3000 ...
+```
+
+{% callout %}
+⚡️ **Performance** — `bun run` is roughly 28x faster than `npm run` (6ms vs 170ms of overhead).
+{% /callout %}
+
+## Install a package
+
+Let's make our server a little more interesting by installing a package. First install the `figlet` package and its type declarations. Figlet is a utility for converting strings into ASCII art.
+
+```bash
+$ bun add figlet
+$ bun add -d @types/figlet # TypeScript users only
+```
+
+Update `index.ts` to use `figlet` in the `fetch` handler.
+
+```ts-diff
++ import figlet from "figlet";
+
+  const server = Bun.serve({
+    port: 3000,
+    fetch(req) {
++     const body = figlet.textSync("Bun!");
++     return new Response(body);
+-     return new Response("Bun!");
+    },
+  });
+```
+
+Restart the server and refresh the page. You should see a new ASCII art banner.
+
+```txt
+  ____              _
+ | __ ) _   _ _ __ | |
+ |  _ \| | | | '_ \| |
+ | |_) | |_| | | | |_|
+ |____/ \__,_|_| |_(_)
+```