@fnet/config

The @fnet/config module is a utility designed to simplify the process of managing and accessing configuration files for applications. By focusing on ease of use and flexibility, it helps users retrieve configuration settings from YAML files located in designated directories. It caters to both single and batch processing of configuration files and allows users to work with custom environmental variables seamlessly.

How It Works

The module scans specified directories to locate YAML configuration files that match the provided name(s). Users can specify a default directory, relative paths, or even use the current working directory. Once a configuration is found, the module parses it and optionally updates the system's environmental variables based on the file's content.

Key Features

• Directory Searching: Automatically searches in a sequence of specified directories and relative paths for configuration files.
• YAML Parsing: Processes YAML files and extracts their data for easy access.
• Environmental Variable Integration: Optionally injects configuration settings into the system’s environment variables.
• Batch Processing: Supports handling multiple configuration files at once by accepting arrays of names.
• Tag Filtering: Allows selective processing of YAML content based on specified tags.
• Optional File Presence: Users can specify whether the absence of a configuration file should trigger an error.

Conclusion

The @fnet/config module provides a straightforward way to manage configuration files, making it easier for users to organize and access application settings. With its uncomplicated setup and useful features, it offers a practical solution for managing application configurations without unnecessary complexity.

@fnet/config Developer Guide

Overview

The @fnet/config library simplifies the process of loading and managing configuration files in your applications. It is particularly useful for environments where configurations need to be dynamic and flexible. The library allows developers to effortlessly locate configuration files across specified directories and optionally transfer configuration-defined environment variables to process.env.

Installation

To use @fnet/config in your project, you can install it via npm or yarn with the following commands:

npm install @fnet/config

yarn add @fnet/config

Usage

The library provides a default asynchronous function designed to locate and process configuration files, handling various extensions such as .fnet, .fnet.yaml, and .fnet.yml. Below is a step-by-step guide on how to use the library.

import loadConfig from '@fnet/config';

async function loadMyConfig() {
  try {
    const config = await loadConfig({
      name: 'myConfig',                    // Name of the config file without extension
      dir: ['path/to/config', 'another/path'], // Directories to search
      rel: ['./.fnet/'],                   // Relative paths within directories
      transferEnv: true,                   // Transfer env variables to process.env
      optional: false,                     // Throws error if file not found
      tags: ['production']                 // Filter by specific tags in YAML
    });

    console.log('Configuration file:', config.file);
    console.log('Parsed data:', config.data);
    console.log('Raw content:', config.raw);
  } catch (error) {
    console.error('Error loading configuration:', error);
  }
}

loadMyConfig();

Examples

Below are examples demonstrating typical usage scenarios for @fnet/config.

Example 1: Loading a Single Configuration File

import loadConfig from '@fnet/config';

async function loadSingleConfig() {
  const config = await loadConfig({ name: 'app-config' });
  console.log(config.file);  // Absolute path to the found file
  console.log(config.data);  // Parsed configuration data
}

Example 2: Loading Multiple Configuration Files

import loadConfig from '@fnet/config';

async function loadMultipleConfigs() {
  const configs = await loadConfig({
    name: ['db-config', 'api-config'],
    dir: process.cwd()
  });
  
  configs.forEach(config => {
    console.log('File:', config.file);
    console.log('Data:', config.data);
  });
}

Example 3: Handling Optional Configurations

import loadConfig from '@fnet/config';

async function loadOptionalConfig() {
  try {
    const config = await loadConfig({
      name: 'optional-config',
      optional: true  // Returns null if file not found
    });
    
    if (config) {
      console.log('Configuration loaded:', config.data);
    } else {
      console.log('Configuration file not found');
    }
  } catch (e) {
    console.log('Unexpected error:', e.message);
  }
}

Configuration File Search

The library searches for configuration files in the following order:

1. In specified directories (or process.cwd() if not specified)
2. Through specified relative paths (defaults to ./.fnet/, ../.fnet/, ../../.fnet/, ../../../.fnet/)
3. With supported extensions: .fnet, .fnet.yaml, .fnet.yml

Return Value Structure

The function returns an object (or array of objects) with the following properties:

• file: Absolute path to the found configuration file
• data: Parsed configuration data
• config: Alias for data (deprecated)
• raw: Raw YAML content

Acknowledgement

The @fnet/config library uses @fnet/yaml for parsing YAML files, ensuring efficient and reliable handling of configuration files.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  name:
    oneOf:
      - type: string
      - type: array
        items:
          type: string
    description: The name of the configuration or an array of names.
  dir:
    oneOf:
      - type: string
      - type: array
        items:
          type: string
    description: The directories to search within. If not specified, uses process.cwd()
  rel:
    type: array
    items:
      type: string
    default:
      - ./.fnet/
      - ../.fnet/
      - ../../.fnet/
      - ../../../.fnet/
    description: Relative paths to consider within directories, will be normalized.
  transferEnv:
    type: boolean
    default: true
    description: Whether to transfer 'env' values from the configuration to process.env.
  optional:
    type: boolean
    default: false
    description: Whether the presence of the file is optional. If false, throws an
      error when file isn't found.
  tags:
    type: array
    items:
      type: string
    default: []
    description: An array of tags used for filtering YAML content.
required:
  - name
additionalProperties: false
description: Schema for the configuration file loader input options.

Output Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  file:
    type: string
    description: Absolute path to the found configuration file
  data:
    type: object
    description: Parsed configuration data
  config:
    type: object
    description: Alias for data (deprecated)
    deprecated: true
  raw:
    type: string
    description: Raw YAML content
required:
  - file
  - data
  - config
  - raw
additionalProperties: false
description: Schema for the configuration file loader output format