configorama 0.9.17 → 0.10.0

package/README.md

@@ -22,6 +22,7 @@ Configorama extends your configuration with a powerful variable system that reso
 <details>
 <summary>Click to expand</summary>
 
+- [Key Features](#key-features)
 - [Getting Started](#getting-started)
   - [Installation](#installation)
   - [Quick Start](#quick-start)
@@ -30,13 +31,19 @@ Configorama extends your configuration with a powerful variable system that reso
   - [Resolution Flow](#resolution-flow)
   - [Analyzing Without Resolving](#analyzing-without-resolving)
   - [Getting Metadata](#getting-metadata)
+  - [Architecture](#architecture)
+  - [Performance](#performance)
 - [Variable Sources](#variable-sources)
+  - [Summary Table](#summary-table)
   - [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)
   - [Terraform HCL Support](#terraform-hcl-support)
   - [Git References](#git-references)
@@ -45,11 +52,18 @@ Configorama extends your configuration with a powerful variable system that reso
   - [If Expressions](#if-expressions)
   - [Filters (Experimental)](#filters-experimental)
   - [Functions (Experimental)](#functions-experimental)
+- [Bundled Plugins](#bundled-plugins)
+  - [CloudFormation](#cloudformation)
 - [API Reference](#api-reference)
   - [Async API](#async-api)
   - [Sync API](#sync-api)
   - [Analyze API](#analyze-api)
   - [Format Utilities](#format-utilities)
+  - [Markdown Files](#markdown-files)
+  - [`buildVariableSyntax(prefix, suffix, excludePatterns?)`](#buildvariablesyntaxprefix-suffix-excludepatterns)
+  - [`Configorama` Class](#configorama-class)
+  - [`configorama/parse-file` Subpath](#configoramaparse-file-subpath)
+  - [TypeScript Types](#typescript-types)
 - [Configuration Options](#configuration-options)
   - [Custom Variable Syntax](#custom-variable-syntax)
   - [allowUnknownVariableTypes](#allowunknownvariabletypes)
@@ -61,7 +75,7 @@ Configorama extends your configuration with a powerful variable system that reso
 - [CLI Usage](#cli-usage)
   - [Basic Commands](#basic-commands)
   - [Command Options](#command-options)
-  - [Examples](#cli-examples)
+  - [CLI Examples](#cli-examples)
 - [Testing](#testing)
   - [Running Tests](#running-tests)
   - [Test Structure](#test-structure)
@@ -79,9 +93,13 @@ Configorama extends your configuration with a powerful variable system that reso
   - [Multi-Stage Resolution](#multi-stage-resolution)
   - [Function Arguments and Context](#function-arguments-and-context)
   - [Programmatic Usage](#programmatic-usage)
-- [What's New](#whats-new)
+- [Comparison vs Serverless Framework Variables](#comparison-vs-serverless-framework-variables)
 - [Alternative Libraries](#alternative-libraries)
+- [Changelog](#changelog)
 - [Inspiration](#inspiration)
+- [License](#license)
+- [Contributing](#contributing)
+- [Support](#support)
 
 </details>
 <!-- end-doc-gen -->
@@ -297,6 +315,59 @@ console.log(result.resolutionHistory)         // Step-by-step resolution for eac
 }
 ```
 
+### Architecture
+
+```
+┌──────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
+│  Input           │───▶│  Configorama core   │───▶│  Output          │
+│                  │    │                     │    │                  │
+│  • Config file   │    │  parser registry    │    │  Resolved config │
+│  • JS/TS object  │    │  (yaml, json, toml, │    │  (+ metadata if  │
+│  • Inline opts   │    │   ini, hcl, md, …)  │    │   requested)     │
+└──────────────────┘    │                     │    └──────────────────┘
+                        │  preProcess()       │
+                        │  ↓                  │
+                        │  populateObject()   │◀───┐  iterates until
+                        │  ↓                  │    │  no variables
+                        │  resolve leaf vars  │────┘  remain
+                        │  ↓                  │
+                        │  apply filters/funcs│
+                        │  ↓                  │
+                        │  return             │
+                        └──────────┬──────────┘
+                                   │
+                                   ▼
+                ┌──────────────────────────────────────┐
+                │           Variable Sources           │
+                │ ┌────────┐ ┌────────┐ ┌────────────┐ │
+                │ │ env    │ │ opt    │ │ file/text  │ │
+                │ │ self   │ │ param  │ │ git/cron   │ │
+                │ │ eval   │ │ if     │ │ + plugins  │ │
+                │ └────────┘ └────────┘ └────────────┘ │
+                │                                      │
+                │  Bundled plugins:                    │
+                │  • plugins/cloudformation            │
+                │                                      │
+                │  Custom: variableSources: [{…}]      │
+                └──────────────────────────────────────┘
+```
+
+Resolution is a **fixed-point loop**: each pass resolves what it can, then `populateObject()` runs again until no `${…}` references remain. Built-in resolvers run first; custom resolvers from `variableSources` are tried in order.
+
+### Performance
+
+Configorama is fast and stays out of the way at runtime — a typical 21KB serverless-style config resolves in **~3ms** on warm Node 22.
+
+- Honest before/after benchmarks against the published `0.9.17` baseline: [`PERF.md`](./PERF.md)
+- Reproducible bench harness: [`scripts/bench.js`](./scripts/bench.js)
+- Run against your own configs:
+  ```bash
+  node scripts/bench.js  # local
+  node scripts/bench.js /path/to/another/configorama  # A/B
+  ```
+
+If your config is slow, please open an issue with the config (or a redacted reproduction) — we can profile and tighten the hot path.
+
 ---
 
 ## Variable Sources
@@ -953,7 +1024,7 @@ See [tests/hclTests](./tests/hclTests) for example Terraform files.
 Access repository information from the current working directory's git data.
 
 <!-- doc-gen CODE src=tests/gitVariables/gitVariables.yml -->
-```yaml
+```yml
 ########################
 # Git Variables
 ########################
@@ -1290,6 +1361,48 @@ inRange: ${between(${value}, 50, 100)}  # true
 
 ---
 
+## Bundled Plugins
+
+Plugins ship in the repo under `plugins/` and are opt-in — install their peer dependencies, then wire them into `variableSources`. Plugins are *not* required dependencies of `configorama` itself, so consumers who don't need them aren't paying for them.
+
+### CloudFormation
+
+Resolves CloudFormation stack output values. Single-region, multi-region, and multi-account.
+
+```yaml
+# Default region, default AWS credentials
+apiUrl: ${cf:my-stack.ApiUrl}
+
+# Explicit region
+westUrl: ${cf(us-west-2):west-stack.ApiUrl}
+
+# Cross-account: 'prod' matches PROD_AWS_ACCESS_KEY_ID env vars
+prodUrl: ${cf(prod:us-west-2):prod-stack.ApiUrl}
+```
+
+```javascript
+const configorama = require('configorama')
+const createCloudFormationResolver = require('configorama/plugins/cloudformation')
+
+const cfResolver = createCloudFormationResolver({
+  defaultRegion: 'us-east-1',
+})
+
+const config = await configorama('config.yml', {
+  variableSources: [cfResolver]
+})
+```
+
+Full docs: [`plugins/cloudformation/README.md`](./plugins/cloudformation/README.md) — covers the env-var-prefix alias convention, refcounted credential mutex for parallel-safe deploys, and the `skipResolution` mode for CI metadata extraction.
+
+Peer dependency (install separately):
+
+```bash
+npm install @aws-sdk/client-cloudformation @aws-sdk/credential-providers
+```
+
+---
+
 ## API Reference
 
 ### Async API
@@ -1477,8 +1590,8 @@ const { format } = require('configorama')
 // Parse YAML
 const yamlObj = format.yaml.parse('key: value')
 
-// Parse JSON5
-const jsonObj = format.json5.parse('{ key: "value", }')
+// Parse JSON (handles JSON5/JSONC too — comments, trailing commas)
+const jsonObj = format.json.parse('{ key: "value", }')
 
 // Parse TOML
 const tomlObj = format.toml.parse('key = "value"')
@@ -1490,11 +1603,133 @@ const iniObj = format.ini.parse('[section]\nkey=value')
 const hclObj = await format.hcl.parse('variable "example" { default = "value" }')
 ```
 
-**Parser methods:**
+**Available parsers:** `format.json`, `format.yaml`, `format.toml`, `format.ini`, `format.hcl`, `format.markdown`.
+
+Each has at minimum a `parse(content)` method; `dump(obj)` / `stringify(obj)` and cross-format converters (e.g. `format.yaml.toJson`, `format.toml.toYaml`) are available where the underlying format supports them. `format.markdown` is a frontmatter parser — see [Markdown Files](#markdown-files) below.
+
+**Real use cases for `format`:**
+
+- Parse a config file without resolving variables (just want the structure):
+  ```javascript
+  const { format } = require('configorama')
+  const fs = require('fs')
+  const raw = format.yaml.parse(fs.readFileSync('config.yml', 'utf8'))
+  // raw is the YAML structure with ${...} strings intact
+  ```
+- Use the same YAML/TOML/JSON5 parsers as configorama itself in your own tooling, so a file that loads in one place loads identically in the other.
+
+---
+
+### Markdown Files
+
+Markdown configs (`.md`, `.mdx`, `.markdown`, `.mdown`, `.mkdn`, `.mkd`) are parsed as YAML/TOML/JSON frontmatter + body. The frontmatter becomes top-level keys; the body is exposed as `_content` on the resolved config (or `_body` if the frontmatter used that key explicitly).
+
+```markdown
+---
+service: my-service
+stage: ${opt:stage, 'dev'}
+---
+
+# Service Docs
+This is the body content.
+```
+
+Resolves to:
+
+```javascript
+{
+  service: 'my-service',
+  stage: 'dev',
+  _content: '# Service Docs\nThis is the body content.'
+}
+```
+
+The body is detached during variable resolution (so `${…}` inside the body text is left alone) and re-attached afterward — only frontmatter keys get variable expansion.
+
+---
+
+### `buildVariableSyntax(prefix, suffix, excludePatterns?)`
+
+Helper for building a properly-escaped regex source string to pass to the `syntax` option. Handles regex-special characters in your delimiters without you having to escape them yourself.
+
+```javascript
+const { buildVariableSyntax } = require('configorama')
+
+// Use {{ ... }} instead of ${ ... }
+const syntax = buildVariableSyntax('{{', '}}')
+
+const config = await configorama('config.yml', { syntax })
+```
+
+**Parameters:**
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `prefix` | `string` | `'${'` | Opening delimiter |
+| `suffix` | `string` | `'}'` | Closing delimiter |
+| `excludePatterns` | `string[]` | `['AWS', 'stageVariables']` | Patterns to exclude via negative lookahead (so e.g. `${AWS::Region}` is left untouched by CloudFormation users) |
+
+---
+
+### `Configorama` Class
+
+For advanced use cases (long-lived instances, hooking into init/resolve lifecycle, accessing partial state) the underlying class is exported.
+
+```javascript
+const { Configorama } = require('configorama')
+
+const instance = new Configorama('config.yml', { options: { stage: 'dev' } })
+await instance.init({ stage: 'dev' })
+const resolved = await instance.populateObject(instance.config)
+const metadata = instance.collectVariableMetadata()
+```
+
+Most users should prefer the top-level `configorama()` / `.sync()` / `.analyze()` functions, which are thin wrappers around this class.
+
+---
+
+### `configorama/parse-file` Subpath
+
+For tools that want to parse a config file (auto-detecting format from extension or contents) without going through variable resolution:
 
-Each parser has:
-- `parse(content)` - Parse string to JavaScript object
-- `stringify(obj)` - Convert JavaScript object to format string (if supported)
+```javascript
+const { parseFile, parseFileContents } = require('configorama/parse-file')
+
+// Read from disk
+const raw = parseFile('./config.yml')
+// returns the parsed object with ${...} strings intact
+
+// Or parse already-loaded contents
+const fromString = parseFileContents({
+  contents: 'service: my-app\nstage: ${opt:stage}',
+  filePath: 'in-memory.yml'
+})
+```
+
+Both are synchronous. Useful for build tools that inspect or rewrite configs before handing them to configorama.
+
+---
+
+### TypeScript Types
+
+Type definitions are bundled (`index.d.ts`). TypeScript users get:
+
+- Generic typing on the resolved config: `configorama<MyConfig>('config.yml')` returns `Promise<MyConfig>`
+- Full typing on `ConfigoramaSettings` and `ConfigoramaResult`
+- Editor autocomplete on all options shown in the [Complete Options Reference](#complete-options-reference)
+
+```typescript
+import configorama, { ConfigoramaSettings } from 'configorama'
+
+interface MyConfig {
+  service: string
+  stage: string
+  database: { host: string; port: number }
+}
+
+const config = await configorama<MyConfig>('config.yml', { options: { stage: 'prod' } })
+// config.database.port is typed as number
+```
 
 ---
 
@@ -1583,9 +1818,11 @@ const config = await configorama(configFile, {
 
 **Use cases:**
 - Multi-stage resolution (local resolution, then cloud provider resolves remaining vars)
-- Serverless Framework integration (let framework resolve SSM, CloudFormation refs)
+- Serverless Framework integration (let the framework resolve SSM and other refs it owns)
 - Gradual migration (allow unknown types during transition period)
 
+> CloudFormation refs (`${cf:…}`, `${cf(region):…}`, `${cf(account:region):…}`) are now resolved natively by the bundled [`plugins/cloudformation/`](./plugins/cloudformation/README.md) plugin — no external resolver required.
+
 ---
 
 ### allowUnresolvedVariables
@@ -1654,10 +1891,17 @@ const config = await configorama(configFile, {
 | `allowUnknownVariableTypes` | `boolean \| string[]` | `false` | Allow unknown variable types to pass through |
 | `allowUnresolvedVariables` | `boolean \| string[]` | `false` | Allow known types that can't resolve to pass through |
 | `allowUndefinedValues` | `boolean` | `false` | Allow undefined as a valid end result |
-| `returnMetadata` | `boolean` | `false` | Return both config and metadata about variables |
+| `returnMetadata` | `boolean` | `false` | Return `{ config, metadata }` instead of just the resolved config |
+| `returnPreResolvedVariableDetails` | `boolean` | `false` | Return metadata about variables *without* resolving them (used by `analyze()`) |
+| `useDotEnvFiles` | `boolean` | `false` | Auto-load `.env`, `.env.{stage}`, etc. into `process.env` before resolution (via [env-stage-loader](https://www.npmjs.com/package/env-stage-loader)) |
+| `dotEnvSilent` | `boolean` | `true` (unless `--verbose`) | Suppress the env-stage-loader log lines when `useDotEnvFiles` is on |
+| `dotEnvDebug` | `boolean` | `false` | Enable env-stage-loader debug output |
+| `dynamicArgs` | `object \| Function` | `undefined` | Values passed into `.js`/`.ts` config files when they're imported as the root config |
 | `mergeKeys` | `string[]` | `[]` | Keys to merge in arrays of objects |
 | `filePathOverrides` | `Record<string, string>` | `{}` | Map of file paths to override (for testing/mocking) |
 
+> The config file itself can also set `useDotenv: true` (or `useDotEnv: true`) at the top level to trigger dotenv loading — useful if you want the behavior intrinsic to the config rather than the JS caller.
+
 **Legacy options (deprecated):**
 
 | Legacy Option | New Equivalent |
@@ -1776,8 +2020,8 @@ interface VariableSource {
 **Advanced example with AWS SSM:**
 
 ```javascript
-const AWS = require('aws-sdk')
-const ssm = new AWS.SSM()
+const { SSMClient, GetParameterCommand } = require('@aws-sdk/client-ssm')
+const ssm = new SSMClient({})
 
 const config = await configorama('config.yml', {
   variableSources: [{
@@ -1790,10 +2034,10 @@ const config = await configorama('config.yml', {
       const paramPath = variable.replace(/^ssm:/, '')
 
       try {
-        const result = await ssm.getParameter({
+        const result = await ssm.send(new GetParameterCommand({
           Name: paramPath,
           WithDecryption: true
-        }).promise()
+        }))
 
         return result.Parameter.Value
       } catch (err) {
@@ -1807,6 +2051,8 @@ const config = await configorama('config.yml', {
 })
 ```
 
+> **See also:** the bundled [`plugins/cloudformation/`](./plugins/cloudformation/README.md) plugin is a production-grade example of a `source: 'remote'` resolver — it handles multi-region, multi-account credential swapping, and per-instance client/output caching.
+
 ```yaml
 # config.yml
 database:
@@ -1959,6 +2205,22 @@ configorama config.yml --verify
 #   - DB_PASSWORD
 ```
 
+**Allow unknown variable types to pass through unresolved:**
+
+```bash
+# ${ssm:...} and ${custom:...} stay as literal ${ssm:...} strings
+# (typical for multi-stage pipelines where another tool resolves them)
+configorama config.yml --allow-unknown
+```
+
+**Allow undefined values in the final output:**
+
+```bash
+# Don't error on values that resolved to undefined — emit them as nulls
+# (useful for downstream tooling that does its own validation)
+configorama config.yml --allow-undefined
+```
+
 ---
 
 ## Testing
@@ -2087,7 +2349,7 @@ service: my-service
 
 provider:
   name: aws
-  runtime: nodejs18.x
+  runtime: nodejs22.x
   stage: ${opt:stage, 'dev'}
   region: ${opt:region, 'us-east-1'}
 
@@ -2134,7 +2396,7 @@ serverless deploy --stage prod --region us-west-2
 **Dockerfile:**
 
 ```dockerfile
-FROM node:18-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 
@@ -2212,12 +2474,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '22'
 
       - name: Install dependencies
         run: npm ci
@@ -2251,7 +2513,7 @@ stages:
 
 verify-config:
   stage: verify
-  image: node:18
+  image: node:22
   script:
     - npm ci
     - npx configorama config.yml --verify --stage $CI_ENVIRONMENT_NAME
@@ -2260,14 +2522,14 @@ verify-config:
 
 test:
   stage: test
-  image: node:18
+  image: node:22
   script:
     - npm ci
     - npm test
 
 deploy-production:
   stage: deploy
-  image: node:18
+  image: node:22
   script:
     - npm ci
     - npm run deploy
@@ -2520,14 +2782,14 @@ secrets: ${file(./fetch-secrets.js)}
 
 ```javascript
 // fetch-secrets.js
-const AWS = require('aws-sdk')
-const ssm = new AWS.SSM()
+const { SSMClient, GetParameterCommand } = require('@aws-sdk/client-ssm')
+const ssm = new SSMClient({})
 
 module.exports = async () => {
-  const result = await ssm.getParameter({
+  const result = await ssm.send(new GetParameterCommand({
     Name: '/myapp/api-key',
     WithDecryption: true
-  }).promise()
+  }))
 
   return result.Parameter.Value
 }
@@ -2594,13 +2856,15 @@ const partiallyResolved = await configorama('config.yml', {
   allowUnknownVariableTypes: ['ssm', 'cf']
 })
 
-// Stage 2: External system resolves SSM and CloudFormation refs
-// (e.g., Serverless Dashboard, AWS CloudFormation, etc.)
+// Stage 2: External system resolves SSM and any other refs
+// (e.g., Serverless Dashboard, secrets manager, etc.)
 const fullyResolved = await externalResolver(partiallyResolved)
 ```
 
 **Use case:** Serverless Framework + Serverless Dashboard workflow.
 
+> For CloudFormation refs specifically, the bundled [CF plugin](./plugins/cloudformation/README.md) resolves them natively in Stage 1 — you don't need a second pass.
+
 ---
 
 ### Function Arguments and Context
@@ -2660,14 +2924,14 @@ const config = await configorama('config.yml', {
     description: 'AWS Systems Manager Parameter Store',
     match: /^ssm:/,
     resolver: async (variable) => {
-      const AWS = require('aws-sdk')
-      const ssm = new AWS.SSM()
+      const { SSMClient, GetParameterCommand } = require('@aws-sdk/client-ssm')
+      const ssm = new SSMClient({})
 
       const paramName = variable.replace(/^ssm:/, '')
-      const result = await ssm.getParameter({
+      const result = await ssm.send(new GetParameterCommand({
         Name: paramName,
         WithDecryption: true
-      }).promise()
+      }))
 
       return result.Parameter.Value
     }
@@ -2734,68 +2998,47 @@ timeout: ${selectByEnv(30, 5, ${environment})}
 
 ---
 
-## What's New
-
-How is this different than the Serverless Framework variable system?
+## Comparison vs Serverless Framework Variables
+
+Configorama was forked from the Serverless Framework variable system and extended. Here's what's different:
+
+| Capability | Serverless | Configorama |
+|---|---|---|
+| Framework-agnostic — use outside Serverless | ❌ Serverless-only | ✅ Any tool, any framework |
+| Pluggable variable sources | ❌ Hardcoded | ✅ Custom resolvers, custom syntax |
+| `self:` prefix optional in self-refs | ❌ Required | ✅ `${foo.bar}` works without `self:` |
+| Numbers as defaults | ❌ Coerced to string | ✅ `${env:TIMEOUT, 30}` stays numeric |
+| Format support | YAML/JSON | YAML, JSON/JSON5/JSONC, TOML, INI, HCL, Markdown, TS, JS |
+| Filters (pipe transforms) | ❌ | ✅ `${value \| toUpperCase}` |
+| Built-in functions | ❌ | ✅ `merge()`, custom user functions |
+| Conditional expressions | ❌ | ✅ `${if(cond ? a : b)}` |
+| Eval/math expressions | ❌ | ✅ `${eval(2 + 2)}` |
+| TypeScript file refs | ❌ | ✅ `${file(./config.ts)}` |
+| Git data refs | ❌ | ✅ `${git:branch}`, `${git:sha1}`, etc. |
+| Cron expression refs | ❌ | ✅ `${cron(every monday at 9am)}` |
+| Metadata extraction (analyze without resolving) | ❌ | ✅ `configorama.analyze(...)` |
+| Multi-account CloudFormation refs | ❌ | ✅ via bundled CF plugin |
+| Circular dependency detection | ❌ Hangs | ✅ Helpful error |
 
-1. **Framework-agnostic** - Use with any tool, not just Serverless Framework
-
-2. **Pluggable** - Add custom variable syntax and sources easily
-
-3. **Filters** - Transform values before resolution:
-   ```yaml
-   key: ${opt:stage | toUpperCase}
-   ```
-
-4. **Cleaner self-references** - No need for `self:` prefix:
-   ```yaml
-   keyOne:
-     subKey: hi
-
-   # Before
-   key: ${self:keyOne.subKey}
-
-   # Now (both work)
-   key: ${keyOne.subKey}
-   key: ${self:keyOne.subKey}
-   ```
-
-5. **Numbers as defaults** - Numeric defaults fully supported:
-   ```yaml
-   timeout: ${env:TIMEOUT, 30}
-   port: ${opt:port, 3000}
-   ```
-
-6. **Multiple format support** - TOML, YML, JSON, INI, HCL, etc.
-
-7. **Built-in functions** - Combine and transform values:
-   ```yaml
-   merged: ${merge(${obj1}, ${obj2})}
-   ```
+---
 
-8. **TypeScript support** - Execute TypeScript files directly:
-   ```yaml
-   config: ${file(./config.ts)}
-   ```
+## Alternative Libraries
 
-9. **Conditional expressions** - If/else logic in configs:
-   ```yaml
-   memory: ${if(${stage} === 'prod' ? 1024 : 512)}
-   ```
+How configorama compares to other variable-substitution libraries:
 
-10. **Metadata extraction** - Analyze configs without resolving:
-    ```javascript
-    const meta = await configorama.analyze('config.yml')
-    ```
+| Library | Formats | Variable sources | Custom resolvers | Async | TypeScript |
+|---|---|---|---|---|---|
+| **configorama** | YAML, JSON5, TOML, INI, HCL, MD, TS, JS | env, opt, file, self, git, cron, eval, if, custom | ✅ | ✅ | ✅ |
+| [sls-yaml](https://github.com/01alchemist/sls-yaml) | YAML | env, opt, file, self | ❌ | ❌ | ❌ |
+| [yaml-boost](https://github.com/blackflux/yaml-boost) | YAML | env, file, self, function | partial | ❌ | ❌ |
+| [serverless-merge-config](https://github.com/CruGlobal/serverless-merge-config) | YAML | merge-focused | ❌ | ❌ | ❌ |
+| [serverless-terraform-variables](https://www.npmjs.com/package/serverless-terraform-variables) | YAML + .tfvars | terraform-focused | ❌ | ❌ | ❌ |
 
 ---
 
-## Alternative Libraries
+## Changelog
 
-- [sls-yaml](https://github.com/01alchemist/sls-yaml) - YAML with variable support
-- [yaml-boost](https://github.com/blackflux/yaml-boost) - YAML preprocessing
-- [serverless-merge-config](https://github.com/CruGlobal/serverless-merge-config) - Merge Serverless configs
-- [serverless-terraform-variables](https://www.npmjs.com/package/serverless-terraform-variables) - Terraform variable support
+Version history lives in [CHANGELOG.md](./CHANGELOG.md). It covers everything from 0.9.9 onward; older releases are in `git log`.
 
 ---
 
@@ -2803,10 +3046,13 @@ How is this different than the Serverless Framework variable system?
 
 This is forked from the [Serverless Framework](https://github.com/serverless/serverless/) variable system.
 
-**Mad props to:**
+<details>
+<summary><strong>Mad props to the original contributors</strong></summary>
 
 [erikerikson](https://github.com/erikerikson), [eahefnawy](https://github.com/eahefnawy), [HyperBrain](https://github.com/HyperBrain), [ac360](https://github.com/ac360), [gcphost](https://github.com/gcphost), [pmuens](https://github.com/pmuens), [horike37](https://github.com/horike37), [lorengordon](https://github.com/lorengordon), [AndrewFarley](https://github.com/AndrewFarley), [tobyhede](https://github.com/tobyhede), [johncmckim](https://github.com/johncmckim), [mangas](https://github.com/mangas), [e-e-e](https://github.com/e-e-e), [BasileTrujillo](https://github.com/BasileTrujillo), [miltador](https://github.com/miltador), [sammarks](https://github.com/sammarks), [RafalWilinski](https://github.com/RafalWilinski), [indieisaconcept](https://github.com/indieisaconcept), [svdgraaf](https://github.com/svdgraaf), [infiniteluke](https://github.com/infiniteluke), [j0k3r](https://github.com/j0k3r), [craigw](https://github.com/craigw), [bsdkurt](https://github.com/bsdkurt), [aoskotsky-amplify](https://github.com/aoskotsky-amplify), and all the other folks who contributed to the variable system.
 
+</details>
+
 **Additionally these tools were very helpful:**
 
 - [yaml-boost](https://github.com/blackflux/yaml-boost)
@@ -2821,11 +3067,10 @@ MIT © [David Wells](https://davidwells.io)
 
 ## Contributing
 
-Contributions welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.
+Bug reports and reproductions are very welcome — please open an [issue](https://github.com/DavidWells/configorama/issues) with a minimal failing config. PRs are reviewed case-by-case; small targeted fixes with a test case are most likely to land quickly.
 
 ## Support
 
 - 🐛 [Report bugs](https://github.com/DavidWells/configorama/issues)
 - 💡 [Request features](https://github.com/DavidWells/configorama/issues)
 - 📖 [Read the docs](https://github.com/DavidWells/configorama#readme)
-- 💬 [Join discussions](https://github.com/DavidWells/configorama/discussions)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "0.9.17",
+  "version": "0.10.0",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -71,16 +71,19 @@
   "devDependencies": {
     "@cdktf/hcl2json": "^0.21.0",
     "@types/node": "^24.10.1",
-    "markdown-magic": "^3.4.0",
+    "markdown-magic": "^4.8.0",
     "tsx": "^4.7.0",
     "typescript": "^5.8.3",
     "uvu": "^0.5.6",
     "watchlist": "^0.3.1"
   },
+  "overrides": {
+    "lodash": "^4.18.1"
+  },
   "peerDependencies": {
     "@cdktf/hcl2json": ">=0.20.0",
-    "tsx": ">=4.0.0",
-    "ts-node": ">=10.0.0"
+    "ts-node": ">=10.0.0",
+    "tsx": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@cdktf/hcl2json": {

package/src/main.js

@@ -8,7 +8,37 @@ console.log = () => {}
 /** */
 /* External dependencies */
 const findUp = require('find-up')
-const traverse = require('traverse')
+/**
+ * Pre-order DFS walk that mimics the subset of `traverse(obj).forEach(fn)`
+ * we actually use: only `this.path` and `this.update(v)`. ~2x faster than
+ * the `traverse` package because it avoids the per-node State object alloc.
+ *
+ * @param {*} root
+ * @param {Function} callback - called with `this = {path, update}` per node
+ */
+function walkAndUpdate(root, callback) {
+  function visit(value, path, parent, key) {
+    const ctx = {
+      path,
+      update(newValue) { if (parent !== null) parent[key] = newValue }
+    }
+    callback.call(ctx, value)
+    // Re-read in case callback mutated the slot
+    const current = parent === null ? root : parent[key]
+    if (current !== null && typeof current === 'object') {
+      // Use Object.keys for both arrays and objects so sparse-array holes are
+      // skipped, matching the `traverse` package's behavior.
+      const keys = Object.keys(current)
+      const isArr = Array.isArray(current)
+      for (let i = 0; i < keys.length; i++) {
+        const k = keys[i]
+        const idx = isArr ? Number(k) : k
+        visit(current[k], path.concat(idx), current, k)
+      }
+    }
+  }
+  visit(root, [], null, null)
+}
 const dotProp = require('dot-prop')
 /* Utils - root */
 const {
@@ -158,6 +188,22 @@ class Configorama {
     this.filterCache = {}
     // Cache for originalValue lookups (perf: avoid repeated dotProp.get)
     this._originalValueCache = new Map()
+    // Paths whose current value is a literal with no variables — skip rebuilding
+    // their leaf object on every subsequent populateObjectImpl iteration.
+    this._resolvedPaths = new Set()
+    // Cache raw file contents per absolute path so repeated ${file:...} refs
+    // to the same file (e.g., merged twice into different keys) don't reread.
+    this._fileContentCache = new Map()
+
+    // rawOriginalConfig (a pre-preProcess snapshot) is only consumed by metadata
+    // display paths. Skipping the cloneDeep when none of those paths are active
+    // saves ~10-15ms per init.
+    const showFound = this.settings.dynamicArgs && (this.settings.dynamicArgs.list || this.settings.dynamicArgs.info)
+    this._needsRawClone = !!(
+      this.settings.returnMetadata ||
+      this.settings.returnPreResolvedVariableDetails ||
+      VERBOSE || SETUP_MODE || showFound
+    )
 
     this.foundVariables = []
     this.fileRefsFound = []
@@ -188,6 +234,10 @@ class Configorama {
     }
     const variableSyntax = varRegex
     this.variableSyntax = variableSyntax
+    // Non-global twin for cheap boolean checks: `.test()` on a global regex
+    // would advance lastIndex between calls, and `.match()` on a global regex
+    // allocates an array of every match. Use this whenever we only need truthy.
+    this.variableSyntaxTest = new RegExp(variableSyntax.source, variableSyntax.flags.replace('g', ''))
 
     // Extract variable prefix/suffix from syntax regex for reconstructing variables
     const syntaxWrapper = extractVariableWrapper(variableSyntax.source)
@@ -200,8 +250,10 @@ class Configorama {
 
     // Set initial config object to populate
     if (typeof fileOrObject === 'object') {
-      // Store truly raw config before any preprocessing
-      this.rawOriginalConfig = cloneDeep(fileOrObject)
+      // Store truly raw config before any preprocessing (only when needed)
+      if (this._needsRawClone) {
+        this.rawOriginalConfig = cloneDeep(fileOrObject)
+      }
       // Preprocess: convert bare refs in if(), escape help() args
       // Skip fallback fixing for object configs (they handle bare refs differently)
       const processed = preProcess(fileOrObject, this.variableSyntax, this.variableTypes, { skipFallbackFix: true })
@@ -677,8 +729,10 @@ class Configorama {
       /*
       console.log('before preprocess', configObject)
       /** */
-      // Store truly raw config before any preprocessing (for metadata display)
-      this.rawOriginalConfig = cloneDeep(configObject)
+      // Store truly raw config before any preprocessing (only when needed)
+      if (this._needsRawClone) {
+        this.rawOriginalConfig = cloneDeep(configObject)
+      }
 
       /* Preprocess step here - escapes ${} in help() args, fixes malformed fallbacks */
       configObject = preProcess(configObject, this.variableSyntax, this.variableTypes)
@@ -816,7 +870,7 @@ class Configorama {
     const originalConfig = this.originalConfig
 
     /* If no variables found just return early */
-    if (this.originalString && !this.originalString.match(this.variableSyntax)) {
+    if (this.originalString && !this.variableSyntaxTest.test(this.originalString)) {
       if (this._markdownContent !== undefined) {
         this.originalConfig[this._markdownContentKey] = this._markdownContent
       }
@@ -829,7 +883,7 @@ class Configorama {
       /* has hardcoded stage */
       if (
         this.originalConfig && this.originalConfig.provider && 
-        this.originalConfig.provider.stage && !this.originalConfig.provider.stage.match(this.variableSyntax)
+        this.originalConfig.provider.stage && !this.variableSyntaxTest.test(this.originalConfig.provider.stage)
       ) {
         providerStage = this.originalConfig.provider.stage
       }
@@ -859,7 +913,7 @@ class Configorama {
             // console.log('leaves two', leaves)
             // Traverse resolved object and run functions
             // console.log('this.config', this.config)
-            traverse(this.config).forEach(function (rawValue) {
+            walkAndUpdate(this.config, function (rawValue) {
               /* Pass through unknown variables */
               if (!configoramaOpts.allowUndefinedValues && typeof rawValue === 'undefined') {
                 const configValuePath = this.path.join('.')
@@ -1096,12 +1150,16 @@ class Configorama {
         mapValues(current, addContext)
       }
     } else {
+      // Compute path once, then skip work for paths already known to be fully resolved.
+      const thePath = context.length > 1 ? context.join('.') : context[0]
+      if (this._resolvedPaths.has(thePath)) {
+        return results
+      }
       // TODO Add values to leaves here
       const leaf = {
         path: context,
         value: current,
       }
-      const thePath = leaf.path.length > 1 ? leaf.path.join('.') : leaf.path[0]
       // console.log('thePath', thePath)
       // console.log('this.originalConfig', this.originalConfig)
 
@@ -1113,21 +1171,39 @@ class Configorama {
         originalValue = cached.value
         originalValuePath = cached.originalValuePath
       } else {
-        originalValue = dotProp.get(this.originalConfig, thePath)
-        // TODO @DWELLS make recursive
+        // Walk down originalConfig once using the path array directly. Avoids
+        // dotProp.get's path-segmenting work and the previous O(depth²) loop
+        // that re-joined and re-walked parent paths.
+        const ancestorValues = []
+        let node = this.originalConfig
+        let fullPathReached = true
+        for (let i = 0; i < context.length; i++) {
+          if (node == null || typeof node !== 'object') {
+            fullPathReached = false
+            break
+          }
+          node = node[context[i]]
+          ancestorValues.push(node)
+        }
+
+        const lastIdx = ancestorValues.length - 1
+        originalValue = fullPathReached ? ancestorValues[lastIdx] : undefined
+
         if (!originalValue) {
-          // Recurse up the tree until we find a value
-          // Use index instead of slice() to avoid array allocations
-          for (let pathLen = leaf.path.length - 1; pathLen > 0 && !originalValue; pathLen--) {
-            const currentPath = leaf.path.slice(0, pathLen).join('.')
-            // console.log('checking parent path:', currentPath)
-            originalValue = dotProp.get(this.originalConfig, currentPath)
-            if (typeof originalValue !== 'undefined') {
-              originalValuePath = currentPath
+          // Same semantics as the previous "recurse up" loop: walk from the
+          // deepest non-full ancestor toward the root, take the first truthy
+          // ancestor as originalValue, and update originalValuePath each time
+          // we see a defined ancestor along the way.
+          const startIdx = fullPathReached ? lastIdx - 1 : lastIdx
+          for (let i = startIdx; i >= 0; i--) {
+            const ancestor = ancestorValues[i]
+            if (typeof ancestor !== 'undefined') {
+              originalValuePath = i > 0 ? context.slice(0, i + 1).join('.') : context[0]
+              originalValue = ancestor
+              if (ancestor) break
             }
           }
         }
-        // Cache the result
         this._originalValueCache.set(thePath, { value: originalValue, originalValuePath })
       }
       if (originalValuePath) {
@@ -1150,6 +1226,9 @@ class Configorama {
           leaf.isFileRef = true
         }
       }
+      // Pre-compute hasVar so populateVariables doesn't have to re-test every leaf
+      // every iteration. Non-string values can never contain a variable.
+      leaf.hasVar = isString(current) && this.variableSyntaxTest.test(current)
       // dotProp.get(this.originalConfig, thePath)
       results.push(leaf)
     }
@@ -1167,9 +1246,18 @@ class Configorama {
    */
   populateVariables(properties) {
     // console.log('properties', properties)
+    // hasVar was precomputed in getProperties — no need to re-test the regex here.
+    // Properties whose value is defined and lacks a variable are terminally
+    // resolved: record their path so getProperties can skip them on the next
+    // iteration. Undefined-valued leaves stay eligible — the final
+    // undefined-detection traverse still needs to find them in this.leaves.
     let variables = properties.filter((property) => {
-      // Initial check if value has variable string in it
-      return isString(property.value) && property.value.match(this.variableSyntax)
+      if (property.hasVar) return true
+      if (property.value !== undefined) {
+        const p = property.path
+        this._resolvedPaths.add(p.length > 1 ? p.join('.') : p[0])
+      }
+      return false
     })
     /*
     console.log(`variables at call count ${this.callCount}`, variables)
@@ -1205,6 +1293,15 @@ class Configorama {
         if (result.value !== result.populated) {
           set(target, result.path, result.populated)
         }
+        // If the populated value is defined and no longer contains a variable,
+        // mark this path resolved so getProperties skips it on subsequent
+        // iterations. Undefined means resolution failed — keep it eligible so
+        // the final undefined-detection traverse still has a leaf to reference.
+        const populated = result.populated
+        if (populated !== undefined && (typeof populated !== 'string' || !this.variableSyntaxTest.test(populated))) {
+          const p = result.path
+          this._resolvedPaths.add(p.length > 1 ? p.join('.') : p[0])
+        }
       })
     })
   }
@@ -1354,7 +1451,7 @@ class Configorama {
         historyEntry.fallbackValues = variableParts.slice(1).map((fallback) => {
           const trimmedFallback = fallback.trim()
           // Check if it's a variable reference
-          const isVariable = trimmedFallback.match(this.variableSyntax) || trimmedFallback.match(this.variablesKnownTypes)
+          const isVariable = this.variableSyntaxTest.test(trimmedFallback) || this.variablesKnownTypes.test(trimmedFallback)
           const fallbackData = {
             isVariable: !!isVariable,
             fullMatch: trimmedFallback,
@@ -1592,7 +1689,7 @@ class Configorama {
       }
 
       /* Handle ${self:custom.ref, ''} with deep values */
-      if (v.match(deepRefSyntax) && originalSrc.match(this.variableSyntax) && !v.match(/deep\:(\d*)\..*}$/)) {
+      if (v.match(deepRefSyntax) && this.variableSyntaxTest.test(originalSrc) && !v.match(/deep\:(\d*)\..*}$/)) {
         // console.log('deep ref syntax')
         // console.log('deep var', this.deep)
         // console.log('originalSrc', originalSrc)
@@ -1642,8 +1739,8 @@ class Configorama {
       /** */
       // Handle comma ${opt:stage, dev} and remove extra suffix
       if (
-        currentMatchedString.match(this.variableSyntax) &&
-        !valueToPopulate.match(this.variableSyntax) &&
+        this.variableSyntaxTest.test(currentMatchedString) &&
+        !this.variableSyntaxTest.test(valueToPopulate) &&
         valueToPopulate.match(this.varSuffixPattern)
       ) {
         valueToPopulate = valueToPopulate.replace(this.varSuffixPattern, '')
@@ -1651,7 +1748,7 @@ class Configorama {
 
       // For eval/if expressions, string values need quotes unless already quoted
       // BUT don't quote strings that contain variable refs (they need further resolution)
-      if (evalIfPattern.test(property) && !valueToPopulate.match(this.variableSyntax)) {
+      if (evalIfPattern.test(property) && !this.variableSyntaxTest.test(valueToPopulate)) {
         const matchIdx = property.indexOf(currentMatchedString)
         const charBefore = matchIdx > 0 ? property[matchIdx - 1] : ''
         // Always escape quotes in values for eval/if context
@@ -1689,8 +1786,8 @@ class Configorama {
         const isNestedInVariable = (
           property.trim() !== matchedString.trim() &&
           property.indexOf(matchedString) !== -1 &&
-          matchedString.match(this.variableSyntax) &&
-          property.match(this.variableSyntax)
+          this.variableSyntaxTest.test(matchedString) &&
+          this.variableSyntaxTest.test(property)
         )
         // Only encode for file() or text() references where JSON braces break regex matching
         const isFileOrTextRef = /\bfile\s*\(|\btext\s*\(/.test(property)
@@ -1861,7 +1958,7 @@ Missing Value ${missingValue} - ${matchedString}
 
       if (
         /* Not another variable reference */
-        !prop.match(this.variableSyntax)
+        !this.variableSyntaxTest.test(prop)
         &&
         /* Not file or text refs */
         !prop.match(fileRefSyntax)
@@ -1898,7 +1995,7 @@ Missing Value ${missingValue} - ${matchedString}
       typeof valueToPopulate === 'string' &&
       !valueToPopulate.match(deepRefSyntax) &&
       foundFilters.length &&
-      !property.match(this.variableSyntax)
+      !this.variableSyntaxTest.test(property)
     ) {
       runFilters = true
     }
@@ -1977,7 +2074,7 @@ Missing Value ${missingValue} - ${matchedString}
       const secondValue = variableStrings[1]
       if (
         isString(firstValue) && firstValue.match(this.variablesKnownTypes) 
-        && isString(secondValue) && !secondValue.match(this.variablesKnownTypes) && !secondValue.match(this.variableSyntax)
+        && isString(secondValue) && !secondValue.match(this.variablesKnownTypes) && !this.variableSyntaxTest.test(secondValue)
       ) {
         if (!isSurroundedByQuotes(secondValue) && !/^-?\d+(\.\d+)?$/.test(secondValue) && !startsWithQuotedPipe(secondValue)) {
           variableStrings = [firstValue, ensureQuote(secondValue)]
@@ -2009,7 +2106,7 @@ Missing Value ${missingValue} - ${matchedString}
 
       extractedValues.forEach((value, index) => {
         // console.log('───────────────────────────────> value', value)
-        if (isString(value) && value.match(this.variableSyntax)) {
+        if (isString(value) && this.variableSyntaxTest.test(value)) {
           deepProperties += 1
           // console.log('makeDeepVariable overwrite', value)
           const deepVariable = this.makeDeepVariable(value, 'via overwrite')
@@ -2630,7 +2727,8 @@ Missing Value ${missingValue} - ${matchedString}
       fileRefSyntax: fileRefSyntax,
       textRefSyntax: textRefSyntax,
       varPrefix: this.varPrefix,
-      varSuffix: this.varSuffix
+      varSuffix: this.varSuffix,
+      fileContentCache: this._fileContentCache
     }
     return getValueFromFileResolver(ctx, variableString, options)
   }
@@ -2654,7 +2752,7 @@ Missing Value ${missingValue} - ${matchedString}
       // if there is a deep reference remaining
       ret = ret.then((result) => {
         // console.log('DEEP RESULT', result)
-        if (isString(result.value) && result.value.match(this.variableSyntax)) {
+        if (isString(result.value) && this.variableSyntaxTest.test(result.value)) {
           // console.log('makeDeepVariable getValueFromDeep', result.value)
           const deepVariable = this.makeDeepVariable(result.value, 'via getValueFromDeep')
           return Promise.resolve(appendDeepVariable(deepVariable, deepRef))
@@ -2759,7 +2857,7 @@ Missing Value ${missingValue} - ${matchedString}
 
           reducedValue = reducedValue[subProperty]
         }
-        if (typeof reducedValue === 'string' && reducedValue.match(this.variableSyntax)) {
+        if (typeof reducedValue === 'string' && this.variableSyntaxTest.test(reducedValue)) {
           // console.log('makeDeepVariable reducedValue', reducedValue)
           reducedValue = this.makeDeepVariable(reducedValue, 'via getDeeperValue')
         }

package/src/resolvers/valueFromFile.js

@@ -108,6 +108,7 @@ function parseFileContents(content, filePath) {
  * @param {RegExp} ctx.textRefSyntax - Regex for text() syntax
  * @param {string} ctx.varPrefix - Variable prefix (e.g., '${')
  * @param {string} ctx.varSuffix - Variable suffix (e.g., '}')
+ * @param {Map<string, string>} [ctx.fileContentCache] - Optional per-instance read cache keyed by absolute file path
  * @param {string} variableString - The variable string to resolve
  * @param {object} options - Resolution options
  * @returns {Promise<any>}
@@ -254,7 +255,14 @@ ${JSON.stringify(options.context, null, 2)}`,
 
   let valueToPopulate
 
-  const variableFileContents = fs.readFileSync(fullFilePath, 'utf-8')
+  // Per-instance read cache: identical ${file:...} refs hit fs once per resolve.
+  let variableFileContents
+  if (ctx.fileContentCache && ctx.fileContentCache.has(fullFilePath)) {
+    variableFileContents = ctx.fileContentCache.get(fullFilePath)
+  } else {
+    variableFileContents = fs.readFileSync(fullFilePath, 'utf-8')
+    if (ctx.fileContentCache) ctx.fileContentCache.set(fullFilePath, variableFileContents)
+  }
 
   /* handle case for referencing raw JS files to inline them */
   if ((argsToPass.length

package/src/utils/parsing/preProcess.js

@@ -233,12 +233,8 @@ function preProcess(configObject, variableSyntax, variableTypes, options = {}) {
                 const afterOp = afterRef.substring(op.length).trimStart()
                 return afterOp.startsWith('"') || afterOp.startsWith("'")
               }
-              // Check if preceded by: "string" op
-              for (const o of comparisonOps) {
-                const pattern = new RegExp(`["'][^"']*["']\\s*${o.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`)
-                if (pattern.test(beforeRef)) return true
-              }
-              return false
+              // Check if preceded by: "string" op (reuses precededByPatterns)
+              return precededByPatterns.some(p => p.test(beforeRef))
             })
 
             if (!precededByQuote && !followedByQuote && isComparedToString) {

package/types/src/main.d.ts

@@ -4,11 +4,15 @@ declare class Configorama {
     settings: any;
     filterCache: {};
     _originalValueCache: Map<any, any>;
+    _resolvedPaths: Set<any>;
+    _fileContentCache: Map<any, any>;
+    _needsRawClone: boolean;
     foundVariables: any[];
     fileRefsFound: any[];
     resolutionTracking: {};
     _trackCalls: boolean;
     variableSyntax: RegExp;
+    variableSyntaxTest: RegExp;
     varPrefix: string;
     varSuffix: string;
     varPrefixPattern: RegExp;

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

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.js"],"names":[],"mappings":";AA2GA;IACE,0CAieC;IAzdC,cAkBW;IAuBX,gBAAqB;IAErB,mCAAoC;IAEpC,sBAAwB;IACxB,qBAAuB;IAGvB,uBAA4B;IAE5B,qBAAmD;IAsBnD,uBAAoC;IAIpC,kBAAqC;IACrC,kBAAqC;IAErC,yBAA+F;IAC/F,yBAAuD;IACvD,kCAAyE;IAKvE,uBAAgD;IAKhD,YAAuB;IAEvB,oBAA0C;IAE1C,gBAAoD;IAOpD,uBAAkC;IAElC,uBAA8B;IAE9B,uBAAkC;IASpC,wBAAmC;IAGnC,mBAqHC;IAwED,4BAA8C;IAG9C,iCAAkC;IAalC,aA2EC;IAUD,oBAEC;IAGD,eAiDC;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,CA2BnB;IAKD;;;;;OAKG;IACH,oBAFa,OAAO,CAAC,GAAG,CAAC,CA6UxB;IA1UC,aAA4B;IAc1B,2BAA4B;IAmB1B,sBAA0C;IAC1C,4BAAkC;IA0SxC;;;OAGG;IACH,2BAFa,MAAM,CAsBlB;IAdC,qBAWE;IAIJ;;;;OAIG;IACH,uCAFa,OAAO,CAAC,GAAG,CAAC,CAIxB;IACD,+CAsBC;IAKD;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;OAWG;IACH,mFAHa;;;;cAZC,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAWD,CA6E9B;IACD;;;OAGG;IACH;;;;;OAKG;IACH,oCAHa,OAAO,CAAC;;;;cAjGP,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAgGgB,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,CAiLb;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,CAsa9J;IAID;;;;;;;;OAQG;IACH,qEAHa,OAAO,CAAC,GAAG,CAAC,CAoExB;IAKD;;;;;;;OAOG;IACH,0FAFa,OAAO,CAAC,GAAG,CAAC,CAgiBxB;IACD,+EA+BC;IACD,yDAiBC;IACD,oEA6BC;IAKD,8CAQC;IACD,kDAyBC;IACD;;;;;;;;;;;;;OAaG;IACH,wEAoDC;IAKD,4BAOC;IACD,sCAqEC;CACF"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/main.js"],"names":[],"mappings":";AAyIA;IACE,0CAufC;IA/eC,cAkBW;IAuBX,gBAAqB;IAErB,mCAAoC;IAGpC,yBAA+B;IAG/B,iCAAkC;IAMlC,wBAIC;IAED,sBAAwB;IACxB,qBAAuB;IAGvB,uBAA4B;IAE5B,qBAAmD;IAsBnD,uBAAoC;IAIpC,2BAAkG;IAIlG,kBAAqC;IACrC,kBAAqC;IAErC,yBAA+F;IAC/F,yBAAuD;IACvD,kCAAyE;IAMrE,uBAAgD;IAMlD,YAAuB;IAEvB,oBAA0C;IAE1C,gBAAoD;IAOpD,uBAAkC;IAElC,uBAA8B;IAE9B,uBAAkC;IASpC,wBAAmC;IAGnC,mBAqHC;IAwED,4BAA8C;IAG9C,iCAAkC;IAalC,aA2EC;IAUD,oBAEC;IAGD,eAiDC;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,CA2BnB;IAKD;;;;;OAKG;IACH,oBAFa,OAAO,CAAC,GAAG,CAAC,CA+UxB;IA5UC,aAA4B;IAc1B,2BAA4B;IAqB1B,sBAA0C;IAC1C,4BAAkC;IA0SxC;;;OAGG;IACH,2BAFa,MAAM,CAsBlB;IAdC,qBAWE;IAIJ;;;;OAIG;IACH,uCAFa,OAAO,CAAC,GAAG,CAAC,CAIxB;IACD,+CAsBC;IAKD;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;;;;OAWG;IACH,mFAHa;;;;cAZC,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAWD,CAsG9B;IACD;;;OAGG;IACH;;;;;OAKG;IACH,oCAHa,OAAO,CAAC;;;;cA1HP,QAAQ;;;;eACR,IAAI,GAAC,MAAM,SAAO;OAyHgB,CAAC,EAAE,CAsClD;IACD;;;;;OAKG;IACH,iDAFa,OAAO,CAAC,IAAI,CAAC,CAoBzB;IAID;;;;;OAKG;IACH;;;;OAIG;IACH,2BAFa,eAAc;;;;;;;;;;OAAa,CAavC;IACD;;;;;OAKG;IACH,yBAHW;;;;;;;;;;OAAa,gCACX,cAAS,CAOrB;IACD;;;;;;OAMG;IACH,6DAFa,GAAC,CAiLb;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,CAsa9J;IAID;;;;;;;;OAQG;IACH,qEAHa,OAAO,CAAC,GAAG,CAAC,CAoExB;IAKD;;;;;;;OAOG;IACH,0FAFa,OAAO,CAAC,GAAG,CAAC,CAgiBxB;IACD,+EA+BC;IACD,yDAkBC;IACD,oEA6BC;IAKD,8CAQC;IACD,kDAyBC;IACD;;;;;;;;;;;;;OAaG;IACH,wEAoDC;IAKD,4BAOC;IACD,sCAqEC;CACF"}

package/types/src/resolvers/valueFromFile.d.ts

@@ -14,6 +14,7 @@
  * @param {RegExp} ctx.textRefSyntax - Regex for text() syntax
  * @param {string} ctx.varPrefix - Variable prefix (e.g., '${')
  * @param {string} ctx.varSuffix - Variable suffix (e.g., '}')
+ * @param {Map<string, string>} [ctx.fileContentCache] - Optional per-instance read cache keyed by absolute file path
  * @param {string} variableString - The variable string to resolve
  * @param {object} options - Resolution options
  * @returns {Promise<any>}
@@ -32,6 +33,7 @@ export function getValueFromFile(ctx: {
     textRefSyntax: RegExp;
     varPrefix: string;
     varSuffix: string;
+    fileContentCache?: Map<string, string>;
 }, variableString: string, options: object): Promise<any>;
 /**
  * Parse file contents based on file extension

package/types/src/resolvers/valueFromFile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"valueFromFile.d.ts","sourceRoot":"","sources":["../../../src/resolvers/valueFromFile.js"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sCAjBG;IAAoB,UAAU,EAAtB,MAAM;IACK,aAAa;IACZ,cAAc,EAA1B,MAAM;IACM,mBAAmB,EAA/B,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,IAAI,EAAhB,MAAM;IACM,cAAc,EAA1B,MAAM;IACM,MAAM,EAAlB,MAAM;IACQ,cAAc;IAChB,aAAa,EAAzB,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,SAAS,EAArB,MAAM;IACM,SAAS,EAArB,MAAM;CACd,kBAAQ,MAAM,WACN,MAAM,GACJ,OAAO,CAAC,GAAG,CAAC,CAwVxB;AApYD;;;;;GAKG;AACH,2CAJW,MAAM,YACN,MAAM,GACJ,GAAC,CAoBb;AA8WD;;;;;;GAMG;AACH,qDAJW,MAAM,qBACN,MAAM,GACJ;IAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,GAAC,IAAI,CAAA;CAAE,CAkBhE;AAED;;;;;;GAMG;AACH,sDALW,MAAM,qBACN,MAAM,yBACN,OAAO,GACL,MAAM,EAAE,CAcpB"}
+{"version":3,"file":"valueFromFile.d.ts","sourceRoot":"","sources":["../../../src/resolvers/valueFromFile.js"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCAlBG;IAAoB,UAAU,EAAtB,MAAM;IACK,aAAa;IACZ,cAAc,EAA1B,MAAM;IACM,mBAAmB,EAA/B,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,IAAI,EAAhB,MAAM;IACM,cAAc,EAA1B,MAAM;IACM,MAAM,EAAlB,MAAM;IACQ,cAAc;IAChB,aAAa,EAAzB,MAAM;IACM,aAAa,EAAzB,MAAM;IACM,SAAS,EAArB,MAAM;IACM,SAAS,EAArB,MAAM;IACoB,gBAAgB,GAA1C,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B,kBAAQ,MAAM,WACN,MAAM,GACJ,OAAO,CAAC,GAAG,CAAC,CA+VxB;AA5YD;;;;;GAKG;AACH,2CAJW,MAAM,YACN,MAAM,GACJ,GAAC,CAoBb;AAsXD;;;;;;GAMG;AACH,qDAJW,MAAM,qBACN,MAAM,GACJ;IAAE,aAAa,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,GAAC,IAAI,CAAA;CAAE,CAkBhE;AAED;;;;;;GAMG;AACH,sDALW,MAAM,qBACN,MAAM,yBACN,OAAO,GACL,MAAM,EAAE,CAcpB"}

package/types/src/utils/parsing/preProcess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preProcess.d.ts","sourceRoot":"","sources":["../../../../src/utils/parsing/preProcess.js"],"names":[],"mappings":";AASA;;;;;;;;GAQG;AACH,+DANW,MAAM,mCAGd;IAA0B,eAAe,GAAjC,OAAO;CACf,OAgYF"}
+{"version":3,"file":"preProcess.d.ts","sourceRoot":"","sources":["../../../../src/utils/parsing/preProcess.js"],"names":[],"mappings":";AASA;;;;;;;;GAQG;AACH,+DANW,MAAM,mCAGd;IAA0B,eAAe,GAAjC,OAAO;CACf,OA4XF"}