0
# Data Manipulation
1

2
Functions for transforming, filtering, and manipulating arrays and objects.
3

4
## Capabilities
5

6
### Array Transformation
7

8
#### Map Function
9

10
Applies a function to each element in an array, returning a new array.
11

12
```javascript { .api }
13
/**
14
 * Apply function to each element in array
15
 * @param array - Input array
16
 * @param function - Function to apply to each element
17
 * @returns New array with transformed elements
18
 */
19
function $map(array, function);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// Transform array of numbers
26
const data = { numbers: [1, 2, 3, 4] };
27
const doubled = await jsonata('$map(numbers, function($item) { $item * 2 })').evaluate(data); // [2, 4, 6, 8]
28

29
// Transform objects
30
const users = { 
31
  users: [
32
    { name: "Alice", age: 30 },
33
    { name: "Bob", age: 25 }
34
  ]
35
};
36
const names = await jsonata('$map(users, function($user) { $user.name })').evaluate(users); // ["Alice", "Bob"]
37

38
// Using lambda syntax
39
const prices = { items: [{ price: 10 }, { price: 20 }] };
40
const withTax = await jsonata('$map(items, λ($item) { {"price": $item.price * 1.1} })').evaluate(prices);
41
```
42

43
#### Filter Function
44

45
Filters array elements based on a predicate function.
46

47
```javascript { .api }
48
/**
49
 * Filter array elements using predicate function
50
 * @param array - Input array
51
 * @param function - Predicate function returning boolean
52
 * @returns Array containing only elements that pass the predicate
53
 */
54
function $filter(array, function);
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
// Filter numbers
61
const data = { numbers: [1, 2, 3, 4, 5, 6] };
62
const evens = await jsonata('$filter(numbers, function($n) { $n % 2 = 0 })').evaluate(data); // [2, 4, 6]
63

64
// Filter objects
65
const products = {
66
  products: [
67
    { name: "Laptop", price: 1000, inStock: true },
68
    { name: "Mouse", price: 25, inStock: false },
69
    { name: "Keyboard", price: 75, inStock: true }
70
  ]
71
};
72
const available = await jsonata('$filter(products, function($p) { $p.inStock })').evaluate(products);
73
// [{ name: "Laptop", price: 1000, inStock: true }, { name: "Keyboard", price: 75, inStock: true }]
74

75
// Filter with multiple conditions
76
const expensive = await jsonata('$filter(products, function($p) { $p.price > 50 and $p.inStock })').evaluate(products);
77
```
78

79
#### Zip Function
80

81
Combines multiple arrays element-wise into a single array.
82

83
```javascript { .api }
84
/**
85
 * Combine multiple arrays element-wise
86
 * @param arrays - Multiple arrays to combine
87
 * @returns Array of arrays, each containing elements from the same position
88
 */
89
function $zip(...arrays);
90
```
91

92
**Usage Examples:**
93

94
```javascript
95
const data = {
96
  names: ["Alice", "Bob", "Charlie"],
97
  ages: [30, 25, 35],
98
  cities: ["New York", "London", "Tokyo"]
99
};
100

101
const combined = await jsonata('$zip(names, ages, cities)').evaluate(data);
102
// [["Alice", 30, "New York"], ["Bob", 25, "London"], ["Charlie", 35, "Tokyo"]]
103

104
// Create objects from zipped arrays
105
const objects = await jsonata('$map($zip(names, ages), function($pair) { {"name": $pair[0], "age": $pair[1]} })').evaluate(data);
106
// [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]
107
```
108

109
### Array Manipulation
110

111
#### Append Function
112

113
Appends arrays or values together.
114

