A flexible query parameter parser and serializer for building complex filters, sorting, and pagination in web applications. Extended from Refine's CRUD operators to support Go backend compatibility.
npm install @lumeweb/query-builderA flexible query parameter parser and serializer for building complex filters, sorting, and pagination in web applications. Extended from Refine's CRUD operators to support Go backend compatibility.
- Query Parsing - Parse URL query parameters into structured filter, sort, and pagination objects
- Query Serialization - Convert structured query objects back to URL-friendly parameters
- Rich Filter Operators - Support for comparison operators (eq, ne, lt, gt, contains, etc.) and logical operators (and, or, not)
- Type-Safe - Full TypeScript support with exported types
- Refine Compatible - Works seamlessly with @refinedev/core types
- Go Backend Compatible - Extended operators include "not" for Go queryutil compatibility
``bash`
pnpm add @lumeweb/query-builder
`typescript
import { parseQueryParams } from "@lumeweb/query-builder";
const params = {
"filters[0][field]": "name",
"filters[0][operator]": "contains",
"filters[0][value]": ["John", "Doe"],
"filters[1][field]": "status",
"filters[1][operator]": "eq",
"filters[1][value]": "active",
"filters[2][operator]": "or",
"filters[2][value][0][field]": "department",
"filters[2][value][0][operator]": "eq",
"filters[2][value][0][value]": "sales",
"filters[2][value][1][field]": "engineering",
"filters[2][value][1][operator]": "eq",
"filters[2][value][1][value]": true,
"_sort": "createdAt",
"_order": "desc",
"_start": "0",
"_end": "20"
};
const parsed = parseQueryParams(params);
// Returns ParsedQuery with filters, sorters, and pagination
`
`typescript
import { serializeQueryParams } from "@lumeweb/query-builder";
const query = {
filters: [
{
field: "status",
operator: "eq",
value: "active"
}
],
sorters: [
{
field: "createdAt",
order: "desc"
}
],
pagination: {
start: 0,
end: 20
}
};
const params = serializeQueryParams(query);
// Returns URL-friendly query parameters
`
`typescript
import {
createEqFilter,
createContainsFilter,
createInFilter,
addFilter,
mergeFilters
} from "@lumeweb/query-builder";
// Create individual filters
const nameFilter = createEqFilter("name", "John");
const titleFilter = createContainsFilter("title", "Manager");
const statusFilter = createInFilter("status", ["active", "pending"]);
// Add filters to a collection
let filters: CrudFilter[] = [];
filters = addFilter(filters, nameFilter);
// Merge multiple filters
const merged = mergeFilters([nameFilter, statusFilter]);
`
`typescript
import {
createAscSort,
createDescSort,
toggleSort,
addSorter
} from "@lumeweb/query-builder";
// Create sort configurations
const nameAsc = createAscSort("name");
const createdDesc = createDescSort("createdAt");
// Toggle sort direction
const toggled = toggleSort(nameAsc); // becomes desc
// Add to sorters array
let sorters: CrudSort[] = [];
sorters = addSorter(sorters, nameAsc);
`
`typescript
import {
calculatePagination,
getTotalPages,
getNextPage,
getPrevPage,
hasNextPage,
hasPrevPage
} from "@lumeweb/query-builder";
const pagination = calculatePagination(2, 25); // page 2, 25 per page
// Returns: { start: 25, end: 50, page: 2, pageSize: 25 }
const totalItems = 100;
const pageSize = 20;
// Get total pages
const total = getTotalPages(totalItems, pageSize); // 5
// Navigate using pagination object
const next = getNextPage(pagination); // 3 (next page number)
const prev = getPrevPage(pagination); // 1 (previous page number)
// Check if more pages exist
const hasNext = hasNextPage(totalItems, pagination); // true
const hasPrev = hasPrevPage(pagination); // true
`
- QueryParams - URL query parameter structureParsedQuery
- - Parsed result with filters, sorters, and paginationCrudFilter
- - Union type for LogicalFilter and ConditionalFilterLogicalOperator
- - "and" | "or" | "not"FieldOperator
- - Comparison operators (eq, ne, lt, lte, gt, gte, contains, etc.)Pagination
- - Pagination parametersCrudSort
- - Sort configuration (re-exported from @refinedev/core)
- GLOBAL_SEARCH_FIELD - "q"FILTER_PREFIX
- - "filters"SORT_PARAM
- - "_sort"ORDER_PARAM
- - "_order"START_PARAM
- - "_start"END_PARAM
- - "_end"
Comparison operators: eq, ne, lt, lte, gt, gte, in, nin, ina, nina, contains, ncontains, containss, ncontainss, between, nbetween, null, nnull, startswith, nstartswith, startswiths, nstartswiths, endswith, nendswith, endswiths, nendswiths
Logical operators: and, or, not
`bashBuild
pnpm run build
Contributions are welcome! Please submit pull requests to the main repository.
See LICENSE file for details.