Idem Query Language

Overview

Idem is a powerful and expressive query language designed for filtering and manipulating data. This library provides a lightweight parser and evaluator for the Idem language, built with TypeScript and ANTLR4.

It is designed to be easily integrated into any JavaScript or TypeScript project, whether it's running in Node.js or the browser.

Features

• Expressive Syntax: A clear and concise syntax for complex queries.
• TypeScript Native: Fully written in TypeScript with type definitions included.
• Cross-platform: Works in both Node.js and modern browsers.
• Extensible: The ANTLR grammar is available for extension and integration with other tools.

Installation

You can install the library using your favorite package manager:

npm install idem
pnpm install idem
...

This library has antlr4ng as a peer dependency. You will need to install it alongside this library if you haven't already.

npm install antlr4ng
pnpm install antlr4ng
...

Usage

The primary way to use the library is by creating an evalExpr function using the createEvalExpr factory. This allows you to provide your own implementation for helper functions, such as date manipulation.

The createEvalExpr function requires an object with a dateFunctions property, which you can implement using a library like date-fns or with your own custom functions.

Here is a simple example:

import { createEvalExpr } from 'idem';
import { addDays, subDays, parseISO, differenceInDays, differenceInSeconds } from 'date-fns';

// Create a configured version of the evaluator
const evalExpr = createEvalExpr({ dateFunctions: { addDays, subDays, parseISO, differenceInDays, differenceInSeconds, } });

// The context object contains the data you want to query.
// The 'self' property is the root of the data.
const context = {
  self: { a: 1.5, b: 2, items: [1, 2, 3], },
};

// --- Example 1: Simple Arithmetic ---
const result1 = evalExpr('20 - 5');
console.log(result1); // Output: 15

// --- Example 2: Checking for an item in a list ---
const result2 = evalExpr('2 in self.items', context);
console.log(result2); // Output: true

The evalExpr function has an optional T generic type, but keep in mind, that whatever generic type we provide to the function, the result is never guaranteed!

The evalExpr function will always catch Errors and in such cases an undefined value will be returned.

Development

This project uses TypeScript, Vite for bundling, and Vitest for testing.

Project Structure

• src/: Main source code of the library.
• src/generated/: ANTLR-generated parser files from Idem.g4.
• Idem.g4: The ANTLR grammar definition for the Idem language.
• vite.config.ts: Vite build configuration.
• vitest.config.ts: Vitest test configuration.

Available Scripts

The following scripts are available:

• pnpm dev: Starts the Vite development server.
• pnpm build: Compiles TypeScript and builds the library for production.
• pnpm generate:antlr: Regenerates the ANTLR parser from Idem.g4.
• pnpm test: Runs the test suite using Vitest.
• pnpm coverage: Runs tests and generates a coverage report.
• pnpm format: Formats, and fixes the code using Biome.
• pnpm lint: Lints the code using Biome.

Contributing

Contributions are welcome! We thank the following contributors for their work on this project:

• Norbert Herczeg (@noherczeg)

Please feel free to open an issue or submit a pull request.

License

This project is licensed under the Eclipse Public License 2.0. See the LICENSE.txt file.