npm - bun-types - Versions diffs - 1.1.37-canary.20241124T140524 → 1.1.37 - Mend

bun-types 1.1.37-canary.20241124T140524 → 1.1.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (272) hide show

package/docs/api/binary-data.md +1028 -0
package/docs/api/cc.md +197 -0
package/docs/api/color.md +262 -0
package/docs/api/console.md +38 -0
package/docs/api/dns.md +113 -0
package/docs/api/fetch.md +308 -0
package/docs/api/ffi.md +536 -0
package/docs/api/file-io.md +358 -0
package/docs/api/file-system-router.md +112 -0
package/docs/api/file.md +19 -0
package/docs/api/glob.md +157 -0
package/docs/api/globals.md +387 -0
package/docs/api/hashing.md +314 -0
package/docs/api/html-rewriter.md +31 -0
package/docs/api/http.md +661 -0
package/docs/api/import-meta.md +69 -0
package/docs/api/node-api.md +16 -0
package/docs/api/semver.md +52 -0
package/docs/api/spawn.md +441 -0
package/docs/api/sqlite.md +692 -0
package/docs/api/streams.md +214 -0
package/docs/api/tcp.md +221 -0
package/docs/api/test.md +1 -0
package/docs/api/transpiler.md +274 -0
package/docs/api/udp.md +125 -0
package/docs/api/utils.md +773 -0
package/docs/api/websockets.md +547 -0
package/docs/api/workers.md +230 -0
package/docs/benchmarks.md +120 -0
package/docs/bun-flavored-toml.md +42 -0
package/docs/bundler/executables.md +291 -0
package/docs/bundler/index.md +1543 -0
package/docs/bundler/intro.md +75 -0
package/docs/bundler/loaders.md +288 -0
package/docs/bundler/macros.md +327 -0
package/docs/bundler/plugins.md +30 -0
package/docs/bundler/vs-esbuild.md +1127 -0
package/docs/cli/add.md +163 -0
package/docs/cli/bun-completions.md +3 -0
package/docs/cli/bun-create.md +254 -0
package/docs/cli/bun-dev.md +21 -0
package/docs/cli/bun-install.md +255 -0
package/docs/cli/bun-upgrade.md +39 -0
package/docs/cli/bunx.md +80 -0
package/docs/cli/filter.md +57 -0
package/docs/cli/init.md +40 -0
package/docs/cli/install.md +205 -0
package/docs/cli/link.md +38 -0
package/docs/cli/outdated.md +61 -0
package/docs/cli/patch-commit.md +9 -0
package/docs/cli/pm.md +150 -0
package/docs/cli/publish.md +107 -0
package/docs/cli/remove.md +5 -0
package/docs/cli/run.md +196 -0
package/docs/cli/test.md +247 -0
package/docs/cli/unlink.md +7 -0
package/docs/cli/update.md +34 -0
package/docs/contributing/upgrading-webkit.md +57 -0
package/docs/ecosystem/elysia.md +24 -0
package/docs/ecosystem/express.md +37 -0
package/docs/ecosystem/hono.md +18 -0
package/docs/ecosystem/react.md +65 -0
package/docs/ecosystem/stric.md +37 -0
package/docs/guides/binary/arraybuffer-to-array.md +27 -0
package/docs/guides/binary/arraybuffer-to-blob.md +24 -0
package/docs/guides/binary/arraybuffer-to-buffer.md +25 -0
package/docs/guides/binary/arraybuffer-to-string.md +15 -0
package/docs/guides/binary/arraybuffer-to-typedarray.md +39 -0
package/docs/guides/binary/blob-to-arraybuffer.md +14 -0
package/docs/guides/binary/blob-to-dataview.md +14 -0
package/docs/guides/binary/blob-to-stream.md +14 -0
package/docs/guides/binary/blob-to-string.md +15 -0
package/docs/guides/binary/blob-to-typedarray.md +14 -0
package/docs/guides/binary/buffer-to-arraybuffer.md +14 -0
package/docs/guides/binary/buffer-to-blob.md +14 -0
package/docs/guides/binary/buffer-to-readablestream.md +41 -0
package/docs/guides/binary/buffer-to-string.md +25 -0
package/docs/guides/binary/buffer-to-typedarray.md +14 -0
package/docs/guides/binary/dataview-to-string.md +15 -0
package/docs/guides/binary/typedarray-to-arraybuffer.md +25 -0
package/docs/guides/binary/typedarray-to-blob.md +16 -0
package/docs/guides/binary/typedarray-to-buffer.md +14 -0
package/docs/guides/binary/typedarray-to-dataview.md +14 -0
package/docs/guides/binary/typedarray-to-readablestream.md +41 -0
package/docs/guides/binary/typedarray-to-string.md +16 -0
package/docs/guides/ecosystem/astro.md +72 -0
package/docs/guides/ecosystem/discordjs.md +77 -0
package/docs/guides/ecosystem/docker.md +140 -0
package/docs/guides/ecosystem/drizzle.md +185 -0
package/docs/guides/ecosystem/edgedb.md +228 -0
package/docs/guides/ecosystem/elysia.md +31 -0
package/docs/guides/ecosystem/express.md +40 -0
package/docs/guides/ecosystem/hono.md +39 -0
package/docs/guides/ecosystem/mongoose.md +87 -0
package/docs/guides/ecosystem/neon-drizzle.md +220 -0
package/docs/guides/ecosystem/neon-serverless-postgres.md +55 -0
package/docs/guides/ecosystem/nextjs.md +38 -0
package/docs/guides/ecosystem/nuxt.md +56 -0
package/docs/guides/ecosystem/pm2.md +57 -0
package/docs/guides/ecosystem/prisma.md +140 -0
package/docs/guides/ecosystem/qwik.md +107 -0
package/docs/guides/ecosystem/react.md +49 -0
package/docs/guides/ecosystem/remix.md +78 -0
package/docs/guides/ecosystem/render.md +79 -0
package/docs/guides/ecosystem/sentry.md +52 -0
package/docs/guides/ecosystem/solidstart.md +58 -0
package/docs/guides/ecosystem/ssr-react.md +51 -0
package/docs/guides/ecosystem/stric.md +55 -0
package/docs/guides/ecosystem/sveltekit.md +125 -0
package/docs/guides/ecosystem/systemd.md +113 -0
package/docs/guides/ecosystem/vite.md +70 -0
package/docs/guides/http/cluster.md +66 -0
package/docs/guides/http/fetch-unix.md +33 -0
package/docs/guides/http/fetch.md +24 -0
package/docs/guides/http/file-uploads.md +94 -0
package/docs/guides/http/hot.md +22 -0
package/docs/guides/http/proxy.md +24 -0
package/docs/guides/http/server.md +46 -0
package/docs/guides/http/simple.md +18 -0
package/docs/guides/http/stream-file.md +48 -0
package/docs/guides/http/stream-iterator.md +47 -0
package/docs/guides/http/stream-node-streams-in-bun.md +20 -0
package/docs/guides/http/tls.md +30 -0
package/docs/guides/install/add-dev.md +26 -0
package/docs/guides/install/add-git.md +36 -0
package/docs/guides/install/add-optional.md +25 -0
package/docs/guides/install/add-peer.md +17 -0
package/docs/guides/install/add-tarball.md +33 -0
package/docs/guides/install/add.md +42 -0
package/docs/guides/install/azure-artifacts.md +73 -0
package/docs/guides/install/cicd.md +41 -0
package/docs/guides/install/custom-registry.md +30 -0
package/docs/guides/install/from-npm-install-to-bun-install.md +214 -0
package/docs/guides/install/git-diff-bun-lockfile.md +38 -0
package/docs/guides/install/jfrog-artifactory.md +28 -0
package/docs/guides/install/npm-alias.md +23 -0
package/docs/guides/install/registry-scope.md +36 -0
package/docs/guides/install/trusted.md +48 -0
package/docs/guides/install/workspaces.md +70 -0
package/docs/guides/install/yarnlock.md +42 -0
package/docs/guides/process/argv.md +57 -0
package/docs/guides/process/ctrl-c.md +16 -0
package/docs/guides/process/ipc.md +66 -0
package/docs/guides/process/nanoseconds.md +13 -0
package/docs/guides/process/os-signals.md +39 -0
package/docs/guides/process/spawn-stderr.md +31 -0
package/docs/guides/process/spawn-stdout.md +26 -0
package/docs/guides/process/spawn.md +41 -0
package/docs/guides/process/stdin.md +54 -0
package/docs/guides/read-file/arraybuffer.md +28 -0
package/docs/guides/read-file/buffer.md +19 -0
package/docs/guides/read-file/exists.md +16 -0
package/docs/guides/read-file/json.md +17 -0
package/docs/guides/read-file/mime.md +20 -0
package/docs/guides/read-file/stream.md +26 -0
package/docs/guides/read-file/string.md +22 -0
package/docs/guides/read-file/uint8array.md +21 -0
package/docs/guides/read-file/watch.md +68 -0
package/docs/guides/runtime/cicd.md +43 -0
package/docs/guides/runtime/define-constant.md +145 -0
package/docs/guides/runtime/import-html.md +15 -0
package/docs/guides/runtime/import-json.md +44 -0
package/docs/guides/runtime/import-toml.md +30 -0
package/docs/guides/runtime/read-env.md +32 -0
package/docs/guides/runtime/set-env.md +37 -0
package/docs/guides/runtime/shell.md +40 -0
package/docs/guides/runtime/timezone.md +35 -0
package/docs/guides/runtime/tsconfig-paths.md +29 -0
package/docs/guides/runtime/typescript.md +47 -0
package/docs/guides/runtime/vscode-debugger.md +47 -0
package/docs/guides/runtime/web-debugger.md +82 -0
package/docs/guides/streams/node-readable-to-arraybuffer.md +11 -0
package/docs/guides/streams/node-readable-to-blob.md +11 -0
package/docs/guides/streams/node-readable-to-json.md +12 -0
package/docs/guides/streams/node-readable-to-string.md +12 -0
package/docs/guides/streams/node-readable-to-uint8array.md +11 -0
package/docs/guides/streams/to-array.md +14 -0
package/docs/guides/streams/to-arraybuffer.md +14 -0
package/docs/guides/streams/to-blob.md +14 -0
package/docs/guides/streams/to-buffer.md +15 -0
package/docs/guides/streams/to-json.md +14 -0
package/docs/guides/streams/to-string.md +14 -0
package/docs/guides/streams/to-typedarray.md +22 -0
package/docs/guides/test/bail.md +22 -0
package/docs/guides/test/coverage-threshold.md +60 -0
package/docs/guides/test/coverage.md +44 -0
package/docs/guides/test/happy-dom.md +68 -0
package/docs/guides/test/migrate-from-jest.md +110 -0
package/docs/guides/test/mock-clock.md +48 -0
package/docs/guides/test/mock-functions.md +68 -0
package/docs/guides/test/rerun-each.md +14 -0
package/docs/guides/test/run-tests.md +111 -0
package/docs/guides/test/skip-tests.md +39 -0
package/docs/guides/test/snapshot.md +99 -0
package/docs/guides/test/spy-on.md +46 -0
package/docs/guides/test/testing-library.md +87 -0
package/docs/guides/test/timeout.md +15 -0
package/docs/guides/test/todo-tests.md +67 -0
package/docs/guides/test/update-snapshots.md +50 -0
package/docs/guides/test/watch-mode.md +19 -0
package/docs/guides/util/base64.md +15 -0
package/docs/guides/util/deep-equals.md +39 -0
package/docs/guides/util/deflate.md +18 -0
package/docs/guides/util/detect-bun.md +23 -0
package/docs/guides/util/entrypoint.md +17 -0
package/docs/guides/util/escape-html.md +22 -0
package/docs/guides/util/file-url-to-path.md +14 -0
package/docs/guides/util/gzip.md +18 -0
package/docs/guides/util/hash-a-password.md +54 -0
package/docs/guides/util/import-meta-dir.md +13 -0
package/docs/guides/util/import-meta-file.md +13 -0
package/docs/guides/util/import-meta-path.md +13 -0
package/docs/guides/util/main.md +32 -0
package/docs/guides/util/path-to-file-url.md +14 -0
package/docs/guides/util/sleep.md +22 -0
package/docs/guides/util/version.md +21 -0
package/docs/guides/util/which-path-to-executable-bin.md +15 -0
package/docs/guides/websocket/compression.md +31 -0
package/docs/guides/websocket/context.md +72 -0
package/docs/guides/websocket/pubsub.md +38 -0
package/docs/guides/websocket/simple.md +33 -0
package/docs/guides/write-file/append.md +52 -0
package/docs/guides/write-file/basic.md +44 -0
package/docs/guides/write-file/blob.md +28 -0
package/docs/guides/write-file/cat.md +17 -0
package/docs/guides/write-file/file-cp.md +16 -0
package/docs/guides/write-file/filesink.md +52 -0
package/docs/guides/write-file/response.md +17 -0
package/docs/guides/write-file/stdout.md +21 -0
package/docs/guides/write-file/stream.md +17 -0
package/docs/guides/write-file/unlink.md +23 -0
package/docs/index.md +77 -0
package/docs/install/cache.md +57 -0
package/docs/install/index.md +202 -0
package/docs/install/lifecycle.md +46 -0
package/docs/install/lockfile.md +90 -0
package/docs/install/npmrc.md +75 -0
package/docs/install/overrides.md +73 -0
package/docs/install/patch.md +57 -0
package/docs/install/registries.md +30 -0
package/docs/install/workspaces.md +70 -0
package/docs/installation.md +289 -0
package/docs/project/benchmarking.md +203 -0
package/docs/project/building-windows.md +162 -0
package/docs/project/internals/build-process-for-ci.md +75 -0
package/docs/project/roadmap.md +87 -0
package/docs/quickstart.md +144 -0
package/docs/runtime/autoimport.md +94 -0
package/docs/runtime/bun-apis.md +129 -0
package/docs/runtime/bunfig.md +532 -0
package/docs/runtime/debugger.md +325 -0
package/docs/runtime/env.md +214 -0
package/docs/runtime/hot.md +139 -0
package/docs/runtime/index.md +309 -0
package/docs/runtime/jsx.md +326 -0
package/docs/runtime/loaders.md +127 -0
package/docs/runtime/modules.md +298 -0
package/docs/runtime/nodejs-apis.md +456 -0
package/docs/runtime/plugins.md +605 -0
package/docs/runtime/shell.md +537 -0
package/docs/runtime/typescript.md +60 -0
package/docs/runtime/web-apis.md +128 -0
package/docs/test/coverage.md +91 -0
package/docs/test/dom.md +75 -0
package/docs/test/hot.md +15 -0
package/docs/test/lifecycle.md +81 -0
package/docs/test/mocks.md +236 -0
package/docs/test/snapshots.md +15 -0
package/docs/test/time.md +106 -0
package/docs/test/writing.md +547 -0
package/docs/typescript.md +51 -0
package/package.json +5 -4

