@flatfile/filter-builder

Flatfile Filter Builder

Purpose

All of the filtering/sorting/pagination capabilities in X currently operate through use of dedicated url parameters. e.g. GET records?sortField=first_name&sortDirection=asc&filterField=last_name&filter=error&versionId=dev_vr_123456. This has proven cumbersome to use, difficult to maintain, and lacking in the flexibility needed by our end users. The goal of filter-builder is to replace these url parameters with a structured, queryable, consistent filtering pattern that can be used across the application and expanded ad infinitum.

Implementation

filter-builder introduces several new patterns.

The first pattern is that of the Filter object. This object contains all the necessary information needed to filter, sort, and paginate a record set. Filter establishes a strict contract that the ephemeral module can expect and parse in a consistent manner.

The second pattern is that of the Flatfile Query Language (FFQL). FFQL is a strict, logical query language that can be parsed into a Filter object. The query language operates as follow:

// Old Filtering...
GET records?sortField=first_name&sortDirection=asc&filterField=last_name&filter=error&versionId=dev_vr_123456

// New Filtering using FFQL
GET records?q=last_name is error&sort=first_name asc&versionId=dev_vr_123456

FFQL is extensible and fully logically parsable, opening up previously unsupported techniques:

GET records?q=((age gte 18 and age lte 65) or first_name eq Bender) and is error

The following operations are supported:

// Data Filter Operators
'eq' | 'ne' | 'gte' | 'gt' | 'lt' | 'lte' | 'like'

// Message Filter Operators
'is'

// Message Filter Statuses
'error' | 'warning' | 'info' | 'valid'

// Logical Filter Operators
'and' | 'or'

Notes

The filter-builder package is complete and has 100% test coverage, but has not been implemented anywhere in the application at this time. Forward rolling changes will need to take into account backwards compatibility and multiple ephemeral storage strategies.