Merge pull request #10 from mfellner/next

Merge next

.travis.yml

@@ -4,8 +4,8 @@ branches:
     - master
 language: node_js
 node_js:
-  - "6.11.0"
-  - "8.0.0"
+  - "8.9.4"
+  - "9.6.1"
 cache:
   yarn: true
   directories:

README.md

@@ -1,6 +1,12 @@
-![typeconf](https://user-images.githubusercontent.com/1183636/26884982-7e63efd0-4ba1-11e7-845d-4ade4627039c.png)   [![Travis](https://img.shields.io/travis/mfellner/typeconf.svg)](travis-ci.org/mfellner/typeconf) [![Codecov](https://img.shields.io/codecov/c/github/mfellner/typeconf.svg)](https://codecov.io/gh/mfellner/janus) [![codebeat badge](https://codebeat.co/badges/6df3709c-deed-4a8f-af7d-2e1ccda63591)](https://codebeat.co/projects/github-com-mfellner-typeconf-master) [![npm](https://img.shields.io/npm/v/typeconf.svg)](https://www.npmjs.com/package/typeconf) [![license](https://img.shields.io/github/license/mfellner/typeconf.svg)](https://choosealicense.com/licenses/mit)
+![typeconf](https://user-images.githubusercontent.com/1183636/26884982-7e63efd0-4ba1-11e7-845d-4ade4627039c.png)  
+[![Travis](https://img.shields.io/travis/mfellner/typeconf.svg)](travis-ci.org/mfellner/typeconf)
+[![Codecov](https://img.shields.io/codecov/c/github/mfellner/typeconf.svg)](https://codecov.io/gh/mfellner/janus)
+[![David](https://img.shields.io/david/mfellner/typeconf.svg)](https://david-dm.org/mfellner/typeconf)
+[![codebeat badge](https://codebeat.co/badges/6df3709c-deed-4a8f-af7d-2e1ccda63591)](https://codebeat.co/projects/github-com-mfellner-typeconf-master)
+[![npm](https://img.shields.io/npm/v/typeconf.svg)](https://www.npmjs.com/package/typeconf)
+[![license](https://img.shields.io/github/license/mfellner/typeconf.svg)](https://choosealicense.com/licenses/mit)
 
-**TypeConf** is a typesafe hierarchical configuration manager for Node.js.
+**TypeConf** is a universal, typesafe, hierarchical configuration manager for Node.js and the browser.
 
 ## Usage
 
@@ -13,26 +19,30 @@ const conf = new TypeConf()
   .withFile('./conf.json');
   .withEnv();
 
-const port = conf.getNumber('port');
-const secret = conf.getString('secret');
+const port: number = conf.getNumber('port');
+const secret: string = conf.getString('secret');
 ```
 
 ## Hierarchical configuration
 
 TypeConf supports different storage backends for configuration values:
 
-All versions:
+#### All versions:
 
 * **withStore(store: object, name?: string)** JavaScript object
 * **withSupplier(supplier: (key: string) => any, name?: string)** Supplier function
-* **set(key: string, value: any)** Override a value
+* **set(key: string, value: any)** Set or override a value
 
-Node.js only:
+#### Node.js only:
 
 * **withArgv()** Command line arguments (requires `minimist`)
 * **withEnv(prefix?: string)** Environment variables
 * **withFile(file: string)** JSON or YAML files (.yaml files require `js-yaml`)
 
+#### Browser only:
+
+* **withDOMNode(id: string)** DOM element with encoded `value` attribute
+
 Backends are queried for existing values in the reverse order that they were added. For example:
 
 ```js
@@ -52,7 +62,7 @@ In this case TypeConf will check for existing values in the following order:
 
 ## Nested object properties
 
-TypeConf can extract nested object properties from environment varibles:
+TypeConf can merge and extract nested object properties from environment varibles:
 
 ```js
 const conf = new TypeConf()
@@ -71,23 +81,65 @@ export EXAMPLE__TEST="override"
 export EXAMPLE__OTHER="another property"
 ```
 
-By default, TypeConf uses two "underline" characters (`__`) as a separator. We can even define completely new objects using this method:
+By default, TypeConf uses two "underscore" characters (`__`) as a separator. We can even define completely new objects using this method:
 
 ```sh
-export ANOTHER__A="property A"
+export ANOTHER__A="property a"
 export ANOTHER__B__C="property b.c"
 ```
 
 ```js
 const another = conf.getObject('another');
-another === {
-  a: 'property A',
-  b: { c: 'property b.c' }
-}
+another === { a: 'property a', b: { c: 'property b.c' } };
 ```
 
 ## API documentation
 
+### withStore(store: object, name?: string): TypeConf
+
+Use a JavaScript object as a source. Optionally provide a unique **name** for the store.
+
+### withSupplier(supplier: (key: string) => any, name?: string): TypeConf
+
+Use a supplier function as a source. Optionally provide a unique **name** for the store.
+
+### withArgv(parser?: (args: string[]) => { [key: string]: any }): TypeConf
+
+**Node.js only.** Use command line arguments as a source. Optionally provide a custom argument parser (uses [minimist](https://www.npmjs.com/package/minimist) by default).
+
+### withEnv(prefix?: string, separator?: string): TypeConf
+
+**Node.js only.** Use environment variables as a source. If a **prefix** is configured, it will be prepended to configuration value names during lookup. The default **separator** for nested object values is `__`. For example:
+
+```sh
+export PREFIX_OBJECT__A="a"
+export PREFIX_OBJECT__B__BB="bb"
+```
+
+```js
+conf.getObject('object') === { a: 'a', b: { bb: 'bb' } };
+```
+
+### withFile(file: string): TypeConf
+
+**Node.js only.** Use a configuration file as a source. JSON and YAML (requires [js-yaml](https://www.npmjs.com/package/js-yaml)) are supported.
+
+### withDOMNode(id: string): TypeConf
+
+**Browser only.** Use a DOM element with a `value` attribute as a source. The value must be a Base64-encoded JSON string. For example:
+
+```html
+<meta id="conf" value="eyJhIjoiYiJ9" />
+```
+
+### set(key: string, value: any): TypeConf
+
+Set an override value.
+
+### unset(key: string): TypeConf
+
+Delete an override value.
+
 ### get(name: string): any
 
 Get a raw value.
@@ -115,3 +167,15 @@ Get an existing value as an object (using `JSON.parse` if necessary) or return a
 ### getType&lt;T&gt;(name: string, Newable: Newable&lt;T&gt;, fallback?: T): T | undefined
 
 Get an existing value as an instance of type `T` (by passing the raw value as the only argument to the constructor) or return an optional fallback value of the same type. **Throws TypeError** if an error occurs during the instantiation of type `T` (constructors should validate the raw configuration value).
+
+### toJSON(): object
+
+Aggregate all values from all supported stores as a plain JavaScript object. There are several limitations:
+
+* Supplier-function stores cannot be aggregated.
+* Environment-variable stores without a defined prefix cannot be aggregated.
+* All command-line arguments are included if the default parser is used.
+
+### toBase64(): string
+
+Aggregate all values from all supported stores and encode them as a Base64 JSON string. The same limitations as for `toJSON()` apply.

package.json

@@ -18,7 +18,7 @@
     "environment"
   ],
   "engines": {
-    "node": ">=6.11.0"
+    "node": ">=8.9.4"
   },
   "scripts": {
     "clean": "rimraf dist/*",
@@ -32,23 +32,23 @@
   "dependencies": {
     "camel-case": "^3.0.0",
     "constant-case": "^2.0.0",
-    "lodash.merge": "^4.6.0"
+    "lodash.merge": "^4.6.1"
   },
   "optionalDependencies": {
     "js-yaml": "^3.10.0",
     "minimist": "^1.2.0"
   },
   "devDependencies": {
-    "@types/jest": "21.1.8",
+    "@types/jest": "22.1.3",
     "@types/lodash.merge": "4.6.3",
     "@types/minimist": "1.2.0",
-    "@types/node": "8.5.1",
-    "jest": "22.0.2",
-    "prettier": "1.9.2",
+    "@types/node": "9.4.6",
+    "jest": "22.4.2",
+    "prettier": "1.11.0",
     "rimraf": "2.6.2",
-    "ts-jest": "22.0.0",
-    "tslint": "5.8.0",
-    "typescript": "2.6.2"
+    "ts-jest": "22.4.0",
+    "tslint": "5.9.1",
+    "typescript": "2.7.2"
   },
   "jest": {
     "testEnvironment": "node",
@@ -60,7 +60,6 @@
       "\\.ts$": "<rootDir>/node_modules/ts-jest/preprocessor.js"
     },
     "testRegex": "/test/.*\\.test.ts$",
-    "mapCoverage": true,
     "coverageReporters": [
       "json",
       "lcov",

src/Newable.ts

@@ -0,0 +1,8 @@
+/**
+ * Generic instantiable type.
+ */
+export interface Newable<T> {
+  new (...args: any[]): T;
+}
+
+export default Newable;

src/StoreError.ts

@@ -0,0 +1,11 @@
+/**
+ * Runtime error caused inside a store.
+ */
+export default class StoreError extends Error {
+  public readonly cause?: Error;
+
+  constructor(message: string, cause?: Error) {
+    super(message);
+    this.cause = cause;
+  }
+}