konfiger v1.2.1

konfiger-nodejs

The notable use cases of this package is loading configuration file, language file, preference setting in an application.

Table of content

• Installation
• Examples
  • Basic
  • Write to disk
  • Get Types
  • Lazy Loading
  • Seperator and delimeter
  • Read file with Stream
  • Read String with Stream
  • Skip Comment entries
  • Object Attachement, Get
  • Object Attachement, Put
  • Multiline value
• Native Object Attachement
  • matchGetKey
  • matchPutKey
• API Documentations
  • KonfigerStream
  • Konfiger
    • Fields
    • Functions
• Usage - Initialization - Inserting - Finding - Updating - Removing
  • Saving to disk
• How it works
• Contributing
• Support
• License

Installation

Module name on npm and bower is konfiger.

Using npm:

npm install konfiger

Using bower:

bower install konfiger

Using yarn:

yarn add konfiger

Examples

Basic

The following example load from file, add an entry, remove an entry and iterate all the key value entries

const { Konfiger } = require("konfiger")

//initialize the key-value from file
var konfiger = Konfiger.fromFile('test/test.config.ini', true)

//add a string
konfiger.putString("Greet", "Hello World")

//get an object
console.log(konfiger.get("Greet"))

//remove an object
konfiger.remove("Greet")

//add an String
konfiger.putString("What", "i don't know what to write here");

for (var entry of konfiger.entries()) {
	console.log(entry)
}

Write to disk

Initialize an empty konfiger object and populate it with random data, then save it to a file

const { Konfiger } = require("konfiger")

let randomValues = [ 'One', 'Two', 'Three', 'Four', 'Five' ]
var konfiger = Konfiger.fromString("", false)

for (var i = 0; i < 200; ++i) {
    var random = Math.floor(Math.random() * (randomValues.length - 1) + 0)
    konfiger.putString(''+i, randomValues[random])
}
konfiger.save('test/konfiger.conf')

Get Types

Load the entries as string and get them as a true type.

const { Konfiger } = require("konfiger")

var konfiger = Konfiger.fromString(`
String=This is a string
Number=215415245
Float=56556.436746
Boolean=true
`, false)

var str = konfiger.getString("String")
var num = konfiger.getLong("Number")
var flo = konfiger.getFloat("Float")
var bool = konfiger.getBoolean("Boolean")

console.log(typeof str)
console.log(typeof num)
console.log(typeof flo)
console.log(typeof bool)

Lazy Loading

The lazyLoad parameter is useful for progressively read entries from a large file. The next example shows initializing from a file with so much key value entry with lazy loading:

The content of test/konfiger.conf is

Ones=11111111111
Twos=2222222222222
Threes=3333333333333
Fours=444444444444
Fives=5555555555555

const { Konfiger } = require("konfiger")

let konfiger = Konfiger.fromFile('test/konfiger.conf', //the file pth
                                true //lazyLoad true
                                )
//at this point nothing is read from the file

//the size of konfiger is 0 even if the file contains over 1000 entries
console.log(konfiger.size())

//the key 'Twos' is at the second line in the file, therefore two entry has 
//been read to get the value.
console.log(konfiger.get("Twos"))

//the size becomes 2, 
console.log(konfiger.size())

//to read all the entries simply call the toString() method
console.log(konfiger.toString())

//now the size is equal to the entry
console.log(konfiger.size())

Seperator and delimeter

Initailize a konfiger object with default seperator and delimeter then change the seperator and selimeter at runtime

const { Konfiger } = require("konfiger")

let konfiger = Konfiger.fromFile('test/konfiger.conf', false)
konfiger.setDelimeter('?')
konfiger.setSeperator(',')

console.log(konfiger.toString())

Read file with Stream

Read a key value file using the progressive KonfigerStream, each scan returns the current key value array [ 'key', 'value']

const { KonfigerStream } = require("konfiger")

var kStream = KonfigerStream.fileStream('test/konfiger.conf')
while (kStream.hasNext()) {
    let entry = kStream.next()
    console.log(entry)
}

Read String with Stream

