@fnet/yaml v0.1.25

@fnet/yaml

Introduction

The @fnet/yaml project is designed to extend the capabilities of YAML processing by introducing expressions that modify YAML data through setters, getters, and tags. This tool allows users to dynamically manage YAML files by setting values, retrieving content, and applying contextual processing based on tags. It's particularly useful for scenarios where YAML configurations need to be managed in a flexible and organized manner, accommodating both local and remote resources.

How It Works

@fnet/yaml works by parsing YAML content and then applying specific processing rules defined by expressions embedded in the keys and values. Users can define "setters" to modify hierarchical structures, "getters" to retrieve data from different sources like files or URLs, and "tags" to conditionally process entries based on the environment or user-defined labels. The tool can handle both inline YAML content and external YAML files.

Key Features

• Setters (s::): Modify YAML content by specifying paths using dot notation, allowing structured adjustments to nested data.
• Getters (g::): Retrieve and integrate content from external sources, such as local files, HTTP URLs, or npm packages, directly into the YAML structure.
• Tags (t::): Implement conditional logic by selectively processing parts of the YAML based on tag expressions.
• File and URL Handling: Access and merge YAML content from local files, HTTP(s) endpoints, and package repositories.
• Path Resolution: Supports relative and absolute paths for accessing nested YAML data.

Conclusion

@fnet/yaml offers a practical approach for users who need to manage YAML configurations with enhanced flexibility and power. It is a straightforward solution for handling complex YAML processing tasks, such as merging configurations from various sources and applying dynamic modifications with ease.

@fnet/yaml Developer Guide

Overview

@fnet/yaml is a Node.js library designed to process YAML documents with extended features such as the ability to use expressions that allow for dynamic path setting (setter) and value getting (getter), as well as optional tag processing. The library provides a convenient way to manage YAML configurations, making dynamic assignments and external data inclusions straightforward.

Installation

You can install the @fnet/yaml library using npm or yarn by running one of the following commands:

# Using npm
npm install @fnet/yaml

# Using yarn
yarn add @fnet/yaml

Usage

The primary use of @fnet/yaml is to process YAML content by replacing placeholders with actual data sourced from various locations such as local files, HTTP URLs, or even npm packages. The library supports expressions for setting and getting values dynamically, as well as filtering parts of the configuration using tags.

Basic Example

Here's a basic example illustrating how to use @fnet/yaml to process a YAML file with setters, getters, and tags:

import processYaml from '@fnet/yaml';

async function main() {
  const result = await processYaml({
    file: 'path/to/your/config.yaml', // Path to the YAML file
    tags: ['dev'], // Optional tags to filter what parts of the config are processed
  });

  console.log(result.parsed); // Outputs the processed YAML in JSON format
  console.log(result.content); // Outputs the processed YAML as a string
}

main();

Examples

Example: Using Setters and Getters

Imagine you want to manage a configuration file with dynamic values:

config.yaml:

s::person.name: John Doe
age: 30
address:
  g::file://./extra-details.yaml

extra-details.yaml:

street: 123 Main St
city: Sampleville

JavaScript Usage:

import processYaml from '@fnet/yaml';

async function main() {
  const result = await processYaml({
    file: 'config.yaml',
  });

  console.log(result.parsed);
  // Output:
  // {
  //   person: { name: 'John Doe' },
  //   age: 30,
  //   address: { street: '123 Main St', city: 'Sampleville' }
  // }
}

main();

Example: Fetching Data from URLs

The library supports fetching YAML data from HTTP URLs and merging it into your configuration.

config.yaml:

data:
  g::http://example.com/data.yaml

JavaScript Usage:

import processYaml from '@fnet/yaml';

async function main() {
  const result = await processYaml({
    file: 'config.yaml',
  });

  console.log(result.parsed);
  // Outputs the configuration with external data included
}

main();

Acknowledgement

@fnet/yaml utilizes the yaml library for YAML parsing and stringification, and it may internally leverage axios for HTTP requests. Special thanks to all the contributors who have helped in developing these robust tools.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  content:
    type: string
    description: The YAML content to be processed.
  file:
    type: string
    description: The path to the YAML file to be processed.
  tags:
    type: array
    items:
      type: string
    description: Optional array of tags to filter by.
  cwd:
    type: string
    description: Current working directory, default is the process's current working
      directory.
required: []