@medyll/idae-query
v0.186.3
Published
A powerful and flexible query library for TypeScript and JavaScript applications, featuring a MongoDB-like query interface, strong TypeScript support, and easy integration with front-end frameworks.
Maintainers
Readme
@medyll/idae-query
A powerful and flexible query library for TypeScript and JavaScript applications.
Features
- Chainable and iterable result sets
- Sorting, grouping, and pagination support
- Dot path resolution for nested properties
- Integration with
@medyll/idae-enginefor data operations - Advanced filtering with
filter(),map(),distinct(),reverse() - Numeric aggregations with
sum(),avg(),min(),max() - Data extraction with
pluck(),reduce(),first(),last() - Flexible counting with optional filtering via
count() - Full TypeScript support with type-safe aggregations
- Dot-path support for nested property access on all methods
Key Features
Rich Method Toolkit
- 13+ chainable methods for data manipulation and transformation
- Fluent API - Chain operations for clean, readable code
- Type-safe aggregations - TypeScript prevents operations on incompatible types
- Dot-path resolution - Access nested properties with string paths (e.g.,
'metadata.order') - Zero dependencies - Lightweight and efficient
- Full test coverage - 79 comprehensive unit tests
Method Categories
Transformation Methods (chainable)
filter()- Filter by predicatemap()- Transform itemsdistinct()- Remove duplicatesreverse()- Reverse order
Aggregation Methods (numeric, with dot-path support)
sum(),avg(),min(),max()- Statistical operations
Utility Methods (terminal operations)
count(),pluck(),reduce(),first(),last()- Extraction and reduction
Original Methods
sortBy(),groupBy(),getPage()- Sorting, grouping, pagination
Installation
npm install @medyll/idae-queryQuick Start
Here's a quick example to get you started:
import { Query } from '@medyll/idae-query';
const data = [
{ id: 1, name: 'John', age: 25, metadata: { order: 1 } },
{ id: 2, name: 'Jane', age: 30, metadata: { order: 2 } },
{ id: 3, name: 'Bob', age: 35, metadata: { order: 3 } },
{ id: 4, name: 'Alice', age: 40, metadata: { order: 4 } },
];
const query = new Query(data);
// Filtering with where()
const adults = query.where({ age: { gte: 30 } });
// Sorting
const sortedData = adults.sortBy({ age: 'asc' });
// Grouping
const groupedData = adults.groupBy('age');
// Pagination
const pageData = adults.getPage(1, 2);
console.log(sortedData);
console.log(groupedData);
console.log(pageData);API
Operators Demo
Query Operators Usage
Advanced Usage
Multi-criteria Sorting
const query = new Query(data);
const sorted = query.where({}).sortBy({ age: 'asc', name: 'desc' });
// Sort first by age ascending, then by name descendingGrouping by Nested Property
const query = new Query(data);
const grouped = query.where({}).groupBy('metadata.order');
// Groups by the nested property metadata.orderPagination
const query = new Query(data);
const resultSet = query.where({});
const page1 = resultSet.getPage(1, 2); // Page 1, 2 items
const page2 = resultSet.getPage(2, 2); // Page 2, 2 itemsNew Methods Overview
The library now includes 13 powerful methods for data manipulation:
Transformation Methods (Chainable - return ResultSet<T>)
filter(predicate: (item: T) => boolean): ResultSet<T>
const adults = resultSet.filter((item) => item.age >= 18);
const filtered = resultSet.filter((item) => item.age > 25).sortBy({ name: 'asc' });map<U>(mapper: (item: T) => U): ResultSet<U>
const transformed = resultSet.map((item) => ({
name: item.name,
isAdult: item.age >= 18
}));distinct(key?: DotPath<T>): ResultSet<T>
const unique = resultSet.distinct(); // Remove exact duplicates
const uniqueByAge = resultSet.distinct('age'); // By field
const uniqueByOrder = resultSet.distinct('metadata.order'); // By dot-pathreverse(): ResultSet<T>
const reversed = resultSet.reverse();
const reversedAndSorted = resultSet.reverse().sortBy({ age: 'asc' });Aggregation Methods (Numeric operations with dot-path support)
sum(field: DotPath<T>): number - Sum all values in a numeric field
const totalAge = resultSet.sum('age');
const totalDiscount = resultSet.sum('metadata.discount');avg(field: DotPath<T>): number - Calculate average of numeric values
const averageAge = resultSet.avg('age');min(field: DotPath<T>): number - Get minimum numeric value
const youngest = resultSet.min('age');max(field: DotPath<T>): number - Get maximum numeric value
const oldest = resultSet.max('age');Utility Methods (Terminal operations)
count(criteria?: Where<T>): number - Count items with optional filtering
const total = resultSet.count();
const adultsCount = resultSet.count({ age: { gt: 18 } });
const filtered = resultSet.count({ name: { contains: 'John' } });pluck(field: DotPath<T>): any[] - Extract array of field values
const ages = resultSet.pluck('age'); // [25, 30, 35, 40]
const orders = resultSet.pluck('metadata.order'); // Dot-path supportreduce<U>(reducer: (acc: U, item: T) => U, initialValue: U): U - Custom reduction
const ageMap = resultSet.reduce((acc, item) => {
acc[item.name] = item.age;
return acc;
}, {});
const totalAge = resultSet.reduce((sum, item) => sum + item.age, 0);first(): T | undefined - Get first item
const first = resultSet.filter((x) => x.age > 30).first();last(): T | undefined - Get last item
const last = resultSet.sortBy({ age: 'desc' }).last();Advanced Usage Examples
Chaining Operations
const query = new Query(data);
// Multi-step transformation
const result = query
.where({ age: { gt: 25 } })
.sortBy({ age: 'asc' })
.pluck('name'); // ['Jane', 'Bob', 'Alice']Statistical Analysis
const query = new Query(data);
const resultSet = query.where({});
// Calculate statistics on data
const stats = {
total: resultSet.count(),
adults: resultSet.count({ age: { gte: 18 } }),
averageAge: resultSet.avg('age'),
minAge: resultSet.min('age'),
maxAge: resultSet.max('age'),
};Data Transformation Pipeline
const query = new Query(data);
// Build a summary report
const report = query
.where({ age: { gte: 18 } })
.reduce((acc, item) => {
acc.total++;
acc.ages.push(item.age);
acc.names.push(item.name);
return acc;
}, { total: 0, ages: [], names: [] });Distinct with Filtering
const query = new Query(data);
// Find unique categories
const uniqueMetadata = query
.where({})
.distinct('metadata.order')
.pluck('metadata.order');Combined Examples
const query = new Query(data);
const resultSet = query.where({});
// Sorting and grouping
const sorted = resultSet.sortBy({ age: 'asc' }).groupBy('age');
// Pagination with filtering
const page = query
.where({ age: { gt: 25 } })
.getPage(1, 10);
// Complex query chain
const summary = {
count: resultSet.count({ age: { gt: 30 } }),
names: query
.where({ age: { gt: 30 } })
.pluck('name'),
maxAge: resultSet.max('age'),
};All operators are accessed through Query (primary API). ResultSet is returned by Query.where() and shouldn’t be used directly.
Query Operators Reference
import { Query, Operators } from '@medyll/idae-query';
const data = [
{ id: 1, name: 'John', age: 25 },
{ id: 2, name: 'Jane', age: 30 },
{ id: 3, name: 'Bob', age: 35 },
];
const query = new Query(data);
// eq - equals
const eqResult = query.where({ age: { eq: 30 } }); // [{ id: 2, name: 'Jane', age: 30 }]
// gt - greater than
const gtResult = query.where({ age: { gt: 25 } }); // [{ id: 2, name: 'Jane', age: 30 }, { id: 3, name: 'Bob', age: 35 }]
// gte - greater than or equal
const gteResult = query.where({ age: { gte: 30 } }); // [{ id: 2, name: 'Jane', age: 30 }, { id: 3, name: 'Bob', age: 35 }]
// lt - less than
const ltResult = query.where({ age: { lt: 30 } }); // [{ id: 1, name: 'John', age: 25 }]
// lte - less than or equal
const lteResult = query.where({ age: { lte: 30 } }); // [{ id: 1, name: 'John', age: 25 }, { id: 2, name: 'Jane', age: 30 }]
// ne - not equal
const neResult = query.where({ age: { ne: 25 } }); // [{ id: 2, name: 'Jane', age: 30 }, { id: 3, name: 'Bob', age: 35 }]
// in - value in array
const inResult = query.where({ age: { in: [25, 35] } }); // [{ id: 1, name: 'John', age: 25 }, { id: 3, name: 'Bob', age: 35 }]
// nin - value not in array
const ninResult = query.where({ age: { nin: [25, 35] } }); // [{ id: 2, name: 'Jane', age: 30 }]
// contains - string contains
const containsResult = query.where({ name: { contains: 'an' } }); // [{ id: 2, name: 'Jane', age: 30 }]
// startsWith - string starts with
const startsWithResult = query.where({ name: { startsWith: 'Ja' } }); // [{ id: 2, name: 'Jane', age: 30 }]
// endsWith - string ends with
const endsWithResult = query.where({ name: { endsWith: 'hn' } }); // [{ id: 1, name: 'John', age: 25 }]
// btw - between (inclusive)
const btwResult = query.where({ age: { btw: [25, 35] } }); // [{ id: 1, name: 'John', age: 25 }, { id: 2, name: 'Jane', age: 30 }, { id: 3, name: 'Bob', age: 35 }]
// Combined operators
const combinedResult = query.where({ age: { gt: 15, lt: 35 } }); // [{ id: 1, name: 'John', age: 25 }, { id: 2, name: 'Jane', age: 30 }]
// Custom operator
Operators.addCustomOperator('isEven', (field, value, data) => data[field] % 2 === 0);
const customResult = query.where({ age: { isEven: true } }); // [{ id: 2, name: 'Jane', age: 30 }]API
Query<T>
Primary entry point for building queries. Query owns the dataset and exposes where() to return a ResultSet for chaining transformations and aggregations. It is the intended public API.
getResultset(data: any[]): ResultSet
Low-level helper that creates a new result set from the provided data. Prefer Query in application code.
ResultSet<T>
Chainable result set returned by Query.where(). It isn’t intended to be used directly.
Transformation Methods (Chainable)
filter(predicate: (item: T) => boolean): ResultSet<T>- Filter items by predicate functionmap<U>(mapper: (item: T) => U): ResultSet<U>- Transform items using mapper functiondistinct(key?: DotPath<T>): ResultSet<T>- Remove duplicate items, optionally by key with dot-path supportreverse(): ResultSet<T>- Reverse the order of items
Aggregation Methods (Numeric, dot-path supported)
sum(field: DotPath<T>): number- Sum numeric values of a fieldavg(field: DotPath<T>): number- Calculate average of numeric valuesmin(field: DotPath<T>): number- Get minimum numeric valuemax(field: DotPath<T>): number- Get maximum numeric value
Utility Methods (Terminal Operations)
count(criteria?: Where<T>): number- Count items, optionally filtered by criteriapluck(field: DotPath<T>): any[]- Extract values of a field with dot-path supportreduce<U>(reducer: (acc: U, item: T) => U, initialValue: U): U- Reduce items to a single valuefirst(): T | undefined- Get first item or undefinedlast(): T | undefined- Get last item or undefined
Original Methods (Sorting, Grouping, Pagination)
setOptions(options: ResultsetOptions): ResultSet- Sets options for the result setsortBy(sortOptions: Record<DotPath, 'asc' | 'desc'>): ResultSet- Sorts the result set by the specified options (supports multi-criteria and dot-path)groupBy(groupBy: DotPath, keepUngroupedData?: boolean): Record<string, any[]>- Groups the result set by the specified propertygetPage(page: number, pageSize: number): ResultSet- Gets the specified page of data
Testing
To run the tests:
- Clone the repository
- Install dependencies:
pnpm installoryarn install - Run tests:
pnpm testoryarn test
The tests cover various scenarios for each method, ensuring the reliability and correctness of the ResultSet class.
Architecture
flowchart LR
Data[Array of Objects] --> RS[getResultset]
RS --> Query[Query Engine]
subgraph Engine [Processing]
Query --> Op[Operators $eq, $gt...]
RS --> Path[PathResolver]
RS --> Sort[Sorting]
RS --> Page[Pagination]
end
Page --> Final[Resultset Output]License
This project is licensed under the MIT License.
Author: Lebrun Meddy (@medyll)
