bun-types 1.2.5-canary.20250306T140602 → 1.2.5-canary.20250308T140614

package/docs/bundler/css_modules.md

@@ -0,0 +1,145 @@
+# CSS Modules
+
+Bun's bundler also supports bundling [CSS modules](https://css-tricks.com/css-modules-part-1-need/) in addition to [regular CSS](/docs/bundler/css) with support for the following features:
+
+- Automatically detecting CSS module files (`.module.css`) with zero configuration
+- Composition (`composes` property)
+- Importing CSS modules into JSX/TSX
+- Warnings/errors for invalid usages of CSS modules
+
+A CSS module is a CSS file (with the `.module.css` extension) where are all class names and animations are scoped to the file. This helps you avoid class name collisions as CSS declarations are globally scoped by default.
+
+Under the hood, Bun's bundler transforms locally scoped class names into unique identifiers.
+
+## Getting started
+
+Create a CSS file with the `.module.css` extension:
+
+```css
+/* styles.module.css */
+.button {
+  color: red;
+}
+
+/* other-styles.module.css */
+.button {
+  color: blue;
+}
+```
+
+You can then import this file, for example into a TSX file:
+
+```tsx
+import styles from "./styles.module.css";
+import otherStyles from "./other-styles.module.css";
+
+export default function App() {
+  return (
+    <>
+      <button className={styles.button}>Red button!</button>
+      <button className={otherStyles.button}>Blue button!</button>
+    </>
+  );
+}
+```
+
+The `styles` object from importing the CSS module file will be an object with all class names as keys and
+their unique identifiers as values:
+
+```tsx
+import styles from "./styles.module.css";
+import otherStyles from "./other-styles.module.css";
+
+console.log(styles);
+console.log(otherStyles);
+```
+
+This will output:
+
+```ts
+{
+  button: "button_123";
+}
+
+{
+  button: "button_456";
+}
+```
+
+As you can see, the class names are unique to each file, avoiding any collisions!
+
+### Composition
+
+CSS modules allow you to _compose_ class selectors together. This lets you reuse style rules across multiple classes.
+
+For example:
+
+```css
+/* styles.module.css */
+.button {
+  composes: background;
+  color: red;
+}
+
+.background {
+  background-color: blue;
+}
+```
+
+Would be the same as writing:
+
+```css
+.button {
+  background-color: blue;
+  color: red;
+}
+
+.background {
+  background-color: blue;
+}
+```
+
+{% callout %}
+There are a couple rules to keep in mind when using `composes`:
+
+- A `composes` property must come before any regular CSS properties or declarations
+- You can only use `composes` on a **simple selector with a single class name**:
+
+```css
+#button {
+  /* Invalid! `#button` is not a class selector */
+  composes: background;
+}
+
+.button,
+.button-secondary {
+  /* Invalid! `.button, .button-secondary` is not a simple selector */
+  composes: background;
+}
+```
+
+{% /callout %}
+
+### Composing from a separate CSS module file
+
+You can also compose from a separate CSS module file:
+
+```css
+/* background.module.css */
+.background {
+  background-color: blue;
+}
+
+/* styles.module.css */
+.button {
+  composes: background from "./background.module.css";
+  color: red;
+}
+```
+
+{% callout %}
+When composing classes from separate files, be sure that they do not contain the same properties.
+
+The CSS module spec says that composing classes from separate files with conflicting properties is
+undefined behavior, meaning that the output may differ and be unreliable.
+{% /callout %}

package/docs/bundler/fullstack.md

@@ -309,5 +309,4 @@ This works similarly to how [`Bun.build` processes HTML files](/docs/bundler/htm
 
 ## This is a work in progress
 
-- ~Client-side hot reloading isn't wired up yet. It will be in the future.~ New in Bun v1.2.3
 - This doesn't support `bun build` yet. It also will in the future.

package/docs/bundler/hmr.md

@@ -0,0 +1,234 @@
+Hot Module Replacement (HMR) allows you to update modules in a running
+application without needing a full page reload. This preserves the application
+state and improves the development experience.
+
+HMR is enabled by default when using Bun's full-stack development server.
+
+## `import.meta.hot` API Reference
+
+Bun implements a client-side HMR API modeled after [Vite's `import.meta.hot` API](https://vitejs.dev/guide/api-hmr.html). It can be checked for with `if (import.meta.hot)`, tree-shaking it in production
+
+```ts
+if (import.meta.hot) {
+  // HMR APIs are available.
+}
+```
+
+However, **this check is often not needed** as Bun will dead-code-eliminate
+calls to all of the HMR APIs in production builds.
+
+```ts
+// This entire function call will be removed in production!
+import.meta.hot.dispose(() => {
+  console.log("dispose");
+});
+```
+
+For this to work, Bun forces these APIs to be called without indirection. That means the following do not work:
+
+```ts#invalid-hmr-usage.ts
+// INVALID: Assigning `hot` to a variable
+const hot = import.meta.hot;
+hot.accept();
+
+// INVALID: Assigning `import.meta` to a variable
+const meta = import.meta;
+meta.hot.accept();
+console.log(meta.hot.data);
+
+// INVALID: Passing to a function
+doSomething(import.meta.hot.dispose);
+
+// OK: The full phrase "import.meta.hot.<API>" must be called directly:
+import.meta.hot.accept();
+
+// OK: `data` can be passed to functions:
+doSomething(import.meta.hot.data);
+```
+
+{% callout %}
+
+**Note** — The HMR API is still a work in progress. Some features are missing. HMR can be disabled in `Bun.serve` by setting the `development` option to `{ hmr: false }`.
+
+{% endcallout %}
+
+|     | Method             | Notes                                                                 |
+| --- | ------------------ | --------------------------------------------------------------------- |
+| ✅  | `hot.accept()`     | Indicate that a hot update can be replaced gracefully.                |
+| ✅  | `hot.data`         | Persist data between module evaluations.                              |
+| ✅  | `hot.dispose()`    | Add a callback function to run when a module is about to be replaced. |
+| ❌  | `hot.invalidate()` |                                                                       |
+| ✅  | `hot.on()`         | Attach an event listener                                              |
+| ✅  | `hot.off()`        | Remove an event listener from `on`.                                   |
+| ❌  | `hot.send()`       |                                                                       |
+| 🚧  | `hot.prune()`      | **NOTE**: Callback is currently never called.                         |
+| ✅  | `hot.decline()`    | No-op to match Vite's `import.meta.hot`                               |
+
+### `import.meta.hot.accept()`
+
+The `accept()` method indicates that a module can be hot-replaced. When called
+without arguments, it indicates that this module can be replaced simply by
+re-evaluating the file. After a hot update, importers of this module will be
+automatically patched.
+
+```ts#index.ts
+import { getCount } from "./foo.ts";
+
+console.log("count is ", getCount());
+
+import.meta.hot.accept();
+
+export function getNegativeCount() {
+  return -getCount();
+}
+```
+
+This creates a hot-reloading boundary for all of the files that `index.ts`
+imports. That means whenever `foo.ts` or any of its dependencies are saved, the
+update will bubble up to `index.ts` will re-evaluate. Files that import
+`index.ts` will then be patched to import the new version of
+`getNegativeCount()`. If only `index.ts` is updated, only the one file will be
+re-evaluated, and the counter in `foo.ts` is reused.
+
+This may be used in combination with `import.meta.hot.data` to transfer state
+from the previous module to the new one.
+
+When no modules call `import.meta.hot.accept()` (and there isn't React Fast
+Refresh or a plugin calling it for you), the page will reload when the file
+updates, and a console warning shows which files were invalidated. This warning
+is safe to ignore if it makes more sense to rely on full page reloads.
+
+#### With callback
+
+When provided one callback, `import.meta.hot.accept` will function how it does
+in Vite. Instead of patching the importers of this module, it will call the
+callback with the new module.
+
+```ts
+export const count = 0;
+
+import.meta.hot.accept(newModule => {
+  if (newModule) {
+    // newModule is undefined when SyntaxError happened
+    console.log("updated: count is now ", newModule.count);
+  }
+});
+```
+
+Prefer using `import.meta.hot.accept()` without an argument as it usually makes your code easier to understand.
+
+#### Accepting other modules
+
+```ts
+import { count } from "./foo";
+
+import.meta.hot.accept("./foo", () => {
+  if (!newModule) return;
+
+  console.log("updated: count is now ", count);
+});
+```
+
+Indicates that a dependency's module can be accepted. When the dependency is updated, the callback will be called with the new module.
+
+#### With multiple dependencies
+
+```ts
+import.meta.hot.accept(["./foo", "./bar"], newModules => {
+  // newModules is an array where each item corresponds to the updated module
+  // or undefined if that module had a syntax error
+});
+```
+
+Indicates that multiple dependencies' modules can be accepted. This variant accepts an array of dependencies, where the callback will receive the updated modules, and `undefined` for any that had errors.
+
+### `import.meta.hot.data`
+
+`import.meta.hot.data` maintains state between module instances during hot
+replacement, enabling data transfer from previous to new versions. When
+`import.meta.hot.data` is written into, Bun will also mark this module as
+capable of self-accepting (equivalent of calling `import.meta.hot.accept()`).
+
+```ts
+import { createRoot } from "react-dom/client";
+import { App } from "./app";
+
+const root = import.meta.hot.data.root ??= createRoot(elem);
+root.render(<App />); // re-use an existing root
+```
+
+In production, `data` is inlined to be `{}`, meaning it cannot be used as a state holder.
+
+The above pattern is recommended for stateful modules because Bun knows it can minify `{}.prop ??= value` into `value` in production.
+
+### `import.meta.hot.dispose()`
+
+Attaches an on-dispose callback. This is called:
+
+- Just before the module is replaced with another copy (before the next is loaded)
+- After the module is detached (removing all imports to this module, see `import.meta.hot.prune()`)
+
+```ts
+const sideEffect = setupSideEffect();
+
+import.meta.hot.dispose(() => {
+  sideEffect.cleanup();
+});
+```
+
+This callback is not called on route navigation or when the browser tab closes.
+
+Returning a promise will delay module replacement until the module is disposed.
+All dispose callbacks are called in parallel.
+
+### `import.meta.hot.prune()`
+
+Attaches an on-prune callback. This is called when all imports to this module
+are removed, but the module was previously loaded.
+
+This can be used to clean up resources that were created when the module was
+loaded. Unlike `import.meta.hot.dispose()`, this pairs much better with `accept`
+and `data` to manage stateful resources. A full example managing a `WebSocket`:
+
+```ts
+import { something } from "./something";
+
+// Initialize or re-use a WebSocket connection
+export const ws = (import.meta.hot.data.ws ??= new WebSocket(location.origin));
+
+// If the module's import is removed, clean up the WebSocket connection.
+import.meta.hot.prune(() => {
+  ws.close();
+});
+```
+
+If `dispose` was used instead, the WebSocket would close and re-open on every
+hot update. Both versions of the code will prevent page reloads when imported
+files are updated.
+
+### `import.meta.hot.on()` and `off()`
+
+`on()` and `off()` are used to listen for events from the HMR runtime. Event names are prefixed with a prefix so that plugins do not conflict with each other.
+
+```ts
+import.meta.hot.on("bun:beforeUpdate", () => {
+  console.log("before a hot update");
+});
+```
+
+When a file is replaced, all of its event listeners are automatically removed.
+
+A list of all built-in events:
+
+| Event                  | Emitted when                                                                                    |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| `bun:beforeUpdate`     | before a hot update is applied.                                                                 |
+| `bun:afterUpdate`      | after a hot update is applied.                                                                  |
+| `bun:beforeFullReload` | before a full page reload happens.                                                              |
+| `bun:beforePrune`      | before prune callbacks are called.                                                              |
+| `bun:invalidate`       | when a module is invalidated with `import.meta.hot.invalidate()`                                |
+| `bun:error`            | when a build or runtime error occurs                                                            |
+| `bun:ws:disconnect`    | when the HMR WebSocket connection is lost. This can indicate the development server is offline. |
+| `bun:ws:connect`       | when the HMR WebSocket connects or re-connects.                                                 |
+
+For compatibility with Vite, the above events are also available via `vite:*` prefix instead of `bun:*`.

package/docs/bundler/loaders.md

@@ -4,6 +4,12 @@ The Bun bundler implements a set of default loaders out of the box. As a rule of
 
 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.
 
+You can explicitly specify which loader to use using the 'loader' import attribute.
+
+```ts
+import my_toml from "./my_file" with { loader: "toml" };
+```
+
 ## Built-in loaders
 
 ### `js`

package/docs/cli/publish.md

@@ -7,7 +7,7 @@ Use `bun publish` to publish a package to the npm registry.
 $ bun publish
 
 ## Output
-bun publish v1.2.5-canary.20250306T140602 (ca7428e9)
+bun publish v1.2.5-canary.20250308T140614 (ca7428e9)
 
 packed 203B package.json
 packed 224B README.md
@@ -82,6 +82,11 @@ The `--dry-run` flag can be used to simulate the publish process without actuall
 $ bun publish --dry-run
 ```
 
