This package has been deprecated

Author message:

No longer maintained. Please see https://github.com/stencila/configa#readme for why.

@stencila/configa
TypeScript icon, indicating that this package has built-in type declarations

0.4.8 • Public • Published

Configa

Application configuration: DRY, flexible and type-safe. Pick any three.

Build status Code coverage NPM

⚠️ Configa is in early development. It's been factored out of Sparkla, another project in early development, for more general usage.

Install

npm install --save @stencila/configa

Quick start

1. Define a configuration class

Configa uses Typescript classes to define configuration options. Create a file config.ts with a single class defining your application configuration e.g.

import { minimum, maximum } from '@stencila/configa/dist/define'

/**
 * myapp ${version}: ${description}
 */
export class Config {
  /**
   * An option that can be a boolean of a string
   */
  optionA: boolean | string = 'default-value'

  /**
   * An option that is not required but has additional validations
   */
  @minimum(1)
  @maximum(10)
  optionA?: number
}

2. Generate configuration schema

Generate the JSON Schema that will be used at run time to validate and document your application's options:

configa schema

3. Use your configuration in your application code

import { collectConfig, helpUsage } from '@stencila/configa/dist/run'

// App config as Typescript for compile time type-checking
import { Config } from './config'

// App config as JSON Schema for run time type-checking and help generation
import configSchema from './config.schema.json'

// Generate a typed configuration object
const { args = [], config } = collectConfig<Config>('myapp', configSchema)

// Generate help from the JSON Schema
if (args.includes('help')) console.log(helpUsage(configSchema))

4. Generate configuration documentation

In your README.md add comments to indicate where to insert documentation e.g.

<\!-- CONFIGA-TABLE-BEGIN -->
<\!-- CONFIGA-TABLE-END -->

Then run,

configa readme

Usage

All configuration options can be set, in descending order of priority, by:

  • a command line argument e.g. --<value> <value>
  • an environment variable prefixed with CONFIGA_ e.g. CONFIGA_<option>=<value>
  • a .json or .ini configuration file, set using the --config option, or .configarc by default
Name Description Type Validators Default
appName The name of the application.1 string undefined
configPath Path to the configuration file to be parsed.2 string undefined
jsonSchemaPath Path to the JSON Schema file to be generated.3 string undefined
readmePath Path to the README file to be updated. string "README.md"
  1. Determines the expected prefix on the names of config files and environment variables. If undefined then parse the name from the package name in ./package.json.
  2. If undefined, then will search for a file config.ts in the current directory and its subdirectories.
  3. If undefined, then will be the path of the config file with extension .json.schema instead of .ts.

Readme

Keywords

Package Sidebar

Install

npm i @stencila/configa

Weekly Downloads

74

Version

0.4.8

License

Apache-2.0

Unpacked Size

82.1 kB

Total Files

31

Last publish

Collaborators

  • ketch
  • nokome
  • stencila-ci