bun-query-builder 0.1.13 → 0.1.15

package/README.md

@@ -1,489 +1,66 @@
-<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
-
-### Core Query Building
-
-- **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`.
-- **Aggregations**: `count()`, `avg()`, `sum()`, `max()`, `min()` with full type safety.
-- **Batch Operations**: `insertMany()`, `updateMany()`, `deleteMany()` for efficient bulk operations.
-
-### Advanced Features
-
-- **Relations**: `with(...)`, `withCount(...)`, `whereHas(...)`, `has()`, `doesntHave()`, `selectAllRelations()` with configurable aliasing and constraint callbacks.
-- **Query Scopes**: Define reusable query constraints on models for cleaner, more maintainable code.
-- **Query Caching**: Built-in LRU cache with TTL support via `cache(ttlMs)`, `clearQueryCache()`, `setQueryCacheMaxSize()`.
-- **Model Hooks**: Lifecycle events - `beforeCreate`, `afterCreate`, `beforeUpdate`, `afterUpdate`, `beforeDelete`, `afterDelete`.
+A simple yet performant query builder for TypeScript. Built with Bun.
 
-### Utilities & Helpers
-
-- **Utilities**: `distinct/distinctOn`, `orderByDesc/latest/oldest/inRandomOrder`, `whereColumn/whereRaw/groupByRaw/havingRaw`, JSON/date helpers.
-- **Pagination**: `paginate`, `simplePaginate`, `cursorPaginate`, plus `chunk/chunkById/eachById`.
-- **Soft Deletes**: `withTrashed()`, `onlyTrashed()` for logical deletion support.
-
-### Database Operations
-
-- **Transactions**: `transaction` with retries/backoff/isolation/onRetry/afterCommit; `savepoint`; distributed tx helpers.
-- **Migrations**: Generate and execute migrations from models with full diff support.
-- **Seeders**: Database seeding with fake data generation via `ts-mocker` (faker alternative).
-- **Raw Queries**: Tagged templates and parameterized queries with `raw()` and `unsafe()`.
-
-### Configuration & Integration
-
-- **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
+## 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()
-```
-
-### Aggregations
-
-```ts
-// Get average age of active users
-const avgAge = await db.selectFrom('users')
-  .where({ active: true })
-  .avg('age')
-
-// Count total posts
-const totalPosts = await db.selectFrom('posts').count()
-
-// Get max and min scores
-const maxScore = await db.selectFrom('users').max('score')
-const minScore = await db.selectFrom('users').min('score')
-```
-
-### Batch Operations
-
-```ts
-// Insert multiple records at once
-await db.insertMany('users', [
-  { name: 'Alice', email: 'alice@example.com' },
-  { name: 'Bob', email: 'bob@example.com' },
-  { name: 'Charlie', email: 'charlie@example.com' },
-])
-
-// Update multiple records matching conditions
-await db.updateMany('users', { verified: false }, { status: 'pending' })
-
-// Delete multiple records by IDs
-await db.deleteMany('users', [1, 2, 3, 4, 5])
+```bash
+npm install bun-query-builder
 ```
 
-### Query Caching
+## Usage
 
-```ts
-// Cache query results for 60 seconds (default)
-const users = await db.selectFrom('users')
-  .where({ active: true })
-  .cache()
-  .get()
+```typescript
+import { QueryBuilder } from 'bun-query-builder'
 
-// Custom cache TTL (5 seconds)
-const posts = await db.selectFrom('posts')
-  .orderBy('created_at', 'desc')
+// Select query
+const users = await QueryBuilder
+  .selectFrom('users')
+  .where('active', '=', true)
+  .orderByDesc('created_at')
   .limit(10)
-  .cache(5000)
-  .get()
-
-// Clear all cached queries
-clearQueryCache()
-
-// Configure cache size
-setQueryCacheMaxSize(500)
-```
-
-### Model Hooks
-
-```ts
-const db = createQueryBuilder<typeof schema>({
-  schema,
-  meta,
-  hooks: {
-    beforeCreate: async ({ table, data }) => {
-      console.log(`Creating ${table}:`, data)
-      // Modify data, validate, or throw to prevent creation
-    },
-    afterCreate: async ({ table, data, result }) => {
-      console.log(`Created ${table}:`, result)
-      // Trigger notifications, update caches, etc.
-    },
-    beforeUpdate: async ({ table, data, where }) => {
-      // Audit logging, validation, etc.
-    },
-    afterUpdate: async ({ table, data, where, result }) => {
-      // Clear related caches, send webhooks, etc.
-    },
-    beforeDelete: async ({ table, where }) => {
-      // Prevent deletion, check constraints, etc.
-    },
-    afterDelete: async ({ table, where, result }) => {
-      // Clean up related data, update aggregates, etc.
-    },
-  }
-})
-```
-
-### Query Scopes
-
-```ts
-// Define scopes on your models
-const User = {
-  name: 'User',
-  table: 'users',
-  scopes: {
-    active: (qb) => qb.where({ status: 'active' }),
-    verified: (qb) => qb.where({ email_verified_at: ['IS NOT', null] }),
-    premium: (qb) => qb.where({ subscription: 'premium' }),
-  },
-  // ... other model properties
-}
-
-// Use scopes in queries
-const activeUsers = await db.selectFrom('users')
-  .scope('active')
-  .scope('verified')
   .get()
-```
-
-### Relations with Constraints
-
-```ts
-// Eager load with constraints
-const users = await db.selectFrom('users')
-  .with({
-    posts: (qb) => qb.where('published', '=', true).orderBy('created_at', 'desc')
-  })
-  .get()
-
-// Check for related records
-const usersWithPosts = await db.selectFrom('users')
-  .has('posts')
-  .get()
-
-// Query by relationship existence
-const activeAuthors = await db.selectFrom('users')
-  .whereHas('posts', (qb) => qb.where('published', '=', true))
-  .get()
-```
-
-## 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)
-```
-
-## Database Seeding
-
-Populate your database with test data using seeders powered by [ts-mocker](https://github.com/stacksjs/ts-mocker):
-
-### Creating a Seeder
-
-```bash
-# Generate a new seeder
-bun qb make:seeder User
-
-# This creates database/seeders/UserSeeder.ts
-```
-
-### Writing a Seeder
-
-```ts
-import { Seeder } from 'bun-query-builder'
-import { faker } from 'ts-mocker'
 
