bun-query-builder 0.1.2

package/dist/loader.d.ts

@@ -0,0 +1,6 @@
+import type { ModelRecord } from './schema';
+export declare function loadModels(options: LoadModelsOptions): Promise<ModelRecord>;
+export declare interface LoadModelsOptions {
+  cwd?: string
+  modelsDir: string
+}

package/dist/meta.d.ts

@@ -0,0 +1,14 @@
+import type { ModelRecord } from './schema';
+export declare function buildSchemaMeta(models: ModelRecord): SchemaMeta;
+export declare interface SchemaMeta {
+  modelToTable: Record<string, string>
+  tableToModel: Record<string, string>
+  primaryKeys: Record<string, string>
+  relations?: Record<string, {
+    hasOne?: Record<string, string>
+    hasMany?: Record<string, string>
+    belongsTo?: Record<string, string>
+    belongsToMany?: Record<string, string>
+  }>
+  scopes?: Record<string, Record<string, (qb: any, value?: any) => any>>
+}

package/dist/migrations.d.ts

@@ -0,0 +1,65 @@
+import type { ModelRecord } from './schema';
+import type { SupportedDialect } from './types';
+export declare function buildMigrationPlan(models: ModelRecord, options: InferenceOptions): MigrationPlan;
+export declare function generateSql(plan: MigrationPlan): string[];
+/**
+ * Helper function to convert SQL statements array to a single string (for backward compatibility)
+ */
+export declare function generateSqlString(plan: MigrationPlan): string;
+/**
+ * Helper function to convert diff SQL statements array to a single string (for backward compatibility)
+ */
+export declare function generateDiffSqlString(previous: MigrationPlan | undefined, next: MigrationPlan): string;
+/**
+ * Compute a stable hash for a migration plan. Useful for snapshotting.
+ */
+export declare function hashMigrationPlan(plan: MigrationPlan): string;
+/**
+ * Generate safe, additive-only SQL to migrate from a previous plan to a new plan.
+ * - Creates new tables
+ * - Adds new columns (no drops or type/nullable/default changes)
+ * - Adds new foreign keys for newly added columns
+ * - Adds new indexes and unique indexes
+ *
+ * If there is no previous plan or the dialect changed, generates full SQL.
+ */
+export declare function generateDiffSql(previous: MigrationPlan | undefined, next: MigrationPlan): string[];
+export declare interface ColumnPlan {
+  name: string
+  type: NormalizedColumnType
+  isPrimaryKey: boolean
+  isUnique: boolean
+  isNullable: boolean
+  hasDefault: boolean
+  defaultValue?: PrimitiveDefault
+  references?: { table: string, column: string }
+}
+export declare interface IndexPlan {
+  name: string
+  columns: string[]
+  type: 'index' | 'unique'
+}
+export declare interface TablePlan {
+  table: string
+  columns: ColumnPlan[]
+  indexes: IndexPlan[]
+}
+export declare interface MigrationPlan {
+  dialect: SupportedDialect
+  tables: TablePlan[]
+}
+export declare interface InferenceOptions {
+  dialect: SupportedDialect
+}
+export type PrimitiveDefault = string | number | boolean | bigint | Date
+export type NormalizedColumnType = | 'string'
+  | 'text'
+  | 'boolean'
+  | 'integer'
+  | 'bigint'
+  | 'float'
+  | 'double'
+  | 'decimal'
+  | 'date'
+  | 'datetime'
+  | 'json'

package/dist/schema.d.ts

