@apisr/drizzle-model 2.0.0 → 2.0.2

package/src/core/result.ts

@@ -22,13 +22,13 @@ export type SafeResult<T> =
 
 /** Accumulated state for a query operation (findMany / findFirst). */
 export interface QueryState {
-	/** Column blacklist for `.exclude()`. */
+	/** SQL SELECT blacklist — columns to omit from the query. */
 	exclude?: AnyRecord;
 	/** When `true`, formatting is skipped. */
 	raw?: boolean;
 	/** When `true`, result is wrapped in `{ data, error }`. */
 	safe?: boolean;
-	/** Column whitelist for `.select()`. */
+	/** SQL SELECT whitelist — columns to include in the query. */
 	select?: AnyRecord;
 	/** Compiled where clause. */
 	where?: unknown;
@@ -154,9 +154,12 @@ export class QueryResult<T> extends ThenableResult<T> {
 	}
 
 	/**
-	 * Whitelists specific fields in the result.
+	 * Controls which columns appear in the SQL SELECT clause (whitelist).
 	 *
-	 * @param value - A map of `{ fieldName: true }`.
+	 * This affects the query itself, not just the result.
+	 * Equivalent to `db.select({ col: table.col }).from(table)`.
+	 *
+	 * @param value - A map of `{ columnName: true }`.
 	 * @returns A new `QueryResult` with the `.select()` state applied.
 	 */
 	select(value: AnyRecord): QueryResult<T> {
@@ -164,9 +167,12 @@ export class QueryResult<T> extends ThenableResult<T> {
 	}
 
 	/**
-	 * Blacklists specific fields from the result.
+	 * Controls which columns are excluded from the SQL SELECT clause (blacklist).
+	 *
+	 * This affects the query itself, not just the result.
+	 * All columns except the listed ones will be fetched.
 	 *
-	 * @param value - A map of `{ fieldName: true }`.
+	 * @param value - A map of `{ columnName: true }`.
 	 * @returns A new `QueryResult` with the `.exclude()` state applied.
 	 */
 	exclude(value: AnyRecord): QueryResult<T> {

package/src/core/runtime.ts

@@ -105,6 +105,16 @@ export class ModelRuntime {
 		return this.config.options.format;
 	}
 
+	/** The current where clause, exposed for relation descriptors. */
+	get $where(): unknown {
+		return this.currentWhere;
+	}
+
+	/** The table name this model is bound to, exposed for relation descriptors. */
+	get $tableName(): string {
+		return this.config.tableName;
+	}
+
 	// ---------------------------------------------------------------------------
 	// Public: filtering
 	// ---------------------------------------------------------------------------
@@ -127,16 +137,26 @@ export class ModelRuntime {
 	// ---------------------------------------------------------------------------
 
 	/**
-	 * Returns the `.with()` value as-is.
+	 * Returns a relation descriptor carrying the model's where clause
+	 * and the nested relation includes.
 	 *
-	 * This is a pass-through used at the type level to allow
-	 * `model.include({ posts: true })` syntax.
+	 * Used in `.with()` to filter a relation and load nested relations:
+	 * ```ts
+	 * userModel.findMany().with({
+	 *   posts: postModel.where({ ... }).include({ comments: true }),
+	 * });
+	 * ```
 	 *
-	 * @param value - The relation include descriptor.
-	 * @returns The same value, unchanged.
+	 * @param value - The nested relation include descriptor.
+	 * @returns A model relation descriptor consumed by the join executor.
 	 */
 	include(value: unknown): unknown {
-		return value;
+		return {
+			__modelRelation: true,
+			whereValue: this.currentWhere,
+			tableName: this.config.tableName,
+			with: value,
+		};
 	}
 
 	/**
@@ -182,7 +202,8 @@ export class ModelRuntime {
 	/**
 	 * Returns a thenable that resolves to an array of matching rows.
 	 *
-	 * Supports chaining: `.select()`, `.exclude()`, `.with()`, `.raw()`.
+	 * Supports chaining: `.select()`, `.exclude()` (SQL SELECT),
+	 * `.with()` (relations), `.raw()`, `.safe()`.
 	 *
 	 * @returns A {@link QueryResult} that can be awaited or further chained.
 	 */
@@ -202,6 +223,8 @@ export class ModelRuntime {
 					baseTable: table,
 					whereSql,
 					withValue: qState.with as AnyRecord,
+					select: qState.select,
+					exclude: qState.exclude,
 					limitOne: false,
 				});
 			} else {
@@ -234,7 +257,8 @@ export class ModelRuntime {
 	/**
 	 * Returns a thenable that resolves to the first matching row (or `undefined`).
 	 *
-	 * Supports chaining: `.select()`, `.exclude()`, `.with()`, `.raw()`.
+	 * Supports chaining: `.select()`, `.exclude()` (SQL SELECT),
+	 * `.with()` (relations), `.raw()`, `.safe()`.
 	 *
 	 * @returns A {@link QueryResult} that can be awaited or further chained.
 	 */
@@ -254,6 +278,8 @@ export class ModelRuntime {
 					baseTable: table,
 					whereSql,
 					withValue: qState.with as AnyRecord,
+					select: qState.select,
+					exclude: qState.exclude,
 					limitOne: true,
 				});
 			} else {
@@ -529,7 +555,11 @@ export class ModelRuntime {
 	}
 
 	/**
-	 * Applies select, exclude, and format transforms to the query result.
+	 * Applies post-query transforms to the query result.
+	 *
+	 * Note: `.select()` and `.exclude()` are handled at the SQL level
+	 * (via {@link ProjectionBuilder}) and are NOT applied here.
+	 * Only format transforms are applied post-query.
 	 */
 	private applyPostQueryTransforms(
 		result: unknown,
@@ -537,12 +567,6 @@ export class ModelRuntime {
 	): unknown {
 		let out = result;
 
-		if (qState.select) {
-			out = this.transformer.applySelect(out, qState.select);
-		}
-		if (qState.exclude) {
-			out = this.transformer.applyExclude(out, qState.exclude);
-		}
 		if (!qState.raw) {
 			out = this.transformer.applyFormat(
 				out,

package/src/model/query/operations.ts

@@ -17,59 +17,59 @@ export type EscapedValue<T> =
 
 type OpValue<T> = T | SQL | EscapedValue<T>;
 
-export type ColumnOpsBase<T> = {
+export interface ColumnOpsBase<T> {
 	eq?: OpValue<T>;
 	equal?: OpValue<T>;
-	not?: OpValue<T>;
 	in?: OpValue<T>[];
-	nin?: OpValue<T>[];
 	isNull?: boolean;
-};
+	nin?: OpValue<T>[];
+	not?: OpValue<T>;
+}
 
-export type NumberOps = {
+export interface NumberOps {
+	between?: [OpValue<number>, OpValue<number>];
 	gt?: OpValue<number>;
 	gte?: OpValue<number>;
 	lt?: OpValue<number>;
 	lte?: OpValue<number>;
-	between?: [OpValue<number>, OpValue<number>];
 	notBetween?: [OpValue<number>, OpValue<number>];
-};
+}
 
-export type StringOps = {
-	like?: OpValue<string>;
-	ilike?: OpValue<string>;
-	startsWith?: OpValue<string>;
-	endsWith?: OpValue<string>;
+export interface StringOps {
 	contains?: OpValue<string>;
-	regex?: OpValue<string>;
-	notRegex?: OpValue<string>;
+	endsWith?: OpValue<string>;
+	ilike?: OpValue<string>;
 	length?: NumberOps;
-};
+	like?: OpValue<string>;
+	notRegex?: OpValue<string>;
+	regex?: OpValue<string>;
+	startsWith?: OpValue<string>;
+}
 
-export type BoolOps = {
-	isTrue?: boolean;
+export interface BoolOps {
 	isFalse?: boolean;
-};
+	isTrue?: boolean;
+}
 
-export type DateOps = {
-	before?: OpValue<Date | string>;
+export interface DateOps {
 	after?: OpValue<Date | string>;
-	on?: OpValue<Date | string>;
-	notOn?: OpValue<Date | string>;
+	before?: OpValue<Date | string>;
 	between?: [OpValue<Date | string>, OpValue<Date | string>];
-};
+	notOn?: OpValue<Date | string>;
+	on?: OpValue<Date | string>;
+}
 
-export type JsonOps<T> = {
+export interface JsonOps<T> {
 	has?: T;
-	hasAny?: T[];
 	hasAll?: T[];
+	hasAny?: T[];
 	len?: NumberOps;
-};
+}
 
-export type LogicalOps<TColumn extends Column> = {
-	or?: ColumnValue<TColumn>[];
+export interface LogicalOps<TColumn extends Column> {
 	and?: ColumnValue<TColumn>[];
-};
+	or?: ColumnValue<TColumn>[];
+}
 
 export type TypeOps<T> = T extends number
 	? NumberOps
@@ -103,29 +103,40 @@ export type ColumnValue<
  * - Drizzle ORM operators should be used directly
  * - complex types (e.g. Date, objects, custom classes) need safe handling
  *
- * There are two supported forms:
+ * There are three supported forms:
  *
  * 1) Implicit equality (default behavior):
  * ```ts
  * where({ name: esc("Alex") })
  * ```
- * Compiles to:
- * ```ts
- * {
- *  eq: "Alex"
- * }
- * // In drizzle: eq(column, "Alex")
- * ```
  *
  * 2) Explicit operator (Drizzle-style):
  * ```ts
  * where({ age: esc(gte, 18) })
  * ```
- * Compiles to:
+ *
+ * 3) Chainable operator methods (recommended):
  * ```ts
- * gte(column, 18)
+ * where({ name: esc.like("%Alex%") })
+ * where({ age: esc.gte(18) })
+ * where({ status: esc.in(["active", "pending"]) })
+ * where({ price: esc.between(10, 100) })
  * ```
  *
+ * Available chainable methods:
+ * - `esc.eq(value)` — equality
+ * - `esc.not(value)` — inequality
+ * - `esc.gt(value)` — greater than
+ * - `esc.gte(value)` — greater than or equal
+ * - `esc.lt(value)` — less than
+ * - `esc.lte(value)` — less than or equal
+ * - `esc.like(pattern)` — SQL LIKE pattern matching
+ * - `esc.ilike(pattern)` — case-insensitive LIKE
+ * - `esc.in(values)` — value in array
+ * - `esc.nin(values)` — value not in array
+ * - `esc.between(min, max)` — value between range
+ * - `esc.notBetween(min, max)` — value not between range
+ *
  * The column is injected later during query compilation.
  * `esc` does NOT execute the operator immediately.
  *
@@ -169,3 +180,30 @@ export function esc<T>(arg1: any, arg2?: any): EscapedValue<T> {
 		equal: arg1,
 	};
 }
+
+// Chainable operator methods - return DSL objects
+esc.eq = <T>(value: T) => ({ eq: value });
+
+esc.not = <T>(value: T) => ({ not: value });
+
+esc.gt = <T>(value: T) => ({ gt: value });
+
+esc.gte = <T>(value: T) => ({ gte: value });
+
+esc.lt = <T>(value: T) => ({ lt: value });
+
+esc.lte = <T>(value: T) => ({ lte: value });
+
+esc.like = (pattern: string) => ({ like: pattern });
+
+esc.ilike = (pattern: string) => ({ ilike: pattern });
+
+esc.in = <T>(values: T[]) => ({ in: values });
+
+esc.nin = <T>(values: T[]) => ({ nin: values });
+
+esc.between = <T>(min: T, max: T) => ({ between: [min, max] as [T, T] });
+
+esc.notBetween = <T>(min: T, max: T) => ({
+	notBetween: [min, max] as [T, T],
+});

package/src/model/result.ts

@@ -2,6 +2,7 @@ import type {
 	TableRelationalConfig,
 	TablesRelationalConfig,
 } from "drizzle-orm/relations";
+import type { SimplifyDeep } from "type-fest";
 import type {
 	ApplyArrayIfArray,
 	InferArrayItem,
@@ -49,7 +50,9 @@ export interface ModelQueryResult<
 			TWithSafe,
 			ApplyArrayIfArray<
 				TResult,
-				Simplify<ModelFormatResult<InferArrayItem<TResult>, TFormat, TTable>>
+				SimplifyDeep<
+					ModelFormatResult<InferArrayItem<TResult>, TFormat, TTable>
+				>
 			>
 		>
 	> {
@@ -148,7 +151,7 @@ export interface ModelInMutableResult<
 	// >(
 	// 	value?: TConfig["dialect"] extends ReturningIdDialects ? never : TValue
 	// ): Omit<ModelMutateResult<TResult, TConfig, TResultType>, "with">;
-	$return: MethodReturnResult<TConfig>;
+	// $return: MethodReturnResult<TConfig>;
 
 	omit<TValue extends MethodExcludeValue<TConfig["tableOutput"]>>(
 		value: TValue

package/tests/base/esc-chainable.test.ts

@@ -0,0 +1,159 @@
+import { beforeAll, describe, expect, test } from "bun:test";
+import { model } from "tests/base";
+import { esc } from "@/model";
+
+const userModel = model("user", {});
+
+function uid(): string {
+	return `${Date.now()}-${Math.random()}`;
+}
+
+describe("esc chainable methods", () => {
+	let testUserId: number;
+
+	beforeAll(async () => {
+		const user = await userModel
+			.insert({
+				name: "Esc Test User",
+				email: `${uid()}@esc.com`,
+				age: 25,
+			})
+			.returnFirst();
+		testUserId = user.id;
+
+		await userModel.insert({
+			name: "Alice",
+			email: `${uid()}@esc.com`,
+			age: 30,
+		});
+
+		await userModel.insert({
+			name: "Bob",
+			email: `${uid()}@esc.com`,
+			age: 20,
+		});
+	});
+
+	test("esc.eq() - equality", async () => {
+		const users = await userModel.where({ id: esc.eq(testUserId) }).findMany();
+
+		expect(users).toBeArray();
+		expect(users.length).toBe(1);
+		expect(users[0]?.id).toBe(testUserId);
+	});
+
+	test("esc.not() - inequality", async () => {
+		const users = await userModel
+			.where({ id: esc.not(testUserId) })
+			.findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(user.id).not.toBe(testUserId);
+		}
+	});
+
+	test("esc.gt() - greater than", async () => {
+		const users = await userModel.where({ age: esc.gt(25) }).findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(user.age).toBeGreaterThan(25);
+		}
+	});
+
+	test("esc.gte() - greater than or equal", async () => {
+		const users = await userModel.where({ age: esc.gte(25) }).findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(user.age).toBeGreaterThanOrEqual(25);
+		}
+	});
+
+	test("esc.lt() - less than", async () => {
+		const users = await userModel.where({ age: esc.lt(25) }).findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(user.age).toBeLessThan(25);
+		}
+	});
+
+	test("esc.lte() - less than or equal", async () => {
+		const users = await userModel.where({ age: esc.lte(25) }).findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(user.age).toBeLessThanOrEqual(25);
+		}
+	});
+
+	test("esc.like() - pattern matching", async () => {
+		const users = await userModel.where({ name: esc.like("Esc%") }).findMany();
+
+		expect(users).toBeArray();
+		expect(users.length).toBeGreaterThan(0);
+		for (const user of users) {
+			expect(user.name.startsWith("Esc")).toBe(true);
+		}
+	});
+
+	test("esc.ilike() - case-insensitive pattern matching", async () => {
+		const users = await userModel
+			.where({ name: esc.ilike("%alice%") })
+			.findMany();
+
+		expect(users).toBeArray();
+		expect(users.length).toBeGreaterThan(0);
+		for (const user of users) {
+			expect(user.name.toLowerCase()).toContain("alice");
+		}
+	});
+
+	test("esc.in() - value in array", async () => {
+		const users = await userModel
+			.where({ name: esc.in(["Alice", "Bob"]) })
+			.findMany();
+
+		expect(users).toBeArray();
+		expect(users.length).toBeGreaterThan(0);
+		for (const user of users) {
+			expect(["Alice", "Bob"]).toContain(user.name);
+		}
+	});
+
+	test("esc.nin() - value not in array", async () => {
+		const users = await userModel
+			.where({ name: esc.nin(["Alice", "Bob"]) })
+			.findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(["Alice", "Bob"]).not.toContain(user.name);
+		}
+	});
+
+	test("esc.between() - value in range", async () => {
+		const users = await userModel
+			.where({ age: esc.between(20, 30) })
+			.findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(user.age).toBeGreaterThanOrEqual(20);
+			expect(user.age).toBeLessThanOrEqual(30);
+		}
+	});
+
+	test("esc.notBetween() - value outside range", async () => {
+		const users = await userModel
+			.where({ age: esc.notBetween(21, 29) })
+			.findMany();
+
+		expect(users).toBeArray();
+		for (const user of users) {
+			expect(user.age < 21 || user.age > 29).toBe(true);
+		}
+	});
+});