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

``bash
$ npm install fiql-query-builder
`

Usage

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

$3

`js

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

$3

`js

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

$3

#### Example standard basic operator
`js
var eqJson = convertFromJson({
equals : {
selector: 'foo',
args: 'bar'
}
});
// eqJson = foo==bar
`

#### Example custom basic operator
`js
var customOperatorJson = convertFromJson({
custom_operator : {
operator: '¬',
selector: 'foo',
args: 'bar'
}
});
// customOperatorJson equals: foo¬bar
`

#### Example standard boolean expression
`js
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
`js
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
`js
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)
`

$3

#### Example standard basic operator
`js
var eqNode = convertFromNode(
new EqNode(
new LeafNode('foo'),
new LeafNode('bar')
)
);
// eqNode = foo==bar
`

#### Example custom basic operator
`js
var customOperatorNode = convertFromNode(
new OpNode(
new LeafNode('foo'),
'¬',
new LeafNode('bar')
)
);
// customOperatorNode equals: foo¬bar
`

#### Example standard boolean expression
`js
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
`js
var customExpressionNode = convertFromNode(
new ExpNode('*', [
new EqNode('foo', 'bar'),
new NeqNode('baz', 'qux')
])
);
// customExpressionNode equals: foo==bar*baz!=qux
`

#### Example grouping and nested arguments
`js
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