bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/api/file-io.md

@@ -1,366 +0,0 @@
-{% callout %}
-
-<!-- **Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. Existing Node.js projects may use Bun's [nearly complete](https://bun.com/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module. -->
-
-**Note** — The `Bun.file` and `Bun.write` APIs documented on this page are heavily optimized and represent the recommended way to perform file-system tasks using Bun. For operations that are not yet available with `Bun.file`, such as `mkdir` or `readdir`, you can use Bun's [nearly complete](https://bun.com/docs/runtime/nodejs-apis#node-fs) implementation of the [`node:fs`](https://nodejs.org/api/fs.html) module.
-
-{% /callout %}
-
-Bun provides a set of optimized APIs for reading and writing files.
-
-## Reading files (`Bun.file()`)
-
-`Bun.file(path): BunFile`
-
-Create a `BunFile` instance with the `Bun.file(path)` function. A `BunFile` represents a lazily-loaded file; initializing it does not actually read the file from disk.
-
-```ts
-const foo = Bun.file("foo.txt"); // relative to cwd
-foo.size; // number of bytes
-foo.type; // MIME type
-```
-
-The reference conforms to the [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) interface, so the contents can be read in various formats.
-
-```ts
-const foo = Bun.file("foo.txt");
-
-await foo.text(); // contents as a string
-await foo.stream(); // contents as ReadableStream
-await foo.arrayBuffer(); // contents as ArrayBuffer
-await foo.bytes(); // contents as Uint8Array
-```
-
-File references can also be created using numerical [file descriptors](https://en.wikipedia.org/wiki/File_descriptor) or `file://` URLs.
-
-```ts
-Bun.file(1234);
-Bun.file(new URL(import.meta.url)); // reference to the current file
-```
-
-A `BunFile` can point to a location on disk where a file does not exist.
-
-```ts
-const notreal = Bun.file("notreal.txt");
-notreal.size; // 0
-notreal.type; // "text/plain;charset=utf-8"
-const exists = await notreal.exists(); // false
-```
-
-The default MIME type is `text/plain;charset=utf-8`, but it can be overridden by passing a second argument to `Bun.file`.
-
-```ts
-const notreal = Bun.file("notreal.json", { type: "application/json" });
-notreal.type; // => "application/json;charset=utf-8"
-```
-
-For convenience, Bun exposes `stdin`, `stdout` and `stderr` as instances of `BunFile`.
-
-```ts
-Bun.stdin; // readonly
-Bun.stdout;
-Bun.stderr;
-```
-
-### Deleting files (`file.delete()`)
-
-You can delete a file by calling the `.delete()` function.
-
-```ts
-await Bun.file("logs.json").delete();
-```
-
-## Writing files (`Bun.write()`)
-
-`Bun.write(destination, data): Promise<number>`
-
-The `Bun.write` function is a multi-tool for writing payloads of all kinds to disk.
-
-The first argument is the `destination` which can have any of the following types:
-
-- `string`: A path to a location on the file system. Use the `"path"` module to manipulate paths.
-- `URL`: A `file://` descriptor.
-- `BunFile`: A file reference.
-
-The second argument is the data to be written. It can be any of the following:
-
-- `string`
-- `Blob` (including `BunFile`)
-- `ArrayBuffer` or `SharedArrayBuffer`
-- `TypedArray` (`Uint8Array`, et. al.)
-- `Response`
-
-All possible permutations are handled using the fastest available system calls on the current platform.
-
-{% details summary="See syscalls" %}
-
-{% table %}
-
-- Output
-- Input
-- System call
-- Platform
-
----
-
-- file
-- file
-- copy_file_range
-- Linux
-
----
-
-- file
-- pipe
-- sendfile
-- Linux
-
----
-
-- pipe
-- pipe
-- splice
-- Linux
-
----
-
-- terminal
-- file
-- sendfile
-- Linux
-
----
-
-- terminal
-- terminal
-- sendfile
-- Linux
-
----
-
-- socket
-- file or pipe
-- sendfile (if http, not https)
-- Linux
-
----
-
-- file (doesn't exist)
-- file (path)
-- clonefile
-- macOS
-
----
-
-- file (exists)
-- file
-- fcopyfile
-- macOS
-
----
-
-- file
-- Blob or string
-- write
-- macOS
-
----
-
-- file
-- Blob or string
-- write
-- Linux
-
-{% /table %}
-
-{% /details %}
-
-To write a string to disk:
-
-```ts
-const data = `It was the best of times, it was the worst of times.`;
-await Bun.write("output.txt", data);
-```
-
-To copy a file to another location on disk:
-
-```js
-const input = Bun.file("input.txt");
-const output = Bun.file("output.txt"); // doesn't exist yet!
-await Bun.write(output, input);
-```
-
-To write a byte array to disk:
-
-```ts
-const encoder = new TextEncoder();
-const data = encoder.encode("datadatadata"); // Uint8Array
-await Bun.write("output.txt", data);
-```
-
-To write a file to `stdout`:
-
-```ts
-const input = Bun.file("input.txt");
-await Bun.write(Bun.stdout, input);
-```
-
-To write the body of an HTTP response to disk:
-
-```ts
-const response = await fetch("https://bun.com");
-await Bun.write("index.html", response);
-```
-
-## Incremental writing with `FileSink`
-
-Bun provides a native incremental file writing API called `FileSink`. To retrieve a `FileSink` instance from a `BunFile`:
-
-```ts
-const file = Bun.file("output.txt");
-const writer = file.writer();
-```
-
-To incrementally write to the file, call `.write()`.
-
-```ts
-const file = Bun.file("output.txt");
-const writer = file.writer();
-
-writer.write("it was the best of times\n");
-writer.write("it was the worst of times\n");
-```
-
-These chunks will be buffered internally. To flush the buffer to disk, use `.flush()`. This returns the number of flushed bytes.
-
-```ts
-writer.flush(); // write buffer to disk
-```
-
-The buffer will also auto-flush when the `FileSink`'s _high water mark_ is reached; that is, when its internal buffer is full. This value can be configured.
-
-```ts
-const file = Bun.file("output.txt");
-const writer = file.writer({ highWaterMark: 1024 * 1024 }); // 1MB
-```
-
-To flush the buffer and close the file:
-
-```ts
-writer.end();
-```
-
-Note that, by default, the `bun` process will stay alive until this `FileSink` is explicitly closed with `.end()`. To opt out of this behavior, you can "unref" the instance.
-
-```ts
-writer.unref();
-
-// to "re-ref" it later
-writer.ref();
-```
-
-## Directories
-
-Bun's implementation of `node:fs` is fast, and we haven't implemented a Bun-specific API for reading directories just yet. For now, you should use `node:fs` for working with directories in Bun.
-
-### Reading directories (readdir)
-
-To read a directory in Bun, use `readdir` from `node:fs`.
-
-```ts
-import { readdir } from "node:fs/promises";
-
-// read all the files in the current directory
-const files = await readdir(import.meta.dir);
-```
-
-#### Reading directories recursively
-
-To recursively read a directory in Bun, use `readdir` with `recursive: true`.
-
-```ts
-import { readdir } from "node:fs/promises";
-
-// read all the files in the current directory, recursively
-const files = await readdir("../", { recursive: true });
-```
-
-### Creating directories (mkdir)
-
-To recursively create a directory, use `mkdir` in `node:fs`:
-
-```ts
-import { mkdir } from "node:fs/promises";
-
-await mkdir("path/to/dir", { recursive: true });
-```
-
-## Benchmarks
-
-The following is a 3-line implementation of the Linux `cat` command.
-
-```ts#cat.ts
-// Usage
-// $ bun ./cat.ts ./path-to-file
-
-import { resolve } from "path";
-
-const path = resolve(process.argv.at(-1));
-await Bun.write(Bun.stdout, Bun.file(path));
-```
-
-To run the file:
-
-```bash
-$ bun ./cat.ts ./path-to-file
-```
-
-It runs 2x faster than GNU `cat` for large files on Linux.
-
-{% image src="/images/cat.jpg" /%}
-
-## Reference
-
-```ts
-interface Bun {
-  stdin: BunFile;
-  stdout: BunFile;
-  stderr: BunFile;
-
-  file(path: string | number | URL, options?: { type?: string }): BunFile;
-
-  write(
-    destination: string | number | BunFile | URL,
-    input:
-      | string
-      | Blob
-      | ArrayBuffer
-      | SharedArrayBuffer
-      | TypedArray
-      | Response,
-  ): Promise<number>;
-}
-
-interface BunFile {
-  readonly size: number;
-  readonly type: string;
-
-  text(): Promise<string>;
-  stream(): ReadableStream;
-  arrayBuffer(): Promise<ArrayBuffer>;
-  json(): Promise<any>;
-  writer(params: { highWaterMark?: number }): FileSink;
-  exists(): Promise<boolean>;
-}
-
-export interface FileSink {
-  write(
-    chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
-  ): number;
-  flush(): number | Promise<number>;
-  end(error?: Error): number | Promise<number>;
-  start(options?: { highWaterMark?: number }): void;
-  ref(): void;
-  unref(): void;
-}
-```

package/docs/api/file-system-router.md

@@ -1,112 +0,0 @@
-Bun provides a fast API for resolving routes against file-system paths. This API is primarily intended for library authors. At the moment only Next.js-style file-system routing is supported, but other styles may be added in the future.
-
-## Next.js-style
-
-The `FileSystemRouter` class can resolve routes against a `pages` directory. (The Next.js 13 `app` directory is not yet supported.) Consider the following `pages` directory:
-
-```txt
-pages
-├── index.tsx
-├── settings.tsx
-├── blog
-│   ├── [slug].tsx
-│   └── index.tsx
-└── [[...catchall]].tsx
-```
-
-The `FileSystemRouter` can be used to resolve routes against this directory:
-
-```ts
-const router = new Bun.FileSystemRouter({
-  style: "nextjs",
-  dir: "./pages",
-  origin: "https://mydomain.com",
-  assetPrefix: "_next/static/"
-});
-router.match("/");
-
-// =>
-{
-  filePath: "/path/to/pages/index.tsx",
-  kind: "exact",
-  name: "/",
-  pathname: "/",
-  src: "https://mydomain.com/_next/static/pages/index.tsx"
-}
-```
-
-Query parameters will be parsed and returned in the `query` property.
-
-```ts
-router.match("/settings?foo=bar");
-
-// =>
-{
-  filePath: "/Users/colinmcd94/Documents/bun/fun/pages/settings.tsx",
-  kind: "dynamic",
-  name: "/settings",
-  pathname: "/settings?foo=bar",
-  src: "https://mydomain.com/_next/static/pages/settings.tsx",
-  query: {
-    foo: "bar"
-  }
-}
-```
-
-The router will automatically parse URL parameters and return them in the `params` property:
-
-```ts
-router.match("/blog/my-cool-post");
-
-// =>
-{
-  filePath: "/Users/colinmcd94/Documents/bun/fun/pages/blog/[slug].tsx",
-  kind: "dynamic",
-  name: "/blog/[slug]",
-  pathname: "/blog/my-cool-post",
-  src: "https://mydomain.com/_next/static/pages/blog/[slug].tsx",
-  params: {
-    slug: "my-cool-post"
-  }
-}
-```
-
-The `.match()` method also accepts `Request` and `Response` objects. The `url` property will be used to resolve the route.
-
-```ts
-router.match(new Request("https://example.com/blog/my-cool-post"));
-```
-
-The router will read the directory contents on initialization. To re-scan the files, use the `.reload()` method.
-
-```ts
-router.reload();
-```
-
-## Reference
-
-```ts
-interface Bun {
-  class FileSystemRouter {
-    constructor(params: {
-      dir: string;
-      style: "nextjs";
-      origin?: string;
-      assetPrefix?: string;
-      fileExtensions?: string[];
-    });
-
-    reload(): void;
-
-    match(path: string | Request | Response): {
-      filePath: string;
-      kind: "exact" | "catch-all" | "optional-catch-all" | "dynamic";
-      name: string;
-      pathname: string;
-      src: string;
-      params?: Record<string, string>;
-      query?: Record<string, string>;
-    } | null
-  }
-}
-```

package/docs/api/file.md

@@ -1,19 +0,0 @@
-Bun.js has fast paths for common use cases that make Web APIs live up to the performance demands of servers and CLIs.
-
-`Bun.file(path)` returns a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) that represents a lazily-loaded file.
-
-When you pass a file blob to `Bun.write`, Bun automatically uses a faster system call:
-
-```js
-const blob = Bun.file("input.txt");
-await Bun.write("output.txt", blob);
-```
-
-On Linux, this uses the [`copy_file_range`](https://man7.org/linux/man-pages/man2/copy_file_range.2.html) syscall and on macOS, this becomes `clonefile` (or [`fcopyfile`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/copyfile.3.html)).
-
-`Bun.write` also supports [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects. It automatically converts to a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob).
-
-```js
-// Eventually, this will stream the response to disk but today it buffers
-await Bun.write("index.html", await fetch("https://example.com"));
-```

package/docs/api/glob.md

@@ -1,178 +0,0 @@
-Bun includes a fast native implementation of file globbing.
-
-## Quickstart
-
-**Scan a directory for files matching `*.ts`**:
-
-```ts
-import { Glob } from "bun";
-
-const glob = new Glob("**/*.ts");
-
-// Scans the current working directory and each of its sub-directories recursively
-for await (const file of glob.scan(".")) {
-  console.log(file); // => "index.ts"
-}
-```
-
-**Match a string against a glob pattern**:
-
-```ts
-import { Glob } from "bun";
-
-const glob = new Glob("*.ts");
-
-glob.match("index.ts"); // => true
-glob.match("index.js"); // => false
-```
-
-`Glob` is a class which implements the following interface:
-
-```ts
-class Glob {
-  scan(root: string | ScanOptions): AsyncIterable<string>;
-  scanSync(root: string | ScanOptions): Iterable<string>;
-
-  match(path: string): boolean;
-}
-
-interface ScanOptions {
-  /**
-   * The root directory to start matching from. Defaults to `process.cwd()`
-   */
-  cwd?: string;
-
-  /**
-   * Allow patterns to match entries that begin with a period (`.`).
-   *
-   * @default false
-   */
-  dot?: boolean;
-
-  /**
-   * Return the absolute path for entries.
-   *
-   * @default false
-   */
-  absolute?: boolean;
-
-  /**
-   * Indicates whether to traverse descendants of symbolic link directories.
-   *
-   * @default false
-   */
-  followSymlinks?: boolean;
-
-  /**
-   * Throw an error when symbolic link is broken
-   *
-   * @default false
-   */
-  throwErrorOnBrokenSymlink?: boolean;
-
-  /**
-   * Return only files.
-   *
-   * @default true
-   */
-  onlyFiles?: boolean;
-}
-```
-
-## Supported Glob Patterns
-
-Bun supports the following glob patterns:
-
-### `?` - Match any single character
-
-```ts
-const glob = new Glob("???.ts");
-glob.match("foo.ts"); // => true
-glob.match("foobar.ts"); // => false
-```
-
-### `*` - Matches zero or more characters, except for path separators (`/` or `\`)
-
-```ts
-const glob = new Glob("*.ts");
-glob.match("index.ts"); // => true
-glob.match("src/index.ts"); // => false
-```
-
-### `**` - Match any number of characters including `/`
-
-```ts
-const glob = new Glob("**/*.ts");
-glob.match("index.ts"); // => true
-glob.match("src/index.ts"); // => true
-glob.match("src/index.js"); // => false
-```
-
-### `[ab]` - Matches one of the characters contained in the brackets, as well as character ranges
-
-```ts
-const glob = new Glob("ba[rz].ts");
-glob.match("bar.ts"); // => true
-glob.match("baz.ts"); // => true
-glob.match("bat.ts"); // => false
-```
-
-You can use character ranges (e.g `[0-9]`, `[a-z]`) as well as the negation operators `^` or `!` to match anything _except_ the characters contained within the braces (e.g `[^ab]`, `[!a-z]`)
-
-```ts
-const glob = new Glob("ba[a-z][0-9][^4-9].ts");
-glob.match("bar01.ts"); // => true
-glob.match("baz83.ts"); // => true
-glob.match("bat22.ts"); // => true
-glob.match("bat24.ts"); // => false
-glob.match("ba0a8.ts"); // => false
-```
-
-### `{a,b,c}` - Match any of the given patterns
-
-```ts
-const glob = new Glob("{a,b,c}.ts");
-glob.match("a.ts"); // => true
-glob.match("b.ts"); // => true
-glob.match("c.ts"); // => true
-glob.match("d.ts"); // => false
-```
-
-These match patterns can be deeply nested (up to 10 levels), and contain any of the wildcards from above.
-
-### `!` - Negates the result at the start of a pattern
-
-```ts
-const glob = new Glob("!index.ts");
-glob.match("index.ts"); // => false
-glob.match("foo.ts"); // => true
-```
-
-### `\` - Escapes any of the special characters above
-
-```ts
-const glob = new Glob("\\!index.ts");
-glob.match("!index.ts"); // => true
-glob.match("index.ts"); // => false
-```
-
-## Node.js `fs.glob()` compatibility
-
-Bun also implements Node.js's `fs.glob()` functions with additional features:
-
-```ts
-import { glob, globSync, promises } from "node:fs";
-
-// Array of patterns
-const files = await promises.glob(["**/*.ts", "**/*.js"]);
-
-// Exclude patterns
-const filtered = await promises.glob("**/*", {
-  exclude: ["node_modules/**", "*.test.*"],
-});
-```
-
-All three functions (`fs.glob()`, `fs.globSync()`, `fs.promises.glob()`) support:
-
-- Array of patterns as the first argument
-- `exclude` option to filter results