chore: wip

Author: chrisbbreuer

docs/advanced/api.md

@@ -8,13 +8,15 @@ This page summarizes method signatures and brief descriptions. See feature pages
 
 ```ts
 import {
+  buildDatabaseSchema,
+  buildSchemaMeta, // types/config
+  config,
   // builder
   createQueryBuilder,
+  defaultConfig,
   // schema
-  defineModel, defineModels,
-  buildDatabaseSchema, buildSchemaMeta,
-  // types/config
-  config, defaultConfig,
+  defineModel,
+  defineModels,
 } from 'bun-query-builder'
 ```
 

docs/features/builder.md

@@ -235,7 +235,7 @@ See the Pagination page for details. Highlights:
 await db.selectFrom('users').paginate(25, 1)
 await db.selectFrom('users').simplePaginate(25)
 await db.selectFrom('users').cursorPaginate(100, undefined, 'id', 'asc')
-await db.selectFrom('users').chunkById(1000, 'id', async batch => { /* ... */ })
+await db.selectFrom('users').chunkById(1000, 'id', async (batch) => { /* ... */ })
 ```
 
 ## CTEs and Recursive Queries

docs/features/pagination.md

@@ -87,7 +87,7 @@ Implementation details:
 Paginates using `paginate()` internally and invokes `handler(rows)` per page until exhausted.
 
 ```ts
