Fast JSON Query


> A blazing-fast, MongoDB-like query engine for filtering JSON data in React applications with TypeScript support and built-in debouncing.

Why Fast JSON Query?

- 🚀 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

Installation

``bash


Using npm

npm install fast-json-query

Using yarn

yarn add fast-json-query

Using pnpm

pnpm add 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`
5. Open a Pull Request

License

MIT © Md Azadur Rahman

Keywords

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