0
# Static Analysis
1

2
LiquidJS provides static analysis capabilities for extracting variable dependencies and analyzing template requirements without rendering.
3

4
## Capabilities
5

6
### Variable Analysis
7

8
Extract variable names and dependencies from templates.
9

10
```typescript { .api }
11
/**
12
 * Get all variable names used in template
13
 * @param template - Template string or parsed Template array
14
 * @param options - Analysis options
15
 * @returns Promise resolving to array of variable names
16
 */
17
variables(template: string | Template[], options?: StaticAnalysisOptions): Promise<string[]>;
18

19
/**
20
 * Get all variable names used in template (synchronous)
21
 * @param template - Template string or parsed Template array  
22
 * @param options - Analysis options
23
 * @returns Array of variable names
24
 */
25
variablesSync(template: string | Template[], options?: StaticAnalysisOptions): string[];
26

27
/**
28
 * Get full variable paths including property access
29
 * @param template - Template string or parsed Template array
30
 * @param options - Analysis options
31
 * @returns Promise resolving to array of full variable paths
32
 */
33
fullVariables(template: string | Template[], options?: StaticAnalysisOptions): Promise<string[]>;
34

35
/**
36
 * Get full variable paths including property access (synchronous)
37
 * @param template - Template string or parsed Template array
38
 * @param options - Analysis options
39
 * @returns Array of full variable paths
40
 */
41
fullVariablesSync(template: string | Template[], options?: StaticAnalysisOptions): string[];
42
```
43

44
### Template Analysis
45

46
Perform comprehensive static analysis of templates.
47

48
```typescript { .api }
49
/**
50
 * Analyze template for variables and dependencies
51
 * @param template - Parsed Template array
52
 * @param options - Analysis options
53
 * @returns Promise resolving to StaticAnalysis result
54
 */
55
analyze(template: Template[], options?: StaticAnalysisOptions): Promise<StaticAnalysis>;
56

57
/**
58
 * Analyze template for variables and dependencies (synchronous)
59
 * @param template - Parsed Template array
60
 * @param options - Analysis options
61
 * @returns StaticAnalysis result
62
 */
63
analyzeSync(template: Template[], options?: StaticAnalysisOptions): StaticAnalysis;
64

65
/**
66
 * Parse and analyze template in one step
67
 * @param html - Template string
68
 * @param filename - Optional filename for error reporting
69
 * @param options - Analysis options
70
 * @returns Promise resolving to StaticAnalysis result
71
 */
72
parseAndAnalyze(html: string, filename?: string, options?: StaticAnalysisOptions): Promise<StaticAnalysis>;
73

74
/**
75
 * Parse and analyze template in one step (synchronous)
76
 * @param html - Template string
77
 * @param filename - Optional filename for error reporting
78
 * @param options - Analysis options
79
 * @returns StaticAnalysis result
80
 */
81
parseAndAnalyzeSync(html: string, filename?: string, options?: StaticAnalysisOptions): StaticAnalysis;
82
```
83

84
### Variable Segments Analysis
85

86
Extract variables as arrays of property segments for detailed path analysis.
87

88
```typescript { .api }
89
/**
90
 * Get all variables as arrays of property segments
91
 * @param template - Template string or parsed Template array
92
 * @param options - Analysis options
93
 * @returns Promise resolving to array of segment arrays
94
 */
95
variableSegments(template: string | Template[], options?: StaticAnalysisOptions): Promise<SegmentArray[]>;
96

97
/**
98
 * Get all variables as arrays of property segments (synchronous)
99
 * @param template - Template string or parsed Template array
100
 * @param options - Analysis options
101
 * @returns Array of segment arrays
102
 */
103
variableSegmentsSync(template: string | Template[], options?: StaticAnalysisOptions): SegmentArray[];
104
```
105

106
### Global Variable Analysis
107

108
Extract global (out-of-scope) variables that need to be provided by the application.
109

