0
# JSONata
1

2
JSONata is a lightweight query and transformation language for JSON data that provides a comprehensive solution for extracting, filtering, and transforming JSON documents using a functional programming approach. It offers an expressive syntax that combines path expressions, predicates, and built-in functions to enable complex data manipulations, aggregations, and restructuring operations without requiring external dependencies.
3

4
## Package Information
5

6
- **Package Name**: jsonata
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jsonata`
10

11
## Core Imports
12

13
```javascript
14
const jsonata = require("jsonata");
15
```
16

17
For ES modules:
18

19
```javascript
20
import jsonata from "jsonata";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const jsonata = require("jsonata");
27

28
const data = {
29
  example: [
30
    { value: 4 },
31
    { value: 7 },
32
    { value: 13 }
33
  ]
34
};
35

36
// Create and evaluate expression
37
const expression = jsonata("$sum(example.value)");
38
const result = await expression.evaluate(data); // returns 24
39

40
// Using bindings
41
const expr = jsonata("name & ' is ' & $string(age) & ' years old'");
42
const person = { name: "John", age: 30 };
43
const greeting = await expr.evaluate(person); // "John is 30 years old"
44
```
45

46
## Architecture
47

48
JSONata is built around several key components:
49

50
- **Expression Factory**: Main `jsonata()` function that parses expressions and returns evaluation objects
51
- **AST Parser**: Converts string expressions into abstract syntax trees for evaluation
52
- **Expression Evaluator**: Processes AST nodes against input data with environment bindings
53
- **Built-in Functions**: Comprehensive library of 60+ functions for data manipulation
54
- **Type System**: Handles JavaScript types with implicit conversions and type checking
55
- **Error Handling**: Detailed error reporting with position information and error codes
56

57
## Capabilities
58

59
### Expression Creation and Evaluation
60

61
Core functionality for creating and evaluating JSONata expressions against JSON data.
62

63
```javascript { .api }
64
/**
65
 * Create a JSONata expression object
66
 * @param expression - JSONata query expression string
67
 * @param options - Optional configuration
68
 * @returns Expression object with evaluation methods
69
 */
70
function jsonata(expression, options);
71

72
interface JsonataOptions {
73
  recover?: boolean;        // Attempt to recover on parse errors
74
  RegexEngine?: RegExp;     // Custom regex engine constructor
75
}
76
```
77

78
[Expression Management](./expressions.md)
79

80
### Numeric Operations
81

82
Functions for mathematical calculations, aggregations, and numeric transformations.
83

84
```javascript { .api }
85
// Aggregation functions
86
function $sum(array);
87
function $count(array);
88
function $max(array);
89
function $min(array);
90
function $average(array);
91

92
// Math functions  
93
function $abs(number);
94
function $floor(number);
95
function $ceil(number);
96
function $round(number, precision);
97
function $sqrt(number);
98
function $power(base, exponent);
99
function $random();
100
```
101

102
[Numeric Functions](./numeric-functions.md)
103

104
### String Processing
105

106
Comprehensive string manipulation, formatting, and transformation functions.
107

108
```javascript { .api }
109
// String operations
110
function $string(value, prettify);
111
function $substring(string, start, length);
112
function $substringBefore(string, chars);
113
function $substringAfter(string, chars);
114
function $lowercase(string);
115
function $uppercase(string);
116
function $length(string);
117
function $trim(string);
118
function $pad(string, width, char);
119

120
// String processing
121
function $split(string, separator, limit);
122
function $join(array, separator);
123
function $match(string, pattern, limit);
124
function $contains(string, pattern);
125
function $replace(string, pattern, replacement, limit);
126
```
127

128
[String Functions](./string-functions.md)
129

130
### Array and Object Manipulation
131

132
Functions for transforming, filtering, and manipulating arrays and objects.
133

134
```javascript { .api }
135
// Array operations
136
function $map(array, function);
137
function $filter(array, function);
138
function $zip(...arrays);
139
function $append(array1, array2);
140
function $reverse(array);
141
function $sort(array, function);
142
function $shuffle(array);
143
function $distinct(array);
144

145
// Object operations  
146
function $keys(object);
147
function $lookup(object, key);
148
function $spread(object);
149
function $merge(array);
150
function $sift(object, function);
151
function $each(object, function);
152
```
153

154
[Data Manipulation](./data-manipulation.md)
155

156
### Date and Time Processing
157

158
Functions for working with timestamps, date formatting, and time calculations.
159

160
```javascript { .api }
161
function $now(picture, timezone);
162
function $millis();
163
function $toMillis(timestamp, picture);
164
function $fromMillis(millis, picture, timezone);
165
function $formatInteger(number, picture);
166
function $parseInteger(string, picture);
167
```
168

169
[Date/Time Functions](./datetime-functions.md)
170

171
### Encoding and Utilities
172

173
Encoding functions, type checking, and utility operations.
174

175
```javascript { .api }
176
// Encoding functions
177
function $base64encode(string);
178
function $base64decode(string);
179
function $encodeUrlComponent(string);
180
function $encodeUrl(string);
181
function $decodeUrlComponent(string);
182
function $decodeUrl(string);
183

184
// Utility functions
185
function $type(value);
186
function $boolean(value);
187
function $not(value);
188
function $exists(value);
189
function $error(message);
190
function $assert(condition, message);
191
```
192

193
[Utility Functions](./utility-functions.md)
194

195
## Types
196

197
```javascript { .api }
198
// Expression object returned by jsonata()
199
interface Expression {
200
  evaluate(input: any, bindings?: Record<string, any>): Promise<any>;
201
  evaluate(input: any, bindings: Record<string, any> | undefined, callback: (err: JsonataError, resp: any) => void): void;
202
  assign(name: string, value: any): void;
203
  registerFunction(name: string, implementation: Function, signature?: string): void;
204
  ast(): ExprNode;
205
  errors(): any;
206
}
207

208
// Error object for JSONata runtime errors
209
interface JsonataError extends Error {
210
  code: string;
211
  position: number;
212
  token: string;
213
}
214

215
// Abstract syntax tree node
216
interface ExprNode {
217
  type: string;
218
  value?: any;
219
  position?: number;
220
  arguments?: ExprNode[];
221
  name?: string;
222
  procedure?: ExprNode;
223
  steps?: ExprNode[];
224
  expressions?: ExprNode[];
225
  stages?: ExprNode[];
226
  lhs?: ExprNode | ExprNode[];
227
  rhs?: ExprNode;
228
}
229

230
// Environment for variable bindings
231
interface Environment {
232
  bind(name: string | symbol, value: any): void;
233
  lookup(name: string | symbol): any;
234
  readonly timestamp: Date;
235
  readonly async: boolean;
236
}
237

238
// Execution context for functions
239
interface Focus {
240
  readonly environment: Environment;
241
  readonly input: any;
242
}
243
```