bun-query-builder 0.1.26 → 0.1.27

package/dist/client.d.ts

@@ -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>
@@ -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/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,
@@ -263,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 -------------------------------------------
 //
@@ -306,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>>;

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>
   };
 }