bun-types 1.1.39-canary.20241216T140602 → 1.1.39-canary.20241217T140602

package/bun.d.ts

@@ -2227,6 +2227,8 @@ declare module "bun" {
 		 * });
 		 */
 		data: T;
+
+		getBufferedAmount(): number;
 	}
 
 	/**

package/docs/api/fetch.md

@@ -234,7 +234,7 @@ To prefetch a DNS entry, you can use the `dns.prefetch` API. This API is useful
 ```ts
 import { dns } from "bun";
 
-dns.prefetch("bun.sh", 443);
+dns.prefetch("bun.sh");
 ```
 
 #### DNS caching

package/docs/api/utils.md

@@ -771,3 +771,28 @@ console.log(obj); // => { foo: "bar" }
 ```
 
 Internally, [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) and [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) serialize and deserialize the same way. This exposes the underlying [HTML Structured Clone Algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) to JavaScript as an ArrayBuffer.
+
+## `estimateShallowMemoryUsageOf` in `bun:jsc`
+
+The `estimateShallowMemoryUsageOf` function returns a best-effort estimate of the memory usage of an object in bytes, excluding the memory usage of properties or other objects it references. For accurate per-object memory usage, use `Bun.generateHeapSnapshot`.
+
+```js
+import { estimateShallowMemoryUsageOf } from "bun:jsc";
+
+const obj = { foo: "bar" };
+const usage = estimateShallowMemoryUsageOf(obj);
+console.log(usage); // => 16
+
+const buffer = Buffer.alloc(1024 * 1024);
+estimateShallowMemoryUsageOf(buffer);
+// => 1048624
+
+const req = new Request("https://bun.sh");
+estimateShallowMemoryUsageOf(req);
+// => 167
+
+const array = Array(1024).fill({ a: 1 });
+// Arrays are usually not stored contiguously in memory, so this will not return a useful value (which isn't a bug).
+estimateShallowMemoryUsageOf(array);
+// => 16
+```

package/docs/bundler/plugins.md

@@ -2,11 +2,47 @@ Bun provides a universal plugin API that can be used to extend both the _runtime
 
 Plugins intercept imports and perform custom loading logic: reading files, transpiling code, etc. They can be used to add support for additional file types, like `.scss` or `.yaml`. In the context of Bun's bundler, plugins can be used to implement framework-level features like CSS extraction, macros, and client-server code co-location.
 
-For more complete documentation of the Plugin API, see [Runtime > Plugins](https://bun.sh/docs/runtime/plugins).
+## Lifecycle hooks
+
+Plugins can register callbacks to be run at various points in the lifecycle of a bundle:
+
+- [`onStart()`](#onstart): Run once the bundler has started a bundle
+- [`onResolve()`](#onresolve): Run before a module is resolved
+- [`onLoad()`](#onload): Run before a module is loaded.
+- [`onBeforeParse()`](#onbeforeparse): Run zero-copy native addons in the parser thread before a file is parsed.
+
+### Reference
+
+A rough overview of the types (please refer to Bun's `bun.d.ts` for the full type definitions):
+
+```ts
+type PluginBuilder = {
+  onStart(callback: () => void): void;
+  onResolve: (
+    args: { filter: RegExp; namespace?: string },
+    callback: (args: { path: string; importer: string }) => {
+      path: string;
+      namespace?: string;
+    } | void,
+  ) => void;
+  onLoad: (
+    args: { filter: RegExp; namespace?: string },
+    defer: () => Promise<void>,
+    callback: (args: { path: string }) => {
+      loader?: Loader;
+      contents?: string;
+      exports?: Record<string, any>;
+    },
+  ) => void;
+  config: BuildConfig;
+};
+
+type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "toml";
+```
 
 ## Usage
 
-A plugin is defined as simple JavaScript object containing a `name` property and a `setup` function. Register a plugin with Bun using the `plugin` function.
+A plugin is defined as simple JavaScript object containing a `name` property and a `setup` function.
 
 ```tsx#myPlugin.ts
 import type { BunPlugin } from "bun";
@@ -28,3 +64,337 @@ Bun.build({
   plugins: [myPlugin],
 });
 ```
+
+## Plugin lifecycle
+
+### Namespaces
+
+`onLoad` and `onResolve` accept an optional `namespace` string. What is a namespaace?
+
+Every module has a namespace. Namespaces are used to prefix the import in transpiled code; for instance, a loader with a `filter: /\.yaml$/` and `namespace: "yaml:"` will transform an import from `./myfile.yaml` into `yaml:./myfile.yaml`.
+
+The default namespace is `"file"` and it is not necessary to specify it, for instance: `import myModule from "./my-module.ts"` is the same as `import myModule from "file:./my-module.ts"`.
+
+Other common namespaces are:
+
+- `"bun"`: for Bun-specific modules (e.g. `"bun:test"`, `"bun:sqlite"`)
+- `"node"`: for Node.js modules (e.g. `"node:fs"`, `"node:path"`)
+
+### `onStart`
+
+```ts
+onStart(callback: () => void): Promise<void> | void;
+```
+
+Registers a callback to be run when the bundler starts a new bundle.
+
+```ts
+import { plugin } from "bun";
+
+plugin({
+  name: "onStart example",
+
+  setup(build) {
+    build.onStart(() => {
+      console.log("Bundle started!");
+    });
+  },
+});
+```
+
+The callback can return a `Promise`. After the bundle process has initialized, the bundler waits until all `onStart()` callbacks have completed before continuing.
+
+For example:
+
+```ts
+const result = await Bun.build({
+  entrypoints: ["./app.ts"],
+  outdir: "./dist",
+  sourcemap: "external",
+  plugins: [
+    {
+      name: "Sleep for 10 seconds",
+      setup(build) {
+        build.onStart(async () => {
+          await Bunlog.sleep(10_000);
+        });
+      },
+    },
+    {
+      name: "Log bundle time to a file",
+      setup(build) {
+        build.onStart(async () => {
+          const now = Date.now();
+          await Bun.$`echo ${now} > bundle-time.txt`;
+        });
+      },
+    },
+  ],
+});
+```
+
+In the above example, Bun will wait until the first `onStart()` (sleeping for 10 seconds) has completed, _as well as_ the second `onStart()` (writing the bundle time to a file).
+
+Note that `onStart()` callbacks (like every other lifecycle callback) do not have the ability to modify the `build.config` object. If you want to mutate `build.config`, you must do so directly in the `setup()` function.
+
+### `onResolve`
+
+```ts
+onResolve(
+  args: { filter: RegExp; namespace?: string },
+  callback: (args: { path: string; importer: string }) => {
+    path: string;
+    namespace?: string;
+  } | void,
+): void;
+```
+
+To bundle your project, Bun walks down the dependency tree of all modules in your project. For each imported module, Bun actually has to find and read that module. The "finding" part is known as "resolving" a module.
+
+The `onResolve()` plugin lifecycle callback allows you to configure how a module is resolved.
+
+The first argument to `onResolve()` is an object with a `filter` and [`namespace`](#what-is-a-namespace) property. The filter is a regular expression which is run on the import string. Effectively, these allow you to filter which modules your custom resolution logic will apply to.
+
+The second argument to `onResolve()` is a callback which is run for each module import Bun finds that matches the `filter` and `namespace` defined in the first argument.
+
+The callback receives as input the _path_ to the matching module. The callback can return a _new path_ for the module. Bun will read the contents of the _new path_ and parse it as a module.
+
+For example, redirecting all imports to `images/` to `./public/images/`:
+
+```ts
+import { plugin } from "bun";
+
+plugin({
+  name: "onResolve example",
+  setup(build) {
+    build.onResolve({ filter: /.*/, namespace: "file" }, args => {
+      if (args.path.startsWith("images/")) {
+        return {
+          path: args.path.replace("images/", "./public/images/"),
+        };
+      }
+    });
+  },
+});
+```
+
+### `onLoad`
+
+```ts
+onLoad(
+  args: { filter: RegExp; namespace?: string },
+  defer: () => Promise<void>,
+  callback: (args: { path: string, importer: string, namespace: string, kind: ImportKind  }) => {
+    loader?: Loader;
+    contents?: string;
+    exports?: Record<string, any>;
+  },
+): void;
+```
+
+After Bun's bundler has resolved a module, it needs to read the contents of the module and parse it.
+
+The `onLoad()` plugin lifecycle callback allows you to modify the _contents_ of a module before it is read and parsed by Bun.
+
+Like `onResolve()`, the first argument to `onLoad()` allows you to filter which modules this invocation of `onLoad()` will apply to.
+
+The second argument to `onLoad()` is a callback which is run for each matching module _before_ Bun loads the contents of the module into memory.
+
+This callback receives as input the _path_ to the matching module, the _importer_ of the module (the module that imported the module), the _namespace_ of the module, and the _kind_ of the module.
+
+The callback can return a new `contents` string for the module as well as a new `loader`.
+
+For example:
+
+```ts
+import { plugin } from "bun";
+
+const envPlugin: BunPlugin = {
+  name: "env plugin",
+  setup(build) {
+    build.onLoad({ filter: /env/, namespace: "file" }, args => {
+      return {
+        contents: `export default ${JSON.stringify(process.env)}`,
+        loader: "js",
+      };
+    });
+  },
+});
+
+Bun.build({
+  entrypoints: ["./app.ts"],
+  outdir: "./dist",
+  plugins: [envPlugin],
+});
+
+// import env from "env"
+// env.FOO === "bar"
+```
+
+This plugin will transform all imports of the form `import env from "env"` into a JavaScript module that exports the current environment variables.
+
+#### `.defer()`
+
+One of the arguments passed to the `onLoad` callback is a `defer` function. This function returns a `Promise` that is resolved when all _other_ modules have been loaded.
+
+This allows you to delay execution of the `onLoad` callback until all other modules have been loaded.
+
+This is useful for returning contens of a module that depends on other modules.
+
+##### Example: tracking and reporting unused exports
+
+```ts
+import { plugin } from "bun";
+
+plugin({
+  name: "track imports",
+  setup(build) {
+    const transpiler = new Bun.Transpiler();
+
+    let trackedImports: Record<string, number> = {};
+
+    // Each module that goes through this onLoad callback
+    // will record its imports in `trackedImports`
+    build.onLoad({ filter: /\.ts/ }, async ({ path }) => {
+      const contents = await Bun.file(path).arrayBuffer();
+
+      const imports = transpiler.scanImports(contents);
+
+      for (const i of imports) {
+        trackedImports[i.path] = (trackedImports[i.path] || 0) + 1;
+      }
+
+      return undefined;
+    });
+
+    build.onLoad({ filter: /stats\.json/ }, async ({ defer }) => {
+      // Wait for all files to be loaded, ensuring
+      // that every file goes through the above `onLoad()` function
+      // and their imports tracked
+      await defer();
+
+      // Emit JSON containing the stats of each import
+      return {
+        contents: `export default ${JSON.stringify(trackedImports)}`,
+        loader: "json",
+      };
+    });
+  },
+});
+```
+
+Note that the `.defer()` function currently has the limitation that it can only be called once per `onLoad` callback.
+
+## Native plugins
+
+One of the reasons why Bun's bundler is so fast is that it is written in native code and leverages multi-threading to load and parse modules in parallel.
+
+However, one limitation of plugins written in JavaScript is that JavaScript itself is single-threaded.
+
+Native plugins are written as [NAPI](/docs/node-api) modules and can be run on multiple threads. This allows native plugins to run much faster than JavaScript plugins.
+
+In addition, native plugins can skip unnecessary work such as the UTF-8 -> UTF-16 conversion needed to pass strings to JavaScript.
+
+These are the following lifecycle hooks which are available to native plugins:
+
+- [`onBeforeParse()`](#onbeforeparse): Called on any thread before a file is parsed by Bun's bundler.
+
+Native plugins are NAPI modules which expose lifecycle hooks as C ABI functions.
+
+To create a native plugin, you must export a C ABI function which matches the signature of the native lifecycle hook you want to implement.
+
+### Creating a native plugin in Rust
+
+Native plugins are NAPI modules which expose lifecycle hooks as C ABI functions.
+
+To create a native plugin, you must export a C ABI function which matches the signature of the native lifecycle hook you want to implement.
+
+```bash
+bun add -g @napi-rs/cli
+napi new
+```
+
+Then install this crate:
+
+```bash
+cargo add bun-native-plugin
+```
+
+Now, inside the `lib.rs` file, we'll use the `bun_native_plugin::bun` proc macro to define a function which
+will implement our native plugin.
+
+Here's an example implementing the `onBeforeParse` hook:
+
+```rs
+use bun_native_plugin::{define_bun_plugin, OnBeforeParse, bun, Result, anyhow, BunLoader};
+use napi_derive::napi;
+
+/// Define the plugin and its name
+define_bun_plugin!("replace-foo-with-bar");
+
+/// Here we'll implement `onBeforeParse` with code that replaces all occurrences of
+/// `foo` with `bar`.
+///
+/// We use the #[bun] macro to generate some of the boilerplate code.
+///
+/// The argument of the function (`handle: &mut OnBeforeParse`) tells
+/// the macro that this function implements the `onBeforeParse` hook.
+#[bun]
+pub fn replace_foo_with_bar(handle: &mut OnBeforeParse) -> Result<()> {
+  // Fetch the input source code.
+  let input_source_code = handle.input_source_code()?;
+
+  // Get the Loader for the file
+  let loader = handle.output_loader();
+
+
+  let output_source_code = input_source_code.replace("foo", "bar");
+
+  handle.set_output_source_code(output_source_code, BunLoader::BUN_LOADER_JSX);
+
+  Ok(())
+}
+```
+
+And to use it in Bun.build():
+
+```typescript
+import myNativeAddon from "./my-native-addon";
+Bun.build({
+  entrypoints: ["./app.tsx"],
+  plugins: [
+    {
+      name: "my-plugin",
+
+      setup(build) {
+        build.onBeforeParse(
+          {
+            namespace: "file",
+            filter: "**/*.tsx",
+          },
+          {
+            napiModule: myNativeAddon,
+            symbol: "replace_foo_with_bar",
+            // external: myNativeAddon.getSharedState()
+          },
+        );
+      },
+    },
+  ],
+});
+```
+
+### `onBeforeParse`
+
+```ts
+onBeforeParse(
+  args: { filter: RegExp; namespace?: string },
+  callback: { napiModule: NapiModule; symbol: string; external?: unknown },
+): void;
+```
+
+This lifecycle callback is run immediately before a file is parsed by Bun's bundler.
+
+As input, it receives the file's contents and can optionally return new source code.
+
+This callback can be called from any thread and so the napi module implementation must be thread-safe.

package/docs/project/bindgen.md

@@ -61,7 +61,10 @@ This function declaration is equivalent to:
 declare function add(a: number, b: number = 1): number;
 ```
 
