0
# Conditional Logic
1

2
Conditional logic helpers that create complex template logic with type-safe comparisons and multiple test scenarios. The select/truth test system enables sophisticated conditional rendering patterns.
3

4
## Capabilities
5

6
### Select Helper
7

8
Groups truth tests and outputs the first one that passes, providing structured conditional logic for templates.
9

10
```javascript { .api }
11
/**
12
 * Groups truth tests and outputs the first match
13
 * @param key - Value to use as left-hand side of comparisons (optional)
14
 * @param type - Coerce all comparison keys to this type (optional)
15
 */
16
{@select key="comparison_value" type="coercion_type"}
17
  <!-- Truth test helpers go here -->
18
{/select}
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
// Basic select with key
25
{@select key="{userStatus}"}
26
  {@eq value="active"}User is active{/eq}
27
  {@eq value="inactive"}User is inactive{/eq}
28
  {@eq value="pending"}User is pending approval{/eq}
29
{/select}
30

31
// Select with type coercion
32
{@select key="{userAge}" type="number"}
33
  {@lt value="18"}Minor{/lt}
34
  {@gte value="18"}Adult{/gte}
35
{/select}
36

37
// Select without global key (each truth test provides its own key)
38
{@select}
39
  {@eq key="{status}" value="published"}Content is published{/eq}
40
  {@eq key="{featured}" value="true"}Content is featured{/eq}
41
{/select}
42
```
43

44
### Truth Test Helpers
45

46
Comparison helpers that test conditions and render content based on the results. All truth tests can be used standalone or within {@select} blocks.
47

48
```javascript { .api }
49
/**
50
 * Equality test helper
51
 * @param key - Left-hand side value (optional if within @select)
52
 * @param value - Right-hand side value for comparison (required)
53
 * @param type - Type coercion override (optional)
54
 */
55
{@eq key="left_value" value="right_value" type="coercion_type"}
56
  Content when values are equal
57
{:else}
58
  Content when values are not equal
59
{/eq}
60

61
/**
62
 * Inequality test helper
63
 * @param key - Left-hand side value (optional if within @select)
64
 * @param value - Right-hand side value for comparison (required)
65
 * @param type - Type coercion override (optional)
66
 */
67
{@ne key="left_value" value="right_value" type="coercion_type"}
68
  Content when values are not equal
69
{:else}
70
  Content when values are equal
71
{/ne}
72

73
/**
74
 * Less than test helper
75
 * @param key - Left-hand side value (optional if within @select)
76
 * @param value - Right-hand side value for comparison (required)
77
 * @param type - Type coercion override (optional)
78
 */
79
{@lt key="left_value" value="right_value" type="coercion_type"}
80
  Content when left < right
81
{:else}
82
  Content when left >= right
83
{/lt}
84

85
/**
86
 * Less than or equal test helper
87
 * @param key - Left-hand side value (optional if within @select)
88
 * @param value - Right-hand side value for comparison (required)
89
 * @param type - Type coercion override (optional)
90
 */
91
{@lte key="left_value" value="right_value" type="coercion_type"}
92
  Content when left <= right
93
{:else}
94
  Content when left > right
95
{/lte}
96

97
/**
98
 * Greater than test helper
99
 * @param key - Left-hand side value (optional if within @select)
100
 * @param value - Right-hand side value for comparison (required)
101
 * @param type - Type coercion override (optional)
102
 */
103
{@gt key="left_value" value="right_value" type="coercion_type"}
104
  Content when left > right
105
{:else}
106
  Content when left <= right
107
{/gt}
108

109
/**
110
 * Greater than or equal test helper
111
 * @param key - Left-hand side value (optional if within @select)
112
 * @param value - Right-hand side value for comparison (required)
113
 * @param type - Type coercion override (optional)
114
 */
115
{@gte key="left_value" value="right_value" type="coercion_type"}
116
  Content when left >= right
117
{:else}
118
  Content when left < right
119
{/gte}
120
```
121

122
**Usage Examples:**
123

