Negligent Pachinko Machine

    uenv

    0.2.5 • Public • Published

    about

    uenv is a zero dependency configuration manager for nodejs, its design goals is to be very fast, allow finely grained access to properties via references, have an easy and straight-forward plugin system, allow different routines within the system to set up different parts of the configuration without having to be aware of the entire tree structure

    installation

    npm install --save uenv

    by example

    kitchen sink

    const path = require('path')
    const uenv = require('uenv')
     
    // import enviorment variables into configuration
    uenv.env()
     
    // assign an object to the root of the configuraiton tree
    uenv.assign({
      foo: 'bar',
      nested: {
        object: {
          a: 1
        }
      }
    })
     
    uenv.set('nested.object.b', 2)
     
    // creates a new child with the literal plugin
    const child = uenv.literalChild('childProperty')
     
    // sets a value referenced as 'child.childfoo'
    child.set('childfoo', 'childbar')
     
    // assign multiple values to child
    child.assign({
      c: 9,
      d: 10
    })
     
    // assign json contents to configuraiton root
    // assuming json1.json contents is { "jsonProperty": { "jsonA": 1, "jsonB": 2 } }
    uenv.json(path.join(__dirname, 'assets', 'json1.json'))
     
    // assign json contents to { jsonData: {} }
    uenv.jsonChild('jsonData', path.join(__dirname, 'assets', 'json1.json'))
     
    // seal a property against changes
    uenv.seal('foo')
    uenv.set('foo', 'notbar')
     
    uenv.get('foo')             // bar
    uenv.equals('foo', 'bar')   // true
    uenv.get('nested')          // { object: { a: 1, b: 2 } }
    uenv.get('nested.object')   // { a: 1, b: 2 }
    uenv.get('nested.object.a') // 1
    uenv.get('childProperty')   // { childfoo: 'childbar', c: 9, d: 10 })
    uenv.get('jsonProperty')    // { jsonA: 1, jsonB: 2 }
    uenv.get('jsonData.jsonProperty') // { jsonA: 1, jsonB: 2 })
    uenv.pick('nested.object', ['b']) // { b: 2 }
    uenv.omit('nested.object', ['b']) // { a: 2 }
    uenv.any(['nested.object.c', 'nested.object.b', 'nested.object.c']) // 2
    // get entire configuration as plain javascript object
    uenv.toJSON()
     

    Useless plugin

    const uenv = require('uenv')
     
    function MyPlugin (methods, arg1) {
      // methods are { set, get, has, assign, toJSON }
      // and would behave depending on the plugin mounted position
      this.__methods = methods
      this.__arg1 = arg1
    }
     
    MyPlugin.prototype.set = function (k, v) {
      this.__methods.set(k, `${this.__arg1}-${v}`)
    }
     
    uenv.plugin('useless', MyPlugin)
     
    const useless = uenv.useless('addthis')
     
    useless.set('foo', 'bar')
     
    uenv.get('foo') // addthis-bar
     

    plugins

    built-in

    • literal - a simple get/set/assign storage for objects
    • env - loads the environment variables into the configuration as-is
    • json - allows reading configuration from a json file, can also be used to store the file

    external plugins

    • (uenv-s3-plugin)[https://github.com/oiime/uenv-s3-plugin] - stores and retrieves configuration from AWS S3, allows encryption before storage

    API

    uenv.assign(obj)

    Assigns an entire object to the configuration

    • obj = plain javascript object to assign

    uenv.set(key, value, options = {})

    Assigns an entire object to the configuration

    • key - key to set, using a separator (eg: 'foo.bar') would set references for the entire hierarchy
    • value - just... the value
    • options - optional parameters
      • references (bool) - if set to false, there would be no references set for any properties of the value (if the value is an object), this can be useful if you dont want to waste memory and need to store large objects

    uenv.get(key)

    Returns a property value

    uenv.has (key)

    Checks if key exists, returns a boolean

    uenv.toJSON ()

    Returns a plain javascript object of all properties

    uenv.plugin (name, Plugin)

    registers a new plugin, Plugin would be constructed whenever use or child are called with its name

    uenv.use (name, ...args)

    Initiates a plugin that'll have access to the properties, any arguments after the plugin name would be passed as arguments to the plugin itself this is accessible via the shorthand method uenv.[plugin name] eg uenv.json()

    uenv.child (key, name, ...args)

    Initiates a plugin that'll have access to the properties at a specific position, any arguments after the plugin name would be passed as arguments to the plugin itself Key can be dot notated to get a child at a deeper part of the tree, any preceding keys would be created with references, this is accessible via the shorthand method [plugin name]Child

    uenv.equals (key, value)

    Checks if a key is equal to a value, returns a boolean

    uenv.seal (key)

    Seals a key, any subsequent attempts to write to this key would not change the stored value

    uenv.any (keys = [])

    returns the first trueish key in the array

    uenv.pick (key, properties = [])

    if key is a plain javascript object, only the properties listed would be returned in a new object

    uenv.omit (key, properties = [])

    if key is a plain javascript object, only the properties not listed would be returned in a new object

    uenv.setOptions (options = {})

    Allows changes internal options within uenv

    • options
      • separator - change the default separator (.) to something else, this needs to be set before any property is set as that'll screw up the references
      uenv.setOptions({ separator: ':'})
      uenv.set('foo:bar', 1)
      uenv.get('foo:bar')

    uenv.instance ()

    Gets a standalone instance of uenv that does not store its properties at the module itself

    jsonPlugin methods

    uenv.json (filename, { required = true })

    • filename - required argument if required is set to true (default), filename to load json from
    • options
      • required - if set to false the plugin would ignore any errors trying to load the json file

    uenv.jsonChild (key, filename, { required = true })

    • key to place object in
    • filename - required argument if required is set to true (default), filename to load json from
    • options
      • required - if set to false the plugin would ignore any errors trying to load the json file

    [jsonChild].save (filename)

    saves current configuration to json file, if filename is not provided it'll save to the same filename set up during construction

    License: MIT

    Install

    npm i uenv

    DownloadsWeekly Downloads

    3

    Version

    0.2.5

    License

    MIT

    Last publish

    Collaborators

    • oiime