0
# Expression System
1

2
Powerful expression evaluation system with mathematical operations, data manipulation, secure code execution in sandboxed environments, and comprehensive data type extensions.
3

4
## Capabilities
5

6
### Expression Class
7

8
Core expression evaluation engine with parameter resolution and context-aware data access.
9

10
```typescript { .api }
11
/**
12
 * Expression evaluation engine
13
 */
14
class Expression {
15
  workflow?: Workflow;
16
  
17
  constructor(expression: string, workflow?: Workflow);
18

19
  /**
20
   * Resolve a simple parameter value with context
21
   * @param value - The value/expression to resolve
22
   * @param siblingParameters - Parameters from the same node
23
   * @param returnType - Expected return type
24
   * @returns Resolved value
25
   */
26
  resolveSimpleParameterValue(
27
    value: any,
28
    siblingParameters: IDataObject,
29
    returnType: string
30
  ): any;
31

32
  /**
33
   * Get parameter value with full execution context
34
   * @param parameterValue - Parameter value to resolve
35
   * @param runExecutionData - Current execution data
36
   * @param runIndex - Current run index
37
   * @param itemIndex - Current item index
38
   * @param node - Current node
39
   * @param connectionInputData - Input data from connections
40
   * @returns Resolved parameter value
41
   */
42
  getParameterValue(
43
    parameterValue: any,
44
    runExecutionData: IRunExecutionData | null,
45
    runIndex: number,
46
    itemIndex: number,
47
    node: INode,
48
    connectionInputData: INodeExecutionData[]
49
  ): any;
50
}
51
```
52

53
### Expression Functions
54

55
Core expression evaluation functions for different contexts and use cases.
56

57
```typescript { .api }
58
/**
59
 * Resolve expression in execution context
60
 * @param expression - Expression string to evaluate
61
 * @param data - Data context for evaluation
62
 * @param options - Evaluation options
63
 * @returns Resolved expression result
64
 */
65
function resolveExpression(
66
  expression: string,
67
  data: IDataObject,
68
  options?: IExpressionOptions
69
): any;
70

71
/**
72
 * Check if value contains expressions
73
 * @param value - Value to check
74
 * @returns Boolean indicating if value has expressions
75
 */
76
function isExpression(value: any): boolean;
77

78
/**
79
 * Execute code in sandboxed environment
80
 * @param code - JavaScript code to execute
81
 * @param context - Execution context
82
 * @param sandbox - Sandbox configuration
83
 * @returns Execution result
84
 */
85
function executeCode(
86
  code: string, 
87
  context: IDataObject,
88
  sandbox?: ISandboxOptions
89
): any;
90
```
91

92
### Expression Extensions
93

94
Data type extensions providing enhanced functionality for arrays, strings, numbers, dates, objects, and booleans.
95

96
```typescript { .api }
97
class ExpressionExtensions {
98
  static readonly functions: Record<string, Extension>;
99
  
100
  /**
101
   * Add custom extension function
102
   * @param name - Extension function name
103
   * @param extension - Extension implementation
104
   */
105
  static addExtension(name: string, extension: Extension): void;
106
}
107

108
interface Extension {
109
  doc: DocMetadata;
110
  transform: (value: any, ...args: any[]) => any;
111
}
112

113
interface DocMetadata {
114
  name: string;
115
  description: string;
116
  returnType?: string;
117
  args?: DocMetadataArgument[];
118
  examples?: DocMetadataExample[];
119
}
120

121
interface DocMetadataArgument {
122
  name: string;
123
  type?: string;
124
  description?: string;
125
  default?: any;
126
  optional?: boolean;
127
}
128
```
129

130
### Expression Parser
131

132
Expression syntax parsing and validation utilities.
133

134
```typescript { .api }
135
/**
136
 * Parse expression syntax and validate
137
 * @param expression - Expression string to parse
138
 * @returns Parsed expression AST
139
 */
140
function parseExpression(expression: string): ExpressionAST;
141

142
/**
143
 * Extract variables from expression
144
 * @param expression - Expression string
145
 * @returns Array of variable names used
146
 */
147
function extractVariables(expression: string): string[];
148

149
/**
150
 * Validate expression syntax
151
 * @param expression - Expression to validate
152
 * @returns Validation result with errors
153
 */
154
function validateExpression(expression: string): ValidationResult;
155

156
interface ExpressionAST {
157
  type: string;
158
  body: any[];
159
  sourceType?: string;
160
}
161
```
162

