bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/{api/yaml.md → runtime/yaml.mdx}

@@ -1,16 +1,22 @@
-In Bun, YAML is a first-class citizen alongside JSON and TOML.
+---
+title: YAML
+description: Use Bun's built-in support for YAML files through both runtime APIs and bundler integration
+---
 
-Bun provides built-in support for YAML files through both runtime APIs and bundler integration. You can
+In Bun, YAML is a first-class citizen alongside JSON and TOML. You can:
 
 - Parse YAML strings with `Bun.YAML.parse`
-- Stringify JavaScript objects to YAML with `Bun.YAML.stringify`
-- import & require YAML files as modules at runtime (including hot reloading & watch mode support)
-- import & require YAML files in frontend apps via bun's bundler
+- `import` & `require` YAML files as modules at runtime (including hot reloading & watch mode support)
+- `import` & `require` YAML files in frontend apps via bun's bundler
+
+---
 
 ## Conformance
 
 Bun's YAML parser currently passes over 90% of the official YAML test suite. While we're actively working on reaching 100% conformance, the current implementation covers the vast majority of real-world use cases. The parser is written in Zig for optimal performance and is continuously being improved.
 
+---
+
 ## Runtime API
 
 ### `Bun.YAML.parse()`
@@ -105,7 +111,7 @@ const data = Bun.YAML.parse(yaml);
 
 #### Error Handling
 
-`Bun.YAML.parse()` throws an error if the YAML is invalid:
+`Bun.YAML.parse()` throws a `SyntaxError` if the YAML is invalid:
 
 ```ts
 try {
@@ -115,174 +121,7 @@ try {
 }
 ```
 
-### `Bun.YAML.stringify()`
-
-Convert a JavaScript value into a YAML string. The API signature matches `JSON.stringify`:
-
-```ts
-YAML.stringify(value, replacer?, space?)
-```
-
-- `value`: The value to convert to YAML
-- `replacer`: Currently only `null` or `undefined` (function replacers not yet supported)
-- `space`: Number of spaces for indentation (e.g., `2`) or a string to use for indentation. **Without this parameter, outputs flow-style (single-line) YAML**
-
-#### Basic Usage
-
-```ts
-import { YAML } from "bun";
-
-const data = {
-  name: "John Doe",
-  age: 30,
-  hobbies: ["reading", "coding"],
-};
-
-// Without space - outputs flow-style (single-line) YAML
-console.log(YAML.stringify(data));
-// {name: John Doe,age: 30,hobbies: [reading,coding]}
-
-// With space=2 - outputs block-style (multi-line) YAML
-console.log(YAML.stringify(data, null, 2));
-// name: John Doe
-// age: 30
-// hobbies:
-//   - reading
-//   - coding
-```
-
-#### Output Styles
-
-```ts
-const arr = [1, 2, 3];
-
-// Flow style (single-line) - default
-console.log(YAML.stringify(arr));
-// [1,2,3]
-
-// Block style (multi-line) - with indentation
-console.log(YAML.stringify(arr, null, 2));
-// - 1
-// - 2
-// - 3
-```
-
-#### String Quoting
-
-`YAML.stringify()` automatically quotes strings when necessary:
-
-- Strings that would be parsed as YAML keywords (`true`, `false`, `null`, `yes`, `no`, etc.)
-- Strings that would be parsed as numbers
-- Strings containing special characters or escape sequences
-
-```ts
-const examples = {
-  keyword: "true", // Will be quoted: "true"
-  number: "123", // Will be quoted: "123"
-  text: "hello world", // Won't be quoted: hello world
-  empty: "", // Will be quoted: ""
-};
-
-console.log(YAML.stringify(examples, null, 2));
-// keyword: "true"
-// number: "123"
-// text: hello world
-// empty: ""
-```
-
-#### Cycles and References
-
-`YAML.stringify()` automatically detects and handles circular references using YAML anchors and aliases:
-
-```ts
-const obj = { name: "root" };
-obj.self = obj; // Circular reference
-
-const yamlString = YAML.stringify(obj, null, 2);
-console.log(yamlString);
-// &root
-// name: root
-// self:
-//   *root
-
-// Objects with shared references
-const shared = { id: 1 };
-const data = {
-  first: shared,
-  second: shared,
-};
-
-console.log(YAML.stringify(data, null, 2));
-// first:
-//   &first
-//   id: 1
-// second:
-//   *first
-```
-
-#### Special Values
-
-```ts
-// Special numeric values
-console.log(YAML.stringify(Infinity)); // .inf
-console.log(YAML.stringify(-Infinity)); // -.inf
-console.log(YAML.stringify(NaN)); // .nan
-console.log(YAML.stringify(0)); // 0
-console.log(YAML.stringify(-0)); // -0
-
-// null and undefined
-console.log(YAML.stringify(null)); // null
-console.log(YAML.stringify(undefined)); // undefined (returns undefined, not a string)
-
-// Booleans
-console.log(YAML.stringify(true)); // true
-console.log(YAML.stringify(false)); // false
-```
-
-#### Complex Objects
-
-```ts
-const config = {
-  server: {
-    port: 3000,
-    host: "localhost",
-    ssl: {
-      enabled: true,
-      cert: "/path/to/cert.pem",
-      key: "/path/to/key.pem",
-    },
-  },
-  database: {
-    connections: [
-      { name: "primary", host: "db1.example.com" },
-      { name: "replica", host: "db2.example.com" },
-    ],
-  },
-  features: {
-    auth: true,
-    "rate-limit": 100, // Keys with special characters are preserved
-  },
-};
-
-const yamlString = YAML.stringify(config, null, 2);
-console.log(yamlString);
-// server:
-//   port: 3000
-//   host: localhost
-//   ssl:
-//     enabled: true
-//     cert: /path/to/cert.pem
-//     key: /path/to/key.pem
-// database:
-//   connections:
-//     - name: primary
-//       host: db1.example.com
-//     - name: replica
-//       host: db2.example.com
-// features:
-//   auth: true
-//   rate-limit: 100
-```
+---
 
 ## Module Import
 
