configorama 0.9.5 → 0.9.11

package/README.md

@@ -2,7 +2,7 @@
 
 Dynamic configuration values with variable support.
 
-Works with `yml`, `json`, `toml` config formats and anything that parsed down to a plain ol' javascript object
+Works with `yml`, `json`, `toml`, `hcl` (Terraform), and other config formats. Supports any format that can be parsed to a plain JavaScript object
 
 ## About
 
@@ -16,6 +16,7 @@ Configorama extends your configuration with a powerful variable system. It resol
 - Git references
 - Cron values
 - Eval expressions
+- If/conditional expressions
 - Async/sync JS functions
 - Filters (experimental)
 - Functions (experimental)
@@ -45,6 +46,7 @@ See [tests](https://github.com/DavidWells/configorama/tree/master/tests) for mor
   - [Git references](#git-references)
   - [Cron Values](#cron-values)
   - [Eval expressions](#eval-expressions)
+  - [If expressions](#if-expressions)
   - [Filters (experimental)](#filters-experimental)
   - [Functions (experimental)](#functions-experimental)
   - [More Examples](#more-examples)
@@ -98,7 +100,7 @@ Configorama creates a graph of your config file and all its dependencies, then i
 
 ```mermaid
 flowchart TD
-    A[Load config file] --> B[Parse yml/json/toml to object]
+    A[Load config file] --> B[Parse yml/json/toml/hcl to object]
     B --> C[Preprocess: raw config file]
     C --> D{Return metadata only?}
     D -->|Yes| E[Collect variable metadata]
@@ -150,6 +152,7 @@ console.log(result.resolutionHistory) // Step-by-step resolution for each path
 | git      | ${git:value}          | Git data               |
 | cron     | ${cron(expr)}         | Cron expressions       |
 | eval     | ${eval(expr)}         | Math/logic expressions |
+| if       | ${if(expr)}           | Conditional expressions |
 
 ### Environment variables
 
@@ -253,10 +256,10 @@ three: ${zaz.wow.cool} # Resolves to `2`
 
 ### File references
 
-Import values from external yml, json, or toml files by relative path.
+Import values from external yml, json, toml, or hcl files by relative path.
 
 ```yml
-# Import full yml/json/toml file via relative path
+# Import full yml/json/toml/hcl file via relative path
 fileRef: ${file(./subFile.yml)}
 
 # Import sub values from files. This imports other-config.yml `topLevel:` value
@@ -279,7 +282,7 @@ Supported file types (extensions are case-insensitive):
 | YAML | `.yml`, `.yaml` |
 | TOML | `.toml`, `.tml` |
 | INI | `.ini` |
-| JSON | `.json`, `.json5` |
+| JSON | `.json`, `.json5`, `.jsonc` |
 
 ### Sync/Async file references
 
@@ -533,6 +536,74 @@ npm install ts-node typescript --save-dev
 - Full TypeScript interface support
 - Comprehensive error handling with helpful dependency messages
 
+### Terraform HCL support
+
+Configorama supports Terraform HCL (HashiCorp Configuration Language) files, allowing you to parse `.tf`, `.tf.json`, and `.hcl` files.
+
+**Installation:**
+
+HCL parsing requires the optional `@cdktf/hcl2json` package:
+
+```bash
+npm install @cdktf/hcl2json
+```
+
+**Supported file types:**
+- `.tf` - Terraform configuration files
+- `.hcl` - Generic HCL files
+- `.tf.json` - Terraform JSON configuration files
+
+**Example:**
+
+```js
+const configorama = require('configorama')
+
+// Parse a Terraform configuration file
+const terraformConfig = await configorama('./main.tf')
+
+// Access Terraform variables, resources, locals, etc.
+console.log(terraformConfig.variable)  // Variables defined in the file
+console.log(terraformConfig.resource)  // Resources
+console.log(terraformConfig.locals)    // Local values
+console.log(terraformConfig.output)    // Outputs
+```
+
+**Importing Terraform files:**
+
+```yml
+# Import Terraform variables from a .tf file
+terraformVars: ${file(./terraform/variables.tf)}
+
+# Import specific variable from Terraform file
+region: ${file(./terraform/variables.tf):variable.region[0].default}
+```
+
+**Variable syntax:**
+When loading `.tf` or `.hcl` files directly, configorama automatically uses `$[...]` syntax instead of `${...}` to avoid conflicts with Terraform's native `${var.name}` interpolation. Terraform expressions like `${var.environment}` and `${map(string)}` are preserved as-is.
+
+```js
+// Loading .tf directly - uses $[...] syntax automatically
+const config = await configorama('./main.tf')
+// config.locals[0].app_name = "myapp-${var.environment}" (preserved)
+
+// Use $[...] for configorama variables in .tf files
+// myvar: $[env:MY_VAR]
+// myref: $[file(./other.yml)]  # referenced files also use $[...]
+```
+
+When importing `.tf` files from other config formats (yml, json, etc.) via `${file()}`, the parent file's syntax applies. Use `allowUnknownVariableTypes: true` if the imported `.tf` contains Terraform interpolations:
+
+```js
+const config = await configorama('./config.yml', {
+  allowUnknownVariableTypes: true
+})
+```
+
+**Read-only support:**
+Currently, HCL files can be read and parsed, but writing/generating HCL files is not supported.
+
+See [tests/hclTests](./tests/hclTests) for example Terraform files.
+
 ### Git references
 
 Access repository information from the current working directory's git data.
@@ -647,6 +718,85 @@ strictEqual: ${eval("foo" === "foo")} # true
 complex: ${eval((10 + 5) * 2)}        # 30
 ```
 
+### If expressions
+
+Conditional expressions using ternary syntax. This is an alias for `eval` with a more intuitive name for conditionals.
+
+```yml
+# Basic ternary (condition ? "yes" : "no")
+status: ${if((5 > 3) ? "yes" : "no")}           # "yes"
+
+# With variables
+threshold: 50
+value: 75
+result: ${if((${self:value} > ${self:threshold}) ? "above" : "below")}  # "above"
+
+# Nested ternary (if/else if/else)
+score: 85
+grade: ${if((${self:score} >= 90) ? "A" : (${self:score} >= 80) ? "B" : "C")}  # "B"
+
+# Boolean result (no ternary needed)
+isValid: ${if(${self:value} > 0)}               # true
+
+# Logical operators
+enabled: true
+count: 5
+canProceed: ${if(${self:enabled} && ${self:count} > 0)}  # true
+```
+
+**Supported operators:**
+
+| Category | Operators |
+|----------|-----------|
+| Comparison | `==` `!=` `===` `!==` `>` `<` `>=` `<=` |
+| Logical | `&&` `\|\|` `!` |
+| Nullish | `??` |
+| Ternary | `condition ? "yes" : "no"` |
+
+**Serverless deployment examples:**
+
+```yml
+service: my-service
+
+provider:
+  name: aws
+  stage: ${opt:stage, 'dev'}
+  region: ${opt:region, 'us-east-1'}
+
+custom:
+  # Different memory by stage
+  memorySize: '${ if( ${provider.stage} === "prod" ) ? 1024 : 512 }'
+
+  # Different log retention by stage
+  logRetention: ${if(("${provider.stage}" === "prod") ? 30 : 7)}
+
+  # Enable features per environment
+  enableDebugEndpoints: ${if("${provider.stage}" !== "prod")}
+  enableMetrics: ${if("${provider.stage}" === "prod")}
+
+  # Regional settings
+  replicaCount: ${if(("${provider.region}" === "us-east-1") ? 3 : 1)}
+
+  # Conditional IAM role (use predefined role in prod, inline in dev)
+  useExternalRole: ${if("${provider.stage}" === "prod")}
+  role: ${if((${custom.useExternalRole}) ? "arn:aws:iam::123:role/prod-role" : null)}
+
+functions:
+  api:
+    handler: handler.api
+    memorySize: ${custom.memorySize}
+
+  # Debug function - only deployed in non-prod
+  debug:
+    handler: handler.debug
+    enabled: ${custom.enableDebugEndpoints}
+
+  # Metrics processor - only in prod
+  metricsProcessor:
+    handler: handler.metrics
+    enabled: ${custom.enableMetrics}
+```
+
 ### Filters (experimental)
 
 Pipe resolved values through transformation functions like case conversion.
@@ -750,6 +900,7 @@ The `source` property defines how the config wizard handles each variable type:
 | `${git:branch}` | `readonly` | Git repository data |
 | `${cron(expr)}` | `readonly` | Cron expression conversion |
 | `${eval(expr)}` | `readonly` | Math/logic evaluation |
+| `${if(expr)}` | `readonly` | Conditional expressions |
 
 ## Options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "0.9.5",
+  "version": "0.9.11",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -25,10 +25,11 @@
     "info": "repomix --include \"cli.js,src/**/*.js\" --ignore \"**/*.test.js\" --copy",
     "docs": "node ./scripts/docs.js",
     "t": "./scripts/run-tests.sh",
-    "test": "npm run test:lib && uvu tests \".*\\.test.js$\" ",
+    "test": "npm run test:slow && npm run test:lib && uvu tests \".*\\.test.js$\"",
     "test:tests": "uvu tests \".*\\.test.js$\" ",
     "test:api": "uvu tests/api api.test.js",
     "test:lib": "uvu src \".*\\.test.js$\"",
+    "test:slow": "uvu src \".*\\.slow-test.js$\" && uvu tests \".*\\.slow-test.js$\"",
     "watch": "watchlist tests -- npm test",
     "typecheck": "tsc --noEmit",
     "types": "tsc",
@@ -84,11 +85,28 @@
     "traverse": "^0.6.8"
   },
   "devDependencies": {
+    "@cdktf/hcl2json": "^0.21.0",
     "@types/node": "^24.10.1",
     "markdown-magic": "^3.4.0",
     "tsx": "^4.7.0",
     "typescript": "^5.8.3",
     "uvu": "^0.5.6",
     "watchlist": "^0.3.1"
+  },
+  "peerDependencies": {
+    "@cdktf/hcl2json": ">=0.20.0",
+    "tsx": ">=4.0.0",
+    "ts-node": ">=10.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@cdktf/hcl2json": {
+      "optional": true
+    },
+    "tsx": {
+      "optional": true
+    },
+    "ts-node": {
+      "optional": true
+    }
   }
 }