From 99786797c7d91d856638b7e265130df9dcdfb22e Mon Sep 17 00:00:00 2001 From: robobun Date: Tue, 23 Sep 2025 16:02:51 -0700 Subject: [PATCH] docs: Add missing YAML.stringify() documentation (#22921) Co-authored-by: Alistair Smith --- docs/api/yaml.md | 172 +++++++++++++++++++++++++++++++++++- packages/bun-types/bun.d.ts | 26 ++++-- 2 files changed, 188 insertions(+), 10 deletions(-) diff --git a/docs/api/yaml.md b/docs/api/yaml.md index 36ee35e070..d6fe44b21c 100644 --- a/docs/api/yaml.md +++ b/docs/api/yaml.md @@ -3,6 +3,7 @@ In Bun, YAML is a first-class citizen alongside JSON and TOML. Bun provides built-in support for YAML files through both runtime APIs and bundler integration. 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 @@ -104,7 +105,7 @@ const data = Bun.YAML.parse(yaml); #### Error Handling -`Bun.YAML.parse()` throws a `SyntaxError` if the YAML is invalid: +`Bun.YAML.parse()` throws an error if the YAML is invalid: ```ts try { @@ -114,6 +115,175 @@ 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 ### ES Modules diff --git a/packages/bun-types/bun.d.ts b/packages/bun-types/bun.d.ts index ae7cd7ca06..89f318c0cc 100644 --- a/packages/bun-types/bun.d.ts +++ b/packages/bun-types/bun.d.ts @@ -636,7 +636,7 @@ declare module "bun" { * import { YAML } from "bun"; * * console.log(YAML.parse("123")) // 123 - * console.log(YAML.parse("123")) // null + * console.log(YAML.parse("null")) // null * console.log(YAML.parse("false")) // false * console.log(YAML.parse("abc")) // "abc" * console.log(YAML.parse("- abc")) // [ "abc" ] @@ -653,7 +653,10 @@ declare module "bun" { * * @param input The JavaScript value to stringify. * @param replacer Currently not supported. - * @param space A number for how many spaces each level of indentation gets, or a string used as indentation. The number is clamped between 0 and 10, and the first 10 characters of the string are used. + * @param space A number for how many spaces each level of indentation gets, or a string used as indentation. + * Without this parameter, outputs flow-style (single-line) YAML. + * With this parameter, outputs block-style (multi-line) YAML. + * The number is clamped between 0 and 10, and the first 10 characters of the string are used. * @returns A string containing the YAML document. * * @example @@ -661,19 +664,24 @@ declare module "bun" { * import { YAML } from "bun"; * * const input = { - * abc: "def" + * abc: "def", + * num: 123 * }; + * + * // Without space - flow style (single-line) * console.log(YAML.stringify(input)); - * // # output + * // {abc: def,num: 123} + * + * // With space - block style (multi-line) + * console.log(YAML.stringify(input, null, 2)); * // abc: def + * // num: 123 * * const cycle = {}; * cycle.obj = cycle; - * console.log(YAML.stringify(cycle)); - * // # output - * // &root - * // obj: - * // *root + * console.log(YAML.stringify(cycle, null, 2)); + * // &1 + * // obj: *1 */ export function stringify(input: unknown, replacer?: undefined | null, space?: string | number): string; }