@@ -290,7 +129,7 @@ console.log(yamlString);
 
 You can import YAML files directly as ES modules. The YAML content is parsed and made available as both default and named exports:
 
-```yaml#config.yaml
+```yaml config.yaml
 database:
   host: localhost
   port: 5432
@@ -308,7 +147,7 @@ features:
 
 #### Default Import
 
-```ts#app.ts
+```ts app.ts icon="/icons/typescript.svg"
 import config from "./config.yaml";
 
 console.log(config.database.host); // "localhost"
@@ -319,7 +158,7 @@ console.log(config.redis.port); // 6379
 
 You can destructure top-level YAML properties as named imports:
 
-```ts
+```ts app.ts icon="/icons/typescript.svg"
 import { database, redis, features } from "./config.yaml";
 
 console.log(database.host); // "localhost"
@@ -329,7 +168,7 @@ console.log(features.auth); // true
 
 Or combine both:
 
-```ts
+```ts app.ts icon="/icons/typescript.svg"
 import config, { database, features } from "./config.yaml";
 
 // Use the full config object
@@ -345,7 +184,7 @@ if (features.rateLimit) {
 
 YAML files can also be required in CommonJS:
 
-```js
+```ts app.ts icon="/icons/typescript.svg"
 const config = require("./config.yaml");
 console.log(config.database.name); // "myapp"
 
@@ -354,44 +193,7 @@ const { database, redis } = require("./config.yaml");
 console.log(database.port); // 5432
 ```
 
-### TypeScript Support
-
-While Bun can import YAML files directly, TypeScript doesn't know the types of your YAML files by default. To add TypeScript support for your YAML imports, create a declaration file with `.d.ts` appended to the YAML filename (e.g., `config.yaml` → `config.yaml.d.ts`):
-
-```yaml#config.yaml
-features: "advanced"
-server:
-  host: localhost
-  port: 3000
-```
-
-```ts#config.yaml.d.ts
-const contents: {
-  features: string;
-  server: {
-    host: string;
-    port: number;
-  };
-};
-
-export = contents;
-```
-
-Now TypeScript will provide proper type checking and auto-completion:
-
-```ts#app.ts
-import config from "./config.yaml";
-
-// TypeScript knows the types!
-config.server.port; // number
-config.server.host; // string
-config.features; // string
-
-// TypeScript will catch errors
-config.server.unknown; // Error: Property 'unknown' does not exist
-```
-
-This approach works for both ES modules and CommonJS, giving you full type safety while Bun continues to handle the actual YAML parsing at runtime.
+---
 
 ## Hot Reloading with YAML
 
@@ -399,7 +201,7 @@ One of the most powerful features of Bun's YAML support is hot reloading. When y
 
 ### Configuration Hot Reloading
 
-```yaml#config.yaml
+```yaml config.yaml
 server:
   port: 3000
   host: localhost
@@ -409,7 +211,7 @@ features:
   verbose: false
 ```
 
-```ts#server.ts
+```ts server.ts icon="/icons/typescript.svg"
 import { server, features } from "./config.yaml";
 
 console.log(`Starting server on ${server.host}:${server.port}`);
@@ -433,7 +235,7 @@ Bun.serve({
 
 Run with hot reloading:
 
-```bash
+```bash terminal icon="terminal"
 bun --hot server.ts
 ```
 
@@ -444,13 +246,15 @@ Now when you modify `config.yaml`, the changes are immediately reflected in your
 - Live debugging with configuration changes
 - Feature flag toggling
 
+---
+
 ## Configuration Management
 
 ### Environment-Based Configuration
 
 YAML excels at managing configuration across different environments:
 
-```yaml#config.yaml
+```yaml config.yaml
 defaults: &defaults
   timeout: 5000
   retries: 3
@@ -489,7 +293,7 @@ production:
     pretty: false
 ```
 
-```ts#app.ts
+```ts app.ts icon="/icons/typescript.svg"
 import configs from "./config.yaml";
 
 const env = process.env.NODE_ENV || "development";
@@ -513,7 +317,7 @@ export default interpolateEnvVars(config);
 
 ### Feature Flags Configuration
 
-```yaml#features.yaml
+```yaml features.yaml
 features:
   newDashboard:
     enabled: true
@@ -533,13 +337,10 @@ features:
     default: auto # auto, light, dark
 ```
 
-```ts#feature-flags.ts
+```ts feature-flags.ts icon="/icons/typescript.svg"
 import { features } from "./features.yaml";
 
-export function isFeatureEnabled(
-  featureName: string,
-  userEmail?: string,
-): boolean {
+export function isFeatureEnabled(featureName: string, userEmail?: string): boolean {
   const feature = features[featureName];
 
   if (!feature?.enabled) {
@@ -572,7 +373,7 @@ if (isFeatureEnabled("newDashboard", user.email)) {
 
 ### Database Configuration
 
-```yaml#database.yaml
+```yaml database.yaml icon="yaml"
 connections:
   primary:
     type: postgres
@@ -608,7 +409,7 @@ seeds:
   directory: ./seeds
 ```
 
-```ts#db.ts
+```ts db.ts icon="/icons/typescript.svg"
 import { connections, migrations } from "./database.yaml";
 import { createConnection } from "./database-driver";
 
@@ -638,7 +439,7 @@ if (parseConfig(migrations).autoRun === "true") {
 
 When you import YAML files in your application and bundle it with Bun, the YAML is parsed at build time and included as a JavaScript module:
 
-```bash
+```bash terminal icon="terminal"
 bun build app.ts --outdir=dist
 ```
 
@@ -652,7 +453,7 @@ This means:
 
 YAML files can be dynamically imported, useful for loading configuration on demand:
 
-```ts#Load configuration based on environment
+```ts Load configuration based on environment
 const env = process.env.NODE_ENV || "development";
 const config = await import(`./configs/${env}.yaml`);
 

package/docs/snippets/cli/add.mdx

@@ -0,0 +1,166 @@
+## CLI Usage
+
+```bash
+bun add <package> <@version>
+```
+
+### Dependency Management
+
+<ParamField path="--production" type="boolean">
+  Don't install devDependencies. Alias: <code>-p</code>
+</ParamField>
+
+<ParamField path="--omit" type="string">
+  Exclude <code>dev</code>, <code>optional</code>, or <code>peer</code> dependencies from install
+</ParamField>
+
+<ParamField path="--global" type="boolean">
+  Install globally. Alias: <code>-g</code>
+</ParamField>
+
+<ParamField path="--dev" type="boolean">
+  Add dependency to <code>devDependencies</code>. Alias: <code>-d</code>
+</ParamField>
+
+<ParamField path="--optional" type="boolean">
+  Add dependency to <code>optionalDependencies</code>
+</ParamField>
+
+<ParamField path="--peer" type="boolean">
+  Add dependency to <code>peerDependencies</code>
+</ParamField>
+
+<ParamField path="--exact" type="boolean">
+  Add the exact version instead of the <code>^</code> range. Alias: <code>-E</code>
+</ParamField>
+
+<ParamField path="--only-missing" type="boolean">
+  Only add dependencies to <code>package.json</code> if they are not already present
+</ParamField>
+
+### Project Files & Lockfiles
+
+<ParamField path="--yarn" type="boolean">
+  Write a <code>yarn.lock</code> file (yarn v1). Alias: <code>-y</code>
+</ParamField>
+
+<ParamField path="--no-save" type="boolean">
+  Don't update <code>package.json</code> or save a lockfile
+</ParamField>
+
+<ParamField path="--save" type="boolean" default="true">
+  Save to <code>package.json</code> (true by default)
+</ParamField>
+
+<ParamField path="--frozen-lockfile" type="boolean">
+  Disallow changes to lockfile
+</ParamField>
+
+<ParamField path="--trust" type="boolean">
+  Add to <code>trustedDependencies</code> in the project's <code>package.json</code> and install the package(s)
+</ParamField>
+
+<ParamField path="--save-text-lockfile" type="boolean">
+  Save a text-based lockfile
+</ParamField>
+
+<ParamField path="--lockfile-only" type="boolean">
+  Generate a lockfile without installing dependencies
+</ParamField>
+
+### Installation Control
+
+<ParamField path="--dry-run" type="boolean">
+  Don't install anything
+</ParamField>
+
+<ParamField path="--force" type="boolean">
+  Always request the latest versions from the registry &amp; reinstall all dependencies. Alias: <code>-f</code>
+</ParamField>
+
+<ParamField path="--no-verify" type="boolean">
+  Skip verifying integrity of newly downloaded packages
+</ParamField>
+
+<ParamField path="--ignore-scripts" type="boolean">
+  Skip lifecycle scripts in the project's <code>package.json</code> (dependency scripts are never run)
+</ParamField>
+
+<ParamField path="--analyze" type="boolean">
+  Recursively analyze &amp; install dependencies of files passed as arguments (using Bun's bundler). Alias:{" "}
+  <code>-a</code>
+</ParamField>
+
+### Network & Registry
+
+<ParamField path="--ca" type="string">
+  Provide a Certificate Authority signing certificate
+</ParamField>
+
+<ParamField path="--cafile" type="string">
+  Same as <code>--ca</code>, but as a file path to the certificate
+</ParamField>
+
+<ParamField path="--registry" type="string">
+  Use a specific registry by default, overriding <code>.npmrc</code>, <code>bunfig.toml</code>, and environment
+  variables
+</ParamField>
+
+<ParamField path="--network-concurrency" type="number" default="48">
+  Maximum number of concurrent network requests (default 48)
+</ParamField>
+
+### Performance &amp; Resource
+
+<ParamField path="--backend" type="string" default="clonefile">
+  Platform-specific optimizations for installing dependencies. Possible values: <code>clonefile</code> (default),{" "}
+  <code>hardlink</code>, <code>symlink</code>, <code>copyfile</code>
+</ParamField>
+
+<ParamField path="--concurrent-scripts" type="number" default="5">
+  Maximum number of concurrent jobs for lifecycle scripts (default 5)
+</ParamField>
+
+### Caching
+
+<ParamField path="--cache-dir" type="string">
+  Store &amp; load cached data from a specific directory path
+</ParamField>
+
+<ParamField path="--no-cache" type="boolean">
+  Ignore manifest cache entirely
+</ParamField>
+
+### Output &amp; Logging
+
+<ParamField path="--silent" type="boolean">
+  Don't log anything
+</ParamField>
+
+<ParamField path="--verbose" type="boolean">
+  Excessively verbose logging
+</ParamField>
+
+<ParamField path="--no-progress" type="boolean">
+  Disable the progress bar
+</ParamField>
+
+<ParamField path="--no-summary" type="boolean">
+  Don't print a summary
+</ParamField>
+
+### Global Configuration &amp; Context
+
+<ParamField path="--config" type="string">
+  Specify path to config file (<code>bunfig.toml</code>). Alias: <code>-c</code>
+</ParamField>
+
+<ParamField path="--cwd" type="string">
+  Set a specific current working directory
+</ParamField>
+
+### Help
+
+<ParamField path="--help" type="boolean">
+  Print this help menu. Alias: <code>-h</code>
+</ParamField>