0
# Built-in Filters
1

2
LiquidJS provides over 80 built-in filters for data transformation, organized into categories for array manipulation, string processing, mathematical operations, date formatting, HTML processing, and URL handling.
3

4
## Capabilities
5

6
### Array Filters
7

8
Filters for manipulating arrays and collections.
9

10
```typescript { .api }
11
/**
12
 * Join array elements with separator
13
 * @param array - Array to join
14
 * @param separator - Separator string (default: ' ')
15
 * @returns Joined string
16
 */
17
join(array: any[], separator?: string): string;
18

19
/**
20
 * Get first element of array
21
 * @param array - Input array
22
 * @returns First element or empty string
23
 */
24
first(array: any[]): any;
25

26
/**
27
 * Get last element of array
28
 * @param array - Input array
29
 * @returns Last element or empty string
30
 */
31
last(array: any[]): any;
32

33
/**
34
 * Reverse array elements
35
 * @param array - Input array
36
 * @returns New reversed array
37
 */
38
reverse(array: any[]): any[];
39

40
/**
41
 * Get array size/length
42
 * @param array - Input array or string
43
 * @returns Length as number
44
 */
45
size(array: any[] | string): number;
46

47
/**
48
 * Sort array by property
49
 * @param array - Input array
50
 * @param property - Property name to sort by (optional)
51
 * @returns Sorted array
52
 */
53
sort(array: any[], property?: string): any[];
54

55
/**
56
 * Case-insensitive natural sort
57
 * @param array - Input array
58
 * @param property - Property name to sort by (optional)
59
 * @returns Naturally sorted array
60
 */
61
sort_natural(array: any[], property?: string): any[];
62

63
/**
64
 * Filter array by property value
65
 * @param array - Input array
66
 * @param property - Property name to filter by
67
 * @param value - Value to match (optional)
68
 * @returns Filtered array
69
 */
70
where(array: any[], property: string, value?: any): any[];
71

72
/**
73
 * Extract property values from array
74
 * @param array - Input array
75
 * @param property - Property name to extract
76
 * @returns Array of property values
77
 */
78
map(array: any[], property: string): any[];
79

80
/**
81
 * Remove duplicate elements
82
 * @param array - Input array
83
 * @returns Array with unique elements
84
 */
85
uniq(array: any[]): any[];
86

87
/**
88
 * Flatten nested arrays
89
 * @param array - Input array
90
 * @returns Flattened array
91
 */
92
flatten(array: any[]): any[];
93

94
/**
95
 * Get array slice
96
 * @param array - Input array
97
 * @param start - Start index
98
 * @param length - Number of elements (optional)
99
 * @returns Array slice
100
 */
101
slice(array: any[], start: number, length?: number): any[];
102

103
/**
104
 * Concatenate arrays
105
 * @param array1 - First array
106
 * @param array2 - Second array
107
 * @returns Concatenated array
108
 */
109
concat(array1: any[], array2: any[]): any[];
110

111
/**
112
 * Get array element at index
113
 * @param array - Input array
114
 * @param index - Index to access
115
 * @returns Element at index
116
 */
117
at(array: any[], index: number): any;
118
```
119

120
### String Filters
121

122
Filters for string manipulation and formatting.
123

