bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/quickstart.md

@@ -1,157 +0,0 @@
-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
-
-? Select a project template - Press return to submit.
-❯ Blank
-  React
-  Library
-
-✓ Select a project template: Blank
-
-+ .gitignore
-+ index.ts
-+ tsconfig.json (for editor autocomplete)
-+ README.md
-
-To get started, run:
-
-    bun run index.ts
-
-bun install v1.3.2-canary.20251105T140650
-
-+ @types/bun@1.3.2-canary.20251105T140650
-+ typescript@5.9.2
-
-7 packages installed
-```
-
-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.com/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": "Preserve",
-    "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",
-    "private": true,
-+   "scripts": {
-+     "start": "bun run index.ts"
-+   },
-    "devDependencies": {
-      "@types/bun": "latest"
-    },
-    "peerDependencies": {
-      "typescript": "^5"
-    }
-  }
-```
-
-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
-  ____              _
- | __ ) _   _ _ __ | |
- |  _ \| | | | '_ \| |
- | |_) | |_| | | | |_|
- |____/ \__,_|_| |_(_)
-```

package/docs/runtime/bun-apis.md

@@ -1,207 +0,0 @@
-Bun implements a set of native APIs on the `Bun` global object and through a number of built-in modules. These APIs are heavily optimized and represent the canonical "Bun-native" way to implement some common functionality.
-
-Bun strives to implement standard Web APIs wherever possible. Bun introduces new APIs primarily for server-side tasks where no standard exists, such as file I/O and starting an HTTP server. In these cases, Bun's approach still builds atop standard APIs like `Blob`, `URL`, and `Request`.
-
-```ts
-Bun.serve({
-  fetch(req: Request) {
-    return new Response("Success!");
-  },
-});
-```
-
-Click the link in the right column to jump to the associated documentation.
-
-{% table %}
-
-- Topic
-- APIs
-
----
-
-- HTTP Server
-- [`Bun.serve`](https://bun.com/docs/api/http#bun-serve)
-
----
-
-- Shell
-- [`$`](https://bun.com/docs/runtime/shell)
-
----
-
-- Bundler
-- [`Bun.build`](https://bun.com/docs/bundler)
-
----
-
-- File I/O
-- [`Bun.file`](https://bun.com/docs/api/file-io#reading-files-bun-file), [`Bun.write`](https://bun.com/docs/api/file-io#writing-files-bun-write), `Bun.stdin`, `Bun.stdout`, `Bun.stderr`
-
----
-
-- Child Processes
-- [`Bun.spawn`](https://bun.com/docs/api/spawn#spawn-a-process-bun-spawn), [`Bun.spawnSync`](https://bun.com/docs/api/spawn#blocking-api-bun-spawnsync)
-
----
-
-- TCP Sockets
-- [`Bun.listen`](https://bun.com/docs/api/tcp#start-a-server-bun-listen), [`Bun.connect`](https://bun.com/docs/api/tcp#start-a-server-bun-listen)
-
----
-
-- UDP Sockets
-- [`Bun.udpSocket`](https://bun.com/docs/api/udp)
-
----
-
-- WebSockets
-- `new WebSocket()` (client), [`Bun.serve`](https://bun.com/docs/api/websockets) (server)
-
----
-
-- Transpiler
-- [`Bun.Transpiler`](https://bun.com/docs/api/transpiler)
-
----
-
-- Routing
-- [`Bun.FileSystemRouter`](https://bun.com/docs/api/file-system-router)
-
----
-
-- Streaming HTML
-- [`HTMLRewriter`](https://bun.com/docs/api/html-rewriter)
-
----
-
-- Hashing
-- [`Bun.password`](https://bun.com/docs/api/hashing#bun-password), [`Bun.hash`](https://bun.com/docs/api/hashing#bun-hash), [`Bun.CryptoHasher`](https://bun.com/docs/api/hashing#bun-cryptohasher), `Bun.sha`
-
----
-
-- SQLite
-- [`bun:sqlite`](https://bun.com/docs/api/sqlite)
-
----
-
-- PostgreSQL Client
-- [`Bun.SQL`](https://bun.com/docs/api/sql), `Bun.sql`
-
----
-
-- Redis (Valkey) Client
-- [`Bun.RedisClient`](https://bun.com/docs/api/redis), `Bun.redis`
-
----
-
-- FFI (Foreign Function Interface)
-- [`bun:ffi`](https://bun.com/docs/api/ffi)
-
----
-
-- DNS
-- [`Bun.dns.lookup`](https://bun.com/docs/api/dns), `Bun.dns.prefetch`, `Bun.dns.getCacheStats`
-
----
-
-- Testing
-- [`bun:test`](https://bun.com/docs/cli/test)
-
----
-
-- Workers
-- [`new Worker()`](https://bun.com/docs/api/workers)
-
----
-
-- Module Loaders
-- [`Bun.plugin`](https://bun.com/docs/bundler/plugins)
-
----
-
-- Glob
-- [`Bun.Glob`](https://bun.com/docs/api/glob)
-
----
-
-- Cookies
-- [`Bun.Cookie`](https://bun.com/docs/api/cookie), [`Bun.CookieMap`](https://bun.com/docs/api/cookie)
-
----
-
-- Node-API
-- [`Node-API`](https://bun.com/docs/api/node-api)
-
----
-
-- `import.meta`
-- [`import.meta`](https://bun.com/docs/api/import-meta)
-
----
-
-- Utilities
-- [`Bun.version`](https://bun.com/docs/api/utils#bun-version), [`Bun.revision`](https://bun.com/docs/api/utils#bun-revision), [`Bun.env`](https://bun.com/docs/api/utils#bun-env), [`Bun.main`](https://bun.com/docs/api/utils#bun-main)
-
----
-
-- Sleep & Timing
-- [`Bun.sleep()`](https://bun.com/docs/api/utils#bun-sleep), [`Bun.sleepSync()`](https://bun.com/docs/api/utils#bun-sleepsync), [`Bun.nanoseconds()`](https://bun.com/docs/api/utils#bun-nanoseconds)
-
----
-
-- Random & UUID
-- [`Bun.randomUUIDv7()`](https://bun.com/docs/api/utils#bun-randomuuidv7)
-
----
-
-- System & Environment
-- [`Bun.which()`](https://bun.com/docs/api/utils#bun-which)
-
----
-
-- Comparison & Inspection
-- [`Bun.peek()`](https://bun.com/docs/api/utils#bun-peek), [`Bun.deepEquals()`](https://bun.com/docs/api/utils#bun-deepequals), `Bun.deepMatch`, [`Bun.inspect()`](https://bun.com/docs/api/utils#bun-inspect)
-
----
-
-- String & Text Processing
-- [`Bun.escapeHTML()`](https://bun.com/docs/api/utils#bun-escapehtml), [`Bun.stringWidth()`](https://bun.com/docs/api/utils#bun-stringwidth), `Bun.indexOfLine`
-
----
-
-- URL & Path Utilities
-- [`Bun.fileURLToPath()`](https://bun.com/docs/api/utils#bun-fileurltopath), [`Bun.pathToFileURL()`](https://bun.com/docs/api/utils#bun-pathtofileurl)
-
----
-
-- Compression
-- [`Bun.gzipSync()`](https://bun.com/docs/api/utils#bun-gzipsync), [`Bun.gunzipSync()`](https://bun.com/docs/api/utils#bun-gunzipsync), [`Bun.deflateSync()`](https://bun.com/docs/api/utils#bun-deflatesync), [`Bun.inflateSync()`](https://bun.com/docs/api/utils#bun-inflatesync), `Bun.zstdCompressSync()`, `Bun.zstdDecompressSync()`, `Bun.zstdCompress()`, `Bun.zstdDecompress()`
-
----
-
-- Stream Processing
-- [`Bun.readableStreamTo*()`](https://bun.com/docs/api/utils#bun-readablestreamto), `Bun.readableStreamToBytes()`, `Bun.readableStreamToBlob()`, `Bun.readableStreamToFormData()`, `Bun.readableStreamToJSON()`, `Bun.readableStreamToArray()`
-
----
-
-- Memory & Buffer Management
-- `Bun.ArrayBufferSink`, `Bun.allocUnsafe`, `Bun.concatArrayBuffers`
-
----
-
-- Module Resolution
-- [`Bun.resolveSync()`](https://bun.com/docs/api/utils#bun-resolvesync)
-
----
-
-- Parsing & Formatting
-- [`Bun.semver`](https://bun.com/docs/api/semver), `Bun.TOML.parse`, [`Bun.YAML.parse`](https://bun.com/docs/api/yaml), [`Bun.color`](https://bun.com/docs/api/color)
-
----
-
-- Low-level / Internals
-- `Bun.mmap`, `Bun.gc`, `Bun.generateHeapSnapshot`, [`bun:jsc`](https://bun.com/reference/bun/jsc)
-
----
-
-{% /table %}

package/docs/runtime/env.md

@@ -1,253 +0,0 @@
-Bun reads your `.env` files automatically and provides idiomatic ways to read and write your environment variables programmatically. Plus, some aspects of Bun's runtime behavior can be configured with Bun-specific environment variables.
-
-## Setting environment variables
-
-Bun reads the following files automatically (listed in order of increasing precedence).
-
-- `.env`
-- `.env.production`, `.env.development`, `.env.test` (depending on value of `NODE_ENV`)
-- `.env.local`
-
-{% callout %}
-**Note:** When `NODE_ENV=test`, `.env.local` is **not** loaded. This ensures consistent test environments across different executions by preventing local overrides during testing. This behavior matches popular frameworks like [Next.js](https://nextjs.org/docs/pages/guides/environment-variables#test-environment-variables) and [Create React App](https://create-react-app.dev/docs/adding-custom-environment-variables/#what-other-env-files-can-be-used).
-{% /callout %}
-
-```txt#.env
-FOO=hello
-BAR=world
-```
-
-Variables can also be set via the command line.
-
-{% codetabs %}
-
-```sh#Linux/macOS
-$ FOO=helloworld bun run dev
-```
-
-```sh#Windows
-# Using CMD
-$ set FOO=helloworld && bun run dev
-
-# Using PowerShell
-$ $env:FOO="helloworld"; bun run dev
-```
-
-{% /codetabs %}
-
-{% details summary="Cross-platform solution with Windows" %}
-
-For a cross-platform solution, you can use [bun shell](https://bun.com/docs/runtime/shell). For example, the `bun exec` command.
-
-```sh
-$ bun exec 'FOO=helloworld bun run dev'
-```
-
-On Windows, `package.json` scripts called with `bun run` will automatically use the **bun shell**, making the following also cross-platform.
-
-```json#package.json
-"scripts": {
-  "dev": "NODE_ENV=development bun --watch app.ts",
-},
-```
-
-{% /details %}
-
-Or programmatically by assigning a property to `process.env`.
-
-```ts
-process.env.FOO = "hello";
-```
-
-### Manually specifying `.env` files
-
-Bun supports `--env-file` to override which specific `.env` file to load. You can use `--env-file` when running scripts in bun's runtime, or when running package.json scripts.
-
-```sh
-$ bun --env-file=.env.1 src/index.ts
-
-$ bun --env-file=.env.abc --env-file=.env.def run build
-```
-
-### Quotation marks
-
-Bun supports double quotes, single quotes, and template literal backticks:
-
-```txt#.env
-FOO='hello'
-FOO="hello"
-FOO=`hello`
-```
-
-### Expansion
-
-Environment variables are automatically _expanded_. This means you can reference previously-defined variables in your environment variables.
-
-```txt#.env
-FOO=world
-BAR=hello$FOO
-```
-
-```ts
-process.env.BAR; // => "helloworld"
-```
-
-This is useful for constructing connection strings or other compound values.
-
-```txt#.env
-DB_USER=postgres
-DB_PASSWORD=secret
-DB_HOST=localhost
-DB_PORT=5432
-DB_URL=postgres://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME
-```
-
-This can be disabled by escaping the `$` with a backslash.
-
-```txt#.env
-FOO=world
-BAR=hello\$FOO
-```
-
-```ts
-process.env.BAR; // => "hello$FOO"
-```
-
-### `dotenv`
-
-Generally speaking, you won't need `dotenv` or `dotenv-expand` anymore, because Bun reads `.env` files automatically.
-
-## Reading environment variables
-
-The current environment variables can be accessed via `process.env`.
-
-```ts
-process.env.API_TOKEN; // => "secret"
-```
-
-Bun also exposes these variables via `Bun.env` and `import.meta.env`, which is a simple alias of `process.env`.
-
-```ts
-Bun.env.API_TOKEN; // => "secret"
-import.meta.env.API_TOKEN; // => "secret"
-```
-
-To print all currently-set environment variables to the command line, run `bun --print process.env`. This is useful for debugging.
-
-```sh
-$ bun --print process.env
-BAZ=stuff
-FOOBAR=aaaaaa
-<lots more lines>
-```
-
-## TypeScript
-
-In TypeScript, all properties of `process.env` are typed as `string | undefined`.
-
-```ts
-Bun.env.whatever;
-// string | undefined
-```
-
-To get autocompletion and tell TypeScript to treat a variable as a non-optional string, we'll use [interface merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces).
-
-```ts
-declare module "bun" {
-  interface Env {
-    AWESOME: string;
-  }
-}
-```
-
-Add this line to any file in your project. It will globally add the `AWESOME` property to `process.env` and `Bun.env`.
-
-```ts
-process.env.AWESOME; // => string
-```
-
-## Configuring Bun
-
-These environment variables are read by Bun and configure aspects of its behavior.
-
-{% table %}
-
-- Name
-- Description
-
----
-
-- `NODE_TLS_REJECT_UNAUTHORIZED`
-- `NODE_TLS_REJECT_UNAUTHORIZED=0` disables SSL certificate validation. This is useful for testing and debugging, but you should be very hesitant to use this in production. Note: This environment variable was originally introduced by Node.js and we kept the name for compatibility.
-
----
-
-- `BUN_CONFIG_VERBOSE_FETCH`
-- If `BUN_CONFIG_VERBOSE_FETCH=curl`, then fetch requests will log the url, method, request headers and response headers to the console. This is useful for debugging network requests. This also works with `node:http`. `BUN_CONFIG_VERBOSE_FETCH=1` is equivalent to `BUN_CONFIG_VERBOSE_FETCH=curl` except without the `curl` output.
-
----
-
-- `BUN_RUNTIME_TRANSPILER_CACHE_PATH`
-- The runtime transpiler caches the transpiled output of source files larger than 50 kb. This makes CLIs using Bun load faster. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is set, then the runtime transpiler will cache transpiled output to the specified directory. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is set to an empty string or the string `"0"`, then the runtime transpiler will not cache transpiled output. If `BUN_RUNTIME_TRANSPILER_CACHE_PATH` is unset, then the runtime transpiler will cache transpiled output to the platform-specific cache directory.
-
----
-
-- `TMPDIR`
-- Bun occasionally requires a directory to store intermediate assets during bundling or other operations. If unset, defaults to the platform-specific temporary directory: `/tmp` on Linux, `/private/tmp` on macOS.
-
----
-
-- `NO_COLOR`
-- If `NO_COLOR=1`, then ANSI color output is [disabled](https://no-color.org/).
-
----
-
-- `FORCE_COLOR`
-- If `FORCE_COLOR=1`, then ANSI color output is force enabled, even if `NO_COLOR` is set.
-
----
-
-- `BUN_CONFIG_MAX_HTTP_REQUESTS`
-- Control the maximum number of concurrent HTTP requests sent by fetch and `bun install`. Defaults to `256`. If you are running into rate limits or connection issues, you can reduce this number.
-
----
-
-- `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD`
-- If `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD=true`, then `bun --watch` will not clear the console on reload
-
----
-
-- `DO_NOT_TRACK`
-- Disable uploading crash reports to `bun.report` on crash. On macOS & Windows, crash report uploads are enabled by default. Otherwise, telemetry is not sent yet as of May 21st, 2024, but we are planning to add telemetry in the coming weeks. If `DO_NOT_TRACK=1`, then auto-uploading crash reports and telemetry are both [disabled](https://do-not-track.dev/).
-
----
-
-- `BUN_OPTIONS`
-- Prepends command-line arguments to any Bun execution. For example, `BUN_OPTIONS="--hot"` makes `bun run dev` behave like `bun --hot run dev`.
-
-{% /table %}
-
-## Runtime transpiler caching
-
-For files larger than 50 KB, Bun caches transpiled output into `$BUN_RUNTIME_TRANSPILER_CACHE_PATH` or the platform-specific cache directory. This makes CLIs using Bun load faster.
-
-This transpiler cache is global and shared across all projects. It is safe to delete the cache at any time. It is a content-addressable cache, so it will never contain duplicate entries. It is also safe to delete the cache while a Bun process is running.
-
-It is recommended to disable this cache when using ephemeral filesystems like Docker. Bun's Docker images automatically disable this cache.
-
-### Disable the runtime transpiler cache
-
-To disable the runtime transpiler cache, set `BUN_RUNTIME_TRANSPILER_CACHE_PATH` to an empty string or the string `"0"`.
-
-```sh
-BUN_RUNTIME_TRANSPILER_CACHE_PATH=0 bun run dev
-```
-
-### What does it cache?
-
-It caches:
-
-- The transpiled output of source files larger than 50 KB.
-- The sourcemap for the transpiled output of the file
-
-The file extension `.pile` is used for these cached files.