Module: config

This module handles configuration resolution for the YTMP3-JS project.

This module offers a parser and resolver for the configuration file of YTMP3-JS, which can parse both JSON and JS configuration file (support both CommonJS and ES module). You can see the KNOWN_CONFIG_EXTS constant to check the supported configuration file's extension names.

The parseConfig function will parse and optionally resolve the configuration file containing the download options and audio converter options (if defined). Before being resolved, the configuration file will be validated first and will throws a InvalidTypeError if any known configuration options has an invalid type, or throws a UnknownOptionError if there is an unknown option defined within the configuration object (see the KNOWN_OPTIONS).

Since:
  • 1.0.0
Author:
  • Ryuu Mitsuki <https://github.com/mitsuki31>
License:
  • MIT
Source:
Examples

JSON Configuration File (ytmp3-js.json) 

{
  "downloadOptions": {
    "outDir": "/path/to/download/folder",
    "quiet": false,
    "convertAudio": true,
    "converterOptions": {
      "format": "opus",
      "codec": "libopus",
      "channels": 1,
      "deleteOld": true
    }
  }
}

CommonJS Module Configuration File (ytmp3-js.config.cjs) 

module.exports = {
  downloadOptions: {
    outDir: '..',
    convertAudio: false,
    quiet: true
  }
}

ES Module Configuration File (ytmp3-js.config.mjs) 

export default {
  downloadOptions: {
    cwd: process.env.HOME,
    outDir: 'downloads',  // $HOME/downloads
    convertAudio: true
  },
  audioConverterOptions: {
    format: 'mp3',
    codec: 'libmp3lame',
    frequency: 48000,
    bitrate: '128k'
    deleteOld: true
  }
}

Requires

Members

(package, inner, constant) ERR_FORMAT :string

A string representating the format of error message. Can be formatted using util.format() function.

First occurrence of '%s' will be intepreted as error message, the second as the directory name of configuration file, and the third one as the base name of the configuration file.

Type:
  • string
Since:
  • 1.0.0
Default Value:
  • '%s\n\tat \x1b[90m%s\n\x1b[1;91m%s\x1b[0m\n'
Source:

(package, inner, constant) KNOWN_CONFIG_EXTS :Readonly.<Array.<('.js'|'.cjs'|'.mjs'|'.config.js'|'.config.mjs'|'.config.cjs'|'.json')>>

An array containing all known configuration file's extension names.

Deprecation Note:
For extensions such as, .js, .cjs and .mjs, needs to be concatenated with .config to prevent config file lookup confusion in the future. At this time, we won't deleted those extension names until next major update, but please consider to change your configuration file's extension for future compatibility.

Type:
  • Readonly.<Array.<('.js'|'.cjs'|'.mjs'|'.config.js'|'.config.mjs'|'.config.cjs'|'.json')>>
Since:
  • 1.0.0
Source:

(package, inner, constant) KNOWN_OPTIONS :Readonly.<Array.<('downloadOptions'|'audioConverterOptions')>>

An array containing all known configuration options.

Type:
  • Readonly.<Array.<('downloadOptions'|'audioConverterOptions')>>
Since:
  • 1.0.0
Source:

Methods

(package, inner) configChecker(params)

Checks the given configuration for validity.

This function ensures that the configuration object adheres to the expected structure and types. It checks for unknown fields and validates the types of known options. Throws an error if there any known options is not object type or if there are unknown fields defined in the configuration.

Parameters:
Name Type Description
params Object

The parameters for the function.

Properties
Name Type Description
config YTMP3Config

The configuration object to be checked.
file string

The file path from which the config object was sourced, used for error reporting.
Since:
  • 1.0.0
Source:
Throws:

(async, package, inner) findGlobalConfig(YTMP3_HOMEDIRopt) → {Promise.<(string|null)>}

Asynchronously finds and returns the path to the most appropriate global configuration file for the ytmp3-js module.

The function searches for configuration files in the user's home directory (specifically, the ~/.ytmp3-js directory -- for more details, see YTMP3_HOMEDIR) and applies a series of prioritization and validation steps to ensure that the returned file is valid and non-empty.