124
```typescript { .api }
125
/**
126
 * Append string to end
127
 * @param str - Input string
128
 * @param suffix - String to append
129
 * @returns Concatenated string
130
 */
131
append(str: string, suffix: string): string;
132

133
/**
134
 * Prepend string to beginning
135
 * @param str - Input string
136
 * @param prefix - String to prepend
137
 * @returns Concatenated string
138
 */
139
prepend(str: string, prefix: string): string;
140

141
/**
142
 * Capitalize first letter
143
 * @param str - Input string
144
 * @returns Capitalized string
145
 */
146
capitalize(str: string): string;
147

148
/**
149
 * Convert to lowercase
150
 * @param str - Input string
151
 * @returns Lowercase string
152
 */
153
downcase(str: string): string;
154

155
/**
156
 * Convert to uppercase
157
 * @param str - Input string
158
 * @returns Uppercase string
159
 */
160
upcase(str: string): string;
161

162
/**
163
 * Replace occurrences
164
 * @param str - Input string
165
 * @param search - String to find
166
 * @param replacement - Replacement string
167
 * @returns String with replacements
168
 */
169
replace(str: string, search: string, replacement: string): string;
170

171
/**
172
 * Replace first occurrence
173
 * @param str - Input string
174
 * @param search - String to find
175
 * @param replacement - Replacement string
176
 * @returns String with first replacement
177
 */
178
replace_first(str: string, search: string, replacement: string): string;
179

180
/**
181
 * Remove occurrences
182
 * @param str - Input string
183
 * @param search - String to remove
184
 * @returns String with removals
185
 */
186
remove(str: string, search: string): string;
187

188
/**
189
 * Remove first occurrence
190
 * @param str - Input string
191
 * @param search - String to remove
192
 * @returns String with first removal
193
 */
194
remove_first(str: string, search: string): string;
195

196
/**
197
 * Truncate string with ellipsis
198
 * @param str - Input string
199
 * @param length - Maximum length
200
 * @param ellipsis - Ellipsis string (default: '...')
201
 * @returns Truncated string
202
 */
203
truncate(str: string, length: number, ellipsis?: string): string;
204

205
/**
206
 * Truncate by word boundary
207
 * @param str - Input string
208
 * @param length - Maximum length
209
 * @param ellipsis - Ellipsis string (default: '...')
210
 * @returns Truncated string
211
 */
212
truncatewords(str: string, length: number, ellipsis?: string): string;
213

214
/**
215
 * Split string into array
216
 * @param str - Input string
217
 * @param delimiter - Split delimiter
218
 * @returns Array of substrings
219
 */
220
split(str: string, delimiter: string): string[];
221

222
/**
223
 * Strip whitespace from both ends
224
 * @param str - Input string
225
 * @param chars - Characters to strip (optional)
226
 * @returns Trimmed string
227
 */
228
strip(str: string, chars?: string): string;
229

230
/**
231
 * Strip whitespace from left
232
 * @param str - Input string
233
 * @param chars - Characters to strip (optional)
234
 * @returns Left-trimmed string
235
 */
236
lstrip(str: string, chars?: string): string;
237

238
/**
239
 * Strip whitespace from right
240
 * @param str - Input string
241
 * @param chars - Characters to strip (optional)
242
 * @returns Right-trimmed string
243
 */
244
rstrip(str: string, chars?: string): string;
245
```
246

247
### Math Filters
248

249
Filters for mathematical operations and number formatting.
250

251
```typescript { .api }
252
/**
253
 * Absolute value
254
 * @param num - Input number
255
 * @returns Absolute value
256
 */
257
abs(num: number): number;
258

259
/**
260
 * Addition
261
 * @param num - Input number
262
 * @param operand - Number to add
263
 * @returns Sum
264
 */
265
plus(num: number, operand: number): number;
266

267
/**
268
 * Subtraction
269
 * @param num - Input number
270
 * @param operand - Number to subtract
271
 * @returns Difference
272
 */
273
minus(num: number, operand: number): number;
274

275
/**
276
 * Multiplication
277
 * @param num - Input number
278
 * @param operand - Number to multiply by
279
 * @returns Product
280
 */
281
times(num: number, operand: number): number;
282

283
/**
284
 * Division
285
 * @param num - Input number
286
 * @param operand - Number to divide by
287
 * @returns Quotient
288
 */
289
divided_by(num: number, operand: number): number;
290

291
/**
292
 * Modulo operation
293
 * @param num - Input number
294
 * @param operand - Modulo operand
295
 * @returns Remainder
296
 */
297
modulo(num: number, operand: number): number;
298

299
/**
300
 * Round to nearest integer
301
 * @param num - Input number
302
 * @param precision - Decimal places (optional)
303
 * @returns Rounded number
304
 */
305
round(num: number, precision?: number): number;
306

307
/**
308
 * Round down (floor)
309
 * @param num - Input number
310
 * @returns Floor value
311
 */
312
floor(num: number): number;
313

314
/**
315
 * Round up (ceiling)
316
 * @param num - Input number
317
 * @returns Ceiling value
318
 */
319
ceil(num: number): number;
320
```
321

322
### Date Filters
323

324
Filters for date formatting and manipulation.
325

326
```typescript { .api }
327
/**
328
 * Format date according to format string
329
 * @param date - Input date
330
 * @param format - Date format string
331
 * @returns Formatted date string
332
 */
333
date(date: Date | string | number, format?: string): string;
334

335
/**
336
 * Convert date to XML Schema format
337
 * @param date - Input date
338
 * @returns ISO 8601 date string
339
 */
340
date_to_xmlschema(date: Date | string | number): string;
341

342
/**
343
 * Convert date to RFC 822 format
344
 * @param date - Input date
345
 * @returns RFC 822 date string
346
 */
347
date_to_rfc822(date: Date | string | number): string;
348

349
/**
350
 * Convert date to string representation
351
 * @param date - Input date
352
 * @returns Date string
353
 */
354
date_to_string(date: Date | string | number): string;
355

356
/**
357
 * Convert date to long string
358
 * @param date - Input date
359
 * @returns Long date string
360
 */
361
date_to_long_string(date: Date | string | number): string;
362
```
363

