@andreasnicolaou/query-builder

@andreasnicolaou/query-builder

A flexible, type-safe query builder for constructing complex conditional expressions with support for nested groups, various operators, and function calls.

Note: This is not an ORM and does not execute queries or connect to any database. It's a serialization and expression-building utility, ideal for building advanced search/filter UIs, custom DSLs, or backend query engines.

Demo

You can try this library live:

👉 Interactive Demo on StackBlitz

Features

• Chainable builder API
• Supports multiple operator types (logical, comparison, set, etc.)
• Nested condition grouping
• Type-safe with TypeScript
• Serializable to JSON
• Human-readable string output

Package Managers

# npm
npm install @andreasnicolaou/query-builder

# yarn
yarn add @andreasnicolaou/query-builder

# pnpm
pnpm add @andreasnicolaou/query-builder

CDN Usage

For direct browser usage without a build step:

<!-- unpkg CDN (latest version, unminified) -->
<script src="https://unpkg.com/@andreasnicolaou/query-builder/dist/index.umd.js"></script>

<!-- unpkg CDN (latest version, minified) -->
<script src="https://unpkg.com/@andreasnicolaou/query-builder/dist/index.umd.min.js"></script>

<!-- jsDelivr CDN (unminified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/query-builder/dist/index.umd.js"></script>

<!-- jsDelivr CDN (minified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/query-builder/dist/index.umd.min.js"></script>

Usage Examples

ES Modules (Recommended)

import { QueryBuilder } from '@andreasnicolaou/query-builder';

const qb = new QueryBuilder();
qb.where('name', 'ilike', '%andreas%');
console.log(qb.toString());

CommonJS

const { QueryBuilder } = require('@andreasnicolaou/query-builder');

const qb = new QueryBuilder();
qb.where('age', '>', 30);
console.log(qb.toString());

Browser (UMD via CDN)

<!-- Use .umd.js for debugging, .umd.min.js for production -->
<script src="https://unpkg.com/@andreasnicolaou/query-builder/dist/index.umd.min.js"></script>
<script>
  // The global variable is 'queryBuilder'
  const qb = new queryBuilder.QueryBuilder();
  qb.where('active', '=', true);
  alert(qb.toString());
</script>

Browser (ES Modules via CDN)

<script type="module">
  import { QueryBuilder } from 'https://unpkg.com/@andreasnicolaou/query-builder/dist/index.js';

  const qb = new QueryBuilder();
  qb.where('role', 'in', ['admin', 'user']);
  console.log(qb.toString());
</script>

TypeScript

// Full type safety and IntelliSense support
import { QueryBuilder, QueryBuilderSerialized } from '@andreasnicolaou/query-builder';

const qb: QueryBuilder = new QueryBuilder();
// ...

Basic Usage

import { QueryBuilder } from '@andreasnicolaou/query-builder';

const query = new QueryBuilder()
  .where('name', 'ilike', '%andreas%') // Case-insensitive search
  .where('age', 'between', [18, 65], 'and') // Age range
  .where('email', 'is not null', undefined, 'and') // Email required
  .group((qb) => {
    qb.where('status', 'in', ['active', 'pending']).where('created', '>', new Date('2025-01-01').toISOString());
  })
  .toString();

console.log(query);
// name ilike '%andreas%' and age between 18 and 65 and email is not null and (status in ('active', 'pending') and created > '2025-01-01T00:00:00.000Z')

Skipping Empty or Invalid Values

import { QueryBuilder } from '@andreasnicolaou/query-builder';

const query = new QueryBuilder()
  .skipWhen({ emptyString: true, emptyArray: true })
  .where('name', '===', '')
  .where('age', '>', 36)
  .where('tags', 'in', [])
  .toString();

console.log(query); // age > 36

UI-Focused Examples

Advanced Search Form

// Perfect for building complex search UIs
const searchQuery = new QueryBuilder()
  .where('title', 'ilike', '%react%') // Case-insensitive title search
  .where('price', 'between', [10, 100], 'and') // Price range
  .where('category', 'in', ['books', 'electronics'], 'and') // Multiple categories
  .group((nested) => {
    nested
      .where('rating', '>=', 4) // High rated
      .where('featured', '=', true, 'or'); // OR featured items
  }, 'and');

// Result: title ilike '%react%' and price between 10 and 100 and category in ('books', 'electronics') and (rating >= 4 or featured = true)

User Profile Filters

// Handle optional and required fields elegantly
const userQuery = new QueryBuilder()
  .skipWhen({ emptyString: true, null: false }) // Allow explicit nulls
  .where('email', 'is not null') // Email required
  .where('firstName', 'like', 'John%', 'and') // Starts with John
  .where('lastName', 'is not empty', undefined, 'and') // Last name provided
  .where('age', 'between', [18, 99], 'and') // Adult users
  .where('deletedAt', 'is null', undefined, 'and'); // Active users only

// Result: email is not null and firstName like 'John%' and lastName is not empty and age between 18 and 99 and deletedAt is null

UI Validation & Error Handling

import { QueryBuilder } from '@andreasnicolaou/query-builder';

// Validate user input before building queries
function buildSearchQuery(formData: any) {
  const errors: string[] = [];

  // Validate age range
  if (formData.ageMin && formData.ageMax) {
    const validation = QueryBuilder.validateOperator('between', [formData.ageMin, formData.ageMax]);
    if (!validation.valid) {
      errors.push(`Age range: ${validation.error}`);
    }
  }

  // Validate category selection
  if (formData.categories && formData.categories.length > 0) {
    const validation = QueryBuilder.validateOperator('in', formData.categories);
    if (!validation.valid) {
      errors.push(`Categories: ${validation.error}`);
    }
  }

  if (errors.length > 0) {
    throw new Error(`Validation errors: ${errors.join(', ')}`);
  }

  // Build query after validation
  return new QueryBuilder()
    .skipWhen({ emptyString: true, emptyArray: true })
    .where('name', 'ilike', `%${formData.search}%`)
    .where('age', 'between', [formData.ageMin, formData.ageMax])
    .where('category', 'in', formData.categories);
}

API

Core Methods

Method	Description
.where(field, operator, value?, logicalOperator?)	Add a condition with any operator
.group(callback, logicalOperator?)	Create nested conditions (groups)
.skipWhen(options?)	Configure automatic value skipping (null, undefined, '', [], NaN , {} are skipped by default)
.toJSON()	Get serializable representation
.toString(options?)	(optionally control array style)
.between(field, range, logicalOperator?)	Add a between condition
.notBetween(field, range, logicalOperator?)	Add a not between condition
.equals(field, value, logicalOperator?)	Add an equals (=) condition
.notEquals(field, value, logicalOperator?)	Add a not equals (!=) condition
.looseEquals(field, value, logicalOperator?)	Add a loose equals (==) condition
.strictEquals(field, value, logicalOperator?)	Add a strict equals (===) condition
.strictNotEquals(field, value, logicalOperator?)	Add a strict not equals (!==) condition
.greaterThan(field, value, logicalOperator?)	Add a greater than (>) condition
.greaterThanOrEqual(field, value, logicalOperator?)	Add a greater than or equal (>=) condition
.lessThan(field, value, logicalOperator?)	Add a less than (<) condition
.lessThanOrEqual(field, value, logicalOperator?)	Add a less than or equal (<=) condition
.like(field, value, logicalOperator?)	Add a like condition
.ilike(field, value, logicalOperator?)	Add an ilike (case-insensitive like) condition
.in(field, values, logicalOperator?)	Add an in condition
.notIn(field, values, logicalOperator?)	Add a not in condition
.isNull(field, logicalOperator?)	Add an is null condition
.isNotNull(field, logicalOperator?)	Add an is not null condition
.isEmpty(field, logicalOperator?)	Add an is empty condition
.isNotEmpty(field, logicalOperator?)	Add an is not empty condition

Static Helpers

Method	Description
QueryBuilder.fn(name, ...args)	Create function calls for values (e.g., UPPER(name))
QueryBuilder.validateOperator(operator, value?)	Validate if an operator is compatible with a value

Supported Operators

Type	Operators
Logical	and, or
Comparison	=, ==, ===, !=, !==, >, <, >=, <=
Word	starts with, ends with, contains, matches, like, ilike
Set	in, not in
Range	between, not between
Null Check	is null, is not null, is empty, is not empty

Contributing

Contributions are welcome! If you encounter issues or have ideas to enhance the library, feel free to submit an issue or pull request.