@skedulo/eql

@skedulo/eql

A TypeScript parser for Skedulo's Entity Query Language (EQL). This library provides tools for parsing and evaluating EQL filter expressions.

Installation

npm install @skedulo/eql
# or
yarn add @skedulo/eql

Usage

You can use this library in several ways:

1. Parse and evaluate a filter expression in one step:

import { evaluateFilter } from "@skedulo/eql";

const event = {
  Current: { JobStatus: "Ready" },
  Previous: { JobStatus: "Dispatched" },
};

const result = evaluateFilter("Current.JobStatus == 'Ready'", event);
console.log(result); // true

2. Parse and evaluate separately:

import { parseFilter, evaluateExpression } from "@skedulo/eql";

// Parse the filter expression into an AST
const ast = parseFilter("Current.JobStatus == 'Ready'");

// Later, evaluate it against an event
const result = evaluateExpression(ast, event);

3. Convert AST back to string (round-trip conversion):

import { parseFilter, stringify } from "@skedulo/eql";

// Parse a query into an AST
const ast = parseFilter("Current.JobStatus == 'Ready' AND priority > 5");

// Convert the AST back to a string
const queryString = stringify(ast);
console.log(queryString); // "Current.JobStatus == 'Ready' AND priority > 5"

This is useful for:

• Query transformation and optimization
• Normalizing query format (e.g., quote styles)
• Building query builders or editors
• Serializing parsed queries for storage

4. Use the types for your own implementations:

import { Expression, Event } from "@skedulo/eql";

function customEvaluator(expr: Expression, event: Event) {
  // Your custom evaluation logic
}

Supported Operations

• Comparison operators: ==, !=
• String pattern matching: LIKE, NOTLIKE (with % and _ wildcards)
• List membership: IN
• Logical operators: AND, OR
• Parentheses for grouping

Examples

// Basic equality
"Current.JobStatus == 'Ready'";

// Comparison between paths
"Current.JobStatus != Previous.JobStatus";

// Pattern matching
"Current.Description LIKE '%urgent%'";

// List membership
"Current.Status IN ['Open', 'InProgress']";

// Complex expressions
"(Current.Status == 'Open' OR Current.Status == 'InProgress') AND Current.Priority == 'High'";

AST to String Conversion

The stringify function converts parsed AST expressions back to EQL query strings. This enables round-trip conversion and query manipulation:

Basic Usage

import { parseFilter, stringify } from "@skedulo/eql";

const ast = parseFilter("operation == 'INSERT'");
const queryString = stringify(ast);
// Result: "operation == 'INSERT'"

Quote Normalization

The stringifier normalizes all string literals to use single quotes:

const ast = parseFilter('operation == "INSERT"'); // Double quotes
const queryString = stringify(ast);
// Result: "operation == 'INSERT'" // Normalized to single quotes

Complex Expressions

The stringifier handles complex nested expressions with proper parenthesization:

const complexQuery = "(operation == 'UPDATE' OR operation == 'INSERT') AND Current.status != Previous.status";
const ast = parseFilter(complexQuery);
const regenerated = stringify(ast);
// Result: exact same string with proper parentheses preserved

Supported Features

• ✅ All comparison operators (==, !=, <, <=, >, >=, LIKE, NOTLIKE, IN, NOTIN)
• ✅ Logical operators (AND, OR) with proper parenthesization
• ✅ All literal types (strings, numbers, booleans, null, dates, times, durations)
• ✅ List literals with mixed types
• ✅ Nested path expressions (e.g., Current.job.status)
• ✅ Quote normalization and escaping