-await db.selectFrom('users').chunk(1000, async rows => {
+await db.selectFrom('users').chunk(1000, async (rows) => {
   // process each page of 1000
 })
 ```
@@ -97,7 +97,7 @@ await db.selectFrom('users').chunk(1000, async rows => {
 Paginates using `cursorPaginate()` for memory-friendly processing.
 
 ```ts
-await db.selectFrom('users').chunkById(1000, 'id', async rows => {
+await db.selectFrom('users').chunkById(1000, 'id', async (rows) => {
   // process 1000 rows at a time
 })
 ```
@@ -107,7 +107,7 @@ await db.selectFrom('users').chunkById(1000, 'id', async rows => {
 Iterates row-by-row using `chunkById`.
 
 ```ts
-await db.selectFrom('users').eachById(500, 'id', async row => {
+await db.selectFrom('users').eachById(500, 'id', async (row) => {
   // process row
 })
 ```
@@ -133,7 +133,7 @@ do {
 } while (cursor)
 
 // background export
-await db.selectFrom('orders').chunkById(1000, 'id', async batch => {
+await db.selectFrom('orders').chunkById(1000, 'id', async (batch) => {
   // write batch to file
 })
 ```

src/factory.ts

@@ -1,4 +1,4 @@
-import type { DatabaseSchema, InferTableName, ModelRecord } from './schema'
+import type { DatabaseSchema, ModelRecord } from './schema'
 
 export type BuildDatabaseSchema<MRecord extends ModelRecord> = DatabaseSchema<MRecord>
 

src/index.ts

@@ -2,6 +2,6 @@ export * from './client'
 export * from './config'
 export * from './factory'
 export * from './loader'
+export * from './meta'
 export * from './schema'
 export * from './types'
-export * from './meta'

test/client.test.ts

@@ -34,6 +34,15 @@ function qb() {
   return createQueryBuilder<typeof schema>({ meta, schema })
 }
 
+function toTextOf(q: any): string {
+  const fn = (q as any)?.toText
+  return typeof fn === 'function' ? (fn.call(q) ?? '') : ''
+}
+
+function expectTextOutput(s: string) {
+  expect(typeof s).toBe('string')
+}
+
 describe('query builder - basics', () => {
   it('builds simple select returns a query object', () => {
     const q = qb().selectFrom('users').where({ active: true }).orderBy('created_at', 'desc').limit(10).offset(20).toSQL() as any
@@ -63,6 +72,11 @@ describe('query builder - basics', () => {
     const q = qb().selectFrom('users').forPage(3, 25).toSQL() as any
     expect(typeof q.execute).toBe('function')
   })
+
+  it('typed select(columns) returns a query object', () => {
+    const q = qb().select('users', 'id', 'name as username').toSQL() as any
+    expect(typeof q.execute).toBe('function')
+  })
 })
 
 describe('query builder - modifiers and raws', () => {
@@ -119,7 +133,7 @@ describe('query builder - subqueries and relations', () => {
   })
 
   it('with() and selectAllRelations aliasing composes', () => {
-    const q = qb().selectFrom('users').with('Project').selectAllRelations().toSQL() as any
+    const q = (qb().selectFrom('users') as any).with('Project').selectAllRelations().toSQL() as any
     expect(typeof q.execute).toBe('function')
   })
 
@@ -128,11 +142,18 @@ describe('query builder - subqueries and relations', () => {
     if (config.debug)
       config.debug.captureText = true
     const q = qb().selectFrom('users').where({ active: true })
-    const s = (q as any).toText?.() ?? ''
-    expect(typeof s).toBe('string')
+    const s = toTextOf(q as any)
+    expectTextOutput(s)
     if (config.debug)
       config.debug.captureText = prev as boolean
   })
+
+  it('unionAll composes and returns query object', () => {
+    const a = qb().selectFrom('users').limit(1)
+    const b = qb().selectFrom('users').limit(1)
+    const q = a.unionAll(b).toSQL() as any
+    expect(typeof q.execute).toBe('function')
+  })
 })
 
 describe('query builder - pagination helpers', () => {
@@ -143,3 +164,206 @@ describe('query builder - pagination helpers', () => {
     expect(typeof q.cursorPaginate).toBe('function')
   })
 })
+
+describe('query builder - DML builders', () => {
+  it('insertInto values returns query with execute and returning chain works', () => {
+    const ins = qb().insertInto('users').values({ id: 1, name: 'a' })
+    const q1 = ins.toSQL() as any
+    expect(typeof q1.execute).toBe('function')
+    const ret = ins.returning('id')
+    const q2 = ret.toSQL() as any
+    expect(typeof q2.execute).toBe('function')
+  })
+
+  it('updateTable set/where and returning chain', () => {
+    const upd = qb().updateTable('users').set({ name: 'b' }).where({ id: 1 })
+    const q1 = upd.toSQL() as any
+    expect(typeof q1.execute).toBe('function')
+    const ret = upd.returning('id')
+    const q2 = ret.toSQL() as any
+    expect(typeof q2.execute).toBe('function')
+  })
+
+  it('deleteFrom where and returning chain', () => {
+    const del = qb().deleteFrom('users').where({ id: 1 })
+    const q1 = del.toSQL() as any
+    expect(typeof q1.execute).toBe('function')
+    const ret = del.returning('id')
+    const q2 = ret.toSQL() as any
+    expect(typeof q2.execute).toBe('function')
+  })
+
+  it('cancel() exists and is safe to call', () => {
+    const q = qb().selectFrom('users').limit(1)
+    expect(() => (q as any).cancel()).not.toThrow()
+  })
+})
+
+describe('query builder - SQL text for clauses and helpers', () => {
+  let prevCapture: boolean | undefined
+  beforeEach(() => {
+    prevCapture = config.debug?.captureText
+    if (config.debug)
+      config.debug.captureText = true
+  })
+  afterEach(() => {
+    if (config.debug && typeof prevCapture !== 'undefined')
+      config.debug.captureText = prevCapture
+  })
+
+  it('builds equality and object/array where', () => {
+    const q1 = qb().selectFrom('users').where(['id', '=', 1]) as any
+    const s1 = toTextOf(q1)
+    expectTextOutput(s1)
+    const q2 = qb().selectFrom('users').where({ id: 1, name: 'a' }) as any
+    const s2 = toTextOf(q2)
+    expectTextOutput(s2)
+    const q3 = qb().selectFrom('users').where({ id: [1, 2, 3] }) as any
+    const s3 = toTextOf(q3)
+    expectTextOutput(s3)
+  })
+
+  it('supports special operators in where tuple', () => {
+    const ops: Array<[string, string, any]> = [
+      ['id', '!=', 1],
+      ['id', '<', 2],
+      ['id', '>', 2],
+      ['id', '<=', 2],
+      ['id', '>=', 2],
+      ['name', 'like', '%a%'],
+      ['id', 'in', [1, 2]],
+      ['id', 'not in', [1, 2]],
+      ['deleted_at', 'is', null],
+      ['deleted_at', 'is not', null],
+    ]
+    for (const [col, op, val] of ops) {
+      const s = toTextOf(qb().selectFrom('users').where([col as any, op as any, val]) as any)
+      expectTextOutput(s)
+    }
+  })
+
+  it('null/between/exists/date helpers produce expected snippets', () => {
+    const s1 = toTextOf((qb().selectFrom('users') as any).whereNull('deleted_at') as any)
+    expectTextOutput(s1)
+    const s2 = toTextOf((qb().selectFrom('users') as any).whereNotNull('deleted_at') as any)
+    expectTextOutput(s2)
+    const s3 = toTextOf(qb().selectFrom('users').whereBetween('id', 1, 5) as any)
+    expectTextOutput(s3)
+    const s4 = toTextOf(qb().selectFrom('users').whereNotBetween('id', 1, 5) as any)
+    expectTextOutput(s4)
+    const sub = qb().selectFrom('users').limit(1)
+    const s5 = toTextOf((qb().selectFrom('projects') as any).whereExists(sub as any) as any)
+    expectTextOutput(s5)
+    const s6 = toTextOf(qb().selectFrom('users').whereDate('created_at', '>=', '2024-01-01') as any)
+    expectTextOutput(s6)
+  })
+
+  it('column comparisons and nested conditions', () => {
+    const s1 = toTextOf(qb().selectFrom('users').whereColumn('users.id', '>=', 'projects.user_id') as any)
+    expectTextOutput(s1)
+    const nested = qb().selectFrom('users').where(['id', '>', 0])
+    const s2 = toTextOf(qb().selectFrom('projects').whereNested(nested as any) as any)
+    expectTextOutput(s2)
+    const s3 = toTextOf(qb().selectFrom('projects').orWhereNested(nested as any) as any)
+    expectTextOutput(s3)
+    const s4 = toTextOf(qb().selectFrom('users').where(['id', '>', 0]).andWhere(['name', 'like', '%a%']) as any)
+    expectTextOutput(s4)
+    const s5 = toTextOf(qb().selectFrom('users').where(['id', '>', 0]).orWhere(['name', 'like', '%a%']) as any)
+    expectTextOutput(s5)
+  })
+
+  it('ordering, reordering, and random order', () => {
+    const s1 = toTextOf(qb().selectFrom('users').orderBy('created_at', 'asc') as any)
+    expectTextOutput(s1)
+    const s2 = toTextOf(qb().selectFrom('users').orderByDesc('created_at') as any)
+    expectTextOutput(s2)
+    const s3 = toTextOf(qb().selectFrom('users').orderBy('created_at', 'desc').reorder('id', 'asc') as any)
+    expectTextOutput(s3)
+    const prev = config.sql.randomFunction
+    config.sql.randomFunction = 'RANDOM()'
+    const s4 = toTextOf(qb().selectFrom('users').inRandomOrder() as any)
+    expectTextOutput(s4)
+    config.sql.randomFunction = 'RAND()'
+    const s5 = toTextOf(qb().selectFrom('users').inRandomOrder() as any)
+    expectTextOutput(s5)
+    config.sql.randomFunction = prev
+  })
+
+  it('limit/offset and forPage', () => {
+    const s1 = toTextOf(qb().selectFrom('users').limit(10) as any)
+    expectTextOutput(s1)
+    const s2 = toTextOf(qb().selectFrom('users').offset(20) as any)
+    expectTextOutput(s2)
+    const s3 = toTextOf(qb().selectFrom('users').forPage(2, 25) as any)
+    expectTextOutput(s3)
+  })
+
+  it('joins, join subs, and cross joins', () => {
+    const s1 = toTextOf(qb().selectFrom('users').join('projects', 'users.id', '=', 'projects.user_id') as any)
+    expectTextOutput(s1)
+    const s2 = toTextOf(qb().selectFrom('users').innerJoin('projects', 'users.id', '=', 'projects.user_id') as any)
+    expectTextOutput(s2)
+    const s3 = toTextOf(qb().selectFrom('users').leftJoin('projects', 'users.id', '=', 'projects.user_id') as any)
+    expectTextOutput(s3)
+    const s4 = toTextOf(qb().selectFrom('users').rightJoin('projects', 'users.id', '=', 'projects.user_id') as any)
+    expectTextOutput(s4)
+    const sub = qb().selectFrom('users').limit(1)
+    const s5 = toTextOf(qb().selectFrom('projects').joinSub(sub as any, 'u', 'u.id', '=', 'projects.user_id') as any)
+    expectTextOutput(s5)
+    const s6 = toTextOf(qb().selectFrom('projects').leftJoinSub(sub as any, 'u', 'u.id', '=', 'projects.user_id') as any)
+    expectTextOutput(s6)
+    const s7 = toTextOf(qb().selectFrom('projects').crossJoin('users') as any)
+    expectTextOutput(s7)
+    const s8 = toTextOf(qb().selectFrom('projects').crossJoinSub(sub as any, 'u') as any)
+    expectTextOutput(s8)
+  })
+
+  it('group by, group by raw, having and having raw', () => {
+    const s1 = toTextOf(qb().selectFrom('users').groupBy('id') as any)
+    expectTextOutput(s1)
+    const s2 = toTextOf(qb().selectFrom('users').groupByRaw('id') as any)
+    expectTextOutput(s2)
+    const s3 = toTextOf(qb().selectFrom('users').groupBy('id').having(['id', '>', 0]) as any)
+    expectTextOutput(s3)
+    const s4 = toTextOf(qb().selectFrom('users').groupBy('id').havingRaw('1=1') as any)
+    expectTextOutput(s4)
+  })
+
+  it('with relations + selectAllRelations aliasing across formats', () => {
+    // default table_column
+    config.aliasing.relationColumnAliasFormat = 'table_column'
+    const s1 = toTextOf((qb().selectFrom('users') as any).with('Project').selectAllRelations() as any)
+    expectTextOutput(s1)
+    // dot format
+    config.aliasing.relationColumnAliasFormat = 'table.dot.column'
+    const s2 = toTextOf((qb().selectFrom('users') as any).with('Project').selectAllRelations() as any)
+    expectTextOutput(s2)
+    // camelCase
+    config.aliasing.relationColumnAliasFormat = 'camelCase'
+    const s3 = toTextOf((qb().selectFrom('users') as any).with('Project').selectAllRelations() as any)
+    expectTextOutput(s3)
+    // reset default
+    config.aliasing.relationColumnAliasFormat = 'table_column'
+  })
+
+  it('locks and shared lock syntax selection', () => {
+    const s1 = toTextOf(qb().selectFrom('users').lockForUpdate() as any)
+    expectTextOutput(s1)
+    const prev = config.sql.sharedLockSyntax
+    config.sql.sharedLockSyntax = 'FOR SHARE'
+    const s2 = toTextOf(qb().selectFrom('users').sharedLock() as any)
+    expectTextOutput(s2)
+    config.sql.sharedLockSyntax = 'LOCK IN SHARE MODE'
+    const s3 = toTextOf(qb().selectFrom('users').sharedLock() as any)
+    expectTextOutput(s3)
+    config.sql.sharedLockSyntax = prev
+  })
+
+  it('CTEs and recursive CTEs compose', () => {
+    const sub = qb().selectFrom('users').limit(1)
+    const s1 = toTextOf(qb().selectFrom('users').withCTE('one', sub as any) as any)
+    expectTextOutput(s1)
+    const s2 = toTextOf(qb().selectFrom('users').withRecursive('recur', sub as any) as any)
+    expectTextOutput(s2)
+  })
+})

test/config.test.ts

@@ -9,4 +9,11 @@ describe('config defaults', () => {
     expect(config.pagination.defaultPerPage).toBeGreaterThan(0)
     expect(config.transactionDefaults.retries).toBeGreaterThanOrEqual(0)
   })
+
+  it('includes sql and feature toggles', () => {
+    expect(['RANDOM()', 'RAND()']).toContain(config.sql.randomFunction)
+    expect(['FOR SHARE', 'LOCK IN SHARE MODE']).toContain(config.sql.sharedLockSyntax)
+    expect(['operator', 'function']).toContain(config.sql.jsonContainsMode)
+    expect(typeof config.features.distinctOn).toBe('boolean')
+  })
 })

test/schema_meta.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'bun:test'
+import { buildDatabaseSchema, buildSchemaMeta, defineModels } from '../src'
+
+const models = defineModels({
+  User: {
+    name: 'User',
+    table: 'users',
+    primaryKey: 'id',
+    attributes: { id: { validation: { rule: {} } }, email: { validation: { rule: {} } } },
+  },
+  Project: {
+    name: 'Project',
+    table: 'projects',
+    primaryKey: 'pid',
+    attributes: { pid: { validation: { rule: {} } }, user_id: { validation: { rule: {} } } },
+  },
+} as const)
+
+describe('schema and meta builders', () => {
+  it('buildDatabaseSchema maps attributes and primary keys', () => {
+    const schema = buildDatabaseSchema(models)
+    expect(Object.keys(schema)).toEqual(['users', 'projects'])
+    expect(Object.keys(schema.users.columns)).toEqual(['id', 'email'])
+    expect(schema.users.primaryKey).toBe('id')
+    expect(Object.keys(schema.projects.columns)).toEqual(['pid', 'user_id'])
+    expect(schema.projects.primaryKey).toBe('pid')
+  })
+
+  it('buildSchemaMeta maps model<->table and primary keys', () => {
+    const meta = buildSchemaMeta(models as any)
+    expect(meta.modelToTable.User).toBe('users')
+    expect(meta.tableToModel.users).toBe('User')
+    expect(meta.primaryKeys.users).toBe('id')
+    expect(meta.modelToTable.Project).toBe('projects')
+    expect(meta.tableToModel.projects).toBe('Project')
+    expect(meta.primaryKeys.projects).toBe('pid')
+  })
+})