110
```typescript { .api }
111
/**
112
 * Get all global variable names (variables not in local scope)
113
 * @param template - Template string or parsed Template array
114
 * @param options - Analysis options
115
 * @returns Promise resolving to array of global variable names
116
 */
117
globalVariables(template: string | Template[], options?: StaticAnalysisOptions): Promise<string[]>;
118

119
/**
120
 * Get all global variable names (synchronous)
121
 * @param template - Template string or parsed Template array
122
 * @param options - Analysis options
123
 * @returns Array of global variable names
124
 */
125
globalVariablesSync(template: string | Template[], options?: StaticAnalysisOptions): string[];
126

127
/**
128
 * Get full global variable paths including property access
129
 * @param template - Template string or parsed Template array
130
 * @param options - Analysis options
131
 * @returns Promise resolving to array of full global variable paths
132
 */
133
globalFullVariables(template: string | Template[], options?: StaticAnalysisOptions): Promise<string[]>;
134

135
/**
136
 * Get full global variable paths including property access (synchronous)
137
 * @param template - Template string or parsed Template array
138
 * @param options - Analysis options
139
 * @returns Array of full global variable paths
140
 */
141
globalFullVariablesSync(template: string | Template[], options?: StaticAnalysisOptions): string[];
142

143
/**
144
 * Get all global variables as arrays of property segments
145
 * @param template - Template string or parsed Template array
146
 * @param options - Analysis options
147
 * @returns Promise resolving to array of global segment arrays
148
 */
149
globalVariableSegments(template: string | Template[], options?: StaticAnalysisOptions): Promise<SegmentArray[]>;
150

151
/**
152
 * Get all global variables as arrays of property segments (synchronous)
153
 * @param template - Template string or parsed Template array
154
 * @param options - Analysis options
155
 * @returns Array of global segment arrays
156
 */
157
globalVariableSegmentsSync(template: string | Template[], options?: StaticAnalysisOptions): SegmentArray[];
158
```
159

160
## Types
161

162
### Analysis Results
163

164
```typescript { .api }
165
interface StaticAnalysis {
166
  /** All variables referenced in the template */
167
  variables: Variables;
168
  /** Variables not in local scope (need to be provided by application) */
169
  globals: Variables;
170
  /** Variables added to local scope by tags like assign, capture, increment */
171
  locals: Variables;
172
}
173

174
interface Variables {
175
  [key: string]: Variable[];
176
}
177

178
interface VariableLocation {
179
  row: number;
180
  col: number;
181
  file?: string;
182
}
183

184
class Variable {
185
  readonly segments: Array<string | number | Variable>;
186
  readonly location: VariableLocation;
187
  
188
  toString(): string;
189
  toArray(): SegmentArray;
190
}
191

192
type SegmentArray = Array<string | number | SegmentArray>;
193

194
interface StaticAnalysisOptions {
195
  /** When true (default), try to load partial templates and analyze them too */
196
  partials?: boolean;
197
}
198
```
199

200
## Usage Examples
201

202
### Basic Variable Analysis
203

204
```typescript
205
import { Liquid } from "liquidjs";
206

207
const engine = new Liquid();
208
const template = `
209
  Hello {{ user.name }}!
210
  {% for item in items %}
211
    {{ item.title | capitalize }}
212
  {% endfor %}
213
  Total: {{ cart.total | money }}
214
`;
215

216
// Get variable names
217
const vars = await engine.variables(template);
218
console.log(vars); // ['user', 'items', 'cart']
219

220
// Get full variable paths  
221
const fullVars = await engine.fullVariables(template);
222
console.log(fullVars); // ['user.name', 'items', 'cart.total']
223
```
224

225
### Comprehensive Analysis
226

227
```typescript
228
const templates = engine.parse(template);
229
const analysis = await engine.analyze(templates);
230

231
console.log('All variables:', analysis.variables);
232
console.log('Global variables:', analysis.globals);
233
console.log('Local variables:', analysis.locals);
234

235
// Variable locations with segments
236
const segments = await engine.variableSegments(template);
237
console.log(segments); // [['user', 'name'], ['items'], ['cart', 'total']]
238

239
// Global variable analysis
240
const globalVars = await engine.globalVariables(template);
241
console.log('Global variable names:', globalVars); // ['user', 'items', 'cart']
242

243
const globalFullVars = await engine.globalFullVariables(template);
244
console.log('Global full paths:', globalFullVars); // ['user.name', 'items', 'cart.total']
245
```
246

247
### Parse and Analyze Combined
248

249
```typescript
250
// One-step parsing and analysis
251
const analysisResult = await engine.parseAndAnalyze(template);
252
console.log('Variables found:', Object.keys(analysisResult.variables));
253

254
// With filename for better error reporting
255
const result = await engine.parseAndAnalyze(template, 'product-card.liquid');
256
console.log('Analysis for product-card.liquid:', result);
257
```