@decohere/config 0.0.1-dev.116 → 0.0.1-dev.118

package/README.md

@@ -0,0 +1,40 @@
+# Config
+
+Application configuration for Decohere: data sources that feed the configuration service, starting with YAML files read from the environment.
+
+## YAML files
+
+`YamlDataSource` reads two files from `CONFIG_DIR` (default `config`):
+
+1. `config.yaml`: production, and the base for every environment.
+2. `config.<NODE_ENV>.yaml`, if it exists, such as `config.dev.yaml`. An unset `NODE_ENV` means `production`, so a missing variable never loads development settings.
+
+### How the files merge
+
+The environment file only states what it changes:
+
+- **Objects** merge key by key.
+- **Lists of named entries** merge by `name`. Every entry is a mapping with a string `name`, as in `database.dataSources`. An entry with a name the base already has merges into that entry, and a new name is added at the end. The base keeps its order. A file that repeats a name in such a list is rejected, because the merge couldn't tell the entries apart.
+- **Any other list**, and a scalar, replaces the earlier value. An empty list (`[]`) clears it.
+
+```yaml
+# config.yaml
+database:
+  dataSources:
+    - name: api
+      host: ${API_DB_HOST}
+      password: ${API_DB_PASSWORD}
+      synchronize: false
+
+# config.dev.yaml: only what development changes
+database:
+  dataSources:
+    - name: api
+      synchronize: true
+```
+
+### Placeholders
+
+`${NAME}` reads an environment variable, and `${NAME:default}` gives it a default. Placeholders are resolved **after** the merge. That way an environment file can replace a production `${VAR}` without the variable being set. Placeholders still unset after the merge fail together, and the error names every variable and where it was used. A variable set to the text `null` means no value.
+
+Secrets come only from the process environment ([ADR 0002](../../docs/adr/0002-secrets-from-the-environment.md)). Nothing here reads a `.env` file; a CLI loads one only with an explicit `--env-file`.

package/commonjs/src/yaml-data-source.js

