bun-types 1.1.39-canary.20241209T140550 → 1.1.39-canary.20241211T140552

package/ambient.d.ts

@@ -0,0 +1,9 @@
+declare module "*.txt" {
+	var text: string;
+	export = text;
+}
+
+declare module "*.toml" {
+	var contents: any;
+	export = contents;
+}

package/bun.d.ts

@@ -1605,6 +1605,26 @@ declare module "bun" {
 		 * https://nodejs.org/api/packages.html#exports
 		 */
 		conditions?: Array<string> | string;
+
+		/**
+		 * Controls how environment variables are handled during bundling.
+		 *
+		 * Can be one of:
+		 * - `"inline"`: Injects environment variables into the bundled output by converting `process.env.FOO`
+		 *   references to string literals containing the actual environment variable values
+		 * - `"disable"`: Disables environment variable injection entirely
+		 * - A string ending in `*`: Inlines environment variables that match the given prefix.
+		 *   For example, `"MY_PUBLIC_*"` will only include env vars starting with "MY_PUBLIC_"
+		 *
+		 * @example
+		 * ```ts
+		 * Bun.build({
+		 *   env: "MY_PUBLIC_*",
+		 *   entrypoints: ["src/index.ts"],
+		 * })
+		 * ```
+		 */
+		env?: "inline" | "disable" | `${string}*`;
 		minify?:
 			| boolean
 			| {

package/docs/bundler/index.md

@@ -546,6 +546,113 @@ export type ImportKind =
 
 By design, the manifest is a simple JSON object that can easily be serialized or written to disk. It is also compatible with esbuild's [`metafile`](https://esbuild.github.io/api/#metafile) format. -->
 
+### `env`
+
+Controls how environment variables are handled during bundling. Internally, this uses `define` to inject environment variables into the bundle, but makes it easier to specify the environment variables to inject.
+
+#### `env: "inline"`
+
+Injects environment variables into the bundled output by converting `process.env.FOO` references to string literals containing the actual environment variable values.
+
+{% codetabs group="a" %}
+
+```ts#JavaScript
+await Bun.build({
+  entrypoints: ['./index.tsx'],
+  outdir: './out',
+  env: "inline",
+})
+```
+
+```bash#CLI
+$ FOO=bar BAZ=123 bun build ./index.tsx --outdir ./out --env inline
+```
+
+{% /codetabs %}
+
+For the input below:
+
+```js#input.js
+console.log(process.env.FOO);
+console.log(process.env.BAZ);
+```
+
+The generated bundle will contain the following code:
+
+```js#output.js
+console.log("bar");
+console.log("123");
+```
+
+#### `env: "PUBLIC_*"` (prefix)
+
+Inlines environment variables matching the given prefix (the part before the `*` character), replacing `process.env.FOO` with the actual environment variable value. This is useful for selectively inlining environment variables for things like public-facing URLs or client-side tokens, without worrying about injecting private credentials into output bundles.
+
+{% codetabs group="a" %}
+
+```ts#JavaScript
+await Bun.build({
+  entrypoints: ['./index.tsx'],
+  outdir: './out',
+
+  // Inline all env vars that start with "ACME_PUBLIC_"
+  env: "ACME_PUBLIC_*",
+})
+```
+
+```bash#CLI
+$ FOO=bar BAZ=123 ACME_PUBLIC_URL=https://acme.com bun build ./index.tsx --outdir ./out --env 'ACME_PUBLIC_*'
+```
+
+{% /codetabs %}
+
+For example, given the following environment variables:
+
+```bash
+$ FOO=bar BAZ=123 ACME_PUBLIC_URL=https://acme.com
+```
+
+And source code:
+
+```ts#index.tsx
+console.log(process.env.FOO);
+console.log(process.env.ACME_PUBLIC_URL);
+console.log(process.env.BAZ);
+```
+
+The generated bundle will contain the following code:
+
+```js
+console.log(process.env.FOO);
+console.log("https://acme.com");
+console.log(process.env.BAZ);
+```
+
+#### `env: "disable"`
+
+Disables environment variable injection entirely.
+
+For example, given the following environment variables:
+
+```bash
+$ FOO=bar BAZ=123 ACME_PUBLIC_URL=https://acme.com
+```
+
+And source code:
+
+```ts#index.tsx
+console.log(process.env.FOO);
+console.log(process.env.ACME_PUBLIC_URL);
+console.log(process.env.BAZ);
+```
+
+The generated bundle will contain the following code:
+
+```js
+console.log(process.env.FOO);
+console.log(process.env.BAZ);
+```
+
 ### `sourcemap`
 
 Specifies the type of sourcemap to generate.

package/docs/guides/test/testing-library.md

@@ -49,7 +49,7 @@ Next, add these preload scripts to your `bunfig.toml` (you can also have everyth
 
 ```toml#bunfig.toml
 [test]
-preload = ["happydom.ts", "testing-library.ts"]
+preload = ["./happydom.ts", "./testing-library.ts"]
 ```
 ---
 
@@ -84,4 +84,4 @@ test('Can use Testing Library', () => {
 
 ---
 
-Refer to the [Testing Library docs](https://testing-library.com/), [Happy DOM repo](https://github.com/capricorn86/happy-dom) and [Docs > Test runner > DOM](https://bun.sh/docs/test/dom) for complete documentation on writing browser tests with Bun.
+Refer to the [Testing Library docs](https://testing-library.com/), [Happy DOM repo](https://github.com/capricorn86/happy-dom) and [Docs > Test runner > DOM](https://bun.sh/docs/test/dom) for complete documentation on writing browser tests with Bun.

package/docs/project/bindgen.md

@@ -0,0 +1,199 @@
+{% callout %}
+
+This document is for maintainers and contributors to Bun, and describes internal implementation details.
+
+{% /callout %}
+
+The new bindings generator, introduced to the codebase in Dec 2024, scans for
+`*.bind.ts` to find function and class definition, and generates glue code to
+interop between JavaScript and native code.
+
+There are currently other code generators and systems that achieve similar
+purposes. The following will all eventually be completely phased out in favor of
+this one:
+
+- "Classes generator", converting `*.classes.ts` for custom classes.
+- "JS2Native", allowing ad-hoc calls from `src/js` to native code.
+
+## Creating JS Functions in Zig
+
+Given a file implementing a simple function, such as `add`
+
+```zig#src/bun.js/math.zig
+pub fn add(global: *JSC.JSGlobalObject, a: i32, b: i32) !i32 {
+    return std.math.add(i32, a, b) catch {
+        // Binding functions can return `error.OutOfMemory` and `error.JSError`.
+        // Others like `error.Overflow` from `std.math.add` must be converted.
+        // Remember to be descriptive.
+        return global.throwPretty("Integer overflow while adding", .{});
+    };
+}
+
+const gen = bun.gen.math; // "math" being this file's basename
+
+const std = @import("std");
+const bun = @import("root").bun;
+const JSC = bun.JSC;
+```
+
+Then describe the API schema using a `.bind.ts` function. The binding file goes next to the Zig file.
+
+```ts#src/bun.js/math.bind.ts
+import { t, fn } from 'bindgen';
+
+export const add = fn({
+  args: {
+    global: t.globalObject,
+    a: t.i32,
+    b: t.i32.default(1),
+  },
+  ret: t.i32,
+});
+```
+
+This function declaration is equivalent to:
+
+```ts
+/**
+ * Throws if zero arguments are provided.
+ * Wraps out of range numbers using modulo.
+ */
+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)`
+
+## Strings
+
+The type for receiving strings is one of [`t.DOMString`](https://webidl.spec.whatwg.org/#idl-DOMString), [`t.ByteString`](https://webidl.spec.whatwg.org/#idl-ByteString), and [`t.USVString`](https://webidl.spec.whatwg.org/#idl-USVString). These map directly to their WebIDL counterparts, and have slightly different conversion logic. Bindgen will pass BunString to native code in all cases.
+
+When in doubt, use DOMString.
+
+`t.UTF8String` can be used in place of `t.DOMString`, but will call `bun.String.toUTF8`. The native callback gets `[]const u8` (WTF-8 data) passed to native code, freeing it after the function returns.
+
+TLDRs from WebIDL spec:
+
+- ByteString can only contain valid latin1 characters. It is not safe to assume bun.String is already in 8-bit format, but it is extremely likely.
+- USVString will not contain invalid surrogate pairs, aka text that can be represented correctly in UTF-8.
+- DOMString is the loosest but also most recommended strategy.
+
+## Function Variants
+
+A `variants` can specify multiple variants (also known as overloads).
+
+```ts#src/bun.js/math.bind.ts
+import { t, fn } from 'bindgen';
+
+export const action = fn({
+  variants: [
+    {
+      args: {
+        a: t.i32,
+      },
+      ret: t.i32,
+    },
+    {
+      args: {
+        a: t.DOMString,
+      },
+      ret: t.DOMString,
+    },
+  ]
+});
+```
+
+In Zig, each variant gets a number, based on the order the schema defines.
+
+```
+fn action1(a: i32) i32 {
+  return a;
+}
+
+fn action2(a: bun.String) bun.String {
+  return a;
+}
+```
+
+## `t.dictionary`
+
+A `dictionary` is a definition for a JavaScript object, typically as a function inputs. For function outputs, it is usually a smarter idea to declare a class type to add functions and destructuring.
+
+## Enumerations
+
+To use [WebIDL's enumeration](https://webidl.spec.whatwg.org/#idl-enums) type, use either:
+
+- `t.stringEnum`: Create and codegen a new enum type.
+- `t.zigEnum`: Derive a bindgen type off of an existing enum in the codebase.
+
+An example of `stringEnum` as used in `fmt.zig` / `bun:internal-for-testing`
+
+```ts
+export const Formatter = t.stringEnum(
+  "highlight-javascript",
+  "escape-powershell",
+);
+
+export const fmtString = fn({
+  args: {
+    global: t.globalObject,
+    code: t.UTF8String,
+    formatter: Formatter,
+  },
+  ret: t.DOMString,
+});
+```
+
+WebIDL strongly encourages using kebab case for enumeration values, to be consistent with existing Web APIs.
+
+### Deriving enums from Zig code
+
+TODO: zigEnum
+
+## `t.oneOf`
+
+A `oneOf` is a union between two or more types. It is represented by `union(enum)` in Zig.
+
+TODO:
+
+## Attributes
+
+There are set of attributes that can be chained onto `t.*` types. On all types there are:
+
+- `.required`, in dictionary parameters only
+- `.optional`, in function arguments only
+- `.default(T)`
+
+When a value is optional, it is lowered to a Zig optional.
+
+Depending on the type, there are more attributes available. See the type definitions in auto-complete for more details. Note that one of the above three can only be applied, and they must be applied at the end.
+
+### Integer Attributes
+
+Integer types allow customizing the overflow behavior with `clamp` or `enforceRange`
+
+```ts
+import { t, fn } from "bindgen";
+
+export const add = fn({
+  args: {
+    global: t.globalObject,
+    // enforce in i32 range
+    a: t.i32.enforceRange(),
+    // clamp to u16 range
+    c: t.u16,
+    // enforce in arbitrary range, with a default if not provided
+    b: t.i32.enforceRange(0, 1000).default(5),
+    // clamp to arbitrary range, or null
+    d: t.u16.clamp(0, 10).optional,
+  },
+  ret: t.i32,
+});
+```
+
+## Callbacks
+
+TODO
+
+## Classes
+
+TODO

package/globals.d.ts

@@ -1,5 +1,3 @@
-export {};
-
 type _ReadableStream<T> = typeof globalThis extends {
 	onerror: any;
 	ReadableStream: infer T;
@@ -146,16 +144,6 @@ import type {
 import type { MessagePort } from "worker_threads";
 import type { WebSocket as _WebSocket } from "ws";
 
-declare module "*.txt" {
-	var text: string;
-	export = text;
-}
-
-declare module "*.toml" {
-	var contents: any;
-	export = contents;
-}
-
 declare global {
 	var Bun: typeof import("bun");
 
@@ -1944,10 +1932,10 @@ declare global {
 		readonly main: boolean;
 
 		/** Alias of `import.meta.dir`. Exists for Node.js compatibility */
-		readonly dirname: string;
+		dirname: string;
 
 		/** Alias of `import.meta.path`. Exists for Node.js compatibility */
-		readonly filename: string;
+		filename: string;
 	}
 
 	/**

package/index.d.ts

@@ -20,3 +20,4 @@
 /// <reference path="./sqlite.d.ts" />
 /// <reference path="./wasm.d.ts" />
 /// <reference path="./deprecated.d.ts" />
+/// <reference path="./ambient.d.ts" />

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.1.39-canary.20241209T140550",
+	"version": "1.1.39-canary.20241211T140552",
 	"name": "bun-types",
 	"license": "MIT",
 	"main": "",

package/sqlite.d.ts

@@ -1152,7 +1152,7 @@ declare module "bun:sqlite" {
 	 *
 	 * @since Bun v1.1.14
 	 */
-	interface Changes {
+	export interface Changes {
 		/**
 		 * The number of rows changed by the last `run` or `exec` call.
 		 */