bun-query-builder 0.1.26 → 0.1.28

package/dist/browser.d.ts

@@ -201,9 +201,12 @@ declare type BrowserAttributeKeys<TDef extends BrowserModelDefinition> = keyof T
 declare type InferBrowserAttributeType<TAttr> = TAttr extends { type: infer T } ? InferType<T> :
   TAttr extends { factory: (faker: unknown) => infer R } ? R :
   unknown;
-// Build the full attributes type from definition
+// Build the full attributes type from definition. Columns declared
+// `nullable: true` admit null — mirrors InferAttributes in type-inference.ts.
 declare type InferBrowserModelAttributes<TDef extends BrowserModelDefinition> = {
-  [K in BrowserAttributeKeys<TDef>]: InferBrowserAttributeType<TDef['attributes'][K]>
+  [K in BrowserAttributeKeys<TDef>]: TDef['attributes'][K] extends { nullable: true }
+    ? InferBrowserAttributeType<TDef['attributes'][K]> | null
+    : InferBrowserAttributeType<TDef['attributes'][K]>
 }
 // System fields added by traits
 declare type BrowserSystemFields<TDef extends BrowserModelDefinition> = { id: number } &

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,34 @@ 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
+ * (inferred `R` is `unknown` when the property is absent), so existing
+ * untyped schemas keep compiling. A table that declares ZERO relations
+ * yields `never` — every relation name is rejected.
+ */
+export type TableRelationName<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> = DB[TTable] extends { relations?: infer R }
+    ? unknown extends R ? 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. A table with zero declared
+ * relations accepts nothing (the bare `Partial<Record<never, ...>>` would be
+ * `{}`, which strings are assignable to — hence the explicit never guard).
+ */
+export type WithRelationArg<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> = [TableRelationName<DB, TTable>] extends [never]
+    ? never
+    :
+      | 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,
@@ -195,12 +196,17 @@ declare type AttributeKeys<TDef extends ModelDefinition> = keyof TDef['attribute
 declare type InferAttributeType<TAttr> = TAttr extends { type: infer T } ? InferType<T> :
   TAttr extends { factory: (faker: Faker) => infer R } ? R :
   unknown;
-// Build the full attributes type from definition
+// Build the full attributes type from definition. Columns declared
+// `nullable: true` admit null — mirrors InferAttributes in type-inference.ts.
 declare type InferModelAttributes<TDef extends ModelDefinition> = {
-  [K in AttributeKeys<TDef>]: InferAttributeType<TDef['attributes'][K]>
+  [K in AttributeKeys<TDef>]: TDef['attributes'][K] extends { nullable: true }
+    ? InferAttributeType<TDef['attributes'][K]> | null
+    : InferAttributeType<TDef['attributes'][K]>
 }
-// System fields added by traits
-declare type SystemFields<TDef extends ModelDefinition> = { id: number } &
+// System fields added by traits. The primary-key column honors the model's
+// declared `primaryKey` (default 'id') — a custom-pk model exposes THAT
+// column, not a phantom 'id'. Mirrors InferAttributes in type-inference.ts.
+declare type SystemFields<TDef extends ModelDefinition> = { [K in TDef extends { primaryKey: infer PK extends string } ? PK : 'id']: number } &
   (TDef['traits'] extends { useUuid: true } ? { uuid: string } : {}) &
   (TDef['traits'] extends { useTimestamps: true } ? { created_at: string; updated_at: string | null } : {}) &
   (TDef['traits'] extends { timestampable: true | object } ? { created_at: string; updated_at: string | null } : {}) &
@@ -212,7 +218,7 @@ declare type SystemFields<TDef extends ModelDefinition> = { id: number } &
 declare type ModelAttributes<TDef extends ModelDefinition> = InferModelAttributes<TDef> & SystemFields<TDef>;
 // All valid column names
 declare type ColumnName<TDef extends ModelDefinition> = | AttributeKeys<TDef>
-  | 'id'
+  | (TDef extends { primaryKey: infer PK extends string } ? PK : 'id')
   | (TDef['traits'] extends { useUuid: true } ? 'uuid' : never)
   | (TDef['traits'] extends { useTimestamps: true } ? 'created_at' | 'updated_at' : never)
   | (TDef['traits'] extends { timestampable: true | object } ? 'created_at' | 'updated_at' : never)
@@ -232,37 +238,44 @@ declare type FillableKeys<TDef extends ModelDefinition> = {
 declare type NumericColumns<TDef extends ModelDefinition> = {
   [K in AttributeKeys<TDef>]: TDef['attributes'][K] extends { type: 'number' } ? K : never
 }[AttributeKeys<TDef>];
-// Infer relation names from model definition (supports both array and object syntax)
-declare type InferBelongsToNames<TDef> = (TDef extends { belongsTo: readonly (infer R)[] }
-    ? R extends string ? Lowercase<R> : never : never)
-  | (TDef extends { belongsTo: Readonly<Record<infer K, unknown>> }
-    ? K extends string ? K : never : never);
-declare type InferHasManyNames<TDef> = (TDef extends { hasMany: readonly (infer R)[] }
-    ? R extends string ? Lowercase<R> : never : never)
-  | (TDef extends { hasMany: Readonly<Record<infer K, unknown>> }
-    ? K extends string ? K : never : never);
-declare type InferHasOneNames<TDef> = (TDef extends { hasOne: readonly (infer R)[] }
-    ? R extends string ? Lowercase<R> : never : never)
-  | (TDef extends { hasOne: Readonly<Record<infer K, unknown>> }
-    ? K extends string ? K : never : never);
-declare type InferBelongsToManyNames<TDef> = (TDef extends { belongsToMany: readonly (infer R)[] }
-    ? R extends string ? Lowercase<R> : R extends { model: infer M extends string } ? Lowercase<M> : never : never)
-  | (TDef extends { belongsToMany: Readonly<Record<infer K, unknown>> }
-    ? K extends string ? K : never : never);
-declare type InferHasOneThroughNames<TDef> = (TDef extends { hasOneThrough: readonly (infer R)[] }
-    ? R extends string ? Lowercase<R> : R extends { model: infer M extends string } ? Lowercase<M> : never : never)
-  | (TDef extends { hasOneThrough: Readonly<Record<infer K, unknown>> }
-    ? K extends string ? K : never : never);
-declare type InferHasManyThroughNames<TDef> = (TDef extends { hasManyThrough: readonly (infer R)[] }
-    ? R extends string ? Lowercase<R> : R extends { model: infer M extends string } ? Lowercase<M> : never : never)
-  | (TDef extends { hasManyThrough: Readonly<Record<infer K, unknown>> }
-    ? K extends string ? K : never : never);
+/**
+ * Relation names of one relation declaration. Array form lowercases the
+ * (unwrapped) model name; record form uses the keys. The array case MUST be
+ * checked first: a tuple also structurally matches `Readonly<Record<...>>`
+ * and would otherwise leak its own keys ('length', indices, ...) into the
+ * relation-name union.
+ */
+declare type RelationKeyOf<V> = V extends readonly (infer E)[]
+    ? E extends string ? Lowercase<E>
+      : E extends { model: infer M extends string } ? Lowercase<M>
+        : never
+    : V extends Readonly<Record<infer K, unknown>>
+      ? K & string
+      : never;
+declare type InferBelongsToNames<TDef> = TDef extends { belongsTo: infer V } ? RelationKeyOf<V> : never;
+declare type InferHasManyNames<TDef> = TDef extends { hasMany: infer V } ? RelationKeyOf<V> : never;
+declare type InferHasOneNames<TDef> = TDef extends { hasOne: infer V } ? RelationKeyOf<V> : never;
+declare type InferBelongsToManyNames<TDef> = TDef extends { belongsToMany: infer V } ? RelationKeyOf<V> : never;
+declare type InferHasOneThroughNames<TDef> = TDef extends { hasOneThrough: infer V } ? RelationKeyOf<V> : never;
+declare type InferHasManyThroughNames<TDef> = TDef extends { hasManyThrough: infer V } ? RelationKeyOf<V> : never;
 export type InferRelationNames<TDef> = | InferBelongsToNames<TDef>
   | InferHasManyNames<TDef>
   | InferHasOneNames<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>
   };
 }