configorama 0.8.0 → 0.9.0

package/README.md

@@ -870,14 +870,49 @@ const config = await configorama(configFile, {
   allowUnresolvedVariables: ['param', 'file'],  // only these pass through
   options: { stage: 'prod' }
 })
-// Unresolved ${param:x} and ${file(missing.yml)} pass through
-// Unresolved ${env:MISSING} throws an error
+// Input:  { paramKey: '${param:x}', fileKey: '${file(missing.yml)}' }
+// Output: { paramKey: '${param:x}', fileKey: '${file(missing.yml)}' }
+
+// Allow only SPECIFIC types to be unresolved
+const config = await configorama(configFile, {
+  allowUnresolvedVariables: ['param', 'file'],  // only these pass through
+  options: { stage: 'prod' }
+})
+// Input:  { key: '${env:MISSING_VAR}', paramKey: '${param:x}', fileKey: '${file(missing.yml)}' }
+// Unresolved ${param:x} and ${file(missing.yml)} pass through but
+// Output error thrown because ${env:MISSING_VAR} throws an error
 ```
 
-This is useful for multi-stage resolution (e.g., Serverless Dashboard resolves params after local resolution).
+This is useful for multi-stage resolution (e.g., Downstream Serverless Dashboard resolves params after local resolution).
+
+> **Note:** This option does NOT apply to `self:` or dotProp variables (e.g., `${foo.bar.baz}`). These are local references that configorama fully owns—if they can't be resolved, it's a config error, not something to defer to another system.
 
 ## FAQ
 
+**Q: What happens with circular variable dependencies?**
+
+Configorama detects circular dependencies and throws a helpful error instead of hanging forever.
+
+```yml
+# Direct cycle - throws error
+a: ${self:b}
+b: ${self:a}
+# Error: Circular variable dependency detected: b → a → b
+
+# Indirect cycle - also detected
+a: ${self:b}
+b: ${self:c}
+c: ${self:a}
+# Error: Circular variable dependency detected: c → a → b → c
+
+# Works with shorthand syntax too
+foo:
+  bar: ${baz.qux}
+baz:
+  qux: ${foo.bar}
+# Error: Circular variable dependency detected: baz.qux → foo.bar → baz.qux
+```
+
 **Q: Why should I use this?**
 
 Never rendering a stale configuration file again!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",

package/src/main.js

@@ -121,6 +121,7 @@ class Configorama {
       allowUndefinedValues: false,
       // Allow known variable types that can't be resolved to pass through
       // Can be: false | true | ['param', 'file', 'env', ...]
+      // Note: Does not apply to self: or dotprop refs - those always error
       allowUnresolvedVariables: false,
       // Return metadata
       returnMetadata: false,
@@ -2767,6 +2768,25 @@ Missing Value ${missingValue} - ${matchedString}
 
     // console.log('getValueFromSrc propertyString', propertyString)
     // console.log(`tracker contains ${variableString}`, this.tracker.contains(variableString))
+
+    // Cycle detection: track dependencies and check for cycles
+    const fromPath = valueObject.path ? valueObject.path.join('.') : null
+    // Extract target path from variableString (e.g., 'self:b' → 'b', 'b.c' → 'b.c')
+    let toPath = variableString
+    if (variableString.startsWith('self:')) {
+      toPath = variableString.slice(5)
+    }
+    // For cycle detection, only track self-references
+    if (fromPath && (variableString.startsWith('self:') || !variableString.includes(':'))) {
+      if (this.tracker.wouldCreateCycle(fromPath, toPath)) {
+        const cyclePath = this.tracker.getCyclePath(fromPath, toPath)
+        return Promise.reject(new Error(
+          `Circular variable dependency detected: ${cyclePath.join(' → ')}`
+        ))
+      }
+      this.tracker.addDependency(fromPath, toPath)
+    }
+
     if (this.tracker.contains(variableString)) {
       // console.log('try to get', variableString)
       return this.tracker.get(variableString, propertyString)
@@ -3253,6 +3273,7 @@ Missing Value ${missingValue} - ${matchedString}
         // console.log('self fixed deepProperties', deepProperties)
       }
     }
+
     return this.getDeeperValue(deepProperties, valueToPopulate).then((res) => {
       /*
       console.log('self getDeeperValue variableString', variableString)

package/src/utils/PromiseTracker.js

@@ -8,6 +8,8 @@ class PromiseTracker {
   reset() {
     this.promiseList = []
     this.promiseMap = {}
+    // Track which variables depend on which (for cycle detection)
+    this.dependencyGraph = {}
     this.startTime = Date.now()
     this.cursor = 0
   }
@@ -81,6 +83,58 @@ class PromiseTracker {
     promise.waitList += ` ${specifier}`
     return promise
   }
+  // Add a dependency edge: "from" depends on "to"
+  addDependency(from, to) {
+    if (!this.dependencyGraph[from]) {
+      this.dependencyGraph[from] = new Set()
+    }
+    this.dependencyGraph[from].add(to)
+  }
+  // Check if adding dependency from → to would create a cycle
+  wouldCreateCycle(from, to) {
+    // Check if "to" can reach "from" (meaning from → to would close a cycle)
+    const visited = new Set()
+    const stack = [to]
+    while (stack.length > 0) {
+      const current = stack.pop()
+      if (current === from) {
+        return true
+      }
+      if (visited.has(current)) {
+        continue
+      }
+      visited.add(current)
+      const deps = this.dependencyGraph[current]
+      if (deps) {
+        for (const dep of deps) {
+          stack.push(dep)
+        }
+      }
+    }
+    return false
+  }
+  // Get the cycle path for error reporting
+  getCyclePath(from, to) {
+    const path = [from, to]
+    const visited = new Set([from, to])
+    let current = to
+    while (current !== from) {
+      const deps = this.dependencyGraph[current]
+      if (!deps) break
+      let found = false
+      for (const dep of deps) {
+        if (dep === from || !visited.has(dep)) {
+          path.push(dep)
+          visited.add(dep)
+          current = dep
+          found = true
+          break
+        }
+      }
+      if (!found) break
+    }
+    return path
+  }
   getPending() {
     return this.promiseList.filter(p => (p.state === 'pending'))
   }

package/types/src/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.js"],"names":[],"mappings":";AA0GA;IACE,0CAwbC;IAhbC,cAaW;IAuBX,gBAAqB;IAErB,sBAAwB;IACxB,qBAAuB;IAGvB,uBAA4B;IAc5B,uBAAoC;IAIpC,kBAAqC;IACrC,kBAAqC;IAErC,yBAA+F;IAC/F,yBAAuD;IACvD,kCAAyE;IAKvE,YAA0B;IAE1B,oBAA6C;IAE7C,gBAAoD;IAOpD,uBAAkC;IAElC,uBAA8B;IAE9B,uBAAkC;IASpC,wBAAmC;IAGnC,mBA8GC;IAoED,4BAA8C;IAO9C,aA2EC;IAUD,oBAEC;IAGD,eAkDC;IAOD,YAAc;IACd,cAAgB;IAChB,kBAAkB;IAGpB;;;;OAIG;IACH,0BAHW,MAAM,GACJ,OAAO,CAQnB;IAED;;;;OAIG;IACH,6BAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAOvB;IAED;;;;OAIG;IACH,gCAHW,MAAM,GACJ,OAAO,CAoBnB;IAKD;;;;;OAKG;IACH,oBAFa,OAAO,CAAC,GAAG,CAAC,CAqsBxB;IAlsBC,aAA4B;IAc1B,2BAA4B;IAQ5B,uBAAgD;IA8qBpD;;;OAGG;IACH,2BAFa,MAAM,CA8alB;IAvBC;;;;;;;;;;;;;;;MAoBC;IAIH;;;;OAIG;IACH,uCAFa,OAAO,CAAC,GAAG,CAAC,CAIxB;IACD,+CAsBC;IAKD;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;OAWG;IACH,mFAHa;;;;cAZC,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAWD,CA+D9B;IACD;;;OAGG;IACH;;;;;OAKG;IACH,oCAHa,OAAO,CAAC;;;;cAnFP,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAkFgB,CAAC,EAAE,CA6BlD;IACD;;;;;OAKG;IACH,iDAFa,OAAO,CAAC,IAAI,CAAC,CAWzB;IAID;;;;;OAKG;IACH;;;;OAIG;IACH,2BAFa,eAAc;;;;;;;;;;OAAa,CAavC;IACD;;;;;OAKG;IACH,yBAHW;;;;;;;;;;OAAa,gCACX,cAAS,CAOrB;IACD;;;;;;OAMG;IACH,6DAFa,GAAC,CA+Kb;IAKD;;;;;;;OAOG;IACH,yDAHa,OAAO,CAAC,GAAG,CAAC,CAiCxB;IACD;;;;OAIG;IAOH;;;;;;OAMG;IACH,wFA2BC;IACD;;;;;;;;;;;OAWG;IACH,8BARG;QAAyB,KAAK,EAAtB,GAAG;QACoB,IAAI,GAA3B,MAAM,EAAE;QACa,cAAc,GAAnC,MAAM;QACc,iBAAiB;KAC7C,6CAEU;QAAC,KAAK,EAAE,GAAG,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,QAAQ;QAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAmY9J;IAID;;;;;;;;OAQG;IACH,qEAHa,OAAO,CAAC,GAAG,CAAC,CAoExB;IAKD;;;;;;;OAOG;IACH,0FAFa,OAAO,CAAC,GAAG,CAAC,CA0fxB;IACD,+EA8BC;IACD,yDAeC;IACD,oEA6BC;IAKD,8CAQC;IACD,kDAyBC;IACD;;;;;;;;;;;;;OAaG;IACH,wEAoDC;IAKD,4BAOC;IACD,sCAoDC;CACF"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.js"],"names":[],"mappings":";AA0GA;IACE,0CAybC;IAjbC,cAcW;IAuBX,gBAAqB;IAErB,sBAAwB;IACxB,qBAAuB;IAGvB,uBAA4B;IAc5B,uBAAoC;IAIpC,kBAAqC;IACrC,kBAAqC;IAErC,yBAA+F;IAC/F,yBAAuD;IACvD,kCAAyE;IAKvE,YAA0B;IAE1B,oBAA6C;IAE7C,gBAAoD;IAOpD,uBAAkC;IAElC,uBAA8B;IAE9B,uBAAkC;IASpC,wBAAmC;IAGnC,mBA8GC;IAoED,4BAA8C;IAO9C,aA2EC;IAUD,oBAEC;IAGD,eAkDC;IAOD,YAAc;IACd,cAAgB;IAChB,kBAAkB;IAGpB;;;;OAIG;IACH,0BAHW,MAAM,GACJ,OAAO,CAQnB;IAED;;;;OAIG;IACH,6BAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAOvB;IAED;;;;OAIG;IACH,gCAHW,MAAM,GACJ,OAAO,CAoBnB;IAKD;;;;;OAKG;IACH,oBAFa,OAAO,CAAC,GAAG,CAAC,CAqsBxB;IAlsBC,aAA4B;IAc1B,2BAA4B;IAQ5B,uBAAgD;IA8qBpD;;;OAGG;IACH,2BAFa,MAAM,CA8alB;IAvBC;;;;;;;;;;;;;;;MAoBC;IAIH;;;;OAIG;IACH,uCAFa,OAAO,CAAC,GAAG,CAAC,CAIxB;IACD,+CAsBC;IAKD;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;OAWG;IACH,mFAHa;;;;cAZC,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAWD,CA+D9B;IACD;;;OAGG;IACH;;;;;OAKG;IACH,oCAHa,OAAO,CAAC;;;;cAnFP,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAkFgB,CAAC,EAAE,CA6BlD;IACD;;;;;OAKG;IACH,iDAFa,OAAO,CAAC,IAAI,CAAC,CAWzB;IAID;;;;;OAKG;IACH;;;;OAIG;IACH,2BAFa,eAAc;;;;;;;;;;OAAa,CAavC;IACD;;;;;OAKG;IACH,yBAHW;;;;;;;;;;OAAa,gCACX,cAAS,CAOrB;IACD;;;;;;OAMG;IACH,6DAFa,GAAC,CA+Kb;IAKD;;;;;;;OAOG;IACH,yDAHa,OAAO,CAAC,GAAG,CAAC,CAiCxB;IACD;;;;OAIG;IAOH;;;;;;OAMG;IACH,wFA2BC;IACD;;;;;;;;;;;OAWG;IACH,8BARG;QAAyB,KAAK,EAAtB,GAAG;QACoB,IAAI,GAA3B,MAAM,EAAE;QACa,cAAc,GAAnC,MAAM;QACc,iBAAiB;KAC7C,6CAEU;QAAC,KAAK,EAAE,GAAG,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,QAAQ;QAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAC,CAmY9J;IAID;;;;;;;;OAQG;IACH,qEAHa,OAAO,CAAC,GAAG,CAAC,CAoExB;IAKD;;;;;;;OAOG;IACH,0FAFa,OAAO,CAAC,GAAG,CAAC,CA6gBxB;IACD,+EA+BC;IACD,yDAeC;IACD,oEA6BC;IAKD,8CAQC;IACD,kDAyBC;IACD;;;;;;;;;;;;;OAaG;IACH,wEAoDC;IAKD,4BAOC;IACD,sCAoDC;CACF"}

package/types/src/utils/PromiseTracker.d.ts

@@ -3,6 +3,7 @@ declare class PromiseTracker {
     reset(): void;
     promiseList: any[];
     promiseMap: {};
+    dependencyGraph: {};
     startTime: number;
     cursor: number;
     start(): void;
@@ -12,6 +13,9 @@ declare class PromiseTracker {
     add(variable: any, promise: any, specifier: any, hasFilter: any, promiseKey: any): any;
     contains(variable: any): boolean;
     get(variable: any, specifier: any): any;
+    addDependency(from: any, to: any): void;
+    wouldCreateCycle(from: any, to: any): boolean;
+    getCyclePath(from: any, to: any): any[];
     getPending(): any[];
     getSettled(): any[];
     getAll(): any[];

package/types/src/utils/PromiseTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PromiseTracker.d.ts","sourceRoot":"","sources":["../../../src/utils/PromiseTracker.js"],"names":[],"mappings":";AAGA;IAIE,cAKC;IAJC,mBAAqB;IACrB,eAAoB;IACpB,kBAA2B;IAC3B,eAAe;IAEjB,cAGC;IADC,yBAAyD;IAE3D,eAqBC;IACD,aAGC;IACD,uFA+BC;IACD,iCAEC;IACD,wCAIC;IACD,oBAEC;IACD,oBAEC;IACD,gBAEC;CACF"}
+{"version":3,"file":"PromiseTracker.d.ts","sourceRoot":"","sources":["../../../src/utils/PromiseTracker.js"],"names":[],"mappings":";AAGA;IAIE,cAOC;IANC,mBAAqB;IACrB,eAAoB;IAEpB,oBAAyB;IACzB,kBAA2B;IAC3B,eAAe;IAEjB,cAGC;IADC,yBAAyD;IAE3D,eAqBC;IACD,aAGC;IACD,uFA+BC;IACD,iCAEC;IACD,wCAIC;IAED,wCAKC;IAED,8CAqBC;IAED,wCAoBC;IACD,oBAEC;IACD,oBAEC;IACD,gBAEC;CACF"}