@@ -38,16 +38,61 @@ function resolveConfigEnv(nodeEnv) {
 function isTree(value) {
     return value != null && typeof value === "object" && !Array.isArray(value);
 }
-/** Objects merge key by key; a list or a scalar in the later file replaces the earlier value. */ function merge(base, override) {
+/** A non-empty list whose every entry is a mapping with a string `name`, such as `dataSources`. */ function isNamedList(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((item)=>isTree(item) && typeof item.name === "string");
+}
+/** Entries with the same name merge in place; new names are added at the end. */ function mergeNamedLists(base, override) {
+    const merged = [
+        ...base
+    ];
+    for (const entry of override){
+        const index = merged.findIndex((item)=>item.name === entry.name);
+        if (index === -1) {
+            merged.push(entry);
+        } else {
+            merged[index] = merge(merged[index], entry);
+        }
+    }
+    return merged;
+}
+/**
+ * Objects merge key by key, and so do lists of named entries (matched by `name`), so an
+ * environment file only states what it changes. Any other list, and a scalar, in the later file
+ * replaces the earlier value.
+ */ function merge(base, override) {
     const merged = {
         ...base
     };
     for (const [key, value] of Object.entries(override)){
         const existing = merged[key];
-        merged[key] = isTree(existing) && isTree(value) ? merge(existing, value) : value;
+        if (isTree(existing) && isTree(value)) {
+            merged[key] = merge(existing, value);
+        } else if (isNamedList(existing) && isNamedList(value)) {
+            merged[key] = mergeNamedLists(existing, value);
+        } else {
+            merged[key] = value;
+        }
     }
     return merged;
 }
+/** A named list that repeats a name can't be merged by name, so say which file and where. */ function assertUniqueNames(value, source, path) {
+    if (isNamedList(value)) {
+        const seen = new Set();
+        for (const item of value){
+            if (seen.has(item.name)) {
+                throw new _errors.ConfigurationError(`Config file ${source}: ${path} lists the name "${String(item.name)}" more than once`);
+            }
+            seen.add(item.name);
+        }
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index)=>assertUniqueNames(item, source, `${path}[${index}]`));
+    } else if (isTree(value)) {
+        for (const [key, item] of Object.entries(value)){
+            assertUniqueNames(item, source, path === "" ? key : `${path}.${key}`);
+        }
+    }
+}
 function resolveString(value, path, missing) {
     let hasPlaceholder = false;
     const resolved = value.replace(PLACEHOLDER, (_match, name, fallback)=>{
@@ -98,6 +143,7 @@ function parseSource({ name, text }) {
     if (!isTree(parsed)) {
         throw new _errors.ConfigurationError(`Config file ${name} must contain a mapping at the top level`);
     }
+    assertUniqueNames(parsed, name, "");
     return parsed;
 }
 function resolveYamlConfig(sources) {

package/es6/src/yaml-data-source.js

@@ -17,16 +17,61 @@ const FILE_EXT = "yaml";
 function isTree(value) {
     return value != null && typeof value === "object" && !Array.isArray(value);
 }
-/** Objects merge key by key; a list or a scalar in the later file replaces the earlier value. */ function merge(base, override) {
+/** A non-empty list whose every entry is a mapping with a string `name`, such as `dataSources`. */ function isNamedList(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((item)=>isTree(item) && typeof item.name === "string");
+}
+/** Entries with the same name merge in place; new names are added at the end. */ function mergeNamedLists(base, override) {
+    const merged = [
+        ...base
+    ];
+    for (const entry of override){
+        const index = merged.findIndex((item)=>item.name === entry.name);
+        if (index === -1) {
+            merged.push(entry);
+        } else {
+            merged[index] = merge(merged[index], entry);
+        }
+    }
+    return merged;
+}
+/**
+ * Objects merge key by key, and so do lists of named entries (matched by `name`), so an
+ * environment file only states what it changes. Any other list, and a scalar, in the later file
+ * replaces the earlier value.
+ */ function merge(base, override) {
     const merged = {
         ...base
     };
     for (const [key, value] of Object.entries(override)){
         const existing = merged[key];
-        merged[key] = isTree(existing) && isTree(value) ? merge(existing, value) : value;
+        if (isTree(existing) && isTree(value)) {
+            merged[key] = merge(existing, value);
+        } else if (isNamedList(existing) && isNamedList(value)) {
+            merged[key] = mergeNamedLists(existing, value);
+        } else {
+            merged[key] = value;
+        }
     }
     return merged;
 }
+/** A named list that repeats a name can't be merged by name, so say which file and where. */ function assertUniqueNames(value, source, path) {
+    if (isNamedList(value)) {
+        const seen = new Set();
+        for (const item of value){
+            if (seen.has(item.name)) {
+                throw new ConfigurationError(`Config file ${source}: ${path} lists the name "${String(item.name)}" more than once`);
+            }
+            seen.add(item.name);
+        }
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index)=>assertUniqueNames(item, source, `${path}[${index}]`));
+    } else if (isTree(value)) {
+        for (const [key, item] of Object.entries(value)){
+            assertUniqueNames(item, source, path === "" ? key : `${path}.${key}`);
+        }
+    }
+}
 function resolveString(value, path, missing) {
     let hasPlaceholder = false;
     const resolved = value.replace(PLACEHOLDER, (_match, name, fallback)=>{
@@ -77,6 +122,7 @@ function parseSource({ name, text }) {
     if (!isTree(parsed)) {
         throw new ConfigurationError(`Config file ${name} must contain a mapping at the top level`);
     }
+    assertUniqueNames(parsed, name, "");
     return parsed;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decohere/config",
-  "version": "0.0.1-dev.116",
+  "version": "0.0.1-dev.118",
   "description": "Database ORM abstractions and repository patterns built on TypeORM",
   "keywords": [
     "typescript",
@@ -25,9 +25,9 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@decohere/core": "0.0.1-dev.116",
-    "@decohere/crucible": "0.0.1-dev.116",
-    "@decohere/http": "0.0.1-dev.116",
+    "@decohere/core": "0.0.1-dev.118",
+    "@decohere/crucible": "0.0.1-dev.118",
+    "@decohere/http": "0.0.1-dev.118",
     "yaml": "^2.9.1"
   },
   "devDependencies": {}