0
# n8n-workflow
1

2
n8n-workflow is the foundational TypeScript library that provides the core workflow execution engine for the n8n automation platform. It implements workflow data structures, node execution logic, expression evaluation, type validation, and data transformation utilities that enable the creation and execution of automated workflows.
3

4
## Package Information
5

6
- **Package Name**: n8n-workflow
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install n8n-workflow`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  Workflow, 
16
  Expression, 
17
  INode, 
18
  INodeExecutionData, 
19
  IExecuteFunctions,
20
  WorkflowDataProxy
21
} from "n8n-workflow";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  Workflow, 
29
  Expression, 
30
  INode, 
31
  INodeExecutionData, 
32
  IExecuteFunctions,
33
  WorkflowDataProxy 
34
} = require("n8n-workflow");
35
```
36

37
For common utilities and constants:
38

39
```typescript
40
import * as common from "n8n-workflow/common";
41
import { 
42
  getChildNodes, 
43
  getParentNodes,
44
  MANUAL_TRIGGER_NODE_TYPE,
45
  START_NODE_TYPE,
46
  LOG_LEVELS
47
} from "n8n-workflow";
48
```
49

50
For type guards and specialized modules:
51

52
```typescript
53
import { 
54
  isINodeProperties,
55
  isResourceMapperValue,
56
  LoggerProxy,
57
  NodeHelpers,
58
  ExpressionExtensions
59
} from "n8n-workflow";
60
```
61

62
## Basic Usage
63

64
```typescript
65
import { Workflow, Expression, INode, INodeExecutionData } from "n8n-workflow";
66

67
// Create a simple workflow
68
const nodes: INode[] = [
69
  {
70
    id: "start",
71
    name: "Start",
72
    type: "n8n-nodes-base.start",
73
    typeVersion: 1,
74
    position: [100, 200],
75
    parameters: {}
76
  }
77
];
78

79
const connections = {
80
  "Start": {
81
    "main": [
82
      [{ "node": "NextNode", "type": "main", "index": 0 }]
83
    ]
84
  }
85
};
86

87
const workflow = new Workflow({
88
  id: "workflow-1",
89
  name: "Example Workflow",
90
  nodes,
91
  connections,
92
  active: true,
93
  nodeTypes: {},
94
  staticData: {}
95
});
96

97
// Evaluate expressions
98
const expression = new Expression("{{ $json.name }}");
99
const result = expression.resolveSimpleParameterValue(
100
  "{{ $json.name }}", 
101
  { name: "John" }, 
102
  "string"
103
);
104
```
105

106
## Architecture
107

108
n8n-workflow is built around several key components:
109

110
- **Workflow Engine**: Core `Workflow` class managing node execution and data flow
111
- **Expression System**: Powerful expression evaluation with sandboxing and extensions
112
- **Data Proxy System**: Context-aware data access and parameter resolution
113
- **Type System**: Comprehensive TypeScript interfaces for workflow components
114
- **Node Execution**: Function contexts and helpers for node development
115
- **Validation Engine**: Runtime type validation and schema checking
116
- **Error Handling**: Comprehensive error classes for different failure scenarios
117

118
## Capabilities
119

120
### Workflow Management
121

122
Core workflow creation, execution, and management functionality including node orchestration and data flow control.
123

124
```typescript { .api }
125
class Workflow {
126
  constructor(parameters: IWorkflowBase);
127
  execute(mode: WorkflowExecuteMode, startNode?: string): Promise<IRunExecutionData>;
128
  getNode(nodeName: string): INode | null;
129
  getNodes(): INode[];
130
  getConnections(): IConnections;
131
}
132

133
interface IWorkflowBase {
134
  id?: string;
135
  name: string;
136
  nodes: INode[];
137
  connections: IConnections;
138
  active: boolean;
139
  nodeTypes: INodeTypes;
140
  staticData?: IDataObject;
141
  settings?: IWorkflowSettings;
142
}
143
```
144

145
[Workflow Management](./workflow-management.md)
146

147
### Expression Evaluation
148

149
Powerful expression evaluation system with mathematical operations, data manipulation, and secure code execution in sandboxed environments.
150

151
```typescript { .api }
152
class Expression {
153
  constructor(expression: string, workflow?: Workflow);
154
  resolveSimpleParameterValue(
155
    value: any,
156
    siblingParameters: IDataObject,
157
    returnType: string
158
  ): any;
159
  getParameterValue(
160
    parameterValue: any,
161
    runExecutionData: IRunExecutionData | null,
162
    runIndex: number,
163
    itemIndex: number,
164
    node: INode,
165
    connectionInputData: INodeExecutionData[]
166
  ): any;
167
}
168
```
169

170
[Expression System](./expression-system.md)
171

172
### Node Execution Context
173

174
Execution contexts and helper functions that provide nodes with access to workflow data, credentials, HTTP requests, and other runtime services.
175

176
```typescript { .api }
177
interface IExecuteFunctions {
178
  getContext(type: string): IContextObject;
179
  getCredentials(type: string): Promise<ICredentialDataDecryptedObject>;
180
  getInputData(inputIndex?: number): INodeExecutionData[];
181
  getNode(): INode;
182
  getWorkflow(): Workflow;
183
  helpers: {
184
    httpRequest(requestOptions: IHttpRequestOptions): Promise<any>;
185
    returnJsonArray(jsonData: IDataObject[]): INodeExecutionData[];
186
  };
187
}
188
```
189

190
[Node Execution](./node-execution.md)
191

192
### Data Proxy and Parameter Resolution
193

194
Advanced data proxy system for accessing workflow data, resolving parameters, and handling complex data transformations with full context awareness.
195

