@decaf-ts/integrations 0.10.8 → 0.11.0

package/lib/cjs/feature-flags/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"feature-flags/index.cjs","sourceRoot":"","sources":["feature-flags/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;GAGG;AACH,iDAA+B;AAC/B,6CAA2B;AAC3B,6CAA2B;AAC3B,mDAAiC;AACjC,gEAA8C;AAC9C,sEAAoD;AACpD,qDAAmC;AACnC,oEAAkD;AAClD,kDAAgC;AAChC,iCAAiC"}
+{"version":3,"file":"feature-flags/index.cjs","sourceRoot":"","sources":["feature-flags/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;GAGG;AACH,iDAA+B;AAC/B,6CAA2B;AAC3B,6CAA2B;AAC3B,mDAAiC;AACjC,gEAA8C;AAC9C,sEAAoD;AACpD,qDAAmC;AACnC,oEAAkD;AAClD,2EAAyD;AACzD,kDAAgC;AAChC,iCAAiC"}

package/lib/cjs/index.cjs

@@ -23,9 +23,9 @@ exports.PACKAGE_NAME = exports.FULL_VERSION = exports.COMMIT = exports.VERSION =
 __exportStar(require("./utils.cjs"), exports);
 __exportStar(require("./namespaces/index.cjs"), exports);
 __exportStar(require("./feature-flags/index.cjs"), exports);
-exports.VERSION = "0.10.7";
-exports.COMMIT = "9f5df0a";
-exports.FULL_VERSION = "0.10.7-9f5df0a";
+exports.VERSION = "0.10.8";
+exports.COMMIT = "6c774f8";
+exports.FULL_VERSION = "0.10.8-6c774f8";
 exports.PACKAGE_NAME = "@decaf-ts/integrations";
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.cjs.map

package/lib/cjs/loader/ObjectLoader.cjs

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObjectLoader = void 0;
 exports.createLoaderHookContext = createLoaderHookContext;
+exports.moduleReference = moduleReference;
 const path_1 = require("path");
 const url_1 = require("url");
 function isPathLikeSource(source) {
@@ -49,12 +50,26 @@ function isPathLikeSource(source) {
  * @description Base loader and concrete family loaders for dynamically
  * resolving Decaf integration objects without forcing callers to duplicate
  * import, selection, or post-load hook logic.
+ *
+ * ## Tree-shaking / build-time references
+ *
+ * Dynamic imports are resolved at runtime, so a bundler cannot see which modules
+ * are actually reachable and may drop them from the output. To keep a module
+ * available, keep a *static* reference to it somewhere in the entry graph (for
+ * example a `loaderManifest` object or a side-effect import) while the runtime
+ * lookup still goes through {@link ObjectLoader.loadModule}. Prefer passing the
+ * specifier as a variable (`import(specifier)`) instead of a string literal:
+ * bundlers leave non-literal dynamic imports untouched, which preserves the
+ * lazy/runtime semantics. See {@link moduleReference} for a small helper that
+ * encodes this pattern.
  */
 class ObjectLoader {
     constructor(options = {}) {
         this.family = options.family ?? "generic";
         this.defaultExportName = options.defaultExportName ?? "default";
         this.hooks = options.hooks ?? [];
+        this.beforeResolveHooks = options.beforeResolveHooks ?? [];
+        this.metadata = options.metadata ?? {};
     }
     normalizeSource(source) {
         if (source instanceof URL) {
@@ -81,9 +96,13 @@ class ObjectLoader {
             if (exportedNames.length === 1) {
                 return module[exportedNames[0]];
             }
+            // Pre-existing raw Error kept for backward compatibility. New code paths
+            // must throw a decaf error hierarchy subclass instead.
             throw new Error(`Module "${source}" does not expose a default export.`);
         }
         if (!(exportName in module)) {
+            // Pre-existing raw Error kept for backward compatibility. New code paths
+            // must throw a decaf error hierarchy subclass instead.
             throw new Error(`Module "${source}" does not export "${exportName}".`);
         }
         return module[exportName];
@@ -98,6 +117,43 @@ class ObjectLoader {
         }
         return current;
     }
+    /**
+     * @summary Build the hook context for a load operation.
+     * @description Concrete loaders call this to build a context that carries the
+     * load phase and any loader-specific metadata into hooks.
+     */
+    createContext(source, exportName, module, phase, metadata = this.metadata) {
+        return {
+            family: this.family,
+            source,
+            exportName,
+            module,
+            loaderName: this.constructor.name,
+            phase,
+            metadata,
+        };
+    }
+    /**
+     * @summary Run the configured export hooks against a value.
+     * @description Exposed to concrete loaders that load content (assets, configs)
+     * instead of importing a module, so they can reuse the same hook pipeline.
+     */
+    async runHooks(value, context, options = {}) {
+        const hooks = [...this.hooks, ...(options.hooks ?? [])];
+        return this.applyHooks(value, context, hooks);
+    }
+    /**
+     * @summary Run the configured pre-resolve hooks against a module namespace.
+     */
+    async runBeforeResolveHooks(module, context, options = {}) {
+        const hooks = [
+            ...this.beforeResolveHooks,
+            ...(options.beforeResolveHooks ?? []),
+        ];
+        if (!hooks.length)
+            return module;
+        return this.applyHooks(module, context, hooks);
+    }
     createInstance(options) {
         const Loader = this.constructor;
         return new Loader(options);
@@ -107,17 +163,12 @@ class ObjectLoader {
     }
     async loadExport(source, exportName = this.defaultExportName, options = {}) {
         const normalizedSource = this.normalizeSource(source);
-        const module = await this.importModule(normalizedSource);
+        const imported = await this.importModule(normalizedSource);
+        const beforeResolveContext = this.createContext(normalizedSource, exportName, imported, "beforeResolve", options.metadata ?? this.metadata);
+        const module = await this.runBeforeResolveHooks(imported, beforeResolveContext, options);
         const resolved = this.resolveExport(module, exportName, normalizedSource);
-        const hookContext = {
-            family: this.family,
-            source: normalizedSource,
-            exportName,
-            module,
-            loaderName: this.constructor.name,
-        };
-        const hooks = [...this.hooks, ...(options.hooks ?? [])];
-        return this.applyHooks(resolved, hookContext, hooks);
+        const afterResolveContext = this.createContext(normalizedSource, exportName, module, "afterResolve", options.metadata ?? this.metadata);
+        return this.runHooks(resolved, afterResolveContext, options);
     }
     async loadDefault(source, options = {}) {
         return this.loadExport(source, this.defaultExportName, options);
@@ -130,6 +181,17 @@ class ObjectLoader {
             family: this.family,
             defaultExportName: this.defaultExportName,
             hooks: [...this.hooks, ...hooks],
+            beforeResolveHooks: [...this.beforeResolveHooks],
+            metadata: this.metadata,
+        });
+    }
+    withBeforeResolveHooks(...hooks) {
+        return this.createInstance({
+            family: this.family,
+            defaultExportName: this.defaultExportName,
+            hooks: [...this.hooks],
+            beforeResolveHooks: [...this.beforeResolveHooks, ...hooks],
+            metadata: this.metadata,
         });
     }
     withOptions(options) {
@@ -137,18 +199,40 @@ class ObjectLoader {
             family: options.family ?? this.family,
             defaultExportName: options.defaultExportName ?? this.defaultExportName,
             hooks: [...this.hooks, ...(options.hooks ?? [])],
+            beforeResolveHooks: [
+                ...this.beforeResolveHooks,
+                ...(options.beforeResolveHooks ?? []),
+            ],
+            metadata: { ...this.metadata, ...(options.metadata ?? {}) },
         });
     }
 }
 exports.ObjectLoader = ObjectLoader;
-function createLoaderHookContext(loader, module, source, exportName) {
+function createLoaderHookContext(loader, module, source, exportName, phase = "afterResolve", metadata = {}) {
     return {
         family: loader.family,
         source,
         exportName,
         module,
         loaderName: loader.constructor.name,
+        phase,
+        metadata,
     };
 }
+/**
+ * @summary Build a lazy module reference that survives bundling.
+ * @description Pass a *variable* specifier to `import()` so bundlers do not
+ * statically inline or drop the target. Pair it with a static reference in your
+ * entry graph when the module must be retained:
+ *
+ * ```ts
+ * export const loaderManifest = { feature: "./feature/index.cjs" } as const;
+ * const reference = moduleReference(loaderManifest.feature);
+ * const module = await reference();
+ * ```
+ */
+function moduleReference(specifier) {
+    return () => Promise.resolve(`${specifier}`).then(s => __importStar(require(s)));
+}
 //# sourceMappingURL=ObjectLoader.js.map
 //# sourceMappingURL=ObjectLoader.cjs.map

package/lib/cjs/loader/ObjectLoader.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"loader/ObjectLoader.cjs","sourceRoot":"","sources":["loader/ObjectLoader.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"loader/ObjectLoader.cjs","sourceRoot":"","sources":["loader/ObjectLoader.js"],"names":[],"mappings":"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"}

package/lib/cjs/loader/assets.cjs

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetObjectLoader = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const core_1 = require("@decaf-ts/core");
+const ObjectLoader_js_1 = require("./ObjectLoader.cjs");
+const TEXT_EXTENSIONS = new Set([
+    ".txt",
+    ".md",
+    ".csv",
+    ".html",
+    ".htm",
+    ".xml",
+    ".yaml",
+    ".yml",
+    ".graphql",
+    ".sql",
+]);
+const IMAGE_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".ico",
+    ".avif",
+    ".tiff",
+]);
+const CONTENT_TYPES = {
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".xml": "application/xml",
+    ".yaml": "application/yaml",
+    ".yml": "application/yaml",
+    ".sql": "application/sql",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".avif": "image/avif",
+    ".tiff": "image/tiff",
+};
+function contentTypeFor(extension) {
+    return CONTENT_TYPES[extension] ?? "application/octet-stream";
+}
+/**
+ * @summary Load asset files as content instead of importing a class.
+ * @description Assets (locale files, images, templates, ...) are *not* modules;
+ * they are read from disk and decoded. Hooks run on the {@link LoadedAsset}
+ * record so callers can inspect or replace content before it enters the system.
+ *
+ * A `"json"` encoding parses the file content, `"utf8"` returns text,
+ * `"base64"` returns a base64 string, and `"binary"` returns the raw
+ * `Buffer`. `"auto"` picks `json` for `.json`, `utf8` for known text
+ * extensions, and `binary` otherwise.
+ */
+class AssetObjectLoader extends ObjectLoader_js_1.ObjectLoader {
+    constructor(options = {}) {
+        super({ ...options, family: "asset" });
+    }
+    async loadAsset(source, options = {}) {
+        const path = this.toFilePath(source);
+        const name = (0, node_path_1.basename)(path);
+        const extension = (0, node_path_1.extname)(path).toLowerCase();
+        const encoding = this.resolveEncoding(extension, options.encoding ?? "auto");
+        const buffer = await (0, promises_1.readFile)(path);
+        const content = this.decode(buffer, encoding);
+        const asset = {
+            source: this.normalizeSource(source),
+            path,
+            name,
+            extension,
+            encoding,
+            contentType: contentTypeFor(extension),
+            content,
+        };
+        const context = this.createContext(asset.source, name, {}, "afterResolve", {
+            ...this.metadata,
+            ...(options.metadata ?? {}),
+            encoding,
+            contentType: asset.contentType,
+        });
+        return this.runHooks(asset, context, options);
+    }
+    async loadText(source, options = {}) {
+        const asset = await this.loadAsset(source, {
+            ...options,
+            encoding: options.encoding && options.encoding !== "auto"
+                ? options.encoding
+                : "utf8",
+        });
+        return asset.content;
+    }
+    async loadJson(source, options = {}) {
+        const asset = await this.loadAsset(source, {
+            ...options,
+            encoding: "json",
+        });
+        return asset.content;
+    }
+    async loadBinary(source, options = {}) {
+        const asset = await this.loadAsset(source, {
+            ...options,
+            encoding: "binary",
+        });
+        return asset.content;
+    }
+    resolveEncoding(extension, requested) {
+        if (requested !== "auto")
+            return requested;
+        if (extension === ".json")
+            return "json";
+        if (TEXT_EXTENSIONS.has(extension))
+            return "utf8";
+        if (IMAGE_EXTENSIONS.has(extension))
+            return "binary";
+        return "binary";
+    }
+    decode(buffer, encoding) {
+        switch (encoding) {
+            case "json":
+                return JSON.parse(buffer.toString("utf8"));
+            case "base64":
+                return buffer.toString("base64");
+            case "binary":
+                return buffer;
+            case "utf8":
+            default:
+                return buffer.toString("utf8");
+        }
+    }
+    toFilePath(source) {
+        if (source instanceof URL) {
+            if (source.protocol !== "file:") {
+                throw new core_1.UnsupportedError(`AssetObjectLoader only supports local file sources, received "${source.href}".`);
+            }
+            return (0, node_url_1.fileURLToPath)(source);
+        }
+        if (source.startsWith("file:")) {
+            return (0, node_url_1.fileURLToPath)(source);
+        }
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(source)) {
+            throw new core_1.UnsupportedError(`AssetObjectLoader only supports local file sources, received "${source}".`);
+        }
+        return (0, node_path_1.isAbsolute)(source) ? source : (0, node_path_1.resolve)(source);
+    }
+}
+exports.AssetObjectLoader = AssetObjectLoader;
+//# sourceMappingURL=assets.js.map
+//# sourceMappingURL=assets.cjs.map

package/lib/cjs/loader/assets.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader/assets.cjs","sourceRoot":"","sources":["loader/assets.js"],"names":[],"mappings":";;;AAAA,+CAA4C;AAC5C,yCAAmE;AACnE,uCAAyC;AACzC,yCAAkD;AAClD,uDAAiD;AACjD,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC5B,MAAM;IACN,KAAK;IACL,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,UAAU;IACV,MAAM;CACT,CAAC,CAAC;AACH,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IAC7B,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;IACP,MAAM;IACN,MAAM;IACN,OAAO;IACP,OAAO;CACV,CAAC,CAAC;AACH,MAAM,aAAa,GAAG;IAClB,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,eAAe;IACtB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,iBAAiB;IACzB,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,kBAAkB;IAC1B,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,cAAc;IACtB,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,YAAY;CACxB,CAAC;AACF,SAAS,cAAc,CAAC,SAAS;IAC7B,OAAO,aAAa,CAAC,SAAS,CAAC,IAAI,0BAA0B,CAAC;AAClE,CAAC;AACD;;;;;;;;;;GAUG;AACH,MAAa,iBAAkB,SAAQ,8BAAY;IAC/C,YAAY,OAAO,GAAG,EAAE;QACpB,KAAK,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG,IAAA,oBAAQ,EAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,SAAS,GAAG,IAAA,mBAAO,EAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,CAAC;QAC7E,MAAM,MAAM,GAAG,MAAM,IAAA,mBAAQ,EAAC,IAAI,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG;YACV,MAAM,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC;YACpC,IAAI;YACJ,IAAI;YACJ,SAAS;YACT,QAAQ;YACR,WAAW,EAAE,cAAc,CAAC,SAAS,CAAC;YACtC,OAAO;SACV,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,cAAc,EAAE;YACvE,GAAG,IAAI,CAAC,QAAQ;YAChB,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;YAC3B,QAAQ;YACR,WAAW,EAAE,KAAK,CAAC,WAAW;SACjC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;QAC/B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;YACvC,GAAG,OAAO;YACV,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,MAAM;gBACrD,CAAC,CAAC,OAAO,CAAC,QAAQ;gBAClB,CAAC,CAAC,MAAM;SACf,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC;IACzB,CAAC;IACD,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;QAC/B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;YACvC,GAAG,OAAO;YACV,QAAQ,EAAE,MAAM;SACnB,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC;IACzB,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;QACjC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE;YACvC,GAAG,OAAO;YACV,QAAQ,EAAE,QAAQ;SACrB,CAAC,CAAC;QACH,OAAO,KAAK,CAAC,OAAO,CAAC;IACzB,CAAC;IACD,eAAe,CAAC,SAAS,EAAE,SAAS;QAChC,IAAI,SAAS,KAAK,MAAM;YACpB,OAAO,SAAS,CAAC;QACrB,IAAI,SAAS,KAAK,OAAO;YACrB,OAAO,MAAM,CAAC;QAClB,IAAI,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC;YAC9B,OAAO,MAAM,CAAC;QAClB,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC;YAC/B,OAAO,QAAQ,CAAC;QACpB,OAAO,QAAQ,CAAC;IACpB,CAAC;IACD,MAAM,CAAC,MAAM,EAAE,QAAQ;QACnB,QAAQ,QAAQ,EAAE,CAAC;YACf,KAAK,MAAM;gBACP,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YAC/C,KAAK,QAAQ;gBACT,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACrC,KAAK,QAAQ;gBACT,OAAO,MAAM,CAAC;YAClB,KAAK,MAAM,CAAC;YACZ;gBACI,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;IACL,CAAC;IACD,UAAU,CAAC,MAAM;QACb,IAAI,MAAM,YAAY,GAAG,EAAE,CAAC;YACxB,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;gBAC9B,MAAM,IAAI,uBAAgB,CAAC,iEAAiE,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC;YACjH,CAAC;YACD,OAAO,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAA,wBAAa,EAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,uBAAgB,CAAC,iEAAiE,MAAM,IAAI,CAAC,CAAC;QAC5G,CAAC;QACD,OAAO,IAAA,sBAAU,EAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAA,mBAAO,EAAC,MAAM,CAAC,CAAC;IACzD,CAAC;CACJ;AA1FD,8CA0FC;AACD,kCAAkC"}

package/lib/cjs/loader/config.cjs

@@ -0,0 +1,241 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigObjectLoader = exports.globalConfig = exports.GlobalConfigRegistry = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const core_1 = require("@decaf-ts/core");
+const db_decorators_1 = require("@decaf-ts/db-decorators");
+const ObjectLoader_js_1 = require("./ObjectLoader.cjs");
+const YAML_SPECIFIER = "yaml";
+/**
+ * @summary Minimal global config registry.
+ * @description A process-wide key/value store that concrete loaders register
+ * loaded configuration into. It is intentionally small: register a value under a
+ * key, read it back, list it, snapshot it, and optionally freeze it once boot
+ * configuration is complete.
+ *
+ * `GlobalConfigRegistry.reset()` clears the contents but keeps the singleton
+ * instance, so a `globalConfig` reference captured at import time stays valid.
+ */
+class GlobalConfigRegistry {
+    constructor() {
+        this.store = new Map();
+        this.frozen = false;
+    }
+    static get instance() {
+        if (!GlobalConfigRegistry.current) {
+            GlobalConfigRegistry.current = new GlobalConfigRegistry();
+        }
+        return GlobalConfigRegistry.current;
+    }
+    static reset() {
+        if (GlobalConfigRegistry.current) {
+            GlobalConfigRegistry.current.clear();
+        }
+    }
+    register(key, value, options = {}) {
+        if (this.frozen) {
+            throw new core_1.UnsupportedError(`The global config registry is frozen; cannot register key "${key}".`);
+        }
+        if (this.store.has(key) && !options.override) {
+            throw new db_decorators_1.ConflictError(`Global config key "${key}" is already registered. Pass override: true to replace it.`);
+        }
+        this.store.set(key, value);
+        return this;
+    }
+    get(key) {
+        return this.store.get(key);
+    }
+    require(key) {
+        if (!this.store.has(key)) {
+            throw new db_decorators_1.NotFoundError(`Global config key "${key}" is not registered.`);
+        }
+        return this.store.get(key);
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    keys() {
+        return [...this.store.keys()];
+    }
+    entries() {
+        return [...this.store.entries()];
+    }
+    snapshot() {
+        return Object.freeze(Object.fromEntries(this.store));
+    }
+    clear() {
+        this.store.clear();
+    }
+    freeze() {
+        this.frozen = true;
+        return this;
+    }
+    get isFrozen() {
+        return this.frozen;
+    }
+}
+exports.GlobalConfigRegistry = GlobalConfigRegistry;
+/** Process-wide config registry used by default. */
+exports.globalConfig = GlobalConfigRegistry.instance;
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof URL));
+}
+function isSourceLike(source) {
+    return typeof source === "string" || source instanceof URL;
+}
+/**
+ * @summary Load config sources into the global config registry.
+ * @description Supports inline objects, `.json` files, optional `.yaml`/`.yml`
+ * files, and JS/TS modules. Loaded configs run through the shared hook
+ * pipeline, then register under a key so the rest of the system can read them
+ * from {@link globalConfig}.
+ */
+class ConfigObjectLoader extends ObjectLoader_js_1.ObjectLoader {
+    constructor(options = {}) {
+        super({ ...options, family: "config" });
+        this.registry = options.registry ?? exports.globalConfig;
+    }
+    createInstance(options) {
+        return new ConfigObjectLoader({
+            ...options,
+            registry: this.registry,
+        });
+    }
+    /**
+     * @summary Load a config source, run hooks, and register it globally.
+     */
+    async loadConfig(source, options = {}) {
+        const { key, namespace, override, format = "auto", registry = this.registry, ...loadOptions } = options;
+        const value = await this.readConfig(source, format);
+        const resolvedKey = key ?? this.deriveKey(source, namespace);
+        const context = this.createContext(this.describeSource(source), resolvedKey, isPlainObject(value) ? value : {}, "afterResolve", {
+            ...this.metadata,
+            ...(options.metadata ?? {}),
+            key: resolvedKey,
+            namespace,
+        });
+        const processed = await this.runHooks(value, context, loadOptions);
+        registry.register(resolvedKey, processed, { override });
+        return processed;
+    }
+    /**
+     * @summary Alias for {@link ConfigObjectLoader.loadConfig}.
+     */
+    async loadAndRegister(source, options = {}) {
+        return this.loadConfig(source, options);
+    }
+    register(key, value, options = {}) {
+        const registry = options.registry ?? this.registry;
+        registry.register(key, value, { override: options.override });
+        return this;
+    }
+    get(key) {
+        return this.registry.get(key);
+    }
+    async readConfig(source, format) {
+        if (isPlainObject(source)) {
+            return source;
+        }
+        const normalized = this.normalizeSource(source);
+        const resolvedFormat = format === "auto" ? this.detectFormat(normalized) : format;
+        if (resolvedFormat === "json") {
+            return JSON.parse(await this.readText(normalized));
+        }
+        if (resolvedFormat === "yaml") {
+            const yaml = await this.loadYaml();
+            return yaml.parse(await this.readText(normalized));
+        }
+        const module = await this.importModule(normalized);
+        return this.resolveExport(module, this.defaultExportName, normalized);
+    }
+    detectFormat(source) {
+        const path = source.split("?")[0].toLowerCase();
+        if (path.endsWith(".json"))
+            return "json";
+        if (path.endsWith(".yaml") || path.endsWith(".yml"))
+            return "yaml";
+        return "module";
+    }
+    async readText(source) {
+        if (/^https?:\/\//i.test(source)) {
+            if (typeof fetch !== "function") {
+                throw new core_1.UnsupportedError(`Remote config source "${source}" requires a global fetch implementation.`);
+            }
+            const response = await fetch(source);
+            if (!response.ok) {
+                throw new core_1.UnsupportedError(`Remote config source "${source}" responded with ${response.status}.`);
+            }
+            return response.text();
+        }
+        const path = source.startsWith("file:")
+            ? (0, node_url_1.fileURLToPath)(source)
+            : (0, node_path_1.isAbsolute)(source)
+                ? source
+                : (0, node_path_1.resolve)(source);
+        return (0, promises_1.readFile)(path, "utf8");
+    }
+    async loadYaml() {
+        try {
+            return (await Promise.resolve(`${YAML_SPECIFIER}`).then(s => __importStar(require(s))));
+        }
+        catch (error) {
+            throw new core_1.UnsupportedError(`YAML config sources require the optional "yaml" package. ` +
+                `Install "yaml" or provide JSON/module config sources instead. ` +
+                `Cause: ${error?.message ?? String(error)}`);
+        }
+    }
+    deriveKey(source, namespace) {
+        const name = isSourceLike(source)
+            ? (0, node_path_1.basename)(this.describeSource(source)).replace(/\.[^.]+$/, "")
+            : "config";
+        return namespace ? `${namespace}:${name}` : name;
+    }
+    describeSource(source) {
+        if (source instanceof URL)
+            return source.href;
+        if (typeof source === "string")
+            return this.normalizeSource(source);
+        return "<inline>";
+    }
+}
+exports.ConfigObjectLoader = ConfigObjectLoader;
+//# sourceMappingURL=config.js.map
+//# sourceMappingURL=config.cjs.map

package/lib/cjs/loader/config.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader/config.cjs","sourceRoot":"","sources":["loader/config.js"],"names":[],"mappings":"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"}