package/docs/bundler/intro.md ADDED Viewed

@@ -0,0 +1,75 @@
+<!-- This document is a work in progress. It's not currently included in the actual docs. -->
+The goal of this document is to break down why bundling is necessary, how it works, and how the bundler became such a key part of modern JavaScript development. The content is not specific to Bun's bundler, but is rather aimed at anyone looking for a greater understanding of how bundlers work and, by extension, how most modern frameworks are implemented.
+## What is bundling
+With the adoption of ECMAScript modules (ESM), browsers can now resolve `import`/`export` statements in JavaScript files loaded via `<script>` tags.
+{% codetabs %}
+```html#index.html
+<html>
+  <head>
+    <script type="module" src="/index.js" ></script>
+  </head>
+</html>
+```
+```js#index.js
+import {sayHello} from "./hello.js";
+sayHello();
+```
+```js#hello.js
+export function sayHello() {
+  console.log("Hello, world!");
+}
+```
+{% /codetabs %}
+When a user visits this website, the files are loaded in the following order:
+{% image src="/images/module_loading_unbundled.png" /%}
+{% callout %}
+**Relative imports** — Relative imports are resolved relative to the URL of the importing file. Because we're importing `./hello.js` from `/index.js`, the browser resolves it to `/hello.js`. If instead we'd imported `./hello.js` from `/src/index.js`, the browser would have resolved it to `/src/hello.js`.
+{% /callout %}
+This approach works, it requires three round-trip HTTP requests before the browser is ready to render the page. On slow internet connections, this may add up to a non-trivial delay.
+This example is extremely simplistic. A modern app may be loading dozens of modules from `node_modules`, each consisting of hundred of files. Loading each of these files with a separate HTTP request becomes untenable very quickly. While most of these requests will be running in parallel, the number of round-trip requests can still be very high; plus, there are limits on how many simultaneous requests a browser can make.
+{% callout %}
+Some recent advances like modulepreload and HTTP/3 are intended to solve some of these problems, but at the moment bundling is still the most performant approach.
+{% /callout %}
+The answer: bundling.
+## Entrypoints
+A bundler accepts an "entrypoint" to your source code (in this case, `/index.js`) and outputs a single file containing all of the code needed to run your app. If does so by parsing your source code, reading the `import`/`export` statements, and building a "module graph" of your app's dependencies.
+{% image src="/images/bundling.png" /%}
+We can now load `/bundle.js` from our `index.html` file and eliminate a round trip request, decreasing load times for our app.
+{% image src="/images/module_loading_bundled.png" /%}
+## Loaders
+Bundlers typically have some set of built-in "loaders".
+## Transpilation
+The JavaScript files above are just that: plain JavaScript. They can be directly executed by any modern browser.
+But modern tooling goes far beyond HTML, JavaScript, and CSS. JSX, TypeScript, and PostCSS/CSS-in-JS are all popular technologies that involve non-standard syntax that must be converted into vanilla JavaScript and CSS before if can be consumed by a browser.
+## Chunking
+## Module resolution
+## Plugins

