@fnet/yaml
v0.1.28
Published
## Introduction
Downloads
200
Readme
@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: []