Object Query Builder

🧩 A powerful, type-safe SQL-like query builder for JavaScript objects

· English · Korean

✨ Features

🎨 Fluent API - Chainable methods for readable queries
🎯 SQL-like Syntax - Familiar query syntax for filtering, sorting, and joining
🔧 Extensible - Easy to add custom functionality
🔒 Type-Safe - Full TypeScript support with generics
⚡ High Performance - Optimized algorithms (O(n) joins with Map)
📦 Zero Dependencies - Pure TypeScript, no external dependencies
🚀 Modern Build - Dual CJS/ESM support with tsup

🚀 Installation

npm install object-querybuilder

yarn add object-querybuilder

pnpm add object-querybuilder

📖 Quick Start

TypeScript

import QueryBuilder from 'object-querybuilder';

interface User {
    name: string;
    age: number;
    gender: string;
}

const users: User[] = [
    { name: 'Lucy', age: 23, gender: 'woman' },
    { name: 'Emma', age: 31, gender: 'woman' },
    { name: 'Daniel', age: 18, gender: 'man' },
    { name: 'Olivia', age: 42, gender: 'woman' },
    { name: 'Alex', age: 33, gender: 'man' }
];

const result = QueryBuilder.create<User>()
    .select(['name', 'age'])
    .from(users)
    .where('age', '>', 25)
    .where('gender', '=', 'woman')
    .orderBy('age', 'desc')
    .run();

console.log(result);
// Output: [
//   { name: 'Olivia', age: 42 },
//   { name: 'Emma', age: 31 }
// ]

JavaScript (CommonJS)

const QueryBuilder = require('object-querybuilder').default;

const users = [
    { name: 'Lucy', age: 23, gender: 'woman' },
    { name: 'Emma', age: 31, gender: 'woman' }
];

const result = QueryBuilder.create()
    .select(['*'])
    .from(users)
    .where('age', '>', 25)
    .run();

JavaScript (ESM)

import QueryBuilder from 'object-querybuilder';

const result = QueryBuilder.create()
    .select(['name', 'age'])
    .from(users)
    .orderBy('age', 'asc')
    .limit(5)
    .run();

📚 API Reference

Core Query Methods

Method	Description	Example
`select(fields)`	Specify fields to return (`['*']` for all)	`.select(['name', 'age'])`
`from(data)`	Set data source (array or single object)	`.from(users)`
`where(key, op, value)`	Filter by condition	`.where('age', '>', 25)`
`whereIn(key, values)`	Filter by array inclusion	`.whereIn('status', ['active', 'pending'])`
`whereNotIn(key, values)`	Filter by array exclusion	`.whereNotIn('role', ['admin'])`
`orderBy(key, order)`	Sort results (asc/desc)	`.orderBy('age', 'desc')`
`orderByMultiple(criteria)`	Sort by multiple fields	`.orderByMultiple([{key: 'dept', order: 'asc'}])`
`limit(count)`	Limit number of results	`.limit(10)`
`offset(count)`	Skip number of results	`.offset(20)`
`distinct()`	Remove duplicates	`.distinct()`
`run()`	Execute query and return results	`.run()`

Join Methods

Method	Description	Example
`join(data, key)`	Inner join on common key	`.join(addresses, 'userId')`
`leftJoin(data, key)`	Left outer join	`.leftJoin(addresses, 'userId')`

Aggregation Methods

Method	Description	Example
`count()`	Count results	`.count()`
`aggregate(func, key)`	Apply function (sum, avg, min, max)	`.aggregate('sum', 'salary')`
`groupBy(key)`	Group results by field	`.groupBy('department')`
`first()`	Get first result	`.first()`
`last()`	Get last result	`.last()`

Utility Methods

Method	Description	Example
`clone()`	Create independent copy	`.clone()`

Supported Operators

Operator	Description	Example
`>`	Greater than	`.where('age', '>', 25)`
`<`	Less than	`.where('price', '<', 100)`
`>=`	Greater than or equal	`.where('score', '>=', 90)`
`<=`	Less than or equal	`.where('stock', '<=', 10)`
`=`	Equal	`.where('status', '=', 'active')`
`!=`	Not equal	`.where('type', '!=', 'draft')`
`like`	Pattern matching (%, _)	`.where('email', 'like', '%@gmail.com')`

💡 Examples

Basic Filtering

// Single condition
QueryBuilder.create()
    .select(['*'])
    .from(products)
    .where('price', '<', 100)
    .run();