package/docs/bundler/loaders.md ADDED Viewed

@@ -0,0 +1,288 @@
+The Bun bundler implements a set of default loaders out of the box. As a rule of thumb, the bundler and the runtime both support the same set of file types out of the box.
+`.js` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` `.jsx` `.toml` `.json` `.txt` `.wasm` `.node`
+Bun uses the file extension to determine which built-in _loader_ should be used to parse the file. Every loader has a name, such as `js`, `tsx`, or `json`. These names are used when building [plugins](https://bun.sh/docs/bundler/plugins) that extend Bun with custom loaders.
+## Built-in loaders
+### `js`
+**JavaScript**. Default for `.cjs` and `.mjs`.
+Parses the code and applies a set of default transforms like dead-code elimination and tree shaking. Note that Bun does not attempt to down-convert syntax at the moment.
+### `jsx`
+**JavaScript + JSX.**. Default for `.js` and `.jsx`.
+Same as the `js` loader, but JSX syntax is supported. By default, JSX is down-converted to plain JavaScript; the details of how this is done depends on the `jsx*` compiler options in your `tsconfig.json`. Refer to the TypeScript documentation [on JSX](https://www.typescriptlang.org/docs/handbook/jsx.html) for more information.
+### `ts`
+**TypeScript loader**. Default for `.ts`, `.mts`, and `.cts`.
+Strips out all TypeScript syntax, then behaves identically to the `js` loader. Bun does not perform typechecking.
+### `tsx`
+**TypeScript + JSX loader**. Default for `.tsx`. Transpiles both TypeScript and JSX to vanilla JavaScript.
+### `json`
+**JSON loader**. Default for `.json`.
+JSON files can be directly imported.
+```ts
+import pkg from "./package.json";
+pkg.name; // => "my-package"
+```
+During bundling, the parsed JSON is inlined into the bundle as a JavaScript object.
+```ts
+var pkg = {
+  name: "my-package",
+  // ... other fields
+};
+pkg.name;
+```
+If a `.json` file is passed as an entrypoint to the bundler, it will be converted to a `.js` module that `export default`s the parsed object.
+{% codetabs %}
+```json#Input
+{
+  "name": "John Doe",
+  "age": 35,
+  "email": "johndoe@example.com"
+}
+```
+```js#Output
+export default {
+  name: "John Doe",
+  age: 35,
+  email: "johndoe@example.com"
+}
+```
+{% /codetabs %}
+### `toml`
+**TOML loader**. Default for `.toml`.
+TOML files can be directly imported. Bun will parse them with its fast native TOML parser.
+```ts
+import config from "./bunfig.toml";
+config.logLevel; // => "debug"
+// via import attribute:
+// import myCustomTOML from './my.config' with {type: "toml"};
+```
+During bundling, the parsed TOML is inlined into the bundle as a JavaScript object.
+```ts
+var config = {
+  logLevel: "debug",
+  // ...other fields
+};
+config.logLevel;
+```
+If a `.toml` file is passed as an entrypoint, it will be converted to a `.js` module that `export default`s the parsed object.
+{% codetabs %}
+```toml#Input
+name = "John Doe"
+age = 35
+email = "johndoe@example.com"
+```
+```js#Output
+export default {
+  name: "John Doe",
+  age: 35,
+  email: "johndoe@example.com"
+}
+```
+{% /codetabs %}
+### `text`
+**Text loader**. Default for `.txt`.
+The contents of the text file are read and inlined into the bundle as a string.
+Text files can be directly imported. The file is read and returned as a string.
+```ts
+import contents from "./file.txt";
+console.log(contents); // => "Hello, world!"
+// To import an html file as text
+// The "type' attribute can be used to override the default loader.
+import html from "./index.html" with { type: "text" };
+```
+When referenced during a build, the contents are into the bundle as a string.
+```ts
+var contents = `Hello, world!`;
+console.log(contents);
+```
+If a `.txt` file is passed as an entrypoint, it will be converted to a `.js` module that `export default`s the file contents.
+{% codetabs %}
+```txt#Input
+Hello, world!
+```
+```js#Output
+export default "Hello, world!";
+```
+{% /codetabs %}
+### `wasm`
+**WebAssembly loader**. Default for `.wasm`.
+In the runtime, WebAssembly files can be directly imported. The file is read and returned as a `WebAssembly.Module`.
+```ts
+import wasm from "./module.wasm";
+console.log(wasm); // => WebAssembly.Module
+```
+In the bundler, `.wasm` files are handled using the [`file`](#file) loader.
+### `napi`
+**Native addon loader**. Default for `.node`.
+In the runtime, native addons can be directly imported.
+```ts
+import addon from "./addon.node";
+console.log(addon);
+```
+In the bundler, `.node` files are handled using the [`file`](#file) loader.
+### `sqlite`
+**SQLite loader**. `with { "type": "sqlite" }` import attribute
+In the runtime and bundler, SQLite databases can be directly imported. This will load the database using [`bun:sqlite`](https://bun.sh/docs/api/sqlite).
+```ts
+import db from "./my.db" with { type: "sqlite" };
+```
+This is only supported when the `target` is `bun`.
+By default, the database is external to the bundle (so that you can potentially use a database loaded elsewhere), so the database file on-disk won't be bundled into the final output.
+You can change this behavior with the `"embed"` attribute:
+```ts
+// embed the database into the bundle
+import db from "./my.db" with { type: "sqlite", embed: "true" };
+```
+When using a [standalone executable](https://bun.sh/docs/bundler/executables), the database is embedded into the single-file executable.
+Otherwise, the database to embed is copied into the `outdir` with a hashed filename.
+### `sh` loader
+**Bun Shell loader**. Default for `.sh` files
+This loader is used to parse [Bun Shell](https://bun.sh/docs/runtime/shell) scripts. It's only supported when starting Bun itself, so it's not available in the bundler or in the runtime.
+```sh
+$ bun run ./script.sh
+```
+### `file`
+**File loader**. Default for all unrecognized file types.
+The file loader resolves the import as a _path/URL_ to the imported file. It's commonly used for referencing media or font assets.
+```ts#logo.ts
+import logo from "./logo.svg";
+console.log(logo);
+```
+_In the runtime_, Bun checks that the `logo.svg` file exists and converts it to an absolute path to the location of `logo.svg` on disk.
+```bash
+$ bun run logo.ts
+/path/to/project/logo.svg
+```
+_In the bundler_, things are slightly different. The file is copied into `outdir` as-is, and the import is resolved as a relative path pointing to the copied file.
+```ts#Output
+var logo = "./logo.svg";
+console.log(logo);
+```
+If a value is specified for `publicPath`, the import will use value as a prefix to construct an absolute path/URL.
+{% table %}
+- Public path
+- Resolved import
+---
+- `""` (default)
+- `/logo.svg`
+---
+- `"/assets"`
+- `/assets/logo.svg`
+---
+- `"https://cdn.example.com/"`
+- `https://cdn.example.com/logo.svg`
+{% /table %}
+{% callout %}
+The location and file name of the copied file is determined by the value of [`naming.asset`](https://bun.sh/docs/bundler#naming).
+{% /callout %}
+This loader is copied into the `outdir` as-is. The name of the copied file is determined using the value of `naming.asset`.
+{% details summary="Fixing TypeScript import errors" %}
+If you're using TypeScript, you may get an error like this:
+```ts
+// TypeScript error
+// Cannot find module './logo.svg' or its corresponding type declarations.
+```
+This can be fixed by creating `*.d.ts` file anywhere in your project (any name will work) with the following contents:
+```ts
+declare module "*.svg" {
+  const content: string;
+  export default content;
+}
+```
+This tells TypeScript that any default imports from `.svg` should be treated as a string.
+{% /details %}

package/docs/bundler/macros.md ADDED Viewed

@@ -0,0 +1,327 @@
+Macros are a mechanism for running JavaScript functions _at bundle-time_. The value returned from these functions are directly inlined into your bundle.
+<!-- embed the result in your (browser) bundle. This is useful for things like embedding the current Git commit hash in your code, making fetch requests to your API at build-time, dead code elimination, and more. -->
+As a toy example, consider this simple function that returns a random number.
+```ts
+export function random() {
+  return Math.random();
+}
+```
+This is just a regular function in a regular file, but we can use it as a macro like so:
+```ts#cli.tsx
+import { random } from './random.ts' with { type: 'macro' };
+console.log(`Your random number is ${random()}`);
+```
+{% callout %}
+**Note** — Macros are indicated using [_import attribute_](https://github.com/tc39/proposal-import-attributes) syntax. If you haven't seen this syntax before, it's a Stage 3 TC39 proposal that lets you attach additional metadata to `import` statements.
+{% /callout %}
+Now we'll bundle this file with `bun build`. The bundled file will be printed to stdout.
+```bash
+$ bun build ./cli.tsx
+console.log(`Your random number is ${0.6805550949689833}`);
+```
+As you can see, the source code of the `random` function occurs nowhere in the bundle. Instead, it is executed _during bundling_ and function call (`random()`) is replaced with the result of the function. Since the source code will never be included in the bundle, macros can safely perform privileged operations like reading from a database.
+## When to use macros
+If you have several build scripts for small things where you would otherwise have a one-off build script, bundle-time code execution can be easier to maintain. It lives with the rest of your code, it runs with the rest of the build, it is automatically parallelized, and if it fails, the build fails too.
+If you find yourself running a lot of code at bundle-time though, consider running a server instead.
+## Import attributes
+Bun Macros are import statements annotated using either:
+- `with { type: 'macro' }` — an [import attribute](https://github.com/tc39/proposal-import-attributes), a Stage 3 ECMA Scrd
+- `assert { type: 'macro' }` — an import assertion, an earlier incarnation of import attributes that has now been abandoned (but is [already supported](https://caniuse.com/mdn-javascript_statements_import_import_assertions) by a number of browsers and runtimes)
+## Security considerations
+Macros must explicitly be imported with `{ type: "macro" }` in order to be executed at bundle-time. These imports have no effect if they are not called, unlike regular JavaScript imports which may have side effects.
+You can disable macros entirely by passing the `--no-macros` flag to Bun. It produces a build error like this:
+```js
+error: Macros are disabled
+foo();
+^
+./hello.js:3:1 53
+```
+To reduce the potential attack surface for malicious packages, macros cannot be _invoked_ from inside `node_modules/**/*`. If a package attempts to invoke a macro, you'll see an error like this:
+```js
+error: For security reasons, macros cannot be run from node_modules.
+beEvil();
+^
+node_modules/evil/index.js:3:1 50
+```
+Your application code can still import macros from `node_modules` and invoke them.
+```ts
+import {macro} from "some-package" with { type: "macro" };
+macro();
+```
+## Export condition `"macro"`
+When shipping a library containing a macro to `npm` or another package registry, use the `"macro"` [export condition](https://nodejs.org/api/packages.html#conditional-exports) to provide a special version of your package exclusively for the macro environment.
+```jsonc#package.json
+{
+  "name": "my-package",
+  "exports": {
+    "import": "./index.js",
+    "require": "./index.js",
+    "default": "./index.js",
+    "macro": "./index.macro.js"
+  }
+}
+```
+With this configuration, users can consume your package at runtime or at bundle-time using the same import specifier:
+```ts
+import pkg from "my-package";                            // runtime import
+import {macro} from "my-package" with { type: "macro" }; // macro import
+```
+The first import will resolve to `./node_modules/my-package/index.js`, while the second will be resolved by Bun's bundler to `./node_modules/my-package/index.macro.js`.
+## Execution
+When Bun's transpiler sees a macro import, it calls the function inside the transpiler using Bun's JavaScript runtime and converts the return value from JavaScript into an AST node. These JavaScript functions are called at bundle-time, not runtime.
+Macros are executed synchronously in the transpiler during the visiting phase—before plugins and before the transpiler generates the AST. They are executed in the order they are imported. The transpiler will wait for the macro to finish executing before continuing. The transpiler will also `await` any `Promise` returned by a macro.
+Bun's bundler is multi-threaded. As such, macros execute in parallel inside of multiple spawned JavaScript "workers".
+## Dead code elimination
+The bundler performs dead code elimination _after_ running and inlining macros. So given the following macro:
+```ts#returnFalse.ts
+export function returnFalse() {
+  return false;
+}
+```
+...then bundling the following file will produce an empty bundle, provided that the minify syntax option is enabled.
+```ts
+import {returnFalse} from './returnFalse.ts' with { type: 'macro' };
+if (returnFalse()) {
+  console.log("This code is eliminated");
+}
+```
+## Serializability
+Bun's transpiler needs to be able to serialize the result of the macro so it can be inlined into the AST. All JSON-compatible data structures are supported:
+```ts#macro.ts
+export function getObject() {
+  return {
+    foo: "bar",
+    baz: 123,
+    array: [ 1, 2, { nested: "value" }],
+  };
+}
+```
+Macros can be async, or return `Promise` instances. Bun's transpiler will automatically `await` the `Promise` and inline the result.
+```ts#macro.ts
+export async function getText() {
+  return "async value";
+}
+```
+The transpiler implements special logic for serializing common data formats like `Response`, `Blob`, `TypedArray`.
+- `TypedArray`: Resolves to a base64-encoded string.
+- `Response`: Bun will read the `Content-Type` and serialize accordingly; for instance, a `Response` with type `application/json` will be automatically parsed into an object and `text/plain` will be inlined as a string. Responses with an unrecognized or `undefined` `type` will be base-64 encoded.
+- `Blob`: As with `Response`, the serialization depends on the `type` property.
+The result of `fetch` is `Promise<Response>`, so it can be directly returned.
+```ts#macro.ts
+export function getObject() {
+  return fetch("https://bun.sh")
+}
+```
+Functions and instances of most classes (except those mentioned above) are not serializable.
+```ts
+export function getText(url: string) {
+  // this doesn't work!
+  return () => {};
+}
+```
+## Arguments
+Macros can accept inputs, but only in limited cases. The value must be statically known. For example, the following is not allowed:
+```ts
+import {getText} from './getText.ts' with { type: 'macro' };
+export function howLong() {
+  // the value of `foo` cannot be statically known
+  const foo = Math.random() ? "foo" : "bar";
+  const text = getText(`https://example.com/${foo}`);
+  console.log("The page is ", text.length, " characters long");
+}
+```
+However, if the value of `foo` is known at bundle-time (say, if it's a constant or the result of another macro) then it's allowed:
+```ts
+import {getText} from './getText.ts' with { type: 'macro' };
+import {getFoo} from './getFoo.ts' with { type: 'macro' };
+export function howLong() {
+  // this works because getFoo() is statically known
+  const foo = getFoo();
+  const text = getText(`https://example.com/${foo}`);
+  console.log("The page is", text.length, "characters long");
+}
+```
+This outputs:
+```ts
+function howLong() {
+  console.log("The page is", 1322, "characters long");
+}
+export { howLong };
+```
+## Examples
+### Embed latest git commit hash
+{% codetabs %}
+```ts#getGitCommitHash.ts
+export function getGitCommitHash() {
+  const {stdout} = Bun.spawnSync({
+    cmd: ["git", "rev-parse", "HEAD"],
+    stdout: "pipe",
+  });
+  return stdout.toString();
+}
+```
+{% /codetabs %}
+<!-- --target=browser so they can clearly see it's for browsers -->
+When we build it, the `getGitCommitHash` is replaced with the result of calling the function:
+{% codetabs %}
+```ts#input
+import { getGitCommitHash } from './getGitCommitHash.ts' with { type: 'macro' };
+console.log(`The current Git commit hash is ${getGitCommitHash()}`);
+```
+```bash#output
+console.log(`The current Git commit hash is 3ee3259104f`);
+```
+{% /codetabs %}
+You're probably thinking "Why not just use `process.env.GIT_COMMIT_HASH`?" Well, you can do that too. But can you do this with an environment variable?
+### Make `fetch()` requests at bundle-time
+In this example, we make an outgoing HTTP request using `fetch()`, parse the HTML response using `HTMLRewriter`, and return an object containing the title and meta tags–all at bundle-time.
+```ts
+export async function extractMetaTags(url: string) {
+  const response = await fetch(url);
+  const meta = {
+    title: "",
+  };
+  new HTMLRewriter()
+    .on("title", {
+      text(element) {
+        meta.title += element.text;
+      },
+    })
+    .on("meta", {
+      element(element) {
+        const name =
+          element.getAttribute("name") || element.getAttribute("property") || element.getAttribute("itemprop");
+        if (name) meta[name] = element.getAttribute("content");
+      },
+    })
+    .transform(response);
+  return meta;
+}
+```
+<!-- --target=browser so they can clearly see it's for browsers -->
+The `extractMetaTags` function is erased at bundle-time and replaced with the result of the function call. This means that the `fetch` request happens at bundle-time, and the result is embedded in the bundle. Also, the branch throwing the error is eliminated since it's unreachable.
+{% codetabs %}
+```ts#input
+import { extractMetaTags } from './meta.ts' with { type: 'macro' };
+export const Head = () => {
+  const headTags = extractMetaTags("https://example.com");
+  if (headTags.title !== "Example Domain") {
+    throw new Error("Expected title to be 'Example Domain'");
+  }
+  return <head>
+    <title>{headTags.title}</title>
+    <meta name="viewport" content={headTags.viewport} />
+  </head>;
+};
+```
+```ts#output
+import { jsx, jsxs } from "react/jsx-runtime";
+export const Head = () => {
+  jsxs("head", {
+    children: [
+      jsx("title", {
+        children: "Example Domain",
+      }),
+      jsx("meta", {
+        name: "viewport",
+        content: "width=device-width, initial-scale=1",
+      }),
+    ],
+  });
+};
+export { Head };
+```
+{% /codetabs %}