@fnet/config

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

Using npm:

npm install @fnet/config

Using yarn:

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 the file is not found
      tags: ['production'] // Filter by specific tags in the YAML file
    });

    console.log('Loaded configuration:', config);
  } 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.data); // Outputs the 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'], // Multiple config names
    dir: process.cwd() // Current working directory
  });
  
  configs.forEach(config => console.log(config.file, 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 // No error if file is not found
    });
    
    console.log('Optional configuration loaded:', config);
  } catch (e) {
    console.log('Config file is optional, proceeding without:', e.message);
  }
}

Acknowledgement

While the @fnet/config library does not require explicit acknowledgment of external libraries for basic usage, it leverages @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
    default: <current working directory>
    description: The directories to search within.
  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.
  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 default exported function argument, handling
  configuration file processing.