@@ -0,0 +1,220 @@
+/**
+ * # `defineModel(model)`
+ *
+ * Freezes and returns a model definition with strong inference for attributes
+ * and options.
+ *
+ * @example
+ * ```ts
+ * const Post = defineModel({
+ *   name: 'Post',
+ *   attributes: {
+ *     title: { validation: { rule: {} // isLength({ min: 1 }) } },
+ *   },
+ * })
+ * ```
+ */
+export declare function defineModel<const T extends ModelDefinition>(model: T): T;
+/**
+ * # `defineModels(models)`
+ *
+ * Freezes and returns a record of model definitions, preserving literal keys so
+ * downstream types (like `DatabaseSchema`) can map model names to table names.
+ *
+ * @example
+ * ```ts
+ * const models = defineModels({ User, Post })
+ * ```
+ */
+export declare function defineModels<const T extends ModelRecord>(models: T): T;
+/**
+ * # `Attribute`
+ *
+ * Describes a model column and its validation/meta options.
+ *
+ * @example
+ * ```ts
+ * const User = defineModel({
+ *   name: 'User',
+ *   attributes: {
+ *     email: { validation: { rule: {} // isEmail() }, unique: true },
+ *     age: { validation: { rule: {} // isInt({ min: 0 }) }, default: 0 },
+ *   }
+ * })
+ * ```
+ */
+export declare interface Attribute {
+  default?: string | number | boolean | Date
+  unique?: boolean
+  order?: number
+  hidden?: boolean
+  fillable?: boolean
+  guarded?: boolean
+  factory?: (faker: unknown) => any
+  validation: {
+    rule: ValidationType
+    message?: ValidatorMessage
+  }
+}
+export declare interface AttributesElements {
+
+}
+/**
+ * # `CompositeIndex`
+ *
+ * Describes a named multi-column index.
+ *
+ * @example
+ * ```ts
+ * { name: 'user_email_unique', columns: ['email'] }
+ * ```
+ */
+export declare interface CompositeIndex {
+  name: string
+  columns: string[]
+}
+export declare interface Base {
+
+}
+/**
+ * # `ModelOptions`
+ *
+ * Declarative model definition used to build a typed `DatabaseSchema`.
+ *
+ * @example
+ * ```ts
+ * const User = defineModel({
+ *   name: 'User',
+ *   table: 'users',
+ *   primaryKey: 'id',
+ *   attributes: {
+ *     id: { validation: { rule: {} // isInt() } },
+ *     email: { validation: { rule: {} // isEmail() }, unique: true },
+ *   },
+ *   indexes: [{ name: 'users_email_unique', columns: ['email'] }],
+ * })
+ * ```
+ */
+export declare interface ModelOptions extends Base {
+  name: string
+  description?: string
+  table?: string
+  primaryKey?: string
+  autoIncrement?: boolean
+  indexes?: CompositeIndex[]
+  traits?: Record<string, unknown>
+  attributes?: AttributesElements
+  hasOne?: HasOne<ModelNames> | ModelNames[]
+  hasMany?: HasMany<ModelNames> | ModelNames[]
+  belongsTo?: BelongsTo<ModelNames> | ModelNames[]
+  belongsToMany?: BelongsToMany<ModelNames> | ModelNames[]
+  hasOneThrough?: HasOneThrough<ModelNames> | ModelNames[]
+  morphOne?: MorphOne<ModelNames> | ModelNames
+  morphMany?: MorphMany<ModelNames>[] | ModelNames[]
+  morphTo?: MorphTo
+  scopes?: {
+    [key: string]: (value: any) => any
+  }
+  get?: {
+    [key: string]: (value: any) => any
+  }
+  set?: {
+    [key: string]: (value: any) => any
+  }
+}
+/**
+ * # `ValidatorMessage`
+ *
+ * Map of field identifiers to custom error messages returned by validators.
+ */
+export type ValidatorMessage = Record<string, string>
+/**
+ * # `ValidationType`
+ *
+ * External validator rule type (compatible with ts-validation). Kept broad to
+ * avoid a hard dependency while still enabling type inference via rule shape.
+ */
+export type ValidationType = unknown
+export type ModelNames = string
+/**
+ * # Relationship helpers
+ *
+ * Lightweight relationship declarations for model definitions. Each helper is a
+ * record keyed by relation name with the related model name as value.
+ */
+export type HasOne<T extends string> = Record<string, T>
+export type HasMany<T extends string> = Record<string, T>
+export type BelongsTo<T extends string> = Record<string, T>
+export type BelongsToMany<T extends string> = Record<string, T>
+export type HasOneThrough<T extends string> = Record<string, T>
+export type MorphOne<T extends string> = Record<string, T>
+export type MorphMany<T extends string> = Record<string, T>
+export type MorphTo = Record<string, unknown>
+export type ModelDefinition = Readonly<ModelOptions>
+/**
+ * # `ModelRecord`
+ *
+ * Collection of models keyed by model name. Kept flexible to preserve literal
+ * attribute keys and value types.
+ */
+export type ModelRecord = Record<string, any>
+/**
+ * # `InferAttributes<M>`
+ *
+ * Given a `ModelDefinition`, produces a record of attribute names to their
+ * inferred input type based on the validator rule shape.
+ */
+declare type ExtractRuleInput<R> = R extends { validate: (value: infer T) => any }
+  ? T
+  : R extends { test: (value: infer T) => any }
+    ? T
+    : R extends { getRules: () => Array<{ test: (value: infer T) => any }> }
+      ? T
+      : unknown
+export type InferAttributes<M extends ModelDefinition> = M extends {
+  attributes: infer A extends Record<string, { validation: { rule: any } }>
+}
+  ? { [K in keyof A & string]: ExtractRuleInput<A[K]['validation']['rule']> }
+  : Record<string, unknown>
+/**
+ * # `InferPrimaryKey<M>`
+ *
+ * Extracts a model's primary key field name, defaulting to `'id'`.
+ */
+export type InferPrimaryKey<M extends ModelDefinition> = M extends {
+  primaryKey: infer K extends string
+}
+  ? K
+  : 'id'
+/**
+ * # `InferTableName<M>`
+ *
+ * Resolves the table name from a model: uses `table` when provided, otherwise
+ * falls back to a simple pluralized form of the model name.
+ */
+export type InferTableName<M extends ModelDefinition> = M extends {
+  table: infer T extends string
+}
+  ? T
+  : M extends { name: infer N extends string }
+    ? `${Lowercase<N>}s`
+    : string
+/**
+ * # `DatabaseSchema<Models>`
+ *
+ * Maps model definitions to a concrete database schema shape containing the
+ * table columns and primary key. This is the primary input for the query
+ * builder's type-safety.
+ *
+ * @example
+ * ```ts
+ * const models = defineModels({ User, Post })
+ * type Schema = DatabaseSchema<typeof models>
+ * ```
+ */
+export type DatabaseSchema<MRecord extends ModelRecord> = {
+  [MName in keyof MRecord & string as InferTableName<MRecord[MName]>]: {
+    columns: InferAttributes<MRecord[MName]>
+    primaryKey: InferPrimaryKey<MRecord[MName]>
+  };
+}

