The odata-filter-parser library is a lightweight library used for the serialization and deserialization of odata $filter
strings into a JavasScript object structure. This is used by several projects under the stamp-web organization both with NodeJS server modules (stamp-webservices) and client applications (stamp-web-aurelia). If others find it of use they are more than welcome to leverage it, but support will be limited. Please see the list of Operators below that are supported as well as Functions
This library is compatible with the $filter syntax for V2 through V4 of OData but only supports as subset of functions and behaviors.
Using the provided objects can be achieved using the require syntax. By default, the required module odata-filter-parser
returns three objects:
- Operators (singleton)
- Predicate
- Parser (singleton)
Only the Predicate
provides a constructor that can be used with new Predicate()
. To include the module use the following syntax:
var odataFilter = require('odata-filter-parser');
Or if only one of the objects is needed, you can access it directly:
var parser = require('odata-filter-parser').Parser;
The following list of OData operators are supported by the parser and predicates
Operator constant | OData operator | Comments |
---|---|---|
EQUALS | eq | equality evaluation |
AND | and | logical and operation |
OR | or | logical _or_ operation |
GREATHER_THAN | gt | greater than evaluation exclusive |
GREATER_THAN_EQUAL | ge | greater than evaluation inclusive |
LESS_THAN | lt | less than evaluation exclusive |
LESS_THAN_EQUAL | le | less than evaluation inclusive |
LIKE | like | like expression |
IS_NULL | is null | null or empty statement |
NOT_EQUAL | ne | non-equality evaluation |
There are also a few functions available on Operators:
Whether the operator only involves one reference to return a boolean result. Operators.IS_NULL
is an example of a unary operation.
Whether the operator is used for logical "gate" operations such as Operators.AND
and Operators.OR
The Predicate is a simple object with particular values and provides some useful utility functions for operating on the Predicate.
This is the primary use-case of the predicate which is the facilitate the serialization of the Predicate to a value OData filter string.
For compatibility all predicates will be wrapped by ()
to ensure cleaner processing and parsing by this library or other libraries.
var p = new Predicate( {
subject: 'name',
operator: Operators.EQUALS,
value: 'Jerry'
});
var s = p.serialize();
will result in s
being the value (name eq 'Jerry')
The flatten function will take a Predicate and will return and array of Predicates. If the Predicate represents a logical operator such as Operators.OR
or
Operators.AND
it will use the subject and value of these predicates in a recursive fashion.
{
subject: {
subject: 'name',
operator: 'eq',
value: 'Serena'
},
operator: 'and',
value: {
subject: 'age',
operator: 'lt',
value: 5
}
}
will result in the following output (where each object in the array is a Predicate):
[
{
subject: 'name',
operator: 'eq',
value: 'Serena'
}, {
subject: 'age',
operator: 'lt',
value: 5
}
]
The parser is used to convert a string value representing a OData $filter string and convert this into a valid Predicate object (structure).
Will parse the string and convert it to a Predicate
object. The object returned will be nested based on the structure of the $filter string.
If the filter string is null or empty, a value of null
will be returned. When a predicate is created from the filter string, if the subject is not another
predicate it will be encoded as a string. The value will be encoded either as a Predicate (for logical operations), a string, number or boolean.
Given a string name eq 'Bob
the parse will result in a Predicate that looks like the following:
{
subject: 'name',
operator: 'eq',
value: 'Bob'
}
Given the string ((name eq 'Serena') and (age lt 5))
the resulting Predicate looks like:
{
subject: {
subject: 'name',
operator: 'eq',
value: 'Serena'
},
operator: 'and',
value: {
subject: 'age',
operator: 'lt',
value: 5
}
}