bun-types 1.1.42 → 1.1.43-canary.20250104T140550

package/docs/api/cc.md

@@ -179,16 +179,16 @@ type Flags = string | string[];
 
 These are flags like `-I` for include directories and `-D` for preprocessor definitions.
 
-#### `defines: Record<string, string>`
+#### `define: Record<string, string>`
 
-The `defines` is an optional object that should be passed to the TinyCC compiler.
+The `define` is an optional object that should be passed to the TinyCC compiler.
 
 ```ts
 type Defines = Record<string, string>;
 
 cc({
   source: "hello.c",
-  defines: {
+  define: {
     "NDEBUG": "1",
   },
 });

package/docs/api/s3.md

@@ -0,0 +1,549 @@
+Production servers often read, upload, and write files to S3-compatible object storage services instead of the local filesystem. Historically, that means local filesystem APIs you use in development can't be used in production. When you use Bun, things are different.
+
+Bun provides fast, native bindings for interacting with S3-compatible object storage services. Bun's S3 API is designed to be simple and feel similar to fetch's `Response` and `Blob` APIs (like Bun's local filesystem APIs).
+
+```ts
+import { s3, write, S3 } from "bun";
+
+const metadata = await s3("123.json", {
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
+});
+
+// Download from S3 as JSON
+const data = await metadata.json();
+
+// Upload to S3
+await write(metadata, JSON.stringify({ name: "John", age: 30 }));
+
+// Presign a URL (synchronous - no network request needed)
+const url = metadata.presign({
+  acl: "public-read",
+  expiresIn: 60 * 60 * 24, // 1 day
+});
+```
+
+S3 is the [de facto standard](https://en.wikipedia.org/wiki/De_facto_standard) internet filesystem. You can use Bun's S3 API with S3-compatible storage services like:
+
+- AWS S3
+- Cloudflare R2
+- DigitalOcean Spaces
+- MinIO
+- Backblaze B2
+- ...and any other S3-compatible storage service
+
+## Basic Usage
+
+There are several ways to interact with Bun's S3 API.
+
+### Using `Bun.s3()`
+
+The `s3()` helper function is used to create one-off `S3File` instances for a single file.
+
+```ts
+import { s3 } from "bun";
+
+// Using the s3() helper
+const s3file = s3("my-file.txt", {
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+  // endpoint: "https://s3.us-east-1.amazonaws.com", // optional
+  // endpoint: "https://<account-id>.r2.cloudflarestorage.com", // Cloudflare R2
+  // endpoint: "https://<region>.digitaloceanspaces.com", // DigitalOcean Spaces
+  // endpoint: "http://localhost:9000", // MinIO
+});
+```
+
+### Reading Files
+
+You can read files from S3 using similar methods to Bun's file system APIs:
+
+```ts
+// Read an S3File as text
+const text = await s3file.text();
+
+// Read an S3File as JSON
+const json = await s3file.json();
+
+// Read an S3File as an ArrayBuffer
+const buffer = await s3file.arrayBuffer();
+
+// Get only the first 1024 bytes
+const partial = await s3file.slice(0, 1024).text();
+
+// Stream the file
+const stream = s3file.stream();
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+## Writing Files
+
+Writing to S3 is just as simple:
+
+```ts
+// Write a string (replacing the file)
+await s3file.write("Hello World!");
+
+// Write with content type
+await s3file.write(JSON.stringify({ name: "John", age: 30 }), {
+  type: "application/json",
+});
+
+// Write using a writer (streaming)
+const writer = s3file.writer({ type: "application/json" });
+writer.write("Hello");
+writer.write(" World!");
+await writer.end();
+
+// Write using Bun.write
+await Bun.write(s3file, "Hello World!");
+```
+
+### Working with large files (streams)
+
+Bun automatically handles multipart uploads for large files and provides streaming capabilities. The same API that works for local files also works for S3 files.
+
+```ts
+// Write a large file
+const bigFile = Buffer.alloc(10 * 1024 * 1024); // 10MB
+const writer = s3file.writer({
+  // Automatically retry on network errors up to 3 times
+  retry: 3,
+
+  // Queue up to 10 requests at a time
+  queueSize: 10,
+
+  // Upload in 5 MB chunks
+  partSize: 5 * 1024 * 1024,
+});
+for (let i = 0; i < 10; i++) {
+  await writer.write(bigFile);
+}
+await writer.end();
+```
+
+## Presigning URLs
+
+When your production service needs to let users upload files to your server, it's often more reliable for the user to upload directly to S3 instead of your server acting as an intermediary.
+
+To facilitate this, you can presign URLs for S3 files. This generates a URL with a signature that allows a user to securely upload that specific file to S3, without exposing your credentials or granting them unnecessary access to your bucket.
+
+```ts
+// Generate a presigned URL that expires in 24 hours (default)
+const url = s3file.presign();
+
+// Custom expiration time (in seconds)
+const url2 = s3file.presign({ expiresIn: 3600 }); // 1 hour
+
+// Using static method
+const url3 = Bun.S3.presign("my-file.txt", {
+  bucket: "my-bucket",
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
+  // endpoint: "https://<account-id>.r2.cloudflarestorage.com", // Cloudflare R2
+  expiresIn: 3600,
+});
+```
+
+### Setting ACLs
+
+To set an ACL (access control list) on a presigned URL, pass the `acl` option:
+
+```ts
+const url = s3file.presign({
+  acl: "public-read",
+  expiresIn: 3600,
+});
+```
+
+You can pass any of the following ACLs:
+
+| ACL                           | Explanation                                                         |
+| ----------------------------- | ------------------------------------------------------------------- |
+| `"public-read"`               | The object is readable by the public.                               |
+| `"private"`                   | The object is readable only by the bucket owner.                    |
+| `"public-read-write"`         | The object is readable and writable by the public.                  |
+| `"authenticated-read"`        | The object is readable by the bucket owner and authenticated users. |
+| `"aws-exec-read"`             | The object is readable by the AWS account that made the request.    |
+| `"bucket-owner-read"`         | The object is readable by the bucket owner.                         |
+| `"bucket-owner-full-control"` | The object is readable and writable by the bucket owner.            |
+| `"log-delivery-write"`        | The object is writable by AWS services used for log delivery.       |
+
+### Expiring URLs
+
+To set an expiration time for a presigned URL, pass the `expiresIn` option.
+
+```ts
+const url = s3file.presign({
+  // Seconds
+  expiresIn: 3600, // 1 hour
+});
+```
+
+### `method`
+
+To set the HTTP method for a presigned URL, pass the `method` option.
+
+```ts
+const url = s3file.presign({
+  method: "PUT",
+  // method: "DELETE",
+  // method: "GET",
+  // method: "HEAD",
+  // method: "POST",
+  // method: "PUT",
+});
+```
+
+### `new Response(S3File)`
+
+To quickly redirect users to a presigned URL for an S3 file, you can pass an `S3File` instance to a `Response` object as the body.
+
+```ts
+const response = new Response(s3file);
+console.log(response);
+```
+
+This will automatically redirect the user to the presigned URL for the S3 file, saving you the memory, time, and bandwidth cost of downloading the file to your server and sending it back to the user.
+
+```ts
+Response (0 KB) {
+  ok: false,
+  url: "",
+  status: 302,
+  statusText: "",
+  headers: Headers {
+    "location": "https://<account-id>.r2.cloudflarestorage.com/...",
+  },
+  redirected: true,
+  bodyUsed: false
+}
+```
+
+## Support for S3-Compatible Services
+
+Bun's S3 implementation works with any S3-compatible storage service. Just specify the appropriate endpoint:
+
+```ts
+import { s3 } from "bun";
+
+// CloudFlare R2
+const r2file = s3("my-file.txt", {
+  accessKeyId: "access-key",
+  secretAccessKey: "secret-key",
+  bucket: "my-bucket",
+  endpoint: "https://<account-id>.r2.cloudflarestorage.com",
+});
+
+// DigitalOcean Spaces
+const spacesFile = s3("my-file.txt", {
+  accessKeyId: "access-key",
+  secretAccessKey: "secret-key",
+  bucket: "my-bucket",
+  endpoint: "https://<region>.digitaloceanspaces.com",
+});
+
+// MinIO
+const minioFile = s3("my-file.txt", {
+  accessKeyId: "access-key",
+  secretAccessKey: "secret-key",
+  bucket: "my-bucket",
+  endpoint: "http://localhost:9000",
+});
+```
+
+## Credentials
+
+Credentials are one of the hardest parts of using S3, and we've tried to make it as easy as possible. By default, Bun reads the following environment variables for credentials.
+
+| Option name       | Environment variable   |
+| ----------------- | ---------------------- |
+| `accessKeyId`     | `S3_ACCESS_KEY_ID`     |
+| `secretAccessKey` | `S3_SECRET_ACCESS_KEY` |
+| `region`          | `S3_REGION`            |
+| `endpoint`        | `S3_ENDPOINT`          |
+| `bucket`          | `S3_BUCKET`            |
+| `sessionToken`    | `S3_SESSION_TOKEN`     |
+
+If the `S3_*` environment variable is not set, Bun will also check for the `AWS_*` environment variable, for each of the above options.
+
+| Option name       | Fallback environment variable |
+| ----------------- | ----------------------------- |
+| `accessKeyId`     | `AWS_ACCESS_KEY_ID`           |
+| `secretAccessKey` | `AWS_SECRET_ACCESS_KEY`       |
+| `region`          | `AWS_REGION`                  |
+| `endpoint`        | `AWS_ENDPOINT`                |
+| `bucket`          | `AWS_BUCKET`                  |
+| `sessionToken`    | `AWS_SESSION_TOKEN`           |
+
+These environment variables are read from [`.env` files](/docs/runtime/env) or from the process environment at initialization time (`process.env` is not used for this).
+
+These defaults are overriden by the options you pass to `s3(credentials)`, `new Bun.S3(credentials)`, or any of the methods that accept credentials. So if, for example, you use the same credentials for different buckets, you can set the credentials once in your `.env` file and then pass `bucket: "my-bucket"` to the `s3()` helper function without having to specify all the credentials again.
+
+### `S3` Buckets
+
+Passing around all of these credentials can be cumbersome. To make it easier, you can create a `S3` bucket instance.
+
+```ts
+import { S3 } from "bun";
+
+const bucket = new S3({
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+  // sessionToken: "..."
+  endpoint: "https://s3.us-east-1.amazonaws.com",
+  // endpoint: "https://<account-id>.r2.cloudflarestorage.com", // Cloudflare R2
+  // endpoint: "http://localhost:9000", // MinIO
+});
+
+// bucket is a function that creates `S3File` instances (lazy)
+const file = bucket("my-file.txt");
+
+// Write to S3
+await file.write("Hello World!");
+
+// Read from S3
+const text = await file.text();
+
+// Write using a Response
+await file.write(new Response("Hello World!"));
+
+// Presign a URL
+const url = file.presign({
+  expiresIn: 60 * 60 * 24, // 1 day
+  acl: "public-read",
+});
+
+// Delete the file
+await file.unlink();
+```
+
+#### Read a file from an `S3` bucket
+
+The `S3` bucket instance is itself a function that creates `S3File` instances. It provides a more convenient API for interacting with S3.
+
+```ts
+const s3file = bucket("my-file.txt");
+const text = await s3file.text();
+const json = await s3file.json();
+const bytes = await s3file.bytes();
+const arrayBuffer = await s3file.arrayBuffer();
+```
+
+#### Write a file to S3
+
+To write a file to the bucket, you can use the `write` method.
+
+```ts
+const bucket = new Bun.S3({
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  endpoint: "https://s3.us-east-1.amazonaws.com",
+  bucket: "my-bucket",
+});
+await bucket.write("my-file.txt", "Hello World!");
+await bucket.write("my-file.txt", new Response("Hello World!"));
+```
+
+You can also call `.write` on the `S3File` instance created by the `S3` bucket instance.
+
+```ts
+const s3file = bucket("my-file.txt");
+await s3file.write("Hello World!", {
+  type: "text/plain",
+});
+await s3file.write(new Response("Hello World!"));
+```
+
+#### Delete a file from S3
+
+To delete a file from the bucket, you can use the `delete` method.
+
+```ts
+const bucket = new Bun.S3({
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+});
+
+await bucket.delete("my-file.txt");
+```
+
+You can also use the `unlink` method, which is an alias for `delete`.
+
+```ts
+// "delete" and "unlink" are aliases of each other.
+await bucket.unlink("my-file.txt");
+```
+
+## `S3File`
+
+`S3File` instances are created by calling the `S3` instance method or the `s3()` helper function. Like `Bun.file()`, `S3File` instances are lazy. They don't refer to something that necessarily exists at the time of creation. That's why all the methods that don't involve network requests are fully synchronous.
+
+```ts
+interface S3File extends Blob {
+  slice(start: number, end?: number): S3File;
+  exists(): Promise<boolean>;
+  unlink(): Promise<void>;
+  presign(options: S3Options): string;
+  text(): Promise<string>;
+  json(): Promise<any>;
+  bytes(): Promise<Uint8Array>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  stream(options: S3Options): ReadableStream;
+  write(
+    data:
+      | string
+      | Uint8Array
+      | ArrayBuffer
+      | Blob
+      | ReadableStream
+      | Response
+      | Request,
+    options?: BlobPropertyBag,
+  ): Promise<void>;
+
+  readonly size: Promise<number>;
+
+  // ... more omitted for brevity
+}
+```
+
+Like `Bun.file()`, `S3File` extends [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob), so all the methods that are available on `Blob` are also available on `S3File`. The same API for reading data from a local file is also available for reading data from S3.
+
+| Method                       | Output           |
+| ---------------------------- | ---------------- |
+| `await s3File.text()`        | `string`         |
+| `await s3File.bytes()`       | `Uint8Array`     |
+| `await s3File.json()`        | `JSON`           |
+| `await s3File.stream()`      | `ReadableStream` |
+| `await s3File.arrayBuffer()` | `ArrayBuffer`    |
+
+That means using `S3File` instances with `fetch()`, `Response`, and other web APIs that accept `Blob` instances just works.
+
+### Partial reads
+
+To read a partial range of a file, you can use the `slice` method.
+
+```ts
+const partial = s3file.slice(0, 1024);
+
+// Read the partial range as a Uint8Array
+const bytes = await partial.bytes();
+
+// Read the partial range as a string
+const text = await partial.text();
+```
+
+Internally, this works by using the HTTP `Range` header to request only the bytes you want. This `slice` method is the same as [`Blob.prototype.slice`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/slice).
+
+## Error codes
+
+When Bun's S3 API throws an error, it will have a `code` property that matches one of the following values:
+
+- `ERR_S3_MISSING_CREDENTIALS`
+- `ERR_S3_INVALID_METHOD`
+- `ERR_S3_INVALID_PATH`
+- `ERR_S3_INVALID_ENDPOINT`
+- `ERR_S3_INVALID_SIGNATURE`
+- `ERR_S3_INVALID_SESSION_TOKEN`
+
+When the S3 Object Storage service returns an error (that is, not Bun), it will be an `S3Error` instance (an `Error` instance with the name `"S3Error"`).
+
+## `S3` static methods
+
+The `S3` class provides several static methods for interacting with S3.
+
+### `S3.presign`
+
+To generate a presigned URL for an S3 file, you can use the `S3.presign` method.
+
+```ts
+import { S3 } from "bun";
+
+const url = S3.presign("my-file.txt", {
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+  expiresIn: 3600,
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
+  // endpoint: "https://<account-id>.r2.cloudflarestorage.com", // Cloudflare R2
+});
+```
+
+This is the same as `S3File.prototype.presign` and `new S3(credentials).presign`, as a static method on the `S3` class.
+
+### `S3.exists`
+
+To check if an S3 file exists, you can use the `S3.exists` method.
+
+```ts
+import { S3 } from "bun";
+
+const exists = await S3.exists("my-file.txt", {
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
+});
+```
+
+The same method also works on `S3File` instances.
+
+```ts
+const s3file = Bun.s3("my-file.txt", {
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+});
+const exists = await s3file.exists();
+```
+
+### `S3.size`
+
+To get the size of an S3 file, you can use the `S3.size` method.
+
+```ts
+import { S3 } from "bun";
+const size = await S3.size("my-file.txt", {
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
+});
+```
+
+### `S3.unlink`
+
+To delete an S3 file, you can use the `S3.unlink` method.
+
+```ts
+import { S3 } from "bun";
+
+await S3.unlink("my-file.txt", {
+  accessKeyId: "your-access-key",
+  secretAccessKey: "your-secret-key",
+  bucket: "my-bucket",
+  // endpoint: "https://s3.us-east-1.amazonaws.com",
+});
+```
+
+## s3:// protocol
+
+To make it easier to use the same code for local files and S3 files, the `s3://` protocol is supported in `fetch` and `Bun.file()`.
+
+```ts
+const response = await fetch("s3://my-bucket/my-file.txt");
+const file = Bun.file("s3://my-bucket/my-file.txt");
+```
+
+This is the equivalent of calling `Bun.s3("my-file.txt", { bucket: "my-bucket" })`.
+
+This `s3://` protocol exists to make it easier to use the same code for local files and S3 files.

