N8n Syntax Extension Methods

n8n Extension Methods

Complete reference for all n8n v1.x expression extension methods. ALWAYS use extension methods over raw JavaScript equivalents — they are null-safe and optimized for n8n's expression engine.

Quick Reference — Method Categories

Full method signatures and parameters: references/methods.md Practical examples: references/examples.md Common mistakes: references/anti-patterns.md

Decision Tree — Which Method Category?

What data type are you working with?
|
+-- String value?
|   +-- Need to extract structured data? --> .extractEmail(), .extractUrl(), .extractDomain()
|   +-- Need to validate? --> .isEmail(), .isUrl(), .isEmpty()
|   +-- Need encoding/hashing? --> .urlEncode(), .base64Encode(), .hash()
|   +-- Need case conversion? --> .toTitleCase(), .toSnakeCase(), .toSentenceCase()
|   +-- Need type conversion? --> .toDateTime(), .toBoolean()
|
+-- Array value?
|   +-- Need specific fields from objects? --> .pluck("field1", "field2")
|   +-- Need deduplication? --> .removeDuplicates() or .unique()
|   +-- Need set operations? --> .union(), .intersection(), .difference()
|   +-- Need aggregation? --> .sum(), .average(), .min(), .max()
|   +-- Need restructuring? --> .chunk(), .smartJoin(), .renameKeys()
|
+-- Number value?
|   +-- Need rounding? --> .round(), .ceil(), .floor()
|   +-- Need formatting? --> .format(locale)
|   +-- Need type check? --> .isEven(), .isOdd(), .isInteger()
|   +-- Need conversion? --> .toDateTime(), .toBoolean()
|
+-- Object value?
|   +-- Need to filter fields? --> .keepFieldsContaining(), .removeFieldsContaining()
|   +-- Need to clean nulls? --> .compact()
|   +-- Need to check structure? --> .hasField(), .keys(), .values()
|   +-- Need to combine? --> .merge()
|   +-- Need serialization? --> .toJsonString(), .urlEncode()
|
+-- DateTime value?
|   +-- Need arithmetic? --> .plus(), .minus()
|   +-- Need comparison? --> .equals(), .isBetween(), .diffTo()
|   +-- Need formatting? --> .format(), .toISO(), .toRelative()
|   +-- Need extraction? --> .year, .month, .day, .hour, .weekday
|   +-- Need timezone? --> .setZone(), .toUTC(), .toLocal()
|
+-- Boolean value?
|   +-- Need number? --> .toNumber()
|   +-- Need string? --> .toString()
|
+-- Binary file?
    +-- Need file info? --> .fileName, .fileSize, .mimeType, .fileExtension

String Methods — Overview

19 methods for extraction, validation, encoding, conversion, and formatting.

Extraction group: .extractEmail(), .extractUrl(), .extractDomain(), .extractUrlPath() Validation group: .isEmail(), .isUrl(), .isEmpty(), .isNotEmpty() Encoding group: .urlEncode(), .urlDecode(), .base64Encode(), .base64Decode(), .hash() Conversion group: .toDateTime(), .toBoolean() Formatting group: .toSentenceCase(), .toSnakeCase(), .toTitleCase(), .quote(), .removeMarkdown(), .replaceSpecialChars()

Key behavior:

• .extractEmail() returns undefined if no email found — ALWAYS check with .isEmpty() or use $ifEmpty()
• .hash() defaults to md5 — ALWAYS specify algorithm explicitly for clarity: .hash("sha256")
• .toBoolean() treats "0", "false", "no" as false (case-insensitive), everything else as true
• .urlEncode(true) encodes ALL characters including URI syntax chars (/, ?, &)

Array Methods — Overview

21 methods for extraction, deduplication, set operations, aggregation, and restructuring.

Extraction group: .first(), .last(), .randomItem(), .pluck() Deduplication group: .removeDuplicates(), .unique(), .union() Set operations: .difference(), .intersection(), .union() Aggregation: .sum(), .average(), .min(), .max() Restructuring: .chunk(), .smartJoin(), .renameKeys(), .append(), .compact()

Key behavior:

