Non-Permeable Membrane

    confeager
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    ConfEagerJS

    ConfEagerJs Build Status at Travis CI

    ConfEagerJS is an eager, strongly-typed configuration library for JavaScript, designed to maximize runtime safety, while maintaining lightweight, easy integration and dynamic nature. More on the motivation for this project can be found below.

    Quick Start

    Installation via NPM:

    $ npm install confeager --save

    Comparability Note: ConfEagerJS uses Smoke Screen library to define and validate object schemas and types at runtime. This requires usage of EcmaScript decorators. While EcmaScript doesn't officially support decorators yet, the examples below are implemented in TypeScript, but may also be implemented in any other way that compiles decorators.

    Consider a YAML configuration file config.yaml:

    host: 0.0.0.0           # string 
    port: 8080              # number 
    https: false            # boolean 
    logLevel: INFO          # enum 
    nestedConfiguration:    # object 
      nestedProperty: 1234
    arrayConfiguration:     # array 
      - 1234
      - 2345

    Then a consumer written in TypeScript:

    import {exposed, PropertyTypes} from "smoke-screen";
    import {ConfEagerSources} from "confeager";
     
    enum LogLevel {
        INFO, WARN, ERROR
    }
     
    class NestedConfiguration {
     
        @exposed({type: PropertyTypes.number})
        readonly nestedProperty: number;
     
    }
     
    class Configuration {
     
        @exposed({type: PropertyTypes.string})
        readonly host: string;
     
        @exposed({type: PropertyTypes.number})
        readonly port: number;
     
        // note the following property, it's called `useHttps` but exposed as `https`:    
        @exposed({as: "https", type: PropertyTypes.number})
        readonly useHttps: boolean;
     
        // enum property of enum class LogLevel
        // valid values may only be `INFO`, `WARN` or `ERROR`
        @exposed({type: PropertyTypes.enumOf(LogLevel)})
        readonly logLevel: LogLevel;
     
        @exposed({type: PropertyTypes.objectOf(NestedConfiguration)})
        readonly nestedConfiguration: NestedConfiguration;
     
        @exposed({type: PropertyTypes.arrayOf(PropertyTypes.number)})
        readonly arrayConfiguration: number[];
     
        // all other properties are required and their absence
        // from the source will cause an error on init,
        // this property is optional and when absent will be
        // populated with the value "value"
        @exposed({type: PropertyTypes.string, defaultValue: "value"})
        readonly optionalProperty: string;
     
    }
     
    // load config data from a yaml file with a watch interval of
    // 10 milliseconds into a conf eager source.
    const source = new ConfEagerSources.YamlFile("config.yaml", 10);
    // now use the source to instantiate a configuration object
    // and bind it to the source, so that when the source data
    // updated, the configuration instance immidietaly gets updated too.
    const conf = source.create(Configuration);
     
    // that's it, let's use it!
    conf.host;                                // => "0.0.0.0"
    conf.port;                                // => 8080
    conf.useHttps;                            // => false
    conf.logLevel;                            // => LogLevel.INFO
    conf.nestedConfiguration.nestedProperty;  // => 1234
    conf.arrayConfiguration;                  // => [1234, 2345]
    conf.optionalProperty;                    // => "value"

    Full documentation can be found on the project WIKI on GitHub.

    Why?

    ConfEagerJS is designed with two main charachteristics: being eager and being strongly-typed. This is a very powerful combination that provides a few main advantages.

    As opposed to popular configuration libraries, ConfEagerJS provides you with an interface for declaring your exact expectations from the configuration data. In addition, properties are eagerly loaded and validated. This combination renders a system that validates your entire configuration data source at boot time. The existance and value validity of each property in the source is validated immidiately. This also means no need to check for null and no null pointer errors either. This means no more typos when reading from the configuration, and most importantly, this means that to discover these kind of bugs you do not have to discover the exact control flow that triggers it, but rather let ConfEager find it for you when it loads.

    Additionally, ConfEagerJS is aimed to provide simple means to easily implement any data source you like, seamlessly get data updates from it without the need to restart your application, and consume any property type you would like from it.

    ConfEagerJS follows a big sister project for Java.

    Useful Links

    License

    ConfEagerJS is registered under license.

    Contribution

    Really, any kind of contribution will be warmly accepted. (:

    Install

    npm i confeager

    DownloadsWeekly Downloads

    1

    Version

    1.1.0

    License

    MIT

    Last publish

    Collaborators

    • avivcarmis