@judo/idem/README.md

A powerful and expressive query language designed for filtering and manipulating data

# Idem Query Language

[![EPL-2.0 license](https://img.shields.io/badge/License-EPL--2.0-blue.svg)](https://opensource.org/licenses/EPL-2.0)

## 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:

```bash
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.

```bash
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:

```typescript
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](https://github.com/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](LICENSE.txt) file.