196
```typescript { .api }
197
class WorkflowDataProxy {
198
  static getDataProxy(
199
    workflow: Workflow,
200
    runExecutionData: IRunExecutionData,
201
    runIndex: number,
202
    itemIndex: number,
203
    node: INode,
204
    connectionInputData: INodeExecutionData[]
205
  ): IDataObject;
206
}
207
```
208

209
[Data Proxy System](./data-proxy.md)
210

211
### Type Validation
212

213
Comprehensive type validation system with runtime type checking and schema validation for ensuring data integrity.
214

215
```typescript { .api }
216
function validateFieldType(
217
  field: string,
218
  value: any,
219
  type: FieldType
220
): ValidationResult;
221

222
function validateParameterValue(
223
  value: any,
224
  parameterDefinition: INodeProperties
225
): ValidationResult;
226

227
function isValidType(value: any, expectedType: string): boolean;
228
```
229

230
[Type Validation](./type-validation.md)
231

232
### Error Handling
233

234
Structured error handling with specific error classes for different failure scenarios, including node errors, workflow errors, and expression errors.
235

236
```typescript { .api }
237
class NodeOperationError extends NodeError {
238
  constructor(node: INode, message: string, options?: ErrorOptions);
239
}
240

241
class WorkflowOperationError extends WorkflowError {
242
  constructor(message: string, options?: ErrorOptions);
243
}
244

245
class ExpressionError extends Error {
246
  constructor(message: string, options?: ExpressionErrorOptions);
247
}
248
```
249

250
[Error Handling](./error-handling.md)
251

252
### Utility Functions
253

254
Essential utility functions for object manipulation, async operations, data transformation, and common programming tasks.
255

256
```typescript { .api }
257
function deepCopy<T>(source: T): T;
258
function isObjectEmpty(obj: object): boolean;
259
function jsonParse(jsonString: string): any;
260
function sleep(ms: number): Promise<void>;
261
function randomString(length: number): string;
262
function updateDisplayOptions(
263
  displayOptions: IDisplayOptions,
264
  properties: INodeProperties[]
265
): IDisplayOptions;
266
```
267

268
[Utility Functions](./utilities.md)
269

270
### Graph Analysis
271

272
Graph analysis utilities for workflow structure analysis, node relationship mapping, and workflow optimization operations.
273

274
```typescript { .api }
275
function buildAdjacencyList(connections: IConnections): AdjacencyList;
276
function parseExtractableSubgraphSelection(
277
  selection: string
278
): ExtractableSubgraphData;
279

280
type AdjacencyList = Record<string, Array<{ node: string; type: string; index: number }>>;
281
```
282

283
[Graph Utilities](./graph-utilities.md)
284

285
### Extension System
286

287
Comprehensive extension system providing data type extensions, native method access, and expression parsing capabilities for enhanced functionality.
288

289
```typescript { .api }
290
class ExpressionExtensions {
291
  static readonly functions: Record<string, Extension>;
292
  static addExtension(name: string, extension: Extension): void;
293
}
294

295
interface Extension {
296
  doc: DocMetadata;
297
  transform: (value: any, ...args: any[]) => any;
298
}
299
```
300

301
[Extension System](./extension-system.md)
302

303
### Constants and Enums
304

305
Essential constants and enumeration values used throughout the n8n workflow system for node types, execution modes, and configuration.
306

307
```typescript { .api }
308
// Node type constants
309
const MANUAL_TRIGGER_NODE_TYPE = 'n8n-nodes-base.manualTrigger';
310
const START_NODE_TYPE = 'n8n-nodes-base.start';
311
const CODE_NODE_TYPE = 'n8n-nodes-base.code';
312

313
// Node type collections
314
const STARTING_NODE_TYPES: string[];
315
const SCRIPTING_NODE_TYPES: string[];
316

317
// Execution constants
318
const LOG_LEVELS: readonly ['silent', 'error', 'warn', 'info', 'debug'];
319
const CODE_LANGUAGES: readonly ['javaScript', 'python'];
320
const CODE_EXECUTION_MODES: readonly ['runOnceForAllItems', 'runOnceForEachItem'];
321
```
322

323
[Constants and Enums](./constants.md)
324

325
### Type Guards
326

327
Runtime type checking functions that validate if values match specific n8n interface types, providing type safety for dynamic workflow data.
328

329
```typescript { .api }
330
function isINodeProperties(value: any): value is INodeProperties;
331
function isINodePropertyOptions(value: any): value is INodePropertyOptions;
332
function isResourceMapperValue(value: any): value is IResourceMapperValue;
333
function isResourceLocatorValue(value: any): value is IResourceLocatorValue;
334
function isFilterValue(value: any): value is IFilterValue;
335
```
336

337
[Type Guards](./type-guards.md)
338

339
### Specialized Modules
340

341
Specialized utility modules and namespaces providing logging, node helpers, telemetry, observable objects, and native method access.
342

343
```typescript { .api }
344
namespace LoggerProxy {
345
  function info(message: string, meta?: object): void;
346
  function debug(message: string, meta?: object): void;
347
  function warn(message: string, meta?: object): void;
348
  function error(message: string, meta?: object): void;
349
}
350

351
namespace NodeHelpers {
352
  function getExecutionData(/*...*/): IExecuteData;
353
  function getNodeParameters(/*...*/): INodeParameters;
354
}
355

356
class NativeMethods {
357
  static getInstanceBaseClasses(): string[];
358
  static hasAccessToMethod(instanceName: string, methodName: string): boolean;
359
}
360
```
361

362
[Specialized Modules](./specialized-modules.md)