@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.

Developer Guide for @fnet/yaml

Overview

The @fnet/yaml library is designed to enhance YAML processing capabilities by allowing developers to use expressions such as setters and getters directly within YAML keys and values. It supports reading from files, URLs, and even fetching content from npm packages. With these enhancements, developers can manage complex configurations across different environments by manipulating YAML data dynamically.

Installation

To install the @fnet/yaml library, you can use either npm or yarn:

npm install @fnet/yaml

or

yarn add @fnet/yaml

Usage

The library is designed to handle YAML content with special expression tags for dynamic data manipulation. Below is a simple guide on how to use the library to process YAML data.

Example Use Case

Suppose you have a YAML configuration file that needs to pull in information dynamically from different sources like files or URLs. You can use the library to process this YAML content accordingly.

import yamlProcessor from '@fnet/yaml';

(async () => {
    const inputYaml = `
        # Using a setter to update person name
        s::person.name: John Doe

        # Using a getter to include content from another YAML file
        profile: g::file://./additional-profile.yaml

        # Using a tag to conditionally include data
        t::prod::producer:
            name: exampleProd
    `;

    try {
        const { content, parsed } = await yamlProcessor({ content: inputYaml, tags: ['prod'] });
        
        console.log('Processed YAML:');
        console.log(content);

    } catch (error) {
        console.error('Error processing YAML:', error);
    }
})();

Examples

Setting Values with Setters

Setters (e.g., s::) allow you to dynamically set values in your YAML structure.

s::settings.server.host: localhost
s::settings.server.port: 8080

Getting Values with Getters

Getters (e.g., g::) retrieve values, which can include fetching and merging external file content.

config: g::file://./config.yaml
apiData: g::http://api.example.com/data.yaml
npmConfig: g::npm:@fnet/webauth@^0.1/config.yaml

Using Tags

Tags (e.g., t::) conditionally process sections of your YAML based on the environment or context.

t::dev::logLevel: debug
t::prod::logLevel: error

By specifying the tag when processing, you control which sections are included.

Acknowledgement

This library leverages the yaml library for YAML parsing and additional internal and external utilities for expression processing.

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: []