0
# Utility Helpers
1

2
Utility and debug helpers that provide debugging capabilities and utility operations for template development and maintenance.
3

4
## Capabilities
5

6
### Context Debug Helper
7

8
Helper for debugging template contexts by outputting context information in various formats.
9

10
```javascript { .api }
11
/**
12
 * Context dump helper - outputs context data for debugging
13
 * @param key - "full" for complete context stack, otherwise current context (optional)
14
 * @param to - "console" to log to console, otherwise outputs to template (optional)
15
 */
16
{@contextDump key="full|current" to="console|template"/}
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
// Dump current context to template
23
{@contextDump/}
24
<!-- Outputs JSON representation of current context -->
25

26
// Dump full context stack to template
27
{@contextDump key="full"/}
28
<!-- Outputs complete context stack as JSON -->
29

30
// Log current context to console
31
{@contextDump to="console"/}
32
<!-- Logs to console, no template output -->
33

34
// Log full context stack to console
35
{@contextDump key="full" to="console"/}
36
<!-- Logs complete stack to console -->
37

38
// Debug specific template section
39
<h2>User Profile</h2>
40
{#user}
41
  <p>Name: {name}</p>
42
  <p>Email: {email}</p>
43

44
  <!-- Debug the current user context -->
45
  {@contextDump to="console"/}
46
{/user}
47

48
// Debug in development environment
49
{@select key="{env}"}
50
  {@eq value="development"}
51
    <details>
52
      <summary>Debug Context</summary>
53
      <pre>{@contextDump/}</pre>
54
    </details>
55
  {/eq}
56
{/select}
57
```
58

59
**Output Format:**
60

61
The context dump is JSON-formatted with special handling for functions:
62
- Functions are converted to strings with formatting cleanup
63
- Output is escaped for safe HTML rendering when output to template
64
- Console output uses raw JSON format
65

66
**Context Types:**
67

68
- **Current context**: Shows only the current context head (default)
69
- **Full context**: Shows the entire context stack including parent contexts
70

71
### Deprecated Reference Helper
72

73
Legacy helper for resolving dust references (deprecated, use native dust resolution instead).
74

75
```javascript { .api }
76
/**
77
 * Tap helper - resolves dust references (DEPRECATED)
78
 * @param input - Value or reference to resolve
79
 * @deprecated Use native Dust context resolution instead
80
 * @removal_version 1.8
81
 */
82
{@tap}{reference_to_resolve}{/tap}
83
```
84

85
**Migration Examples:**
86

87
```javascript
88
// OLD (deprecated, will be removed in v1.8)
89
{@tap}{user.profile.name}{/tap}
90

91
// NEW (use native Dust resolution)
92
{user.profile.name}
93

94
// OLD (deprecated)
95
{@tap}{#items}{name}{/items}{/tap}
96

97
// NEW (native Dust iteration)
98
{#items}{name}{/items}
99

100
// OLD (deprecated with complex references)
101
{@tap}{user.settings[0].value}{/tap}
102

103
// NEW (native resolution)
104
{user.settings[0].value}
105
```
106

107
**Deprecation Warning:**
108

109
The `@tap` helper generates deprecation warnings when used:
110
- Warning message: "Deprecation warning: tap is deprecated and will be removed in a future version of dustjs-helpers"
111
- Links to migration documentation: https://github.com/linkedin/dustjs-helpers/wiki/Deprecated-Features#tap
112
- Scheduled removal in version 1.8
113
- Warnings are cached per helper name to prevent spam in logs
114
- Uses internal `_deprecated()` function that tracks already shown warnings
115

116
## Advanced Debugging Patterns
117

118
### Conditional Debug Output
119

120
```javascript
121
// Debug only in development mode
122
{@eq key="{debug}" value="true"}
123
  <div class="debug-panel">
124
    <h3>Template Debug Info</h3>
125
    <h4>Current Context:</h4>
126
    <pre>{@contextDump/}</pre>
127

128
    <h4>Full Stack:</h4>
129
    <pre>{@contextDump key="full"/}</pre>
130
  </div>
131
{/eq}
132

133
// Debug specific data sections
134
{#products}
135
  <div class="product">
136
    <h3>{name}</h3>
137

138
    {@contextDump key="current" to="console"/}
139

140
    {@select key="{debug}"}
141
      {@eq value="verbose"}
142
        <small>Debug: {name} | Price: {price} | Stock: {stock}</small>
143
      {/eq}
144
    {/select}
145
  </div>
146
{/products}
147
```
148

149
### Performance and Error Debugging
150

151
```javascript
152
// Log context size for performance monitoring
153
{@size key="{data}"}
154
  {@contextDump to="console"/}
155
  <!-- Log context when data size exceeds threshold -->
156
  {@gt value="1000"}
157
    {@contextDump key="full" to="console"/}
158
  {/gt}
159
{/@size}
160

161
// Debug missing data
162
{@contextDump key="current" to="console"/}
163
{@select key="{user}"}
164
  {@none}
165
    <!-- Log context when user is missing -->
166
    {@contextDump key="full" to="console"/}
167
    <p>User data not available</p>
168
  {/none}
169
{/select}
170
```
171

172
**Security Considerations:**
173

174
- Never use `@contextDump` with template output in production
175
- Context may contain sensitive data that should not be exposed to users
176
- Always use `to="console"` parameter for production debugging
177
- Consider environment-based conditional rendering for debug helpers
178

179
**Best Practices:**
180

181
- Use `@contextDump` primarily during development and testing
182
- Combine with conditional helpers to control when debugging occurs
183
- Log to console rather than template output to avoid exposing data
184
- Remove or conditionally disable debug helpers in production builds