@apisr/drizzle-model 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Change log
+
+## 2.0.1 | 01-03-2026
+- mark `pg` as peerDep
+- add `CHANGELOG.md`
+- add `relations.test.ts` to test relations
+- add `SimplifyDeep<>` from `type-fest` in queries, for better DX of using relations
+- fix relations `include()` function
+
+## 2.0.0 | 28-02-2026
+- add `REAMDE.md`
+- add `count()` function
+- add `Simplify<>` to all queries
+- add `returnFirst()` and make `return()` to return array of rows
+- add `omit()` as transformator after `return()/returnFirst()`
+- remake entire core, better JSDoc, OOP over functional, and much more...
+- remake all tests
+- add `safe()` function
+```ts
+const { data: user, error } = userModel.findFirst().safe();
+```
+- and in overall just make better DX

package/README.md

@@ -0,0 +1,433 @@
+# @apisr/drizzle-model
+
+> **⚠️ This package is on high development stage! May have bugs**  
+
+> **⚠️ Requires `drizzle-orm@beta`**  
+> This package is built for Drizzle ORM beta versions (`^1.0.0-beta.2-86f844e`).  
+
+Type-safe, chainable model runtime for **Drizzle ORM**.
+
+Build reusable models for tables and relations with a progressive flow:
+
+1. **Intent Stage** — declare what you want (`where`, `insert`, `update`, ...)
+2. **Execution Stage** — choose execution (`findMany`, `findFirst`, `return`, `returnFirst`)
+3. **Refinement Stage** — shape the SQL query (`select`, `exclude`, `with`)
+4. **Programmatic Polishing** — post-process the result (`omit`, `raw`, `safe`)
+
+---
+
+## Learning Path (easy → advanced)
+
+1. [Install and create your first model](#install-and-first-model)
+2. [Basic reads](#basic-reads)
+3. [Basic writes](#basic-writes)
+4. [Result refinement](#result-refinement)
+5. [Error-safe execution](#error-safe-execution)
+6. [Advanced: model options and extension](#advanced-model-options-and-extension)
+7. [Full API reference](#full-api-reference)
+
+---
+
+## Install and first model
+
+```bash
+bun add @apisr/drizzle-model drizzle-orm@beta
+```
+
+```ts
+import { modelBuilder, esc } from "@apisr/drizzle-model";
+import { drizzle } from "drizzle-orm/node-postgres";
+import * as schema from "./schema";
+import { relations } from "./relations";
+
+const db = drizzle(process.env.DATABASE_URL!, { schema, relations });
+
+const model = modelBuilder({
+  db,
+  schema,
+  // requires DrizzleORM relations v2. See: https://orm.drizzle.team/docs/relations-v1-v2
+  relations,
+  dialect: "PostgreSQL",
+});
+
+const userModel = model("user", {});
+```
+
+> `drizzle-orm` is a peer dependency.
+
+---
+
+## Basic reads
+
+### Find one
+
+```ts
+const user = await userModel.findFirst();
+```
+
+### Find many with filter
+
+```ts
+const users = await userModel
+  .where({ name: esc("Alex") })
+  .findMany();
+```
+
+### Count
+
+```ts
+const total = await userModel.count();
+const verified = await userModel.where({ isVerified: esc(true) }).count();
+```
+
+---
+
+## Basic writes
+
+### Insert
+
+```ts
+await userModel.insert({
+  name: "New User",
+  email: "new@example.com",
+  age: 18,
+});
+```
+
+### Update
+
+```ts
+const updated = await userModel
+  .where({ id: esc(1) })
+  .update({ name: "Updated" })
+  .returnFirst();
+```
+
+### Delete
+
+```ts
+await userModel.where({ id: esc(2) }).delete();
+```
+
+### Upsert
+
+```ts
+const row = await userModel
+  .upsert({
+    insert: { name: "Alex", email: "alex@ex.com", age: 20 },
+    update: { name: "Alex Updated" },
+    target: schema.user.email,
+  })
+  .returnFirst();
+```
+
+---
+
+## Result refinement
+
+### Query-side refinement (`findMany` / `findFirst` result)
+
+#### Loading relations with `.with()`
+
+```ts
+// Load related posts for each user
+const users = await userModel
+  .findMany()
+  .with({ posts: true });
+
+// Nested relations
+const users = await userModel
+  .findMany()
+  .with({
+    posts: {
+      comments: true,
+    },
+  });
+
+// Multiple relations
+const users = await userModel
+  .findMany()
+  .with({
+    posts: true,
+    invitee: true,
+  });
+
+// Query `where` relations
+const users = await userModel
+  .findMany()
+  .with({
+    posts: postModel.where({
+      title: {
+        like: "New%"
+      }
+    }),
+  });
+```
+
+#### Using `.include()` for type-safe relation values
+
+`.include()` is a helper that returns the relation value as-is, used for type-level relation selection:
+
+```ts
+// Pass to .with()
+const users = await userModel.findMany().with({
+  posts: postModel.where({
+    title: {
+      like: "New%"
+    }
+  }).include({
+    comments: true
+  })
+});
+```
+
+#### SQL column selection with `.select()` and `.exclude()`
+
+`.select()` and `.exclude()` control which columns appear in the SQL `SELECT` clause — they affect the query itself, not just the result.
+
+```ts
+// Only fetch id and name columns
+const users = await userModel
+  .findMany()
+  .select({ id: true, name: true });
+
+// Fetch all columns except email
+const users = await userModel
+  .findMany()
+  .exclude({ email: true });
+
+// Combine: start with a whitelist, then drop a field
+const users = await userModel
+  .findMany()
+  .select({ id: true, name: true, email: true })
+  .exclude({ email: true });
+```
+
+This is equivalent to:
+
+```ts
+db.select({ id: schema.user.id, name: schema.user.name }).from(schema.user);
+```
+
+#### Combining query refiners
+
+```ts
+const users = await userModel
+  .findMany()
+  .with({ posts: true })
+  .select({ id: true, name: true });
+```
+
+Available query refiners:
+
+- `.select(fields)` — SQL SELECT whitelist
+- `.exclude(fields)` — SQL SELECT blacklist
+- `.with(relations)` — load related entities via JOINs
+- `.raw()` — skip format function
+- `.safe()` — wrap in `{ data, error }`
+- `.debug()` — inspect query state
+
+### Mutation-side refinement (`insert` / `update` / `delete` / `upsert` result)
+
+```ts
+const rows = await userModel
+  .insert({ email: "a@b.com", name: "Alex", age: 20 })
+  .return();
+
+const first = await userModel
+  .insert({ email: "b@b.com", name: "Anna", age: 21 })
+  .returnFirst();
+
+// .omit() removes fields from the result AFTER the query runs (programmatic, not SQL)
+const sanitized = await userModel
+  .where({ id: esc(1) })
+  .update({ secretField: 999 })
+  .returnFirst()
+  .omit({ secretField: true });
+```
+
+Available mutation refiners:
+
+- `.return(fields?)` — return all rows
+- `.returnFirst(fields?)` — return first row
+- `.omit(fields)` — remove fields from result after query (programmatic, not SQL)
+- `.safe()` — wrap in `{ data, error }`
+
+---
+
+## Error-safe execution
+
+Use `.safe()` when you prefer a result object instead of throw/reject behavior.
+
+```ts
+const result = await userModel.findMany().safe();
+
+if (result.error) {
+  console.error(result.error);
+} else {
+  console.log(result.data);
+}
+```
+
+Shape:
+
+```ts
+type SafeResult<T> =
+  | { data: T; error: undefined }
+  | { data: undefined; error: unknown };
+```
+
+---
+
+## Advanced: model options and extension
+
+### `format`
+
+```ts
+const userModel = model("user", {
+  format(row) {
+    const { secretField, ...rest } = row;
+    return {
+      ...rest,
+      isVerified: Boolean(rest.isVerified),
+    };
+  },
+});
+```
+
+Use `.raw()` to bypass format.
+
+### Default `where`
+
+```ts
+const activeUsers = model("user", {
+  where: { isVerified: esc(true) },
+});
+```
+
+### Custom `methods`
+
+```ts
+const userModel = model("user", {
+  methods: {
+    async byEmail(email: string) {
+      return await userModel.where({ email: esc(email) }).findFirst();
+    },
+  },
+});
+```
+
+### `extend()` and `db()`
+
+```ts
+const extended = userModel.extend({
+  methods: {
+    async adults() {
+      return await userModel.where({ age: { gte: esc(18) } }).findMany();
+    },
+  },
+});
+
+const txUserModel = userModel.db(db);
+```
+
+Note: when method names conflict during `extend`, existing runtime methods take precedence over newly passed ones.
+
+---
+
+## Full API reference
+
+### Model-level methods
+
+- Query/lifecycle:
+  - `where(value)`
+  - `findMany()`
+  - `findFirst()`
+  - `count()`
+  - `include(value)`
+  - `extend(options)`
+  - `db(dbInstance)`
+- Mutations:
+  - `insert(value)`
+  - `update(value)`
+  - `delete()`
+  - `upsert(value)`
+
+### Query result methods
+
+- `.with(...)`
+- `.select(...)`
+- `.exclude(...)`
+- `.raw()`
+- `.safe()`
+- `.debug()`
+
+### Mutation result methods
+
+- `.return(...)`
+- `.returnFirst(...)`
+- `.omit(...)`
+- `.safe()`
+
+---
+
+## Dialect notes
+
+- Dialects with native `.returning()` use it for mutation return pipelines.
+- Dialects with ID-only return paths may use dialect-specific fallback behavior.
+- Upsert uses `onConflictDoUpdate` when supported.
+
+---
+
+## Type safety notes
+
+- Prefer `esc(...)` for explicit where value/operator expressions.
+- `.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 }`.
+- `.return()` returns array shape; `.returnFirst()` returns single-row shape.
+
+---
+
+## Testing
+
+Comprehensive tests are available in `tests/base`:
+
+- `find.test.ts`
+- `insert.test.ts`
+- `update.test.ts`
+- `delete.test.ts`
+- `upsert.test.ts`
+- `count.test.ts`
+- `safe.test.ts`
+- `relations.test.ts`
+
+Run all base tests:
+
+```bash
+bun test base
+```
+
+---
+
+## Troubleshooting
+
+### `safe()` returns `{ data: undefined, error }`
+
+The underlying operation throws. Re-run without `.safe()` to inspect the raw stack.
+
+### `.return()` result shape surprises
+
+- `.return()` => array
+- `.returnFirst()` => single object
+- no return chain => dialect/default execution behavior
+
+### Relation loading with `.with(...)`
+
+Ensure relation metadata is defined with Drizzle `defineRelations` and passed to `modelBuilder({ relations })`.
+
+---
+
+## License
+
+MIT (follow repository root license if different).

package/TODO.md

@@ -1,11 +1,11 @@
 # TODO:
 
-- DONE TYPES => `count()` function to count rows
+- DONE => `count()` function to count rows
 - DONE => Fix types. On insert, and add Simplify<> = for more readable queries.
-- DONE TYPES => add `returnFirst()` to return first of `return()`
-- DONE TYPES => add `omit()` as progammic `exclude()`. The main difference is `omit()` is applied after query. `exclude()` is applied on the query.
-- JUST remake a entire core. Manually write code with a few AI changes.
-- DONE TYPES => Add `safe()`:
+- DONE => add `returnFirst()` to return first of `return()`
+- DONE => add `omit()` as progammic `exclude()`. The main difference is `omit()` is applied after query. `exclude()` is applied on the query.
+- DONE JUST remake a entire core. Manually write code with a few AI changes.
+- DONE => Add `safe()`:
 ```ts
 const { data: user, error } = userModel.findFirst().safe();
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apisr/drizzle-model",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "private": false,
   "scripts": {
     "lint": "eslint . --max-warnings 0",
@@ -8,7 +8,8 @@
     "check-types": "tsc --noEmit"
   },
   "peerDependencies": {
-    "drizzle-orm": "^1.0.0-beta.2-86f844e"
+    "drizzle-orm": "^1.0.0-beta.2-86f844e",
+    "pg": "^8.16.3"
   },
   "devDependencies": {
     "@repo/eslint-config": "*",
@@ -31,6 +32,6 @@
   },
   "type": "module",
   "dependencies": {
-    "pg": "^8.16.3"
+    "type-fest": "^5.4.4"
   }
 }

package/src/core/query/joins.ts

@@ -1,6 +1,7 @@
 import { and, eq } from "drizzle-orm";
 import type { DialectHelper } from "../dialect.ts";
 import { ProjectionBuilder } from "./projection.ts";
+import { WhereCompiler } from "./where.ts";
 
 /** Generic record type used throughout the join executor. */
 type AnyRecord = Record<string, unknown>;
@@ -45,6 +46,8 @@ export interface JoinNode {
 	targetTable: AnyRecord;
 	/** Name of the target (child) table. */
 	targetTableName: string;
+	/** Optional compiled WHERE filter for this relation (added to JOIN ON). */
+	whereFilter?: unknown;
 }
 
 // ---------------------------------------------------------------------------
@@ -59,12 +62,16 @@ export interface JoinExecutorConfig {
 	baseTableName: string;
 	/** The Drizzle database instance. */
 	db: unknown;
+	/** SQL SELECT blacklist for base table columns. */
+	exclude?: AnyRecord;
 	/** When `true`, only the first result is returned. */
 	limitOne?: boolean;
 	/** The relations metadata map from Drizzle. */
 	relations: Record<string, AnyRecord>;
 	/** The full schema map (`{ tableName: drizzleTable }`). */
 	schema: Record<string, AnyRecord>;
+	/** SQL SELECT whitelist for base table columns. */
+	select?: AnyRecord;
 	/** An optional compiled SQL where clause. */
 	whereSql?: unknown;
 	/** The user-supplied `.with()` value describing which relations to load. */
@@ -91,10 +98,12 @@ export interface JoinExecutorConfig {
 export class JoinExecutor {
 	private readonly dialect: DialectHelper;
 	private readonly projection: ProjectionBuilder;
+	private readonly whereCompiler: WhereCompiler;
 
 	constructor(dialect: DialectHelper) {
 		this.dialect = dialect;
 		this.projection = new ProjectionBuilder();
+		this.whereCompiler = new WhereCompiler();
 	}
 
 	/**
@@ -126,6 +135,7 @@ export class JoinExecutor {
 	 */
 	private async buildJoinTree(config: JoinExecutorConfig): Promise<JoinNode> {
 		const usedAliasKeys = new Set<string>();
+		usedAliasKeys.add(`table:${config.baseTableName}`);
 
 		const root: JoinNode = {
 			path: [],
@@ -180,6 +190,9 @@ export class JoinExecutor {
 		value: unknown,
 		path: string[]
 	): Promise<JoinNode> {
+		const { whereValue, nestedWith } =
+			this.extractRelationDescriptor(value);
+
 		const relMeta = this.getRelationMeta(
 			config.relations,
 			currentTableName,
@@ -200,6 +213,13 @@ export class JoinExecutor {
 			? await this.dialect.createTableAlias(targetTable, aliasKey)
 			: targetTable;
 
+		const whereFilter = whereValue
+			? this.whereCompiler.compile(
+					targetAliasTable as AnyRecord,
+					whereValue
+			  )
+			: undefined;
+
 		const node: JoinNode = {
 			path: [...path, key],
 			key,
@@ -215,10 +235,13 @@ export class JoinExecutor {
 			pkField: this.getPrimaryKeyField(targetAliasTable),
 			parent,
 			children: [],
+			whereFilter,
 		};
 
-		if (value && typeof value === "object" && value !== (true as unknown)) {
-			for (const [childKey, childVal] of Object.entries(value as AnyRecord)) {
+		if (nestedWith && typeof nestedWith === "object") {
+			for (const [childKey, childVal] of Object.entries(
+				nestedWith as AnyRecord
+			)) {
 				if (
 					childVal !== true &&
 					(typeof childVal !== "object" || childVal == null)
@@ -258,8 +281,14 @@ export class JoinExecutor {
 		root: JoinNode,
 		nodes: JoinNode[]
 	): Promise<AnyRecord[]> {
+		const baseColumns = this.projection.build(
+			root.targetAliasTable,
+			config.select,
+			config.exclude
+		).selectMap;
+
 		const selectMap: AnyRecord = {
-			base: this.projection.extractColumns(root.targetAliasTable),
+			base: baseColumns,
 		};
 
 		for (const node of nodes) {
@@ -387,6 +416,10 @@ export class JoinExecutor {
 			return eq(tgtCol as never, src as never);
 		});
 
+		if (node.whereFilter) {
+			parts.push(node.whereFilter as never);
+		}
+
 		return parts.length === 1 ? parts[0] : and(...parts);
 	}
 
@@ -496,6 +529,40 @@ export class JoinExecutor {
 		);
 	}
 
+	/**
+	 * Extracts relation where clause and nested relations from a `.with()` value.
+	 *
+	 * Handles three cases:
+	 * - `true` → no filter, no nested relations.
+	 * - A ModelRuntime (has `$model === "model"`) → extract `$where`, no nested.
+	 * - A model descriptor (`__modelRelation: true`) → extract `whereValue` and `with`.
+	 * - A plain object → treat as nested relation map.
+	 */
+	private extractRelationDescriptor(value: unknown): {
+		whereValue: unknown;
+		nestedWith: unknown;
+	} {
+		if (value === true || value == null) {
+			return { whereValue: undefined, nestedWith: undefined };
+		}
+
+		if (typeof value !== "object") {
+			return { whereValue: undefined, nestedWith: undefined };
+		}
+
+		const rec = value as AnyRecord;
+
+		if (rec.$model === "model") {
+			return { whereValue: rec.$where, nestedWith: undefined };
+		}
+
+		if (rec.__modelRelation === true) {
+			return { whereValue: rec.whereValue, nestedWith: rec.with };
+		}
+
+		return { whereValue: undefined, nestedWith: value };
+	}
+
 	// ---------------------------------------------------------------------------
 	// Helpers: result grouping internals
 	// ---------------------------------------------------------------------------

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> {