-export default class UserSeeder extends Seeder {
-  async run(qb: any): Promise<void> {
-    // Generate 50 users with realistic fake data
-    const users = Array.from({ length: 50 }, () => ({
-      name: faker.person.fullName(),
-      email: faker.internet.email(),
-      age: faker.number.int(18, 80),
-      role: faker.helpers.arrayElement(['admin', 'user', 'moderator']),
-      created_at: new Date(),
-      updated_at: new Date(),
-    }))
-
-    await qb.table('users').insert(users).execute()
-  }
-
-  // Control execution order (lower runs first)
-  get order(): number {
-    return 10 // Default is 100
-  }
-}
-```
-
-### Running Seeders
-
-```bash
-# Run all seeders
-bun qb seed
-bun qb db:seed
-
-# Run a specific seeder
-bun qb seed --class UserSeeder
-
-# Drop all tables, re-run migrations and seed
-bun qb db:fresh
-```
-
-### Programmatic Usage
-
-```ts
-import { runSeeders, runSeeder } from 'bun-query-builder'
-
-// Run all seeders
-await runSeeders({
-  seedersDir: './database/seeders',
-  verbose: true
-})
-
-// Run specific seeder
-await runSeeder('UserSeeder', { verbose: true })
-```
-
-### CLI
-
-```bash
-# Model Generation
-query-builder make:model User
-query-builder make:model Post --table=blog_posts
-query-builder model:show User                   # Show detailed model info
-
-# Schema Introspection
-query-builder introspect ./app/Models --verbose
-query-builder sql ./app/Models users --limit 5
-
-# Migrations
-query-builder migrate ./app/Models --dialect postgres
-query-builder migrate:generate                  # Generate migration from drift
-query-builder migrate:status                    # Show migration status
-query-builder migrate:list                      # List all migrations
-query-builder migrate:rollback --steps 2        # Rollback migrations
-query-builder migrate:fresh ./app/Models
-query-builder reset ./app/Models
-
-# Database Info
-query-builder db:info                           # Show database statistics
-query-builder db:stats                          # Alias for db:info
-query-builder inspect users                     # Inspect table structure
-query-builder table:info users                  # Alias for inspect
-query-builder db:wipe --force                   # Drop all tables
-query-builder db:optimize                       # Optimize database (VACUUM, ANALYZE)
-query-builder db:optimize --aggressive          # Aggressive optimization
-
-# Interactive Console
-query-builder console                           # Start REPL
-query-builder tinker                            # Alias for console
-
-# Seeders
-query-builder make:seeder User
-query-builder seed
-query-builder db:seed --class UserSeeder
-query-builder db:fresh
-
-# Data Management
-query-builder export users --format json
-query-builder export users --format csv --output users.csv
-query-builder import users users.json --truncate
-query-builder dump --tables users,posts
-
-# Cache Management
-query-builder cache:clear
-query-builder cache:stats
-query-builder cache:config --size 500
-
-# Performance
-query-builder benchmark --iterations 1000
-query-builder benchmark --operations select,insert
-query-builder query:explain-all ./queries        # Batch EXPLAIN analysis
-
-# Schema Validation
-query-builder validate:schema ./app/Models
-query-builder check                             # Alias for validate:schema
-
-# Connectivity
-query-builder ping
-query-builder wait-ready --attempts 30 --delay 250
-
-# Execute SQL
-query-builder file ./migrations/seed.sql
-query-builder unsafe "SELECT * FROM users WHERE id = $1" --params "[1]"
-query-builder explain "SELECT * FROM users WHERE active = true"
-
-# Diagrams & Visualization
-query-builder relation:diagram                   # Generate Mermaid ER diagram
-query-builder relation:diagram --format dot     # Generate Graphviz DOT
-query-builder relation:diagram --output schema.mmd
+// Insert
+await QueryBuilder
+  .insertInto('users')
+  .values({ name: 'John', email: 'john@example.com' })
+  .execute()
+
+// Update
+await QueryBuilder
+  .update('users')
+  .set({ active: false })
+  .where('id', '=', 1)
+  .execute()
+
+// Delete
+await QueryBuilder
+  .deleteFrom('users')
+  .where('id', '=', 1)
+  .execute()
 ```
 
-## Performance
-
-**🏆 bun-query-builder wins 13 out of 16 benchmarks (81.25%)**
-
-### Summary
-
-| Category | Win Rate | Performance vs Best |
-|----------|----------|-------------------|
-| Basic Queries | 7/7 (100%) 🎯 | 1.36x-29.29x faster |
-| Advanced Queries | 4/5 (80%) | 1.01x-3.96x faster |
-| Batch Operations | 2/4 (50%) | 1.45x-4.83x faster |
-
-### Key Performance Wins
-
-🚀 **Dominant in Basic Queries:**
-
-- **29.29x faster** than Prisma in DELETE operations
-- **16.45x faster** than Prisma in SELECT with LIMIT
-- **14.86x faster** than Prisma in SELECT active users
-- **13.8x faster** than Prisma in SELECT by ID
-- **12.65x faster** than Prisma in COUNT queries
-
-⚡ **Strong in Advanced Queries:**
-
-- **3.96x faster** than Drizzle in AGGREGATE queries
-- **2.99x faster** than Prisma in GROUP BY + HAVING
-- **1.28x faster** than Prisma in JOIN operations
-- **1.03x faster** than Kysely in JOIN operations
-- **1.02x faster** than Kysely in AGGREGATE queries
-
-💪 **Competitive in Batch Operations:**
-
-- **4.83x faster** than Prisma in DELETE MANY
-- **1.45x faster** than Kysely in DELETE MANY
-- Within 14% of Kysely on INSERT MANY
-
-### Perfect Category
-
-- **100% wins** in basic CRUD operations (7/7) 🎯 - Beating Kysely, Drizzle, and Prisma in every single basic query
-
-### The Trade-offs (3 out of 16)
-
-- **WHERE: Complex conditions** - Kysely 1.05x faster
-- **ORDER BY + LIMIT** - Kysely 1.07x faster
-- **SELECT: Large result set (1000 rows)**
-
-**Note:** Two additional benchmarks where we're competitive but not winning:
-
-- **INSERT MANY: 100 users** - Kysely 1.14x faster
-- **UPDATE MANY** - Prisma 1.10x faster
-
-### Why Fast?
-
-bun-query-builder leverages Bun's native SQLite driver with:
-
-- **Direct BunDatabase access** - No abstraction layers
-- **Statement caching** - Prepared statements reused across queries
-- **Ultra-fast path** - Optimized execution for queries without hooks/soft-deletes
-- **Smart optimizations** - For-loop template processing, minimal allocations
-
-**[View Full Benchmark Results →](./packages/benchmark/README.md)**
-
-## 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.
+## Features
 
-- [JetBrains](https://www.jetbrains.com/)
-- [The Solana Foundation](https://solana.com/)
+- **Typed from Models** - Infer tables, columns, and primary keys from your model files
+- **Fluent Builder** - `select`, `insert`, `update`, `delete`, `where`, `join`, `groupBy`, `having`, `union`
+- **Aggregations** - `count()`, `avg()`, `sum()`, `max()`, `min()` with full type safety
+- **Batch Operations** - `insertMany()`, `updateMany()`, `deleteMany()` for efficient bulk operations
+- **Relations** - `with(...)`, `withCount(...)`, `whereHas(...)`, `has()`, `doesntHave()`
+- **Query Caching** - Built-in LRU cache with TTL support
+- **Model Hooks** - Lifecycle events for `beforeCreate`, `afterCreate`, `beforeUpdate`, `afterUpdate`, `beforeDelete`, `afterDelete`
+- **Transactions** - Full transaction support with retries, backoff, and isolation levels
+- **Migrations** - Generate and execute migrations from models with diff support
+- **Seeders** - Database seeding with fake data generation
+- **Soft Deletes** - `withTrashed()`, `onlyTrashed()` for logical deletion
+- **Pagination** - `paginate`, `simplePaginate`, `cursorPaginate`, `chunk`, `chunkById`
+- **CLI** - Introspection, query printing, connectivity checks, and more
 
 ## 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 -->
+MIT

package/dist/__tests__/type-narrowing-compile.d.ts

@@ -0,0 +1 @@
+

package/dist/__tests__/type-narrowing.test.d.ts

@@ -0,0 +1 @@
+

package/dist/actions/benchmark.d.ts

@@ -5,4 +5,4 @@ export declare function runBenchmark(options?: BenchmarkOptions): Promise<void>;
 export declare interface BenchmarkOptions {
   operations?: string
   iterations?: number
-}
+}

package/dist/actions/cache.d.ts

@@ -15,4 +15,4 @@ export declare function cacheStats(): Promise<void>;
 export declare function cacheConfig(options?: CacheConfigOptions): Promise<void>;
 export declare interface CacheConfigOptions {
   size?: number
-}
+}

package/dist/actions/console.d.ts

@@ -5,4 +5,4 @@ export declare function startConsole(): Promise<void>;
 /**
  * Tinker - alias for startConsole
  */
-export declare function tinker(): Promise<void>;
+export declare function tinker(): Promise<void>;

package/dist/actions/data.d.ts

@@ -1,6 +1,7 @@
 /**
  * Export data from a table
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function exportData(tableName: string, options?: ExportOptions): Promise<void>;
 /**
  * Import data into a table
@@ -22,4 +23,4 @@ export declare interface ImportOptions {
 export declare interface DumpOptions {
   tables?: string
   output?: string
-}
+}

package/dist/actions/db-info.d.ts

@@ -19,4 +19,4 @@ export declare interface DatabaseInfo {
   tables: TableInfo[]
   totalTables: number
   totalRows: number
-}
+}

package/dist/actions/db-optimize.d.ts

@@ -9,4 +9,4 @@ export declare interface OptimizeOptions {
   tables?: string[]
   verbose?: boolean
 }
-export { dbOptimize as optimizeDatabase };
+export { dbOptimize as optimizeDatabase };

package/dist/actions/db-wipe.d.ts

@@ -8,4 +8,4 @@ export declare interface WipeOptions {
   force?: boolean
   verbose?: boolean
 }
-export { dbWipe as wipeDatabase };
+export { dbWipe as wipeDatabase };

package/dist/actions/explain.d.ts

@@ -1 +1 @@
-export declare function explain(sql: string): void;
+export declare function explain(sql: string): Promise<void>;

package/dist/actions/file.d.ts

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

package/dist/actions/index.d.ts

@@ -22,4 +22,4 @@ export { freshDatabase, makeSeeder, runSeeder, runSeeders } from './seed';
 export { sql } from './sql';
 export { unsafe } from './unsafe';
 export { checkSchema, validateSchema } from './validate';
-export { waitReady } from './wait-ready';
+export { waitReady } from './wait-ready';

package/dist/actions/inspect.d.ts

@@ -27,4 +27,4 @@ export declare interface TableInspection {
 }
 export declare interface InspectOptions {
   verbose?: boolean
-}
+}

package/dist/actions/introspect.d.ts

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

package/dist/actions/make-model.d.ts

@@ -6,4 +6,4 @@ export declare interface MakeModelOptions {
   table?: string
   dir?: string
   timestamps?: boolean
-}
+}

package/dist/actions/migrate-generate.d.ts

@@ -3,4 +3,4 @@ import type { GenerateMigrationResult, MigrateOptions } from '@/types';
  * Generate migration files from model changes (alias for generateMigration)
  */
 export declare function migrateGenerate(dir?: string, opts?: MigrateOptions): Promise<GenerateMigrationResult>;
-export { migrateGenerate as generateMigration };
+export { migrateGenerate as generateMigration };

package/dist/actions/migrate-rollback.d.ts

@@ -10,4 +10,4 @@
 export declare function migrateRollback(options?: RollbackOptions): Promise<void>;
 export declare interface RollbackOptions {
   steps?: number
-}
+}

package/dist/actions/migrate-status.d.ts

@@ -10,4 +10,4 @@ export declare interface MigrationStatus {
   file: string
   status: 'executed' | 'pending' | 'transient'
   executedAt?: string
-}
+}

package/dist/actions/migrate.d.ts

@@ -28,4 +28,4 @@ export declare function copyModelsToGenerated(_dir?: string, _workspaceRoot?: st
  * Clear the generated directory to force fresh migration generation
  * This is called during migrate:fresh to ensure all models are treated as new
  */
-export declare function clearGeneratedDirectory(workspaceRoot?: string): Promise<void>;
+export declare function clearGeneratedDirectory(workspaceRoot?: string): Promise<void>;

package/dist/actions/model-show.d.ts

@@ -19,4 +19,4 @@ export declare interface ModelDetails {
   timestamps?: boolean
   softDeletes?: boolean
 }
-export { modelShow as showModel };
+export { modelShow as showModel };

package/dist/actions/ping.d.ts

@@ -1 +1 @@
-export declare function ping(): void;
+export declare function ping(): Promise<void>;

package/dist/actions/query-explain-all.d.ts

@@ -13,4 +13,4 @@ export declare interface ExplainResult {
   plan: any[]
   error?: string
 }
-export { queryExplainAll as explainAllQueries };
+export { queryExplainAll as explainAllQueries };