1.0.0 • Published 10 months ago

config-valley v1.0.0

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

config-valley

ts Download Status Github Star Github Issues NPM version License ci codecov code style: prettier

config-valley is a simple and easy-to-use utility for reading configuration from various sources. When developing CLI utilities, it may be necessary to read configuration from files like package.json or tsconfig.json to enhance user convenience. config-valley allows you to consistently read configuration from various formats, such as JSON, JSONC, JSON5, YAML, and TOML, using DI (Dependency Injection).

  1. Supports JSON, JSONC, JSON5, YAML, and TOML.
  2. Customizable configuration reading through DI.

Enhance the convenience of your CLI utility by using config-valley!

installation

# npm
npm install config-valley --save

# yarn
yarn install config-valley --save

# pnpm
pnpm add config-valley --save

Usage

architecture

config-valley has an architecture as shown in the diagram. It includes the FileHandle class for reading configuration files (including package.json and tsconfig.json), and various implementations of the IParser interface such as JSONParser, JSON5Parser, PackageJsonParser, TsconfigParser, TomlParser, and YamlParser. The ConfigHandle class contains both a FileHandle and an IParser, while the ConfigHandleContainer holds multiple ConfigHandle instances.

When using config-valley, you pass an array of ConfigHandle instances to the ConfigHandleContainer. See the example below:

import pathe from 'pathe';
import { 
  ConfigHandleContainer, 
  ConfigHandle,
  JsonKeyParser,
  PackageJsonParser,
  TsconfigJsonParser
} from 'config-valley';

function getConfigHandle() {
  const filename = 'your configuration file name, for example, .appconfig';
  const keyname = 'key name for extract configuration from package.json or tsconfig.json';

  const handle = new ConfigHandleContainer({
    handles: [
      // extract configuration from config file using keyname
      ConfigHandle.factory(
        new JsonKeyParser(keyname),
        pathe.join(process.cwd(), filename),
      ),
      // read configuration from config file
      ConfigHandle.factory(pathe.join(process.cwd(), filename)),
      // extract configuration from package.json using keyname
      ConfigHandle.factory(
        new PackageJsonParser(keyname),
        pathe.join(process.cwd(), 'package.json'),
      ),
      // extract configuration from tsconfig.json using keyname
      ConfigHandle.factory(
        new TsconfigJsonParser(keyname),
        pathe.join(process.cwd(), 'tsconfig.json'),
      ),
    ]
  });

  return handle;
}

const handle = getConfigHandle();
const config = await handle.read();

// show your configuration
console.log(config);

// change configuration
config.output = 'mytools/dist'

// save your configuration
await container.write(config)

How can I read various configuration formats?

config-valley reads configuration files using various parsers that implement the IParser interface. The FileHandle reads the configuration file, and the IParser implementation parses the read buffer. The ConfigHandle combines these two. The ConfigHandleContainer holds multiple ConfigHandle instances in an array. Finally, the ConfigHandleContainer reads the configuration files sequentially until successful.

Synchronous vs Asynchronous

You can use SyncConfigHandle and SyncConfigHandleContainer, or ConfigHandle and ConfigHandleContainer, depending on your needs. They have the same usage, but the FileHandle and IParser implementations must be developed specifically for synchronous or asynchronous use.

Support formats

config-valley supports JSON, JSONC, JSON5, YAML, and TOML. When reading configuration from package.json or tsconfig.json, you need to extract the configuration from a specific key. This method is also supported for other file formats. In such cases, you can use Json5KeyParser, YamlKeyParser, or TomlKeyParser to extract the configuration by specifying a key in the input file.

function getConfigHandle() {
  const filename = 'your configuration file name, for example, .appconfig';

  const handle = new ConfigHandleContainer({
    handles: [
      ConfigHandle.factory(
        new TomlKeyParser(args?.configKey),
        pathe.join(process.cwd(), filename),
      ),
    ]
  });

  return handle;
}
Class NameUsage
JSONParserThe JSONParser class parses JSON format files.
JSONKeyParserThe JSONKeyParser class parses JSON format files and extracts configuration from a specific key.
JSONCParserThe JSONCParser class parses JSON with Comments format files.
JSONCKeyParserThe JSONCKeyParser class parses JSON with Comments format files and extracts configuration from a specific key.
JSON5ParserThe JSON5Parser class parses JSON5 format files.
JSON5KeyParserThe JSON5KeyParser class parses JSON5 format files and extracts configuration from a specific key.
YamlParserThe YamlParser class parses YAML format files.
YamlKeyParserThe YamlKeyParser class parses YAML format files and extracts configuration from a specific key.
TomlParserThe TomlParser class parses TOML format files.
TomlKeyParserThe TomlKeyParser class parses TOML format files and extracts configuration from a specific key.
PackageJsonParserThe PackageJsonParser class parses package.json files and extracts configuration from a specific key.
TsconfigJsonParserThe TsconfigJsonParser class parses tsconfig.json files and extracts configuration from a specific key.

License

This software is licensed under the MIT.