• .pluck("name") extracts a single field; .pluck("name", "email") extracts multiple fields as sub-objects
• .removeDuplicates() works on primitives; .removeDuplicates("email") deduplicates objects by key
• .smartJoin("id", "value") transforms [{id: "a", value: 1}, {id: "b", value: 2}] into {a: 1, b: 2}
• .average() and .sum() throw errors on non-numeric arrays — ALWAYS ensure numeric data first

Number Methods — Overview

11 methods for rounding, formatting, type checks, and conversion.

Key behavior:

• .format() uses Intl.NumberFormat — pass locale for regional formatting: .format("de-DE")
• .round(2) rounds to 2 decimal places; .round() rounds to nearest integer
• .isEven() and .isOdd() throw errors on non-integers — ALWAYS check .isInteger() first
• .toDateTime() interprets numbers as Unix milliseconds by default; use .toDateTime("s") for seconds, .toDateTime("excel") for Excel serial dates

Object Methods — Overview

12 methods for filtering, merging, checking, and serializing.

Key behavior:

• .compact() removes fields with null or "" values — does NOT remove 0 or false
• .merge(other) gives precedence to the BASE object, not the argument
• .keepFieldsContaining("test") and .removeFieldsContaining("test") match partial string values
• .hasField("name") checks top-level keys ONLY — does NOT check nested fields
• .urlEncode() produces query string format: key1=value1&key2=value2

DateTime Methods — Overview (Luxon-based)

25+ methods organized as property accessors, transformations, comparisons, and formatters.

Property accessors: .year, .month, .day, .hour, .minute, .second, .weekday, .weekNumber, .quarter, .monthLong, .weekdayLong Transformation: .plus(), .minus(), .set(), .startOf(), .endOf(), .setZone(), .toUTC(), .toLocal() Comparison: .equals(), .hasSame(), .isBetween(), .diffTo(), .diffToNow() Formatting: .format(), .toISO(), .toRelative(), .toLocaleString(), .toMillis(), .toSeconds()

Key behavior:

• .plus(5, "days") and .minus({days: 5, hours: 3}) — supports both positional and object syntax
• .format("yyyy-MM-dd") uses Luxon tokens, NOT moment.js tokens
• .diffTo(other, "days") returns a Duration object — access .days property for the number
• .isBetween(start, end) is exclusive on both bounds
• ALWAYS use $now and $today instead of new Date() — they respect workflow timezone

Luxon Format Tokens

Common patterns:

• ISO date: yyyy-MM-dd → 2026-03-19
• ISO datetime: yyyy-MM-dd'T'HH:mm:ss → 2026-03-19T14:05:09
• Human-readable: EEEE, MMMM dd yyyy → Wednesday, March 19 2026
• Time only: HH:mm:ss → 14:05:09
• European date: dd-MM-yyyy → 19-03-2026

Boolean Methods — Overview

3 methods: .isEmpty(), .toNumber(), .toString().

• .isEmpty() returns false for ALL boolean values; only returns true for null
• .toNumber() converts true → 1, false → 0

BinaryFile Properties — Overview

7 read-only properties for file metadata access via $binary.data:

Key behavior:

• .fileSize returns a STRING, not a number — ALWAYS convert with parseInt() for math operations
• .directory is NOT set when binary data is stored in the database — ALWAYS check before using
• .fileType returns only the first part of the MIME type (e.g., "image" from "image/jpeg")

Chaining Methods

Extension methods return typed values that support further chaining:

// String chaining
{{ $json.email.extractDomain().toTitleCase() }}

// Array chaining
{{ $json.items.pluck("price").sum() }}

// DateTime chaining
{{ $now.minus({days: 7}).startOf("day").toISO() }}

// Mixed type chaining
{{ $json.timestamp.toDateTime().format("yyyy-MM-dd") }}

NEVER chain methods without understanding the return type — check references/methods.md for return types.

Reference Links

• Complete Method Tables — All methods with full signatures, parameters, and return types
• Practical Examples — Real-world patterns combining multiple methods
• Anti-Patterns — Common mistakes and how to avoid them
• n8n Expression Reference — Official documentation
• Luxon DateTime — Underlying DateTime library