bun-types 1.3.2-canary.20251105T140650 → 1.3.2-canary.20251106T140813

package/docs/project/asan.md

@@ -1,124 +0,0 @@
-# ASAN Builds for Bun
-
-This document explains how to use and configure ASAN (Address Sanitizer) builds for Bun.
-
-> **Note**: ASAN builds are available in CI for Linux and are configured to help identify memory issues in release builds.
-
-## What is ASAN?
-
-ASAN (Address Sanitizer) is a memory error detector for C/C++ and Zig code. It can detect:
-
-- Use-after-free
-- Heap buffer overflow
-- Stack buffer overflow
-- Global buffer overflow
-- Use-after-return
-- Use-after-scope
-- Initialization order bugs
-- Memory leaks
-
-## ASAN Builds in CI
-
-Bun CI includes ASAN builds to catch memory errors. These builds are configured with:
-
-- Release optimizations for speed
-- ASAN instrumentation for memory error detection
-- Assertions enabled for both Bun and WebKit
-
-The CI pipeline automatically:
-
-- Builds a special ASAN-enabled release build for Linux
-- Runs all tests to thoroughly check for memory issues
-- Uses reduced parallelism to avoid memory pressure during testing
-- Applies suppressions for known false positives
-- Extends test timeouts to accommodate ASAN overhead
-- Includes ASAN builds in release artifacts for debugging purposes
-
-## Local ASAN Builds
-
-To build Bun with ASAN locally, you can use the npm script:
-
-```bash
-# Build a release build with ASAN and assertions (recommended)
-bun run build:asan
-```
-
-Or manually with CMake:
-
-```bash
-# Debug build with ASAN
-cmake -B build -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON
-
-# Release build with ASAN
-cmake -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_ASAN=ON
-
-# Release build with ASAN and assertions
-cmake -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_ASAN=ON -DENABLE_ASSERTIONS=ON
-```
-
-## Running with ASAN
-
-When running an ASAN build, you can configure behavior with environment variables:
-
-```bash
-# Basic ASAN options - leak detection disabled (recommended)
-ASAN_OPTIONS=detect_leaks=0:halt_on_error=0:detect_odr_violation=0 ./build/bun-asan
-
-# If you really need leak detection (will produce A LOT of noise)
-# ASAN_OPTIONS=detect_leaks=1:leak_check_at_exit=1:halt_on_error=0 ./build/bun-asan
-# LSAN_OPTIONS=suppressions=lsan.supp:print_suppressions=1 ./build/bun-asan
-```
-
-> **Warning**: Enabling leak detection will generate excessive noise due to deliberately uncollected memory in WebKit and other components. It's recommended to keep leak detection disabled and focus on other memory errors like use-after-free, buffer overflows, etc.
-
-## Other Memory Error Types
-
-ASAN can detect several types of memory errors:
-
-1. **Use-after-free**: When a program continues to use memory after it's been freed
-2. **Buffer overflow**: When a program writes beyond the bounds of allocated memory
-3. **Stack overflow**: When a function's stack usage exceeds available space
-4. **Memory corruption**: Often caused by writing to invalid memory locations
-5. **Use-after-return**: When a function returns a pointer to stack memory that's no longer valid
-
-When an error is detected, ASAN will print a helpful report showing:
-
-- The type of error
-- The memory address where the error occurred
-- A stack trace showing the code path that led to the error
-- Information about the memory allocation/deallocation (if relevant)
-
-Example error output:
-
-```
-==1234==ERROR: AddressSanitizer: heap-use-after-free on address 0x614000000044 at pc 0x55d8e2ac1f14...
-READ of size 4 at 0x614000000044 thread T0
-    #0 0x55d8e2ac1f14 in main example.c:10
-    #1 0x7f91e6f5e0b2 in __libc_start_main...
-```
-
-## Understanding ASAN Reports
-
-ASAN reports contain detailed information about memory errors:
-
-```
-==12345==ERROR: AddressSanitizer: heap-use-after-free on address 0x7f7ddab8c084
-READ of size 4 at 0x7f7ddab8c084 thread T0
-    #0 0x43b45a in Function source/file.cpp:123:45
-    #1 0x44af90 in AnotherFunction source/file.cpp:234:10
-    ...
-```
-
-Key components of the report:
-
-- Error type (heap-use-after-free, heap-buffer-overflow, etc.)
-- Operation (READ/WRITE) and size
-- Stack trace showing where the error occurred
-- Information about the allocated/freed memory
-
-## Best Practices
-
-1. Run tests with ASAN builds regularly
-2. Add suppressions only for well-understood false positives
-3. Fix real issues promptly - ASAN errors indicate real problems
-4. Consider using ASAN in debug builds during development

package/docs/project/benchmarking.md

@@ -1,203 +0,0 @@
-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.com/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/bindgen.md

@@ -1,225 +0,0 @@
-{% callout %}
-
-This document is for maintainers and contributors to Bun, and describes internal implementation details.
-
-{% /callout %}
-
-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
-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
-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