@decohere/config 0.0.1-dev.126 → 0.0.1-dev.5

package/LICENSE

@@ -1,15 +0,0 @@
-ISC License
-
-Copyright (c) 2025-2026 Typesmiths
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,40 +0,0 @@
-# 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/configuration-data-source.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "ConfigurationDataSource", {
-    enumerable: true,
-    get: function() {
-        return ConfigurationDataSource;
-    }
-});
-class ConfigurationDataSource {
-}

package/commonjs/src/configuration.extensions.js

@@ -1,45 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "BuilderExtensions", {
-    enumerable: true,
-    get: function() {
-        return BuilderExtensions;
-    }
-});
-const _http = require("@decohere/http");
-const _configuration = require("@decohere/core/configuration");
-const _extensibility = require("@decohere/core/extensibility");
-const _configurationservice = require("./configuration.service.js");
-const _const = require("./const.js");
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-class BuilderExtensions {
-    static withConfiguration(builder, ...dataSourceArgs) {
-        const dataSources = dataSourceArgs ?? [];
-        builder.withServices((builder)=>{
-            builder.registerSingleton(_configuration.ConfigurationServiceToken, _configurationservice.ConfigurationService);
-            for (const dataSource of dataSources){
-                builder.registerSingleton(_const.ConfigurationDataSourceKey, dataSource);
-            }
-        });
-        return builder;
-    }
-}
-_ts_decorate([
-    (0, _extensibility.extension)(_http.Builder),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof _http.Builder === "undefined" ? Object : _http.Builder,
-        Array
-    ]),
-    _ts_metadata("design:returntype", void 0)
-], BuilderExtensions, "withConfiguration", null);

package/commonjs/src/configuration.service.js

@@ -1,98 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "ConfigurationService", {
-    enumerable: true,
-    get: function() {
-        return ConfigurationService;
-    }
-});
-const _decorators = require("@decohere/crucible/decorators");
-const _caching = require("@decohere/core/caching");
-const _system = require("@decohere/core/system");
-const _const = require("./const.js");
-const _errors = require("./errors.js");
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-function _ts_param(paramIndex, decorator) {
-    return function(target, key) {
-        decorator(target, key, paramIndex);
-    };
-}
-class ConfigurationService {
-    data = {};
-    dataSources = [];
-    isInitialized = false;
-    constructor(dataSources = []){
-        this.dataSources = dataSources;
-    }
-    async initialize() {
-        if (this.isInitialized) {
-            return;
-        }
-        const records = await Promise.all(this.dataSources.map(async (d)=>await d.getData()));
-        this.validateDataSources(records);
-        const entries = records.flatMap((r)=>Object.entries(r));
-        this.data = Object.fromEntries(entries);
-        this.isInitialized = true;
-    }
-    async get(typeOrString) {
-        await this.ensureInitialized();
-        const obj = typeof typeOrString === "string" ? this.getStringKey(typeOrString) : this.getConstructable(typeOrString);
-        return obj;
-    }
-    async ensureInitialized() {
-        if (this.isInitialized) return;
-        await this.initialize();
-    }
-    validateDataSources(records) {
-        const keys = records.flatMap((record)=>Object.keys(record));
-        const uniqueKeys = new Set(keys);
-        if (uniqueKeys.size < keys.length) {
-            throw new _errors.ConfigurationError(`Cannot have duplicate data source names. The data sources are: ${keys.join(",")}`);
-        }
-    }
-    getConstructable(type) {
-        const key = (0, _system.lowerCamelCase)(type?.name.replace(/configuration|config/i, ""));
-        const data = this.data[key];
-        const configObject = new type();
-        Object.assign(configObject, data);
-        return configObject;
-    }
-    getStringKey(key) {
-        const data = this.data[key];
-        return data;
-    }
-}
-_ts_decorate([
-    (0, _caching.memoize)(),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof Constructable === "undefined" ? Object : Constructable
-    ]),
-    _ts_metadata("design:returntype", typeof T === "undefined" ? Object : T)
-], ConfigurationService.prototype, "getConstructable", null);
-_ts_decorate([
-    (0, _caching.cache)(),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        String
-    ]),
-    _ts_metadata("design:returntype", typeof T === "undefined" ? Object : T)
-], ConfigurationService.prototype, "getStringKey", null);
-ConfigurationService = _ts_decorate([
-    (0, _decorators.injectable)(),
-    _ts_param(0, (0, _decorators.inject)(_const.ConfigurationDataSourceKey)),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        Array
-    ])
-], ConfigurationService);

package/commonjs/src/const.js

