0
# Token System and Expressions
1

2
Comprehensive token resolution system for handling unresolved values and creating Terraform expressions, enabling dynamic configuration and cross-resource references.
3

4
## Capabilities
5

6
### Token Class
7

8
Static utilities for token manipulation, conversion, and resolution of unresolved values.
9

10
```typescript { .api }
11
/**
12
 * Token manipulation and resolution utilities
13
 */
14
class Token {
15
  /**
16
   * Check if a value contains unresolved tokens
17
   * @param obj - Value to check
18
   * @returns True if the value contains unresolved tokens
19
   */
20
  static isUnresolved(obj: any): boolean;
21

22
  /**
23
   * Convert a value to a string, resolving tokens as needed
24
   * @param value - Value to convert
25
   * @param options - Encoding options
26
   * @returns String representation
27
   */
28
  static asString(value: any, options?: EncodingOptions): string;
29

30
  /**
31
   * Convert a value to a number, resolving tokens as needed
32
   * @param value - Value to convert
33
   * @returns Numeric representation
34
   */
35
  static asNumber(value: any): number;
36

37
  /**
38
   * Convert a value to a string array, resolving tokens as needed
39
   * @param value - Value to convert
40
   * @param options - Encoding options
41
   * @returns Array of strings
42
   */
43
  static asList(value: any, options?: EncodingOptions): string[];
44

45
  /**
46
   * Convert a value to a number array, resolving tokens as needed
47
   * @param value - Value to convert
48
   * @returns Array of numbers
49
   */
50
  static asNumberList(value: any): number[];
51

52
  /**
53
   * Convert a value to a string map, resolving tokens as needed
54
   * @param value - Value to convert
55
   * @param options - Encoding options
56
   * @returns Map of strings
57
   */
58
  static asStringMap(value: any, options?: EncodingOptions): {[key: string]: string};
59

60
  /**
61
   * Convert a value to a number map, resolving tokens as needed
62
   * @param value - Value to convert
63
   * @param options - Encoding options
64
   * @returns Map of numbers
65
   */
66
  static asNumberMap(value: any, options?: EncodingOptions): {[key: string]: number};
67

68
  /**
69
   * Convert a value to a boolean map, resolving tokens as needed
70
   * @param value - Value to convert
71
   * @param options - Encoding options
72
   * @returns Map of booleans
73
   */
74
  static asBooleanMap(value: any, options?: EncodingOptions): {[key: string]: boolean};
75

76
  /**
77
   * Convert a value to any type of map, resolving tokens as needed
78
   * @param value - Value to convert
79
   * @param options - Encoding options
80
   * @returns Map of any values
81
   */
82
  static asAnyMap(value: any, options?: EncodingOptions): {[key: string]: any};
83

84
  /**
85
   * Convert a value to any type, resolving tokens as needed
86
   * @param value - Value to convert
87
   * @returns Resolved value as IResolvable
88
   */
89
  static asAny(value: any): IResolvable;
90

91
  /**
92
   * Create a null value token
93
   * @returns Null value as IResolvable
94
   */
95
  static nullValue(): IResolvable;
96
}
97
```
98

99
**Usage Examples:**
100

101
```typescript
102
import { Token, TerraformOutput, TerraformVariable } from "cdktf";
103

104
// Check if a value is unresolved
105
const variable = new TerraformVariable(this, "region", {
106
  type: "string",
107
  default: "us-east-1"
108
});
109

110
console.log(Token.isUnresolved(variable.stringValue)); // true
111
console.log(Token.isUnresolved("literal-string"));    // false
112

113
// Convert tokens to various types
114
const output = new TerraformOutput(this, "region_output", {
115
  value: variable.stringValue
116
});
117

118
const regionString = Token.asString(variable.stringValue);
119
const portNumber = Token.asNumber(variable.numberValue);
120
const tagsList = Token.asList(variable.listValue);
121
const tagsMap = Token.asStringMap({
122
  Environment: variable.stringValue,
123
  Project: "my-app"
124
});
125
```
126

127
### Lazy Class
128

129
Lazy evaluation utilities for deferring computation until synthesis time.
130

