Build, generate, parse, and evaluate LDAP filters
A library for working with Lightweight Directory Access Protocol (LDAP) filters based on RFC 4515.
Although this format is typicaly used with the LDAP protocol, this library could be implemented in other applications that need portable string-based filters for the purpose of matching object data.
npm install ldap-filters
Build a filter (programatically)
var Filter = ;var output = Filter;console;
Note: You must call the
.toString() method, to obtain the filter as a string.
Various methods can be used to build simple filters:
- .present() - tests for presence
- .equalTo(value) - tests for equality
- .contains(value) - tests if attribute contains value
- .endsWith(value) - tests if attribute ends with value
- .startsWith(value) - tests if attribute starts with value
- .approx(value) - tests if value is approximate match
- .gte(value) - tests if value is greater than or equal
- .lte(value) - tests if value is less than or equal
- .raw(value) - add an raw (escaped) attribute value
Added in 2.x The
.raw method is useful for building filters that
have complex substring matches not suitable for
.contains() — however, you will need to escape
any values that require escaping. This can be done using
Filter.escape() like so:
var match_value = '*' + Filter + '*';var filter = Filter;match_value == '*James \\28Jimmy\\29*' // true
Simple filters can be aggregated with AND, OR, and NOT:
- Filter.AND(list) - AND a list (array) of filters
- Filter.OR(list) - OR a list (array) of filters
- Filter.NOT(filter) - NOT (negate) a filter
Aggregation and nesting can be used to build complex filters.
Parse a filter
Parses a filter from a string, returning a Filter object.
var Filter = ;var input = '(&(givenName=jenny)(sn=jensen))';Filter;
Simplify a filter
.simplify() method will reduce any AND or OR filters that have only
one child/condition and replace them with that filter. NOT filters, and
any other filters will remain intact.
var input = '(&(uid=jenny))';Filter // => '(uid=jenny)'
Whether you've created a filter programatically or by parsing a filter, you
can output with
toString() method or by concatenating with a string, like so:
filter.toString() filter + ''
This will result in compacted output with no whitespace like:
If you pass a value of
true or a numeric indentation value to
toString(), the output will be beautified with space indentation.
Will result in similar output to the following:
(& (givenName=jenny) (sn=jensen) (| (c=us) (st=ontario) ) )
A value of
true will use
Filter.indent property, which defaults to 4.
The indentation character defaults to a space, see
Evaluate data against a filter
Test if (object) data matches a given filter. The filter can be one
created programatically, or parsed from a text string. A boolean
true value will be returned for a successful match.
var Filter = ;var input = '(&(givenName~=jeni)(sn=jensen))';var parsed = Filter;var data = givenName: 'Jenny' sn: 'Jensen' ;console;
A complete test suite is included. To run it, you will need to have mocha and chai installed. Mocha should be installed globally (need sudo?).
npm install -g mochanpm install chai
Tests can be run from npm or manually with mocha:
# Run tests with npmnpm test# Run tests manuallymocha test/*.js
The parser is built with pegjs. To re-build the parser, you'll need the pegjs dev dependency installed.
# Build parser with npmnpm run build# Build manually with pegjs# requires pegjs command to be availble (npm i -g pegjs)pegjs lib/parser.pegjs lib/parser.js
Version 2.x and above are using an updated original pegjs-based parser. This version offers better RFC-compliance and improved matching for complicated substring matches and escaped characters, as well as addressing some bugs found in the previous jison parser.