# @ucast/js

> git@github.com:stalniy/ucast.git

Latest version **4.0.1** (published 2026-04-24) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @ucast/js
pnpm add @ucast/js
yarn add @ucast/js
bun add @ucast/js
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.1 |
| Published | 2026-04-24 |
| First published | 2020-07-10 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 60.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 270 |
| Author | Sergii Stotskyi |
| Maintainers | stalniy |
| Keywords | ast, interpreter, conditions, query, builder |

## Links

- npm: https://www.npmjs.com/package/@ucast/js
- Repository: https://github.com/stalniy/ucast
- Homepage: https://github.com/stalniy/ucast#readme
- Issues: https://github.com/stalniy/ucast/issues
- npm.io page: https://npm.io/package/@ucast/js

## Dependencies (1)

- [@ucast/core](https://npm.io/package/@ucast/core.md) 2.0.0

## Alternatives

- [gamedig](https://npm.io/package/gamedig.md) — 29.3K weekly downloads
- [join-monster](https://npm.io/package/join-monster.md) — 12.8K weekly downloads
- [masked](https://npm.io/package/masked.md) — 5.5K weekly downloads
- [@comunica/actor-query-process-explain-logical](https://npm.io/package/@comunica/actor-query-process-explain-logical.md) — 4.7K weekly downloads
- [@veracity/vui](https://npm.io/package/@veracity/vui.md) — 4.6K weekly downloads

## Recent versions

- 4.0.1 (latest) — 2026-04-24
- 4.0.0 — 2026-04-24
- 3.1.0 — 2026-02-04
- 3.0.4 — 2024-01-31
- 3.0.3 — 2023-02-15
- 3.0.2 — 2021-07-15
- 3.0.1 — 2021-01-10
- 3.0.0 — 2020-10-17
- 2.2.3 — 2020-10-17
- 2.2.2 — 2020-08-26
- 2.2.1 — 2020-08-24
- 2.2.0 — 2020-08-20
- 2.1.3 — 2020-08-20
- 2.1.2 — 2020-08-20
- 2.1.1 — 2020-08-14
- … 6 more at https://npm.io/package/@ucast/js/versions

## README

# UCAST JavaScript

[![@ucast/js NPM version](https://badge.fury.io/js/%40ucast%2Fjs.svg)](https://badge.fury.io/js/%40ucast%2Fjs)
[![](https://img.shields.io/npm/dm/%40ucast%2Fjs.svg)](https://www.npmjs.com/package/%40ucast%2Fjs)
[![UCAST join the chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/stalniy-ucast/community)

This package is a part of [ucast] ecosystem. It provides interpreter that can execute conditions AST in JavaScript against any JavaScript object.

[ucast]: https://github.com/stalniy/ucast

## Installation

```sh
npm i @ucast/js
# or
yarn add @ucast/js
# or
pnpm add @ucast/js
```

## Getting Started

### Interpret conditions AST

First of all, you need AST to interpret it. For the sake of an example, we will create it manually:

```js
import { CompoundCondition, FieldCondition } from '@ucast/core';
import { interpret } from '@ucast/js';

// x > 5 && y < 10
const condition = new CompoundCondition('and', [
  new FieldCondition('gt', 'x', 5),
  new FieldCondition('lt', 'y', 10),
]);

interpret(condition, { x: 2, y: 1 }); // false
interpret(condition, { x: 6, y: 7 }); // true
```

The default `interpret` function:

* supports the next operators, implemented according to [MongoDB query language](https://docs.mongodb.com/manual/reference/operator/query/):

  * `eq`, `ne`
  * `lt`, `lte`
  * `gt`, `gte`
  * `within` (the same as `in` but `in` is a reserved word in JavaScript), `nin`
  * `all`
  * `regex`
  * `or`, `nor`, `and`, `not`
  * `exists`
  * `size`
  * `mod`
  * `where`,
  * `elemMatch`

* supports dot notation to access nested object property values in conditions:

  ```js
  const condition = new FieldCondition('eq', 'address.street', 'some street');
  interpret(condition, { address: { street: 'another street' } }); // false
  ```

* compare values by strict equality, so variables that reference objects are equal only if they are references to the same object:

  ```js
  const address = { street: 'test' };
  const condition = new FieldCondition('eq', 'address', address);

  interpret(condition, { address }) // true
  interpret(condition, { address: { street: 'test' } }) // false, objects are compared by strict equality
  ```

* follows current MongoDB `null` equality semantics: `{ field: null }` matches missing fields, explicit `null` values, and arrays that contain `null`, but not explicit `undefined` values.


### Custom interpreter

Sometimes you may want to reduce (or restrict) amount of supported operators (e.g., to utilize tree-shaking and reduce bundle size). To do this you can create a custom interpreter manually:

```js
import { FieldCondition } from '@ucast/core';
import { createJsInterpreter, eq, lt, gt } from '@ucast/js';

// supports only $eq, $lt and $gt operators
const interpret = createJsInterpreter({ eq, lt, gt });
const condition = new FieldCondition('in', 'x', [1, 2]);

interpret(condition, { x: 1 }) // throws Error, `$in` is not supported
```

### Custom object matching

You can also provide a custom `get` or `compare` function. So, you can implement custom logic to get object's property or to compare values. `compare` is used everywhere equality or comparison is required (e.g., in `$in`, `$lt`, `$gt`). This function must return `1` if `a > b`, `-1` if `a < b` and `0` if `a === b`.

Let's enhance our interpreter to support deep object comparison using [lodash]:

```js
import isEqual from 'lodash/isEqual';
import { createJsInterpreter, allInterpreters, compare } from '@ucast/js';

const interpret = createJsInterpreter(allInterpreters, {
  compare(a, b) {
    if (typeof a === typeof b && typeof a === 'object' && isEqual(a, b)) {
      return 0;
    }

    return compare(a, b);
  }
});
const condition = new FieldCondition('eq', 'x', { active: true });

interpret(condition, { x: { active: true } }); // true
```

### Custom Operator Interpreter

Any operator is just a function that accepts 3 parameters and returns boolean result. To see how to implement this function let's create `$type` interpreter that checks object property type using `typeof` operator:

```js
import { createJsInterpreter } from '@ucast/js';

function type(condition, object, { get }) {
  return typeof get(object, condition.field) === condition.value;
}

const interpret = createJsInterpreter({ type });
const condition = new FieldCondition('type', 'x', 'number');

interpret(condition, { x: 1 }); // true
```

**Pay attention** that object property is got by using `get` function. Make sure that you always use `get` function in custom operators to get object's property value, otherwise your operator will not support dot notation.

## Want to help?

Want to file a bug, contribute some code, or improve documentation? Excellent! Read up on guidelines for [contributing]

## License

[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)

[contributing]: https://github.com/stalniy/ucast/blob/master/CONTRIBUTING.md

---
_Source: https://npm.io/package/@ucast/js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._