0
# Core Template Engine
1

2
The Liquid class is the main entry point for LiquidJS, providing comprehensive template parsing and rendering capabilities with support for both synchronous and asynchronous operations.
3

4
## Capabilities
5

6
### Liquid Class
7

8
Main engine class for parsing and rendering Liquid templates with extensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * Main LiquidJS template engine
13
 */
14
class Liquid {
15
  readonly options: NormalizedFullOptions;
16
  readonly renderer: Render;
17
  readonly parser: Parser; // @deprecated
18
  readonly filters: Record<string, FilterImplOptions>;
19
  readonly tags: Record<string, TagClass>;
20
  
21
  constructor(opts?: LiquidOptions);
22
}
23
```
24

25
### Template Parsing
26

27
Parse template strings or files into Template arrays for rendering.
28

29
```typescript { .api }
30
/**
31
 * Parse template string into Template array
32
 * @param html - Template string to parse
33
 * @param filepath - Optional filepath for error reporting
34
 * @returns Array of parsed templates
35
 */
36
parse(html: string, filepath?: string): Template[];
37

38
/**
39
 * Parse template file asynchronously
40
 * @param file - Path to template file
41
 * @param lookupType - Type of lookup (Root, Partials, Layouts)
42
 * @returns Promise resolving to Template array
43
 */
44
parseFile(file: string, lookupType?: LookupType): Promise<Template[]>;
45

46
/**
47
 * Parse template file synchronously
48
 * @param file - Path to template file  
49
 * @param lookupType - Type of lookup (Root, Partials, Layouts)
50
 * @returns Template array
51
 */
52
parseFileSync(file: string, lookupType?: LookupType): Template[];
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
import { Liquid } from "liquidjs";
59

60
const engine = new Liquid();
61

62
// Parse template string
63
const templates = engine.parse("Hello {{ name }}!");
64

65
// Parse template file
66
const fileTemplates = await engine.parseFile("template.liquid");
67

68
// Parse with specific lookup type
69
const partialTemplates = await engine.parseFile("header.liquid", "partials");
70
```
71

72
### Template Rendering
73

74
Render parsed templates with data context, supporting multiple output formats.
75

76
```typescript { .api }
77
/**
78
 * Render templates asynchronously
79
 * @param tpl - Array of parsed templates
80
 * @param scope - Data context for rendering
81
 * @param renderOptions - Rendering options
82
 * @returns Promise resolving to rendered output
83
 */
84
render(tpl: Template[], scope?: object, renderOptions?: RenderOptions): Promise<any>;
85

86
/**
87
 * Render templates synchronously
88
 * @param tpl - Array of parsed templates
89
 * @param scope - Data context for rendering
90
 * @param renderOptions - Rendering options
91
 * @returns Rendered output
92
 */
93
renderSync(tpl: Template[], scope?: object, renderOptions?: RenderOptions): any;
94

95
/**
96
 * Render templates to Node.js readable stream
97
 * @param tpl - Array of parsed templates
98
 * @param scope - Data context for rendering
99
 * @param renderOptions - Rendering options
100
 * @returns Node.js ReadableStream
101
 */
102
renderToNodeStream(tpl: Template[], scope?: object, renderOptions?: RenderOptions): NodeJS.ReadableStream;
103
```
104

105
**Usage Examples:**
106

107
```typescript
108
const templates = engine.parse("Hello {{ name | capitalize }}!");
109
const data = { name: "world" };
110

111
// Async rendering
112
const result = await engine.render(templates, data);
113
console.log(result); // "Hello World!"
114

115
// Sync rendering
116
const resultSync = engine.renderSync(templates, data);
117

118
// Stream rendering (Node.js only)
119
const stream = engine.renderToNodeStream(templates, data);
120
stream.pipe(process.stdout);
121
```
122

123
### Combined Parse and Render
124

125
Convenience methods that combine parsing and rendering in a single operation.
126

127
```typescript { .api }
128
/**
129
 * Parse and render template string asynchronously
130
 * @param html - Template string to parse and render
131
 * @param scope - Data context for rendering
132
 * @param renderOptions - Rendering options
133
 * @returns Promise resolving to rendered output
134
 */
135
parseAndRender(html: string, scope?: Context | object, renderOptions?: RenderOptions): Promise<any>;
136

137
/**
138
 * Parse and render template string synchronously
139
 * @param html - Template string to parse and render
140
 * @param scope - Data context for rendering
141
 * @param renderOptions - Rendering options
142
 * @returns Rendered output
143
 */
144
parseAndRenderSync(html: string, scope?: Context | object, renderOptions?: RenderOptions): any;
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
// One-step async parsing and rendering
151
const result = await engine.parseAndRender(
152
  "Hello {{ name }}!",
153
  { name: "Alice" }
154
);
155

156
// One-step sync parsing and rendering
157
const resultSync = engine.parseAndRenderSync(
158
  "{% for item in items %}{{ item }}{% endfor %}",
159
  { items: [1, 2, 3] }
160
);
161
```
162

163
### File Operations
164

165
Render templates directly from files with automatic parsing.
166

167
```typescript { .api }
168
/**
169
 * Render template file asynchronously
170
 * @param file - Path to template file
171
 * @param ctx - Data context for rendering
172
 * @param renderFileOptions - File rendering options
173
 * @returns Promise resolving to rendered output
174
 */