115
```javascript { .api }
116
/**
117
 * Append arrays or values
118
 * @param arg1 - First array or value
119
 * @param arg2 - Second array or value to append
120
 * @returns Combined array
121
 */
122
function $append(arg1, arg2);
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
const data = { 
129
  fruits: ["apple", "banana"],
130
  vegetables: ["carrot", "lettuce"]
131
};
132
const combined = await jsonata('$append(fruits, vegetables)').evaluate(data); 
133
// ["apple", "banana", "carrot", "lettuce"]
134

135
// Append single value
136
const withExtra = await jsonata('$append(fruits, "orange")').evaluate(data);
137
// ["apple", "banana", "orange"]
138

139
// Chain multiple appends
140
const all = await jsonata('$append($append(fruits, vegetables), ["bread", "milk"])').evaluate(data);
141
```
142

143
#### Reverse Function
144

145
Reverses the order of elements in an array.
146

147
```javascript { .api }
148
/**
149
 * Reverse array elements
150
 * @param arr - Array to reverse
151
 * @returns New array with elements in reverse order
152
 */
153
function $reverse(arr);
154
```
155

156
**Usage Examples:**
157

158
```javascript
159
const data = { items: [1, 2, 3, 4, 5] };
160
const reversed = await jsonata('$reverse(items)').evaluate(data); // [5, 4, 3, 2, 1]
161

162
// Reverse and process
163
const names = { list: ["Alice", "Bob", "Charlie"] };
164
const lastFirst = await jsonata('$reverse(list)[0]').evaluate(names); // "Charlie"
165
```
166

167
#### Sort Function
168

169
Sorts array elements using an optional comparison function.
170

171
```javascript { .api }
172
/**
173
 * Sort array elements
174
 * @param arr - Array to sort
175
 * @param function - Optional comparison function
176
 * @returns New sorted array
177
 */
178
function $sort(arr, function);
179
```
180

181
**Usage Examples:**
182

183
```javascript
184
// Sort numbers (default ascending)
185
const numbers = { values: [3, 1, 4, 1, 5, 9] };
186
const sorted = await jsonata('$sort(values)').evaluate(numbers); // [1, 1, 3, 4, 5, 9]
187

188
// Sort strings
189
const names = { list: ["Charlie", "Alice", "Bob"] };
190
const alphabetical = await jsonata('$sort(list)').evaluate(names); // ["Alice", "Bob", "Charlie"]
191

192
// Sort with custom function
193
const people = {
194
  people: [
195
    { name: "Alice", age: 30 },
196
    { name: "Charlie", age: 25 },
197
    { name: "Bob", age: 35 }
198
  ]
199
};
200
const byAge = await jsonata('$sort(people, function($a, $b) { $a.age < $b.age })').evaluate(people);
201
// Sorted by age ascending
202

203
// Sort by multiple criteria
204
const byNameThenAge = await jsonata('$sort(people, function($a, $b) { $a.name < $b.name ? true : $a.name > $b.name ? false : $a.age < $b.age })').evaluate(people);
205
```
206

207
#### Shuffle Function
208

209
Randomly shuffles array elements.
210

211
```javascript { .api }
212
/**
213
 * Randomly shuffle array elements
214
 * @param arr - Array to shuffle
215
 * @returns New array with elements in random order
216
 */
217
function $shuffle(arr);
218
```
219

220
#### Distinct Function
221

222
Returns array with duplicate elements removed.
223

224
```javascript { .api }
225
/**
226
 * Remove duplicate elements from array
227
 * @param arr - Array to process
228
 * @returns New array with unique elements only
229
 */
230
function $distinct(arr);
231
```
232

233
**Usage Examples:**
234

235
```javascript
236
const data = { values: [1, 2, 2, 3, 3, 3, 4] };
237
const unique = await jsonata('$distinct(values)').evaluate(data); // [1, 2, 3, 4]
238

239
// Remove duplicate objects (by reference)
240
const items = {
241
  list: [
242
    { id: 1, name: "Apple" },
243
    { id: 2, name: "Banana" },
244
    { id: 1, name: "Apple" }
245
  ]
246
};
247
// Note: Objects are compared by deep equality
248
const distinctItems = await jsonata('$distinct(list)').evaluate(items);
249
```
250

