node-yq

Node.js wrapper for yq, a lightweight and portable command-line YAML processor.

Installation

npm install node-yq

During installation, the corresponding yq binary file will be automatically downloaded to the project's bin directory.

Supported Platforms

• macOS (darwin) - x64, arm64
• Linux - x64, arm64
• Windows - x64

Usage

Basic Usage

const yq = require('node-yq');

// Synchronous execution
const result = yq.execSync(['e', '.name', 'config.yaml']);
console.log(result);

// Asynchronous execution
yq.exec(['e', '.name', 'config.yaml'])
  .then(result => {
    console.log(result);
  })
  .catch(error => {
    console.error(error);
  });

Methods

execSync(args, options)

• Parameters:
  • args: yq command arguments array
  • options: optional execution options, passed to child_process.execSync
• Returns: command execution result string

exec(args, options)

• Parameters:
  • args: yq command arguments array
  • options: optional execution options, passed to child_process.spawn
• Returns: Promise, resolves to command execution result string

parse(filePath, options)

• Parameters:
  • filePath: YAML file path
  • options: optional execution options
• Returns: Promise, resolves to parsed YAML string

toJson(filePath, options)

• Parameters:
  • filePath: YAML file path
  • options: optional execution options
• Returns: Promise, resolves to converted JSON string

extract(filePath, expression, options)

• Parameters:
  • filePath: YAML file path
  • expression: yq expression for extracting fields
  • options: optional execution options
• Returns: Promise, resolves to extracted field value

update(filePath, expression, value, options)

• Parameters:
  • filePath: YAML file path
  • expression: yq expression for specifying the field to update
  • value: new value to set
  • options: optional execution options
• Returns: Promise, resolves to command execution result

getYqPath()

• Returns: path to yq binary file

checkYqInstalled()

• Returns: boolean indicating if yq is installed

Examples

Parsing YAML Files

const yq = require('node-yq');

yq.parse('config.yaml')
  .then(result => {
    console.log(result);
  })
  .catch(error => {
    console.error(error);
  });

Converting YAML to JSON

const yq = require('node-yq');

yq.toJson('config.yaml')
  .then(result => {
    console.log(JSON.parse(result));
  })
  .catch(error => {
    console.error(error);
  });

Extracting Specific Fields

const yq = require('node-yq');

yq.extract('config.yaml', '.database.url')
  .then(result => {
    console.log(result);
  })
  .catch(error => {
    console.error(error);
  });

Updating Fields in YAML Files

const yq = require('node-yq');

yq.update('config.yaml', '.database.port', '3306')
  .then(() => {
    console.log('Successfully updated database port');
  })
  .catch(error => {
    console.error(error);
  });

Notes

• This library automatically downloads yq binary files during installation, so network connection is required.
• The default supported yq version is 4.35.1.
• You can specify the yq version to install via the YQ_VERSION environment variable, for example:

  YQ_VERSION=4.35.0 npm install node-yq

• This library is a wrapper around the yq command-line tool, so usage is consistent with the yq command-line tool.

License

MIT