Read a key value string using the progressive KonfigerStream, each scan returns the current key value array [ 'key', 'value']

const { KonfigerStream } = require("konfiger")

var kStream = KonfigerStream.stringStream(`
String=This is a string
Number=215415245
Float=56556.436746
Boolean=true
`)

while (kStream.hasNext()) {
    let entry = kStream.next()
    console.log(entry)
}

Skip Comment entries

Read all the key value entry using the stream and skipping all commented entries. The default comment prefix is // but in the example below the commented entries starts with # so the prefix is changed. The same thing happen if the key value entry is loaded from file.

const { KonfigerStream } = require("konfiger")

var kStream = KonfigerStream.stringStream(`
String=This is a string
#Number=215415245
Float=56556.436746
#Boolean=true
`)
kStream.setCommentPrefix("#")

while (kStream.hasNext()) {
    let entry = kStream.next()
    console.log(entry)
}

Object Attachement, Get

The example below attach a javascript object to a konfiger object, whenever the value of the konfiger object changes the attached object entries is also updated.

For the file properties.conf

project = konfiger
author = Adewale Azeez

const { Konfiger } = require("konfiger")

var properties = {
    project: "",
    author: ""
}

var kon = Konfiger.fromFile('properties.conf')
kon.resolve(properties)

console.log(properties.project) // konfiger
console.log(properties.author) // Adewale Azeez
kon.put("project", "konfiger-nodejs")
console.log(properties.project) // konfiger-nodejs

Object Attachement, Put

The following snippet reads the value of a javascript object into the konfiger object, the object is then attached to konfiger so anytime the konfiger entry changes it updates the object.

var properties = {
    project: "konfiger",
    author: "Adewale"
}

var kon = Konfiger.fromString('')
kon.dissolve(properties)

console.log(kon.get("project")) // konfiger
console.log(kon.get("author")) // Adewale Azeez

Multiline value

Konfiger stream allow multiline value. If the line ends with \ the next line will be parse as the continuation and the leading spaces will be trimmed. The continuation character chan be changed like the example below the continuation character is changed from \ to +.

for the file test.contd.conf

Description = This project is the closest thing to Android +
              Shared Preference in other languages +
              and off the Android platform.
ProjectName = konfiger

const { KonfigerStream } = require("konfiger")

var ks = KonfigerStream.fileStream("test.contd.conf")
ks.setContinuationChar('+')
console.log(ks.next()[1])
console.log(ks.next()[1])

Native Object Attachement

This feature of the project allow seamless integration with the konfiger entries by eliminating the need for writing Konfiger.get*("") everytime to read a value into a variable or writing lot of Konfiger.put*() to add an entry.

The two function resolve and dissolve is used to attach an object. resolve function integrate the object such that the entries in konfiger will be assigned to the matching key in the object. See the resolve and dissolve examples above.

In a case where the object keys are different from the entries keys in the konfiger object the function matchGetKey can be attached to the object to match the key when setting the object entries values, and the function matchPutKey is called when setting the konfiger entries from the object.

For the file English.lang

LoginTitle = Login Page
AgeInstruction = You must me 18 years or above to register
NewsletterOptin = Signup for our weekly news letter

For an object which as the same key as the konfiger entries above there is no need to declare the matchGetKey or matchPutKey in the object. Resolve example

const { KonfigerStream } = require("konfiger")

var pageProps = {
    LoginTitle: "",
    AgeInstruction: "",
    NewsletterOptin: ""
}

var kon = Konfiger.fromFile('English.lang')
kon.resolve(pageProps)
console.log(pageProps)

Dissolve example

const { KonfigerStream } = require("konfiger")

var pageProps = {
    LoginTitle: "Login Page",
    AgeInstruction: "You must me 18 years or above to register",
    NewsletterOptin: "Signup for our weekly news letter"
}

var kon = Konfiger.fromString('')
kon.dissolve(pageProps)
console.log(kon.toString())

matchGetKey

If the identifier in the object keys does not match the above entries key the object will not be resolved. For example loginTitle does not match LoginTitle, the matchGetKey can be used to map the variable key to the konfiger entry key. The following example map the object key to konfiger entries key.

