fiql-query-builder

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 | | ------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | | customoperator |

• 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 (==) | | notequals |

• selector {String} (required)
• args {Object \| String} (required))

| Produces an inequality operator (!=) | | lessthan |

• selector {String} (required)
• args {Object \| String} (required)

| Produces an less than operator (=lt=) | | lessthanorequal |

• selector {String} (required)
• args {Object \| String} (required)

| Produces an less than or equal operator (=le=) | | greaterthan |

• selector {String} (required)
• args {Object \| String} (required)

| Produces an greater operator (=gt=) | | greaterthanorequal |

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

• 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