configorama 0.6.18 → 0.6.19

package/package.json

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

package/src/main.js

@@ -67,7 +67,7 @@ const { warnIfNotFound, isValidValue } = require('./utils/validation/warnIfNotFo
 /* Utils - variables */
 const cleanVariable = require('./utils/variables/cleanVariable')
 const appendDeepVariable = require('./utils/variables/appendDeepVariable')
-const { getFallbackString, verifyVariable } = require('./utils/variables/variableUtils')
+const { extractVariableWrapper, getFallbackString, verifyVariable } = require('./utils/variables/variableUtils')
 const { findNestedVariables } = require('./utils/variables/findNestedVariables')
 
 /* Resolvers */
@@ -174,6 +174,15 @@ class Configorama {
     const variableSyntax = varRegex
     this.variableSyntax = variableSyntax
 
+    // Extract variable prefix/suffix from syntax regex for reconstructing variables
+    const syntaxWrapper = extractVariableWrapper(variableSyntax.source)
+    this.varPrefix = syntaxWrapper.prefix
+    this.varSuffix = syntaxWrapper.suffix
+    const escapedSuffix = this.varSuffix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    this.varPrefixPattern = new RegExp('^' + this.varPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    this.varSuffixPattern = new RegExp(escapedSuffix + '$')
+    this.varSuffixWithSpacePattern = new RegExp('\\s+' + escapedSuffix + '$')
+
     // Set initial config object to populate
     if (typeof fileOrObject === 'object') {
       // set config objects
@@ -566,7 +575,7 @@ class Configorama {
       this.rawOriginalConfig = cloneDeep(configObject)
 
       /* Preprocess step here - escapes ${} in help() args, fixes malformed fallbacks */
-      configObject = preProcess(configObject, this.variableSyntax)
+      configObject = preProcess(configObject, this.variableSyntax, this.variableTypes)
       /*
       console.log('after preprocess', configObject)
       /** */
@@ -654,7 +663,7 @@ class Configorama {
         const fileName = this.configFilePath ? ` in ${this.configFilePath}` : ''
 
         // Extract base variable name from varMatch key (e.g., '${env:FOO, default}' -> 'env:FOO')
-        const getBaseVarName = (key) => key.replace(/^\$\{/, '').replace(/\}$/, '').split(',')[0].trim()
+        const getBaseVarName = (key) => key.replace(this.varPrefixPattern, '').replace(this.varSuffixPattern, '').split(',')[0].trim()
 
         logHeader(`Found ${varKeys.length} Variables${fileName}`)
 
@@ -1309,9 +1318,9 @@ class Configorama {
             .map((filter) => filter.trim())
             .filter(Boolean)
 
-          // Remove filters from the key (replace "| String}" with "}")
+          // Remove filters from the key (replace "| String}" with suffix)
           // Also clean up any trailing whitespace before the closing brace
-          keyWithoutFilters = originalSrc.replace(filterMatch, '}').replace(/\s+}$/, '}')
+          keyWithoutFilters = originalSrc.replace(filterMatch, this.varSuffix).replace(this.varSuffixWithSpacePattern, this.varSuffix)
         }
 
         const key = keyWithoutFilters
@@ -1337,7 +1346,7 @@ class Configorama {
           if (cleaned.varMatch && filterMatch) {
             const match = cleaned.varMatch.match(filterMatch)
             if (match) {
-              cleaned.varMatch = cleaned.varMatch.replace(filterMatch, '').replace(/\s+$/, '') + '}'
+              cleaned.varMatch = cleaned.varMatch.replace(filterMatch, '').replace(/\s+$/, '') + this.varSuffix
             }
           }
           if (cleaned.variable && filterMatch) {
@@ -2202,7 +2211,7 @@ class Configorama {
     let foundFilters = []
     if (hasFilters) {
       foundFilters = hasFilters[0]
-        .replace(/}$/, '') // remove trailing }
+        .replace(this.varSuffixPattern, '')
         .split('|')
         .map((filter) => filter.trim())
         .filter(Boolean)
@@ -2287,13 +2296,13 @@ class Configorama {
       console.log('isString currentMatchedString', currentMatchedString)
       console.log('>------')
       /** */
-      // Handle comma ${opt:stage, dev} and remove extra }
+      // Handle comma ${opt:stage, dev} and remove extra suffix
       if (
         currentMatchedString.match(this.variableSyntax) &&
         !valueToPopulate.match(this.variableSyntax) &&
-        valueToPopulate.match(/}$/)
+        valueToPopulate.match(this.varSuffixPattern)
       ) {
-        valueToPopulate = valueToPopulate.replace(/}$/, '')
+        valueToPopulate = valueToPopulate.replace(this.varSuffixPattern, '')
       }
 
       property = replaceAll(currentMatchedString, valueToPopulate, property)
@@ -2340,7 +2349,7 @@ class Configorama {
       let missingValue = matchedString
 
       if (matchedString.match(deepRefSyntax)) {
-        const deepIndex = matchedString.split(':')[1].replace('}', '')
+        const deepIndex = matchedString.split(':')[1].replace(this.varSuffixPattern, '')
         const i = Number(deepIndex)
         missingValue = this.deep[i]
       }
@@ -2372,6 +2381,39 @@ class Configorama {
         }
       }
 
+      // If allowUnresolvedVariables and there are fallbacks, use the fallback
+      if (this.opts.allowUnresolvedVariables && splitVars.length > 1) {
+        const nextFallback = splitVars[1].trim()
+        // Strip trailing variable suffix (handles }, }}, >, ]], etc.)
+        const nextFallbackClean = nextFallback.replace(this.varSuffixPattern, '')
+        const isQuotedString = /^['"].*['"]$/.test(nextFallbackClean)
+        const isNumeric = /^-?\d+(\.\d+)?$/.test(nextFallbackClean)
+        if (isQuotedString || isNumeric) {
+          let staticValue = nextFallbackClean.replace(/^['"]|['"]$/g, '')
+          // Convert to number if it's a numeric fallback
+          if (isNumeric) {
+            staticValue = Number(staticValue)
+          }
+          return {
+            value: staticValue,
+            path: valueObject.path,
+            originalSource: valueObject.originalSource,
+            resolutionHistory: valueObject.resolutionHistory || [],
+          }
+        }
+        // Next fallback is another variable
+        const remainingContent = splitVars.slice(1).join(', ').replace(this.varSuffixPattern, '')
+        const remainingFallbacks = this.varPrefix + remainingContent + this.varSuffix
+        return {
+          value: remainingFallbacks,
+          path: valueObject.path,
+          originalSource: valueObject.originalSource,
+          resolutionHistory: valueObject.resolutionHistory || [],
+          __internal_only_flag: true,
+          caller: 'allowUnresolvedVariables-fallback',
+        }
+      }
+
       const currentPath = valueObject.path.join('.')
 
       const errorMessage = `
@@ -2394,7 +2436,7 @@ Missing Value ${missingValue} - ${matchedString}
       )
       
       // Double processing needed for `${eval(${self:three} > ${self:four})}`
-      if (prop.startsWith('${')) {
+      if (prop.startsWith(this.varPrefix)) {
         prop = cleanVariable(prop, this.variableSyntax, true, `populateVariable string ${this.callCount}`)
       }
       
@@ -2595,7 +2637,7 @@ Missing Value ${missingValue} - ${matchedString}
 
       if (deepProperties > 0) {
         // Reconstruct a minimal variable string with deep refs, not the full outer string
-        const reconstructed = '${' + deepVariableParts.join(', ') + '}'
+        const reconstructed = this.varPrefix + deepVariableParts.join(', ') + this.varSuffix
         return Promise.resolve(reconstructed)
       }
       return Promise.resolve(extractedValues.find(isValidValue)) // resolve first valid value, else undefined
@@ -2694,7 +2736,7 @@ Missing Value ${missingValue} - ${matchedString}
         .map((f) => {
           return trim(f)
           // TODO refactor this. This is a temp fix for filters with nested vars.
-          .replace(/}$/, '')
+          .replace(this.varSuffixPattern, '')
         })
       // console.log('filters to run', _filter)
 
@@ -2809,6 +2851,16 @@ Missing Value ${missingValue} - ${matchedString}
           }
 
           if (this.opts.allowUnresolvedVariables) {
+            // Check if outer expression has fallbacks we can use
+            // valueCount[0] is the primary var, valueCount[1+] are fallbacks
+            if (valueCount.length > 1) {
+              const primaryVar = valueCount[0]
+              // If the unresolvable variableString is used INSIDE the primary var,
+              // return undefined to trigger the outer fallback mechanism
+              if (primaryVar.includes(variableString)) {
+                return Promise.resolve(undefined)
+              }
+            }
             // Encode unresolved variable to pass through resolution
             return Promise.resolve(encodeUnknown(propertyString))
           }
@@ -2885,7 +2937,7 @@ Missing Value ${missingValue} - ${matchedString}
         if (typeof val === 'string' && val.match(/deep:/)) {
           // TODO refactor the deep filter logic here. match | filter | filter..
           const allFilters = propertyString
-            .replace(/}$/, '')
+            .replace(this.varSuffixPattern, '')
             .split('|')
             .reduce((acc, currentFilter, i) => {
               if (i === 0) {
@@ -2895,7 +2947,7 @@ Missing Value ${missingValue} - ${matchedString}
               return acc
             }, '')
           // add filters to deep references if filter is used
-          const deepValueWithFilters = newHasFilter[1] ? val.replace(/}$/, ` ${allFilters}}`) : val
+          const deepValueWithFilters = newHasFilter[1] ? val.replace(this.varSuffixPattern, ` ${allFilters}${this.varSuffix}`) : val
           // console.log('deepValueWithFilters', deepValueWithFilters)
           // console.log('RESOLVER RETURN newValue 4', deepValueWithFilters)
           return Promise.resolve(deepValueWithFilters)

package/src/utils/parsing/preProcess.js

@@ -3,16 +3,27 @@
  * and escape variables inside help() filter arguments
  */
 const { splitByComma } = require('../strings/splitByComma')
+const { extractVariableWrapper } = require('../variables/variableUtils')
 
 /**
  * Preprocess config to fix malformed fallback references
  * @param {Object} configObject - The parsed configuration object
  * @param {RegExp} variableSyntax - The variable syntax regex to use
+ * @param {Array} [variableTypes] - Array of variable type definitions with type/prefix fields
  * @returns {Object} The preprocessed configuration object
  */
-function preProcess(configObject, variableSyntax) {
-  // Known reference prefixes that should be wrapped in ${}
-  const refPrefixes = ['self:', 'opt:', 'env:', 'file:', 'text:', 'deep:']
+function preProcess(configObject, variableSyntax, variableTypes) {
+  // Extract prefix/suffix from variable syntax for reconstructing variables
+  const { prefix: varPrefix, suffix: varSuffix } = variableSyntax
+    ? extractVariableWrapper(variableSyntax.source)
+    : { prefix: '${', suffix: '}' }
+
+  // Extract reference prefixes from variable types, or use defaults
+  const refPrefixes = variableTypes && variableTypes.length > 0
+    ? variableTypes
+        .map(v => (v.prefix || v.type) + ':')
+        .filter(p => p !== 'dot.prop:' && p !== 'string:' && p !== 'number:')
+    : ['self:', 'opt:', 'env:', 'file:', 'text:', 'deep:']
 
   /**
    * Escape variables inside help() filter arguments so main resolver skips them
@@ -52,31 +63,37 @@ function preProcess(configObject, variableSyntax) {
     let changed = true
 
     // Keep iterating until no more changes (to handle nested variables)
+    const prefixLen = varPrefix.length
+    const suffixLen = varSuffix.length
+
     while (changed) {
       changed = false
 
-      // Find innermost ${...} blocks (ones that don't contain other ${)
+      // Find innermost variable blocks (ones that don't contain other variables)
       let i = 0
       while (i < result.length) {
-        if (result[i] === '$' && result[i + 1] === '{') {
+        if (result.substring(i, i + prefixLen) === varPrefix) {
           const start = i
-          let braceCount = 1
-          let j = i + 2
-
-          // Find the matching closing brace by counting { and }
-          while (j < result.length && braceCount > 0) {
-            if (result[j] === '{') {
-              braceCount++
-            } else if (result[j] === '}') {
-              braceCount--
+          let depth = 1
+          let j = i + prefixLen
+
+          // Find the matching suffix by counting full prefix/suffix occurrences
+          while (j < result.length && depth > 0) {
+            if (result.substring(j, j + prefixLen) === varPrefix) {
+              depth++
+              j += prefixLen
+            } else if (result.substring(j, j + suffixLen) === varSuffix) {
+              depth--
+              if (depth > 0) j += suffixLen
+            } else {
+              j++
             }
-            j++
           }
 
-          if (braceCount === 0) {
-            const end = j
+          if (depth === 0) {
+            const end = j + suffixLen
             const match = result.substring(start, end)
-            const content = result.substring(start + 2, end - 1)
+            const content = result.substring(start + prefixLen, end - suffixLen)
 
             // Only process if there's a comma (indicating fallback syntax)
             if (content.includes(',')) {
@@ -84,10 +101,10 @@ function preProcess(configObject, variableSyntax) {
               const parts = splitByComma(content, variableSyntax)
 
               if (parts.length > 1) {
-                // Check if the first part has nested ${} - if so, skip this (process inner ones first)
+                // Check if the first part has nested variables - if so, skip this (process inner ones first)
                 const firstPart = parts[0]
-                if (firstPart.includes('${')) {
-                  i = start + 2 // Move past ${ to find inner variables
+                if (firstPart.includes(varPrefix)) {
+                  i = start + prefixLen // Move past prefix to find inner variables
                   continue
                 }
 
@@ -101,16 +118,16 @@ function preProcess(configObject, variableSyntax) {
 
                   // Check if this looks like a reference but is not wrapped
                   const looksLikeRef = refPrefixes.some(prefix => trimmed.startsWith(prefix))
-                  const alreadyWrapped = trimmed.startsWith('${') && trimmed.endsWith('}')
+                  const alreadyWrapped = trimmed.startsWith(varPrefix) && trimmed.endsWith(varSuffix)
 
                   if (looksLikeRef && !alreadyWrapped) {
-                    return ` \${${trimmed}}`
+                    return ` ${varPrefix}${trimmed}${varSuffix}`
                   }
 
                   return ` ${trimmed}`
                 })
 
-                const replacement = `\${${fixed.join(',')}}`
+                const replacement = `${varPrefix}${fixed.join(',')}${varSuffix}`
                 if (replacement !== match) {
                   result = result.substring(0, start) + replacement + result.substring(end)
                   changed = true
@@ -119,7 +136,7 @@ function preProcess(configObject, variableSyntax) {
               }
             }
 
-            i = start + 2 // Move past ${ to continue searching for nested variables
+            i = start + prefixLen // Move past prefix to continue searching for nested variables
           } else {
             i++
           }

package/src/utils/parsing/preProcess.test.js

@@ -0,0 +1,214 @@
+// Tests for preProcess utility (fixFallbacksInString)
+
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const preProcess = require('./preProcess')
+
+// Default ${} syntax
+const defaultSyntax = /\$\{([ ~:a-zA-Z0-9._\\'",\-\/\(\)]+?)\}/g
+
+// Custom syntaxes
+const doubleBraceSyntax = /\$\{\{([ ~:a-zA-Z0-9._\\'",\-\/\(\)]+?)\}\}/g
+const hashSyntax = /\#\{([ ~:a-zA-Z0-9._\\'",\-\/\(\)]+?)\}/g
+const angleSyntax = /\<([ ~:a-zA-Z0-9._\\'",\-\/\(\)]+?)\>/g
+
+// Tests for fixFallbacksInString with default ${} syntax
+test('fixFallbacksInString - wraps unwrapped self: fallback', () => {
+  const input = { key: '${opt:missing, self:fallback}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${opt:missing, ${self:fallback}}')
+})
+
+test('fixFallbacksInString - wraps unwrapped env: fallback', () => {
+  const input = { key: '${opt:missing, env:FALLBACK}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${opt:missing, ${env:FALLBACK}}')
+})
+
+test('fixFallbacksInString - wraps unwrapped opt: fallback', () => {
+  const input = { key: '${self:missing, opt:fallback}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${self:missing, ${opt:fallback}}')
+})
+
+test('fixFallbacksInString - wraps unwrapped file: fallback', () => {
+  const input = { key: '${opt:missing, file:./config.json}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${opt:missing, ${file:./config.json}}')
+})
+
+test('fixFallbacksInString - leaves already wrapped fallback alone', () => {
+  const input = { key: '${opt:missing, ${self:fallback}}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${opt:missing, ${self:fallback}}')
+})
+
+test('fixFallbacksInString - leaves string fallback alone', () => {
+  const input = { key: '${opt:missing, "default"}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${opt:missing, "default"}')
+})
+
+test('fixFallbacksInString - leaves numeric fallback alone', () => {
+  const input = { key: '${opt:missing, 42}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${opt:missing, 42}')
+})
+
+test('fixFallbacksInString - handles multiple fallbacks', () => {
+  const input = { key: '${opt:missing, self:first, env:second}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${opt:missing, ${self:first}, ${env:second}}')
+})
+
+test('fixFallbacksInString - handles nested variables in primary', () => {
+  const input = { key: '${file(./config.${opt:stage}.json), "default"}' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, '${file(./config.${opt:stage}.json), "default"}')
+})
+
+// Tests for ${{}} syntax
+test('fixFallbacksInString - ${{}} syntax wraps unwrapped fallback', () => {
+  const input = { key: '${{opt:missing, self:fallback}}' }
+  const result = preProcess(input, doubleBraceSyntax)
+  assert.is(result.key, '${{opt:missing, ${{self:fallback}}}}')
+})
+
+test('fixFallbacksInString - ${{}} syntax leaves wrapped fallback alone', () => {
+  const input = { key: '${{opt:missing, ${{self:fallback}}}}' }
+  const result = preProcess(input, doubleBraceSyntax)
+  assert.is(result.key, '${{opt:missing, ${{self:fallback}}}}')
+})
+
+test('fixFallbacksInString - ${{}} syntax leaves string fallback alone', () => {
+  const input = { key: '${{opt:missing, "default"}}' }
+  const result = preProcess(input, doubleBraceSyntax)
+  assert.is(result.key, '${{opt:missing, "default"}}')
+})
+
+// Tests for #{} syntax
+test('fixFallbacksInString - #{} syntax wraps unwrapped fallback', () => {
+  const input = { key: '#{opt:missing, self:fallback}' }
+  const result = preProcess(input, hashSyntax)
+  assert.is(result.key, '#{opt:missing, #{self:fallback}}')
+})
+
+test('fixFallbacksInString - #{} syntax leaves wrapped fallback alone', () => {
+  const input = { key: '#{opt:missing, #{self:fallback}}' }
+  const result = preProcess(input, hashSyntax)
+  assert.is(result.key, '#{opt:missing, #{self:fallback}}')
+})
+
+test('fixFallbacksInString - #{} syntax handles multiple fallbacks', () => {
+  const input = { key: '#{opt:missing, env:FIRST, self:second}' }
+  const result = preProcess(input, hashSyntax)
+  assert.is(result.key, '#{opt:missing, #{env:FIRST}, #{self:second}}')
+})
+
+// Tests for <> syntax
+test('fixFallbacksInString - <> syntax wraps unwrapped fallback', () => {
+  const input = { key: '<opt:missing, self:fallback>' }
+  const result = preProcess(input, angleSyntax)
+  assert.is(result.key, '<opt:missing, <self:fallback>>')
+})
+
+test('fixFallbacksInString - <> syntax leaves wrapped fallback alone', () => {
+  const input = { key: '<opt:missing, <self:fallback>>' }
+  const result = preProcess(input, angleSyntax)
+  assert.is(result.key, '<opt:missing, <self:fallback>>')
+})
+
+test('fixFallbacksInString - <> syntax leaves string fallback alone', () => {
+  const input = { key: '<opt:missing, "default">' }
+  const result = preProcess(input, angleSyntax)
+  assert.is(result.key, '<opt:missing, "default">')
+})
+
+// Edge cases
+test('fixFallbacksInString - handles deeply nested objects', () => {
+  const input = {
+    level1: {
+      level2: {
+        key: '${opt:missing, self:fallback}'
+      }
+    }
+  }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.level1.level2.key, '${opt:missing, ${self:fallback}}')
+})
+
+test('fixFallbacksInString - handles arrays', () => {
+  const input = {
+    items: [
+      '${opt:one, self:fallback1}',
+      '${opt:two, self:fallback2}'
+    ]
+  }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.items[0], '${opt:one, ${self:fallback1}}')
+  assert.is(result.items[1], '${opt:two, ${self:fallback2}}')
+})
+
+test('fixFallbacksInString - handles no variable syntax', () => {
+  const input = { key: 'just a plain string' }
+  const result = preProcess(input, defaultSyntax)
+  assert.is(result.key, 'just a plain string')
+})
+
+test('fixFallbacksInString - handles null variableSyntax', () => {
+  const input = { key: '${opt:missing, self:fallback}' }
+  const result = preProcess(input, null)
+  // Without syntax, should use defaults
+  assert.is(result.key, '${opt:missing, ${self:fallback}}')
+})
+
+// Tests with explicit variableTypes
+const defaultVariableTypes = [
+  { type: 'env' },
+  { type: 'options', prefix: 'opt' },
+  { type: 'self', prefix: 'self' },
+  { type: 'file', prefix: 'file' },
+  { type: 'text', prefix: 'text' },
+  { type: 'deep' },
+]
+
+test('fixFallbacksInString - uses variableTypes to determine prefixes', () => {
+  const input = { key: '${opt:missing, self:fallback}' }
+  const result = preProcess(input, defaultSyntax, defaultVariableTypes)
+  assert.is(result.key, '${opt:missing, ${self:fallback}}')
+})
+
+test('fixFallbacksInString - custom variableTypes with custom prefix', () => {
+  const customTypes = [
+    { type: 'ssm', prefix: 'ssm' },
+    { type: 'secret', prefix: 'secret' },
+  ]
+  const input = { key: '${opt:missing, ssm:/path/to/param}' }
+  const result = preProcess(input, defaultSyntax, customTypes)
+  assert.is(result.key, '${opt:missing, ${ssm:/path/to/param}}')
+})
+
+test('fixFallbacksInString - custom variableTypes wraps secret: fallback', () => {
+  const customTypes = [
+    { type: 'ssm', prefix: 'ssm' },
+    { type: 'secret', prefix: 'secret' },
+    { type: 'self', prefix: 'self' },
+  ]
+  const input = { key: '${self:missing, secret:API_KEY}' }
+  const result = preProcess(input, defaultSyntax, customTypes)
+  assert.is(result.key, '${self:missing, ${secret:API_KEY}}')
+})
+
+test('fixFallbacksInString - ignores dot.prop and string types in prefixes', () => {
+  const typesWithDotProp = [
+    { type: 'env' },
+    { type: 'dot.prop' },
+    { type: 'string' },
+    { type: 'self', prefix: 'self' },
+  ]
+  const input = { key: '${env:MISSING, self:fallback}' }
+  const result = preProcess(input, defaultSyntax, typesWithDotProp)
+  assert.is(result.key, '${env:MISSING, ${self:fallback}}')
+})
+
+test.run()

package/src/utils/variables/variableUtils.js

@@ -1,3 +1,45 @@
+/**
+ * Extract variable prefix/suffix from regex source
+ * @param {string} syntaxSource - The regex source string (e.g., '\\$\\{(...)\\}')
+ * @returns {{ prefix: string, suffix: string }} The unescaped prefix and suffix
+ */
+function extractVariableWrapper(syntaxSource) {
+  // Find first capturing group ( that's not escaped and not a special group (?:, (?=, etc.)
+  let openParen = -1
+  for (let i = 0; i < syntaxSource.length; i++) {
+    if (syntaxSource[i] === '(' && (i === 0 || syntaxSource[i - 1] !== '\\')) {
+      // Check if it's a special group like (?:, (?=, (?!, (?<
+      if (syntaxSource[i + 1] !== '?') {
+        openParen = i
+        break
+      }
+    }
+  }
+
+  // Find last ) that's not escaped
+  let closeParen = -1
+  for (let i = syntaxSource.length - 1; i >= 0; i--) {
+    if (syntaxSource[i] === ')' && (i === 0 || syntaxSource[i - 1] !== '\\')) {
+      closeParen = i
+      break
+    }
+  }
+
+  let escapedPrefix = openParen > 0 ? syntaxSource.substring(0, openParen) : ''
+  const escapedSuffix = closeParen >= 0 ? syntaxSource.substring(closeParen + 1) : ''
+
+  // Strip any leading non-capturing groups like (?:...) from prefix
+  escapedPrefix = escapedPrefix.replace(/^\(\?:[^)]*\)/g, '')
+
+  // Unescape regex escapes: \$ -> $, \{ -> {, \[ -> [, etc.
+  const unescape = (s) => s.replace(/\\(.)/g, '$1')
+
+  return {
+    prefix: unescape(escapedPrefix) || '${',
+    suffix: unescape(escapedSuffix) || '}'
+  }
+}
+
 /**
  * Get fallback variable string
  * @param {string[]} split - Array from split at comma
@@ -47,6 +89,7 @@ Remove or update the \${${variableString}} to fix
 }
 
 module.exports = {
+  extractVariableWrapper,
   getFallbackString,
   verifyVariable
 } 

package/src/utils/variables/variableUtils.test.js

@@ -1,6 +1,6 @@
 const { test } = require('uvu')
 const assert = require('uvu/assert')
-const { getFallbackString, verifyVariable } = require('./variableUtils')
+const { extractVariableWrapper, getFallbackString, verifyVariable } = require('./variableUtils')
 
 // Tests for getFallbackString
 test('getFallbackString - should reconstruct variable from split array', () => {
@@ -113,5 +113,42 @@ test('verifyVariable - should match with function and config param', () => {
   assert.is(result, true)
 })
 
+// Tests for extractVariableWrapper
+test('extractVariableWrapper - standard ${} syntax', () => {
+  const result = extractVariableWrapper('\\$\\{([^}]+)\\}')
+  assert.equal(result.prefix, '${')
+  assert.equal(result.suffix, '}')
+})
+
+test('extractVariableWrapper - double brace ${{}} syntax', () => {
+  const result = extractVariableWrapper('\\$\\{\\{([^}]+)\\}\\}')
+  assert.equal(result.prefix, '${{')
+  assert.equal(result.suffix, '}}')
+})
+
+test('extractVariableWrapper - hash #{} syntax', () => {
+  const result = extractVariableWrapper('\\#\\{([^}]+)\\}')
+  assert.equal(result.prefix, '#{')
+  assert.equal(result.suffix, '}')
+})
+
+test('extractVariableWrapper - angle bracket <> syntax', () => {
+  const result = extractVariableWrapper('\\<([^>]+)\\>')
+  assert.equal(result.prefix, '<')
+  assert.equal(result.suffix, '>')
+})
+
+test('extractVariableWrapper - double bracket [[]] syntax', () => {
+  const result = extractVariableWrapper('\\[\\[([^\\]]+)\\]\\]')
+  assert.equal(result.prefix, '[[')
+  assert.equal(result.suffix, ']]')
+})
+
+test('extractVariableWrapper - strips non-capturing group prefix', () => {
+  const result = extractVariableWrapper('(?:prefix)\\$\\{([^}]+)\\}')
+  assert.equal(result.prefix, '${')
+  assert.equal(result.suffix, '}')
+})
+
 // Run all tests
 test.run()