const { KonfigerStream } = require("konfiger")

var pageProps = {
    loginTitle: "",
    ageInstruct: "",
    NewsletterOptin: "",
    matchGetKey: function(key) {
        switch (key) {
            case "loginTitle":
                return "LoginTitle"
            case "ageInstruct":
                return "AgeInstruction"
        }
    }
}

var kon = Konfiger.fromFile('English.lang')
kon.resolve(pageProps)
console.log(pageProps)

The way the above code snippet works is that when iterating the object keys if check if the function matchGetKey is present in the object if it is present the key is sent as parameter to the matchGetKey and the returned value is used to get the value from konfiger, if the matchGetKey does not return anything the object key is used to get the value from konfiger (as in the case of NewsletterOptin).

During the resolve or dissolve process if the entry value is function it is skipped even if it key matches

For dissolving an object the method matchGetKey is invoked to find the actual key to use to add the entry in konfiger, if the object does not declare the matchGetKey function the entries will be added to konfiger as it is declared. The following example similar to the one above but dissolves an object into konfiger.

const { KonfigerStream } = require("konfiger")

var pageProps = {
    loginTitle: "Login Page",
    ageInstruct: "You must me 18 years or above to register",
    NewsletterOptin: "Signup for our weekly news letter",
    matchGetKey: function(key) {
        switch (key) {
            case "loginTitle":
                return "LoginTitle"
            case "ageInstruct":
                return "AgeInstruction"
        }
    }
}

var kon = Konfiger.fromFile('English.lang')
kon.dissolve(pageProps)
console.log(kon.toString())

matchPutKey

The matchPutKey is invoked when an entry value is changed or when a new entry is added to konfiger. The matchPutKey is invoked with the new entry key and checked in the object matchPutKey (if decalred), the returned value is what is set in the object. E.g. if an entry [Name, Thecarisma] is added to konfiger the object matchPutKey is invoked with the parameter Name the returned value is used to set the corresponding object entry.

const { KonfigerStream } = require("konfiger")

var pageProps = {
    loginTitle: "",
    ageInstruct: "",
    NewsletterOptin: "",
    matchPutKey: function(key) {
        switch (key) {
            case "LoginTitle":
                return "loginTitle"
            case "AgeInstruction":
                return "ageInstruct"
        }
    }
}

var kon = Konfiger.fromString('')
kon.resolve(pageProps)

kon.put("LoginTitle", "Login Page")
kon.put("AgeInstruction", "You must me 18 years or above to register")
kon.put("NewsletterOptin", "Signup for our weekly news letter")
console.log(pageProps.loginTitle)
console.log(pageProps.ageInstruct)
console.log(pageProps.NewsletterOptin)

Konfiger does not create new entry in an object it just set existing values. Konfiger only change the value in an object if the key is defined

Warning!!! The values resolved is not typed so if the entry initial value is an integer the resolved value will be a string. All resolved value is string, you will need to do the type conversion by your self.

If your entry keys is the same as the object keys you don't need to declare the matchGetKey or matchPutKey function in the object.

Usage

Initialization

The main Konfiger contructor is not exported from the package, the two functions are exported for initialization, fromString and fromFile. The fromString function creates a Konfiger object from a string with valid key value entry or from empty string, the fromFile function creates the Konfiger object from a file, the two functions accept a cumpulsory second parameter lazyLoad which indicates whether to read all the entry from the file or string suring initialization. The lazyLoad parameter is useful for progressively read entries from a large file. The two initializing functions also take 2 extra optional parameters delimeter and seperator. If the third and fourth parameter is not specified the default is used, delimeter = =, seperator = \n. If the file or string has different delimeter and seperator always send the third and fourth parameter.

The following initializer progressively read the file when needed

let konfiger = Konfiger.fromFile('test/konfiger.conf', true)

The following initializer read all the entries from file at once

let konfiger = Konfiger.fromFile('test/konfiger.conf', false)

The following initializer read all the entries from string when needed