package/docs/bundler/html.md

@@ -0,0 +1,110 @@
+As of Bun v1.1.43, Bun's bundler now has first-class support for HTML. Build static sites, landing pages, and web applications with zero configuration. Just point Bun at your HTML file and it handles everything else.
+
+```html#index.html
+<!doctype html>
+<html>
+  <head>
+    <link rel="stylesheet" href="./styles.css" />
+    <script src="./app.ts" type="module"></script>
+  </head>
+  <body>
+    <img src="./logo.png" />
+  </body>
+</html>
+```
+
+One command is all you need (won't be experimental after Bun v1.2):
+
+{% codetabs %}
+
+```bash#CLI
+$ bun build --experimental-html --experimental-css ./index.html --outdir=dist
+```
+
+```ts#API
+Bun.build({
+  entrypoints: ["./index.html"],
+  outdir: "./dist",
+
+  // On by default in Bun v1.2+
+  html: true,
+  experimentalCss: true,
+});
+```
+
+{% /codetabs %}
+
+Bun automatically:
+
+- Bundles, tree-shakes, and optimizes your JavaScript, JSX and TypeScript
+- Bundles and optimizes your CSS
+- Copies & hashes images and other assets
+- Updates all references to local files or packages in your HTML
+
+## Zero Config, Maximum Performance
+
+The HTML bundler is enabled by default after Bun v1.2+. Drop in your existing HTML files and Bun will handle:
+
+- **TypeScript & JSX** - Write modern JavaScript for browsers without the setup
+- **CSS** - Bundle CSS stylesheets directly from `<link rel="stylesheet">` or `@import`
+- **Images & Assets** - Automatic copying & hashing & rewriting of assets in JavaScript, CSS, and HTML
+
+## Watch mode
+
+You can run `bun build --watch` to watch for changes and rebuild automatically.
+
+You've never seen a watch mode this fast.
+
+## Plugin API
+
+Need more control? Configure the bundler through the JavaScript API and use Bun's builtin `HTMLRewriter` to preprocess HTML.
+
+```ts
+await Bun.build({
+  entrypoints: ["./index.html"],
+  outdir: "./dist",
+  html: true,
+  experimentalCss: true,
+  minify: true,
+
+  plugins: [
+    {
+      // A plugin that makes every HTML tag lowercase
+      name: "lowercase-html-plugin",
+      setup({ onLoad }) {
+        const rewriter = new HTMLRewriter().on("*", {
+          element(element) {
+            element.tagName = element.tagName.toLowerCase();
+          },
+          text(element) {
+            element.replace(element.text.toLowerCase());
+          },
+        });
+
+        onLoad({ filter: /\.html$/ }, async args => {
+          const html = await Bun.file(args.path).text();
+
+          return {
+            // Bun's bundler will scan the HTML for <script> tags, <link rel="stylesheet"> tags, and other assets
+            // and bundle them automatically
+            contents: rewriter.transform(html),
+            loader: "html",
+          };
+        });
+      },
+    },
+  ],
+});
+```
+
+## What Gets Processed?
+
+Bun automatically handles all common web assets:
+
+- Scripts (`<script src>`) are run through Bun's JavaScript/TypeScript/JSX bundler
+- Stylesheets (`<link rel="stylesheet">`) are run through Bun's CSS parser & bundler
+- Images (`<img>`, `<picture>`) are copied and hashed
+- Media (`<video>`, `<audio>`, `<source>`) are copied and hashed
+- Any `<link>` tag with an `href` attribute pointing to a local file is rewritten to the new path, and hashed
+
+All paths are resolved relative to your HTML file, making it easy to organize your project however you want.