@terreno/api 0.13.3 → 0.14.1

package/dist/config.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * Runtime configuration registry with a fixed resolution order:
+ *
+ *   1. In-process override (Config.setOverride) — highest, for tests/bootstrap
+ *   2. Cached env map — typically loaded from an admin-editable Mongoose document
+ *   3. process.env
+ *   4. Registered default
+ *
+ * Why a registry: every key migrating off raw `process.env` declares its type
+ * and default in one place. That keeps the admin UI honest (no surprise keys),
+ * gives synchronous access without scattered `?? "default"` literals at call
+ * sites, and lets tests assert behavior against a single source of truth.
+ *
+ * Why sync: hundreds of call sites read configuration during request handling
+ * and module init; an async API would force enormous refactors. Callers load
+ * the env map once via `Config.refresh()` after Mongo connects, then read
+ * synchronously from cache.
+ *
+ * The mechanism is agnostic to where the env map comes from. Apps wire up
+ * their backing store with `Config.setEnvLoader(fn)`. The optional
+ * `envConfigurationPlugin` provides a drop-in Mongoose schema integration.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = void 0;
+var errors_1 = require("./errors");
+var overrides = new Map();
+var cachedEnv = null;
+var envLoader = null;
+// Null-prototype object so lookups don't resolve inherited keys like
+// `constructor` / `toString` as accidentally-registered entries.
+var REGISTRY = Object.create(null);
+/**
+ * Registers a configuration key, its default, and metadata. Re-registration
+ * of the same key throws so duplicates surface at boot.
+ */
+var register = function (key, registration) {
+    if (registration === void 0) { registration = {}; }
+    if (REGISTRY[key]) {
+        throw new errors_1.APIError({ status: 500, title: "Config key \"".concat(key, "\" registered more than once") });
+    }
+    REGISTRY[key] = registration;
+};
+/**
+ * Returns the configured string value for `key`, applying the resolution
+ * order documented at the top of this file. Returns `undefined` if no
+ * source supplies a value and no default was registered.
+ */
+var getString = function (key) {
+    var _a;
+    if (overrides.has(key)) {
+        return overrides.get(key);
+    }
+    if (cachedEnv && key in cachedEnv) {
+        var v = cachedEnv[key];
+        if (v !== undefined && v !== "") {
+            return v;
+        }
+    }
+    // Guard against process.env keys like "toString" / "constructor" inheriting
+    // a function from Object.prototype. Only accept string values.
+    var fromProcess = process.env[key];
+    if (typeof fromProcess === "string" && fromProcess !== "") {
+        return fromProcess;
+    }
+    return (_a = REGISTRY[key]) === null || _a === void 0 ? void 0 : _a.default;
+};
+/**
+ * Returns the configured value as a number. Throws if a value is present but
+ * not finite — silent NaN propagation has bitten apps before.
+ */
+var getNumber = function (key) {
+    var raw = getString(key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    // Number() rejects partially-numeric strings like "5000ms" (returns NaN)
+    // whereas parseFloat would silently truncate to 5000.
+    var parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        throw new errors_1.APIError({
+            error: new Error("Config key \"".concat(key, "\" is not a valid number: ").concat(JSON.stringify(raw))),
+            status: 500,
+            title: "Config key \"".concat(key, "\" is not a valid number"),
+        });
+    }
+    return parsed;
+};
+/**
+ * Returns true iff the string value equals "true" (case-insensitive). Mirrors
+ * the existing `process.env.X === "true"` idiom.
+ */
+var getBoolean = function (key) {
+    var raw = getString(key);
+    return raw !== undefined && raw.toLowerCase() === "true";
+};
+/**
+ * Parses a JSON-encoded config value. Returns undefined if unset; throws on
+ * malformed JSON so misconfiguration fails loud at the call site rather than
+ * producing silent runtime errors later.
+ */
+var getJSON = function (key) {
+    var raw = getString(key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new errors_1.APIError({
+            error: new Error("Config key \"".concat(key, "\" is not valid JSON: ").concat(error.message)),
+            status: 500,
+            title: "Config key \"".concat(key, "\" is not valid JSON"),
+        });
+    }
+};
+/**
+ * Registers a loader that returns the env map (typically backed by an
+ * admin-editable Mongoose document). Called once at app startup before
+ * the first `Config.refresh()`.
+ */
+var setEnvLoader = function (loader) {
+    envLoader = loader;
+};
+/**
+ * Reloads the in-memory cache by invoking the registered env loader. No-op
+ * (clears cache) if no loader has been registered.
+ */
+var refresh = function () { return __awaiter(void 0, void 0, void 0, function () {
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                if (!envLoader) {
+                    cachedEnv = {};
+                    return [2 /*return*/];
+                }
+                return [4 /*yield*/, envLoader()];
+            case 1:
+                cachedEnv = _a.sent();
+                return [2 /*return*/];
+        }
+    });
+}); };
+/** Replaces the cache directly. Intended for the envConfigurationPlugin and tests. */
+var setCachedEnv = function (env) {
+    cachedEnv = env;
+};
+/**
+ * Sets an in-process override for `key`. Highest precedence — wins over
+ * the cached env map. Intended for tests and bootstrap helpers.
+ */
+var setOverride = function (key, value) {
+    overrides.set(key, value);
+};
+/** Clears every override. Call from afterEach in tests. */
+var clearOverrides = function () {
+    overrides.clear();
+};
+/** Returns the registered default (if any) for `key`. */
+var getDefault = function (key) {
+    var _a;
+    return (_a = REGISTRY[key]) === null || _a === void 0 ? void 0 : _a.default;
+};
+/** Returns the registration metadata for `key`, including secret/description. */
+var getRegistration = function (key) {
+    return REGISTRY[key];
+};
+/** Returns the registered keys, sorted. Used by the admin UI. */
+var getRegisteredKeys = function () {
+    return Object.keys(REGISTRY).sort();
+};
+/** Returns true if `key` was registered. */
+var isRegistered = function (key) {
+    return key in REGISTRY;
+};
+/** Removes every registered key. Intended for tests. */
+var clearRegistryForTesting = function () {
+    var e_1, _a;
+    try {
+        for (var _b = __values(Object.keys(REGISTRY)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var key = _c.value;
+            delete REGISTRY[key];
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+};
+exports.Config = {
+    clearOverrides: clearOverrides,
+    clearRegistryForTesting: clearRegistryForTesting,
+    get: getString,
+    getBoolean: getBoolean,
+    getDefault: getDefault,
+    getJSON: getJSON,
+    getNumber: getNumber,
+    getRegisteredKeys: getRegisteredKeys,
+    getRegistration: getRegistration,
+    isRegistered: isRegistered,
+    refresh: refresh,
+    register: register,
+    setCachedEnv: setCachedEnv,
+    setEnvLoader: setEnvLoader,
+    setOverride: setOverride,
+};

package/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config.test.js

@@ -0,0 +1,328 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var bun_test_1 = require("bun:test");
+var config_1 = require("./config");
+var KEYS = [
+    "TERRENO_CFG_STRING",
+    "TERRENO_CFG_DEFAULTED",
+    "TERRENO_CFG_NUM",
+    "TERRENO_CFG_BOOL",
+    "TERRENO_CFG_JSON",
+    "TERRENO_CFG_UNDEFAULTED",
+    "TERRENO_CFG_UNREGISTERED",
+];
+var resetEnv = function () {
+    var e_1, _a;
+    try {
+        for (var KEYS_1 = __values(KEYS), KEYS_1_1 = KEYS_1.next(); !KEYS_1_1.done; KEYS_1_1 = KEYS_1.next()) {
+            var key = KEYS_1_1.value;
+            Reflect.deleteProperty(process.env, key);
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (KEYS_1_1 && !KEYS_1_1.done && (_a = KEYS_1.return)) _a.call(KEYS_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+};
+(0, bun_test_1.describe)("Config", function () {
+    (0, bun_test_1.beforeEach)(function () {
+        config_1.Config.clearRegistryForTesting();
+        config_1.Config.clearOverrides();
+        config_1.Config.setCachedEnv(null);
+        config_1.Config.setEnvLoader(null);
+        resetEnv();
+        config_1.Config.register("TERRENO_CFG_STRING");
+        config_1.Config.register("TERRENO_CFG_DEFAULTED", { default: "fallback" });
+        config_1.Config.register("TERRENO_CFG_NUM", { default: "1000" });
+        config_1.Config.register("TERRENO_CFG_BOOL", { default: "false" });
+        config_1.Config.register("TERRENO_CFG_JSON", { default: "{}" });
+        config_1.Config.register("TERRENO_CFG_UNDEFAULTED");
+    });
+    (0, bun_test_1.afterEach)(function () {
+        resetEnv();
+        config_1.Config.clearRegistryForTesting();
+        config_1.Config.clearOverrides();
+        config_1.Config.setCachedEnv(null);
+        config_1.Config.setEnvLoader(null);
+    });
+    (0, bun_test_1.describe)("resolution order", function () {
+        (0, bun_test_1.it)("returns the registered default when nothing is set", function () {
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+        });
+        (0, bun_test_1.it)("returns process.env when set and no cache/override is present", function () {
+            process.env.TERRENO_CFG_STRING = "fromEnv";
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBe("fromEnv");
+        });
+        (0, bun_test_1.it)("cache wins over process.env", function () {
+            process.env.TERRENO_CFG_STRING = "fromEnv";
+            config_1.Config.setCachedEnv({ TERRENO_CFG_STRING: "fromCache" });
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBe("fromCache");
+        });
+        (0, bun_test_1.it)("override wins over cache and process.env", function () {
+            process.env.TERRENO_CFG_STRING = "fromEnv";
+            config_1.Config.setCachedEnv({ TERRENO_CFG_STRING: "fromCache" });
+            config_1.Config.setOverride("TERRENO_CFG_STRING", "fromOverride");
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBe("fromOverride");
+        });
+        (0, bun_test_1.it)("falls through empty-string cache values to process.env", function () {
+            process.env.TERRENO_CFG_STRING = "fromEnv";
+            config_1.Config.setCachedEnv({ TERRENO_CFG_STRING: "" });
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBe("fromEnv");
+        });
+        (0, bun_test_1.it)("falls through empty-string process.env to default", function () {
+            process.env.TERRENO_CFG_DEFAULTED = "";
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+        });
+        (0, bun_test_1.it)("returns undefined for an unregistered key with nothing set", function () {
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_UNREGISTERED")).toBeUndefined();
+        });
+        (0, bun_test_1.it)("returns process.env for an unregistered key when set", function () {
+            process.env.TERRENO_CFG_UNREGISTERED = "value";
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_UNREGISTERED")).toBe("value");
+        });
+        (0, bun_test_1.it)("setOverride(key, undefined) is treated as 'force unset'", function () {
+            process.env.TERRENO_CFG_STRING = "fromEnv";
+            config_1.Config.setOverride("TERRENO_CFG_STRING", undefined);
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBeUndefined();
+        });
+    });
+    (0, bun_test_1.describe)("getNumber", function () {
+        (0, bun_test_1.it)("parses numeric process.env values", function () {
+            process.env.TERRENO_CFG_NUM = "5000";
+            (0, bun_test_1.expect)(config_1.Config.getNumber("TERRENO_CFG_NUM")).toBe(5000);
+        });
+        (0, bun_test_1.it)("parses the registered default", function () {
+            (0, bun_test_1.expect)(config_1.Config.getNumber("TERRENO_CFG_NUM")).toBe(1000);
+        });
+        (0, bun_test_1.it)("returns undefined when no value is available", function () {
+            (0, bun_test_1.expect)(config_1.Config.getNumber("TERRENO_CFG_UNDEFAULTED")).toBeUndefined();
+        });
+        (0, bun_test_1.it)("throws on non-numeric values", function () {
+            process.env.TERRENO_CFG_NUM = "not-a-number";
+            (0, bun_test_1.expect)(function () { return config_1.Config.getNumber("TERRENO_CFG_NUM"); }).toThrow(/not a valid number/);
+        });
+        (0, bun_test_1.it)("throws on partially-numeric strings like '5000ms'", function () {
+            process.env.TERRENO_CFG_NUM = "5000ms";
+            (0, bun_test_1.expect)(function () { return config_1.Config.getNumber("TERRENO_CFG_NUM"); }).toThrow(/not a valid number/);
+        });
+        (0, bun_test_1.it)("supports floats", function () {
+            process.env.TERRENO_CFG_NUM = "3.14";
+            (0, bun_test_1.expect)(config_1.Config.getNumber("TERRENO_CFG_NUM")).toBe(3.14);
+        });
+    });
+    (0, bun_test_1.describe)("getBoolean", function () {
+        (0, bun_test_1.it)("returns true for 'true'", function () {
+            process.env.TERRENO_CFG_BOOL = "true";
+            (0, bun_test_1.expect)(config_1.Config.getBoolean("TERRENO_CFG_BOOL")).toBe(true);
+        });
+        (0, bun_test_1.it)("returns true for 'TRUE' (case-insensitive)", function () {
+            process.env.TERRENO_CFG_BOOL = "TRUE";
+            (0, bun_test_1.expect)(config_1.Config.getBoolean("TERRENO_CFG_BOOL")).toBe(true);
+        });
+        (0, bun_test_1.it)("returns false for 'false'", function () {
+            process.env.TERRENO_CFG_BOOL = "false";
+            (0, bun_test_1.expect)(config_1.Config.getBoolean("TERRENO_CFG_BOOL")).toBe(false);
+        });
+        (0, bun_test_1.it)("returns false when unset and default is 'false'", function () {
+            (0, bun_test_1.expect)(config_1.Config.getBoolean("TERRENO_CFG_BOOL")).toBe(false);
+        });
+        (0, bun_test_1.it)("returns false for any non-true string", function () {
+            process.env.TERRENO_CFG_BOOL = "yes";
+            (0, bun_test_1.expect)(config_1.Config.getBoolean("TERRENO_CFG_BOOL")).toBe(false);
+        });
+    });
+    (0, bun_test_1.describe)("getJSON", function () {
+        (0, bun_test_1.it)("parses valid JSON", function () {
+            process.env.TERRENO_CFG_JSON = JSON.stringify({ hook: "https://example.com" });
+            (0, bun_test_1.expect)(config_1.Config.getJSON("TERRENO_CFG_JSON")).toEqual({
+                hook: "https://example.com",
+            });
+        });
+        (0, bun_test_1.it)("parses the registered default", function () {
+            (0, bun_test_1.expect)(config_1.Config.getJSON("TERRENO_CFG_JSON")).toEqual({});
+        });
+        (0, bun_test_1.it)("returns undefined when nothing is set and no default exists", function () {
+            (0, bun_test_1.expect)(config_1.Config.getJSON("TERRENO_CFG_UNDEFAULTED")).toBeUndefined();
+        });
+        (0, bun_test_1.it)("throws on malformed JSON instead of silently returning undefined", function () {
+            process.env.TERRENO_CFG_JSON = "{not json";
+            (0, bun_test_1.expect)(function () { return config_1.Config.getJSON("TERRENO_CFG_JSON"); }).toThrow(/not valid JSON/);
+        });
+    });
+    (0, bun_test_1.describe)("registry", function () {
+        (0, bun_test_1.it)("exposes registered keys in sorted order", function () {
+            var keys = config_1.Config.getRegisteredKeys();
+            var sorted = __spreadArray([], __read(keys), false).sort();
+            (0, bun_test_1.expect)(keys).toEqual(sorted);
+        });
+        (0, bun_test_1.it)("isRegistered returns true for known keys", function () {
+            (0, bun_test_1.expect)(config_1.Config.isRegistered("TERRENO_CFG_STRING")).toBe(true);
+        });
+        (0, bun_test_1.it)("isRegistered returns false for unknown keys", function () {
+            (0, bun_test_1.expect)(config_1.Config.isRegistered("NOT_A_REAL_KEY")).toBe(false);
+        });
+        (0, bun_test_1.it)("getDefault returns the registered default", function () {
+            (0, bun_test_1.expect)(config_1.Config.getDefault("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+        });
+        (0, bun_test_1.it)("getDefault returns undefined for keys with no default", function () {
+            (0, bun_test_1.expect)(config_1.Config.getDefault("TERRENO_CFG_STRING")).toBeUndefined();
+        });
+        (0, bun_test_1.it)("getRegistration exposes secret + description metadata", function () {
+            config_1.Config.register("TERRENO_CFG_WITH_META", {
+                description: "A secret thing",
+                secret: true,
+            });
+            var meta = config_1.Config.getRegistration("TERRENO_CFG_WITH_META");
+            (0, bun_test_1.expect)(meta === null || meta === void 0 ? void 0 : meta.secret).toBe(true);
+            (0, bun_test_1.expect)(meta === null || meta === void 0 ? void 0 : meta.description).toBe("A secret thing");
+        });
+        (0, bun_test_1.it)("re-registering the same key throws", function () {
+            (0, bun_test_1.expect)(function () { return config_1.Config.register("TERRENO_CFG_STRING"); }).toThrow(/registered more than once/);
+        });
+        (0, bun_test_1.it)("does not treat Object prototype keys as registered", function () {
+            (0, bun_test_1.expect)(config_1.Config.isRegistered("constructor")).toBe(false);
+            (0, bun_test_1.expect)(config_1.Config.isRegistered("toString")).toBe(false);
+            (0, bun_test_1.expect)(config_1.Config.isRegistered("hasOwnProperty")).toBe(false);
+            // And re-registering one of these names should still succeed.
+            (0, bun_test_1.expect)(function () { return config_1.Config.register("toString", { default: "x" }); }).not.toThrow();
+            (0, bun_test_1.expect)(config_1.Config.get("toString")).toBe("x");
+        });
+    });
+    (0, bun_test_1.describe)("clearOverrides", function () {
+        (0, bun_test_1.it)("removes all overrides", function () {
+            config_1.Config.setOverride("TERRENO_CFG_STRING", "x");
+            config_1.Config.setOverride("TERRENO_CFG_DEFAULTED", "y");
+            config_1.Config.clearOverrides();
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBeUndefined();
+            (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_DEFAULTED")).toBe("fallback");
+        });
+    });
+    (0, bun_test_1.describe)("refresh", function () {
+        (0, bun_test_1.it)("loads values via the registered env loader", function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        config_1.Config.setEnvLoader(function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, ({ TERRENO_CFG_STRING: "fromLoader" })];
+                        }); }); });
+                        return [4 /*yield*/, config_1.Config.refresh()];
+                    case 1:
+                        _a.sent();
+                        (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBe("fromLoader");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("clears the cache when no loader is registered", function () { return __awaiter(void 0, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        config_1.Config.setCachedEnv({ TERRENO_CFG_STRING: "stale" });
+                        config_1.Config.setEnvLoader(null);
+                        return [4 /*yield*/, config_1.Config.refresh()];
+                    case 1:
+                        _a.sent();
+                        (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBeUndefined();
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+        (0, bun_test_1.it)("updates the cache on each refresh", function () { return __awaiter(void 0, void 0, void 0, function () {
+            var payload;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        payload = { TERRENO_CFG_STRING: "first" };
+                        config_1.Config.setEnvLoader(function () { return __awaiter(void 0, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, payload];
+                        }); }); });
+                        return [4 /*yield*/, config_1.Config.refresh()];
+                    case 1:
+                        _a.sent();
+                        (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBe("first");
+                        payload = { TERRENO_CFG_STRING: "second" };
+                        return [4 /*yield*/, config_1.Config.refresh()];
+                    case 2:
+                        _a.sent();
+                        (0, bun_test_1.expect)(config_1.Config.get("TERRENO_CFG_STRING")).toBe("second");
+                        return [2 /*return*/];
+                }
+            });
+        }); });
+    });
+});

package/dist/configuration.test.js

@@ -72,6 +72,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
 var bun_test_1 = require("bun:test");
 var mongoose_1 = __importStar(require("mongoose"));
 var supertest_1 = __importDefault(require("supertest"));

package/dist/configurationApp.d.ts

@@ -9,7 +9,7 @@ interface ConfigFieldMeta {
     required: boolean;
     description?: string;
     enum?: string[];
-    default?: any;
+    default?: unknown;
     secret?: boolean;
     widget?: string;
 }