bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/project/roadmap.md

@@ -1,87 +0,0 @@
-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

@@ -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.20251104T140728
-
-+ @types/bun@1.3.2-canary.20251104T140728
-+ 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/autoimport.md

@@ -1,94 +0,0 @@
-If no `node_modules` directory is found in the working directory or higher, Bun will abandon Node.js-style module resolution in favor of the **Bun module resolution algorithm**.
-
-Under Bun-style module resolution, all imported packages are auto-installed on the fly into a [global module cache](https://bun.com/docs/install/cache) during execution (the same cache used by [`bun install`](https://bun.com/docs/cli/install)).
-
-```ts
-import { foo } from "foo"; // install `latest` version
-
-foo();
-```
-
-The first time you run this script, Bun will auto-install `"foo"` and cache it. The next time you run the script, it will use the cached version.
-
-## Version resolution
-
-To determine which version to install, Bun follows the following algorithm:
-
-1. Check for a `bun.lock` file in the project root. If it exists, use the version specified in the lockfile.
-2. Otherwise, scan up the tree for a `package.json` that includes `"foo"` as a dependency. If found, use the specified semver version or version range.
-3. Otherwise, use `latest`.
-
-## Cache behavior
-
-Once a version or version range has been determined, Bun will:
-
-1. Check the module cache for a compatible version. If one exists, use it.
-2. When resolving `latest`, Bun will check if `package@latest` has been downloaded and cached in the last _24 hours_. If so, use it.
-3. Otherwise, download and install the appropriate version from the `npm` registry.
-
-## Installation
-
-Packages are installed and cached into `<cache>/<pkg>@<version>`, so multiple versions of the same package can be cached at once. Additionally, a symlink is created under `<cache>/<pkg>/<version>` to make it faster to look up all versions of a package that exist in the cache.
-
-## Version specifiers
-
-This entire resolution algorithm can be short-circuited by specifying a version or version range directly in your import statement.
-
-```ts
-import { z } from "zod@3.0.0"; // specific version
-import { z } from "zod@next"; // npm tag
-import { z } from "zod@^3.20.0"; // semver range
-```
-
-## Benefits
-
-This auto-installation approach is useful for a few reasons:
-
-- **Space efficiency** — Each version of a dependency only exists in one place on disk. This is a huge space and time savings compared to redundant per-project installations.
-- **Portability** — To share simple scripts and gists, your source file is _self-contained_. No need to `zip` together a directory containing your code and config files. With version specifiers in `import` statements, even a `package.json` isn't necessary.
-- **Convenience** — There's no need to run `npm install` or `bun install` before running a file or script. Just `bun run` it.
-- **Backwards compatibility** — Because Bun still respects the versions specified in `package.json` if one exists, you can switch to Bun-style resolution with a single command: `rm -rf node_modules`.
-
-## Limitations
-
-- No Intellisense. TypeScript auto-completion in IDEs relies on the existence of type declaration files inside `node_modules`. We are investigating various solutions to this.
-- No [patch-package](https://github.com/ds300/patch-package) support
-
-<!-- - The implementation details of Bun's install cache will change between versions. Don't think of it as an API. To reliably resolve packages, use Bun's builtin APIs (such as `Bun.resolveSync` or `import.meta.resolve`) instead of relying on the filesystem directly. Bun will likely move to a binary archive format where packages may not correspond to files/folders on disk at all - so if you depend on the filesystem structure instead of the JavaScript API, your code will eventually break. -->
-
-<!-- ## Customizing behavior
-
-To prefer locally-installed versions of packages. Instead of checking npm for latest versions, you can pass the `--prefer-offline` flag to prefer locally-installed versions of packages.
-
-```bash
-$ bun run --prefer-offline my-script.ts
-```
-
-This will check the install cache for installed versions of packages before checking the npm registry. If no matching version of a package is installed, only then will it check npm for the latest version.
-
-#### Prefer latest
-
-To always use the latest version of a package, you can pass the `--prefer-latest` flag.
-
-```bash
-$ bun run --prefer-latest my-script.ts
-``` -->
-
-## FAQ
-
-{% details summary="How is this different from what pnpm does?" %}
-
-With pnpm, you have to run `pnpm install`, which creates a `node_modules` folder of symlinks for the runtime to resolve. By contrast, Bun resolves dependencies on the fly when you run a file; there's no need to run any `install` command ahead of time. Bun also doesn't create a `node_modules` folder.
-
-{% /details %}
-
-{% details summary="How is this different from Yarn Plug'N'Play does?" %}
-With Yarn, you must run `yarn install` before you run a script. By contrast, Bun resolves dependencies on the fly when you run a file; there's no need to run any `install` command ahead of time.
-
-Yarn Plug'N'Play also uses zip files to store dependencies. This makes dependency loading [slower at runtime](https://twitter.com/jarredsumner/status/1458207919636287490), as random access reads on zip files tend to be slower than the equivalent disk lookup.
-{% /details %}
-
-{% details summary="How is this different from what Deno does?" %}
-
-Deno requires an `npm:` specifier before each npm `import`, lacks support for import maps via `compilerOptions.paths` in `tsconfig.json`, and has incomplete support for `package.json` settings. Unlike Deno, Bun does not currently support URL imports.
-{% /details %}

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 %}