Nicely Presented Misnomer

    fiql-query-builder

    1.0.10 • Public • Published

    FIQL Query Builder

    Build Status Codacy Badge Codacy Badge

    Overview

    Feed Item Query Language (FIQL) is a simple, URI-friendly query language for filtering entries of web feeds.

    This module provides the utility to generate valid FIQL query strings by using a JSON objects or the custom classes provided.

    Installation

    $ npm install fiql-query-builder

    Usage

    FIQL query strings can be produced by supplying a JSON object, or using the Node classes provided.

    JSON to FIQL

     
    // var json = ...;
     
    // Using require()
    var fiqlQueryBuilder = require('fiql-query-builder');
    fiqlQueryBuilder.convertFromJson(json);
     
    // Using ES6 import
    import { convertFromJson } from 'fiql-query-builder';
    convertFromJson(json);
     

    Basic Operators

    Object Key Children Description
    custom_operator
    • selector {String} (required) - The left-hand side of the operator
    • operator {String} (required) - The custom operator
    • args {Object | String} (required) - The child node for operator (right-hand side)
    Define a custom basic operator
    equals
    • selector {String} (required)
    • args {Object | String} (required)
    Produces an equality operator (==)
    not_equals
    • selector {String} (required)
    • args {Object | String} (required))
    Produces an inequality operator (!=)
    less_than
    • selector {String} (required)
    • args {Object | String} (required)
    Produces an less than operator (=lt=)
    less_than_or_equal
    • selector {String} (required)
    • args {Object | String} (required)
    Produces an less than or equal operator (=le=)
    greater_than
    • selector {String} (required)
    • args {Object | String} (required)
    Produces an greater operator (=gt=)
    greater_than_or_equal
    • selector {String} (required)
    • args {Object | String} (required)
    Produces an greater than or equal operator (=ge=)
    in
    • selector {String} (required)
    • args {Object | String} (required)
    Produces an in operator (in)
    out
    • selector {String} (required)
    • args {Object | String} (required)
    Produces an out operator (out)

    Boolean Expressions

    Object Key Children Description
    custom_expression
    • operator {String} (required) - The custom operator
    • children {Object[]} - The children for the expression
    Define a custom boolean expression
    and
    • _ {Object[]} (required)
    Combines child array with an and operator (;)
    or
    • _ {Object[]} (required)
    Combines child array with an or operator (,)

    Grouping

    Object Key Children Description
    group
    • _ {Object} (required) - The child expression
    Wraps an expression in parentheses

    Node to FIQL

     
    // var node = ...
     
    // Using require()
    var fiqlQueryBuilder = require('fiql-query-builder');
    fiqlQueryBuilder.convertFromNode(node);
     
    // Using ES6 import
    import { convertFromNode, EqNode, AndNode, OpNode } from 'fiql-query-builder';
    convertFromNode(node);
     

    LeafNode(value)

    The query param is built by traversing the object tree recursively, so a LeafNode is used to represent a primitive value.

    Param Type Description
    value string The string value

    OpNode(selector, operator, args)

    A generic operator

    Param Type Description
    selector LeafNode The left-hand side of the operator
    operator string The custom operator
    args GroupNode | LeafNode | ExpNode | OpNode The child node for operator (right-hand side)
    Subclasses

    Standard operator classes have been provided, and can be instantiated using ClassName(selector, args).

    • Equality (==) : EqNode
    • Inequality (!=) : NeqNode
    • Less than (=lt=) : LtNode
    • Less than or equal to (=le=) : LeNode
    • Greater than (=gt=) : GtNode
    • Greater than or equals to (=ge=) : GeNode
    • In (=in=) : InNode
    • Not in (=out=) : NotInNode

    ExpNode(operator, children)

    A generic boolean expression

    Param Type Description
    operator string The custom operator
    children Node[] The child nodes for the expression
    Subclasses

    Standard boolean expression classes have been provided, and can be instantiated using ClassName(children).

    • And (;) : AndNode
    • Or (,) : OrNode

    GroupNode(exp)

    Used to wrap parentheses around a boolean expression.

    Param Type Description
    exp ExpNode The boolean expression to wrap parentheses around

    Examples

    JSON to FIQL

    Example standard basic operator

    var eqJson = convertFromJson({
        equals : {
            selector: 'foo',
            args: 'bar'
        }
    });
    // eqJson = foo==bar

    Example custom basic operator

    var customOperatorJson = convertFromJson({
        custom_operator : {
            operator: '¬',
            selector: 'foo',
            args: 'bar' 
        }
    });
    // customOperatorJson equals: foo¬bar 

    Example standard boolean expression

    var andJson = convertFromJson({
        and : [
            {
                equals: {
                    selector: 'foo',
                    args: 'bar'
                }
            },
            {
                not_equals: {
                    selector: 'baz',
                    args: 'qux'
                }
            }
        ]
    });
    // andJson equals: foo==bar;baz!=qux

    Example custom boolean expression

    var customExpressionJson = convertFromJson({
        custom_expression : {
            operator: '*',
            children: [
                {
                    equals: {
                        selector: 'foo',
                        args: 'bar'
                    }
                },
                {
                    not_equals: {
                        selector: 'baz',
                        args: 'qux'
                    }
                }
            ]
        }
    });
    // customExpressionJson equals: foo==bar*baz!=qux

    Example grouping and nested arguments

    var groupJson = convertFromJson({
        equals : {
            selector: 'k',
            args: {
                group : {
                    and : [
                        {
                            less_than: {
                                selector: 'foo',
                                args: 'bar'
                            }
                        },
                        {
                            not_equals: {
                                selector: 'baz',
                                args: 'qux'
                            }
                        }
                    ]
                }
            }
        }
    });
    // groupJson equals: k==(foo=lt=bar,baz!=qux)

    Node to FIQL

    Example standard basic operator

    var eqNode = convertFromNode(
        new EqNode(
            new LeafNode('foo'), 
            new LeafNode('bar')
        )
    );
    // eqNode = foo==bar

    Example custom basic operator

    var customOperatorNode = convertFromNode(
        new OpNode(
            new LeafNode('foo'), 
            '¬', 
            new LeafNode('bar')
        )
    );
    // customOperatorNode equals: foo¬bar 

    Example standard boolean expression

    var andNode = convertFromNode(
        new AndNode([
            new EqNode(
                new LeafNode('foo'), 
                new LeafNode('bar')
            ),
            new NeqNode(
                new LeafNode('baz'), 
                new LeafNode('qux')
            )
        ])
    );
    // andNode equals: foo==bar;baz!=qux

    Example custom boolean expression

    var customExpressionNode = convertFromNode(
        new ExpNode('*', [
            new EqNode('foo', 'bar'),
            new NeqNode('baz', 'qux')
        ])
    );
    // customExpressionNode equals: foo==bar*baz!=qux

    Example grouping and nested arguments

    var groupNode = convertFromNode(
        new EqNode(
            new LeafNode('k'),
            new GroupNode(
                new AndNode([
                    new LtNode(
                        new LeafNode('foo'),
                        new LeafNode('bar')
                    ),
                    new NeqNode(
                        new LeafNode('baz'),
                        new LeafNode('qux')
                    )
                ])
            )
        )
    );
    // groupNode equals: k==(foo=lt=bar,baz!=qux)

    License

    This project is licensed under MIT License

    Install

    npm i fiql-query-builder

    DownloadsWeekly Downloads

    288

    Version

    1.0.10

    License

    MIT

    Unpacked Size

    50.5 kB

    Total Files

    31

    Last publish

    Collaborators

    • lmcq