molex-env 0.2.6 → 0.3.1

package/README.md

@@ -126,8 +126,8 @@ OPTIONAL_KEY=
 
 Files are loaded and merged in this order (later files override earlier ones):
 
-1. `.menv` - Base configuration (committed to git)
-2. `.menv.local` - Local overrides (ignored by git)
+1. `.menv` - Base configuration
+2. `.menv.local` - Local overrides
 3. `.menv.{profile}` - Profile-specific config (e.g., `.menv.prod`)
 4. `.menv.{profile}.local` - Profile + local overrides (e.g., `.menv.prod.local`)
 
@@ -277,23 +277,62 @@ Watch .menv files and reload automatically when they change. Perfect for develop
 
 **Arguments:**
 
-- `options` - Same options as `load()`
+- `options` - Same options as `load()`, including `debug` for automatic change logging
 - `onChange(error, result)` - Callback fired on file changes
 
-**Example:**
+**Automatic Change Detection:**
+
+When `debug: true` is enabled, watch mode automatically logs what values changed on each reload:
 
 ```javascript
 const { watch } = require('molex-env');
 
-// Watch with callback
-watch({ profile: 'dev', strict: true }, (err, result) => {
+watch({ 
+  profile: 'dev',
+  debug: true,  // Automatically logs changes
+  schema: {
+    PORT: 'number',
+    DEBUG: 'boolean',
+    SERVICE_URL: 'string'
+  }
+}, (err, result) => {
+  if (err) {
+    console.error('Config reload failed:', err.message);
+    return;
+  }
+  console.log('✅ Config successfully reloaded');
+});
+
+// When you edit .menv files, automatic output:
+// [molex-env] Config reloaded - changes detected:
+//   PORT: 3000 → 8080
+//   SERVICE_URL: https://api.example.com → https://api.production.com
+// ✅ Config successfully reloaded
+```
+
+**Manual Change Detection:**
+
+Without `debug: true`, you can manually detect changes in your callback:
+
+```javascript
+let currentConfig;
+
+watch({ profile: 'dev' }, (err, result) => {
   if (err) {
     console.error('Config reload failed:', err.message);
     return;
   }
   
-  console.log('Config reloaded!');
-  console.log('New PORT:', result.parsed.PORT);
+  if (!currentConfig) {
+    console.log('Initial config loaded');
+  } else {
+    // Manually check what changed
+    if (currentConfig.PORT !== result.parsed.PORT) {
+      console.log(`PORT changed: ${currentConfig.PORT} → ${result.parsed.PORT}`);
+    }
+  }
+  
+  currentConfig = result.parsed;
   
   // Restart your server or update app state here
   if (global.server) {
@@ -325,10 +364,17 @@ function startServer(config) {
 const initial = require('molex-env').load({ profile: 'dev' });
 server = startServer(initial.parsed);
 
-// Watch for changes
-watch({ profile: 'dev' }, (err, result) => {
+// Watch for changes with automatic change logging
+watch({ 
+  profile: 'dev',
+  debug: true,
+  schema: {
+    PORT: 'number',
+    DEBUG: 'boolean'
+  }
+}, (err, result) => {
   if (!err && result.parsed.PORT !== initial.parsed.PORT) {
-    console.log('Port changed, restarting...');
+    console.log('Port changed, restarting server...');
     server.close(() => {
       server = startServer(result.parsed);
     });
@@ -657,10 +703,9 @@ console.log(`PORT: ${process.menv.PORT}`);
 ```javascript
 const { watch } = require('molex-env');
 
