@theunwalked/cardigantime 0.0.7 → 0.0.8

package/dist/cardigantime.cjs

@@ -187,7 +187,8 @@ class ArgumentError extends Error {
  */ const DEFAULT_OPTIONS = {
     configFile: DEFAULT_CONFIG_FILE,
     isRequired: false,
-    encoding: DEFAULT_ENCODING
+    encoding: DEFAULT_ENCODING,
+    pathResolution: undefined
 };
 /**
  * Default features enabled when creating a Cardigantime instance.
@@ -415,6 +416,62 @@ const create$1 = (params)=>{
     };
 };
 
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ */ function resolveConfigPaths$1(config, configDir, pathFields = [], resolvePathArray = []) {
+    if (!config || typeof config !== 'object' || pathFields.length === 0) {
+        return config;
+    }
+    const resolvedConfig = {
+        ...config
+    };
+    for (const fieldPath of pathFields){
+        const value = getNestedValue$1(resolvedConfig, fieldPath);
+        if (value !== undefined) {
+            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);
+            const resolvedValue = resolvePathValue$1(value, configDir, shouldResolveArrayElements);
+            setNestedValue$1(resolvedConfig, fieldPath, resolvedValue);
+        }
+    }
+    return resolvedConfig;
+}
+/**
+ * Gets a nested value from an object using dot notation.
+ */ function getNestedValue$1(obj, path) {
+    return path.split('.').reduce((current, key)=>current === null || current === void 0 ? void 0 : current[key], obj);
+}
+/**
+ * Sets a nested value in an object using dot notation.
+ */ function setNestedValue$1(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    const target = keys.reduce((current, key)=>{
+        if (!(key in current)) {
+            current[key] = {};
+        }
+        return current[key];
+    }, obj);
+    target[lastKey] = value;
+}
+/**
+ * Resolves a path value (string or array of strings) relative to the config directory.
+ */ function resolvePathValue$1(value, configDir, resolveArrayElements) {
+    if (typeof value === 'string') {
+        return resolveSinglePath$1(value, configDir);
+    }
+    if (Array.isArray(value) && resolveArrayElements) {
+        return value.map((item)=>typeof item === 'string' ? resolveSinglePath$1(item, configDir) : item);
+    }
+    return value;
+}
+/**
+ * Resolves a single path string relative to the config directory if it's a relative path.
+ */ function resolveSinglePath$1(pathStr, configDir) {
+    if (!pathStr || path.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path.resolve(configDir, pathStr);
+}
 /**
  * Discovers configuration directories by traversing up the directory tree.
  * 
@@ -493,8 +550,10 @@ const create$1 = (params)=>{
  * @param configFileName Name of the configuration file
  * @param encoding File encoding
  * @param logger Optional logger
+ * @param pathFields Optional array of field names that contain paths to be resolved
+ * @param resolvePathArray Optional array of field names whose array elements should all be resolved as paths
  * @returns Promise resolving to parsed configuration object or null if not found
- */ async function loadConfigFromDirectory(configDir, configFileName, encoding = 'utf8', logger) {
+ */ async function loadConfigFromDirectory(configDir, configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray) {
     const storage = create$1({
         log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
     });
@@ -514,8 +573,13 @@ const create$1 = (params)=>{
         const yamlContent = await storage.readFile(configFilePath, encoding);
         const parsedYaml = yaml__namespace.load(yamlContent);
         if (parsedYaml !== null && typeof parsedYaml === 'object') {
+            let config = parsedYaml;
+            // Apply path resolution if configured
+            if (pathFields && pathFields.length > 0) {
+                config = resolveConfigPaths$1(config, configDir, pathFields, resolvePathArray || []);
+            }
             logger === null || logger === void 0 ? void 0 : logger.verbose(`Successfully loaded config from: ${configFilePath}`);
-            return parsedYaml;
+            return config;
         } else {
             logger === null || logger === void 0 ? void 0 : logger.debug(`Config file contains invalid format: ${configFilePath}`);
             return null;
@@ -622,7 +686,7 @@ const create$1 = (params)=>{
  * // result.errors contains any non-fatal errors
  * ```
  */ async function loadHierarchicalConfig(options) {
-    const { configFileName, encoding = 'utf8', logger } = options;
+    const { configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray } = options;
     logger === null || logger === void 0 ? void 0 : logger.verbose('Starting hierarchical configuration loading');
     // Discover all configuration directories
     const discoveredDirs = await discoverConfigDirectories(options);
@@ -643,7 +707,7 @@ const create$1 = (params)=>{
     ].sort((a, b)=>b.level - a.level);
     for (const dir of sortedDirs){
         try {
-            const config = await loadConfigFromDirectory(dir.path, configFileName, encoding, logger);
+            const config = await loadConfigFromDirectory(dir.path, configFileName, encoding, logger, pathFields, resolvePathArray);
             if (config !== null) {
                 configs.push(config);
                 logger === null || logger === void 0 ? void 0 : logger.debug(`Loaded config from level ${dir.level}: ${dir.path}`);
@@ -675,6 +739,68 @@ const create$1 = (params)=>{
  */ function clean(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([_, v])=>v !== undefined));
 }
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ * 
+ * @param config - The configuration object to process
+ * @param configDir - The directory containing the configuration file
+ * @param pathFields - Array of field names (using dot notation) that contain paths to be resolved
+ * @param resolvePathArray - Array of field names whose array elements should all be resolved as paths
+ * @returns The configuration object with resolved paths
+ */ function resolveConfigPaths(config, configDir, pathFields = [], resolvePathArray = []) {
+    if (!config || typeof config !== 'object' || pathFields.length === 0) {
+        return config;
+    }
+    const resolvedConfig = {
+        ...config
+    };
+    for (const fieldPath of pathFields){
+        const value = getNestedValue(resolvedConfig, fieldPath);
+        if (value !== undefined) {
+            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);
+            const resolvedValue = resolvePathValue(value, configDir, shouldResolveArrayElements);
+            setNestedValue(resolvedConfig, fieldPath, resolvedValue);
+        }
+    }
+    return resolvedConfig;
+}
+/**
+ * Gets a nested value from an object using dot notation.
+ */ function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key)=>current === null || current === void 0 ? void 0 : current[key], obj);
+}
+/**
+ * Sets a nested value in an object using dot notation.
+ */ function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    const target = keys.reduce((current, key)=>{
+        if (!(key in current)) {
+            current[key] = {};
+        }
+        return current[key];
+    }, obj);
+    target[lastKey] = value;
+}
+/**
+ * Resolves a path value (string or array of strings) relative to the config directory.
+ */ function resolvePathValue(value, configDir, resolveArrayElements) {
+    if (typeof value === 'string') {
+        return resolveSinglePath(value, configDir);
+    }
+    if (Array.isArray(value) && resolveArrayElements) {
+        return value.map((item)=>typeof item === 'string' ? resolveSinglePath(item, configDir) : item);
+    }
+    return value;
+}
+/**
+ * Resolves a single path string relative to the config directory if it's a relative path.
+ */ function resolveSinglePath(pathStr, configDir) {
+    if (!pathStr || path__namespace.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path__namespace.resolve(configDir, pathStr);
+}
 /**
  * Validates and secures a user-provided path to prevent path traversal attacks.
  * 
@@ -758,7 +884,7 @@ const create$1 = (params)=>{
  * // config is fully typed based on your schema
  * ```
  */ const read = async (args, options)=>{
-    var _options_defaults;
+    var _options_defaults, _options_defaults_pathResolution;
     const logger = options.logger;
     const rawConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
     if (!rawConfigDir) {
@@ -771,6 +897,7 @@ const create$1 = (params)=>{
     if (options.features.includes('hierarchical')) {
         logger.verbose('Hierarchical configuration discovery enabled');
         try {
+            var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
             // Extract the config directory name from the path for hierarchical discovery
             const configDirName = path__namespace.basename(resolvedConfigDir);
             const startingDir = path__namespace.dirname(resolvedConfigDir);
@@ -780,7 +907,9 @@ const create$1 = (params)=>{
                 configFileName: options.defaults.configFile,
                 startingDir,
                 encoding: options.defaults.encoding,
-                logger
+                logger,
+                pathFields: (_options_defaults_pathResolution1 = options.defaults.pathResolution) === null || _options_defaults_pathResolution1 === void 0 ? void 0 : _options_defaults_pathResolution1.pathFields,
+                resolvePathArray: (_options_defaults_pathResolution2 = options.defaults.pathResolution) === null || _options_defaults_pathResolution2 === void 0 ? void 0 : _options_defaults_pathResolution2.resolvePathArray
             });
             rawFileConfig = hierarchicalResult.config;
             if (hierarchicalResult.discoveredDirs.length > 0) {
@@ -805,8 +934,13 @@ const create$1 = (params)=>{
         logger.verbose('Using single directory configuration loading');
         rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
     }
+    // Apply path resolution if configured
+    let processedConfig = rawFileConfig;
+    if ((_options_defaults_pathResolution = options.defaults.pathResolution) === null || _options_defaults_pathResolution === void 0 ? void 0 : _options_defaults_pathResolution.pathFields) {
+        processedConfig = resolveConfigPaths(rawFileConfig, resolvedConfigDir, options.defaults.pathResolution.pathFields, options.defaults.pathResolution.resolvePathArray || []);
+    }
     const config = clean({
-        ...rawFileConfig,
+        ...processedConfig,
         ...{
             configDirectory: resolvedConfigDir
         }
@@ -1175,6 +1309,7 @@ class ConfigurationError extends Error {
  * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')
  * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)
  * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')
+ * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)
  * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])
  * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)
  * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)
@@ -1189,15 +1324,25 @@ class ConfigurationError extends Error {
  *   apiKey: z.string().min(1),
  *   timeout: z.number().default(5000),
  *   debug: z.boolean().default(false),
+ *   contextDirectories: z.array(z.string()).optional(),
  * });
  * 
  * const cardigantime = create({
  *   defaults: {
  *     configDirectory: './config',
  *     configFile: 'myapp.yaml',
+ *     // Resolve relative paths in contextDirectories relative to config file location
+ *     pathResolution: {
+ *       pathFields: ['contextDirectories'],
+ *       resolvePathArray: ['contextDirectories']
+ *     }
  *   },
  *   configShape: MyConfigSchema.shape,
  * });
+ * 
+ * // If config file is at ../config/myapp.yaml and contains:
+ * // contextDirectories: ['./context', './data']
+ * // These paths will be resolved relative to ../config/ directory
  * ```
  */ const create = (pOptions)=>{
     const defaults = {