@@ -1,20 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get ConfigurationDataSourceKey () {
-        return ConfigurationDataSourceKey;
-    },
-    get DEFAULT_CONFIG_DIR () {
-        return DEFAULT_CONFIG_DIR;
-    }
-});
-const ConfigurationDataSourceKey = Symbol("ConfigurationDataSourceKey");
-const DEFAULT_CONFIG_DIR = "config";

package/commonjs/src/errors.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "ConfigurationError", {
-    enumerable: true,
-    get: function() {
-        return ConfigurationError;
-    }
-});
-class ConfigurationError extends Error {
-}

package/commonjs/src/index.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-_export_star(require("./configuration.extensions.js"), exports);
-_export_star(require("./configuration.service.js"), exports);
-_export_star(require("./configuration-data-source.js"), exports);
-_export_star(require("./const.js"), exports);
-_export_star(require("./yaml-data-source.js"), exports);
-function _export_star(from, to) {
-    Object.keys(from).forEach(function(k) {
-        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
-            Object.defineProperty(to, k, {
-                enumerable: true,
-                get: function() {
-                    return from[k];
-                }
-            });
-        }
-    });
-    return from;
-}

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

@@ -1,185 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get YamlDataSource () {
-        return YamlDataSource;
-    },
-    get resolveConfigEnv () {
-        return resolveConfigEnv;
-    },
-    get resolveYamlConfig () {
-        return resolveYamlConfig;
-    }
-});
-const _io = require("@decohere/core/io");
-const _yaml = require("yaml");
-const _configurationdatasource = require("./configuration-data-source.js");
-const _const = require("./const.js");
-const _errors = require("./errors.js");
-const CONFIG_FILE_NAME = "config";
-/** Unset NODE_ENV must not silently load config.dev.yaml (TypeORM synchronize, etc.). */ const DEFAULT_ENV = "production";
-const FILE_EXT = "yaml";
-function resolveConfigEnv(nodeEnv) {
-    const env = nodeEnv ?? process.env.NODE_ENV;
-    if (env == null || env.trim() === "") {
-        return DEFAULT_ENV;
-    }
-    return env;
-}
-/** `${NAME}` or `${NAME:default}`. The default may be empty, and runs up to the first `}`. */ const PLACEHOLDER = /\$\{(\w+)(?::([^}]*))?\}/g;
-function isTree(value) {
-    return value != null && typeof value === "object" && !Array.isArray(value);
-}
-/** 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];
-        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)=>{
-        hasPlaceholder = true;
-        const fromEnv = process.env[name];
-        if (fromEnv !== undefined) {
-            return fromEnv;
-        }
-        if (fallback !== undefined) {
-            return fallback;
-        }
-        missing.push({
-            name,
-            path
-        });
-        return "";
-    });
-    // A variable set to the text "null" means no value.
-    return hasPlaceholder && resolved === "null" ? null : resolved;
-}
-function resolveValue(value, path, missing) {
-    if (typeof value === "string") {
-        return resolveString(value, path, missing);
-    }
-    if (Array.isArray(value)) {
-        return value.map((item, index)=>resolveValue(item, `${path}[${index}]`, missing));
-    }
-    if (isTree(value)) {
-        const resolved = {};
-        for (const [key, item] of Object.entries(value)){
-            resolved[key] = resolveValue(item, path === "" ? key : `${path}.${key}`, missing);
-        }
-        return resolved;
-    }
-    return value;
-}
-function parseSource({ name, text }) {
-    let parsed;
-    try {
-        parsed = (0, _yaml.parse)(text);
-    } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        throw new _errors.ConfigurationError(`Cannot parse config file ${name}: ${reason}`);
-    }
-    if (parsed == null) {
-        return undefined;
-    }
-    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) {
-    let merged = {};
-    for (const source of sources){
-        const tree = parseSource(source);
-        if (tree !== undefined) {
-            merged = merge(merged, tree);
-        }
-    }
-    const missing = [];
-    const resolved = resolveValue(merged, "", missing);
-    if (missing.length > 0) {
-        const lines = missing.map(({ name, path })=>`  - ${name} (used at ${path})`);
-        throw new _errors.ConfigurationError(`Config references ${missing.length} environment variable(s) that are not set:\n${lines.join("\n")}\n` + "Set them, give the value a default with ${NAME:default}, or replace it in the environment's config file.");
-    }
-    return resolved;
-}
-class YamlDataSource extends _configurationdatasource.ConfigurationDataSource {
-    name = YamlDataSource.name;
-    async getData() {
-        const configDir = process.env.CONFIG_DIR ?? _const.DEFAULT_CONFIG_DIR;
-        const env = resolveConfigEnv();
-        const candidates = [
-            `${configDir}/${CONFIG_FILE_NAME}.${FILE_EXT}`,
-            `${configDir}/${CONFIG_FILE_NAME}.${env}.${FILE_EXT}`
-        ];
-        const sources = [];
-        for (const filePath of candidates){
-            if (await _io.io.fileExists(filePath)) {
-                sources.push({
-                    name: filePath,
-                    text: await _io.io.readFile(filePath)
-                });
-            }
-        }
-        return resolveYamlConfig(sources);
-    }
-}

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

@@ -1,2 +0,0 @@
-export class ConfigurationDataSource {
-}

package/es6/src/configuration.extensions.js

@@ -1,35 +0,0 @@
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-import { Builder } from "@decohere/http";
-import { ConfigurationServiceToken } from "@decohere/core/configuration";
-import { extension } from "@decohere/core/extensibility";
-import { ConfigurationService } from "./configuration.service.js";
-import { ConfigurationDataSourceKey } from "./const.js";
-export class BuilderExtensions {
-    static withConfiguration(builder, ...dataSourceArgs) {
-        const dataSources = dataSourceArgs ?? [];
-        builder.withServices((builder)=>{
-            builder.registerSingleton(ConfigurationServiceToken, ConfigurationService);
-            for (const dataSource of dataSources){
-                builder.registerSingleton(ConfigurationDataSourceKey, dataSource);
-            }
-        });
-        return builder;
-    }
-}
-_ts_decorate([
-    extension(Builder),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof Builder === "undefined" ? Object : Builder,
-        Array
-    ]),
-    _ts_metadata("design:returntype", void 0)
-], BuilderExtensions, "withConfiguration", null);

package/es6/src/configuration.service.js

@@ -1,88 +0,0 @@
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-function _ts_param(paramIndex, decorator) {
-    return function(target, key) {
-        decorator(target, key, paramIndex);
-    };
-}
-import { inject, injectable } from "@decohere/crucible/decorators";
-import { cache, memoize } from "@decohere/core/caching";
-import { lowerCamelCase } from "@decohere/core/system";
-import { ConfigurationDataSourceKey } from "./const.js";
-import { ConfigurationError } from "./errors.js";
-export class ConfigurationService {
-    data = {};
-    dataSources = [];
-    isInitialized = false;
-    constructor(dataSources = []){
-        this.dataSources = dataSources;
-    }
-    async initialize() {
-        if (this.isInitialized) {
-            return;
-        }
-        const records = await Promise.all(this.dataSources.map(async (d)=>await d.getData()));
-        this.validateDataSources(records);
-        const entries = records.flatMap((r)=>Object.entries(r));
-        this.data = Object.fromEntries(entries);
-        this.isInitialized = true;
-    }
-    async get(typeOrString) {
-        await this.ensureInitialized();
-        const obj = typeof typeOrString === "string" ? this.getStringKey(typeOrString) : this.getConstructable(typeOrString);
-        return obj;
-    }
-    async ensureInitialized() {
-        if (this.isInitialized) return;
-        await this.initialize();
-    }
-    validateDataSources(records) {
-        const keys = records.flatMap((record)=>Object.keys(record));
-        const uniqueKeys = new Set(keys);
-        if (uniqueKeys.size < keys.length) {
-            throw new ConfigurationError(`Cannot have duplicate data source names. The data sources are: ${keys.join(",")}`);
-        }
-    }
-    getConstructable(type) {
-        const key = lowerCamelCase(type?.name.replace(/configuration|config/i, ""));
-        const data = this.data[key];
-        const configObject = new type();
-        Object.assign(configObject, data);
-        return configObject;
-    }
-    getStringKey(key) {
-        const data = this.data[key];
-        return data;
-    }
-}
-_ts_decorate([
-    memoize(),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof Constructable === "undefined" ? Object : Constructable
-    ]),
-    _ts_metadata("design:returntype", typeof T === "undefined" ? Object : T)
-], ConfigurationService.prototype, "getConstructable", null);
-_ts_decorate([
-    cache(),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        String
-    ]),
-    _ts_metadata("design:returntype", typeof T === "undefined" ? Object : T)
-], ConfigurationService.prototype, "getStringKey", null);
-ConfigurationService = _ts_decorate([
-    injectable(),
-    _ts_param(0, inject(ConfigurationDataSourceKey)),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        Array
-    ])
-], ConfigurationService);

package/es6/src/errors.js

@@ -1,2 +0,0 @@
-export class ConfigurationError extends Error {
-}