124
```javascript
125
// Standalone truth tests
126
{@eq key="{user.role}" value="admin"}
127
  <div class="admin-panel">Admin Controls</div>
128
{/eq}
129

130
{@gt key="{score}" value="90"}
131
  <span class="grade-a">Excellent!</span>
132
{:else}
133
  <span class="grade-lower">Keep trying</span>
134
{/gt}
135

136
// Within select blocks
137
{@select key="{priority}" type="number"}
138
  {@eq value="1"}High Priority{/eq}
139
  {@eq value="2"}Medium Priority{/eq}
140
  {@eq value="3"}Low Priority{/eq}
141
{/select}
142
```
143

144
### Conditional Flow Helpers
145

146
Special helpers that work within {@select} blocks to handle complex conditional scenarios.
147

148
```javascript { .api }
149
/**
150
 * Any helper - renders if at least one truth test in the parent @select passes
151
 * Must be used inside a @select block
152
 */
153
{@any}
154
  Content to show if any condition matched
155
{/any}
156

157
/**
158
 * None helper - renders if no truth tests in the parent @select pass
159
 * Must be used inside a @select block
160
 */
161
{@none}
162
  Content to show if no conditions matched
163
{/none}
164
```
165

166
**Usage Examples:**
167

168
```javascript
169
{@select key="{userType}"}
170
  {@eq value="premium"}Premium Features Available{/eq}
171
  {@eq value="pro"}Pro Features Available{/eq}
172
  {@any}
173
    <p>You have special account privileges</p>
174
  {/any}
175
  {@none}
176
    <p>Standard account features only</p>
177
  {/none}
178
{/select}
179

180
// Complex example with multiple conditions
181
{@select key="{user.status}"}
182
  {@eq value="active"}
183
    {@select key="{user.subscription}"}
184
      {@eq value="premium"}Premium Active User{/eq}
185
      {@eq value="basic"}Basic Active User{/eq}
186
      {@none}Active User - No Subscription{/none}
187
    {/select}
188
  {/eq}
189
  {@eq value="inactive"}Inactive User{/eq}
190
  {@none}Unknown User Status{/none}
191
{/select}
192
```
193

194
## Type Coercion
195

196
All comparison helpers support automatic type coercion to ensure consistent comparisons:
197

198
- `number`: Converts values using `+value`
199
- `string`: Converts values using `String(value)`
200
- `boolean`: Converts values to boolean (`'false'` string becomes `false`)
201
- `date`: Converts values using `new Date(value)`
202

203
**Type Coercion Examples:**
204

205
```javascript
206
// String comparison
207
{@select key="{userId}" type="string"}
208
  {@eq value="123"}User found{/eq}
209
{/select}
210

211
// Numeric comparison
212
{@select key="{age}" type="number"}
213
  {@gte value="21"}Can drink{/gte}
214
  {@lt value="21"}Too young{/lt}
215
{/select}
216

217
// Boolean comparison
218
{@select key="{isEnabled}" type="boolean"}
219
  {@eq value="true"}Feature is enabled{/eq}
220
  {@eq value="false"}Feature is disabled{/eq}
221
{/select}
222
```
223

224
**Error Handling:**
225

226
**Truth Test Helpers (eq, ne, lt, lte, gt, gte):**
227
- **Missing key**: Logs warning `"{@helperName}: No key specified"` and skips rendering
228
- **Missing value parameter**: No error, uses `undefined` for comparison
229
- **Type coercion errors**: Values that cannot be coerced retain their original type
230

231
**Select Helper:**
232
- **Missing body block**: Logs warning `"{@select}: Missing body block"`
233
- **Invalid key references**: Resolves to `undefined` and continues processing
234
- **Type coercion failures**: Uses original value type if coercion fails
235

236
**Any/None Helpers:**
237
- **Used outside @select**: Logs error `"{@any}: Must be used inside a {@select} block"`
238
- **Nested any/none**: Logs error `"{@any}: Must not be nested inside {@any} or {@none} block"` and skips rendering
239
- **Deferred rendering failures**: Handled gracefully with chunk mapping
240

241
**Logging:**
242

243
All error and warning messages use the dust logging system:
244
- `dust.log(helperName, message, "WARN")` for non-critical issues
245
- `dust.log(helperName, message, "ERROR")` for critical violations
246
- Helper names in log messages match the template helper name (e.g., "eq", "select", "any")