npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ucast/js

v3.0.4

Published

[email protected]:stalniy/ucast.git

Downloads

2,331,993

Readme

UCAST JavaScript

@ucast/js NPM version UCAST join the chat

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

Installation

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:

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:

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

    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:

    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

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:

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

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:

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