bun-query-builder 0.1.5 → 0.1.7

package/dist/loader.d.ts

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

package/dist/meta.d.ts

@@ -1,5 +1,5 @@
 import type { ModelRecord } from './schema';
-export declare function buildSchemaMeta(models: ModelRecord): SchemaMeta;
+
 export declare interface SchemaMeta {
   modelToTable: Record<string, string>
   tableToModel: Record<string, string>
@@ -18,4 +18,5 @@ export declare interface SchemaMeta {
     morphedByMany?: Record<string, string>
   }>
   scopes?: Record<string, Record<string, (qb: any, value?: any) => any>>
-}
+}
+export declare function buildSchemaMeta(models: ModelRecord): SchemaMeta;

package/dist/migrations.d.ts

@@ -1,33 +1,26 @@
 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 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 {
+
+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 {
   name: string
   type: NormalizedColumnType
   isPrimaryKey: boolean
@@ -38,33 +31,35 @@ export declare interface ColumnPlan {
   references?: { table: string, column: string }
   enumValues?: string[]
 }
-export declare interface IndexPlan {
+
+export interface IndexPlan {
   name: string
   columns: string[]
   type: 'index' | 'unique'
 }
-export declare interface TablePlan {
+
+export interface TablePlan {
   table: string
   columns: ColumnPlan[]
   indexes: IndexPlan[]
 }
-export declare interface MigrationPlan {
+
+export 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'
-  | 'enum'
+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[];

package/dist/schema.d.ts

@@ -1,49 +1,8 @@
-/**
- * # `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 {
+export declare type ValidatorMessage = Record<string, string>
+
+export type ValidationType = unknown
+
+export interface Attribute {
   default?: string | number | boolean | Date
   unique?: boolean
   order?: number
@@ -56,46 +15,33 @@ export declare interface Attribute {
     message?: ValidatorMessage
   }
 }
-export declare interface AttributesElements {
 
+export interface AttributesElements {
+  [key: string]: Attribute
 }
-/**
- * # `CompositeIndex`
- *
- * Describes a named multi-column index.
- *
- * @example
- * ```ts
- * { name: 'user_email_unique', columns: ['email'] }
- * ```
- */
-export declare interface CompositeIndex {
+
+export 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 {
+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 {
   name: string
   description?: string
   table?: string
@@ -125,102 +71,9 @@ export declare 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>
-/**
- * # `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]>
-  };
-}
+export declare function defineModel<const T extends ModelDefinition>(model: T): T;
+export declare function defineModels<const T extends ModelRecord>(models: T): T;

package/dist/seeder.d.ts

@@ -1,26 +1,21 @@
-/**
- * Helper function to create a seeder
- */
-export declare function defineSeeder(seederClass: new () => Seeder): new () => Seeder;
-/**
- * Seeder configuration options
- */
+export declare abstract class Seeder {
+  abstract run(qb: any): Promise<void>
+
+  get order(): number {
+    return 100
+  }
+
+  get description(): string | undefined {
+    return undefined
+  }
+}
 export declare interface SeederConfig {
   seedersDir?: string
   seeders?: string[]
   verbose?: boolean
 }
-/**
- * Options for running seeders
- */
 export declare interface RunSeederOptions {
   class?: string
   verbose?: boolean
 }
-/**
- * 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>;
-}
+export declare function defineSeeder(seederClass?: new ()): new () => Seeder;

package/dist/types.d.ts

@@ -1,127 +1,49 @@
-/**
- * # `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
@@ -133,17 +55,12 @@ export declare interface QueryHooks {
   beforeDelete?: (event: { table: string, where?: any }) => void | Promise<void>
   afterDelete?: (event: { table: string, where?: any, result: any }) => void | Promise<void>
 }
-/**
- * # `FeatureToggles`
- *
- * Optional features that may be enabled per instance.
- *
- * - `distinctOn`: Enables PostgreSQL-like `DISTINCT ON (...)` behavior in builders.
- */
-export declare interface FeatureToggles {
+
+export interface FeatureToggles {
   distinctOn: boolean
 }
-export declare interface DatabaseConfig {
+
+export interface DatabaseConfig {
   database: string
   username: string
   password: string
@@ -151,26 +68,13 @@ export declare interface DatabaseConfig {
   url?: string
   port: number
 }
-/**
- * # `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 QueryBuilderConfig {
   verbose: boolean
   dialect: SupportedDialect
+
   database: DatabaseConfig
+
   timestamps: TimestampConfig
   pagination: PaginationConfig
   aliasing: AliasingConfig
@@ -179,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'
+}