-The code generator will provide `bun.gen.math.jsAdd`, which is the native function implementation. To pass to JavaScript, use `bun.gen.math.createAddCallback(global)`
+The code generator will provide `bun.gen.math.jsAdd`, which is the native
+function implementation. To pass to JavaScript, use
+`bun.gen.math.createAddCallback(global)`. JS files in `src/js/` may use
+`$bindgenFn("math.bind.ts", "add")` to get a handle to the implementation.
 
 ## Strings
 
@@ -104,7 +107,7 @@ export const action = fn({
 
 In Zig, each variant gets a number, based on the order the schema defines.
 
-```
+```zig
 fn action1(a: i32) i32 {
   return a;
 }
@@ -180,9 +183,9 @@ export const add = fn({
     // enforce in i32 range
     a: t.i32.enforceRange(),
     // clamp to u16 range
-    c: t.u16,
+    b: t.u16,
     // enforce in arbitrary range, with a default if not provided
-    b: t.i32.enforceRange(0, 1000).default(5),
+    c: t.i32.enforceRange(0, 1000).default(5),
     // clamp to arbitrary range, or null
     d: t.u16.clamp(0, 10).optional,
   },
@@ -190,6 +193,29 @@ export const add = fn({
 });
 ```
 
+Various Node.js validator functions such as `validateInteger`, `validateNumber`, and more are available. Use these when implementing Node.js APIs, so the error messages match 1:1 what Node would do.
+
+Unlike `enforceRange`, which is taken from WebIDL, `validate*` functions are much more strict on the input they accept. For example, Node's numerical validator check `typeof value === 'number'`, while WebIDL uses `ToNumber` for lossy conversion.
+
+```ts
+import { t, fn } from "bindgen";
+
+export const add = fn({
+  args: {
+    global: t.globalObject,
+    // throw if not given a number
+    a: t.f64.validateNumber(),
+    // valid in i32 range
+    a: t.i32.validateInt32(),
+    // f64 within safe integer range
+    b: t.f64.validateInteger(),
+    // f64 in given range
+    c: t.f64.validateNumber(-10000, 10000),
+  },
+  ret: t.i32,
+});
+```
+
 ## Callbacks
 
 TODO

package/docs/runtime/plugins.md

@@ -553,150 +553,3 @@ plugin({
 ```
 
 This plugin will transform all imports of the form `import env from "env"` into a JavaScript module that exports the current environment variables.
-
-#### `.defer()`
-
-One of the arguments passed to the `onLoad` callback is a `defer` function. This function returns a `Promise` that is resolved when all _other_ modules have been loaded.
-
-This allows you to delay execution of the `onLoad` callback until all other modules have been loaded.
-
-This is useful for returning contens of a module that depends on other modules.
-
-##### Example: tracking and reporting unused exports
-
-```ts
-import { plugin } from "bun";
-
-plugin({
-  name: "track imports",
-  setup(build) {
-    const transpiler = new Bun.Transpiler();
-
-    let trackedImports: Record<string, number> = {};
-
-    // Each module that goes through this onLoad callback
-    // will record its imports in `trackedImports`
-    build.onLoad({ filter: /\.ts/ }, async ({ path }) => {
-      const contents = await Bun.file(path).arrayBuffer();
-
-      const imports = transpiler.scanImports(contents);
-
-      for (const i of imports) {
-        trackedImports[i.path] = (trackedImports[i.path] || 0) + 1;
-      }
-
-      return undefined;
-    });
-
-    build.onLoad({ filter: /stats\.json/ }, async ({ defer }) => {
-      // Wait for all files to be loaded, ensuring
-      // that every file goes through the above `onLoad()` function
-      // and their imports tracked
-      await defer();
-
-      // Emit JSON containing the stats of each import
-      return {
-        contents: `export default ${JSON.stringify(trackedImports)}`,
-        loader: "json",
-      };
-    });
-  },
-});
-```
-
-Note that the `.defer()` function currently has the limitation that it can only be called once per `onLoad` callback.
-
-## Native plugins
-
-{% callout %}
-**NOTE** — This is an advanced and experiemental API recommended for plugin developers who are familiar with systems programming and the C ABI. Use with caution.
-{% /callout %}
-
-One of the reasons why Bun's bundler is so fast is that it is written in native code and leverages multi-threading to load and parse modules in parallel.
-
-However, one limitation of plugins written in JavaScript is that JavaScript itself is single-threaded.
-
-Native plugins are written as [NAPI](/docs/node-api) modules and can be run on multiple threads. This allows native plugins to run much faster than JavaScript plugins.
-
-In addition, native plugins can skip unnecessary work such as the UTF-8 -> UTF-16 conversion needed to pass strings to JavaScript.
-
-These are the following lifecycle hooks which are available to native plugins:
-
-- [`onBeforeParse()`](#onbeforeparse): Called on any thread before a file is parsed by Bun's bundler.
-
-### Creating a native plugin
-
-Native plugins are NAPI modules which expose lifecycle hooks as C ABI functions.
-
-To create a native plugin, you must export a C ABI function which matches the signature of the native lifecycle hook you want to implement.
-
-#### Example: Rust with napi-rs
-
-First initialize a napi project (see [here](https://napi.rs/docs/introduction/getting-started) for a more comprehensive guide).
-
-Then install Bun's official safe plugin wrapper crate:
-
-```bash
-cargo add bun-native-plugin
-```
-
-Now you can export an `extern "C" fn` which is the implementation of your plugin:
-
-```rust
-#[no_mangle]
-extern "C" fn on_before_parse_impl(
-  args: *const bun_native_plugin::sys::OnBeforeParseArguments,
-  result: *mut bun_native_plugin::sys::OnBeforeParseResult,
-) {
-  let args = unsafe { &*args };
-  let result = unsafe { &mut *result };
-
-  let mut handle = match bun_native_plugin::OnBeforeParse::from_raw(args, result) {
-    Ok(handle) => handle,
-    Err(_) => {
-      return;
-    }
-  };
-
-  let source_code = match handle.input_source_code() {
-    Ok(source_code) => source_code,
-    Err(_) => {
-      handle.log_error("Fetching source code failed!");
-      return;
-    }
-  };
-
-  let loader = handle.output_loader();
-  handle.set_output_source_code(source_code.replace("foo", "bar"), loader);
-```
-
-Use napi-rs to compile the plugin to a `.node` file, then you can `require()` it from JS and use it:
-
-```js
-await Bun.build({
-  entrypoints: ["index.ts"],
-  setup(build) {
-    const myNativePlugin = require("./path/to/plugin.node");
-
-    build.onBeforeParse(
-      { filter: /\.ts/ },
-      { napiModule: myNativePlugin, symbol: "on_before_parse_impl" },
-    );
-  },
-});
-```
-
-### `onBeforeParse`
-
-```ts
-onBeforeParse(
-  args: { filter: RegExp; namespace?: string },
-  callback: { napiModule: NapiModule; symbol: string; external?: unknown },
-): void;
-```
-
-This lifecycle callback is run immediately before a file is parsed by Bun's bundler.
-
-As input, it receives the file's contents and can optionally return new source code.
-
-This callback can be called from any thread and so the napi module implementation must be thread-safe.

package/jsc.d.ts

@@ -226,4 +226,18 @@ declare module "bun:jsc" {
 	 * Run JavaScriptCore's sampling profiler
 	 */
 	function startSamplingProfiler(optionalDirectory?: string): void;
+
+	/**
+	 * Non-recursively estimate the memory usage of an object, excluding the memory usage of
+	 * properties or other objects it references. For more accurate per-object
+	 * memory usage, use {@link Bun.generateHeapSnapshot}.
+	 *
+	 * This is a best-effort estimate. It may not be 100% accurate. When it's
+	 * wrong, it may mean the memory is non-contiguous (such as a large array).
+	 *
+	 * Passing a primitive type that isn't heap allocated returns 0.
+	 */
+	function estimateShallowMemoryUsageOf(
+		value: object | CallableFunction | bigint | symbol | string,
+	): number;
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.39-canary.20241216T140602",
+	"version": "1.1.39-canary.20241217T140602",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",