@apisr/drizzle-model 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change log
 
+## 2.0.2 | 01-0-2026
+- add `esc.*()` operations
+- update README.md with new `esc.*()`
+
 ## 2.0.1 | 01-03-2026
 - mark `pg` as peerDep
 - add `CHANGELOG.md`

package/README.md

@@ -381,7 +381,45 @@ Note: when method names conflict during `extend`, existing runtime methods take
 
 ## Type safety notes
 
-- Prefer `esc(...)` for explicit where value/operator expressions.
+### Using `esc()` for explicit where expressions
+
+The `esc()` function provides three ways to specify comparison operators:
+
+**1. Implicit equality (simplest):**
+```ts
+where({ name: esc("Alex") })
+```
+
+**2. Explicit operator (Drizzle-style):**
+```ts
+import { gte } from "drizzle-orm";
+where({ age: esc(gte, 18) })
+```
+
+**3. Chainable methods (recommended):**
+```ts
+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
+
+### Other type safety features
+
 - `.select()` and `.exclude()` control SQL SELECT columns and refine result types.
 - `.omit()` removes fields from the result programmatically after the query.
 - `.safe()` wraps result types into `{ data, error }`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apisr/drizzle-model",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "private": false,
   "scripts": {
     "lint": "eslint . --max-warnings 0",

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/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);
+		}
+	});
+});

package/tests/snippets/x-2.ts

@@ -0,0 +1,28 @@
+import { esc, modelBuilder } from "src/model";
+import { db } from "../db";
+import { relations } from "../relations";
+import * as schema from "../schema";
+
+const model = modelBuilder({
+	schema,
+	db,
+	relations,
+	dialect: "PostgreSQL",
+});
+
+// create model
+const userModel = model("user", {});
+
+await userModel
+	.where({
+		name: {
+			like: "A%",
+		},
+	})
+	.findFirst();
+
+await userModel
+	.where({
+		name: esc.like("A%"),
+	})
+	.findFirst();