yaml 2.3.4 → 2.4.0

package/README.md

@@ -33,6 +33,8 @@ npm install yaml
 The API provided by `yaml` has three layers, depending on how deep you need to go: [Parse & Stringify](https://eemeli.org/yaml/#parse-amp-stringify), [Documents](https://eemeli.org/yaml/#documents), and the underlying [Lexer/Parser/Composer](https://eemeli.org/yaml/#parsing-yaml).
 The first has the simplest API and "just works", the second gets you all the bells and whistles supported by the library along with a decent [AST](https://eemeli.org/yaml/#content-nodes), and the third lets you get progressively closer to YAML source, if that's your thing.
 
+A [command-line tool](https://eemeli.org/yaml/#command-line-tool) is also included.
+
 ```js
 import { parse, stringify } from 'yaml'
 // or
@@ -55,26 +57,26 @@ const YAML = require('yaml')
   - [`#directives`](https://eemeli.org/yaml/#stream-directives)
   - [`#errors`](https://eemeli.org/yaml/#errors)
   - [`#warnings`](https://eemeli.org/yaml/#errors)
-- [`isDocument(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
+- [`isDocument(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
 - [`parseAllDocuments(str, options?): Document[]`](https://eemeli.org/yaml/#parsing-documents)
 - [`parseDocument(str, options?): Document`](https://eemeli.org/yaml/#parsing-documents)
 
 ### Content Nodes
 
-- [`isAlias(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
-- [`isCollection(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
-- [`isMap(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
-- [`isNode(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
-- [`isPair(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
-- [`isScalar(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
-- [`isSeq(foo): boolean`](https://eemeli.org/yaml/#identifying-nodes)
+- [`isAlias(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
+- [`isCollection(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
+- [`isMap(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
+- [`isNode(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
+- [`isPair(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
+- [`isScalar(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
+- [`isSeq(foo): boolean`](https://eemeli.org/yaml/#identifying-node-types)
 - [`new Scalar(value)`](https://eemeli.org/yaml/#scalar-values)
 - [`new YAMLMap()`](https://eemeli.org/yaml/#collections)
 - [`new YAMLSeq()`](https://eemeli.org/yaml/#collections)
 - [`doc.createAlias(node, name?): Alias`](https://eemeli.org/yaml/#working-with-anchors)
 - [`doc.createNode(value, options?): Node`](https://eemeli.org/yaml/#creating-nodes)
 - [`doc.createPair(key, value): Pair`](https://eemeli.org/yaml/#creating-nodes)
-- [`visit(node, visitor)`](https://eemeli.org/yaml/#modifying-nodes)
+- [`visit(node, visitor)`](https://eemeli.org/yaml/#finding-and-modifying-nodes)
 
 ### Parsing YAML
 

package/bin.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { UserError, cli, help } from './dist/cli.mjs'
+
+cli(process.stdin, error => {
+  if (error instanceof UserError) {
+    if (error.code === UserError.ARGS) console.error(`${help}\n`)
+    console.error(error.message)
+    process.exitCode = error.code
+  } else if (error) throw error
+})

package/browser/dist/compose/resolve-flow-scalar.js

@@ -189,19 +189,19 @@ function foldNewline(source, offset) {
     return { fold, offset };
 }
 const escapeCodes = {
-    '0': '\0',
-    a: '\x07',
-    b: '\b',
-    e: '\x1b',
-    f: '\f',
-    n: '\n',
-    r: '\r',
-    t: '\t',
-    v: '\v',
-    N: '\u0085',
-    _: '\u00a0',
-    L: '\u2028',
-    P: '\u2029',
+    '0': '\0', // null character
+    a: '\x07', // bell character
+    b: '\b', // backspace
+    e: '\x1b', // escape character
+    f: '\f', // form feed
+    n: '\n', // line feed
+    r: '\r', // carriage return
+    t: '\t', // horizontal tab
+    v: '\v', // vertical tab
+    N: '\u0085', // Unicode next line
+    _: '\u00a0', // Unicode non-breaking space
+    L: '\u2028', // Unicode line separator
+    P: '\u2029', // Unicode paragraph separator
     ' ': ' ',
     '"': '"',
     '/': '/',

package/browser/dist/schema/yaml-1.1/binary.js

@@ -2,7 +2,7 @@ import { Scalar } from '../../nodes/Scalar.js';
 import { stringifyString } from '../../stringify/stringifyString.js';
 
 const binary = {
-    identify: value => value instanceof Uint8Array,
+    identify: value => value instanceof Uint8Array, // Buffer inherits from Uint8Array
     default: false,
     tag: 'tag:yaml.org,2002:binary',
     /**

package/browser/dist/stringify/stringifyCollection.js

@@ -1,4 +1,3 @@
-import { Collection } from '../nodes/Collection.js';
 import { isNode, isPair } from '../nodes/identity.js';
 import { stringify } from './stringify.js';
 import { lineComment, indentComment } from './stringifyComment.js';
@@ -120,7 +119,7 @@ function stringifyFlowCollection({ comment, items }, ctx, { flowChars, itemInden
     else {
         if (!reqNewline) {
             const len = lines.reduce((sum, line) => sum + line.length + 2, 2);
-            reqNewline = len > Collection.maxFlowStringSingleLineLength;
+            reqNewline = ctx.options.lineWidth > 0 && len > ctx.options.lineWidth;
         }
         if (reqNewline) {
             str = start;

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="node" />
+export declare const help = "yaml: A command-line YAML processor and inspector\n\nReads stdin and writes output to stdout and errors & warnings to stderr.\n\nUsage:\n  yaml          Process a YAML stream, outputting it as YAML\n  yaml cst      Parse the CST of a YAML stream\n  yaml lex      Parse the lexical tokens of a YAML stream\n  yaml valid    Validate a YAML stream, returning 0 on success\n\nOptions:\n  --help, -h    Show this message.\n  --json, -j    Output JSON.\n\nAdditional options for bare \"yaml\" command:\n  --doc, -d     Output pretty-printed JS Document objects.\n  --single, -1  Require the input to consist of a single YAML document.\n  --strict, -s  Stop on errors.\n  --visit, -v   Apply a visitor to each document (requires a path to import)\n  --yaml 1.1    Set the YAML version. (default: 1.2)";
+export declare class UserError extends Error {
+    static ARGS: number;
+    static SINGLE: number;
+    code: number;
+    constructor(code: number, message: string);
+}
+export declare function cli(stdin: NodeJS.ReadableStream, done: (error?: Error) => void, argv?: string[]): Promise<void>;

package/dist/cli.mjs

@@ -0,0 +1,195 @@
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { prettyToken } from './parse/cst.js';
+import { Lexer } from './parse/lexer.js';
+import { Parser } from './parse/parser.js';
+import { Composer } from './compose/composer.js';
+import { LineCounter } from './parse/line-counter.js';
+import { prettifyError } from './errors.js';
+import { visit } from './visit.js';
+
+const help = `\
+yaml: A command-line YAML processor and inspector
+
+Reads stdin and writes output to stdout and errors & warnings to stderr.
+
+Usage:
+  yaml          Process a YAML stream, outputting it as YAML
+  yaml cst      Parse the CST of a YAML stream
+  yaml lex      Parse the lexical tokens of a YAML stream
+  yaml valid    Validate a YAML stream, returning 0 on success
+
+Options:
+  --help, -h    Show this message.
+  --json, -j    Output JSON.
+
+Additional options for bare "yaml" command:
+  --doc, -d     Output pretty-printed JS Document objects.
+  --single, -1  Require the input to consist of a single YAML document.
+  --strict, -s  Stop on errors.
+  --visit, -v   Apply a visitor to each document (requires a path to import)
+  --yaml 1.1    Set the YAML version. (default: 1.2)`;
+class UserError extends Error {
+    constructor(code, message) {
+        super(`Error: ${message}`);
+        this.code = code;
+    }
+}
+UserError.ARGS = 2;
+UserError.SINGLE = 3;
+async function cli(stdin, done, argv) {
+    let args;
+    try {
+        args = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                doc: { type: 'boolean', short: 'd' },
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean', short: 'j' },
+                single: { type: 'boolean', short: '1' },
+                strict: { type: 'boolean', short: 's' },
+                visit: { type: 'string', short: 'v' },
+                yaml: { type: 'string', default: '1.2' }
+            }
+        });
+    }
+    catch (error) {
+        return done(new UserError(UserError.ARGS, error.message));
+    }
+    const { positionals: [mode], values: opt } = args;
+    stdin.setEncoding('utf-8');
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+    switch (opt.help || mode) {
+        /* istanbul ignore next */
+        case true: // --help
+            console.log(help);
+            break;
+        case 'lex': {
+            const lexer = new Lexer();
+            const data = [];
+            const add = (tok) => {
+                if (opt.json)
+                    data.push(tok);
+                else
+                    console.log(prettyToken(tok));
+            };
+            stdin.on('data', (chunk) => {
+                for (const tok of lexer.lex(chunk, true))
+                    add(tok);
+            });
+            stdin.on('end', () => {
+                for (const tok of lexer.lex('', false))
+                    add(tok);
+                if (opt.json)
+                    console.log(JSON.stringify(data));
+                done();
+            });
+            break;
+        }
+        case 'cst': {
+            const parser = new Parser();
+            const data = [];
+            const add = (tok) => {
+                if (opt.json)
+                    data.push(tok);
+                else
+                    console.dir(tok, { depth: null });
+            };
+            stdin.on('data', (chunk) => {
+                for (const tok of parser.parse(chunk, true))
+                    add(tok);
+            });
+            stdin.on('end', () => {
+                for (const tok of parser.parse('', false))
+                    add(tok);
+                if (opt.json)
+                    console.log(JSON.stringify(data));
+                done();
+            });
+            break;
+        }
+        case undefined:
+        case 'valid': {
+            const lineCounter = new LineCounter();
+            const parser = new Parser(lineCounter.addNewLine);
+            // @ts-expect-error Version is validated at runtime
+            const composer = new Composer({ version: opt.yaml });
+            const visitor = opt.visit
+                ? (await import(resolve(opt.visit))).default
+                : null;
+            let source = '';
+            let hasDoc = false;
+            let reqDocEnd = false;
+            const data = [];
+            const add = (doc) => {
+                if (hasDoc && opt.single) {
+                    return done(new UserError(UserError.SINGLE, 'Input stream contains multiple documents'));
+                }
+                for (const error of doc.errors) {
+                    prettifyError(source, lineCounter)(error);
+                    if (opt.strict || mode === 'valid')
+                        return done(error);
+                    console.error(error);
+                }
+                for (const warning of doc.warnings) {
+                    prettifyError(source, lineCounter)(warning);
+                    console.error(warning);
+                }
+                if (visitor)
+                    visit(doc, visitor);
+                if (mode === 'valid')
+                    doc.toJS();
+                else if (opt.json)
+                    data.push(doc);
+                else if (opt.doc) {
+                    Object.defineProperties(doc, {
+                        options: { enumerable: false },
+                        schema: { enumerable: false }
+                    });
+                    console.dir(doc, { depth: null });
+                }
+                else {
+                    if (reqDocEnd)
+                        console.log('...');
+                    try {
+                        const str = String(doc);
+                        console.log(str.endsWith('\n') ? str.slice(0, -1) : str);
+                    }
+                    catch (error) {
+                        done(error);
+                    }
+                }
+                hasDoc = true;
+                reqDocEnd = !doc.directives?.docEnd;
+            };
+            stdin.on('data', (chunk) => {
+                source += chunk;
+                for (const tok of parser.parse(chunk, true)) {
+                    for (const doc of composer.next(tok))
+                        add(doc);
+                }
+            });
+            stdin.on('end', () => {
+                for (const tok of parser.parse('', false)) {
+                    for (const doc of composer.next(tok))
+                        add(doc);
+                }
+                for (const doc of composer.end(false))
+                    add(doc);
+                if (opt.single && !hasDoc) {
+                    return done(new UserError(UserError.SINGLE, 'Input stream contained no documents'));
+                }
+                if (mode !== 'valid' && opt.json) {
+                    console.log(JSON.stringify(opt.single ? data[0] : data));
+                }
+                done();
+            });
+            break;
+        }
+        default:
+            done(new UserError(UserError.ARGS, `Unknown command: ${JSON.stringify(mode)}`));
+    }
+}
+
+export { UserError, cli, help };

package/dist/compose/resolve-flow-scalar.js

@@ -191,19 +191,19 @@ function foldNewline(source, offset) {
     return { fold, offset };
 }
 const escapeCodes = {
-    '0': '\0',
-    a: '\x07',
-    b: '\b',
-    e: '\x1b',
-    f: '\f',
-    n: '\n',
-    r: '\r',
-    t: '\t',
-    v: '\v',
-    N: '\u0085',
-    _: '\u00a0',
-    L: '\u2028',
-    P: '\u2029',
+    '0': '\0', // null character
+    a: '\x07', // bell character
+    b: '\b', // backspace
+    e: '\x1b', // escape character
+    f: '\f', // form feed
+    n: '\n', // line feed
+    r: '\r', // carriage return
+    t: '\t', // horizontal tab
+    v: '\v', // vertical tab
+    N: '\u0085', // Unicode next line
+    _: '\u00a0', // Unicode non-breaking space
+    L: '\u2028', // Unicode line separator
+    P: '\u2029', // Unicode paragraph separator
     ' ': ' ',
     '"': '"',
     '/': '/',

package/dist/nodes/Pair.d.ts

@@ -5,7 +5,7 @@ import type { StringifyContext } from '../stringify/stringify.js';
 import { addPairToJSMap } from './addPairToJSMap.js';
 import { NODE_TYPE } from './identity.js';
 import type { ToJSContext } from './toJS.js';
-export declare function createPair(key: unknown, value: unknown, ctx: CreateNodeContext): Pair<import("./Node.js").Node, import("./YAMLMap.js").YAMLMap<unknown, unknown> | import("./Scalar.js").Scalar<unknown> | import("./Alias.js").Alias | import("./YAMLSeq.js").YAMLSeq<unknown>>;
+export declare function createPair(key: unknown, value: unknown, ctx: CreateNodeContext): Pair<import("./Node.js").Node, import("./Alias.js").Alias | import("./Scalar.js").Scalar<unknown> | import("./YAMLMap.js").YAMLMap<unknown, unknown> | import("./YAMLSeq.js").YAMLSeq<unknown>>;
 export declare class Pair<K = unknown, V = unknown> {
     readonly [NODE_TYPE]: symbol;
     /** Always Node or null when parsed, but can be set to anything. */

package/dist/parse/cst.d.ts

@@ -99,7 +99,7 @@ export declare const SCALAR = "\u001F";
 /** @returns `true` if `token` is a flow or block collection */
 export declare const isCollection: (token: Token | null | undefined) => token is BlockMap | BlockSequence | FlowCollection;
 /** @returns `true` if `token` is a flow or block scalar; not an alias */
-export declare const isScalar: (token: Token | null | undefined) => token is BlockScalar | FlowScalar;
+export declare const isScalar: (token: Token | null | undefined) => token is FlowScalar | BlockScalar;
 /** Get a printable representation of a lexer token */
 export declare function prettyToken(token: string): string;
 /** Identify the type of a lexer token. May return `null` for unknown tokens. */

package/dist/schema/yaml-1.1/binary.js

@@ -4,7 +4,7 @@ var Scalar = require('../../nodes/Scalar.js');
 var stringifyString = require('../../stringify/stringifyString.js');
 
 const binary = {
-    identify: value => value instanceof Uint8Array,
+    identify: value => value instanceof Uint8Array, // Buffer inherits from Uint8Array
     default: false,
     tag: 'tag:yaml.org,2002:binary',
     /**

package/dist/stringify/stringifyCollection.js

@@ -1,6 +1,5 @@
 'use strict';
 
-var Collection = require('../nodes/Collection.js');
 var identity = require('../nodes/identity.js');
 var stringify = require('./stringify.js');
 var stringifyComment = require('./stringifyComment.js');
@@ -122,7 +121,7 @@ function stringifyFlowCollection({ comment, items }, ctx, { flowChars, itemInden
     else {
         if (!reqNewline) {
             const len = lines.reduce((sum, line) => sum + line.length + 2, 2);
-            reqNewline = len > Collection.Collection.maxFlowStringSingleLineLength;
+            reqNewline = ctx.options.lineWidth > 0 && len > ctx.options.lineWidth;
         }
         if (reqNewline) {
             str = start;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "license": "ISC",
   "author": "Eemeli Aro <eemeli@gmail.com>",
   "repository": "github:eemeli/yaml",
@@ -18,6 +18,7 @@
   ],
   "type": "commonjs",
   "main": "./dist/index.js",
+  "bin": "./bin.mjs",
   "browser": {
     "./dist/index.js": "./browser/index.js",
     "./dist/util.js": "./browser/dist/util.js",
@@ -52,7 +53,9 @@
     "test:dist:types": "tsc --allowJs --moduleResolution node --noEmit --target es5 dist/index.js",
     "test:types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
     "docs:install": "cd docs-slate && bundle install",
+    "predocs:deploy": "node docs/prepare-docs.mjs",
     "docs:deploy": "cd docs-slate && ./deploy.sh",
+    "predocs": "node docs/prepare-docs.mjs",
     "docs": "cd docs-slate && bundle exec middleman server",
     "preversion": "npm test && npm run build",
     "prepublishOnly": "npm run clean && npm test && npm run build"
@@ -66,17 +69,17 @@
   },
   "devDependencies": {
     "@babel/core": "^7.12.10",
-    "@babel/plugin-proposal-class-properties": "^7.12.1",
-    "@babel/plugin-proposal-nullish-coalescing-operator": "^7.12.1",
+    "@babel/plugin-transform-class-properties": "^7.23.3",
+    "@babel/plugin-transform-nullish-coalescing-operator": "^7.23.4",
     "@babel/plugin-transform-typescript": "^7.12.17",
     "@babel/preset-env": "^7.12.11",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-replace": "^5.0.2",
     "@rollup/plugin-typescript": "^11.0.0",
     "@types/jest": "^29.2.4",
-    "@types/node": "^14.18.35",
-    "@typescript-eslint/eslint-plugin": "^6.4.1",
-    "@typescript-eslint/parser": "^6.4.1",
+    "@types/node": "^20.11.20",
+    "@typescript-eslint/eslint-plugin": "^7.0.2",
+    "@typescript-eslint/parser": "^7.0.2",
     "babel-jest": "^29.0.1",
     "cross-env": "^7.0.3",
     "eslint": "^8.2.0",
@@ -85,7 +88,7 @@
     "jest": "^29.0.1",
     "jest-ts-webcompat-resolver": "^1.0.0",
     "prettier": "^3.0.2",
-    "rollup": "^3.7.5",
+    "rollup": "^4.12.0",
     "tslib": "^2.1.0",
     "typescript": "^5.0.3"
   },