251
### Advanced Array Operations
252

253
#### Single Function
254

255
Returns a single element from an array, with optional filtering.
256

257
```javascript { .api }
258
/**
259
 * Return single element from array
260
 * @param array - Input array
261
 * @param function - Optional filter function
262
 * @returns Single element, throws error if multiple or zero results
263
 */
264
function $single(array, function);
265
```
266

267
**Usage Examples:**
268

269
```javascript
270
// Get single element (throws if not exactly one)
271
const data = { users: [{ name: "Alice", id: 1 }] };
272
const user = await jsonata('$single(users)').evaluate(data); // { name: "Alice", id: 1 }
273

274
// Get single matching element
275
const people = {
276
  people: [
277
    { name: "Alice", id: 1 },
278
    { name: "Bob", id: 2 },
279
    { name: "Charlie", id: 3 }
280
  ]
281
};
282
const alice = await jsonata('$single(people, function($p) { $p.name = "Alice" })').evaluate(people);
283
```
284

285
#### Fold Left Function
286

287
Reduces array from left using an accumulator function.
288

289
```javascript { .api }
290
/**
291
 * Reduce array from left with accumulator function
292
 * @param array - Input array
293
 * @param function - Reducer function taking (accumulator, current, index, array)
294
 * @param init - Initial accumulator value
295
 * @returns Final accumulated result
296
 */
297
function $foldLeft(array, function, init);
298
```
299

300
**Usage Examples:**
301

302
```javascript
303
// Sum with fold
304
const numbers = { values: [1, 2, 3, 4, 5] };
305
const sum = await jsonata('$foldLeft(values, function($acc, $val) { $acc + $val }, 0)').evaluate(numbers); // 15
306

307
// Build object from array
308
const items = { list: ["apple", "banana", "cherry"] };
309
const indexed = await jsonata('$foldLeft(list, function($acc, $val, $index) { $merge([$acc, {$string($index): $val}]) }, {})').evaluate(items);
310
// { "0": "apple", "1": "banana", "2": "cherry" }
311

312
// Find maximum with fold
313
const data = { values: [3, 7, 2, 9, 1] };
314
const max = await jsonata('$foldLeft(values, function($max, $val) { $val > $max ? $val : $max }, 0)').evaluate(data); // 9
315
```
316

317
### Object Operations
318

319
#### Keys Function
320

321
Returns an array of object keys.
322

323
```javascript { .api }
324
/**
325
 * Get object keys as array
326
 * @param arg - Object to get keys from
327
 * @returns Array of key strings
328
 */
329
function $keys(arg);
330
```
331

332
**Usage Examples:**
333

334
```javascript
335
const user = { name: "Alice", age: 30, city: "New York" };
336
const keys = await jsonata('$keys($)').evaluate(user); // ["name", "age", "city"]
337

338
// Process each key-value pair
339
const obj = { a: 1, b: 2, c: 3 };
340
const pairs = await jsonata('$keys($).{"key": $, "value": $lookup($, $)}').evaluate(obj);
341
// [{"key": "a", "value": 1}, {"key": "b", "value": 2}, {"key": "c", "value": 3}]
342
```
343

344
#### Lookup Function
345

346
Looks up a value by key in an object.
347

348
```javascript { .api }
349
/**
350
 * Look up value by key in object
351
 * @param input - Object to search in
352
 * @param key - Key to look up
353
 * @returns Value associated with the key
354
 */
355
function $lookup(input, key);
356
```
357

358
**Usage Examples:**
359

360
```javascript
361
const data = { name: "Alice", age: 30 };
362
const name = await jsonata('$lookup($, "name")').evaluate(data); // "Alice"
363

364
// Dynamic key lookup
365
const config = { 
366
  settings: { theme: "dark", lang: "en" },
367
  currentSetting: "theme"
368
};
369
const value = await jsonata('$lookup(settings, currentSetting)').evaluate(config); // "dark"
370
```
371

