bun-types 1.1.37-canary.20241124T140524 → 1.1.37-canary.20241125T140601

package/docs/api/file-io.md

@@ -0,0 +1,358 @@
+{% 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.sh/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.sh/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;
+```
+
+## 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.sh");
+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

@@ -0,0 +1,112 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,157 @@
+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
+```