@overture-stack/sqon-builder

SQON Builder

This is a library to facilitate the creation, parsing and manipulation of SQON filter objects. It also provides the relevant TypeScript definitions to improve your developer experience when using SQONs.

Arranger Compatibility

Important note: Only works with Arranger v3+

Changes introduced in Arranger v3.0 have redefined an important part of the SQON syntax: Considering an Arranger "field" is an entity with multiple atributes, e.g. value, state params, display format; for semantic precision and ease of implementation, filters now expect a "fieldName" string (or array of them) instead of a "field". i.e. we've renamed the relevant properties.

How to Use

Filters

To create a SQON that filters one property by value:

import SQON from 'sqon-builder';

SQON.in('name', ['Jim', 'Bob']);

Produces a SQON with the following content:

{
  "op": "and",
  "content": [
    {
      "op": "in",
      "content": {
        "fieldName": "name",
        "value": ["Jim", "Bob"]
      }
    }
  ]
}

There are currently 3 filters available (to be expanded to match the full SQON specification):

Filter	Value Type	Description
in	Array<string | number>	field value must be in the given list.
gt	number	Greater Than - field value must be greater than the given number
lt	number	Lesser Than - field value must be lesser than the given number

A SQON can chain multiple of these filters together into a single SQON that requires all the provided conditions:

SQON.in('name', ['Jim', 'Bob']).gt('score', 9000).lt('age', 100);

Creates the SQON:

{
  "op": "and",
  "content": [
    {
      "op": "in",
      "content": {
        "fieldName": "name",
        "value": ["Jim", "Bob"]
      }
    },
    {
      "op": "gt",
      "content": {
        "fieldName": "score",
        "value": 9000
      }
    },
    {
      "op": "lt",
      "content": {
        "fieldName": "age",
        "value": 100
      }
    }
  ]
}

Combining Multiple Filters

Every SQON can be combined with other SQONs through the boolean combinations and, or, and not:

const nameFilter = SQON.in('name', ['Jim', 'Bob']);
const scoreFilter = SQON.gt('score', 9000);

SQON.or(nameFilter, scoreFilter);

Result:

{
  "op": "or",
  "content": [
    {
      "op": "and",
      "content": [
        {
          "op": "in",
          "content": {
            "fieldName": "name",
            "value": ["Jim", "Bob"]
          }
        }
      ]
    },
    {
      "op": "and",
      "content": [
        {
          "op": "gt",
          "content": {
            "fieldName": "score",
            "value": 9000
          }
        }
      ]
    }
  ]
}

A SQON can also chain these operations like with filters to combine with other SQONs:

const name = SQON.in('name', ['Jim', 'Bob']);
const denied = SQON.in('status', ['DENIED']);
const score = SQON.gt('score', 9000);
const age = SQON.lt('age', 100);

score.or(age).and(name).not(denied);

This is equivalent to:

SQON.and([
  SQON.or([
    score,
    age
  ])
  name,
  SQON.not([denied]),
]);

Result:

{
  "op": "and",
  "content": [
    {
      "op": "or",
      "content": [
        {
          "op": "and",
          "content": [
            {
              "op": "gt",
              "content": {
                "fieldName": "score",
                "value": 9000
              }
            }
          ]
        },
        {
          "op": "and",
          "content": [
            {
              "op": "lt",
              "content": {
                "fieldName": "age",
                "value": 100
              }
            }
          ]
        }
      ]
    },
    {
      "op": "in",
      "content": {
        "fieldName": "name",
        "value": ["Jim", "Bob"]
      }
    },
    {
      "op": "not",
      "content": [
        {
          "op": "and",
          "content": [
            {
              "op": "in",
              "content": {
                "fieldName": "status",
                "value": ["DENIED"]
              }
            }
          ]
        }
      ]
    }
  ]
}

String Output

The SQON data object can be passed directly to most network request libraries, but if a string is needed there is a convenience method toString().

SQON.in('name', ['Jim', 'Bob']).toString();
// {"op":"and","content":[{"op":"in","content":{"fieldName":"name","value":["Jim","Bob"]}}]}

This is just a shortcut to running JSON.stringify(someSqon).

API

Filters

SQON.in(fieldName, values)

Creates a filter requiring the given field to have one of the given values. Should function with single values or arrays of values.

Example: SQON.in('name',['Jim','Bob'])

SQON.gt(fieldName, value)

Greater Than operator. Create a filter requiring the given field to be greater than the given value

Example: SQON.gt('age',21)

SQON.lt(fieldName, value)

Lesser Than operator. Create a filter requiring the given field to be lesser than the given value

Example: SQON.lt('count', 100)

Combinations

Combinations can be initiaed from the SQON class or from a SQON instance.

If this is called from an instance, the method will accept one SQON or an array, and the instance can be considered grouped with the SQONs provided in the arguments.

If this is called from the class, an array of SQONs is required to be passed.

SQON.and(sqon)

All filters in the resulting SQON must be true.

Example: SQON.and( [someSqon, anotherSqon] )

SQON.or(sqon)

At least one filter in the resulting SQON must be true.

Example: SQON.or( [someSqon, anotherSqon] )

SQON.not(sqon)

None of the filters in the resulting SQON can be true.

Example: SQON.not( [someSqon] )

From

Build a new SQON from a string or from a JSON object.

Example with string:

SQON.from(
  '{"op":"and","content":[{"op":"in","content":{"fieldName":"name","value":"Tim"}},{"op":"gt","content":{"fieldName":"age","value":"19"}}]}',
);