bun-types 1.1.39-canary.20241204T140703 → 1.1.39-canary.20241206T140546

package/bun.d.ts

@@ -14,6 +14,7 @@
  * This module aliases `globalThis.Bun`.
  */
 declare module "bun" {
+	import type { FFIFunctionCallableSymbol } from "bun:ffi";
 	import type { Encoding as CryptoEncoding } from "crypto";
 	import type {
 		CipherNameAndProtocol,
@@ -4043,7 +4044,11 @@ declare module "bun" {
 		defer: () => Promise<void>;
 	}
 
-	type OnLoadResult = OnLoadResultSourceCode | OnLoadResultObject | undefined;
+	type OnLoadResult =
+		| OnLoadResultSourceCode
+		| OnLoadResultObject
+		| undefined
+		| void;
 	type OnLoadCallback = (
 		args: OnLoadArgs,
 	) => OnLoadResult | Promise<OnLoadResult>;
@@ -4099,7 +4104,34 @@ declare module "bun" {
 		| undefined
 		| null;
 
+	type FFIFunctionCallable = Function & {
+		// Making a nominally typed function so that the user must get it from dlopen
+		readonly __ffi_function_callable: typeof FFIFunctionCallableSymbol;
+	};
+
 	interface PluginBuilder {
+		/**
+		 * Register a callback which will be invoked when bundling starts.
+		 * @example
+		 * ```ts
+		 * Bun.plugin({
+		 *   setup(builder) {
+		 *     builder.onStart(() => {
+		 *       console.log("bundle just started!!")
+		 *     });
+		 *   },
+		 * });
+		 * ```
+		 */
+		onStart(callback: OnStartCallback): void;
+		onBeforeParse(
+			constraints: PluginConstraints,
+			callback: {
+				napiModule: unknown;
+				symbol: string;
+				external?: unknown | undefined;
+			},
+		): void;
 		/**
 		 * Register a callback to load imports with a specific import specifier
 		 * @param constraints The constraints to apply the plugin to
@@ -4135,20 +4167,6 @@ declare module "bun" {
 			constraints: PluginConstraints,
 			callback: OnResolveCallback,
 		): void;
-		/**
-		 * Register a callback which will be invoked when bundling starts.
-		 * @example
-		 * ```ts
-		 * Bun.plugin({
-		 *   setup(builder) {
-		 *     builder.onStart(() => {
-		 *       console.log("bundle just started!!")
-		 *     });
-		 *   },
-		 * });
-		 * ```
-		 */
-		onStart(callback: OnStartCallback): void;
 		/**
 		 * The config object passed to `Bun.build` as is. Can be mutated.
 		 */

package/docs/guides/test/migrate-from-jest.md

@@ -30,7 +30,6 @@ Bun implements the vast majority of Jest's matchers, but compatibility isn't 100
 
 Some notable missing features:
 
-- `expect().toMatchInlineSnapshot()`
 - `expect().toHaveReturned()`
 
 ---

package/docs/guides/test/snapshot.md

@@ -4,10 +4,6 @@ name: Use snapshot testing in `bun test`
 
 Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
 
-{% callout %}
-The `.toMatchInlineSnapshot()` method is not yet supported.
-{% /callout %}
-
 ```ts#snap.test.ts
 import { test, expect } from "bun:test";
 
@@ -96,4 +92,4 @@ Ran 1 tests across 1 files. [102.00ms]
 
 ---
 
-See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/mocks) for complete documentation on mocking with the Bun test runner.
+See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/snapshots) for complete documentation on snapshots with the Bun test runner.

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

@@ -4,10 +4,6 @@ name: Update snapshots in `bun test`
 
 Bun's test runner supports Jest-style snapshot testing via `.toMatchSnapshot()`.
 
-{% callout %}
-The `.toMatchInlineSnapshot()` method is not yet supported.
-{% /callout %}
-
 ```ts#snap.test.ts
 import { test, expect } from "bun:test";
 
@@ -47,4 +43,4 @@ Ran 1 tests across 1 files. [102.00ms]
 
 ---
 
-See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/mocks) for complete documentation on mocking with the Bun test runner.
+See [Docs > Test Runner > Snapshots](https://bun.sh/docs/test/snapshots) for complete documentation on snapshots with the Bun test runner.

package/docs/runtime/plugins.md

@@ -355,7 +355,7 @@ Bun.build({
 
 {% /callout %}
 
-## Lifecycle callbacks
+## Lifecycle hooks
 
 Plugins can register callbacks to be run at various points in the lifecycle of a bundle:
 
@@ -363,6 +363,8 @@ Plugins can register callbacks to be run at various points in the lifecycle of a
 - [`onResolve()`](#onresolve): Run before a module is resolved
 - [`onLoad()`](#onload): Run before a module is loaded.
 
+### Reference
+
 A rough overview of the types (please refer to Bun's `bun.d.ts` for the full type definitions):
 
 ```ts
@@ -603,3 +605,98 @@ plugin({
 ```
 
 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/docs/test/writing.md

@@ -531,17 +531,17 @@ Bun implements the following matchers. Full Jest compatibility is on the roadmap
 
 ---
 
-- ❌
+- ✅
 - [`.toMatchInlineSnapshot()`](https://jestjs.io/docs/expect#tomatchinlinesnapshotpropertymatchers-inlinesnapshot)
 
 ---
 
-- ❌
+- ✅
 - [`.toThrowErrorMatchingSnapshot()`](https://jestjs.io/docs/expect#tothrowerrormatchingsnapshothint)
 
 ---
 
-- ❌
+- ✅
 - [`.toThrowErrorMatchingInlineSnapshot()`](https://jestjs.io/docs/expect#tothrowerrormatchinginlinesnapshotinlinesnapshot)
 
 {% /table %}

package/ffi.d.ts

@@ -570,17 +570,22 @@ declare module "bun:ffi" {
 			? FFITypeStringToType[T]
 			: never;
 
+	const FFIFunctionCallableSymbol: unique symbol;
 	type ConvertFns<Fns extends Symbols> = {
-		[K in keyof Fns]: (
-			...args: Fns[K]["args"] extends infer A extends readonly FFITypeOrString[]
-				? { [L in keyof A]: FFITypeToArgsType[ToFFIType<A[L]>] }
-				: // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
-					[unknown] extends [Fns[K]["args"]]
-					? []
-					: never
-		) => [unknown] extends [Fns[K]["returns"]] // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
-			? undefined
-			: FFITypeToReturnsType[ToFFIType<NonNullable<Fns[K]["returns"]>>];
+		[K in keyof Fns]: {
+			(
+				...args: Fns[K]["args"] extends infer A extends
+					readonly FFITypeOrString[]
+					? { [L in keyof A]: FFITypeToArgsType[ToFFIType<A[L]>] }
+					: // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+						[unknown] extends [Fns[K]["args"]]
+						? []
+						: never
+			): [unknown] extends [Fns[K]["returns"]] // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+				? undefined
+				: FFITypeToReturnsType[ToFFIType<NonNullable<Fns[K]["returns"]>>];
+			__ffi_function_callable: typeof FFIFunctionCallableSymbol;
+		};
 	};
 
 	/**

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.39-canary.20241204T140703",
+	"version": "1.1.39-canary.20241206T140546",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",

package/test.d.ts

@@ -1358,6 +1358,57 @@ declare module "bun:test" {
 		 * @param hint Hint used to identify the snapshot in the snapshot file.
 		 */
 		toMatchSnapshot(propertyMatchers?: object, hint?: string): void;
+		/**
+		 * Asserts that a value matches the most recent inline snapshot.
+		 *
+		 * @example
+		 * expect("Hello").toMatchInlineSnapshot();
+		 * expect("Hello").toMatchInlineSnapshot(`"Hello"`);
+		 *
+		 * @param value The latest automatically-updated snapshot value.
+		 */
+		toMatchInlineSnapshot(value?: string): void;
+		/**
+		 * Asserts that a value matches the most recent inline snapshot.
+		 *
+		 * @example
+		 * expect({ c: new Date() }).toMatchInlineSnapshot({ c: expect.any(Date) });
+		 * expect({ c: new Date() }).toMatchInlineSnapshot({ c: expect.any(Date) }, `
+		 * {
+		 *   "v": Any<Date>,
+		 * }
+		 * `);
+		 *
+		 * @param propertyMatchers Object containing properties to match against the value.
+		 * @param value The latest automatically-updated snapshot value.
+		 */
+		toMatchInlineSnapshot(propertyMatchers?: object, value?: string): void;
+		/**
+		 * Asserts that a function throws an error matching the most recent snapshot.
+		 *
+		 * @example
+		 * function fail() {
+		 *   throw new Error("Oops!");
+		 * }
+		 * expect(fail).toThrowErrorMatchingSnapshot();
+		 * expect(fail).toThrowErrorMatchingSnapshot("This one should say Oops!");
+		 *
+		 * @param value The latest automatically-updated snapshot value.
+		 */
+		toThrowErrorMatchingSnapshot(hint?: string): void;
+		/**
+		 * Asserts that a function throws an error matching the most recent snapshot.
+		 *
+		 * @example
+		 * function fail() {
+		 *   throw new Error("Oops!");
+		 * }
+		 * expect(fail).toThrowErrorMatchingInlineSnapshot();
+		 * expect(fail).toThrowErrorMatchingInlineSnapshot(`"Oops!"`);
+		 *
+		 * @param value The latest automatically-updated snapshot value.
+		 */
+		toThrowErrorMatchingInlineSnapshot(value?: string): void;
 		/**
 		 * Asserts that an object matches a subset of properties.
 		 *