A lightweight and efficient JSON querying utility for filtering and searching data
npm install fast-json-query





> A blazing-fast, MongoDB-like query engine for filtering JSON data in React applications with TypeScript support and built-in debouncing.
- ๐ Ultra-lightweight: Only 438B minified + gzipped (core), 695B (with hooks)
- โก High Performance: Optimized for large datasets with minimal overhead
- ๐ Type-safe: Full TypeScript support with comprehensive type definitions
- โ๏ธ React Integration: Seamless hooks for React applications
- ๐ Smart Debouncing: Built-in performance optimization for real-time filtering
- ๐ฆ Zero Dependencies: No external dependencies, pure JavaScript
- ๐งช Production Ready: 100% test coverage, battle-tested
- ๐ณ Tree-shakeable: Import only what you need
- ๐ Well Documented: Comprehensive documentation and examples
``bashUsing npm
npm install fast-json-query
Quick Start
`typescript
import { useJsonQuery } from 'fast-json-query';function SearchableUserList() {
const users = [
{ id: 1, name: 'John Doe', age: 30, skills: ['React', 'TypeScript'] },
{ id: 2, name: 'Jane Smith', age: 25, skills: ['Vue', 'JavaScript'] },
];
// Filter users over 25 with React skills
const results = useJsonQuery(users, {
$and: [
{ age: { $gt: 25 } },
{ skills: { $contains: 'React' } }
]
});
return (
{results.map(user => (
- {user.name} - {user.age}
))}
);
}
`Features
$3
`typescript
// Simple equality
const activeUsers = useJsonQuery(users, { status: 'active' });// Complex conditions
const seniorDevs = useJsonQuery(users, {
$or: [
{ experience: { $gt: 5 } },
{ level: { $in: ['senior', 'lead'] } }
],
skills: { $contains: 'JavaScript' }
});
`$3
`typescript
const { results, isDebouncing } = useDebounceQuery(
users,
{ name: { $regex: searchTerm } },
{ delay: 300 }
);
`API Reference
$3
#### Comparison
-
$eq: Exact match
- $gt, $gte: Greater than (or equal)
- $lt, $lte: Less than (or equal)
- $ne: Not equal
- $in: Value in array
- $nin: Value not in array
- $regex: Regular expression match
- $exists: Property existence check#### Logical
-
$and: All conditions true
- $or: Any condition true
- $not: Negate condition#### Array
-
$size: Array length check
- $contains: Array includes value$3
#### useJsonQuery
`typescript
function useJsonQuery(
data: T[],
query: Query,
options?: QueryOptions
): T[];interface QueryOptions {
caseSensitive?: boolean;
}
`#### useDebounceQuery
`typescript
function useDebounceQuery(
data: T[],
query: Query,
options?: DebounceOptions
): DebounceResult;interface DebounceOptions extends QueryOptions {
delay?: number;
}
interface DebounceResult {
results: T[];
isDebouncing: boolean;
}
`Performance
- Bundle Size: Core: 438B, Hooks: 695B (minified + gzipped)
- Memory Usage: O(1) space complexity for queries
- Time Complexity: O(n) for simple queries, optimized for large datasets
Browser Support
- Chrome, Firefox, Safari, Edge (latest 2 versions)
- IE 11 with appropriate polyfills
Contributing
We welcome contributions! Please see our Contributing Guide for details.
1. Fork the repository
2. Create your feature branch:
git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature`MIT ยฉ Md Azadur Rahman
json-query, mongodb-query, react-hooks, typescript, json-filter, data-query, react-query, json-search, typescript-query, debounce-query, lightweight-query, fast-query, react-json-query, json-query-engine, mongodb-like-query
---
Made with โค๏ธ by Md Azadur Rahman