The function first retrieves a list of configuration files in the specified directory that match a set of known file extensions (KNOWN_CONFIG_EXTS). If exactly one file is found, its basename is returned immediately. If multiple configuration files are present, the function prioritizes specific configuration file names in the following order:

  1. ytmp3-js.config.cjs
  2. ytmp3-js.config.mjs
  3. ytmp3-js.config.js
  4. ytmp3-js.json

If the prioritized file is empty, the function will iterate through other available files until it finds a non-empty file or exhausts the list.

Parameters:
Name Type Attributes Description
YTMP3_HOMEDIR string <optional>

The directory from where to search the global configuration file. Defaults to YTMP3_HOMEDIR.
Since:
  • 1.1.0
Source:
See:
Returns:

A promise fullfills with a string representing the absolute path of the selected configuration file, or null if no global configuration file is found or if the searchDir is not exist and not a directory.

Type
Promise.<(string|null)>

(package, inner) importConfig(filenon-null) → {YTMP3Config|DownloadOptions|Promise.<(YTMP3Config|DownloadOptions)>}

An alias for parseConfig function, with resolve parameter is set to true.

Parameters:
Name Type Description
file string

A string path refers to configuration file to import and resolve.
Since:
  • 1.0.0
Source:
See:
Returns:
Type
YTMP3Config | DownloadOptions | Promise.<(YTMP3Config|DownloadOptions)>

(package, inner) parseConfig(configFilenon-null, resolveopt) → {YTMP3Config|DownloadOptions|Promise.<(YTMP3Config|DownloadOptions)>}

Parses a configuration file and either resolves or validates its contents.

This function can handle both CommonJS and ES module formats for configuration files. When importing an ES module, it returns a Promise that resolves to the configuration object. It also supports optional resolution of the configuration.

Parameters:
Name Type Attributes Default Description
configFile string

A string path refers to the configuration file.
resolve boolean <optional>
 true

Determines whether to resolve the configuration object. If set to false, will validate the configuration only.
Since:
  • 1.0.0
Source:
See:
Throws:

  • If the given configFile is not a string.

    Type
    InvalidTypeError

  • If the file extension is not supported or if an error occurs during import.

    Type
    Error
Returns:

The configuration object or a Promise that fullfilled with the configuration object if an ES module is imported. The returned configuration object will be automatically resolved if resolve is set to true.

Type
YTMP3Config | DownloadOptions | Promise.<(YTMP3Config|DownloadOptions)>
Examples

Synchronously parse a CommonJS configuration file 

const config = parseConfig('./config.js');
console.log(config);

Asynchronously parse an ES module configuration file 

parseConfig('./config.mjs').then((config) => {
  console.log(config);
}).catch((error) => {
  console.error('Failed to load config:', error);
});

(async, package, inner) parseGlobalConfig(globConfigPath, parserOptionsopt) → {Promise.<any>}

Parses the global configuration file at the specified path with optional parser options.

This function validates the type of the configuration file path and parser options, checks if the file is readable, and imports the configuration file. The forceRequire option is enabled if the file extension is .json unless overridden by the provided options.

Parameters:
Name Type Attributes Description
globConfigPath string

The path to the global configuration file. Must be a valid string.
parserOptions Object <optional>

Optional settings for parsing the configuration file.

Properties
Name Type Attributes Description
forceRequire boolean <optional>

If true, forces the use of require() for importing the file, even if it's an ES module.
Since:
  • 1.1.0
Source:
Throws:
Returns:

A promise fullfills with the parsed configuration data.

Type
Promise.<any>

(package, inner) resolveConfig(params) → {DownloadOptions}

Resolves the configuration for YTMP3-JS from a given configuration object.

This function takes a configuration object typically sourced from a config file (e.g., ytmp3-js.config.js) and ensures that it adheres to the expected structure and types. It specifically resolves the download options and the audio converter options, providing fallbacks and handling type checks.

Parameters:
Name Type Description
params Object

The parameters for the function.

Properties
Name Type Description
config YTMP3Config

The configuration object to be resolved.
file string

The file path from which the config object was sourced, used for error reporting.
Since:
  • 1.0.0
Source:
Throws:

If any known options is not object type.

Type
InvalidTypeError
Returns:

The resolved download options and audio converter options if provided.

Type
DownloadOptions