163
### Sandboxing and Security
164

165
Secure expression execution with configurable sandboxing options.
166

167
```typescript { .api }
168
interface ISandboxOptions {
169
  object?: Record<string, any>;
170
  timeout?: number;
171
  allowedBuiltins?: string[];
172
  blockedBuiltins?: string[];
173
}
174

175
/**
176
 * Create secure sandbox context
177
 * @param options - Sandbox configuration
178
 * @returns Sandbox context object
179
 */
180
function createSandbox(options: ISandboxOptions): ISandboxContext;
181

182
/**
183
 * Execute function in sandbox
184
 * @param fn - Function to execute
185
 * @param context - Sandbox context
186
 * @param timeout - Execution timeout
187
 * @returns Function result
188
 */
189
function executeSandboxed<T>(
190
  fn: () => T,
191
  context: ISandboxContext,
192
  timeout?: number
193
): Promise<T>;
194
```
195

196
### Data Type Extensions
197

198
Built-in extensions for different data types with comprehensive functionality.
199

200
```typescript { .api }
201
// Array Extensions
202
interface ArrayExtensions {
203
  chunk(size: number): any[][];
204
  compact(): any[];
205
  difference(values: any[]): any[];
206
  first(): any;
207
  last(): any;
208
  unique(): any[];
209
  flatten(): any[];
210
  isEmpty(): boolean;
211
  length(): number;
212
}
213

214
// String Extensions  
215
interface StringExtensions {
216
  contains(searchString: string): boolean;
217
  startsWith(searchString: string): boolean;
218
  endsWith(searchString: string): boolean;
219
  toTitleCase(): string;
220
  toSentenceCase(): string;
221
  stripTags(): string;
222
  urlEncode(): string;
223
  urlDecode(): string;
224
  hash(algorithm?: string): string;
225
}
226

227
// Number Extensions
228
interface NumberExtensions {
229
  abs(): number;
230
  ceil(): number;
231
  floor(): number;
232
  round(precision?: number): number;
233
  isNaN(): boolean;
234
  isFinite(): boolean;
235
  format(options?: NumberFormatOptions): string;
236
}
237

238
// Date Extensions
239
interface DateExtensions {
240
  format(format: string): string;
241
  toISOString(): string;
242
  beginningOf(unit: string): Date;
243
  endOf(unit: string): Date;
244
  plus(duration: any): Date;
245
  minus(duration: any): Date;
246
  diff(date: Date, unit?: string): number;
247
}
248
```
249

250
**Usage Examples:**
251

252
```typescript
253
import { Expression, resolveExpression, ExpressionExtensions } from "n8n-workflow";
254

255
// Basic expression evaluation
256
const expression = new Expression("{{ $json.firstName + ' ' + $json.lastName }}");
257
const result = expression.resolveSimpleParameterValue(
258
  "{{ $json.firstName + ' ' + $json.lastName }}",
259
  { firstName: "John", lastName: "Doe" },
260
  "string"
261
);
262
// Result: "John Doe"
263

264
// Using data type extensions
265
const arrayResult = resolveExpression(
266
  "{{ $json.items.unique().length() }}",
267
  { items: ["a", "b", "a", "c", "b"] }
268
);
269
// Result: 3
270

271
// String manipulation
272
const stringResult = resolveExpression(
273
  "{{ $json.email.contains('@gmail.com') }}",
274
  { email: "user@gmail.com" }
275
);
276
// Result: true
277

278
// Date formatting
279
const dateResult = resolveExpression(
280
  "{{ $json.createdAt.format('yyyy-MM-dd') }}",
281
  { createdAt: new Date("2023-12-25") }
282
);
283
// Result: "2023-12-25"
284

285
// Mathematical operations
286
const mathResult = resolveExpression(
287
  "{{ ($json.price * $json.quantity).round(2) }}",
288
  { price: 19.99, quantity: 3 }
289
);
290
// Result: 59.97
291

292
// Complex data transformation
293
const complexResult = resolveExpression(`
294
  {{ 
295
    $json.users
296
      .filter(user => user.active)
297
      .map(user => user.name.toTitleCase()) 
298
      .join(', ')
299
  }}`,
300
  {
301
    users: [
302
      { name: "john doe", active: true },
303
      { name: "jane smith", active: false },
304
      { name: "bob wilson", active: true }
305
    ]
306
  }
307
);
308
// Result: "John Doe, Bob Wilson"
309
```