@kittlekit/query-builder-core

Headless query-builder engine for schema-driven filters.

What This Package Is

Use this package when you want the non-UI part of a query builder:

• field metadata and filter field definitions
• operator configuration
• query tree creation and updates
• filter output generation
• schema-driven filter field parsing from Zod

This package depends on @kittlekit/schema-form-core for metadata reuse.

Install

npm install @kittlekit/query-builder-core @kittlekit/schema-form-core zod

Quick Start

import { z } from "zod"
import { zodToFilterFields, createInitialQuery, buildFilterOutput } from "@kittlekit/query-builder-core"

const schema = z.object({
  email: z.string().email(),
  status: z.enum(["active", "inactive"]),
})

const fields = zodToFilterFields(schema)
const query = createInitialQuery(fields)
const output = buildFilterOutput(query)

Main Exports

Types

• FilterField
• QueryCondition
• QueryGroup
• FilterOutput
• FilterValue

Operator helpers

• OPERATORS
• getOperatorsForType
• operatorNeedsValue
• operatorNeedsRange
• getDefaultValueForType

Query state helpers

• generateId
• createCondition
• createGroup
• createInitialQuery
• hydrateQuery
• updateConditionInQuery
• addConditionToQuery
• removeConditionFromQuery
• addGroupToQuery
• removeGroupFromQuery
• toggleGroupLogicInQuery
• buildFilterOutput
• hasConditionsInQuery

Schema integration

• zodToFilterFields

Query Model

The core query model is a tree of groups and conditions.

• groups contain logic: "AND" | "OR"
• groups contain child groups or conditions
• conditions contain field, operator, and value

This makes it easy to support nested filtering UIs and server-side filter conversion.

Relationship to Other Packages

schema-form-core -> query-builder-core -> query-builder-react -> query-builder-tailwind

Out of Scope

• React state
• UI rendering
• Tailwind styling
• app-specific filter-to-SQL translation

Publish

npm run build --workspace @kittlekit/query-builder-core
npm publish --workspace @kittlekit/query-builder-core --access public

Examples

• smoke app: sandbox/query-builder-smoke
• app wrapper reference: web/src/components/queryBuilder/QueryBuilder.tsx

Release Notes

0.1.0

• first public extraction of query model, operators, and Zod metadata parsing
• validated via tarball install in a clean smoke app