@theunwalked/cardigantime 0.0.7 → 0.0.9

package/README.md

@@ -233,6 +233,60 @@ debug: true
 ./myapp --debug
 ```
 
+### Advanced Usage Examples
+
+#### Basic Configuration with Path Resolution
+
+```typescript
+import { create } from '@theunwalked/cardigantime';
+import { z } from 'zod';
+
+const MyConfigSchema = z.object({
+  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,
+});
+```
+
+#### Hierarchical Configuration with Custom Array Overlap
+
+```typescript
+const cardigantime = create({
+  defaults: {
+    configDirectory: '.myapp',
+    configFile: 'config.yaml',
+    fieldOverlaps: {
+      'features': 'append',              // Accumulate features from all levels
+      'excludePatterns': 'prepend',      // Higher precedence patterns come first
+      'api.endpoints': 'append',         // Nested field configuration
+      'security.allowedOrigins': 'append' // Security settings accumulate
+    }
+  },
+  configShape: MyConfigSchema.shape,
+  features: ['config', 'hierarchical'],  // Enable hierarchical discovery
+});
+```
+
+This configuration enables powerful composition scenarios where:
+- **Features** from all configuration levels are combined (e.g., base features + project features + local features)
+- **Exclude patterns** are layered with local patterns taking precedence
+- **API endpoints** can be extended at each level
+- **Security settings** accumulate for maximum flexibility
+
 ## Core Concepts
 
 ### 1. Configuration Sources & Precedence
@@ -297,6 +351,9 @@ database:
   ssl: false
 logging:
   level: info
+features:
+  - auth
+  - basic-logging
 
 # /home/user/projects/myproject/.kodrdriv/config.yaml (Level 1)  
 database:
@@ -304,14 +361,19 @@ database:
   ssl: true
 api:
   timeout: 5000
+features:
+  - advanced-logging
+  - metrics
 
 # /home/user/projects/myproject/submodule/.kodrdriv/config.yaml (Level 0)
 database:
   host: dev.example.com
 logging:
   level: debug
+features:
+  - debug-mode
 
-# Final merged configuration:
+# Final merged configuration (with default array behavior):
 database:
   host: dev.example.com    # From Level 0 (highest precedence)
   port: 5433               # From Level 1  
@@ -320,6 +382,79 @@ api:
   timeout: 5000            # From Level 1
 logging:
   level: debug             # From Level 0 (highest precedence)
+features:
+  - debug-mode             # From Level 0 (arrays override by default)
+```
+
+#### Configurable Array Overlap Behavior
+
+By default, arrays in hierarchical configurations follow the **override** behavior - arrays from higher precedence levels completely replace arrays from lower precedence levels. However, you can configure custom overlap behavior for array fields:
+
+```typescript
+const cardigantime = create({
+  defaults: { 
+    configDirectory: '.kodrdriv',
+    configFile: 'config.yaml',
+    fieldOverlaps: {
+      'features': 'append',           // Combine features by appending
+      'excludePatterns': 'prepend',   // Combine exclude patterns by prepending
+      'middlewares': 'override'       // Override middlewares (default behavior)
+    }
+  },
+  configShape: MyConfigSchema.shape,
+  features: ['config', 'hierarchical'],
+});
+```
+
+**Available Overlap Modes:**
+
+- **`override`** (default): Higher precedence arrays completely replace lower precedence arrays
+- **`append`**: Higher precedence array elements are appended to lower precedence arrays  
+- **`prepend`**: Higher precedence array elements are prepended to lower precedence arrays
+
+**Example with Custom Array Overlap:**
+
+```yaml
+# /home/user/projects/.kodrdriv/config.yaml (Level 2)
+features: ['auth', 'basic-logging']
+excludePatterns: ['*.tmp', '*.cache']
+
+# /home/user/projects/myproject/.kodrdriv/config.yaml (Level 1)  
+features: ['advanced-logging', 'metrics']
+excludePatterns: ['*.log']
+
+# /home/user/projects/myproject/submodule/.kodrdriv/config.yaml (Level 0)
+features: ['debug-mode']
+excludePatterns: ['*.debug']
+```
+
+With the configuration above (`features: 'append'`, `excludePatterns: 'prepend'`):
+
+```yaml
+# Final merged configuration:
+features: 
+  - auth              # From Level 2
+  - basic-logging     # From Level 2  
+  - advanced-logging  # From Level 1
+  - metrics           # From Level 1
+  - debug-mode        # From Level 0 (appended)
+excludePatterns:
+  - "*.debug"         # From Level 0 (prepended first)
+  - "*.log"           # From Level 1 (prepended second)  
+  - "*.tmp"           # From Level 2
+  - "*.cache"         # From Level 2
+```
+
+**Nested Field Paths:**
+
+You can configure overlap behavior for nested array fields using dot notation:
+
+```typescript
+fieldOverlaps: {
+  'api.endpoints': 'append',
+  'database.migrations': 'prepend',
+  'config.features.experimental': 'override'
+}
 ```
 
 #### Enabling Hierarchical Discovery

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;
@@ -526,24 +590,26 @@ const create$1 = (params)=>{
     }
 }
 /**
- * Deep merges multiple configuration objects with proper precedence.
+ * Deep merges multiple configuration objects with proper precedence and configurable array overlap behavior.
  * 
  * Objects are merged from lowest precedence to highest precedence,
  * meaning that properties in later objects override properties in earlier objects.
- * Arrays are replaced entirely (not merged).
+ * Arrays can be merged using different strategies based on the fieldOverlaps configuration.
  * 
  * @param configs Array of configuration objects, ordered from lowest to highest precedence
+ * @param fieldOverlaps Configuration for how array fields should be merged (optional)
  * @returns Merged configuration object
  * 
  * @example
  * ```typescript
  * const merged = deepMergeConfigs([
- *   { api: { timeout: 5000 }, debug: true },        // Lower precedence
- *   { api: { retries: 3 }, features: ['auth'] },    // Higher precedence
- * ]);
- * // Result: { api: { timeout: 5000, retries: 3 }, debug: true, features: ['auth'] }
+ *   { api: { timeout: 5000 }, features: ['auth'] },        // Lower precedence
+ *   { api: { retries: 3 }, features: ['analytics'] },      // Higher precedence
+ * ], {
+ *   'features': 'append'  // Results in features: ['auth', 'analytics']
+ * });
  * ```
- */ function deepMergeConfigs(configs) {
+ */ function deepMergeConfigs(configs, fieldOverlaps) {
     if (configs.length === 0) {
         return {};
     }
@@ -553,16 +619,18 @@ const create$1 = (params)=>{
         };
     }
     return configs.reduce((merged, current)=>{
-        return deepMergeTwo(merged, current);
+        return deepMergeTwo(merged, current, fieldOverlaps);
     }, {});
 }
 /**
- * Deep merges two objects with proper precedence.
+ * Deep merges two objects with proper precedence and configurable array overlap behavior.
  * 
  * @param target Target object (lower precedence)
  * @param source Source object (higher precedence)
+ * @param fieldOverlaps Configuration for how array fields should be merged (optional)
+ * @param currentPath Current field path for nested merging (used internally)
  * @returns Merged object
- */ function deepMergeTwo(target, source) {
+ */ function deepMergeTwo(target, source, fieldOverlaps, currentPath = '') {
     // Handle null/undefined
     if (source == null) return target;
     if (target == null) return source;
@@ -570,11 +638,17 @@ const create$1 = (params)=>{
     if (typeof source !== 'object' || typeof target !== 'object') {
         return source; // Source takes precedence
     }
-    // Handle arrays - replace entirely, don't merge
+    // Handle arrays with configurable overlap behavior
     if (Array.isArray(source)) {
-        return [
-            ...source
-        ];
+        if (Array.isArray(target) && fieldOverlaps) {
+            const overlapMode = getOverlapModeForPath(currentPath, fieldOverlaps);
+            return mergeArrays(target, source, overlapMode);
+        } else {
+            // Default behavior: replace entirely
+            return [
+                ...source
+            ];
+        }
     }
     if (Array.isArray(target)) {
         return source; // Source object replaces target array
@@ -585,17 +659,72 @@ const create$1 = (params)=>{
     };
     for(const key in source){
         if (Object.prototype.hasOwnProperty.call(source, key)) {
+            const fieldPath = currentPath ? `${currentPath}.${key}` : key;
             if (Object.prototype.hasOwnProperty.call(result, key) && typeof result[key] === 'object' && typeof source[key] === 'object' && !Array.isArray(source[key]) && !Array.isArray(result[key])) {
                 // Recursively merge nested objects
-                result[key] = deepMergeTwo(result[key], source[key]);
+                result[key] = deepMergeTwo(result[key], source[key], fieldOverlaps, fieldPath);
             } else {
-                // Replace with source value (higher precedence)
-                result[key] = source[key];
+                // Handle arrays and primitives with overlap consideration
+                if (Array.isArray(source[key]) && Array.isArray(result[key]) && fieldOverlaps) {
+                    const overlapMode = getOverlapModeForPath(fieldPath, fieldOverlaps);
+                    result[key] = mergeArrays(result[key], source[key], overlapMode);
+                } else {
+                    // Replace with source value (higher precedence)
+                    result[key] = source[key];
+                }
             }
         }
     }
     return result;
 }
+/**
+ * Determines the overlap mode for a given field path.
+ * 
+ * @param fieldPath The current field path (dot notation)
+ * @param fieldOverlaps Configuration mapping field paths to overlap modes
+ * @returns The overlap mode to use for this field path
+ */ function getOverlapModeForPath(fieldPath, fieldOverlaps) {
+    // Check for exact match first
+    if (fieldPath in fieldOverlaps) {
+        return fieldOverlaps[fieldPath];
+    }
+    // Check for any parent path matches (for nested configurations)
+    const pathParts = fieldPath.split('.');
+    for(let i = pathParts.length - 1; i > 0; i--){
+        const parentPath = pathParts.slice(0, i).join('.');
+        if (parentPath in fieldOverlaps) {
+            return fieldOverlaps[parentPath];
+        }
+    }
+    // Default to override if no specific configuration found
+    return 'override';
+}
+/**
+ * Merges two arrays based on the specified overlap mode.
+ * 
+ * @param targetArray The lower precedence array
+ * @param sourceArray The higher precedence array
+ * @param mode The overlap mode to use
+ * @returns The merged array
+ */ function mergeArrays(targetArray, sourceArray, mode) {
+    switch(mode){
+        case 'append':
+            return [
+                ...targetArray,
+                ...sourceArray
+            ];
+        case 'prepend':
+            return [
+                ...sourceArray,
+                ...targetArray
+            ];
+        case 'override':
+        default:
+            return [
+                ...sourceArray
+            ];
+    }
+}
 /**
  * Loads configurations from multiple directories and merges them with proper precedence.
  * 
@@ -614,15 +743,19 @@ const create$1 = (params)=>{
  *   configDirName: '.kodrdriv',
  *   configFileName: 'config.yaml',
  *   startingDir: '/project/subdir',
- *   maxLevels: 5
+ *   maxLevels: 5,
+ *   fieldOverlaps: {
+ *     'features': 'append',
+ *     'excludePatterns': 'prepend'
+ *   }
  * });
  * 
- * // result.config contains merged configuration
+ * // result.config contains merged configuration with custom array merging
  * // result.discoveredDirs shows where configs were found
  * // result.errors contains any non-fatal errors
  * ```
  */ async function loadHierarchicalConfig(options) {
-    const { configFileName, encoding = 'utf8', logger } = options;
+    const { configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray, fieldOverlaps } = 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 +776,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}`);
@@ -656,8 +789,8 @@ const create$1 = (params)=>{
             logger === null || logger === void 0 ? void 0 : logger.debug(errorMsg);
         }
     }
-    // Merge all configurations with proper precedence
-    const mergedConfig = deepMergeConfigs(configs);
+    // Merge all configurations with proper precedence and configurable array overlap
+    const mergedConfig = deepMergeConfigs(configs, fieldOverlaps);
     logger === null || logger === void 0 ? void 0 : logger.verbose(`Hierarchical loading complete. Merged ${configs.length} configurations`);
     return {
         config: mergedConfig,
@@ -675,6 +808,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 +953,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 +966,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 +976,10 @@ 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,
+                fieldOverlaps: options.defaults.fieldOverlaps
             });
             rawFileConfig = hierarchicalResult.config;
             if (hierarchicalResult.discoveredDirs.length > 0) {
@@ -805,8 +1004,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 +1379,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 +1394,31 @@ 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']
+ *     },
+ *     // Configure how array fields are merged in hierarchical mode
+ *     fieldOverlaps: {
+ *       'features': 'append',              // Accumulate features from all levels
+ *       'excludePatterns': 'prepend'       // Higher precedence patterns come first
+ *     }
  *   },
  *   configShape: MyConfigSchema.shape,
+ *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery
  * });
+ * 
+ * // 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 = {