bun-query-builder 0.1.8 → 0.1.10

package/dist/migrations.d.ts

@@ -1,26 +1,33 @@
 import type { ModelRecord } from './schema';
 import type { SupportedDialect } from './types';
-
-declare function findWorkspaceRoot(startPath: string): string;
-declare function ensureSqlDirectory(): string;
-declare function createMigrationFile(statement: string, fileName: string): boolean;
-export declare type PrimitiveDefault = string | number | boolean | bigint | Date
-
-export type NormalizedColumnType =
-  | 'string'
-  | 'text'
-  | 'boolean'
-  | 'integer'
-  | 'bigint'
-  | 'float'
-  | 'double'
-  | 'decimal'
-  | 'date'
-  | 'datetime'
-  | 'json'
-  | 'enum'
-
-export interface ColumnPlan {
+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 comprehensive SQL to migrate from a previous plan to a new plan.
+ * - Creates new tables
+ * - Drops removed tables
+ * - Adds new columns
+ * - Drops removed columns
+ * - Adds new indexes
+ * - Drops removed indexes
+ * - Adds new foreign keys for newly added columns
+ *
+ * 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
@@ -31,35 +38,33 @@ export interface ColumnPlan {
   references?: { table: string, column: string }
   enumValues?: string[]
 }
-
-export interface IndexPlan {
+export declare interface IndexPlan {
   name: string
   columns: string[]
   type: 'index' | 'unique'
 }
-
-export interface TablePlan {
+export declare interface TablePlan {
   table: string
   columns: ColumnPlan[]
   indexes: IndexPlan[]
 }
-
-export interface MigrationPlan {
+export declare interface MigrationPlan {
   dialect: SupportedDialect
   tables: TablePlan[]
 }
-declare function guessTypeFromName(columnName: string): NormalizedColumnType | undefined;
-declare function normalizeDefaultValue(value: unknown): PrimitiveDefault | undefined;
-declare function detectEnumFromValidationRule(rule: unknown): string[] | undefined;
-declare function detectTypeFromValidationRule(rule: unknown): NormalizedColumnType | undefined;
-export declare function buildMigrationPlan(models: ModelRecord, options: InferenceOptions): MigrationPlan;
-export declare function generateSql(plan: MigrationPlan): string[];
-export declare function generateSqlString(plan: MigrationPlan): string;
-export declare function generateDiffSqlString(previous: MigrationPlan | undefined, next: MigrationPlan): string;
-export declare function hashMigrationPlan(plan: MigrationPlan): string;
-declare function canonicalize(value: any): any;
-declare function mapTablesByName(tables: TablePlan[]): Record<string, TablePlan>;
-declare function mapColumnsByName(columns: ColumnPlan[]): Record<string, ColumnPlan>;
-declare function columnsAreDifferent(col1: ColumnPlan, col2: ColumnPlan): boolean;
-declare function mapIndexesByKey(indexes: IndexPlan[]): Record<string, IndexPlan>;
-export declare function generateDiffSql(previous: MigrationPlan | undefined, next: MigrationPlan): string[];
+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'
+  | 'enum'

package/dist/schema.d.ts

@@ -1,8 +1,49 @@
-export declare type ValidatorMessage = Record<string, string>
-
-export type ValidationType = unknown
-
-export interface Attribute {
+/**
+ * # `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
@@ -15,33 +56,46 @@ export interface Attribute {
     message?: ValidatorMessage
   }
 }
+export declare interface AttributesElements {
 
-export interface AttributesElements {
-  [key: string]: Attribute
 }
-
-export interface CompositeIndex {
+/**
+ * # `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 {
 
-export interface Base {}
-
-export type ModelNames = string
-
-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, { through: T, target: T }>
-export type HasManyThrough<T extends string> = Record<string, { through: T, target: 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 MorphToMany<T extends string> = Record<string, T>
-export type MorphedByMany<T extends string> = Record<string, T>
-
-export interface ModelOptions extends 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
@@ -71,9 +125,102 @@ export interface ModelOptions extends Base {
     [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, { through: T, target: T }>
+export type HasManyThrough<T extends string> = Record<string, { through: T, target: 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 MorphToMany<T extends string> = Record<string, T>
+export type MorphedByMany<T extends string> = Record<string, T>
 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>
-export declare function defineModel<const T extends ModelDefinition>(model: T): T;
-export declare function defineModels<const T extends ModelRecord>(models: T): T;
+/**
+ * # `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/seeder.d.ts

@@ -1,21 +1,26 @@
-export declare abstract class Seeder {
-  abstract run(qb: any): Promise<void>
-
-  get order(): number {
-    return 100
-  }
-
-  get description(): string | undefined {
-    return undefined
-  }
-}
+/**
+ * Helper function to create a seeder
+ */
+export declare function defineSeeder(seederClass: new () => Seeder): new () => Seeder;
+/**
+ * Seeder configuration options
+ */
 export declare interface SeederConfig {
   seedersDir?: string
   seeders?: string[]
   verbose?: boolean
 }
+/**
+ * Options for running seeders
+ */
 export declare interface RunSeederOptions {
   class?: string
   verbose?: boolean
 }
-export declare function defineSeeder(seederClass?: new ()): new () => Seeder;
+/**
+ * Base seeder class that all seeders should extend.
+ * Provides access to query builder and faker for generating test data.
+ */
+export declare abstract class Seeder {
+  abstract run(qb: any): Promise<void>;
+}

package/dist/types.d.ts

@@ -1,49 +1,127 @@
-export declare type SupportedDialect = 'postgres' | 'mysql' | 'sqlite'
-
-export interface TransactionBackoffConfig {
+/**
+ * # `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
 }
-
-export interface TransactionDefaultsConfig {
+/**
+ * # `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
 }
-
-export interface TimestampConfig {
+/**
+ * # `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
 }
-
-export interface PaginationConfig {
+/**
+ * # `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
 }
-
-export interface AliasingConfig {
+/**
+ * # `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'
 }
-
-export interface RelationsConfig {
+/**
+ * # `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'
   maxDepth?: number
   maxEagerLoad?: number
   detectCycles?: boolean
 }
-
-export interface SqlConfig {
+/**
+ * # `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'
 }
-
-export interface QueryHooks {
+/**
+ * # `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
@@ -55,12 +133,17 @@ export interface QueryHooks {
   beforeDelete?: (event: { table: string, where?: any }) => void | Promise<void>
   afterDelete?: (event: { table: string, where?: any, result: any }) => void | Promise<void>
 }
-
-export interface FeatureToggles {
+/**
+ * # `FeatureToggles`
+ *
+ * Optional features that may be enabled per instance.
+ *
+ * - `distinctOn`: Enables PostgreSQL-like `DISTINCT ON (...)` behavior in builders.
+ */
+export declare interface FeatureToggles {
   distinctOn: boolean
 }
-
-export interface DatabaseConfig {
+export declare interface DatabaseConfig {
   database: string
   username: string
   password: string
@@ -68,13 +151,26 @@ export interface DatabaseConfig {
   url?: string
   port: number
 }
-
-export interface QueryBuilderConfig {
+/**
+ * # `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
-
   database: DatabaseConfig
-
   timestamps: TimestampConfig
   pagination: PaginationConfig
   aliasing: AliasingConfig
@@ -83,51 +179,56 @@ export 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 interface CliOption {
+export declare interface CliOption {
   verbose: boolean
 }
-
-export interface SqlOptions {
+export declare interface SqlOptions {
   limit?: number
 }
-
-export interface WaitReadyOptions {
+export declare interface WaitReadyOptions {
   attempts?: number
   delay?: number
 }
-
-export interface FileOptions {
+export declare interface FileOptions {
   params?: string
 }
-
-export interface IntrospectOptions {
+export declare interface IntrospectOptions {
   verbose?: boolean
 }
-
-export interface MigrateOptions {
+export declare interface MigrateOptions {
   dialect?: SupportedDialect
   state?: string
   apply?: boolean
   full?: boolean
 }
-
-export interface GenerateMigrationResult {
+export declare interface GenerateMigrationResult {
   sql: string
   sqlStatements: string[]
   hasChanges: boolean
   plan: any
 }
-
-export interface UnsafeOptions {
+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

@@ -1,7 +1,7 @@
 {
   "name": "bun-query-builder",
   "type": "module",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "A simple yet performant query builder for TypeScript. Built with Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",