let konfiger = Konfiger.fromString(`
Ones=11111111111
Twos=2222222222222
`, true)

The following initializer read all the entries from String at once

let konfiger = Konfiger.fromString(`
Ones=11111111111
Twos=2222222222222
`, false)

Initialize a string which have custom delimeter and seperator

let konfiger = Konfiger.fromString(`Ones:11111111111,Twos:2222222222222`, 
                                false, 
                                ':',
                                ',')

Inserting

The following types can be added into the object, int, float, long, boolean, object and string.

To add any object into the entry use the put method as it check the value type and properly get it string value

konfiger.put("String", "This is a string")
konfiger.put("Long", 143431423)
konfiger.put("Boolean", true)
konfiger.put("Float", 12.345)

The put method do a type check on the value and calls the appropriate put method e.g konfiger.put("Boolean", true) will result in a call to konfiger.putBoolean("Boolean", true). The following method are avaliable to directly add the value according to the type, putString, putBoolean, putLong and putInt. The previous example can be re-written as:

konfiger.putString("String", "This is a string")
konfiger.putLong("Long", 143431423)
konfiger.putBoolean("Boolean", true)
konfiger.putFloat("Float", 12.345)

Finding

There are various ways to get the value from the konfiger object, the main get method and getString method both returns a string type, the other get methods returns specific types

konfiger.get("String")

To get specific type from the object use the following methods, getString, getBoolean, getLong, getFloat and getInt.

konfiger.getString("String")
konfiger.getLong("Long")
konfiger.getBoolean("Boolean")
konfiger.getFloat("Float")

If the requested entrr does not exist a null/undefined value is returned, to prevent that a fallback value should be sent as second parameter incase the key is not found the second parameter will be returned.

konfiger.get("String", "Default Value")
konfiger.getBoolean("Boolean", false)

If the konfiger is initialized with lazy loading enabled if the get method is called the stream will start reading until the key is found and the stream is paused again, if the key is not found the stream will read to end.

Updating

The put method can be used to add new entry or to update an already existing entry in the object. The updateAt method is usefull for updating a value using it index instead of key

konfiger.updateAt(0, "This is an updated string")

Removing

The remove method removes a key value entry from the konfiger, it returns true if an entry is removed and false if no entry is removed. The remove method accept either key(string) or index(int) of the entry.

konfiger.remove("String")
konfiger.remove(0)

Saving to disk

Every operation on the konfiger object is done in memory to save the updated entries in a file call the save method with the file path to save the entry. If the konfiger is initiated from file then there is no need to add the file path to the save method, the entries will be saved to the file path used during initialization.

konfiger.save("test/test.config.ini")

in case of load from file, the save will write the entries to test/test.config.ini.

//...
var konfiger = Konfiger.fromFile('test/test.config.ini', true)
//...
konfiger.save()

API Documentations

Even though JavaScript is weakly type the package does type checking to ensure wrong datatype is not passed into the functions.

KonfigerStream

Konfiger

Fields

Functions

How it works

Konfiger stream progressively load the key value entry from a file or string when needed, it uses two method hasNext which check if there is still an entry in the stream and next for the current key value entry in the stream.

In Konfiger the key value pair is stored in a map, all search updating and removal is done on the konfigerObjects in the class. The string sent as first parameter if parsed into valid key value using the separator and delimiter fields and if loaded from file it content is parsed into valid key value pair. The toString method also parse the konfigerObjects content into a valid string with regards to the separator and delimeter. The value is properly escaped and unescaped.

The save function write the current Konfiger to the file, if the file does not exist it is created if it can. Everything is written in memory and is disposed on app exit hence it important to call the save function when nessasary.

Contributing

Before you begin contribution please read the contribution guide at CONTRIBUTING GUIDE

You can open issue or file a request that only address problems in this implementation on this repo, if the issue address the concepts of the package then create an issue or rfc here

Support

You can support some of this community as they make big impact in the traing of individual to get started with software engineering and open source contribution.

• https://www.patreon.com/devcareer

License

MIT License Copyright (c) 2020 Adewale Azeez - konfiger