// Multiple conditions (chained)
QueryBuilder.create()
    .select(['*'])
    .from(users)
    .where('age', '>=', 18)
    .where('status', '=', 'active')
    .whereIn('role', ['user', 'moderator'])
    .run();

Pattern Matching

// Find emails from Gmail
QueryBuilder.create()
    .from(users)
    .where('email', 'like', '%@gmail.com')
    .run();

// Find names starting with 'A'
QueryBuilder.create()
    .from(users)
    .where('name', 'like', 'A%')
    .run();

// Find names containing 'son'
QueryBuilder.create()
    .from(users)
    .where('name', 'like', '%son%')
    .run();

Joining Data

const users = [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
];

const orders = [
    { userId: 1, product: 'Laptop', amount: 1200 },
    { userId: 1, product: 'Mouse', amount: 25 },
    { userId: 2, product: 'Keyboard', amount: 75 }
];

// Inner join (only matching records)
const result = QueryBuilder.create()
    .from(users)
    .join(orders, 'userId')
    .run();

// Left join (all users, even without orders)
const result = QueryBuilder.create()
    .from(users)
    .leftJoin(orders, 'userId')
    .run();

Pagination

const PAGE_SIZE = 10;
const currentPage = 3;

const result = QueryBuilder.create()
    .select(['*'])
    .from(items)
    .orderBy('createdAt', 'desc')
    .limit(PAGE_SIZE)
    .offset((currentPage - 1) * PAGE_SIZE)
    .run();

Aggregation & Analytics

const sales = [
    { product: 'Laptop', price: 1200, quantity: 5 },
    { product: 'Mouse', price: 25, quantity: 50 },
    { product: 'Keyboard', price: 75, quantity: 20 }
];

// Total revenue
const total = QueryBuilder.create()
    .from(sales)
    .aggregate('sum', 'price');
// Result: 1300

// Average price
const avg = QueryBuilder.create()
    .from(sales)
    .aggregate('avg', 'price');
// Result: 433.33

// Most expensive item
const max = QueryBuilder.create()
    .from(sales)
    .aggregate('max', 'price');
// Result: 1200

// Group by and count
const grouped = QueryBuilder.create()
    .from(orders)
    .groupBy('status');
// Result: { 'pending': [...], 'completed': [...], 'cancelled': [...] }

Sorting

// Single field
QueryBuilder.create()
    .from(products)
    .orderBy('price', 'desc')
    .run();

// Multiple fields
QueryBuilder.create()
    .from(employees)
    .orderByMultiple([
        { key: 'department', order: 'asc' },
        { key: 'salary', order: 'desc' },
        { key: 'name', order: 'asc' }
    ])
    .run();

Advanced Use Cases

// Find top 5 most expensive products in Electronics
QueryBuilder.create()
    .select(['name', 'price', 'rating'])
    .from(products)
    .where('category', '=', 'Electronics')
    .where('inStock', '=', true)
    .orderBy('price', 'desc')
    .limit(5)
    .run();

// Get unique active users who made purchases
QueryBuilder.create()
    .select(['userId', 'username'])
    .from(transactions)
    .where('status', '=', 'completed')
    .whereIn('userId', activeUserIds)
    .distinct()
    .run();

// Reusable query with cloning
const baseQuery = QueryBuilder.create()
    .from(users)
    .where('status', '=', 'active');

const adults = baseQuery.clone()
    .where('age', '>=', 18)
    .run();

const minors = baseQuery.clone()
    .where('age', '<', 18)
    .run();

🎯 Use Cases

Frontend Data Filtering - Filter API responses in browser
Testing - Mock database queries without actual DB
Data Processing - Transform and analyze in-memory data
Prototyping - Quick data manipulation without backend
Report Generation - Aggregate and summarize data
ETL Operations - Extract, transform, load data pipelines

🤝 Contributing

Contributions are always welcome! Please feel free to open an issue or submit a pull request.

💳 License

MIT

Made with ❤️ by AGUMON 🦖

ljlm0402/object-querybuilder

Object Query Builder

🧩 A powerful, type-safe SQL-like query builder for JavaScript objects

✨ Features

🚀 Installation

📖 Quick Start

TypeScript

JavaScript (CommonJS)

JavaScript (ESM)

📚 API Reference

Core Query Methods

Join Methods

Aggregation Methods

Utility Methods

Supported Operators

💡 Examples

Basic Filtering

Pattern Matching

Joining Data

Aggregation & Analytics

Sorting

Advanced Use Cases

🎯 Use Cases

🤝 Contributing

💳 License

On this page

Languages

Contributors

Latest Release