KoreForge.Jex 1.1.2

KoreForge.Jex

KoreForge.Jex is a high-performance JSON Expression language engine for .NET that enables runtime JSON transformation using a simple, expressive scripting syntax. It's designed for scenarios where you need to dynamically transform JSON documents without recompiling your application.

Features

• Declarative Transformations: Transform JSON documents using intuitive %set statements with dot-notation paths
• Control Flow: Full support for conditionals (%if/%then/%else) and loops (%foreach)
• Rich Standard Library: Built-in functions for strings, math, arrays, dates, JSON operations, and more
• Custom Functions: Register your own C# functions for domain-specific transformations
• Nested JSON Expansion: Automatically parse escaped JSON strings embedded within documents
• JSONPath Support: Query JSON using JSONPath expressions (jp1, jpn)
• Type Safety: Strong error reporting with source locations for debugging
• High Performance: Sub-microsecond execution for simple transformations

Installation

dotnet add package KoreForge.Jex

Quick Start

using KoreForge;
using Newtonsoft.Json.Linq;

// Create a JEX instance
var jex = new Jex();

// Compile a transformation script
var program = jex.Compile(@"
    %set $.fullName = concat($in.firstName, "" "", $in.lastName);
    %set $.isAdult = $in.age >= 18;
");

// Execute on JSON input
var input = JObject.Parse(@"{
    ""firstName"": ""John"",
    ""lastName"": ""Doe"",
    ""age"": 25
}");

var result = program.Execute(input);
// Result: { "fullName": "John Doe", "isAdult": true }

Syntax Overview

Variable Scopes

Statements

// Set a value in the output
%set $.name = $in.name;

// Create a local variable
%let temp = $in.value * 2;

// Conditional logic
%if ($in.age >= 18) %then %do;
    %set $.status = "adult";
%else %do;
    %set $.status = "minor";
%end;

// Loop over arrays
%foreach item %in $in.items %do;
    push($.processed, upper(&item.name));
%end;

Object Literals

%set $.person = {
    "name": $in.firstName,
    "age": $in.age,
    "tags": ["user", "active"]
};

Built-in Functions

String Functions

Math Functions

Array Functions

JSON Functions

Date Functions

Utility Functions

Custom Functions

Register custom functions to extend JEX with your own logic:

var jex = new Jex();

// Register a function that returns a value
jex.RegisterFunction("calculateTax", (amount, rate) => 
    amount.AsNumber() * rate.AsNumber());

// Register a void function (for side effects like push)
jex.RegisterVoidFunction("log", (context, args) => 
    Console.WriteLine(args[0].AsString()));

var program = jex.Compile(@"
    %set $.tax = calculateTax($in.price, 0.08);
");

Nested JSON Expansion

JEX can automatically parse JSON strings embedded within your documents:

var input = JObject.Parse(@"{
    ""payload"": ""{\""name\"":\""John\"",\""age\"":30}""
}");

// Expand a specific field
var program = jex.Compile(@"
    %set $.data = expandJson($in, ""$.payload"");
");
// Result: { "data": { "name": "John", "age": 30 } }

// Or expand all nested JSON strings recursively
var programAll = jex.Compile(@"
    %set $ = expandJsonAll($in);
");

Performance

Benchmark results on .NET 10.0.1 (13th Gen Intel Core i7-13650HX, Windows 11):

Run benchmarks yourself:

cd KoreForge.Jex
.\scr\build-benchmark.ps1

Error Handling

JEX provides detailed error messages with source locations:

try
{
    var program = jex.Compile(@"
        %set $.value = unknownFunction($in.x);
    ");
}
catch (JexCompileException ex)
{
    // "Unknown function 'unknownFunction' at (2,23)-(2,38)"
    Console.WriteLine(ex.Message);
}

Runtime errors include execution context:

try
{
    program.Execute(input);
}
catch (JexRuntimeException ex)
{
    // "Division by zero at (5,15)-(5,25)"
    Console.WriteLine(ex.Message);
}

Libraries

JEX supports reusable function libraries:

// Define a library with custom functions
var librarySource = @"
    %function greet(name)
        %return concat(""Hello, "", &name, ""!"");
    %end;
";

var library = jex.CompileLibrary("MyLib", librarySource);

// Use in programs
var program = jex.Compile(@"
    %set $.greeting = MyLib.greet($in.name);
", library);

Requirements

• .NET 10.0 or later
• Newtonsoft.Json 13.0.4+

Related Packages

This package is part of the KoreForge suite of libraries:

• KoreForge.Pipeline - Chainable middleware pipeline for processing
• KoreForge.Flow - State-machine workflow orchestration
• KoreForge.Kafka - Kafka messaging integration

License

MIT License - see LICENSE.md for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.