configorama 0.7.1 → 0.8.0

package/README.md

@@ -29,14 +29,18 @@ See [tests](https://github.com/DavidWells/configorama/tree/master/tests) for mor
 <summary>Click to expand</summary>
 
 - [About](#about)
-- [How it works](#how-it-works)
 - [Usage](#usage)
+- [How it works](#how-it-works)
 - [Variable Sources](#variable-sources)
   - [Environment variables](#environment-variables)
   - [CLI option flags](#cli-option-flags)
+  - [Parameter values](#parameter-values)
   - [Self references](#self-references)
   - [File references](#file-references)
   - [Sync/Async file references](#syncasync-file-references)
+    - [Passing arguments to functions](#passing-arguments-to-functions)
+    - [ConfigContext](#configcontext)
+    - [Functions without arguments](#functions-without-arguments)
   - [TypeScript file references](#typescript-file-references)
   - [Git references](#git-references)
   - [Cron Values](#cron-values)
@@ -45,7 +49,11 @@ See [tests](https://github.com/DavidWells/configorama/tree/master/tests) for mor
   - [Functions (experimental)](#functions-experimental)
   - [More Examples](#more-examples)
 - [Custom Variable Sources](#custom-variable-sources)
+  - [Variable Source Types](#variable-source-types)
 - [Options](#options)
+  - [Custom Variable Syntax](#custom-variable-syntax)
+  - [allowUnknownVariableTypes](#allowunknownvariabletypes)
+  - [allowUnresolvedVariables](#allowunresolvedvariables)
 - [FAQ](#faq)
 - [Whats new](#whats-new)
 - [Alt libs](#alt-libs)
@@ -136,6 +144,7 @@ console.log(result.resolutionHistory) // Step-by-step resolution for each path
 |----------|-----------------------|------------------------|
 | env      | ${env:VAR}            | Environment variables  |
 | opt      | ${opt:flag}           | CLI option flags       |
+| param    | ${param:key}          | Parameter values       |
 | self     | ${key} or ${self:key} | Self references        |
 | file     | ${file(path)}         | File references        |
 | git      | ${git:value}          | Git data               |
@@ -168,6 +177,58 @@ foo: ${opt:stage}-hello
 foo: ${opt:stage, 'dev'}
 ```
 
+### Parameter values
+
+Access parameter values via `${param:key}`. Parameters follow a resolution hierarchy:
+
+1. **CLI params** (`--param="key=value"`) - highest priority
+2. **Stage-specific params** (`stages.<stage>.params`)
+3. **Default params** (`stages.default.params`)
+
+```yml
+# Direct parameter reference
+appDomain: ${param:domain}
+
+# Parameter with fallback
+apiKey: ${param:apiKey, 'default-api-key'}
+
+# Stage-specific parameters defined in config
+stages:
+  dev:
+    params:
+      domain: dev.myapp.com
+      dbHost: localhost
+  prod:
+    params:
+      domain: myapp.com
+      dbHost: prod-db.myapp.com
+  default:
+    params:
+      domain: default.myapp.com
+      dbPort: 3306
+```
+
+**CLI Usage:**
+
+```bash
+# Single param
+node app.js --param="domain=example.com"
+
+# Multiple params
+node app.js --param="domain=example.com" --param="apiKey=secret123"
+```
+
+**Code Usage:**
+
+```js
+const config = await configorama('config.yml', {
+  options: {
+    stage: 'prod',
+    param: ['domain=cli-override.com', 'apiKey=secret']
+  }
+})
+```
+
 ### Self references
 
 Reference values from other key paths in the same configuration file.
@@ -682,6 +743,7 @@ The `source` property defines how the config wizard handles each variable type:
 |----------|-------------|-------------|
 | `${env:VAR}` | `user` | Environment variables |
 | `${opt:flag}` | `user` | CLI option flags |
+| `${param:key}` | `user` | Parameter values |
 | `${self:key}` | `config` | Self references |
 | `${file(path)}` | `config` | File references |
 | `${text(path)}` | `config` | Raw text file references |
@@ -694,42 +756,125 @@ The `source` property defines how the config wizard handles each variable type:
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `options` | object | `{}` | CLI options/flags to populate `${opt:xyz}` variables |
-| `allowUnknownVariables` | boolean | `false` | Allow unknown variable types to pass through (e.g., `${custom:thing}`) |
-| `allowUnresolvedVariables` | boolean | `false` | Allow known variable types that can't be resolved to pass through instead of throwing |
+| `syntax` | string/RegExp | `${...}` | Custom variable syntax regex pattern |
+| `allowUnknownVariableTypes` | boolean \| string[] | `false` | Allow unknown variable types to pass through (e.g., `${ssm:path}`) |
+| `allowUnresolvedVariables` | boolean \| string[] | `false` | Allow known variable types that can't be resolved to pass through |
 | `allowUndefinedValues` | boolean | `false` | Allow undefined to be an end result |
 | `variableSources` | array | `[]` | Custom variable sources (see above) |
 
-> **Note:** `allowUnknownVars` is deprecated, use `allowUnknownVariables` instead.
+> **Note:** Legacy options `allowUnknownVars`, `allowUnknownVariables`, `allowUnknownParams`, and `allowUnknownFileRefs` are deprecated. Use `allowUnknownVariableTypes` and `allowUnresolvedVariables` instead.
+
+<details>
+<summary><strong>Migration Guide</strong></summary>
+
+**From legacy options to new API:**
+
+```js
+// OLD → NEW
+
+// Unknown variable types (unregistered resolvers)
+{ allowUnknownVars: true }        → { allowUnknownVariableTypes: true }
+{ allowUnknownVariables: true }   → { allowUnknownVariableTypes: true }
+
+// Unresolved params
+{ allowUnknownParams: true }      → { allowUnresolvedVariables: ['param'] }
+
+// Unresolved file refs
+{ allowUnknownFileRefs: true }    → { allowUnresolvedVariables: ['file'] }
+
+// Both params and files
+{ allowUnknownParams: true, allowUnknownFileRefs: true }
+→ { allowUnresolvedVariables: ['param', 'file'] }
+
+// All unresolved (env, opt, file, param, etc.)
+{ allowUnresolvedVariables: true }  // unchanged, now also accepts arrays
+```
+
+**New array syntax allows granular control:**
+
+```js
+// Only allow specific unknown types
+{ allowUnknownVariableTypes: ['ssm', 'cf', 's3'] }
 
-### allowUnknownVariables
+// Only allow specific resolver types to fail gracefully
+{ allowUnresolvedVariables: ['param'] }  // only params, env/file/opt still throw
+```
+
+Legacy options still work but will be removed in a future major version.
+
+</details>
 
-When `allowUnknownVariables: true`, unknown variable types (not registered resolvers) pass through as-is:
+### Custom Variable Syntax
+
+Use the `syntax` option to change the variable delimiters. You can provide a regex string directly or use `buildVariableSyntax()` to generate one with proper character escaping:
 
 ```js
+const configorama = require('configorama')
+const { buildVariableSyntax } = require('configorama')
+
+// Using buildVariableSyntax helper (recommended)
 const config = await configorama(configFile, {
-  allowUnknownVariables: true,
+  syntax: buildVariableSyntax('{{', '}}'),  // Mustache-style: {{env:FOO}}
   options: { stage: 'dev' }
 })
 
-// Input:  { key: '${ssm:/path/to/secret}' }  // ssm: not a registered type
-// Output: { key: '${ssm:/path/to/secret}' }  // passes through instead of throwing
+// Other examples:
+buildVariableSyntax('${{', '}}')   // ${{env:FOO}}
+buildVariableSyntax('#{', '}')     // #{env:FOO}
+buildVariableSyntax('[[', ']]')    // [[env:FOO]]
+buildVariableSyntax('<', '>')      // <env:FOO>
+```
+
+The `buildVariableSyntax(prefix, suffix, excludePatterns)` function:
+- Automatically excludes suffix characters from the allowed character class (prevents parsing issues)
+- Supports nested variables by excluding `$` and `{` from values
+- Third parameter `excludePatterns` is an array of strings to exclude via negative lookahead (default: `['AWS', 'stageVariables']`)
+
+### allowUnknownVariableTypes
+
+Controls what happens when encountering unregistered variable types (e.g., `${ssm:path}` when `ssm` isn't a registered resolver).
+
+```js
+// Allow ALL unknown types to pass through
+const config = await configorama(configFile, {
+  allowUnknownVariableTypes: true,
+  options: { stage: 'dev' }
+})
+// Input:  { key: '${ssm:/path/to/secret}' }
+// Output: { key: '${ssm:/path/to/secret}' }
+
+// Allow only SPECIFIC unknown types
+const config = await configorama(configFile, {
+  allowUnknownVariableTypes: ['ssm', 'cf'],  // only these pass through
+  options: { stage: 'dev' }
+})
+// ${ssm:path} and ${cf:stack.output} pass through
+// ${custom:thing} throws an error
 ```
 
 ### allowUnresolvedVariables
 
-When `allowUnresolvedVariables: true`, variables that can't be resolved (missing env vars, missing files, etc.) pass through as-is instead of throwing an error:
+Controls what happens when a known resolver can't find a value (missing env vars, missing files, etc.).
 
 ```js
+// Allow ALL unresolved variables to pass through
 const config = await configorama(configFile, {
   allowUnresolvedVariables: true,
   options: { stage: 'dev' }
 })
-
 // Input:  { key: '${env:MISSING_VAR}' }
-// Output: { key: '${env:MISSING_VAR}' }  // passes through instead of throwing
+// Output: { key: '${env:MISSING_VAR}' }
+
+// Allow only SPECIFIC types to be unresolved
+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
 ```
 
-This is useful for multi-stage resolution or when you want to analyze config structure without providing all values.
+This is useful for multi-stage resolution (e.g., Serverless Dashboard resolves params after local resolution).
 
 ## FAQ
 

package/cli.js

@@ -10,7 +10,7 @@ const { makeBox } = require('@davidwells/box-logger')
 
 // Parse command line arguments
 const argv = minimist(process.argv.slice(2), {
-  string: ['output', 'o', 'format', 'f'],
+  string: ['output', 'o', 'format', 'f', 'param'],
   boolean: ['help', 'h', 'version', 'v', 'debug', 'allow-unknown', 'allow-undefined', 'list', 'info', 'verify'],
   alias: {
     h: 'help',
@@ -41,6 +41,7 @@ Options:
   -d, --debug               Enable debug mode
   -i, --info                Show info about the config
   -v, --verify              Verify the config
+  --param <key=value>       Pass parameter values (can be used multiple times)
   --allow-unknown           Allow unknown variables to pass through
   --allow-undefined         Allow undefined values in the final output
 
@@ -49,6 +50,7 @@ Examples:
   configorama --info config.yml
   configorama --format yaml config.json
   configorama --output resolved.json config.yml
+  configorama --param="domain=myapp.com" --param="key=value" config.yml
   configorama --allow-unknown config.toml
   `)
   process.exit(0)

package/index.d.ts

@@ -17,10 +17,43 @@ export interface ConfigoramaSettings {
   filters?: Record<string, Function>
   /** Object of custom functions */
   functions?: Record<string, Function>
-  /** Allow unknown variables to pass through without throwing errors */
-  allowUnknownVars?: boolean
-  /** Allow undefined values to pass through without throwing errors */
+  /** Parameters to populate for ${param:xyz} */
+  params?: Record<string, any>
+
+  // === Variable Resolution Options ===
+
+  /**
+   * Allow unknown variable types (unregistered resolvers) to pass through.
+   * - `true`: All unknown types pass through (e.g., ${ssm:path}, ${cf:stack})
+   * - `false`: Throws on unknown types
+   * - `string[]`: Only specified types pass through (e.g., ['ssm', 'cf'])
+   */
+  allowUnknownVariableTypes?: boolean | string[]
+
+  /**
+   * Allow known variable types that can't resolve to pass through.
+   * - `true`: All unresolved variables pass through
+   * - `false`: Throws when resolution fails
+   * - `string[]`: Only specified types pass through (e.g., ['param', 'file'])
+   */
+  allowUnresolvedVariables?: boolean | string[]
+
+  /** Allow undefined values as final results */
   allowUndefinedValues?: boolean
+
+  // === Legacy Options (deprecated, use above instead) ===
+
+  /** @deprecated Use allowUnknownVariableTypes instead */
+  allowUnknownVars?: boolean
+  /** @deprecated Use allowUnknownVariableTypes instead */
+  allowUnknownVariables?: boolean
+  /** @deprecated Use allowUnresolvedVariables: ['param'] instead */
+  allowUnknownParams?: boolean
+  /** @deprecated Use allowUnresolvedVariables: ['file'] instead */
+  allowUnknownFileRefs?: boolean
+
+  // === Other Options ===
+
   /** Values passed into .js config files if user using javascript config */
   dynamicArgs?: object | Function
   /** Return both config and metadata about variables found */

package/package.json

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

package/src/index.js

@@ -1,8 +1,7 @@
 const Configorama = require('./main')
 const parsers = require('./parsers')
 const enrichMetadata = require('./utils/parsing/enrichMetadata')
-
-module.exports.Configorama = Configorama
+const { buildVariableSyntax } = require('./utils/variables/variableUtils')
 
 /**
  * @typedef {Object} ConfigoramaSettings
@@ -130,3 +129,17 @@ module.exports.analyze = async (configPathOrObject, settings = {}) => {
  * @type {Object}
  */
 module.exports.format = parsers
+
+/**
+ * Configorama class for advanced usage
+ */
+module.exports.Configorama = Configorama
+
+/**
+ * Build variable syntax regex with proper character escaping
+ * @param {string} [prefix='${'] - Variable prefix (e.g., '${', '{{', '[[')
+ * @param {string} [suffix='}'] - Variable suffix (e.g., '}', '}}', ']]')
+ * @param {string[]} [excludePatterns] - Patterns to exclude via negative lookahead
+ * @returns {string} Regex source string for use with syntax option
+ */
+module.exports.buildVariableSyntax = buildVariableSyntax

package/src/main.js

@@ -2,19 +2,16 @@
 const os = require('os')
 const path = require('path')
 const fs = require('fs')
-
 /* // disable logs to find broken tests
 console.log = () => {}
 // process.exit(1)
 /** */
-
 /* External dependencies */
 const promiseFinallyShim = require('promise.prototype.finally').shim()
 const findUp = require('find-up')
 const traverse = require('traverse')
 const dotProp = require('dot-prop')
 const { makeBox, makeStackedBoxes } = require('@davidwells/box-logger')
-
 /* Utils - root */
 const {
   isArray, isString, isNumber, isObject, isDate, isRegExp, isFunction,
@@ -23,71 +20,56 @@ const {
 } = require('./utils/lodash')
 const PromiseTracker = require('./utils/PromiseTracker')
 const handleSignalEvents = require('./utils/handleSignalEvents')
-
 /* Utils - encoders */
 const { encodeUnknown, decodeUnknown } = require('./utils/encoders/unknown-values')
 const { decodeEncodedValue } = require('./utils/encoders')
-const { encodeJsSyntax, decodeJsSyntax, hasParenthesesPlaceholder, encodeJsonForVariable } = require('./utils/encoders/js-fixes')
-
+const { decodeJsSyntax, hasParenthesesPlaceholder, encodeJsonForVariable } = require('./utils/encoders/js-fixes')
 /* Utils - parsing */
 const enrichMetadata = require('./utils/parsing/enrichMetadata')
 const preProcess = require('./utils/parsing/preProcess')
 const { parseFileContents } = require('./utils/parsing/parse')
 const { mergeByKeys } = require('./utils/parsing/mergeByKeys')
 const { arrayToJsonPath } = require('./utils/parsing/arrayToJsonPath')
-
 /* Utils - paths */
 const { normalizePath, extractFilePath, resolveInnerVariables } = require('./utils/paths/filePathUtils')
-const { resolveAlias } = require('./utils/paths/resolveAlias')
-const { resolveFilePathFromMatch } = require('./utils/paths/getFullFilePath')
 const { findLineForKey } = require('./utils/paths/findLineForKey')
-
 /* Utils - regex */
-const { combineRegexes, funcRegex, funcStartOfLineRegex, subFunctionRegex } = require('./utils/regex')
-
+const { combineRegexes, funcRegex } = require('./utils/regex')
 /* Utils - strings */
 const formatFunctionArgs = require('./utils/strings/formatFunctionArgs')
-
 const { splitByComma } = require('./utils/strings/splitByComma')
 const { splitCsv } = require('./utils/strings/splitCsv')
 const { replaceAll } = require('./utils/strings/replaceAll')
 const { getTextAfterOccurrence, findNestedVariable } = require('./utils/strings/textUtils')
-const { trimSurroundingQuotes, ensureQuote, isSurroundedByQuotes, startsWithQuotedPipe } = require('./utils/strings/quoteUtils')
-
+const { ensureQuote, isSurroundedByQuotes, startsWithQuotedPipe } = require('./utils/strings/quoteUtils')
 /* Utils - ui */
 const chalk = require('./utils/ui/chalk')
 const deepLog = require('./utils/ui/deep-log')
 const { logHeader } = require('./utils/ui/logs')
 const { createEditorLink } = require('./utils/ui/createEditorLink')
 const { runConfigWizard, isSensitiveVariable } = require('./utils/ui/configWizard')
-
 /* Utils - validation */
 const { warnIfNotFound, isValidValue } = require('./utils/validation/warnIfNotFound')
-
 /* Utils - variables */
 const cleanVariable = require('./utils/variables/cleanVariable')
 const appendDeepVariable = require('./utils/variables/appendDeepVariable')
-const { extractVariableWrapper, getFallbackString, verifyVariable } = require('./utils/variables/variableUtils')
+const { extractVariableWrapper, getFallbackString, verifyVariable, buildVariableSyntax } = require('./utils/variables/variableUtils')
 const { findNestedVariables } = require('./utils/variables/findNestedVariables')
-
 /* Resolvers */
 const getValueFromString = require('./resolvers/valueFromString')
 const getValueFromNumber = require('./resolvers/valueFromNumber')
 const getValueFromEnv = require('./resolvers/valueFromEnv')
 const getValueFromOptions = require('./resolvers/valueFromOptions')
+const getValueFromParam = require('./resolvers/valueFromParam')
 const getValueFromCron = require('./resolvers/valueFromCron')
 const getValueFromEval = require('./resolvers/valueFromEval')
 const createGitResolver = require('./resolvers/valueFromGit')
 const { getValueFromFile: getValueFromFileResolver } = require('./resolvers/valueFromFile')
-
 /* Parsers */
-const YAML = require('./parsers/yaml')
-const TOML = require('./parsers/toml')
-const INI = require('./parsers/ini')
 const JSON5 = require('./parsers/json5')
-
 /* Functions */
 const md5Function = require('./functions/md5')
+
 /**
  * Maintainer's notes:
  *
@@ -102,6 +84,7 @@ const md5Function = require('./functions/md5')
  *   pause population, noting the continued depth to traverse.  This motivated "deep" variables.
  *   Original issue #4687
  */
+
 const deepRefSyntax = RegExp(/(\${)?deep:\d+(\.[^}]+)*()}?/)
 const deepIndexReplacePattern = new RegExp(/^deep:|(\.[^}]+)*$/g)
 const deepIndexPattern = /deep\:(\d*)/
@@ -110,8 +93,6 @@ const fileRefSyntax = RegExp(/^file\((~?[@\{\}\:\$a-zA-Z0-9._\-\/,'" =+]+?)\)/g)
 const textRefSyntax = RegExp(/^text\((~?[@\{\}\:\$a-zA-Z0-9._\-\/,'" =+]+?)\)/g)
 // TODO update file regex ^file\((~?[a-zA-Z0-9._\-\/, ]+?)\)
 // To match file(asyncValue.js, lol) input params
-const envRefSyntax = RegExp(/^env:/g)
-const optRefSyntax = RegExp(/^opt:/g)
 const selfRefSyntax = RegExp(/^self:/g)
 const base64WrapperRegex = /\[_\[([A-Za-z0-9+/=\s]*)\]_\]/g
 const logLines = '─────────────────────────────────────────────────'
@@ -133,13 +114,13 @@ class Configorama {
     const options = opts || {}
     // Set opts to pass into JS file calls
     this.settings = Object.assign({}, {
-      // Allow for unknown variable syntax to pass through without throwing errors
-      allowUnknownVariables: false,
-      // Allow undefined to be an end result.
+      // Allow unknown ${xyz:...} syntax where xyz is not a registered resolver
+      // Can be: false | true | ['ssm', 'cf', ...]
+      allowUnknownVariableTypes: false,
+      // Allow undefined to be an end result
       allowUndefinedValues: false,
-      // Allow unknown file refs to pass through without throwing errors
-      allowUnknownFileRefs: false,
       // Allow known variable types that can't be resolved to pass through
+      // Can be: false | true | ['param', 'file', 'env', ...]
       allowUnresolvedVariables: false,
       // Return metadata
       returnMetadata: false,
@@ -147,11 +128,27 @@ class Configorama {
       returnPreResolvedVariableDetails: false,
     }, options)
 
-    // Backward compat: allowUnknownVars -> allowUnknownVariables
-    if (options.allowUnknownVars !== undefined && options.allowUnknownVariables === undefined) {
-      this.settings.allowUnknownVariables = options.allowUnknownVars
+    // Backward compat: allowUnknownVars -> allowUnknownVariableTypes
+    if (options.allowUnknownVars !== undefined && options.allowUnknownVariableTypes === undefined) {
+      this.settings.allowUnknownVariableTypes = options.allowUnknownVars
+    }
+    // Backward compat: allowUnknownVariables -> allowUnknownVariableTypes
+    if (options.allowUnknownVariables !== undefined && options.allowUnknownVariableTypes === undefined) {
+      this.settings.allowUnknownVariableTypes = options.allowUnknownVariables
     }
 
+    // Merge legacy allowUnknownParams and allowUnknownFileRefs into allowUnresolvedVariables
+    let unresolvedSetting = this.settings.allowUnresolvedVariables
+    if (unresolvedSetting !== true) {
+      const specificTypes = Array.isArray(unresolvedSetting) ? [...unresolvedSetting] : []
+      if (options.allowUnknownParams) specificTypes.push('param')
+      if (options.allowUnknownFileRefs) specificTypes.push('file')
+      if (specificTypes.length > 0) {
+        unresolvedSetting = [...new Set(specificTypes)]
+      }
+    }
+    this.settings.allowUnresolvedVariables = unresolvedSetting
+
     this.filterCache = {}
 
     this.foundVariables = []
@@ -160,8 +157,8 @@ class Configorama {
     // Track variable resolutions for metadata (keyed by path)
     this.resolutionTracking = {}
 
-    const defaultSyntax = '\\${((?!AWS|stageVariables)[ ~:a-zA-Z0-9=+!@#%*<>?._\'",|\\-\\/\\(\\)\\\\]+?)}'
-  
+    const defaultSyntax = buildVariableSyntax('${', '}', ['AWS', 'stageVariables'])
+
     const varSyntax = options.syntax || defaultSyntax
     let varRegex
     if (typeof varSyntax === 'string') {
@@ -229,6 +226,14 @@ class Configorama {
        */
       getValueFromOptions,
 
+      /**
+       * Parameters
+       * Usage:
+       * ${param:domain}
+       * ${param:key, "fallbackValue"}
+       */
+      getValueFromParam,
+
       /**
        * Cron expressions
        * Usage:
@@ -542,6 +547,56 @@ class Configorama {
     this.callCount = 0
   }
 
+  /**
+   * Check if unresolved variables of a given type should pass through
+   * @param {string} type - The resolver type (e.g., 'param', 'file', 'env')
+   * @returns {boolean}
+   */
+  isUnresolvedAllowed(type) {
+    const setting = this.settings.allowUnresolvedVariables
+    if (setting === true) return true
+    if (setting === false || setting === undefined) return false
+    if (Array.isArray(setting) && setting.includes(type)) return true
+    return false
+  }
+
+  /**
+   * Extract type prefix from a variable string
+   * @param {string} varString - Variable string like 'ssm:path/to/thing' or 'custom:value'
+   * @returns {string|null} The type prefix or null if not found
+   */
+  extractTypePrefix(varString) {
+    if (!varString || typeof varString !== 'string') return null
+    const colonIndex = varString.indexOf(':')
+    if (colonIndex === -1) return null
+    return varString.substring(0, colonIndex)
+  }
+
+  /**
+   * Check if unknown variable types should pass through
+   * @param {string} varString - Variable string like 'ssm:path' or full '${ssm:path}'
+   * @returns {boolean}
+   */
+  isUnknownTypeAllowed(varString) {
+    const setting = this.settings.allowUnknownVariableTypes
+    if (setting === true) return true
+    if (setting === false || setting === undefined) return false
+    if (Array.isArray(setting)) {
+      // Extract type prefix from variable string
+      // Handle both 'ssm:path' and '${ssm:path}' formats
+      let cleanVar = varString
+      if (cleanVar.startsWith(this.varPrefix)) {
+        cleanVar = cleanVar.slice(this.varPrefix.length)
+      }
+      if (cleanVar.endsWith(this.varSuffix)) {
+        cleanVar = cleanVar.slice(0, -this.varSuffix.length)
+      }
+      const typePrefix = this.extractTypePrefix(cleanVar)
+      if (typePrefix && setting.includes(typePrefix)) return true
+    }
+    return false
+  }
+
   // ################
   // ## PUBLIC API ##
   // ################
@@ -1941,8 +1996,8 @@ class Configorama {
     for (let i = 0; i < matches.length; i += 1) {
       warnIfNotFound(matches[i].variable, results[i], {
         patterns: {
-          env: envRefSyntax,
-          opt: optRefSyntax,
+          env: getValueFromEnv.match,
+          opt: getValueFromOptions.match,
           self: selfRefSyntax,
           file: fileRefSyntax,
           deep: deepRefSyntax,
@@ -2380,7 +2435,7 @@ class Configorama {
 
       if (nestedVar) {
         const fallbackStr = getFallbackString(splitVars, nestedVar)
-        if (!this.settings.allowUnknownVariables) {
+        if (!this.isUnknownTypeAllowed(nestedVar)) {
           verifyVariable(nestedVar, valueObject, this.variableTypes, this.config)
         }
 
@@ -2864,14 +2919,21 @@ Missing Value ${missingValue} - ${matchedString}
           // console.log('nestedVars', nestedVars)
           const noNestedVars = nestedVars.length < 2
 
-          if (this.settings.allowUnknownFileRefs && variableString.match(fileRefSyntax)) {
-            // Encode the unknown file variable to pass through resolution
+          // Check if this unresolved variable type should pass through
+          const isFileRef = variableString.match(fileRefSyntax)
+          const isParamRef = variableString.match(getValueFromParam.match)
+
+          // Params pass through entirely (including fallbacks) for third-party resolution
+          if (isParamRef && this.isUnresolvedAllowed('param')) {
             return Promise.resolve(encodeUnknown(propertyString))
           }
 
-          if (this.settings.allowUnresolvedVariables) {
+          const isUnresolvedAllowed =
+            this.settings.allowUnresolvedVariables === true ||
+            (isFileRef && this.isUnresolvedAllowed('file'))
+
+          if (isUnresolvedAllowed) {
             // 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,
@@ -2880,7 +2942,6 @@ Missing Value ${missingValue} - ${matchedString}
                 return Promise.resolve(undefined)
               }
             }
-            // Encode unresolved variable to pass through resolution
             return Promise.resolve(encodeUnknown(propertyString))
           }
 
@@ -3046,7 +3107,7 @@ Missing Value ${missingValue} - ${matchedString}
       // console.log('nestedVar', nestedVar)
 
       if (nestedVar) {
-        if (!this.settings.allowUnknownVariables) {
+        if (!this.isUnknownTypeAllowed(nestedVar)) {
           verifyVariable(nestedVar, valueObject, this.variableTypes, this.config)
         }
         const fallbackStr = getFallbackString(split, nestedVar)
@@ -3148,8 +3209,8 @@ Missing Value ${missingValue} - ${matchedString}
 
 
 
-    /* Pass through unknown variables */
-    if (this.settings.allowUnknownVariables || allowSpecialCase) {
+    /* Pass through unknown variable types */
+    if (allowSpecialCase || this.isUnknownTypeAllowed(propertyString)) {
       // console.log('allowUnknownVars propertyString', propertyString)
       const varMatches = propertyString.match(this.variableSyntax)
       let allowUnknownVars = propertyString