package/dist/types.d.ts

@@ -0,0 +1,216 @@
+/**
+ * # `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 {
+  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 {
+  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 {
+  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 {
+  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 {
+  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 {
+  foreignKeyFormat: 'singularParent_id' | 'parentId'
+  singularizeStrategy?: 'stripTrailingS' | 'none'
+}
+/**
+ * # `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 {
+  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 {
+  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 {
+  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 {
+  verbose: boolean
+  dialect: SupportedDialect
+  timestamps: TimestampConfig
+  pagination: PaginationConfig
+  aliasing: AliasingConfig
+  relations: RelationsConfig
+  transactionDefaults: TransactionDefaultsConfig
+  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 {
+  verbose: boolean
+}
+export declare interface SqlOptions {
+  limit?: number
+}
+export declare interface WaitReadyOptions {
+  attempts?: number
+  delay?: number
+}
+export declare interface FileOptions {
+  params?: string
+}
+export declare interface IntrospectOptions {
+  verbose?: boolean
+}
+export declare interface MigrateOptions {
+  dialect?: SupportedDialect
+  state?: string
+  apply?: boolean
+  full?: boolean
+}
+export declare interface GenerateMigrationResult {
+  sql: string
+  sqlStatements: string[]
+  hasChanges: boolean
+  plan: any
+}
+export declare 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

@@ -0,0 +1,99 @@
+{
+  "name": "bun-query-builder",
+  "type": "module",
+  "version": "0.1.2",
+  "description": "A simple yet performant query builder for TypeScript. Built with Bun.",
+  "author": "Chris Breuer <chris@stacksjs.org>",
+  "license": "MIT",
+  "homepage": "https://github.com/stacksjs/bun-query-builder#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/bun-query-builder.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/bun-query-builder/issues"
+  },
+  "keywords": [
+    "typescript",
+    "query-builder",
+    "bun",
+    "package"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "import": "./dist/*"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "query-builder": "./dist/bin/cli.js",
+    "qbx": "./dist/bin/cli.js",
+    "qb": "./dist/bin/cli.js"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun --bun build.ts && bun run compile",
+    "compile": "bun build ./bin/cli.ts --compile --minify --outfile bin/query-builder",
+    "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",
+    "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",
+    "fresh": "bunx rimraf node_modules/ bun.lock && bun i",
+    "prepublishOnly": "bun --bun run build && bun run compile:all && bun run zip",
+    "test": "bun test",
+    "lint": "bunx --bun eslint .",
+    "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",
+    "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"
+  },
+  "dependencies": {
+    "@stacksjs/launchpad": "^0.6.4"
+  },
+  "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"
+  },
+  "overrides": {
+    "unconfig": "0.3.10"
+  },
+  "git-hooks": {
+    "pre-commit": {
+      "staged-lint": {
+        "*.{js,ts,json,yaml,yml,md}": "bunx --bun eslint --fix"
+      }
+    },
+    "commit-msg": "bunx gitlint --edit .git/COMMIT_EDITMSG"
+  }
+}