131
```typescript { .api }
132
/**
133
 * Lazy evaluation utilities for deferred computation
134
 */
135
class Lazy {
136
  /**
137
   * Create a lazy string value
138
   * @param producer - Function that produces the string value
139
   * @param options - Lazy string options
140
   * @returns Lazy string value
141
   */
142
  static stringValue(producer: IStringProducer, options?: LazyStringValueOptions): string;
143

144
  /**
145
   * Create a lazy number value
146
   * @param producer - Function that produces the number value
147
   * @returns Lazy number value
148
   */
149
  static numberValue(producer: INumberProducer): number;
150

151
  /**
152
   * Create a lazy list value
153
   * @param producer - Function that produces the list value
154
   * @param options - Lazy list options
155
   * @returns Lazy list value
156
   */
157
  static listValue(producer: IListProducer, options?: LazyListValueOptions): string[];
158

159
  /**
160
   * Create a lazy value of any type
161
   * @param producer - Function that produces the value
162
   * @param options - Lazy value options
163
   * @returns Lazy value as IResolvable
164
   */
165
  static anyValue(producer: IAnyProducer, options?: LazyAnyValueOptions): IResolvable;
166
}
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import { Lazy, TerraformStack } from "cdktf";
173

174
class MyStack extends TerraformStack {
175
  constructor(scope: Construct, id: string) {
176
    super(scope, id);
177

178
    // Lazy string that computes at synthesis time
179
    const dynamicName = Lazy.stringValue({
180
      produce: () => {
181
        const timestamp = Date.now();
182
        return `resource-${timestamp}`;
183
      }
184
    });
185

186
    // Lazy list that filters resources
187
    const activeInstanceIds = Lazy.listValue({
188
      produce: () => {
189
        return this.getActiveInstances().map(i => i.id);
190
      }
191
    });
192
  }
193

194
  private getActiveInstances(): any[] {
195
    // Implementation to get active instances
196
    return [];
197
  }
198
}
199
```
200

201
### Expression Functions
202

203
Functions for creating Terraform expressions and references.
204

205
```typescript { .api }
206
/**
207
 * Create a reference to a Terraform resource or data source
208
 * @param identifier - The identifier to reference
209
 * @param stack - Optional stack context
210
 * @returns Resolvable reference
211
 */
212
function ref(identifier: string, stack?: TerraformStack): IResolvable;
213

214
/**
215
 * Create a conditional expression (ternary operator)
216
 * @param condition - Condition expression
217
 * @param trueValue - Value if condition is true
218
 * @param falseValue - Value if condition is false
219
 * @returns Conditional expression result
220
 */
221
function conditional(condition: Expression, trueValue: Expression, falseValue: Expression): any;
222

223
/**
224
 * Create a property access expression
225
 * @param target - Target object expression
226
 * @param args - Property access arguments
227
 * @returns Property access expression
228
 */
229
function propertyAccess(target: Expression, args: Expression[]): IResolvable;
230

231
/**
232
 * Create a function call expression
233
 * @param name - Function name
234
 * @param args - Function arguments
235
 * @returns Function call expression
236
 */
237
function call(name: string, args: Expression[]): IResolvable;
238

239
/**
240
 * Create a for expression for list/map comprehension
241
 * @param input - Input collection expression
242
 * @param valueExpression - Expression for each value
243
 * @param keyExpression - Optional expression for each key
244
 * @returns For expression result
245
 */
246
function forExpression(
247
  input: Expression,
248
  valueExpression: Expression,
249
  keyExpression?: Expression
250
): IResolvable;
251

252
/**
253
 * Create a reference to a dependable resource
254
 * @param dependable - The dependable resource
255
 * @returns Dependable reference string
256
 */
257
function dependable(dependable: ITerraformDependable): string;
258

259
/**
260
 * Create a raw string literal that won't be processed as a token
261
 * @param str - Raw string value
262
 * @returns Raw string as IResolvable
263
 */
264
function rawString(str: string): IResolvable;
265
```
266

267
**Usage Examples:**
268

269
```typescript
270
import { ref, conditional, propertyAccess, forExpression } from "cdktf";
271

272
// Create references
273
const instanceRef = ref("aws_instance.web.id");
274
const crossStackRef = ref("data.terraform_remote_state.vpc.outputs.vpc_id", otherStack);
275

276
// Conditional expressions
277
const environmentName = conditional(
278
  ref("var.is_production"),
279
  "production",
280
  "development"
281
);
282

283
// Property access
284
const instanceAz = propertyAccess(ref("aws_instance.web"), ["availability_zone"]);
285

286
// For expressions - transform a list
287
const upperCaseNames = forExpression(
288
  ref("var.user_names"),
289
  call("upper", [ref("each.value")])
290
);
291

292
// For expressions - create a map from list
293
const userEmailMap = forExpression(
294
  ref("var.users"),
295
  ref("each.value.email"),
296
  ref("each.value.name")
297
);
298
```
299

300
### Operator Expressions
301

302
Support for Terraform operators in expressions.
303

