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

package/docs/runtime/index.md

@@ -0,0 +1,309 @@
+Bun is a new JavaScript & TypeScript runtime designed to be a faster, leaner, and more modern drop-in replacement for Node.js.
+
+## Speed
+
+Bun is designed to start fast and run fast. Its transpiler and runtime are written in Zig, a modern, high-performance language. On Linux, this translates into startup times [4x faster](https://twitter.com/jarredsumner/status/1499225725492076544) than Node.js.
+
+{% image src="/images/bun-run-speed.jpeg" caption="Bun vs Node.js vs Deno running Hello World" /%}
+
+<!-- If no `node_modules` directory is found in the working directory or above, Bun will abandon Node.js-style module resolution in favor of the `Bun module resolution algorithm`. Under Bun-style module resolution, all packages are _auto-installed_ on the fly into a [global module cache](https://bun.sh/docs/install/cache). For full details on this algorithm, refer to [Runtime > Modules](https://bun.sh/docs/runtime/modules). -->
+
+Performance sensitive APIs like `Buffer`, `fetch`, and `Response` are heavily profiled and optimized. Under the hood Bun uses the [JavaScriptCore engine](https://developer.apple.com/documentation/javascriptcore), which is developed by Apple for Safari. It starts and runs faster than V8, the engine used by Node.js and Chromium-based browsers.
+
+## TypeScript
+
+Bun natively supports TypeScript out of the box. All files are transpiled on the fly by Bun's fast native transpiler before being executed. Similar to other build tools, Bun does not perform typechecking; it simply removes type annotations from the file.
+
+```bash
+$ bun index.js
+$ bun index.jsx
+$ bun index.ts
+$ bun index.tsx
+```
+
+Some aspects of Bun's runtime behavior are affected by the contents of your `tsconfig.json` file. Refer to [Runtime > TypeScript](https://bun.sh/docs/runtime/typescript) page for details.
+
+<!-- Before execution, Bun internally transforms all source files to vanilla JavaScript using its fast native transpiler. The transpiler looks at the files extension to determine how to handle it. -->
+
+<!--
+
+every file before execution. Its transpiler  can directly run TypeScript and JSX `{.js|.jsx|.ts|.tsx}` files directly. During execution, Bun internally transpiles all files (including `.js` files) to vanilla JavaScript with its fast native transpiler. -->
+
+<!-- A loader determines how to map imports &amp; file extensions to transforms and output. -->
+
+<!-- Currently, Bun implements the following loaders: -->
+
+<!-- {% table %}
+
+- Extension
+- Transforms
+- Output (internal)
+
+---
+
+- `.js`
+- JSX + JavaScript
+- `.js`
+
+---
+
+- `.jsx`
+- JSX + JavaScript
+- `.js`
+
+---
+
+- `.ts`
+- TypeScript + JavaScript
+- `.js`
+
+---
+
+- `.tsx`
+- TypeScript + JSX + JavaScript
+- `.js`
+
+---
+
+- `.mjs`
+- JavaScript
+- `.js`
+
+---
+
+- `.cjs`
+- JavaScript
+- `.js`
+
+---
+
+- `.mts`
+- TypeScript
+- `.js`
+
+---
+
+- `.cts`
+- TypeScript
+- `.js`
+
+
+{% /table %} -->
+
+## JSX
+
+## JSON and TOML
+
+Source files can import a `*.json` or `*.toml` file to load its contents as a plain old JavaScript object.
+
+```ts
+import pkg from "./package.json";
+import bunfig from "./bunfig.toml";
+```
+
+## WASI
+
+{% callout %}
+🚧 **Experimental**
+{% /callout %}
+
+Bun has experimental support for WASI, the [WebAssembly System Interface](https://github.com/WebAssembly/WASI). To run a `.wasm` binary with Bun:
+
+```bash
+$ bun ./my-wasm-app.wasm
+# if the filename doesn't end with ".wasm"
+$ bun run ./my-wasm-app.whatever
+```
+
+{% callout %}
+
+**Note** — WASI support is based on [wasi-js](https://github.com/sagemathinc/cowasm/tree/main/core/wasi-js). Currently, it only supports WASI binaries that use the `wasi_snapshot_preview1` or `wasi_unstable` APIs. Bun's implementation is not fully optimized for performance; this will become more of a priority as WASM grows in popularity.
+{% /callout %}
+
+## Node.js compatibility
+
+Long-term, Bun aims for complete Node.js compatibility. Most Node.js packages already work with Bun out of the box, but certain low-level APIs like `dgram` are still unimplemented. Track the current compatibility status at [Ecosystem > Node.js](https://bun.sh/docs/runtime/nodejs-apis).
+
+Bun implements the Node.js module resolution algorithm, so dependencies can still be managed with `package.json`, `node_modules`, and CommonJS-style imports.
+
+{% callout %}
+**Note** — We recommend using Bun's [built-in package manager](https://bun.sh/docs/cli/install) for a performance boost over other npm clients.
+{% /callout %}
+
+## Web APIs
+
+<!-- When prudent, Bun attempts to implement Web-standard APIs instead of introducing new APIs. Refer to [Runtime > Web APIs](https://bun.sh/docs/web-apis) for a list of Web APIs that are available in Bun. -->
+
+Some Web APIs aren't relevant in the context of a server-first runtime like Bun, such as the [DOM API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API#html_dom_api_interfaces) or [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API). Many others, though, are broadly useful outside of the browser context; when possible, Bun implements these Web-standard APIs instead of introducing new APIs.
+
+The following Web APIs are partially or completely supported.
+
+{% table %}
+
+---
+
+- HTTP
+- [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
+
+---
+
+- URLs
+- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+
+---
+
+- Streams
+- [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) [`TransformStream`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) [`ByteLengthQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/ByteLengthQueuingStrategy) [`CountQueuingStrategy`](https://developer.mozilla.org/en-US/docs/Web/API/CountQueuingStrategy) and associated classes
+
+---
+
+- Blob
+- [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
+
+---
+
+- WebSockets
+- [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+
+---
+
+- Encoding and decoding
+- [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/atob) [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/btoa) [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
+
+---
+
+- Timeouts
+- [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout) [`clearTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout)
+
+---
+
+- Intervals
+- [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/setInterval)[`clearInterval`](https://developer.mozilla.org/en-US/docs/Web/API/clearInterval)
+
+---
+
+- Crypto
+- [`crypto`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) [`SubtleCrypto`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
+  [`CryptoKey`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey)
+
+---
+
+- Debugging
+
+- [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) [`performance`](https://developer.mozilla.org/en-US/docs/Web/API/Performance)
+
+---
+
+- Microtasks
+- [`queueMicrotask`](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask)
+
+---
+
+- Errors
+- [`reportError`](https://developer.mozilla.org/en-US/docs/Web/API/reportError)
+
+---
+
+- User interaction
+- [`alert`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert) [`confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm) [`prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) (intended for interactive CLIs)
+
+<!-- - Blocking. Prints the alert message to terminal and awaits `[ENTER]` before proceeding. -->
+<!-- - Blocking. Prints confirmation message and awaits `[y/N]` input from user. Returns `true` if user entered `y` or `Y`, `false` otherwise.
+- Blocking. Prints prompt message and awaits user input. Returns the user input as a string. -->
+
+---
+
+- Realms
+- [`ShadowRealm`](https://github.com/tc39/proposal-shadowrealm)
+
+---
+
+- Events
+- [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+  [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) [`ErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/ErrorEvent) [`CloseEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent) [`MessageEvent`](https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent)
+
+---
+
+{% /table %}
+
+## Bun APIs
+
+Bun exposes a set of Bun-specific APIs on the `Bun` global object and through a number of built-in modules. These APIs represent the canonical "Bun-native" way to perform some common development tasks. They are all heavily optimized for performance. Click the link in the left column to view the associated documentation.
+
+{% table %}
+
+- Topic
+- APIs
+
+---
+
+- [HTTP](https://bun.sh/docs/api/http)
+- `Bun.serve`
+
+---
+
+- [File I/O](https://bun.sh/docs/api/file-io)
+- `Bun.file` `Bun.write`
+
+---
+
+- [Processes](https://bun.sh/docs/api/spawn)
+- `Bun.spawn` `Bun.spawnSync`
+
+---
+
+- [TCP](https://bun.sh/docs/api/tcp)
+- `Bun.listen` `Bun.connect`
+
+---
+
+- [Transpiler](https://bun.sh/docs/api/transpiler)
+- `Bun.Transpiler`
+
+---
+
+- [Routing](https://bun.sh/docs/api/file-system-router)
+- `Bun.FileSystemRouter`
+
+---
+
+- [HTMLRewriter](https://bun.sh/docs/api/html-rewriter)
+- `HTMLRewriter`
+
+---
+
+- [Utils](https://bun.sh/docs/api/utils)
+- `Bun.peek` `Bun.which`
+
+---
+
+- [SQLite](https://bun.sh/docs/api/sqlite)
+- `bun:sqlite`
+
+---
+
+- [FFI](https://bun.sh/docs/api/ffi)
+- `bun:ffi`
+
+---
+
+- [DNS](https://bun.sh/docs/api/dns)
+- `bun:dns`
+
+---
+
+- [Testing](https://bun.sh/docs/api/test)
+- `bun:test`
+
+---
+
+- [Node-API](https://bun.sh/docs/api/node-api)
+- `Node-API`
+
+---
+
+{% /table %}
+
+## Plugins
+
+Support for additional file types can be implemented with plugins. Refer to [Runtime > Plugins](https://bun.sh/docs/bundler/plugins) for full documentation.

package/docs/runtime/jsx.md

@@ -0,0 +1,326 @@
+Bun supports `.jsx` and `.tsx` files out of the box. Bun's internal transpiler converts JSX syntax into vanilla JavaScript before execution.
+
+```tsx#react.tsx
+function Component(props: {message: string}) {
+  return (
+    <body>
+      <h1 style={{color: 'red'}}>{props.message}</h1>
+    </body>
+  );
+}
+
+console.log(<Component message="Hello world!" />);
+```
+
+## Configuration
+
+Bun reads your `tsconfig.json` or `jsconfig.json` configuration files to determines how to perform the JSX transform internally. To avoid using either of these, the following options can also be defined in [`bunfig.toml`](https://bun.sh/docs/runtime/bunfig).
+
+The following compiler options are respected.
+
+### [`jsx`](https://www.typescriptlang.org/tsconfig#jsx)
+
+How JSX constructs are transformed into vanilla JavaScript internally. The table below lists the possible values of `jsx`, along with their transpilation of the following simple JSX component:
+
+```tsx
+<Box width={5}>Hello</Box>
+```
+
+{% table %}
+
+- Compiler options
+- Transpiled output
+
+---
+
+- ```json
+  {
+    "jsx": "react"
+  }
+  ```
+
+- ```tsx
+  import { createElement } from "react";
+  createElement("Box", { width: 5 }, "Hello");
+  ```
+
+---
+
+- ```json
+  {
+    "jsx": "react-jsx"
+  }
+  ```
+
+- ```tsx
+  import { jsx } from "react/jsx-runtime";
+  jsx("Box", { width: 5 }, "Hello");
+  ```
+
+---
+
+- ```json
+  {
+    "jsx": "react-jsxdev"
+  }
+  ```
+
+- ```tsx
+  import { jsxDEV } from "react/jsx-dev-runtime";
+  jsxDEV(
+    "Box",
+    { width: 5, children: "Hello" },
+    undefined,
+    false,
+    undefined,
+    this,
+  );
+  ```
+
+  The `jsxDEV` variable name is a convention used by React. The `DEV` suffix is a visible way to indicate that the code is intended for use in development. The development version of React is slower and includes additional validity checks & debugging tools.
+
+---
+
+- ```json
+  {
+    "jsx": "preserve"
+  }
+  ```
+
+- ```tsx
+  // JSX is not transpiled
+  // "preserve" is not supported by Bun currently
+  <Box width={5}>Hello</Box>
+  ```
+
+{% /table %}
+
+<!-- {% table %}
+
+- `react`
+- `React.createElement("Box", {width: 5}, "Hello")`
+
+---
+
+- `react-jsx`
+- `jsx("Box", {width: 5}, "Hello")`
+
+---
+
+- `react-jsxdev`
+- `jsxDEV("Box", {width: 5}, "Hello", void 0, false)`
+
+---
+
+- `preserve`
+- `<Box width={5}>Hello</Box>` Left as-is; not yet supported by Bun.
+
+{% /table %} -->
+
+### [`jsxFactory`](https://www.typescriptlang.org/tsconfig#jsxFactory)
+
+{% callout %}
+**Note** — Only applicable when `jsx` is `react`.
+{% /callout %}
+
+The function name used to represent JSX constructs. Default value is `"createElement"`. This is useful for libraries like [Preact](https://preactjs.com/) that use a different function name (`"h"`).
+
+{% table %}
+
+- Compiler options
+- Transpiled output
+
+---
+
+- ```json
+  {
+    "jsx": "react",
+    "jsxFactory": "h"
+  }
+  ```
+
+- ```tsx
+  import { h } from "react";
+  h("Box", { width: 5 }, "Hello");
+  ```
+
+{% /table %}
+
+### [`jsxFragmentFactory`](https://www.typescriptlang.org/tsconfig#jsxFragmentFactory)
+
+{% callout %}
+**Note** — Only applicable when `jsx` is `react`.
+{% /callout %}
+
+The function name used to represent [JSX fragments](https://react.dev/reference/react/Fragment) such as `<>Hello</>`; only applicable when `jsx` is `react`. Default value is `"Fragment"`.
+
+{% table %}
+
+- Compiler options
+- Transpiled output
+
+---
+
+- ```json
+  {
+    "jsx": "react",
+    "jsxFactory": "myjsx",
+    "jsxFragmentFactory": "MyFragment"
+  }
+  ```
+
+- ```tsx
+  // input
+  <>Hello</>;
+
+  // output
+  import { myjsx, MyFragment } from "react";
+  myjsx(MyFragment, null, "Hello");
+  ```
+
+{% /table %}
+
+### [`jsxImportSource`](https://www.typescriptlang.org/tsconfig#jsxImportSource)
+
+{% callout %}
+**Note** — Only applicable when `jsx` is `react-jsx` or `react-jsxdev`.
+{% /callout %}
+
+The module from which the component factory function (`createElement`, `jsx`, `jsxDEV`, etc) will be imported. Default value is `"react"`. This will typically be necessary when using a component library like Preact.
+
+{% table %}
+
+- Compiler options
+- Transpiled output
+
+---
+
+- ```jsonc
+  {
+    "jsx": "react",
+    // jsxImportSource is not defined
+    // default to "react"
+  }
+  ```
+
+- ```tsx
+  import { jsx } from "react/jsx-runtime";
+  jsx("Box", { width: 5, children: "Hello" });
+  ```
+
+---
+
+- ```jsonc
+  {
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+  }
+  ```
+
+- ```tsx
+  import { jsx } from "preact/jsx-runtime";
+  jsx("Box", { width: 5, children: "Hello" });
+  ```
+
+---
+
+- ```jsonc
+  {
+    "jsx": "react-jsxdev",
+    "jsxImportSource": "preact",
+  }
+  ```
+
+- ```tsx
+  // /jsx-runtime is automatically appended
+  import { jsxDEV } from "preact/jsx-dev-runtime";
+  jsxDEV(
+    "Box",
+    { width: 5, children: "Hello" },
+    undefined,
+    false,
+    undefined,
+    this,
+  );
+  ```
+
+{% /table %}
+
+### JSX pragma
+
+All of these values can be set on a per-file basis using _pragmas_. A pragma is a special comment that sets a compiler option in a particular file.
+
+{% table %}
+
+- Pragma
+- Equivalent config
+
+---
+
+- ```ts
+  // @jsx h
+  ```
+
+- ```jsonc
+  {
+    "jsxFactory": "h",
+  }
+  ```
+
+---
+
+- ```ts
+  // @jsxFrag MyFragment
+  ```
+- ```jsonc
+  {
+    "jsxFragmentFactory": "MyFragment",
+  }
+  ```
+
+---
+
+- ```ts
+  // @jsxImportSource preact
+  ```
+- ```jsonc
+  {
+    "jsxImportSource": "preact",
+  }
+  ```
+
+{% /table %}
+
+## Logging
+
+Bun implements special logging for JSX to make debugging easier. Given the following file:
+
+```tsx#index.tsx
+import { Stack, UserCard } from "./components";
+
+console.log(
+  <Stack>
+    <UserCard name="Dom" bio="Street racer and Corona lover" />
+    <UserCard name="Jakob" bio="Super spy and Dom's secret brother" />
+  </Stack>
+);
+```
+
+Bun will pretty-print the component tree when logged:
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/d29db51d-6837-44e2-b8be-84fc1b9e9d97" / %}
+
+## Prop punning
+
+The Bun runtime also supports "prop punning" for JSX. This is a shorthand syntax useful for assigning a variable to a prop with the same name.
+
+```tsx
+function Div(props: {className: string;}) {
+  const {className} = props;
+
+  // without punning
+  return <div className={className} />;
+  // with punning
+  return <div {className} />;
+}
+```