bun-types 1.1.37-canary.20241123T140655 → 1.1.37-canary.20241125T140601

package/docs/guides/install/jfrog-artifactory.md

@@ -0,0 +1,28 @@
+---
+name: Using bun install with Artifactory
+---
+
+[JFrog Artifactory](https://jfrog.com/artifactory/) is a package management system for npm, Docker, Maven, NuGet, Ruby, Helm, and more. It allows you to host your own private npm registry, npm packages, and other types of packages as well.
+
+To use it with `bun install`, add a `bunfig.toml` file to your project with the following contents:
+
+---
+
+### Configure with bunfig.toml
+
+Make sure to replace `MY_SUBDOMAIN` with your JFrog Artifactory subdomain, such as `jarred1234` and MY_TOKEN with your JFrog Artifactory token.
+
+```toml#bunfig.toml
+[install.registry]
+url = "https://MY_SUBDOMAIN.jfrog.io/artifactory/api/npm/npm/_auth=MY_TOKEN"
+# Bun v1.0.3+ supports using an environment variable here
+# url = "$NPM_CONFIG_REGISTRY"
+```
+
+---
+
+### Configure with `$NPM_CONFIG_REGISTRY`
+
+Like with npm, you can use the `NPM_CONFIG_REGISTRY` environment variable to configure JFrog Artifactory with bun install.
+
+---

package/docs/guides/install/npm-alias.md

@@ -0,0 +1,23 @@
+---
+name: Install a package under a different name
+---
+
+To install an npm package under an alias:
+
+```sh
+$ bun add my-custom-name@npm:zod
+```
+
+---
+
+The `zod` package can now be imported as `my-custom-name`.
+
+```ts
+import { z } from "my-custom-name";
+
+z.string();
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/registry-scope.md

@@ -0,0 +1,36 @@
+---
+name: Configure a private registry for an organization scope with bun install
+---
+
+Bun does not read `.npmrc` files; instead private registries are configured via `bunfig.toml`. To configure a registry for a particular npm scope:
+
+```toml#bunfig.toml
+[install.scopes]
+# as a string
+"@myorg1" = "https://username:password@registry.myorg.com/"
+
+# as an object with username/password
+# you can reference environment variables
+"@myorg2" = {
+  username = "myusername",
+  password = "$npm_pass",
+  url = "https://registry.myorg.com/"
+}
+
+# as an object with token
+"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
+
+```
+
+---
+
+Your `bunfig.toml` can reference environment variables. Bun automatically loads environment variables from `.env.local`, `.env.[NODE_ENV]`, and `.env`. See [Docs > Environment variables](https://bun.sh/docs/runtime/env) for more information.
+
+```toml#bunfig.toml
+[install.scopes]
+"@myorg3" = { token = "$npm_token", url = "https://registry.myorg.com/" }
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/trusted.md

@@ -0,0 +1,48 @@
+---
+name: Add a trusted dependency
+---
+
+Unlike other npm clients, Bun does not execute arbitrary lifecycle scripts for installed dependencies, such as `postinstall` and `node-gyp` builds. These scripts represent a potential security risk, as they can execute arbitrary code on your machine.
+
+{% callout %}
+Bun includes a default allowlist of popular packages containing `postinstall` scripts that are known to be safe. You can see this list [here](https://github.com/oven-sh/bun/blob/main/src/install/default-trusted-dependencies.txt).
+{% /callout %}
+
+---
+
+If you are seeing one of the following errors, you are probably trying to use a package that uses `postinstall` to work properly:
+
+- `error: could not determine executable to run for package`
+- `InvalidExe`
+
+---
+
+To allow Bun to execute lifecycle scripts for a specific package, add the package to `trustedDependencies` in your package.json file. You can do this automatically by running the command `bun pm trust <pkg>`.
+
+{% callout %}
+Note that this only allows lifecycle scripts for the specific package listed in `trustedDependencies`, _not_ the dependencies of that dependency!
+{% /callout %}
+
+<!-- Bun maintains an allow-list of popular packages containing `postinstall` scripts that are known to be safe. To run lifecycle scripts for packages that aren't on this list, add the package to `trustedDependencies` in your package.json. -->
+
+```json-diff
+  {
+    "name": "my-app",
+    "version": "1.0.0",
++   "trustedDependencies": ["my-trusted-package"]
+  }
+```
+
+---
+
+Once this is added, run a fresh install. Bun will re-install your dependencies and properly install
+
+```sh
+$ rm -rf node_modules
+$ rm bun.lockb
+$ bun install
+```
+
+---
+
+See [Docs > Package manager > Trusted dependencies](https://bun.sh/docs/install/lifecycle) for complete documentation of trusted dependencies.

package/docs/guides/install/workspaces.md

@@ -0,0 +1,70 @@
+---
+name: Configuring a monorepo using workspaces
+---
+
+Bun's package manager supports npm `"workspaces"`. This allows you to split a codebase into multiple distinct "packages" that live in the same repository, can depend on each other, and (when possible) share a `node_modules` directory.
+
+Clone [this sample project](https://github.com/colinhacks/bun-workspaces) to experiment with workspaces.
+
+---
+
+The root `package.json` should not contain any `"dependencies"`, `"devDependencies"`, etc. Each individual package should be self-contained and declare its own dependencies. Similarly, it's conventional to declare `"private": true` to avoid accidentally publishing the root package to `npm`.
+
+```json#package.json
+{
+  "name": "my-monorepo",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ]
+}
+```
+
+---
+
+It's common to place all packages in a `packages` directory. The `"workspaces"` field in package.json supports glob patterns, so you can use `packages/*` to indicate that each subdirectory of `packages` should be considered separate _package_ (also known as a workspace).
+
+```txt
+.
+├── package.json
+├── node_modules
+└── packages
+    ├── stuff-a
+    │   └── package.json
+    └── stuff-b
+        └── package.json
+```
+
+---
+
+To add dependencies between workspaces, use the `"workspace:*"` syntax. Here we're adding `stuff-a` as a dependency of `stuff-b`.
+
+```json-diff#packages/stuff-b/package.json
+{
+  "name": "stuff-b",
+  "dependencies": {
++   "stuff-a": "workspace:*"
+  }
+}
+```
+
+---
+
+Once added, run `bun install` from the project root to install dependencies for all workspaces.
+
+```sh
+$ bun install
+```
+
+---
+
+To add npm dependencies to a particular workspace, just `cd` to the appropriate directory and run `bun add` commands as you would normally. Bun will detect that you are in a workspace and hoist the dependency as needed.
+
+```sh
+$ cd packages/stuff-a
+$ bun add zod
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/install/yarnlock.md

@@ -0,0 +1,42 @@
+---
+name: Generate a human-readable lockfile
+---
+
+By default Bun generates a binary `bun.lockb` file when you run `bun install`. In some cases, it's preferable to generate a human-readable lockfile instead.
+
+---
+
+Use the `--yarn` flag to generate a Yarn-compatible `yarn.lock` file (in addition to `bun.lockb`).
+
+```sh
+$ bun install --yarn
+```
+
+---
+
+To set this as the default behavior, add the following to your `bunfig.toml` file.
+
+```toml#bunfig.toml
+[install.lockfile]
+print = "yarn"
+```
+
+---
+
+To print a Yarn lockfile to your console without writing it to disk, just "run" your `bun.lockb` with `bun`.
+
+```sh
+$ bun bun.lockb
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+# bun ./bun.lockb --hash: 9BFBF11D86084AAB-9418b03ff880c569-390CE6459EACEC9A...
+
+abab@^2.0.6:
+  version "2.0.6"
+  resolved "https://registry.npmjs.org/abab/-/abab-2.0.6.tgz"
+  integrity sha512-j2afSsaIENvHZN2B8GOpF566vZ5WVk5opAiMTvWgaQT8DkbOqsTfvNAvH...
+```
+
+---
+
+See [Docs > Package manager](https://bun.sh/docs/cli/install) for complete documentation of Bun's package manager.

package/docs/guides/process/argv.md

@@ -0,0 +1,57 @@
+---
+name: Parse command-line arguments
+---
+
+The _argument vector_ is the list of arguments passed to the program when it is run. It is available as `Bun.argv`.
+
+```ts#cli.ts
+console.log(Bun.argv);
+```
+
+---
+
+Running this file with arguments results in the following:
+
+```sh
+$ bun run cli.ts --flag1 --flag2 value
+[ '/path/to/bun', '/path/to/cli.ts', '--flag1', '--flag2', 'value' ]
+```
+
+---
+
+To parse `argv` into a more useful format, `util.parseArgs` would be helpful.
+
+Example:
+
+```ts#cli.ts
+import { parseArgs } from "util";
+
+const { values, positionals } = parseArgs({
+  args: Bun.argv,
+  options: {
+    flag1: {
+      type: 'boolean',
+    },
+    flag2: {
+      type: 'string',
+    },
+  },
+  strict: true,
+  allowPositionals: true,
+});
+
+console.log(values);
+console.log(positionals);
+```
+
+then it outputs
+
+```
+$ bun run cli.ts --flag1 --flag2 value
+{
+  flag1: true,
+  flag2: "value",
+}
+[ "/path/to/bun", "/path/to/cli.ts" ]
+```
+

package/docs/guides/process/ctrl-c.md

@@ -0,0 +1,16 @@
+---
+name: Listen for CTRL+C
+---
+
+The `ctrl+c` shortcut sends an _interrupt signal_ to the running process. This signal can be intercepted by listening for the `SIGINT` event. If you want to close the process, you must explicitly call `process.exit()`.
+
+```ts
+process.on("SIGINT", () => {
+  console.log("Ctrl-C was pressed");
+  process.exit();
+});
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/process/ipc.md

@@ -0,0 +1,66 @@
+---
+name: Spawn a child process and communicate using IPC
+---
+
+Use [`Bun.spawn()`](https://bun.sh/docs/api/spawn) to spawn a child process. When spawning a second `bun` process, you can open a direct inter-process communication (IPC) channel between the two processes.
+
+{%callout%}
+**Note** — This API is only compatible with other `bun` processes. Use `process.execPath` to get a path to the currently running `bun` executable.
+{%/callout%}
+
+```ts#parent.ts
+const child = Bun.spawn(["bun", "child.ts"], {
+  ipc(message) {
+    /**
+     * The message received from the sub process
+     **/
+  },
+});
+```
+
+---
+
+The parent process can send messages to the subprocess using the `.send()` method on the returned `Subprocess` instance. A reference to the sending subprocess is also available as the second argument in the `ipc` handler.
+
+```ts#parent.ts
+const childProc = Bun.spawn(["bun", "child.ts"], {
+  ipc(message, childProc) {
+    /**
+     * The message received from the sub process
+     **/
+    childProc.send("Respond to child")
+  },
+});
+
+childProc.send("I am your father"); // The parent can send messages to the child as well
+```
+
+---
+
+Meanwhile the child process can send messages to its parent using with `process.send()` and receive messages with `process.on("message")`. This is the same API used for `child_process.fork()` in Node.js.
+
+```ts#child.ts
+process.send("Hello from child as string");
+process.send({ message: "Hello from child as object" });
+
+process.on("message", (message) => {
+  // print message from parent
+  console.log(message);
+});
+```
+
+---
+
+All messages are serialized using the JSC `serialize` API, which allows for the same set of [transferrable types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) supported by `postMessage` and `structuredClone`, including strings, typed arrays, streams, and objects.
+
+```ts#child.ts
+// send a string
+process.send("Hello from child as string");
+
+// send an object
+process.send({ message: "Hello from child as object" });
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.sh/docs/api/spawn) for complete documentation.

package/docs/guides/process/nanoseconds.md

@@ -0,0 +1,13 @@
+---
+name: Get the process uptime in nanoseconds
+---
+
+Use `Bun.nanoseconds()` to get the total number of nanoseconds the `bun` process has been alive.
+
+```ts
+Bun.nanoseconds();
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/process/os-signals.md

@@ -0,0 +1,39 @@
+---
+name: Listen to OS signals
+---
+
+Bun supports the Node.js `process` global, including the `process.on()` method for listening to OS signals.
+
+```ts
+process.on("SIGINT", () => {
+  console.log("Received SIGINT");
+});
+```
+
+---
+
+If you don't know which signal to listen for, you listen to the umbrella `"exit"` event.
+
+```ts
+process.on("exit", code => {
+  console.log(`Process exited with code ${code}`);
+});
+```
+
+---
+
+If you don't know which signal to listen for, you listen to the [`"beforeExit"`](https://nodejs.org/api/process.html#event-beforeexit) and [`"exit"`](https://nodejs.org/api/process.html#event-exit) events.
+
+```ts
+process.on("beforeExit", code => {
+  console.log(`Event loop is empty!`);
+});
+
+process.on("exit", code => {
+  console.log(`Process is exiting with code ${code}`);
+});
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/process/spawn-stderr.md

@@ -0,0 +1,31 @@
+---
+name: Read stderr from a child process
+---
+
+When using [`Bun.spawn()`](https://bun.sh/docs/api/spawn), the child process inherits the `stderr` of the spawning process. If instead you'd prefer to read and handle `stderr`, set the `stderr` option to `"pipe"`.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"], {
+  stderr: "pipe",
+});
+proc.stderr; // => ReadableStream
+```
+
+---
+
+To read `stderr` until the child process exits, use the [`Bun.readableStreamToText()`](https://bun.sh/docs/api/utils#bun-readablestreamto) convenience function.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"], {
+  stderr: "pipe",
+});
+
+const errors: string = await Bun.readableStreamToText(proc.stderr);
+if (errors) {
+  // handle errors
+}
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.sh/docs/api/spawn) for complete documentation.

package/docs/guides/process/spawn-stdout.md

@@ -0,0 +1,26 @@
+---
+name: Read stdout from a child process
+---
+
+When using [`Bun.spawn()`](https://bun.sh/docs/api/spawn), the `stdout` of the child process can be consumed as a `ReadableStream` via `proc.stdout`.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"]);
+
+const output = await new Response(proc.stdout).text();
+output; // => "hello"
+```
+
+---
+
+To instead pipe the `stdout` of the child process to `stdout` of the parent process, set "inherit".
+
+```ts
+const proc = Bun.spawn(["echo", "hello"], {
+  stdout: "inherit",
+});
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.sh/docs/api/spawn) for complete documentation.

package/docs/guides/process/spawn.md

@@ -0,0 +1,41 @@
+---
+name: Spawn a child process
+---
+
+Use [`Bun.spawn()`](https://bun.sh/docs/api/spawn) to spawn a child process.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"]);
+
+// await completion
+await proc.exited;
+```
+
+---
+
+The second argument accepts a configuration object.
+
+```ts
+const proc = Bun.spawn(["echo", "Hello, world!"], {
+  cwd: "/tmp",
+  env: { FOO: "bar" },
+  onExit(proc, exitCode, signalCode, error) {
+    // exit handler
+  },
+});
+```
+
+---
+
+By default, the `stdout` of the child process can be consumed as a `ReadableStream` using `proc.stdout`.
+
+```ts
+const proc = Bun.spawn(["echo", "hello"]);
+
+const output = await new Response(proc.stdout).text();
+output; // => "hello"
+```
+
+---
+
+See [Docs > API > Child processes](https://bun.sh/docs/api/spawn) for complete documentation.

package/docs/guides/process/stdin.md

@@ -0,0 +1,54 @@
+---
+name: Read from stdin
+---
+
+For CLI tools, it's often useful to read from `stdin`. In Bun, the `console` object is an `AsyncIterable` that yields lines from `stdin`.
+
+```ts#index.ts
+const prompt = "Type something: ";
+process.stdout.write(prompt);
+for await (const line of console) {
+  console.log(`You typed: ${line}`);
+  process.stdout.write(prompt);
+}
+```
+
+---
+
+Running this file results in a never-ending interactive prompt that echoes whatever the user types.
+
+```sh
+$ bun run index.ts
+Type something: hello
+You typed: hello
+Type something: hello again
+You typed: hello again
+```
+
+---
+
+Bun also exposes stdin as a `BunFile` via `Bun.stdin`. This is useful for incrementally reading large inputs that are piped into the `bun` process.
+
+There is no guarantee that the chunks will be split line-by-line.
+
+```ts#stdin.ts
+for await (const chunk of Bun.stdin.stream()) {
+  // chunk is Uint8Array
+  // this converts it to text (assumes ASCII encoding)
+  const chunkText = Buffer.from(chunk).toString();
+  console.log(`Chunk: ${chunkText}`);
+}
+```
+
+---
+
+This will print the input that is piped into the `bun` process.
+
+```sh
+$ echo "hello" | bun run stdin.ts
+Chunk: hello
+```
+
+---
+
+See [Docs > API > Utils](https://bun.sh/docs/api/utils) for more useful utilities.

package/docs/guides/read-file/arraybuffer.md

@@ -0,0 +1,28 @@
+---
+name: Read a file to an ArrayBuffer
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.arrayBuffer()` to read the file as an `ArrayBuffer`.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const buffer = await file.arrayBuffer();
+```
+
+---
+
+The binary content in the `ArrayBuffer` can then be read as a typed array, such as `Int8Array`. For `Uint8Array`, use [`.bytes()`](./uint8array).
+
+```ts
+const buffer = await file.arrayBuffer();
+const bytes = new Int8Array(buffer);
+
+bytes[0];
+bytes.length;
+```
+
+---
+
+Refer to the [Typed arrays](https://bun.sh/docs/api/binary-data#typedarray) docs for more information on working with typed arrays in Bun.

package/docs/guides/read-file/buffer.md

@@ -0,0 +1,19 @@
+---
+name: Read a file to a Buffer
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats.
+
+To read the file into a `Buffer` instance, first use `.arrayBuffer()` to consume the file as an `ArrayBuffer`, then use `Buffer.from()` to create a `Buffer` from the `ArrayBuffer`.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const arrbuf = await file.arrayBuffer();
+const buffer = Buffer.from(arrbuf);
+```
+
+---
+
+Refer to [Binary data > Buffer](https://bun.sh/docs/api/binary-data#buffer) for more information on working with `Buffer` and other binary data formats in Bun.

package/docs/guides/read-file/exists.md

@@ -0,0 +1,16 @@
+---
+name: Check if a file exists
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. Use the `.exists()` method to check if a file exists at the given path.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+await file.exists(); // boolean;
+```
+
+---
+
+Refer to [API > File I/O](https://bun.sh/docs/api/file-io) for more information on working with `BunFile`.

package/docs/guides/read-file/json.md

@@ -0,0 +1,17 @@
+---
+name: Read a JSON file
+---
+
+The `Bun.file()` function accepts a path and returns a `BunFile` instance. The `BunFile` class extends `Blob` and allows you to lazily read the file in a variety of formats. Use `.json()` to read and parse the contents of a `.json` file as a plain object.
+
+The MIME type of the `BunFile` will be set accordingly.
+
+```ts
+const path = "/path/to/package.json";
+const file = Bun.file(path);
+
+const contents = await file.json();
+// { name: "my-package" }
+
+file.type; // => "application/json;charset=utf-8";
+```