364
### HTML Filters
365

366
Filters for HTML processing and escaping.
367

368
```typescript { .api }
369
/**
370
 * Escape HTML entities
371
 * @param str - Input string
372
 * @returns HTML-escaped string
373
 */
374
escape(str: string): string;
375

376
/**
377
 * Escape for single quotes
378
 * @param str - Input string
379
 * @returns Escaped string
380
 */
381
escape_once(str: string): string;
382

383
/**
384
 * Remove HTML tags
385
 * @param str - Input HTML string
386
 * @returns Plain text string
387
 */
388
strip_html(str: string): string;
389

390
/**
391
 * Strip newlines
392
 * @param str - Input string
393
 * @returns String without newlines
394
 */
395
strip_newlines(str: string): string;
396

397
/**
398
 * Convert newlines to <br> tags
399
 * @param str - Input string
400
 * @returns String with <br> tags
401
 */
402
newline_to_br(str: string): string;
403
```
404

405
### URL Filters
406

407
Filters for URL encoding and manipulation.
408

409
```typescript { .api }
410
/**
411
 * URL encode string
412
 * @param str - Input string
413
 * @returns URL-encoded string
414
 */
415
url_encode(str: string): string;
416

417
/**
418
 * URL decode string
419
 * @param str - Input URL-encoded string
420
 * @returns Decoded string
421
 */
422
url_decode(str: string): string;
423

424
/**
425
 * Create URL slug
426
 * @param str - Input string
427
 * @returns URL-friendly slug
428
 */
429
slugify(str: string): string;
430

431
/**
432
 * Base64 encode
433
 * @param str - Input string
434
 * @returns Base64-encoded string
435
 */
436
base64_encode(str: string): string;
437

438
/**
439
 * Base64 decode
440
 * @param str - Base64-encoded string
441
 * @returns Decoded string
442
 */
443
base64_decode(str: string): string;
444
```
445

446
### Miscellaneous Filters
447

448
General utility filters for common operations.
449

450
```typescript { .api }
451
/**
452
 * Provide default value for falsy inputs
453
 * @param value - Input value
454
 * @param defaultValue - Default to use if input is falsy
455
 * @returns Input value or default
456
 */
457
default(value: any, defaultValue: any): any;
458

459
/**
460
 * Convert to JSON string
461
 * @param value - Input value
462
 * @returns JSON string representation
463
 */
464
json(value: any): string;
465

466
/**
467
 * Output raw unescaped value
468
 * @param value - Input value
469
 * @returns Raw unescaped value
470
 */
471
raw(value: any): any;
472

473
/**
474
 * Inspect value for debugging
475
 * @param value - Input value
476
 * @returns String representation for debugging
477
 */
478
inspect(value: any): string;
479
```
480

481
## Usage Examples
482

483
### Array Operations
484

485
```typescript
486
const engine = new Liquid();
487

488
// Join array elements
489
const result1 = await engine.parseAndRender(
490
  "{{ tags | join: ', ' }}",
491
  { tags: ["red", "blue", "green"] }
492
);
493
// Result: "red, blue, green"
494

495
// Filter and sort
496
const result2 = await engine.parseAndRender(`
497
  {% assign active_users = users | where: 'active', true | sort: 'name' %}
498
  {% for user in active_users %}{{ user.name }}{% endfor %}
499
`, {
500
  users: [
501
    { name: "Bob", active: true },
502
    { name: "Alice", active: true },
503
    { name: "Charlie", active: false }
504
  ]
505
});
506
```
507

508
### String Transformations
509

510
```typescript
511
// String manipulation
512
const result = await engine.parseAndRender(
513
  "{{ title | capitalize | append: ' - ' | append: site_name }}",
514
  { title: "hello world", site_name: "My Site" }
515
);
516
// Result: "Hello world - My Site"
517

518
// Text processing
519
const processed = await engine.parseAndRender(
520
  "{{ content | strip_html | truncatewords: 20 }}",
521
  { content: "<p>This is a <strong>long</strong> HTML content...</p>" }
522
);
523
```
524

525
### Mathematical Operations
526

527
```typescript
528
// Math calculations
529
const calculation = await engine.parseAndRender(
530
  "{{ price | times: quantity | plus: tax | round: 2 }}",
531
  { price: 19.99, quantity: 3, tax: 5.50 }
532
);
533
// Result: "65.47"
534
```