bun-query-builder 0.1.25 → 0.1.27

package/dist/client.d.ts

@@ -103,8 +103,8 @@ export declare interface BaseSelectQueryBuilder<DB extends DatabaseSchema<any>,
   groupByRaw: (fragment: SqlFragment) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   having: (expr: WhereExpression<any>) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   havingRaw: (fragment: SqlFragment) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
-  addSelect: (...columns: (keyof DB[TTable]['columns'] & string | string)[]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
-  select?: (columns: (keyof DB[TTable]['columns'] & string | string)[]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  addSelect: (...columns: ((keyof DB[TTable]['columns'] & string) | string | SqlFragment)[]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  select?: (columns: string | SqlFragment | ((keyof DB[TTable]['columns'] & string) | string | SqlFragment)[]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   selectAll?: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   orderByRaw: (fragment: SqlFragment) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   union: (other: { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
@@ -118,13 +118,22 @@ export declare interface BaseSelectQueryBuilder<DB extends DatabaseSchema<any>,
   whereJsonContainsKey?: (path: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   whereJsonDoesntContainKey?: (path: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   whereJsonLength?: (path: string, opOrLen: WhereOperator | number, len?: number) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
-  with?: (...relations: string[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
-  withPivot?: (relation: string, ...columns: string[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
-  wherePivot?: (relation: string, column: string, opOrValue: any, value?: any) => SelectQueryBuilder<DB, TTable, TSelected, any>
-  wherePivotIn?: (relation: string, column: string, values: any[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
-  wherePivotNotIn?: (relation: string, column: string, values: any[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
-  wherePivotNull?: (relation: string, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
-  wherePivotNotNull?: (relation: string, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  with?: (...relations: WithRelationArg<DB, TTable>[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  whereHas?: (relation: TableRelationName<DB, TTable>, callback?: (qb: any) => any) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  whereDoesntHave?: (relation: TableRelationName<DB, TTable>, callback?: (qb: any) => any) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  has?: (relation: TableRelationName<DB, TTable>) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  doesntHave?: (relation: TableRelationName<DB, TTable>) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  withCount?: (...relations: TableRelationName<DB, TTable>[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  withSum?: (relation: TableRelationName<DB, TTable>, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  withAvg?: (relation: TableRelationName<DB, TTable>, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  withMax?: (relation: TableRelationName<DB, TTable>, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  withMin?: (relation: TableRelationName<DB, TTable>, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  withPivot?: (relation: TableRelationName<DB, TTable>, ...columns: string[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivot?: (relation: TableRelationName<DB, TTable>, column: string, opOrValue: any, value?: any) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotIn?: (relation: TableRelationName<DB, TTable>, column: string, values: any[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotNotIn?: (relation: TableRelationName<DB, TTable>, column: string, values: any[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotNull?: (relation: TableRelationName<DB, TTable>, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotNotNull?: (relation: TableRelationName<DB, TTable>, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
   applyPivotColumns?: () => SelectQueryBuilder<DB, TTable, TSelected, any>
   lockForUpdate: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   sharedLock: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
@@ -148,7 +157,7 @@ export declare interface BaseSelectQueryBuilder<DB extends DatabaseSchema<any>,
   explain: () => Promise<any[]>
   simple: () => any
   toText?: () => string
-  paginate: (perPage: number, page?: number) => Promise<{ data: SelectedRow<DB, TTable, TSelected>[], meta: { perPage: number, page: number, total: number, lastPage: number } }>
+  paginate: (perPage: number, page?: number, opts?: { tx?: { unsafe: (sql: string, params?: any[]) => any } }) => Promise<{ data: SelectedRow<DB, TTable, TSelected>[], meta: { perPage: number, page: number, total: number, lastPage: number } }>
   simplePaginate: (perPage: number, page?: number) => Promise<{ data: SelectedRow<DB, TTable, TSelected>[], meta: { perPage: number, page: number, hasMore: boolean } }>
   toSQL: () => string
   execute: () => Promise<SelectedRow<DB, TTable, TSelected>[]>
@@ -399,6 +408,27 @@ export type SelectedRow<DB extends DatabaseSchema<any>, _TTable extends keyof DB
 declare type JoinColumn<DB extends DatabaseSchema<any>, TTables extends string> = TTables extends any
   ? `${TTables}.${keyof DB[TTables]['columns'] & string}`
   : never;
+/**
+ * # `TableRelationName<DB, TTable>`
+ *
+ * The relation names declared for a table, read from the type-level
+ * `relations` map that `DatabaseSchema` carries. Falls back to `string`
+ * for hand-written schema types that don't declare relation metadata, so
+ * existing untyped schemas keep compiling.
+ */
+export type TableRelationName<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> = DB[TTable] extends { relations?: infer R }
+    ? [keyof NonNullable<R>] extends [never] ? string : keyof NonNullable<R> & string
+    : string;
+/**
+ * # `WithRelationArg<DB, TTable>`
+ *
+ * Argument accepted by `.with()`: a declared relation name, a dotted nested
+ * path rooted at a declared relation (`'posts.comments'`), or a record
+ * mapping relation names to constraint callbacks.
+ */
+export type WithRelationArg<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> = | TableRelationName<DB, TTable>
+  | `${TableRelationName<DB, TTable>}.${string}`
+  | Partial<Record<TableRelationName<DB, TTable>, (qb: any) => any>>;
 // Convert snake_case to PascalCase at the type level (e.g. created_at -> CreatedAt)
 declare type SnakeToPascal<S extends string> = S extends `${infer H}_${infer T}`
   ? `${Capitalize<H>}${SnakeToPascal<T>}`

package/dist/config.d.ts

@@ -13,18 +13,4 @@ export declare function getPlaceholders(count: number, startIndex?: number): str
 export declare function getConfig(): Promise<QueryBuilderConfig>;
 export declare function setConfig(userConfig: Partial<QueryBuilderConfig>): void;
 export declare const defaultConfig: QueryBuilderConfig;
-// For backwards compatibility — synchronous access with default fallback.
-//
-// Why `let` + an explicit `Object.assign(config, defaultConfig)` instead of
-// the obvious `export const config = defaultConfig`: when downstream code
-// (e.g. `bunfig`, our config loader) introduces a top-level `await`, Bun's
-// bundler may wrap this module's initializer in `__esm(async () => {...})`.
-// Static `const x = y` exports inside such a wrapper are reassigned only
-// once the async init runs, so callers that reach `setConfig(...)` before
-// that init (e.g. another module's top-level `setConfig` call mid-graph)
-// see `config` as `undefined` and `Object.assign(undefined, ...)` throws.
-// Initializing as `let config = {...defaultConfig}` outside the wrapper, and
-// having `setConfig` re-hydrate from defaults if it's somehow still empty,
-// keeps the surface synchronous for every consumer regardless of how the
-// module ends up bundled.
-export declare let config: QueryBuilderConfig;
+export declare const config: QueryBuilderConfig;

package/dist/db.d.ts

@@ -1,5 +1,20 @@
 import { Database } from 'bun:sqlite';
 import { SQL } from 'bun';
+import type { PoolConfig } from './types';
+/**
+ * Map the qb-level `pool` config (ms-based, ergonomic) onto the Bun SQL
+ * driver's native option names (second resolution). Only the knobs Bun's
+ * `SQL` actually honors are emitted — `min`/`autoReconnect` are accepted on
+ * `PoolConfig` for forward-compatibility but the driver manages them itself,
+ * so they are intentionally not passed through. See
+ * stacksjs/bun-query-builder#1014.
+ */
+export declare function resolvePoolOptions(pool?: PoolConfig): {
+  max?: number
+  idleTimeout?: number
+  connectionTimeout?: number
+  maxLifetime?: number
+};
 /**
  * Returns a Bun SQL instance configured for the current dialect and database settings.
  * For SQLite, uses bun:sqlite directly for better compiled binary support.
@@ -16,6 +31,37 @@ export declare function resetConnection(): void;
 export declare function withFreshConnection<T>(fn: (sql: SQL) => Promise<T>): Promise<T>;
 // Export a lazy proxy - no connection is made until first use
 export declare const bunSql: SQL;
+/**
+ * The query object returned by `connection.unsafe(...)` / a tagged template.
+ * Both Bun's native `SQL` query and our `createSQLiteSQL` wrapper satisfy this.
+ * See stacksjs/bun-query-builder#1044.
+ */
+export declare interface DriverQuery {
+  execute: () => Promise<any>
+  values?: () => any
+  raw?: () => any
+  toString: () => string
+  cancel?: () => void
+  readonly sql?: string
+  [key: string]: any
+}
+/**
+ * The shared connection surface used across the dispatch path — both the
+ * `bun:sqlite` wrapper and Bun's native `SQL` satisfy it. Typing `_sql` against
+ * this (instead of `any`) is what lets the ~hundreds of `(_sql as any).unsafe`
+ * casts be dropped. See stacksjs/bun-query-builder#1044.
+ */
+export declare interface DriverConnection {
+  (strings: TemplateStringsArray, ...values: any[]): DriverQuery
+  (value: any): any
+  unsafe: (sql: string, values?: any[]) => AwaitableDriverQuery
+  query?: (sql: string, params?: any[]) => any
+  close?: () => Promise<void> | void
+  _prepareStatement?: (sql: string) => any
+  [key: string]: any
+}
+/** An `unsafe(...)` result: a query object that is ALSO directly awaitable. */
+export type AwaitableDriverQuery = DriverQuery & PromiseLike<any>;
 /**
  * SQLite wrapper that provides a SQL-like tagged template literal interface
  * using bun:sqlite's Database class for better compiled binary support.
@@ -27,5 +73,13 @@ declare class SQLiteWrapper {
   close(): void;
   get database(): Database;
 }
+// NOTE: this module no longer installs a process-wide `unhandledRejection`
+// handler. A library has no business doing so: ANY such listener suppresses the
+// runtime's default crash for EVERY unhandled rejection in the consumer's
+// process (the old handler's body matched only DB errors but silently swallowed
+// the rest), masking genuine production bugs. Expected "database does not exist"
+// errors during tests are surfaced/awaited at query time now (#1022); a test
+// harness that needs to tolerate a missing DB should install its own handler.
+// See stacksjs/bun-query-builder#1040.
 // Also export the SQL class for advanced usage
 export { SQL } from 'bun';

package/dist/orm.d.ts

@@ -1,5 +1,6 @@
 import { Database, type SQLQueryBindings } from 'bun:sqlite';
 import type { Faker } from '@stacksjs/ts-faker';
+import type { RelationCardinality } from './type-inference';
 import type { SupportedDialect } from './types';
 export type {
   ModelInstance,
@@ -13,6 +14,18 @@ export type {
   FillableKeys,
   HiddenKeys,
 };
+/**
+ * Extract an affected-row count from a Bun SQL driver result.
+ *
+ * Verified against live Postgres (Bun 1.3): a non-RETURNING `UPDATE`/`DELETE`
+ * returns an empty array carrying `{ count: <affected>, affectedRows: null,
+ * command: 'UPDATE' }`. So `count` must be checked BEFORE the `Array.length`
+ * fallback (which would be 0) — see stacksjs/bun-query-builder#1032. MySQL
+ * surfaces `affectedRows` instead.
+ */
+export declare function extractChanges(res: any): number;
+/** Extract a generated primary key from a Bun SQL driver result. */
+export declare function extractInsertId(res: any): number | bigint | null;
 export declare function configureOrm(options: { database?: string | Database; verbose?: boolean }): void;
 /**
  * Return the underlying `bun:sqlite` Database backing the model layer.
@@ -251,6 +264,18 @@ export type InferRelationNames<TDef> = | InferBelongsToNames<TDef>
   | InferBelongsToManyNames<TDef>
   | InferHasOneThroughNames<TDef>
   | InferHasManyThroughNames<TDef>;
+/**
+ * Cardinality-aware value of a loaded relation as returned by
+ * `ModelInstance.getRelation()`. Relations declared as to-many (hasMany,
+ * belongsToMany, hasManyThrough) yield arrays; to-one relations (hasOne,
+ * belongsTo, hasOneThrough) yield a single instance or null. `undefined`
+ * means the relation was not eager-loaded.
+ */
+declare type LoadedRelationValue<TDef, R extends string> = 'one' extends RelationCardinality<TDef, R>
+    ? ModelInstance<any, any> | null | undefined
+    : 'many' extends RelationCardinality<TDef, R>
+      ? ModelInstance<any, any>[] | undefined
+      : ModelInstance<any, any>[] | ModelInstance<any, any> | null | undefined;
 declare type WhereOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like' | 'not like' | 'in' | 'not in';
 // --- Dialect-aware execution layer -------------------------------------------
 //
@@ -294,7 +319,7 @@ declare class ModelInstance<TDef extends ModelDefinition, TSelected extends Colu
   set<K extends ColumnName<TDef>>(key: K, value: K extends keyof ModelAttributes<TDef> ? ModelAttributes<TDef>[K] : unknown): void;
   only<K extends TSelected>(keys: ReadonlyArray<K>): Partial<ModelAttributes<TDef>>;
   except<K extends TSelected>(keys: ReadonlyArray<K>): Partial<ModelAttributes<TDef>>;
-  getRelation(name: string): ModelInstance<any, any>[] | ModelInstance<any, any> | null | undefined;
+  getRelation<R extends InferRelationNames<TDef> & string>(name: R): LoadedRelationValue<TDef, R>;
   setRelation(name: string, data: ModelInstance<any, any>[] | ModelInstance<any, any> | null): void;
   getLoadedRelations(): Record<string, ModelInstance<any, any>[] | ModelInstance<any, any> | null>;
   get attributes(): Pick<ModelAttributes<TDef>, TSelected & keyof ModelAttributes<TDef>>;
@@ -309,6 +334,8 @@ declare class ModelInstance<TDef extends ModelDefinition, TSelected extends Colu
   update(data: Partial<Pick<InferModelAttributes<TDef>, FillableKeys<TDef>>>): Promise<this>;
   fresh(): Promise<ModelInstance<TDef, TSelected> | null>;
   delete(): Promise<boolean>;
+  restore(): Promise<this>;
+  trashed(): boolean;
   refresh(): Promise<this | null>;
   replicate(): ModelInstance<TDef, TSelected>;
   toArray(): Record<string, unknown>;
@@ -352,6 +379,8 @@ export declare class BelongsToManyRelationBuilder<TRel extends ModelDefinition>
  */
 declare class ModelQueryBuilder<TDef extends ModelDefinition, TSelected extends ColumnName<TDef> = ColumnName<TDef>> {
   constructor(definition: TDef);
+  withTrashed(): ModelQueryBuilder<TDef, TSelected>;
+  onlyTrashed(): ModelQueryBuilder<TDef, TSelected>;
   where<K extends ColumnName<TDef>>(column: K, value: K extends keyof ModelAttributes<TDef> ? ModelAttributes<TDef>[K] : unknown): ModelQueryBuilder<TDef, TSelected>;
   where<K extends ColumnName<TDef>>(column: K, operator: WhereOperator, value: K extends keyof ModelAttributes<TDef> ? ModelAttributes<TDef>[K] : unknown): ModelQueryBuilder<TDef, TSelected>;
   where<K extends ColumnName<TDef>>(column: K, operatorOrValue: WhereOperator | unknown, value?: unknown): ModelQueryBuilder<TDef, TSelected>;

package/dist/relation-utils.d.ts

@@ -0,0 +1,27 @@
+import type { OnForeignKeyAction } from './schema';
+/**
+ * Unwrap a single relation entry to a descriptor, or null if it isn't a valid
+ * relation entry. Accepts:
+ *   - `'Model'`
+ *   - `{ model: 'Model', foreignKey?, onDelete? }`
+ */
+export declare function normalizeRelationEntry(entry: unknown): NormalizedRelation | null;
+/**
+ * Flatten a relation declaration into descriptors. Accepts every supported
+ * shape: string array, object-in-array, record (name->Model) and record
+ * (name->config). Invalid entries are dropped.
+ */
+export declare function normalizeRelationList(rel: unknown): NormalizedRelation[];
+/**
+ * A relation entry reduced to the fields the schema/migration layers need.
+ *
+ * Single source of truth for unwrapping the supported relation-declaration
+ * shapes. Previously `meta.ts` (toRecord) and `migrations.ts`
+ * (normalizeBelongsTo) each re-implemented this — the exact shape that caused
+ * stacksjs/bun-query-builder#1023, and the fix had to be applied twice. See #1042.
+ */
+export declare interface NormalizedRelation {
+  model: string
+  foreignKey?: string
+  onDelete?: OnForeignKeyAction
+}

package/dist/schema.d.ts

@@ -258,6 +258,61 @@ export type InferTableName<M extends ModelDefinition> = M extends {
   : M extends { name: infer N extends string }
     ? `${Lowercase<N>}s`
     : string;
+/**
+ * Resolve a models-record entry to the raw definition. `defineModel()` (and
+ * `createModel`/`createBrowserModel`) wrap definitions in an object exposing
+ * `getDefinition()` / `definition`; `buildDatabaseSchema` unwraps these at
+ * runtime, so the type level must unwrap them too or the schema degrades to
+ * an untyped index signature.
+ */
+declare type UnwrapModelDefinition<M> = M extends { getDefinition: () => infer D } ? D :
+    M extends { definition: infer D } ? D :
+      M;
+/**
+ * Unwrap a relation entry to the related model's name. Entries may be a plain
+ * model-name string, a `{ model: 'X' }` config (belongsToMany Option A/B), or
+ * a `{ through, target }` through-relation descriptor.
+ */
+declare type RelationEntryModelName<E> = E extends string ? E :
+    E extends { model: infer M extends string } ? M :
+      E extends { target: infer T extends string } ? T :
+        never;
+/**
+ * Normalize one relation declaration (array or record form) into a
+ * `relationName -> relatedModelName` record, mirroring `buildSchemaMeta`:
+ * array entries use the (unwrapped) model name as the relation name; record
+ * entries use the key.
+ */
+declare type RelationRecordOf<V> = [V] extends [never]
+    ? {} // absent relation kind — must yield {} (not never) so intersections survive
+    : V extends readonly (infer E)[]
+      ? { [K in RelationEntryModelName<E> & string]: K }
+      : V extends Readonly<Record<string, unknown>>
+        ? { [K in keyof V & string]: RelationEntryModelName<V[K]> }
+        : {}
+/** All relations of a model as a `relationName -> relatedModelName` record. */
+declare type ModelRelationsRecord<M> = RelationRecordOf<M extends { hasOne: infer V } ? V : never>
+  & RelationRecordOf<M extends { hasMany: infer V } ? V : never>
+  & RelationRecordOf<M extends { belongsTo: infer V } ? V : never>
+  & RelationRecordOf<M extends { belongsToMany: infer V } ? V : never>
+  & RelationRecordOf<M extends { hasOneThrough: infer V } ? V : never>
+  & RelationRecordOf<M extends { hasManyThrough: infer V } ? V : never>
+  & RelationRecordOf<M extends { morphOne: infer V } ? V : never>
+  & RelationRecordOf<M extends { morphMany: infer V } ? V : never>
+  & RelationRecordOf<M extends { morphToMany: infer V } ? V : never>
+  & RelationRecordOf<M extends { morphedByMany: infer V } ? V : never>;
+/** Resolve a related model name to its table name within the models record. */
+declare type RelatedTableName<MRecord extends ModelRecord, ModelName> = ModelName extends keyof MRecord ? InferTableName<UnwrapModelDefinition<MRecord[ModelName]>> : string;
+/**
+ * # `InferTableRelations<M, MRecord>`
+ *
+ * `relationName -> relatedTableName` record for one model, resolved against
+ * the full models record. Powers the type-level narrowing of `.with()`,
+ * `.whereHas()`, `.withCount()`, etc. on the query builder.
+ */
+export type InferTableRelations<M, MRecord extends ModelRecord> = {
+  [K in keyof ModelRelationsRecord<UnwrapModelDefinition<M>> & string]: RelatedTableName<MRecord, ModelRelationsRecord<UnwrapModelDefinition<M>>[K]>
+}
 /**
  * # `DatabaseSchema<Models>`
  *
@@ -265,6 +320,11 @@ export type InferTableName<M extends ModelDefinition> = M extends {
  * table columns and primary key. This is the primary input for the query
  * builder's type-safety.
  *
+ * The `relations` field is type-level only (phantom): `buildDatabaseSchema`
+ * never materializes it at runtime. It maps relation names to related table
+ * names so builder methods like `.with()` can narrow their accepted relation
+ * names per table.
+ *
  * @example
  * ```ts
  * const models = defineModels({ User, Post })
@@ -272,8 +332,10 @@ export type InferTableName<M extends ModelDefinition> = M extends {
  * ```
  */
 export type DatabaseSchema<MRecord extends ModelRecord> = {
-  [MName in keyof MRecord & string as InferTableName<MRecord[MName]>]: {
-    columns: InferAttributes<MRecord[MName]>
-    primaryKey: InferPrimaryKey<MRecord[MName]>
+  [MName in keyof MRecord & string as InferTableName<UnwrapModelDefinition<MRecord[MName]>>]: {
+    columns: InferAttributes<UnwrapModelDefinition<MRecord[MName]>>
+    primaryKey: InferPrimaryKey<UnwrapModelDefinition<MRecord[MName]>>
+    /** Phantom, type-level only: relation name -> related table name. */
+    relations?: InferTableRelations<MRecord[MName], MRecord>
   };
 }