-let currentConfig;
-
 watch({
   profile: 'dev',
+  debug: true,  // Automatic change detection
   schema: {
     PORT: 'number',
     DEBUG: 'boolean',
@@ -672,24 +717,15 @@ watch({
     return;
   }
   
-  const changed = [];
-  if (!currentConfig) {
-    console.log('Initial config loaded');
-  } else {
-    // Detect what changed
-    Object.keys(result.parsed).forEach(key => {
-      if (currentConfig[key] !== result.parsed[key]) {
-        changed.push(`${key}: ${currentConfig[key]} → ${result.parsed[key]}`);
-      }
-    });
-    
-    if (changed.length > 0) {
-      console.log('Config updated:', changed.join(', '));
-    }
-  }
-  
-  currentConfig = result.parsed;
+  console.log('Config reloaded and ready to use');
+  // result.parsed has the new values
 });
+
+console.log('Watching for changes...');
+// Output on file change:
+// [molex-env] Config reloaded - changes detected:
+//   DEBUG: false → true
+//   API_URL: https://api.example.com → https://api.dev.local
 ```
 
 ### Validation and Error Handling
@@ -730,35 +766,19 @@ try {
 
 ## Best Practices
 
-### Git Configuration
-
-Add to `.gitignore`:
-```gitignore
-# Keep base configs in git
-# .menv
-# .menv.dev
-# .menv.prod
-
-# Ignore local overrides (machine-specific, secrets)
-.menv.local
-.menv.*.local
-```
-
 ### Environment Strategy
 
 ```
 Development:   .menv + .menv.local
 Staging:       .menv + .menv.staging
-Production:    .menv + .menv.prod + .menv.prod.local (secrets)
+Production:    .menv + .menv.prod + .menv.prod.local
 ```
 
 ### Security Tips
 
-- ✅ **DO** use `.menv.local` for secrets and add to `.gitignore`
 - ✅ **DO** use `strict: true` in production to catch unknown keys and configuration errors
 - ✅ **DO** use `debug: true` during development to understand file precedence
 - ✅ **DO** validate sensitive values (URLs, ports, etc.) after loading
-- ❌ **DON'T** commit production secrets to git
 - ❌ **DON'T** use `exportEnv: true` if you need immutable config
 
 ### Performance
@@ -794,11 +814,25 @@ The example demonstrates:
 
 **Problem:** Getting errors about unknown keys when loading config.
 
-**Solution:** Add all keys to your schema or disable strict mode:
+**Cause:** You have a key in your `.menv` file that isn't defined in your schema, and `strict: true` is enabled.
+
+**Solution:** Either add the key to your schema or disable strict mode:
 ```javascript
-load({ strict: false });  // Allow unknown keys
+// Option 1: Add missing key to schema
+load({ 
+  strict: true,
+  schema: { 
+    PORT: 'number',
+    YOUR_MISSING_KEY: 'string'  // Add this
+  }
+});
+
+// Option 2: Disable strict mode to allow unknown keys
+load({ strict: false });
 ```
 
+> **Note:** This is different from "required" - unknown keys exist in your file but not in schema. Required keys exist in schema but not in your file.
+
 ### Values are strings instead of typed
 
 **Problem:** `PORT` is `"3000"` (string) instead of `3000` (number).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "molex-env",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "Native .menv loader with profiles, typing, and origin tracking.",
   "main": "src/index.js",
   "files": [

package/src/lib/watch.js

@@ -27,6 +27,7 @@ function watch(options, onChange, load)
     const basenames = new Set(files.map((file) => path.basename(file)));
     const watchers = [];
     let timer = null;
+    let previousConfig = null;
 
     const trigger = () =>
     {
@@ -35,7 +36,40 @@ function watch(options, onChange, load)
         {
             try
             {
-                const result = load(options);
+                // Disable file precedence debug during reload to avoid conflicts with watch change detection
+                const reloadOptions = { ...options, debug: false };
+                const result = load(reloadOptions);
+                
+                // Auto-detect changes if debug mode was enabled
+                if (options.debug && previousConfig)
+                {
+                    const changes = [];
+                    for (const key in result.parsed)
+                    {
+                        const oldValue = previousConfig[key];
+                        const newValue = result.parsed[key];
+                        
+                        // Compare values (handle dates and objects)
+                        const oldStr = oldValue instanceof Date ? oldValue.toISOString() : JSON.stringify(oldValue);
+                        const newStr = newValue instanceof Date ? newValue.toISOString() : JSON.stringify(newValue);
+                        
+                        if (oldStr !== newStr)
+                        {
+                            changes.push({ key, old: oldValue, new: newValue });
+                        }
+                    }
+                    
+                    if (changes.length > 0)
+                    {
+                        console.log('[molex-env] Config reloaded - changes detected:');
+                        changes.forEach(({ key, old, new: newVal }) =>
+                        {
+                            console.log(`  ${key}: ${old} → ${newVal}`);
+                        });
+                    }
+                }
+                
+                previousConfig = { ...result.parsed };
                 onChange(null, result);
             } catch (err)
             {