175
renderFile(file: string, ctx?: Context | object, renderFileOptions?: RenderFileOptions): Promise<any>;
176

177
/**
178
 * Render template file synchronously
179
 * @param file - Path to template file
180
 * @param ctx - Data context for rendering
181
 * @param renderFileOptions - File rendering options
182
 * @returns Rendered output
183
 */
184
renderFileSync(file: string, ctx?: Context | object, renderFileOptions?: RenderFileOptions): any;
185

186
/**
187
 * Render template file to Node.js readable stream
188
 * @param file - Path to template file
189
 * @param scope - Data context for rendering
190
 * @param renderOptions - Rendering options
191
 * @returns Promise resolving to Node.js ReadableStream
192
 */
193
renderFileToNodeStream(file: string, scope?: object, renderOptions?: RenderOptions): Promise<NodeJS.ReadableStream>;
194
```
195

196
**Usage Examples:**
197

198
```typescript
199
// Render file with data
200
const html = await engine.renderFile("template.liquid", {
201
  title: "My Page",
202
  users: [{ name: "Alice" }, { name: "Bob" }]
203
});
204

205
// Render with lookup type
206
const partial = await engine.renderFile("header.liquid", data, {
207
  lookupType: "partials"
208
});
209

210
// Stream rendering from file (Node.js only)
211
const fileStream = await engine.renderFileToNodeStream("large-template.liquid", data);
212
fileStream.pipe(process.stdout);
213
```
214

215
### Value Evaluation
216

217
Evaluate Liquid expressions and variables outside of full template context.
218

219
```typescript { .api }
220
/**
221
 * Evaluate Liquid expression asynchronously
222
 * @param str - Expression string to evaluate
223
 * @param scope - Data context for evaluation
224
 * @returns Promise resolving to evaluated value
225
 */
226
evalValue(str: string, scope?: object | Context): Promise<any>;
227

228
/**
229
 * Evaluate Liquid expression synchronously
230
 * @param str - Expression string to evaluate
231
 * @param scope - Data context for evaluation
232
 * @returns Evaluated value
233
 */
234
evalValueSync(str: string, scope?: object | Context): any;
235
```
236

237
**Usage Examples:**
238

239
```typescript
240
const data = { user: { name: "Alice", age: 25 } };
241

242
// Evaluate simple expressions
243
const name = await engine.evalValue("user.name", data);
244
// Result: "Alice"
245

246
const greeting = await engine.evalValue("user.name | prepend: 'Hello, '", data);
247
// Result: "Hello, Alice"
248

249
// Sync evaluation
250
const age = engine.evalValueSync("user.age", data);
251
// Result: 25
252
```
253

254
### Express.js Integration
255

256
Built-in support for Express.js template engine integration.
257

258
```typescript { .api }
259
/**
260
 * Create Express.js template engine function
261
 * @returns Express-compatible template engine function
262
 */
263
express(): (filePath: string, ctx: object, callback: (err: Error | null, rendered: string) => void) => void;
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
import express from "express";
270
import { Liquid } from "liquidjs";
271

272
const app = express();
273
const engine = new Liquid();
274

275
// Register as Express template engine
276
app.engine("liquid", engine.express());
277
app.set("view engine", "liquid");
278

279
// Use in routes
280
app.get("/", (req, res) => {
281
  res.render("index", { title: "Home", user: req.user });
282
});
283
```
284

285
## Types
286

287
### Core Engine Types
288

289
```typescript { .api }
290
interface Template {
291
  token: Token;
292
  render(ctx: Context, emitter: Emitter): any;
293
  children?(partials: boolean, sync: boolean): Generator<unknown, Template[]>;
294
  arguments?(): Arguments;
295
  blockScope?(): Iterable<string>;
296
  localScope?(): Iterable<IdentifierToken | QuotedToken>;
297
  partialScope?(): PartialScope | undefined;
298
}
299

300
interface RenderOptions {
301
  sync?: boolean;
302
  globals?: object;
303
  strictVariables?: boolean;
304
  ownPropertyOnly?: boolean;
305
  templateLimit?: number;
306
  renderLimit?: number;
307
  memoryLimit?: number;
308
}
309

310
interface RenderFileOptions extends RenderOptions {
311
  lookupType?: LookupType;
312
}
313

314
enum LookupType {
315
  Root = 'fs',
316
  Partials = 'partials',
317
  Layouts = 'layouts'
318
}
319
```
320

321
### Engine Properties
322

323
```typescript { .api }
324
interface NormalizedFullOptions {
325
  // File system configuration
326
  root: string[];
327
  partials: string[];
328
  layouts: string[];
329
  fs: FS;
330
  
331
  // Template processing
332
  strictFilters: boolean;
333
  strictVariables: boolean;
334
  dynamicPartials: boolean;
335
  
336
  // Performance limits
337
  parseLimit: number;
338
  renderLimit: number;
339
  memoryLimit: number;
340
  
341
  // Additional options...
342
}
343
```