304
```typescript { .api }
305
/**
306
 * Operator expression for mathematical and logical operations
307
 */
308
class OperatorExpression {
309
  /**
310
   * Create an operator expression
311
   * @param left - Left operand
312
   * @param operator - Operator string
313
   * @param right - Right operand
314
   */
315
  constructor(left: Expression, operator: string, right: Expression);
316

317
  /**
318
   * Addition operator
319
   * @param left - Left operand
320
   * @param right - Right operand
321
   * @returns Addition expression
322
   */
323
  static add(left: Expression, right: Expression): OperatorExpression;
324

325
  /**
326
   * Subtraction operator
327
   * @param left - Left operand
328
   * @param right - Right operand
329
   * @returns Subtraction expression
330
   */
331
  static subtract(left: Expression, right: Expression): OperatorExpression;
332

333
  /**
334
   * Multiplication operator
335
   * @param left - Left operand
336
   * @param right - Right operand
337
   * @returns Multiplication expression
338
   */
339
  static multiply(left: Expression, right: Expression): OperatorExpression;
340

341
  /**
342
   * Division operator
343
   * @param left - Left operand
344
   * @param right - Right operand
345
   * @returns Division expression
346
   */
347
  static divide(left: Expression, right: Expression): OperatorExpression;
348

349
  /**
350
   * Equality operator
351
   * @param left - Left operand
352
   * @param right - Right operand
353
   * @returns Equality expression
354
   */
355
  static equals(left: Expression, right: Expression): OperatorExpression;
356

357
  /**
358
   * Inequality operator
359
   * @param left - Left operand
360
   * @param right - Right operand
361
   * @returns Inequality expression
362
   */
363
  static notEquals(left: Expression, right: Expression): OperatorExpression;
364

365
  /**
366
   * Logical AND operator
367
   * @param left - Left operand
368
   * @param right - Right operand
369
   * @returns AND expression
370
   */
371
  static and(left: Expression, right: Expression): OperatorExpression;
372

373
  /**
374
   * Logical OR operator
375
   * @param left - Left operand
376
   * @param right - Right operand
377
   * @returns OR expression
378
   */
379
  static or(left: Expression, right: Expression): OperatorExpression;
380
}
381
```
382

383
## Type Definitions
384

385
```typescript { .api }
386
/**
387
 * Base interface for resolvable values
388
 */
389
interface IResolvable {
390
  /**
391
   * Stack trace of where this resolvable was created
392
   */
393
  readonly creationStack: string[];
394

395
  /**
396
   * Resolve the value during synthesis
397
   * @param context - Resolution context
398
   * @returns Resolved value
399
   */
400
  resolve(context: IResolveContext): any;
401

402
  /**
403
   * String representation of the resolvable
404
   * @returns String representation
405
   */
406
  toString(): string;
407
}
408

409
/**
410
 * Context provided during token resolution
411
 */
412
interface IResolveContext {
413
  /**
414
   * The scope in which resolution is taking place
415
   */
416
  readonly scope: IConstruct;
417

418
  /**
419
   * True if we are preparing for JSON output
420
   */
421
  readonly preparing: boolean;
422
}
423

424
/**
425
 * Union type for all expression types
426
 */
427
type Expression = string | number | boolean | IResolvable | any[];
428

429
/**
430
 * Options for encoding tokens as strings
431
 */
432
interface EncodingOptions {
433
  /**
434
   * Character to use for quotes
435
   * @default '"'
436
   */
437
  readonly displayHint?: string;
438
}
439

440
/**
441
 * Producer interface for lazy string values
442
 */
443
interface IStringProducer {
444
  /**
445
   * Produce the string value
446
   */
447
  produce(context?: IResolveContext): string;
448
}
449

450
/**
451
 * Producer interface for lazy number values
452
 */
453
interface INumberProducer {
454
  /**
455
   * Produce the number value
456
   */
457
  produce(context?: IResolveContext): number;
458
}
459

460
/**
461
 * Producer interface for lazy list values
462
 */
463
interface IListProducer {
464
  /**
465
   * Produce the list value
466
   */
467
  produce(context?: IResolveContext): string[];
468
}
469

470
/**
471
 * Producer interface for lazy any values
472
 */
473
interface IAnyProducer {
474
  /**
475
   * Produce the value
476
   */
477
  produce(context?: IResolveContext): any;
478
}
479

480
/**
481
 * Options for lazy string values
482
 */
483
interface LazyStringValueOptions {
484
  /**
485
   * Display hint for the lazy value
486
   */
487
  readonly displayHint?: string;
488
}
489

490
/**
491
 * Options for lazy list values
492
 */
493
interface LazyListValueOptions {
494
  /**
495
   * Display hint for the lazy value
496
   */
497
  readonly displayHint?: string;
498

499
  /**
500
   * Omit empty arrays from output
501
   * @default false
502
   */
503
  readonly omitEmpty?: boolean;
504
}
505

506
/**
507
 * Options for lazy any values
508
 */
509
interface LazyAnyValueOptions {
510
  /**
511
   * Display hint for the lazy value
512
   */
513
  readonly displayHint?: string;
514

515
  /**
516
   * Omit empty values from output
517
   * @default false
518
   */
519
  readonly omitEmptyArray?: boolean;
520
}
521

522
/**
523
 * Constants for for expression variables
524
 */
525
declare const FOR_EXPRESSION_KEY: string;
526
declare const FOR_EXPRESSION_VALUE: string;
527
```