bun-query-builder 0.1.2 → 0.1.6

package/dist/types.d.ts

@@ -1,158 +1,80 @@
-/**
- * # `TransactionBackoffConfig`
- *
- * Controls exponential backoff between transaction retry attempts.
- *
- * - `baseMs`: Initial delay in milliseconds used for the first retry.
- * - `factor`: Multiplicative growth factor applied per attempt (e.g., 2 = doubles).
- * - `maxMs`: Maximum delay cap in milliseconds; backoff never exceeds this value.
- * - `jitter`: When true, adds a small randomization to the delay to reduce thundering herds.
- *
- * The delay for attempt n (1-indexed) is roughly: min(maxMs, baseMs * factor^(n-1)),
- * optionally adjusted by jitter.
- */
-export declare interface TransactionBackoffConfig {
+export declare type SupportedDialect = 'postgres' | 'mysql' | 'sqlite'
+
+export interface TransactionBackoffConfig {
   baseMs: number
   factor: number
   maxMs: number
   jitter: boolean
 }
-/**
- * # `TransactionDefaultsConfig`
- *
- * Default settings applied to transactional operations.
- *
- * - `retries`: Number of times a transaction may be retried on retriable errors
- *   (e.g., deadlocks, serialization failures).
- * - `isolation`: Transaction isolation level.
- *   - 'read committed': Prevents dirty reads; non-repeatable reads possible.
- *   - 'repeatable read': Ensures stable snapshot for a transaction; phantom reads may vary by DB.
- *   - 'serializable': Highest isolation; transactions appear to run one-by-one.
- * - `sqlStates`: Additional vendor error codes considered retriable.
- * - `backoff`: Backoff configuration applied between retries.
- */
-export declare interface TransactionDefaultsConfig {
+
+export interface TransactionDefaultsConfig {
   retries: number
   isolation?: 'read committed' | 'repeatable read' | 'serializable'
   sqlStates: string[]
   backoff: TransactionBackoffConfig
 }
-/**
- * # `TimestampConfig`
- *
- * Column naming conventions for timestamp fields used by helpers.
- *
- * - `createdAt`: Column name for row creation time (e.g., 'created_at').
- * - `updatedAt`: Column name for last update time (e.g., 'updated_at').
- * - `defaultOrderColumn`: Column used by helpers like `latest()`/`oldest()`.
- */
-export declare interface TimestampConfig {
+
+export interface TimestampConfig {
   createdAt: string
   updatedAt: string
   defaultOrderColumn: string
 }
-/**
- * # `PaginationConfig`
- *
- * Defaults for result pagination helpers.
- *
- * - `defaultPerPage`: Default LIMIT used by paginate helpers when not specified.
- * - `cursorColumn`: Default column used for cursor-based pagination (e.g., 'id').
- */
-export declare interface PaginationConfig {
+
+export interface PaginationConfig {
   defaultPerPage: number
   cursorColumn: string
 }
-/**
- * # `AliasingConfig`
- *
- * Controls how selected columns from joined relations are aliased.
- *
- * - `relationColumnAliasFormat`:
- *   - 'table_column': Aliases as `${table}_${column}` (e.g., `posts_title`).
- *   - 'table.dot.column': Aliases with dot notation (e.g., `posts.title`).
- *   - 'camelCase': Aliases as camelCase from `${table}_${column}` (e.g., `postsTitle`).
- */
-export declare interface AliasingConfig {
+
+export interface AliasingConfig {
   relationColumnAliasFormat: 'table_column' | 'table.dot.column' | 'camelCase'
 }
-/**
- * # `RelationsConfig`
- *
- * Conventions for inferring foreign key names and singularization.
- *
- * - `foreignKeyFormat`:
- *   - 'singularParent_id': Uses `${singular(parent)}_id` (e.g., `user_id`).
- *   - 'parentId': Uses camelCase `parentId` (e.g., `userId`).
- * - `singularizeStrategy`:
- *   - 'stripTrailingS': Naively remove trailing 's' when singularizing (default behavior when enabled elsewhere).
- *   - 'none': Do not singularize relation/table names.
- */
-export declare interface RelationsConfig {
+
+export interface RelationsConfig {
   foreignKeyFormat: 'singularParent_id' | 'parentId'
   singularizeStrategy?: 'stripTrailingS' | 'none'
+  maxDepth?: number
+  maxEagerLoad?: number
+  detectCycles?: boolean
 }
-/**
- * # `SqlConfig`
- *
- * Dialect-specific SQL toggles.
- *
- * - `randomFunction`:
- *   - 'RANDOM()': PostgreSQL/SQLite style function for random ordering.
- *   - 'RAND()': MySQL style function for random ordering.
- * - `sharedLockSyntax`:
- *   - 'FOR SHARE': PostgreSQL style shared lock.
- *   - 'LOCK IN SHARE MODE': MySQL style shared lock.
- * - `jsonContainsMode`:
- *   - 'operator': Use native operators when available (e.g., Postgres `@>`).
- *   - 'function': Use a function-based approach (e.g., `json_contains`) when operators are not available.
- */
-export declare interface SqlConfig {
+
+export interface SqlConfig {
   randomFunction?: 'RANDOM()' | 'RAND()'
   sharedLockSyntax?: 'FOR SHARE' | 'LOCK IN SHARE MODE'
   jsonContainsMode?: 'operator' | 'function'
 }
-/**
- * # `QueryHooks`
- *
- * Optional lifecycle hooks around query execution. These are invoked for any
- * statement executed through the builder (select/insert/update/delete/raw).
- */
-export declare interface QueryHooks {
+
+export interface QueryHooks {
   onQueryStart?: (event: { sql: string, params?: any[], kind?: 'select' | 'insert' | 'update' | 'delete' | 'raw' }) => void
   onQueryEnd?: (event: { sql: string, params?: any[], durationMs: number, rowCount?: number, kind?: 'select' | 'insert' | 'update' | 'delete' | 'raw' }) => void
   onQueryError?: (event: { sql: string, params?: any[], error: any, durationMs: number, kind?: 'select' | 'insert' | 'update' | 'delete' | 'raw' }) => void
   startSpan?: (event: { sql: string, params?: any[], kind?: 'select' | 'insert' | 'update' | 'delete' | 'raw' }) => { end: (error?: any) => void }
-}
-/**
- * # `FeatureToggles`
- *
- * Optional features that may be enabled per instance.
- *
- * - `distinctOn`: Enables PostgreSQL-like `DISTINCT ON (...)` behavior in builders.
- */
-export declare interface FeatureToggles {
+  beforeCreate?: (event: { table: string, data: any }) => void | Promise<void>
+  afterCreate?: (event: { table: string, data: any, result: any }) => void | Promise<void>
+  beforeUpdate?: (event: { table: string, data: any, where?: any }) => void | Promise<void>
+  afterUpdate?: (event: { table: string, data: any, where?: any, result: any }) => void | Promise<void>
+  beforeDelete?: (event: { table: string, where?: any }) => void | Promise<void>
+  afterDelete?: (event: { table: string, where?: any, result: any }) => void | Promise<void>
+}
+
+export interface FeatureToggles {
   distinctOn: boolean
 }
-/**
- * # `QueryBuilderConfig`
- *
- * Global configuration for the query builder.
- *
- * - `verbose`: Enables extra logging/diagnostics from the builder.
- * - `dialect`: Target SQL dialect. See `SupportedDialect` for details.
- * - `timestamps`: Timestamp column naming conventions.
- * - `pagination`: Defaults for pagination helpers.
- * - `aliasing`: How relation columns are aliased in SELECT lists.
- * - `relations`: Foreign key naming and singularization conventions.
- * - `transactionDefaults`: Default retry/backoff/isolation behavior for transactions.
- * - `sql`: Dialect-specific SQL toggles.
- * - `features`: Optional feature flags.
- * - `debug.captureText`: When true, the builder exposes a `toText()` method to capture SQL text in memory for debugging.
- */
-export declare interface QueryBuilderConfig {
+
+export interface DatabaseConfig {
+  database: string
+  username: string
+  password: string
+  host: string
+  url?: string
+  port: number
+}
+
+export interface QueryBuilderConfig {
   verbose: boolean
   dialect: SupportedDialect
+
+  database: DatabaseConfig
+
   timestamps: TimestampConfig
   pagination: PaginationConfig
   aliasing: AliasingConfig
@@ -161,56 +83,51 @@ export declare interface QueryBuilderConfig {
   sql: SqlConfig
   features: FeatureToggles
   debug?: {
-    /** When true, capture query text for debugging via `toText()`. */
     captureText: boolean
   }
   hooks?: QueryHooks
   softDeletes?: {
-    /** When true, apply a default `WHERE deleted_at IS NULL` filter. */
     enabled: boolean
-    /** Column name used for soft delete flag/timestamp. */
     column: string
-    /** When true, default filter is applied unless `.withTrashed()` is called. */
     defaultFilter: boolean
   }
 }
-export declare interface CliOption {
+
+export interface CliOption {
   verbose: boolean
 }
-export declare interface SqlOptions {
+
+export interface SqlOptions {
   limit?: number
 }
-export declare interface WaitReadyOptions {
+
+export interface WaitReadyOptions {
   attempts?: number
   delay?: number
 }
-export declare interface FileOptions {
+
+export interface FileOptions {
   params?: string
 }
-export declare interface IntrospectOptions {
+
+export interface IntrospectOptions {
   verbose?: boolean
 }
-export declare interface MigrateOptions {
+
+export interface MigrateOptions {
   dialect?: SupportedDialect
   state?: string
   apply?: boolean
   full?: boolean
 }
-export declare interface GenerateMigrationResult {
+
+export interface GenerateMigrationResult {
   sql: string
   sqlStatements: string[]
   hasChanges: boolean
   plan: any
 }
-export declare interface UnsafeOptions {
+
+export interface UnsafeOptions {
   params?: string
-}
-/**
- * # `SupportedDialect`
- *
- * The SQL dialect used to tailor generated SQL and certain features.
- * - 'postgres': Uses `RANDOM()`, supports JSON operators (e.g. `@>`), `FOR SHARE`, `FOR UPDATE`, CTEs
- * - 'mysql': Uses `RAND()`, shared locks via `LOCK IN SHARE MODE`
- * - 'sqlite': Lightweight engine; some features are limited or emulated
- */
-export type SupportedDialect = 'postgres' | 'mysql' | 'sqlite'
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bun-query-builder",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.6",
   "description": "A simple yet performant query builder for TypeScript. Built with Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -41,20 +41,20 @@
   ],
   "scripts": {
     "build": "bun --bun build.ts && bun run compile",
-    "compile": "bun build ./bin/cli.ts --compile --minify --outfile bin/query-builder",
+    "compile": "bun build ./bin/cli.ts --compile --minify --outfile bin/qbx",
     "compile:all": "bun run compile:linux-x64 && bun run compile:linux-arm64 && bun run compile:windows-x64 && bun run compile:darwin-x64 && bun run compile:darwin-arm64",
-    "compile:linux-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-x64 --outfile bin/query-builder-linux-x64",
-    "compile:linux-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-arm64 --outfile bin/query-builder-linux-arm64",
-    "compile:windows-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-windows-x64 --outfile bin/query-builder-windows-x64.exe",
-    "compile:darwin-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-x64 --outfile bin/query-builder-darwin-x64",
-    "compile:darwin-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-arm64 --outfile bin/query-builder-darwin-arm64",
+    "compile:linux-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-x64 --outfile bin/qbx-linux-x64",
+    "compile:linux-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-linux-arm64 --outfile bin/qbx-linux-arm64",
+    "compile:windows-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-windows-x64 --outfile bin/qbx-windows-x64.exe",
+    "compile:darwin-x64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-x64 --outfile bin/qbx-darwin-x64",
+    "compile:darwin-arm64": "bun build ./bin/cli.ts --compile --minify --target=bun-darwin-arm64 --outfile bin/qbx-darwin-arm64",
     "zip": "bun run zip:all",
     "zip:all": "bun run zip:linux-x64 && bun run zip:linux-arm64 && bun run zip:windows-x64 && bun run zip:darwin-x64 && bun run zip:darwin-arm64",
-    "zip:linux-x64": "zip -j bin/query-builder-linux-x64.zip bin/query-builder-linux-x64",
-    "zip:linux-arm64": "zip -j bin/query-builder-linux-arm64.zip bin/query-builder-linux-arm64",
-    "zip:windows-x64": "zip -j bin/query-builder-windows-x64.zip bin/query-builder-windows-x64.exe",
-    "zip:darwin-x64": "zip -j bin/query-builder-darwin-x64.zip bin/query-builder-darwin-x64",
-    "zip:darwin-arm64": "zip -j bin/query-builder-darwin-arm64.zip bin/query-builder-darwin-arm64",
+    "zip:linux-x64": "zip -j bin/qbx-linux-x64.zip bin/qbx-linux-x64",
+    "zip:linux-arm64": "zip -j bin/qbx-linux-arm64.zip bin/qbx-linux-arm64",
+    "zip:windows-x64": "zip -j bin/qbx-windows-x64.zip bin/qbx-windows-x64.exe",
+    "zip:darwin-x64": "zip -j bin/qbx-darwin-x64.zip bin/qbx-darwin-x64",
+    "zip:darwin-arm64": "zip -j bin/qbx-darwin-arm64.zip bin/qbx-darwin-arm64",
     "fresh": "bunx rimraf node_modules/ bun.lock && bun i",
     "prepublishOnly": "bun --bun run build && bun run compile:all && bun run zip",
     "test": "bun test",
@@ -62,28 +62,19 @@
     "lint:fix": "bunx --bun eslint . --fix",
     "changelog": "bunx logsmith --verbose",
     "changelog:generate": "bunx logsmith --output CHANGELOG.md",
-    "release": "bun run changelog:generate && bunx bumpx prompt --recursive",
-    "postinstall": "bunx git-hooks",
+    "release": "bun --bun run changelog:generate && bunx --bun bumpx prompt --recursive",
     "dev:docs": "bun --bun vitepress dev docs",
     "build:docs": "bun --bun vitepress build docs",
     "preview:docs": "bun --bun vitepress preview docs",
-    "typecheck": "bun --bun tsc --noEmit"
+    "typecheck": "bun --bun tsc"
   },
   "dependencies": {
-    "@stacksjs/launchpad": "^0.6.4"
+    "@stacksjs/clapp": "^0.2.0",
+    "@stacksjs/ts-validation": "^0.4.7",
+    "ts-mocker": "^0.1.5"
   },
   "devDependencies": {
-    "@stacksjs/bumpx": "^0.1.61",
-    "@stacksjs/docs": "^0.70.23",
-    "@stacksjs/eslint-config": "^4.14.0-beta.3",
-    "@stacksjs/gitlint": "^0.1.5",
-    "@stacksjs/logsmith": "^0.1.15",
-    "@types/bun": "^1.2.21",
-    "buddy-bot": "^0.8.10",
-    "bun-git-hooks": "^0.2.19",
-    "bun-plugin-dtsx": "0.9.5",
-    "bunfig": "^0.15.0",
-    "typescript": "^5.9.2"
+    "bunfig": "^0.15.0"
   },
   "overrides": {
     "unconfig": "0.3.10"

package/LICENSE.md

@@ -1,21 +0,0 @@
-# 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

@@ -1,150 +0,0 @@
-<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 -->