API Reference

All generic types accept either interface or type as the shape parameter — both work identically.

Core Types

QuerySchema

The portable query model. Can be constructed via the aq builder or as a plain object.

interface QuerySchema<TShape extends SchemaShape = SchemaShape> {
  where?: QueryWhere<TShape> | null
  orderBy?: QueryOrderBy<TShape>[]
  limit?: number
  offset?: number
  mate?: Record<string, any>
  table?: string
}

QueryWhere

Represents a single condition or logical combination.

type QueryWhere<TShape> =
  | ComparisonWhere<TShape>
  | CompoundWhere<TShape>
  | UnaryLogicalWhere<TShape>

ComparisonWhere

A discriminated union of four comparison variants:

type ComparisonWhere<TShape, TField = FieldPathByShape<TShape>> =
  | UnaryComparisonWhere<TShape, TField>   // op: '=' | '>' | '>=' | '<' | '<=' | 'like' | 'ilike'
  | SetComparisonWhere<TShape, TField>     // op: '@>' | '<@' | '&&'
  | ToMultiComparisonWhere<TShape, TField> // op: 'in'  (uses `values` instead of `value`)
  | PredicateWhere<TShape, TField>         // op: 'is null'  (no value field)

CompoundWhere

Logical combination (and / or).

interface CompoundWhere<TShape> {
  op: 'and' | 'or'
  conditions: QueryWhere<TShape>[]
}

UnaryLogicalWhere

Negation (not).

interface UnaryLogicalWhere<TShape> {
  op: 'not'
  condition: QueryWhere<TShape>
}

QueryOrderBy

interface QueryOrderBy<TShape> {
  field: FieldPathByShape<TShape>
  direction?: 'asc' | 'desc'
}

Functions

aq

Create a new QuerySchema builder.

aq<TShape>(state?: QuerySchema<TShape>): AgnosticQuery<TShape>

newWhere

Create a standalone WHERE builder.

newWhere<TShape>(state?: QueryWhere<TShape> | null): NewWhere<TShape>

newComparisonWhere

Create a reusable ComparisonWhere factory.

newComparisonWhere<TShape>(): <Col, Op>(col, op, value) => ComparisonWhere<TShape>

findWhere

Create a WHERE tree searcher.

findWhere<TShape>(where: QueryWhere<TShape>): WhereSearcher<TShape>

createExpr

Create a WhereExpr for use in callbacks. Used internally by .where(callback).

createExpr<TShape>(q?: QueryWhere<TShape> | null): WhereExpr<TShape>

Adapter Functions

Drizzle

toDrizzle<T>(db, table, data: QuerySchema<T>): Promise<T[]>
toDrizzleWhere<T>(table, where?: QueryWhere<T>): SQL | undefined
toDrizzleOrderBy<T>(table, orderBy?: QueryOrderBy<T>[]): SQL[]

Raw SQL (PostgreSQL)

toSql(options: { table: string } & QuerySchema): SqlResult | undefined
toSqlWhere(where?: QueryWhere): string
toSqlOrderBy(orderBy?: QueryOrderBy[]): string

Kysely

fromKysely<T>(query: SelectQueryBuilder): QuerySchema<T>
toKyselyWhere<T>(where: QueryWhere<T>): ExpressionOrFactory<...>
toKyselyOrderBy<T>(query: SelectQueryBuilder, orderBy: QueryOrderBy<T>[]): SelectQueryBuilder

TanStack DB

fromTanDbWhere(where: unknown): QueryWhere | undefined
fromTanDbOrderBy(orderBy: unknown): QueryOrderBy[]
fromTanDb<TShape>(loadSubsetOptions?: LoadSubsetOptions): QuerySchema<TShape>

db0

toDb0<T>(db: Database, data: QuerySchema<T>): Promise<T[]>

Zod / Valibot

createQuerySchema<TShape>(): ZodSchema<QuerySchema<TShape>>