# Expressions Overview
This allows you to perform numeric calculations, rounding, comparisons, and advanced math operations directly inside expressions—without using custom helpers. This is an extensive list. For examples and instructions on how to use each expression, please use our brand new and improved iX Hello Employee". This is an extensive list. For examples and instructions on how to use each expression, please use our brand new and improved iX Hello Employee".
#### Math (Full Object)
```
Math.abs(-5); // 5
Math.ceil(4.2); // 5
Math.floor(4.8); // 4
Math.round(4.5); // 5 (or use Math.round(x * 100) / 100 for decimals)
Math.min(1, 2, 3); // 1
Math.max(1, 2, 3); // 3
Math.pow(2, 8); // 256 (or use 2 ** 8)
Math.sqrt(16); // 4
Math.random(); // 0.0 to 1.0
Math.PI; // 3.14159...
```
#### Object (Read-Only)
Object (Read Only) referring to the built‑in JavaScript `Object` global where the binding itself is read‑only, but the object and its methods are fully usable.
```
Object.keys(user); // ['name', 'email', 'age']
Object.values(user); // ['John', 'john@example.com', 30]
Object.entries(user); // [['name', 'John'], ['email', '...'], ...]
Object.fromEntries(entries); // { name: 'John', ... }
Object.hasOwn(user, 'email'); // true
Object.assign({}, a, b); // Merge objects (creates new object)
```
#### Array (Static)
It means only the static methods of the JavaScript `Array` object are available, not the instance (prototype) methods.
```
Array.isArray(items); // true/false
Array.from(iterable); // Convert to array
Array.of(1, 2, 3); // [1, 2, 3]
```
#### JSON
`JSON` is exposed as a safe, static global utility for data transformation only
```
JSON.parse('{"a":1}'); // { a: 1 }
JSON.stringify({ a: 1 }); // '{"a":1}'
JSON.stringify(obj, null, 2); // Pretty print
```
#### Type Constructors
Type Constructors refers to the built‑in data‑type functions that let you create or coerce values into a specific type inside an expression.
```
String(123); // '123'
Number('42'); // 42
Boolean(1); // true
parseInt('42px'); // 42
parseFloat('3.14'); // 3.14
```
#### Date (Static Methods)
`Date` is exposed only with its static methods. This means you can work with timestamps and ISO date strings, but you cannot create or manipulate full `Date` objects the way you would in standard JavaScript.
Date.now(); // Timestamp in ms
Date.parse('2026-01-15'); // Timestamp
Date.UTC(2026, 0, 15); // UTC timestamp
#### Encoding & Security helpers
**Encoding** refers to a small set of **safe, stateless encoding/decoding utilities** exposed to help you prepare or interpret **data for transport**, especially in:
* API query parameters
* $fromToon (| Parsed array | Parse TOON back to objects )
* $toToon (Compact table format | For AI-optimized data display)
* URLs
* Headers
* Tokens or identifiers
* Text passed between workflow steps
```
btoa('hello'); // Base64 encode: 'aGVsbG8='
atob('aGVsbG8='); // Base64 decode: 'hello'
encodeURIComponent('a=b&c=d'); // URL-encode (escapes all special chars including / : @)
decodeURIComponent('a%3Db'); // URL-decode
encodeURI('https://example.com/path?q=hello world'); // URI-encode (preserves / : @ ? #)
decodeURI('https://example.com/path?q=hello%20world'); // URI-decode
```
Encoding & Security helpers are designed to protect customer conversations, integrations, and enterprise systems by ensuring that data is: Safely encoded before display or transmission, Protected from injection and formatting attacks, Handled consistently across channels and APIs, Sanitized before being rendered or reused.
```
$hash('password123'); // SHA-256 hash (default)
$hash('data', 'md5'); // MD5 hash
$hash('data', 'sha1'); // SHA-1 hash
$escapeHtml(''); // '<script>alert("xss")</script>'
```
#### Type Checking & Type Checking helpers
Type Checking is supported through a limited, safe subset of JavaScript type‑inspection utilities.
```
typeof value; // 'string', 'number', 'boolean', 'object', 'undefined'
typeof str === 'string'; // Check if string
typeof num === 'number'; // Check if number
typeof x === 'undefined'; // Safe check for undefined
isNaN(value); // Check if NaN
isFinite(value); // Check if finite number
Number.isNaN(value); // Strict NaN check
Number.isFinite(value); // Strict finite check
Number.isInteger(value); // Check if integer
```
Type Checking helpers allow you to verify the data type of a value before using it in logic, comparisons, transformations, or responses.
```
$isEmpty(null); // true
$isEmpty(''); // true
$isEmpty([]); // true
$isEmpty({}); // true
$isEmpty('hello'); // false
```
#### BigInt & BigInt Helpers
`BigInt` is available as a type constructor for large integers, but with strict limitations to keep expressions safe and deterministic.
```
BigInt('12345678901234567890'); // Create from string (for large numbers)
BigInt(42); // Create from number
BigInt('0xFF'); // Hex
BigInt('0b1010'); // Binary
// Arithmetic: +, -, *, /, %, ** (both operands must be BigInt)
// Comparison: ===, !==, <, >, <=, >= (can compare with Number)
```
BigInt Helpers are specialized `$ helpers` designed to work with very large integers—numbers that are too large to be safely represented as standard numeric types (for example, long account numbers, transaction references, or large counters).
```
$bigint('12345678901234567890'); // Safe BigInt creation — returns null on error instead of throwing
$isBigInt(value); // true if value is BigInt type
```
#### Regular Expressions
RegExp are intended for **string validation and pattern matching**, not for full‑blown text processing or dynamic regex construction.
```
RegExp('pattern'); // Create regex
RegExp('pattern', 'gi'); // With flags (g, i, m, s, u, y)
RegExp('hello').test(str); // Test if matches
str.match(RegExp('\\d+')); // Find matches
str.replace(RegExp('foo', 'g'), 'bar'); // Replace all
```
#### Sample Example: We are using regular expression to format a phone number
The phone number is : "5553211234"
The flow looks like this:
#### Result:
### Native Methods (Always Available)
Native Methods are core language methods that are always available, regardless of which global's are enabled or restricted.
#### String Methods
String methods are native and always available.They are the most reliable and widely used tools in expressions
```
name.toUpperCase(); // 'JOHN'
name.toLowerCase(); // 'john'
name.trim(); // Remove whitespace
name.split(','); // ['a', 'b', 'c']
name.replace('a', 'b'); // Replace first
name.replaceAll('a', 'b'); // Replace all
name.slice(0, 5); // Substring
name.substring(0, 5); // Substring
name.startsWith('Hello'); // true/false
name.endsWith('!'); // true/false
name.includes('world'); // true/false
name.indexOf('o'); // Position or -1
name.padStart(10, '0'); // '0000000123'
name.padEnd(10, '-'); // '123-------'
name.repeat(3); // 'abcabcabc'
name.charAt(0); // First character
name.charCodeAt(0); // Character code
```
#### Array Methods
Explains what you can safely rely on everywhere, without depending on `Array (Static)` or prototype-heavy behavior. Array handling exists, but it is intentionally constrained.
```
items[0] // First item
items.at(-1) // Last item
items.length // Count
items.filter(x => x.active) // Filter
items.map(x => x.name) // Transform
items.reduce((a, b) => a + b, 0) // Aggregate
items.find(x => x.id === 5) // Find one
items.findIndex(x => x.id === 5) // Find index
items.some(x => x.valid) // Any match?
items.every(x => x.valid) // All match?
items.includes(value) // Contains?
items.indexOf(value) // Position
items.slice(0, 5) // Subset
items.join(', ') // Join to string
items.flat() // Flatten nested
items.flatMap(x => x.items) // Map + flatten
items.toSorted() // Sort (non-mutating, ES2023)
items.toReversed() // Reverse (non-mutating, ES2023)
[...new Set(items)] // Unique values
```
Note: Mutating array methods (.push(), .pop(), .splice(), .sort(), .reverse()) are NOT\
available. Use non-mutating alternatives like .toSorted(), .toReversed(), spread, or\
$sortBy().
#### Number Methods
This is focused only on number methods you can always rely on, without depending on `Math`, `BigInt`, or environment‑specific behavior.
```
price.toFixed(2); // '99.99'
value.toString(); // Convert to string
value.toPrecision(4); // '99.99'
```
### Standard Library Functions ($ Helpers)
These are utility functions with a $ prefix for operations that have no pure-JavaScript
\
equivalent. Grouped by category.
#### Date & Time
Date & Time helpers allow you to:
* Work with the current timestamp
* Format dates for display or APIs
* Add or subtract time (days, hours, minutes)
* Compare dates for routing logic
* Calculate time differences (SLAs, expiry)
* The Date and Time are in UTC time zone
#### **Current Date/Time**
They are used whenever you need the *system‑generated time* inside flows, conditions, variables, API mappings, or responses.
These helpers are read‑only, platform‑controlled, and safe for production conversational logic.
```
$now(); // '2026-02-19T15:30:00.000Z' (ISO string)
$today(); // '2026-02-19' (date only)
```
#### **Date Arithmetic**
**Date Arithmetic helpers** allow you to **add, subtract, and calculate differences** between dates and timestamps. They are part of the **standard `$ helper` library** and are commonly used in: SLAs & escalation logic, Expiry and validity checks, Follow‑up scheduling, Appointment windows, Aging calculations.
```
$addDays('2026-01-15', 7); // '2026-01-22T00:00:00.000Z'
$addHours('2026-01-15T10:00:00Z', 2); // '2026-01-15T12:00:00.000Z'
$addMinutes('2026-01-15T10:00:00Z', 30); // '2026-01-15T10:30:00.000Z'
$addSeconds('2026-01-15T10:00:00Z', 90); // '2026-01-15T10:01:30.000Z'
$addMonths('2026-01-15', 3); // '2026-04-15T00:00:00.000Z'
$addYears('2026-01-15', 1); // '2027-01-15T00:00:00.000Z'
$dateDiff('2026-01-10', '2026-01-15'); // 5 (days, default)
$dateDiff('2026-01-15T10:00:00Z', '2026-01-15T13:00:00Z', 'hours'); // 3
```
Note : Format is Year-Month-Date
#### **Date Parts**
Date Parts helpers let you extract individual components (year, month, day, hour, etc.) from a date or timestamp.
Extract components for branching ("if month is December"):
```
$year('2026-12-25'); // 2026
$month('2026-12-25'); // 12
$day('2026-12-25'); // 25
$dayOfWeek('2026-12-25'); // 4 (0=Sunday, 1=Monday, ..., 6=Saturday)
$dayName('2026-12-25'); // 'Thursday'
$hour('2026-12-25T14:30:00Z'); // 14
$minute('2026-12-25T14:30:00Z'); // 30
```
#### **Date Comparison**
Date Comparison helpers are used to compare two dates or timestamps and return a boolean result (`true` / `false`).
#### Date Validation
Date validation is typically done using **standard `$ helpers`** such as **existence checks, null checks, and comparisons**, rather than custom parsing or regex logic.
#### Relative Time
**Relative Time** refers to evaluating or presenting time **in relation to another point in time**, most commonly **relative to “now”**.\
Instead of asking *“What is the exact date?”*, relative time answers questions like:
* “**5 minutes ago**”
* “**Within the last 24 hours**”
* “**In the next 7 days**”
* “**Expired 2 days back**”
```
$timeAgo('2026-02-16T10:00:00Z'); // '3 days ago'
$timeAgo('2026-02-20T10:00:00Z'); // 'in 1 day'
```
#### Formatting
Formatting helpers are used to convert dates and timestamps into readable or system‑required string formats.
Locale-aware display formatting with named patterns and custom date format strings:
```
// Named number patterns
$format(1234.5, 'currency'); // '$1,234.50' (USD)
$format(1234.5, 'EUR'); // '1.234,50 €'
$format(0.15, 'percent'); // '15%'
$format(1234567, 'number'); // '1,234,567'
$format(1234567, '0,0'); // '1,234,567' (number grouping)
// Named date patterns
$format('2026-01-15T10:30:00Z', 'date'); // '1/15/2026' (en-US locale)
$format('2026-01-15T10:30:00Z', 'time'); // '10:30:00 AM'
$format('2026-01-15T10:30:00Z', 'datetime'); // '1/15/2026, 10:30:00 AM'
$format('2026-01-15T10:30:00Z', 'iso'); // '2026-01-15T10:30:00.000Z'
// Custom date format strings (UTC-based)
$format('2026-01-15', 'MMMM D, YYYY'); // 'January 15, 2026'
$format('2026-01-15', 'MM/DD/YYYY'); // '01/15/2026'
$format('2026-01-15', 'MMM D, YYYY'); // 'Jan 15, 2026'
```
Date format tokens: MMMM (January), MMM (Jan), MM (01), D (5), DD (05), YYYY (2026)
#### Data Access & Transformation
Data Access and Transformation are essential for robust, enterprise‑grade conversational flows.
```
$get(obj, 'user.address.city', 'Unknown'); // Deep path access with default
$groupBy(orders, 'status'); // { pending: [...], shipped: [...] }
$sortBy(users, 'lastName'); // Sorted by lastName ascending
$sortBy(users, 'age', 'desc'); // Sorted by age descending
items.filter((x) => x.status === 'active').length; // Count matching (native JS)
```
#### LLM Optimization
LLM Optimization focuses on getting higher‑quality, more predictable, and more cost‑efficient responses from Large Language Models by controlling what data is sent, how it is structured, and how the model is guided—*before* a prompt is executed.
In iX Hello, this optimization is achieved without writing model‑level code, using Expression Engine helpers, data shaping, and guard logic.
```
$toToon(users); // Convert to TOON format (compact tabular representation)
$fromToon(toonString); // Parse TOON back to array of objects
```
#### Identity
Identity helpers and patterns are used to identify, normalize, validate, and safely use identities across customer conversations and integrations.\
“Identity” in iX Hello typically refers to who the user is (or which entity they represent) and how that identity is consistently referenced across channels, sessions, APIs, and LLM prompts.
```
$guid(); // 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
$uuid(); // Alias for $guid()
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.ixhello.com/ixhc2/technical-specifications/expression-engine/expressions-overview.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.