+### `--gzip-level`
+
+Specify the level of gzip compression to use when packing the package. Only applies to `bun publish` without a tarball path argument. Values range from `0` to `9` (default is `9`).
+{% bunCLIUsage command="publish" /%}
+
 ### `--auth-type`
 
 If you have 2FA enabled for your npm account, `bun publish` will prompt you for a one-time password. This can be done through a browser or the CLI. The `--auth-type` flag can be used to tell the npm registry which method you prefer. The possible values are `web` and `legacy`, with `web` being the default.
@@ -102,7 +107,6 @@ Provide a one-time password directly to the CLI. If the password is valid, this
 $ bun publish --otp 123456
 ```
 
-### `--gzip-level`
-
-Specify the level of gzip compression to use when packing the package. Only applies to `bun publish` without a tarball path argument. Values range from `0` to `9` (default is `9`).
-{% bunCLIUsage command="publish" /%}
+{% callout %}
+**Note** - `bun publish` respects the `NPM_CONFIG_TOKEN` environment variable which can be used when publishing in github actions or automated workflows.
+{% /callout %}

package/docs/guides/ecosystem/nuxt.md

@@ -9,7 +9,7 @@ $ bunx nuxi init my-nuxt-app
 ✔ Which package manager would you like to use?
 bun
 ◐ Installing dependencies...
-bun install v1.2.5-canary.20250306T140602 (16b4bf34)
+bun install v1.2.5-canary.20250308T140614 (16b4bf34)
  + @nuxt/devtools@0.8.2
  + nuxt@3.7.0
  785 packages installed [2.67s]

package/docs/guides/install/add-peer.md

@@ -16,7 +16,7 @@ This will add the package to `peerDependencies` in `package.json`.
 ```json-diff
 {
   "peerDependencies": {
-+   "@types/bun": "^1.2.5-canary.20250306T140602"
++   "@types/bun": "^1.2.5-canary.20250308T140614"
   }
 }
 ```
@@ -28,7 +28,7 @@ Running `bun install` will install peer dependencies by default, unless marked o
 ```json-diff
 {
   "peerDependencies": {
-    "@types/bun": "^1.2.5-canary.20250306T140602"
+    "@types/bun": "^1.2.5-canary.20250308T140614"
   },
   "peerDependenciesMeta": {
 +   "@types/bun": {

package/docs/guides/install/from-npm-install-to-bun-install.md

@@ -97,7 +97,7 @@ $ bun update
 $ bun update @types/bun --latest
 
 # Update a dependency to a specific version
-$ bun update @types/bun@1.2.5-canary.20250306T140602
+$ bun update @types/bun@1.2.5-canary.20250308T140614
 
 # Update all dependencies to the latest versions
 $ bun update --latest

package/docs/guides/test/run-tests.md

@@ -21,7 +21,7 @@ Here's what the output of a typical test run looks like. In this case, there are
 
 ```sh
 $ bun test
-bun test v1.2.5-canary.20250306T140602 (9c68abdb)
+bun test v1.2.5-canary.20250308T140614 (9c68abdb)
 
 test.test.js:
 ✓ add [0.87ms]
@@ -47,7 +47,7 @@ To only run certain test files, pass a positional argument to `bun test`. The ru
 
 ```sh
 $ bun test test3
-bun test v1.2.5-canary.20250306T140602 (9c68abdb)
+bun test v1.2.5-canary.20250308T140614 (9c68abdb)
 
 test3.test.js:
 ✓ add [1.40ms]
@@ -85,7 +85,7 @@ Adding `-t add` will only run tests with "add" in the name. This works with test
 
 ```sh
 $ bun test -t add
-bun test v1.2.5-canary.20250306T140602 (9c68abdb)
+bun test v1.2.5-canary.20250308T140614 (9c68abdb)
 
 test.test.js:
 ✓ add [1.79ms]

package/docs/guides/test/snapshot.md

@@ -18,7 +18,7 @@ The first time this test is executed, Bun will evaluate the value passed into `e
 
 ```sh
 $ bun test test/snap
-bun test v1.2.5-canary.20250306T140602 (9c68abdb)
+bun test v1.2.5-canary.20250308T140614 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.48ms]
@@ -61,7 +61,7 @@ Later, when this test file is executed again, Bun will read the snapshot file an
 
 ```sh
 $ bun test
-bun test v1.2.5-canary.20250306T140602 (9c68abdb)
+bun test v1.2.5-canary.20250308T140614 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [1.05ms]
@@ -78,7 +78,7 @@ To update snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.5-canary.20250306T140602 (9c68abdb)
+bun test v1.2.5-canary.20250308T140614 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

package/docs/guides/test/update-snapshots.md

@@ -29,7 +29,7 @@ To regenerate snapshots, use the `--update-snapshots` flag.
 
 ```sh
 $ bun test --update-snapshots
-bun test v1.2.5-canary.20250306T140602 (9c68abdb)
+bun test v1.2.5-canary.20250308T140614 (9c68abdb)
 
 test/snap.test.ts:
 ✓ snapshot [0.86ms]

package/docs/guides/util/version.md

@@ -5,7 +5,7 @@ name: Get the current Bun version
 Get the current version of Bun in a semver format.
 
 ```ts#index.ts
-Bun.version; // => "1.2.5-canary.20250306T140602"
+Bun.version; // => "1.2.5-canary.20250308T140614"
 ```
 
 ---

package/docs/installation.md

@@ -14,7 +14,7 @@ Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1. Us
 ```bash#macOS/Linux_(curl)
 $ curl -fsSL https://bun.sh/install | bash # for macOS, Linux, and WSL
 # to install a specific version
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250306T140602"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250308T140614"
 ```
 
 ```bash#npm
@@ -189,10 +189,10 @@ Since Bun is a single binary, you can install older versions of Bun by re-runnin
 
 ### Installing a specific version of Bun on Linux/Mac
 
-To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.5-canary.20250306T140602`.
+To install a specific version of Bun, you can pass the git tag of the version you want to install to the install script, such as `bun-v1.2.0` or `bun-v1.2.5-canary.20250308T140614`.
 
 ```sh
-$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250306T140602"
+$ curl -fsSL https://bun.sh/install | bash -s "bun-v1.2.5-canary.20250308T140614"
 ```
 
 ### Installing a specific version of Bun on Windows
@@ -201,7 +201,7 @@ On Windows, you can install a specific version of Bun by passing the version num
 
 ```sh
 # PowerShell:
-$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.5-canary.20250306T140602"
+$ iex "& {$(irm https://bun.sh/install.ps1)} -Version 1.2.5-canary.20250308T140614"
 ```
 
 ## Downloading Bun binaries directly

package/docs/runtime/debugger.md

@@ -124,11 +124,11 @@ await fetch("https://example.com", {
 This prints the `fetch` request as a single-line `curl` command to let you copy-paste into your terminal to replicate the request.
 
 ```sh
-[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.5-canary.20250306T140602" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
+[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" -H "Connection: keep-alive" -H "User-Agent: Bun/1.2.5-canary.20250308T140614" -H "Accept: */*" -H "Host: example.com" -H "Accept-Encoding: gzip, deflate, br" --compressed -H "Content-Length: 13" --data-raw "{\"foo\":\"bar\"}"
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.5-canary.20250306T140602
+[fetch] > User-Agent: Bun/1.2.5-canary.20250308T140614
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br
@@ -170,7 +170,7 @@ This prints the following to the console:
 [fetch] > HTTP/1.1 POST https://example.com/
 [fetch] > content-type: application/json
 [fetch] > Connection: keep-alive
-[fetch] > User-Agent: Bun/1.2.5-canary.20250306T140602
+[fetch] > User-Agent: Bun/1.2.5-canary.20250308T140614
 [fetch] > Accept: */*
 [fetch] > Host: example.com
 [fetch] > Accept-Encoding: gzip, deflate, br

package/docs/test/dom.md

@@ -55,7 +55,7 @@ Let's run this test with `bun test`:
 
 ```bash
 $ bun test
-bun test v1.2.5-canary.20250306T140602
+bun test v1.2.5-canary.20250308T140614
 
 dom.test.ts:
 ✓ dom test [0.82ms]

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.2.5-canary.20250306T140602",
+	"version": "1.2.5-canary.20250308T140614",
 	"name": "bun-types",
 	"license": "MIT",
 	"types": "./index.d.ts",

package/test.d.ts

@@ -168,8 +168,14 @@ declare module "bun:test" {
 	 * @param label the label for the tests
 	 * @param fn the function that defines the tests
 	 */
+
+	interface FunctionLike {
+		readonly name: string;
+	}
 	export interface Describe {
-		(label: string, fn: () => void): void;
+		(fn: () => void): void;
+
+		(label: number | string | Function | FunctionLike, fn: () => void): void;
 		/**
 		 * Skips all other tests, except this group of tests.
 		 *