From 5b81d37814cc4aae47dde4fc87b60eecae1d6308 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 31 May 2026 15:13:06 +0000
Subject: [PATCH 1/2] Initial plan


From b8e0e30d6b0b80f647d18c2d6b6d266c8b2da865 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 31 May 2026 15:14:21 +0000
Subject: [PATCH 2/2] docs: add variable expansion section to README

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/README.md b/README.md
index f09095e..1de3324 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,79 @@ Output:
 Cool App
 ```
 
+## Variable Expansion
+
+ts-appconfig supports variable expansion using the `${VARIABLE_NAME}` syntax. You can reference other variables within your environment schema or `.env` file, and they will be resolved automatically.
+
+**Basic expansion:**
+
+`.env`
+```
+APP_HOST=localhost
+APP_PORT=3000
+APP_URL=http://${APP_HOST}:${APP_PORT}
+```
+
+`src/environment.ts`
+```typescript
+export class Environment extends AppConfig {
+	readonly APP_HOST: string = '';
+	readonly APP_PORT: string = '';
+	readonly APP_URL: string = '';
+}
+
+export const env: Environment = configure(Environment);
+```
+
+`env.APP_URL` will resolve to `http://localhost:3000`.
+
+**Nested expansion:**
+
+Variables can reference other variables that are themselves references. ts-appconfig will resolve them in multiple passes until all variables are expanded.
+
+`.env`
+```
+FIRST=Hello
+SECOND=${FIRST} World
+THIRD=${SECOND}!
+```
+
+`env.THIRD` will resolve to `Hello World!`.
+
+**Referencing number variables:**
+
+When a string variable references a number variable, the number is cast to a string during expansion.
+
+```typescript
+export class Environment extends AppConfig {
+	readonly PORT: number = 3000;
+	readonly URL: string = 'http://localhost:${PORT}';
+}
+```
+
+`env.URL` will resolve to `'http://localhost:3000'`.
+
+**Circular references:**
+
+If two variables reference each other, a `CircularReferenceError` is thrown at configuration time.
+
+```typescript
+export class Environment extends AppConfig {
+	readonly A: string = '${B}';
+	readonly B: string = '${A}'; // CircularReferenceError!
+}
+```
+
+**Undefined references:**
+
+If a variable references a name that does not exist in the schema, an `UndefinedReferenceError` is thrown at configuration time.
+
+```typescript
+export class Environment extends AppConfig {
+	readonly A: string = '${DOES_NOT_EXIST}'; // UndefinedReferenceError!
+}
+```
+
 ## Options
 
 Pass `ConfigurationOptions` as a second argument to `configure` to customize how variables are loaded and parsed. All options are optional, you only have to specify the options you would like to change.