372
#### Spread Function
373

374
Spreads an object into key-value pairs.
375

376
```javascript { .api }
377
/**
378
 * Spread object into key-value pairs
379
 * @param arg - Object to spread
380
 * @returns Array of objects with "name" and "value" properties
381
 */
382
function $spread(arg);
383
```
384

385
**Usage Examples:**
386

387
```javascript
388
const user = { name: "Alice", age: 30, city: "New York" };
389
const pairs = await jsonata('$spread($)').evaluate(user);
390
// [{"name": "name", "value": "Alice"}, {"name": "age", "value": 30}, {"name": "city", "value": "New York"}]
391

392
// Transform spread data
393
const transformed = await jsonata('$spread($).{"key": name, "val": $string(value)}').evaluate(user);
394
```
395

396
#### Merge Function
397

398
Merges an array of objects into a single object.
399

400
```javascript { .api }
401
/**
402
 * Merge array of objects into single object
403
 * @param arg - Array of objects to merge
404
 * @returns Single merged object
405
 */
406
function $merge(arg);
407
```
408

409
**Usage Examples:**
410

411
```javascript
412
const data = {
413
  objects: [
414
    { a: 1, b: 2 },
415
    { c: 3, d: 4 },
416
    { a: 10, e: 5 }  // 'a' will be overwritten
417
  ]
418
};
419
const merged = await jsonata('$merge(objects)').evaluate(data); // { a: 10, b: 2, c: 3, d: 4, e: 5 }
420

421
// Merge configuration objects
422
const config = {
423
  defaults: { theme: "light", timeout: 5000 },
424
  user: { theme: "dark" },
425
  runtime: { debug: true }
426
};
427
const final = await jsonata('$merge([defaults, user, runtime])').evaluate(config);
428
// { theme: "dark", timeout: 5000, debug: true }
429
```
430

431
#### Sift Function
432

433
Filters object properties using a predicate function.
434

435
```javascript { .api }
436
/**
437
 * Filter object properties using predicate function
438
 * @param arg - Object to filter
439
 * @param func - Predicate function receiving (value, key, object)
440
 * @returns New object with filtered properties
441
 */
442
function $sift(arg, func);
443
```
444

445
**Usage Examples:**
446

447
```javascript
448
// Filter by value
449
const data = { a: 1, b: 2, c: 3, d: 4, e: 5 };
450
const filtered = await jsonata('$sift($, function($value) { $value > 2 })').evaluate(data); // { c: 3, d: 4, e: 5 }
451

452
// Filter by key pattern
453
const config = {
454
  user_name: "Alice",
455
  user_age: 30,
456
  system_version: "1.0",
457
  system_debug: true
458
};
459
const userSettings = await jsonata('$sift($, function($value, $key) { $contains($key, "user_") })').evaluate(config);
460
// { user_name: "Alice", user_age: 30 }
461
```
462

463
#### Each Function
464

465
Applies a function to each property in an object.
466

467
```javascript { .api }
468
/**
469
 * Apply function to each property in object
470
 * @param object - Object to iterate over
471
 * @param function - Function to apply to each property
472
 * @returns Array of results from function applications
473
 */
474
function $each(object, function);
475
```
476

477
**Usage Examples:**
478

479
```javascript
480
const user = { name: "Alice", age: 30, city: "New York" };
481
const descriptions = await jsonata('$each($, function($value, $key) { $key & ": " & $string($value) })').evaluate(user);
482
// ["name: Alice", "age: 30", "city: New York"]
483

484
// Process nested objects
485
const data = {
486
  users: {
487
    alice: { age: 30, role: "admin" },
488
    bob: { age: 25, role: "user" }
489
  }
490
};
491
const summaries = await jsonata('$each(users, function($user, $name) { $name & " (" & $user.role & ")" })').evaluate(data);
492
// ["alice (admin)", "bob (user)"]
493
```