@theunwalked/cardigantime 0.0.8 → 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

@@ -590,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 {};
     }
@@ -617,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;
@@ -634,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
@@ -649,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.
  * 
@@ -678,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, pathFields, resolvePathArray } = 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);
@@ -720,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,
@@ -909,7 +978,8 @@ const create$1 = (params)=>{
                 encoding: options.defaults.encoding,
                 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
+                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) {
@@ -1335,9 +1405,15 @@ class ConfigurationError extends Error {
  *     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: