bun-query-builder 0.1.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2024 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+<p align="center"><img src=".github/art/cover.jpg" alt="Social Card of this repo"></p>
+
+[![npm version][npm-version-src]][npm-version-href]
+[![GitHub Actions][github-actions-src]][github-actions-href]
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+<!-- [![npm downloads][npm-downloads-src]][npm-downloads-href] -->
+<!-- [![Codecov][codecov-src]][codecov-href] -->
+
+# bun-query-builder
+
+Fully-typed, model-driven Query Builder for Bun’s native `sql`.
+
+Define your data model once and get a type-safe query experience _(a la Kysely/Laravel)_, powered by Bun’s tagged templates for safety and performance.
+
+## Features
+
+- **Typed from Models**: Infer tables/columns/PKs from your model files; `selectFrom('users')` and `where({ active: true })` are typed.
+- **Fluent Builder**: `select/insert/update/delete`, `where/andWhere/orWhere`, `join/leftJoin/rightJoin/crossJoin`, `groupBy/having`, `union/unionAll`.
+- **Relations**: `with(...)`, `withCount(...)`, `whereHas(...)`, `selectAllRelations()` with configurable aliasing.
+- **Utilities**: `distinct/distinctOn`, `orderByDesc/latest/oldest/inRandomOrder`, `whereColumn/whereRaw/groupByRaw/havingRaw`, JSON/date helpers.
+- **Pagination**: `paginate`, `simplePaginate`, `cursorPaginate`, plus `chunk/chunkById/eachById`.
+- **Transactions**: `transaction` with retries/backoff/isolation/onRetry/afterCommit; `savepoint`; distributed tx helpers.
+- **Configurable**: Dialect hints, timestamps, alias strategies, relation FK formats, JSON mode, random function, shared lock syntax.
+- **Bun API passthroughs**: `unsafe`, `file`, `simple`, pool `reserve/release`, `close`, `ping/waitForReady`.
+- **CLI**: Introspection, query printing, connectivity checks, file/unsafe execution, explain.
+
+> Note: LISTEN/NOTIFY and COPY helpers are scaffolded and will be wired as Bun exposes native APIs.
+
+## Get Started
+
+### Installation
+
+```bash
+bun add bun-query-builder
+```
+
+### Usage
+
+```ts
+import { buildDatabaseSchema, buildSchemaMeta, createQueryBuilder } from 'bun-query-builder'
+
+// Load or define your model files (see docs for model shape)
+const models = {
+  User: { name: 'User', table: 'users', primaryKey: 'id', attributes: { id: { validation: { rule: {} } }, name: { validation: { rule: {} } }, active: { validation: { rule: {} } } } },
+} as const
+
+const schema = buildDatabaseSchema(models as any)
+const meta = buildSchemaMeta(models as any)
+const db = createQueryBuilder<typeof schema>({ schema, meta })
+
+// Fully-typed query
+const q = db
+  .selectFrom('users')
+  .where({ active: true })
+  .orderBy('created_at', 'desc')
+  .limit(10)
+
+const rows = await q.execute()
+```
+
+## Migrations
+
+Generate and execute migrations from your models:
+
+```ts
+import { generateMigration, executeMigration } from 'bun-query-builder'
+
+// Generate migration from models directory
+const migration = await generateMigration('./models', { 
+  dialect: 'postgres', 
+  apply: true, 
+  full: true 
+})
+
+// Execute the migration
+await executeMigration(migration)
+```
+
+### CLI
+
+```bash
+# Print inferred schema from model dir
+query-builder introspect ./app/Models --verbose
+
+# Print a sample SQL (text) for a table
+query-builder sql ./app/Models users --limit 5
+
+# Connectivity:
+query-builder ping
+query-builder wait-ready --attempts 30 --delay 250
+
+# Execute a file or unsafe string (be careful!)
+query-builder file ./migrations/seed.sql
+query-builder unsafe "SELECT * FROM users WHERE id = $1" --params "[1]"
+
+# Explain a query
+query-builder explain "SELECT * FROM users WHERE active = true"
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+## Changelog
+
+Please see our [releases](https://github.com/stackjs/bun-query-builder/releases) page for more information on what has changed recently.
+
+## Contributing
+
+Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
+
+## Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/ts-starter/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+
+## Postcardware
+
+“Software that is free, but hopes for a postcard.” We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
+
+Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
+
+## Sponsors
+
+We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
+
+- [JetBrains](https://www.jetbrains.com/)
+- [The Solana Foundation](https://solana.com/)
+
+## License
+
+The MIT License (MIT). Please see [LICENSE](LICENSE.md) for more information.
+
+Made with 💙
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/bun-query-builder?style=flat-square
+[npm-version-href]: https://npmjs.com/package/bun-query-builder
+[github-actions-src]: https://img.shields.io/github/actions/workflow/status/stacksjs/ts-starter/ci.yml?style=flat-square&branch=main
+[github-actions-href]: https://github.com/stacksjs/ts-starter/actions?query=workflow%3Aci
+
+<!-- [codecov-src]: https://img.shields.io/codecov/c/gh/stacksjs/ts-starter/main?style=flat-square
+[codecov-href]: https://codecov.io/gh/stacksjs/ts-starter -->

package/dist/actions/explain.d.ts

@@ -0,0 +1 @@
+export declare function explain(sql: string): void;

package/dist/actions/file.d.ts

@@ -0,0 +1,2 @@
+import type { FileOptions } from '../types';
+export declare function file(path: string, opts?: FileOptions): void;

package/dist/actions/index.d.ts

@@ -0,0 +1,8 @@
+export { explain } from './explain';
+export { file } from './file';
+export { introspect } from './introspect';
+export { executeMigration, generateMigration } from './migrate';
+export { ping } from './ping';
+export { sql } from './sql';
+export { unsafe } from './unsafe';
+export { waitReady } from './wait-ready';

package/dist/actions/introspect.d.ts

@@ -0,0 +1,2 @@
+import type { IntrospectOptions } from '../types';
+export declare function introspect(dir: string, _opts?: IntrospectOptions): void;

package/dist/actions/migrate.d.ts

@@ -0,0 +1,3 @@
+import type { GenerateMigrationResult, MigrateOptions } from '../types';
+export declare function generateMigration(dir: string, opts?: MigrateOptions): Promise<GenerateMigrationResult>;
+export declare function executeMigration(migration: GenerateMigrationResult): Promise<boolean>;

package/dist/actions/ping.d.ts

@@ -0,0 +1 @@
+export declare function ping(): void;

package/dist/actions/sql.d.ts

@@ -0,0 +1,2 @@
+import type { SqlOptions } from '../types';
+export declare function sql(dir: string, table: string, opts?: SqlOptions): void;

package/dist/actions/unsafe.d.ts

@@ -0,0 +1,2 @@
+import type { UnsafeOptions } from '../types';
+export declare function unsafe(sql: string, opts?: UnsafeOptions): void;

package/dist/actions/wait-ready.d.ts

@@ -0,0 +1,2 @@
+import type { WaitReadyOptions } from '../types';
+export declare function waitReady(opts?: WaitReadyOptions): void;

package/dist/client.d.ts

@@ -0,0 +1,427 @@
+import { config } from './config';
+import type { DatabaseSchema } from './schema';
+import type { SchemaMeta } from './meta';
+export declare function createQueryBuilder<DB extends DatabaseSchema<any>>(state?: Partial<InternalState>): QueryBuilder<DB>;
+export declare interface WhereRaw {
+  raw: any
+}
+export declare interface BaseSelectQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string, TSelected, TJoined extends string = TTable> {
+  distinct: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  distinctOn: (...columns: (keyof DB[TTable]['columns'] & string | string)[]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  selectRaw: (fragment: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  where: (expr: WhereExpression<DB[TTable]['columns']> | string, op?: WhereOperator, value?: any) => SelectQueryBuilder<DB, TTable, TSelected>
+  whereRaw: (fragment: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereColumn: (left: string, op: WhereOperator, right: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereColumn: (left: string, op: WhereOperator, right: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereIn: (column: keyof DB[TTable]['columns'] & string, values: any[] | { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereIn: (column: keyof DB[TTable]['columns'] & string, values: any[] | { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereNotIn: (column: keyof DB[TTable]['columns'] & string, values: any[] | { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereNotIn: (column: keyof DB[TTable]['columns'] & string, values: any[] | { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereLike: (column: keyof DB[TTable]['columns'] & string, pattern: string, caseSensitive?: boolean) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereILike?: (column: keyof DB[TTable]['columns'] & string, pattern: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereLike: (column: keyof DB[TTable]['columns'] & string, pattern: string, caseSensitive?: boolean) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereILike?: (column: keyof DB[TTable]['columns'] & string, pattern: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereNotLike: (column: keyof DB[TTable]['columns'] & string, pattern: string, caseSensitive?: boolean) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereNotILike?: (column: keyof DB[TTable]['columns'] & string, pattern: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereNotLike: (column: keyof DB[TTable]['columns'] & string, pattern: string, caseSensitive?: boolean) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereNotILike?: (column: keyof DB[TTable]['columns'] & string, pattern: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereAny: (columns: (keyof DB[TTable]['columns'] & string)[], op: WhereOperator, value: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereAll: (columns: (keyof DB[TTable]['columns'] & string)[], op: WhereOperator, value: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereNone: (columns: (keyof DB[TTable]['columns'] & string)[], op: WhereOperator, value: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereNested: (fragment: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereNested: (fragment: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereDate: (column: string, op: WhereOperator, date: string | Date) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereBetween: (column: string, start: any, end: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereNotBetween: (column: string, start: any, end: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereJsonContains: (column: string, json: unknown) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereJsonPath?: (path: string, op: WhereOperator, value: unknown) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  andWhere: (expr: WhereExpression<DB[TTable]['columns']> | string, op?: WhereOperator, value?: any) => SelectQueryBuilder<DB, TTable, TSelected>
+  orWhere: (expr: WhereExpression<DB[TTable]['columns']> | string, op?: WhereOperator, value?: any) => SelectQueryBuilder<DB, TTable, TSelected>
+  orderBy: (column: ColumnName<DB, TTable>, direction?: SortDirection) => SelectQueryBuilder<DB, TTable, TSelected>
+  orderByDesc: (column: ColumnName<DB, TTable>) => SelectQueryBuilder<DB, TTable, TSelected>
+  inRandomOrder: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  reorder: (column: string, direction?: 'asc' | 'desc') => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  latest: (column?: keyof DB[TTable]['columns'] & string) => SelectQueryBuilder<DB, TTable, TSelected>
+  oldest: (column?: keyof DB[TTable]['columns'] & string) => SelectQueryBuilder<DB, TTable, TSelected>
+  limit: (n: number) => SelectQueryBuilder<DB, TTable, TSelected>
+  offset: (n: number) => SelectQueryBuilder<DB, TTable, TSelected>
+  withTimeout?: (ms: number) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  abort?: (signal: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  join: <T2 extends keyof DB & string>(
+    table: T2,
+    onLeft: JoinColumn<DB, TJoined | T2>,
+    operator: '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like',
+    onRight: JoinColumn<DB, TJoined | T2>,
+  ) => SelectQueryBuilder<DB, TTable, TSelected, TJoined | T2>
+  joinSub: (sub: { toSQL: () => any }, alias: string, onLeft: string, operator: WhereOperator, onRight: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  innerJoin: <T2 extends keyof DB & string>(
+    table: T2,
+    onLeft: JoinColumn<DB, TJoined | T2>,
+    operator: '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like',
+    onRight: JoinColumn<DB, TJoined | T2>,
+  ) => SelectQueryBuilder<DB, TTable, TSelected, TJoined | T2>
+  leftJoin: <T2 extends keyof DB & string>(
+    table: T2,
+    onLeft: JoinColumn<DB, TJoined | T2>,
+    operator: '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like',
+    onRight: JoinColumn<DB, TJoined | T2>,
+  ) => SelectQueryBuilder<DB, TTable, TSelected, TJoined | T2>
+  leftJoinSub: (sub: { toSQL: () => any }, alias: string, onLeft: string, operator: WhereOperator, onRight: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  rightJoin: <T2 extends keyof DB & string>(
+    table: T2,
+    onLeft: JoinColumn<DB, TJoined | T2>,
+    operator: '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like',
+    onRight: JoinColumn<DB, TJoined | T2>,
+  ) => SelectQueryBuilder<DB, TTable, TSelected, TJoined | T2>
+  crossJoin: <T2 extends keyof DB & string>(table: T2) => SelectQueryBuilder<DB, TTable, TSelected, TJoined | T2>
+  crossJoinSub: (sub: { toSQL: () => any }, alias: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  groupBy: (...columns: (keyof DB[TTable]['columns'] & string | string)[]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  groupByRaw: (fragment: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  having: (expr: WhereExpression<any>) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  havingRaw: (fragment: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  addSelect: (...columns: (keyof DB[TTable]['columns'] & string | string)[]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  selectAll?: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orderByRaw: (fragment: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  union: (other: { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  unionAll: (other: { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  forPage: (page: number, perPage: number) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  selectAllRelations?: () => SelectQueryBuilder<DB, TTable, any, TJoined>
+  whereNull?: (column: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereNotNull?: (column: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereExists?: (subquery: { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereJsonDoesntContain?: (column: string, json: unknown) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereJsonContainsKey?: (path: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereJsonDoesntContainKey?: (path: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereJsonLength?: (path: string, opOrLen: WhereOperator | number, len?: number) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  with?: (...relations: string[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  lockForUpdate: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  sharedLock: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  withCTE: (name: string, sub: { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  withRecursive: (name: string, sub: { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  value: <K extends keyof TSelected & string>(column: K) => Promise<SelectedRow<DB, TTable, TSelected>[K]>
+  pluck: {
+    /**
+     * # `pluck(column)`
+     *
+     * Returns an array of values for a single column.
+     *
+     * @example
+     * ```ts
+     * const names = await db.selectFrom('users').pluck('name')
+     * const ids = await db.selectFrom('users').orderBy('id').pluck('id')
+     * ```
+     */
+    <K extends keyof TSelected & string>(column: K): Promise<SelectedRow<DB, TTable, TSelected>[K][]>
+    /**
+     * # `pluck(column, key)`
+     *
+     * Returns an object keyed by the given key column.
+     *
+     * @example
+     * ```ts
+     * const byId = await db.selectFrom('users').pluck('email', 'id')
+     * const map = await db.selectFrom('users').pluck('name', 'email')
+     * ```
+     */
+    <K extends keyof TSelected & string, K2 extends keyof TSelected & string>(column: K, key: K2): Promise<Record<string, SelectedRow<DB, TTable, TSelected>[K]>>
+  }
+  exists: () => Promise<boolean>
+  doesntExist: () => Promise<boolean>
+  cursorPaginate: (perPage: number, cursor?: string | number, column?: string, direction?: 'asc' | 'desc') => Promise<{ data: any[], meta: { perPage: number, nextCursor: string | number | null } }>
+  chunk: (size: number, handler: (rows: any[]) => Promise<void> | void) => Promise<void>
+  chunkById: (size: number, column?: string, handler?: (rows: any[]) => Promise<void> | void) => Promise<void>
+  eachById: (size: number, column?: string, handler?: (row: any) => Promise<void> | void) => Promise<void>
+  when: (condition: any, then: (qb: any) => any, otherwise?: (qb: any) => any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  tap: (fn: (qb: any) => any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  dump: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  dd: () => never
+  explain: () => Promise<any[]>
+  simple: () => any
+  toText?: () => string
+  paginate: (perPage: number, page?: number) => Promise<{ data: SelectedRow<DB, TTable, TSelected>[], meta: { perPage: number, page: number, total: number, lastPage: number } }>
+  simplePaginate: (perPage: number, page?: number) => Promise<{ data: SelectedRow<DB, TTable, TSelected>[], meta: { perPage: number, page: number, hasMore: boolean } }>
+  toSQL: () => string
+  execute: () => Promise<SelectedRow<DB, TTable, TSelected>[]>
+  executeTakeFirst: () => Promise<SelectedRow<DB, TTable, TSelected> | undefined>
+  get: () => Promise<SelectedRow<DB, TTable, TSelected>[]>
+  first: () => Promise<SelectedRow<DB, TTable, TSelected> | undefined>
+  firstOrFail: () => Promise<SelectedRow<DB, TTable, TSelected>>
+  find: (id: any) => Promise<SelectedRow<DB, TTable, TSelected> | undefined>
+  findOrFail: (id: any) => Promise<SelectedRow<DB, TTable, TSelected>>
+  findMany: (ids: any[]) => Promise<TSelected[]>
+  lazy: () => AsyncIterable<TSelected>
+  lazyById: () => AsyncIterable<TSelected>
+  pipe: <R>(fn: (qb: SelectQueryBuilder<DB, TTable, TSelected, TJoined>) => R) => R
+  count: () => Promise<number>
+  rows: TSelected[]
+  row: TSelected
+  values: () => Promise<any[][]>
+  toParams?: () => any[]
+  raw: () => Promise<any[][]>
+  cancel: () => void
+  withTrashed?: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  onlyTrashed?: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  scope?: (name: string, value?: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  clone?: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  rowNumber?: (alias?: string, partitionBy?: string | string[], orderBy?: [string, 'asc' | 'desc'][]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  denseRank?: (alias?: string, partitionBy?: string | string[], orderBy?: [string, 'asc' | 'desc'][]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  rank?: (alias?: string, partitionBy?: string | string[], orderBy?: [string, 'asc' | 'desc'][]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+}
+export declare interface InsertQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> {
+  values: (data: Partial<DB[TTable]['columns']> | Partial<DB[TTable]['columns']>[]) => InsertQueryBuilder<DB, TTable>
+  returning: <K extends keyof DB[TTable]['columns'] & string>(...cols: K[]) => SelectQueryBuilder<DB, TTable, Pick<DB[TTable]['columns'], K>>
+  toSQL: () => string
+  execute: () => Promise<number | DB[TTable]['columns'] | DB[TTable]['columns'][]>
+}
+export declare interface UpdateQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> {
+  set: (values: Partial<DB[TTable]['columns']>) => UpdateQueryBuilder<DB, TTable>
+  where: (expr: WhereExpression<DB[TTable]['columns']>) => UpdateQueryBuilder<DB, TTable>
+  returning: <K extends keyof DB[TTable]['columns'] & string>(...cols: K[]) => SelectQueryBuilder<DB, TTable, Pick<DB[TTable]['columns'], K>>
+  toSQL: () => string
+  execute: () => Promise<number>
+  executeTakeFirst?: () => Promise<{ numUpdatedRows?: number }>
+}
+export declare interface DeleteQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> {
+  where: (expr: WhereExpression<DB[TTable]['columns']>) => DeleteQueryBuilder<DB, TTable>
+  returning: <K extends keyof DB[TTable]['columns'] & string>(...cols: K[]) => SelectQueryBuilder<DB, TTable, Pick<DB[TTable]['columns'], K>>
+  toSQL: () => string
+  execute: () => Promise<number>
+  executeTakeFirst?: () => Promise<{ numDeletedRows?: number }>
+}
+export declare interface QueryBuilder<DB extends DatabaseSchema<any>> {
+  select: <TTable extends keyof DB & string, K extends keyof DB[TTable]['columns'] & string>(
+    table: TTable,
+    ...columns: (K | `${string} as ${string}`)[]
+  ) => SelectQueryBuilder<DB, TTable, any>
+  selectFrom: <TTable extends keyof DB & string>(table: TTable) => TypedSelectQueryBuilder<DB, TTable, DB[TTable]['columns'], TTable, `SELECT * FROM ${TTable}`>
+  insertInto: <TTable extends keyof DB & string>(table: TTable) => TypedInsertQueryBuilder<DB, TTable>
+  updateTable: <TTable extends keyof DB & string>(table: TTable) => UpdateQueryBuilder<DB, TTable>
+  deleteFrom: <TTable extends keyof DB & string>(table: TTable) => DeleteQueryBuilder<DB, TTable>
+  selectFromSub: (sub: { toSQL: () => any }, alias: string) => SelectQueryBuilder<DB, keyof DB & string, any>
+  sql: any
+  raw: (strings: TemplateStringsArray, ...values: any[]) => any
+  simple: (strings: TemplateStringsArray, ...values: any[]) => any
+  unsafe: (query: string, params?: any[]) => Promise<any>
+  file: (path: string, params?: any[]) => Promise<any>
+  reserve: () => Promise<(QueryBuilder<DB> & { release: () => void })>
+  close: (opts?: { timeout?: number }) => Promise<void>
+  listen: (channel: string, handler?: (payload: any) => void) => Promise<void>
+  unlisten: (channel?: string) => Promise<void>
+  notify: (channel: string, payload?: any) => Promise<void>
+  copyTo: (queryOrTable: string, options?: Record<string, any>) => Promise<any>
+  copyFrom: (queryOrTable: string, source: AsyncIterable<any> | Iterable<any>, options?: Record<string, any>) => Promise<any>
+  ping: () => Promise<boolean>
+  waitForReady: (opts?: { attempts?: number, delayMs?: number }) => Promise<void>
+  transaction: <T>(fn: (tx: QueryBuilder<DB>) => Promise<T> | T, options?: TransactionOptions) => Promise<T>
+  savepoint: <T>(fn: (sp: QueryBuilder<DB>) => Promise<T> | T) => Promise<T>
+  beginDistributed: <T>(name: string, fn: (tx: QueryBuilder<DB>) => Promise<T> | T) => Promise<T>
+  commitDistributed: (name: string) => Promise<void>
+  rollbackDistributed: (name: string) => Promise<void>
+  configure: (opts: Partial<typeof config>) => QueryBuilder<DB>
+  setTransactionDefaults: (defaults: TransactionOptions) => void
+  transactional: <TArgs extends any[], R>(fn: (tx: QueryBuilder<DB>, ...args: TArgs) => Promise<R> | R, options?: TransactionOptions) => (...args: TArgs) => Promise<R>
+  count: <TTable extends keyof DB & string>(table: TTable, column?: keyof DB[TTable]['columns'] & string) => Promise<number>
+  sum: <TTable extends keyof DB & string>(table: TTable, column: keyof DB[TTable]['columns'] & string) => Promise<number>
+  avg: <TTable extends keyof DB & string>(table: TTable, column: keyof DB[TTable]['columns'] & string) => Promise<number>
+  min: <TTable extends keyof DB & string>(table: TTable, column: keyof DB[TTable]['columns'] & string) => Promise<any>
+  max: <TTable extends keyof DB & string>(table: TTable, column: keyof DB[TTable]['columns'] & string) => Promise<any>
+  insertOrIgnore: <TTable extends keyof DB & string>(table: TTable, values: Partial<DB[TTable]['columns']> | Partial<DB[TTable]['columns']>[]) => Promise<any>
+  insertGetId: <TTable extends keyof DB & string>(table: TTable, values: Partial<DB[TTable]['columns']>, idColumn?: keyof DB[TTable]['columns'] & string) => Promise<any>
+  updateOrInsert: <TTable extends keyof DB & string>(table: TTable, match: Partial<DB[TTable]['columns']>, values: Partial<DB[TTable]['columns']>) => Promise<boolean>
+  upsert: <TTable extends keyof DB & string>(table: TTable, rows: Partial<DB[TTable]['columns']>[], conflictColumns: (keyof DB[TTable]['columns'] & string)[], mergeColumns?: (keyof DB[TTable]['columns'] & string)[]) => Promise<any>
+  create: <TTable extends keyof DB & string>(
+    table: TTable,
+    values: Partial<DB[TTable]['columns']>,
+  ) => Promise<DB[TTable]['columns']>
+  createMany: <TTable extends keyof DB & string>(
+    table: TTable,
+    rows: Partial<DB[TTable]['columns']>[],
+  ) => Promise<void>
+  firstOrCreate: <TTable extends keyof DB & string>(
+    table: TTable,
+    match: Partial<DB[TTable]['columns']>,
+    defaults?: Partial<DB[TTable]['columns']>,
+  ) => Promise<DB[TTable]['columns']>
+  updateOrCreate: <TTable extends keyof DB & string>(
+    table: TTable,
+    match: Partial<DB[TTable]['columns']>,
+    values: Partial<DB[TTable]['columns']>,
+  ) => Promise<DB[TTable]['columns']>
+  save: <TTable extends keyof DB & string>(
+    table: TTable,
+    values: Partial<DB[TTable]['columns']>,
+  ) => Promise<DB[TTable]['columns']>
+  remove: <TTable extends keyof DB & string>(
+    table: TTable,
+    id: DB[TTable]['columns'][DB[TTable]['primaryKey'] & keyof DB[TTable]['columns']] | any,
+  ) => Promise<any>
+  find: <TTable extends keyof DB & string>(
+    table: TTable,
+    id: DB[TTable]['columns'][DB[TTable]['primaryKey'] & keyof DB[TTable]['columns']] | any,
+  ) => Promise<DB[TTable]['columns'] | undefined>
+  findOrFail: <TTable extends keyof DB & string>(
+    table: TTable,
+    id: DB[TTable]['columns'][DB[TTable]['primaryKey'] & keyof DB[TTable]['columns']] | any,
+  ) => Promise<DB[TTable]['columns']>
+  findMany: <TTable extends keyof DB & string>(
+    table: TTable,
+    ids: any[],
+  ) => Promise<DB[TTable]['columns'][]>
+  latest: <TTable extends keyof DB & string>(
+    table: TTable,
+    column?: keyof DB[TTable]['columns'] & string,
+  ) => Promise<DB[TTable]['columns'] | undefined>
+  oldest: <TTable extends keyof DB & string>(
+    table: TTable,
+    column?: keyof DB[TTable]['columns'] & string,
+  ) => Promise<DB[TTable]['columns'] | undefined>
+  skip: <TTable extends keyof DB & string>(
+    table: TTable,
+    count: number,
+  ) => SelectQueryBuilder<DB, TTable, DB[TTable]['columns'], TTable>
+  rawQuery: (query: string) => Promise<any>
+  id?: (name: string) => any
+  ids?: (...names: string[]) => any
+  advisoryLock?: (key: number | string) => Promise<void>
+  tryAdvisoryLock?: (key: number | string) => Promise<boolean>
+}
+declare interface InternalState {
+  sql: any
+  meta?: SchemaMeta
+  schema?: any
+  txDefaults?: TransactionOptions
+}
+export declare interface TransactionOptions {
+  retries?: number
+  isolation?: TransactionIsolation
+  onRetry?: (attempt: number, error: any) => void
+  afterCommit?: () => void
+  sqlStates?: string[]
+  backoff?: TxBackoff
+  logger?: (event: TxLoggerEvent) => void
+  readOnly?: boolean
+  onRollback?: (error: any) => void
+  afterRollback?: () => void
+}
+declare interface TxBackoff {
+  baseMs?: number
+  maxMs?: number
+  factor?: number
+  jitter?: boolean
+}
+declare interface TxLoggerEvent {
+  type: 'start' | 'retry' | 'commit' | 'rollback' | 'error'
+  attempt: number
+  error?: any
+  durationMs?: number
+}
+// Where condition helpers
+declare type Primitive = string | number | boolean | bigint | Date | null | undefined
+declare type ValueOrRef = Primitive
+export type WhereOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like' | 'in' | 'not in' | 'is' | 'is not'
+export type WhereExpression<TableColumns> = | Partial<{ [K in keyof TableColumns & string]: ValueOrRef | ValueOrRef[] }>
+  | [key: keyof TableColumns & string, op: WhereOperator, value: ValueOrRef | ValueOrRef[]]
+  | WhereRaw
+export type QueryResult = any
+/**
+ * # `SortDirection`
+ *
+ * The direction used when ordering query results.
+ */
+export type SortDirection = 'asc' | 'desc'
+/**
+ * # `ColumnName<DB, TTable>`
+ *
+ * Helper type extracting a string union of column names for a given table.
+ */
+export type ColumnName<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> = keyof DB[TTable]['columns'] & string
+// Named row alias to improve IDE hover readability
+export type SelectedRow<DB extends DatabaseSchema<any>, _TTable extends keyof DB & string, TSelected> = Readonly<TSelected>
+declare type JoinColumn<DB extends DatabaseSchema<any>, TTables extends string> = TTables extends any
+  ? `${TTables}.${keyof DB[TTables]['columns'] & string}`
+  : never
+// Convert snake_case to PascalCase at the type level (e.g. created_at -> CreatedAt)
+declare type SnakeToPascal<S extends string> = S extends `${infer H}_${infer T}`
+  ? `${Capitalize<H>}${SnakeToPascal<T>}`
+  : Capitalize<S>
+// Typed SQL builder (type-level only). We piggy-back on the runtime builder but
+// thread a phantom TSql string through method signatures so hovers can show the
+// composed SQL at compile-time for common operations.
+declare type _TypedDynamicWhereMethods<DB extends DatabaseSchema<any>, TTable extends keyof DB & string, TSelected, TJoined extends string, TSql extends string> = {
+  [K in keyof DB[TTable]['columns'] & string as `where${SnakeToPascal<K>}`]: (
+    value: DB[TTable]['columns'][K],
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} WHERE ${K} = ?`>
+} & {
+  [K in keyof DB[TTable]['columns'] & string as `orWhere${SnakeToPascal<K>}`]: (
+    value: DB[TTable]['columns'][K],
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} OR ${K} = ?`>
+} & {
+  [K in keyof DB[TTable]['columns'] & string as `andWhere${SnakeToPascal<K>}`]: (
+    value: DB[TTable]['columns'][K],
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} AND ${K} = ?`>
+}
+export type TypedSelectQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string, TSelected, TJoined extends string = TTable, TSql extends string = `SELECT * FROM ${TTable}`> = Omit<
+  BaseSelectQueryBuilder<DB, TTable, TSelected, TJoined>,
+  'toSQL' | 'where' | 'andWhere' | 'orWhere' | 'orderBy' | 'limit'
+> & DynamicWhereMethods<DB, TTable, TSelected, TJoined>
+& _TypedDynamicWhereMethods<DB, TTable, TSelected, TJoined, TSql>
+& {
+  toSQL: () => TSql
+  where: (<K extends keyof DB[TTable]['columns'] & string>(
+    expr: Record<K, DB[TTable]['columns'][K]>,
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} WHERE ${K} = ?`>) & (<K extends keyof DB[TTable]['columns'] & string, OP extends WhereOperator>(
+    expr: [K, OP, any],
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} WHERE ${K} ${Uppercase<OP>} ${OP extends 'in' | 'not in' ? '(?)' : '?'}`>) & ((
+    expr: WhereExpression<DB[TTable]['columns']> | string,
+    op?: WhereOperator,
+    value?: any,
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} WHERE ${string}`>)
+  andWhere: (<K extends keyof DB[TTable]['columns'] & string>(
+    expr: Record<K, DB[TTable]['columns'][K]>,
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} AND ${K} = ?`>) & (<K extends keyof DB[TTable]['columns'] & string, OP extends WhereOperator>(
+    expr: [K, OP, any],
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} AND ${K} ${Uppercase<OP>} ${OP extends 'in' | 'not in' ? '(?)' : '?'}`>) & ((
+    expr: WhereExpression<DB[TTable]['columns']> | string,
+    op?: WhereOperator,
+    value?: any,
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} AND ${string}`>)
+  orWhere: (<K extends keyof DB[TTable]['columns'] & string>(
+    expr: Record<K, DB[TTable]['columns'][K]>,
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} OR ${K} = ?`>) & (<K extends keyof DB[TTable]['columns'] & string, OP extends WhereOperator>(
+    expr: [K, OP, any],
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} OR ${K} ${Uppercase<OP>} ${OP extends 'in' | 'not in' ? '(?)' : '?'}`>) & ((
+    expr: WhereExpression<DB[TTable]['columns']> | string,
+    op?: WhereOperator,
+    value?: any,
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} OR ${string}`>)
+  orderBy: <C extends keyof DB[TTable]['columns'] & string, D extends 'asc' | 'desc' = 'asc'>(
+    column: C,
+    direction?: D,
+  ) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} ORDER BY ${C} ${D}`>
+  limit: <N extends number>(n: N) => TypedSelectQueryBuilder<DB, TTable, TSelected, TJoined, `${TSql} LIMIT ${N}`>
+}
+declare type DynamicWhereMethods<DB extends DatabaseSchema<any>, TTable extends keyof DB & string, TSelected, TJoined extends string = TTable> = {
+  [K in keyof DB[TTable]['columns'] & string as `where${SnakeToPascal<K>}`]: (value: DB[TTable]['columns'][K]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+} & {
+  [K in keyof DB[TTable]['columns'] & string as `orWhere${SnakeToPascal<K>}`]: (value: DB[TTable]['columns'][K]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+} & {
+  [K in keyof DB[TTable]['columns'] & string as `andWhere${SnakeToPascal<K>}`]: (value: DB[TTable]['columns'][K]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+}
+export type SelectQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string, TSelected, TJoined extends string = TTable> = BaseSelectQueryBuilder<DB, TTable, TSelected, TJoined> & DynamicWhereMethods<DB, TTable, TSelected, TJoined>
+// Typed INSERT builder to expose a structured SQL literal in hovers
+export type TypedInsertQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string, TSql extends string = `INSERT INTO ${TTable}`> = Omit<InsertQueryBuilder<DB, TTable>, 'toSQL' | 'values' | 'returning'> & {
+  toSQL: () => TSql
+  values: (
+    data: Partial<DB[TTable]['columns']> | Partial<DB[TTable]['columns']>[],
+  ) => TypedInsertQueryBuilder<DB, TTable, `${TSql} ${string}`>
+  returning: <K extends keyof DB[TTable]['columns'] & string>(
+    ...cols: K[]
+  ) => TypedSelectQueryBuilder<
+    DB,
+    TTable,
+    Pick<DB[TTable]['columns'], K>,
+    TTable,
+    `${TSql} RETURNING ${string}`
+  >
+}
+declare type TransactionIsolation = 'read committed' | 'repeatable read' | 'serializable'

package/dist/config.d.ts

@@ -0,0 +1,3 @@
+export declare const defaultConfig: QueryBuilderConfig;
+// eslint-disable-next-line antfu/no-top-level-await
+export declare const config: QueryBuilderConfig;