@apisr/drizzle-model 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -1,6 +1,9 @@
 # Change log
 
-## 2.0.2 | 01-0-2026
+## 2.0.3 | 02-03-2026
+- I forgot to rebuild package in `2.0.2 to 2.0.0`, damn
+
+## 2.0.2 | 01-03-2026
 - add `esc.*()` operations
 - update README.md with new `esc.*()`
 

package/README.md

@@ -1,9 +1,12 @@
 # @apisr/drizzle-model
 
-> **⚠️ This package is on high development stage! May have bugs**  
+> **⚠️ Development Status**  
+> This package is in active development and **not recommended for production use yet**.  
+> APIs may change between minor versions. Semantic versioning will be enforced after v1.0.0 stable release.
 
 > **⚠️ Requires `drizzle-orm@beta`**  
 > This package is built for Drizzle ORM beta versions (`^1.0.0-beta.2-86f844e`).  
+> See [Compatibility](#compatibility) for details.  
 
 Type-safe, chainable model runtime for **Drizzle ORM**.
 
@@ -16,6 +19,58 @@ Build reusable models for tables and relations with a progressive flow:
 
 ---
 
+## Philosophy
+
+Drizzle ORM gives you low-level composable primitives.
+
+`@apisr/drizzle-model` adds:
+
+- **A model abstraction per table** — encapsulate table logic in reusable models
+- **A progressive query pipeline** — build queries step-by-step with clear intent
+- **A unified result-shaping layer** — consistent formatting and transformation
+- **Safe execution flows** — error handling without try-catch boilerplate
+- **Reusable business logic extensions** — custom methods and model composition
+
+---
+
+## Why not just use Drizzle directly?
+
+Drizzle ORM is already type-safe and powerful.
+
+`@apisr/drizzle-model` adds value when you need:
+
+- **Reusable model abstraction per table** — define once, use everywhere
+- **Chainable intent → execution flow** — progressive, readable query building
+- **Built-in result shaping** — consistent formatting and field selection
+- **Centralized formatting layer** — transform data in one place
+- **Safer error pipelines** — `.safe()` for error-as-value patterns
+- **Composable model extensions** — custom methods and model inheritance
+
+### Quick Comparison
+
+**Without drizzle-model:**
+```ts
+import { eq } from "drizzle-orm";
+
+await db
+  .select()
+  .from(schema.user)
+  .where(eq(schema.user.id, 1));
+```
+
+**With drizzle-model:**
+```ts
+await userModel.where({ id: esc(1) }).findFirst();
+```
+
+The difference becomes more apparent with:
+- Consistent formatting across queries
+- Reusable where conditions
+- Nested relation loading
+- Custom business logic methods
+
+---
+
 ## Learning Path (easy → advanced)
 
 1. [Install and create your first model](#install-and-first-model)
@@ -23,8 +78,12 @@ Build reusable models for tables and relations with a progressive flow:
 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)
+6. [Transactions](#transactions)
+7. [Advanced: model options and extension](#advanced-model-options-and-extension)
+8. [Performance considerations](#performance-considerations)
+9. [Limitations](#limitations)
+10. [Full API reference](#full-api-reference)
+11. [Compatibility](#compatibility)
 
 ---
 
@@ -51,6 +110,17 @@ const model = modelBuilder({
 });
 
 const userModel = model("user", {});
+
+// Real-world example with formatting
+const postModel = model("post", {
+  format(row) {
+    return {
+      ...row,
+      createdAt: new Date(row.createdAt),
+      updatedAt: row.updatedAt ? new Date(row.updatedAt) : null,
+    };
+  },
+});
 ```
 
 > `drizzle-orm` is a peer dependency.
@@ -68,9 +138,15 @@ const user = await userModel.findFirst();
 ### Find many with filter
 
 ```ts
+// ✅ Correct: use esc() for literal values
 const users = await userModel
   .where({ name: esc("Alex") })
   .findMany();
+
+// ❌ Wrong: plain values are not allowed
+// const users = await userModel
+//   .where({ name: "Alex" }) // Type error!
+//   .findMany();
 ```
 
 ### Count
@@ -166,10 +242,15 @@ const users = await userModel
 
 #### Using `.include()` for type-safe relation values
 
-`.include()` is a helper that returns the relation value as-is, used for type-level relation selection:
+`.include()` is a helper that allows you to specify nested relations when using a model instance in `.with()`.
+
+**Why it exists:**
+- When you pass a model with `.where()` to `.with()`, you need a way to also load nested relations
+- `.include()` preserves the model's where clause while adding relation loading
+- It's purely type-level — it doesn't affect SQL directly, but enables type-safe nested relation selection
 
 ```ts
-// Pass to .with()
+// Load posts with a filter AND their comments
 const users = await userModel.findMany().with({
   posts: postModel.where({
     title: {
@@ -179,6 +260,11 @@ const users = await userModel.findMany().with({
     comments: true
   })
 });
+
+// Without .include(), you can only filter posts:
+const users = await userModel.findMany().with({
+  posts: postModel.where({ published: esc(true) })
+});
 ```
 
 #### SQL column selection with `.select()` and `.exclude()`
@@ -253,6 +339,32 @@ Available mutation refiners:
 - `.omit(fields)` — remove fields from result after query (programmatic, not SQL)
 - `.safe()` — wrap in `{ data, error }`
 
+### Edge case behavior
+
+**What happens when `.findFirst()` returns nothing?**
+
+```ts
+const user = await userModel.where({ id: esc(999) }).findFirst();
+// user is `undefined` if no row matches
+```
+
+**What does `.returnFirst()` return if no row was affected?**
+
+```ts
+const updated = await userModel
+  .where({ id: esc(999) })
+  .update({ name: "New" })
+  .returnFirst();
+// updated is `undefined` if no row was updated
+```
+
+**Return nullability:**
+- `.findFirst()` → `T | undefined`
+- `.findMany()` → `T[]` (empty array if no matches)
+- `.returnFirst()` → `T | undefined`
+- `.return()` → `T[]` (empty array if no rows affected)
+- `.count()` → `number` (0 if no matches)
+
 ---
 
 ## Error-safe execution
@@ -279,10 +391,39 @@ type SafeResult<T> =
 
 ---
 
+## Transactions
+
+Use `.db()` to bind a model to a transaction instance:
+
+```ts
+await db.transaction(async (tx) => {
+  const txUser = userModel.db(tx);
+  const txPost = postModel.db(tx);
+  
+  const user = await txUser.insert({
+    name: "Alice",
+    email: "alice@example.com",
+    age: 25,
+  }).returnFirst();
+  
+  await txPost.insert({
+    title: "First Post",
+    content: "Hello world",
+    authorId: user.id,
+  });
+});
+```
+
+The transaction-bound model uses the same API as the regular model.
+
+---
+
 ## Advanced: model options and extension
 
 ### `format`
 
+Transform every row returned from queries:
+
 ```ts
 const userModel = model("user", {
   format(row) {
@@ -293,9 +434,27 @@ const userModel = model("user", {
     };
   },
 });
+
+// Real-world example: date parsing and sanitization
+const postModel = model("post", {
+  format(row) {
+    return {
+      ...row,
+      createdAt: new Date(row.createdAt),
+      updatedAt: row.updatedAt ? new Date(row.updatedAt) : null,
+      // Remove internal fields
+      internalStatus: undefined,
+    };
+  },
+});
 ```
 
-Use `.raw()` to bypass format.
+Use `.raw()` to bypass format when needed:
+
+```ts
+const rawUser = await userModel.findFirst().raw();
+// secretField is present, isVerified is original type
+```
 
 ### Default `where`
 
@@ -335,39 +494,123 @@ Note: when method names conflict during `extend`, existing runtime methods take
 
 ---
 
+## Performance considerations
+
+### Relation loading with `.with()`
+
+- **No N+1 queries** — `.with()` uses JOIN-based loading, not separate queries per row
+- **Deep nesting** may generate larger queries — use `.select()` to reduce payload size
+- **Selective loading** — only load relations you need
+
+```ts
+// ✅ Good: selective loading
+const users = await userModel
+  .findMany()
+  .with({ posts: true })
+  .select({ id: true, name: true });
+
+// ⚠️ Careful: deep nesting + all columns
+const users = await userModel
+  .findMany()
+  .with({
+    posts: {
+      comments: {
+        author: true
+      }
+    }
+  });
+// This works, but generates a large query with many JOINs
+```
+
+### Query optimization tips
+
+- Use `.select()` to fetch only needed columns
+- Use `.count()` instead of `.findMany()` when you only need the count
+- Add indexes on columns used in `.where()` conditions
+- Use `.raw()` to skip formatting when performance is critical
+
+---
+
+## Limitations
+
+Current limitations you should be aware of:
+
+- **Requires Drizzle ORM relations v2** — v1 relations are not supported
+- **Explicit `esc()` required** — plain values in `.where()` are not allowed (by design for type safety)
+- **No lazy loading** — relations must be loaded eagerly with `.with()`
+- **No middleware system** — use `format()` for transformations
+- **No query caching** — implement caching at application level if needed
+- **No automatic soft deletes** — implement via default `where` conditions
+- **No polymorphic relations** — standard Drizzle relation limitations apply
+
+---
+
 ## 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()`
+### Intent Stage
+
+Declare what you want to do:
+
+- `where(value)` — filter conditions
+- `insert(value)` — insert new rows
+- `update(value)` — update existing rows
+- `delete()` — delete rows
+- `upsert(value)` — insert or update
+
+### Execution Stage
+
+Choose how to execute:
+
+**Queries:**
+- `findMany()` — fetch multiple rows
+- `findFirst()` — fetch first matching row
+- `count()` — count matching rows
+
+**Mutations:**
+- `.return()` — return all affected rows
+- `.returnFirst()` — return first affected row
+- (no return chain) — execute without returning rows
+
+### Refinement Stage
+
+Shape the SQL query:
+
+- `.with(relations)` — load related entities via JOINs
+- `.select(fields)` — SQL SELECT whitelist
+- `.exclude(fields)` — SQL SELECT blacklist
+
+### Programmatic Stage
+
+Post-process the result:
+
+- `.omit(fields)` — remove fields from result after query
+- `.raw()` — skip format function
+- `.safe()` — wrap in `{ data, error }`
+- `.debug()` — inspect query state
+
+### Model-level utilities
+
+- `include(value)` — specify nested relations for model instances in `.with()`
+- `extend(options)` — create extended model with additional methods
+- `db(dbInstance)` — bind model to different db/transaction instance
+
+---
+
+## Compatibility
+
+| Drizzle Version | Supported | Notes |
+|------------------|-----------|-------|
+| v1 beta (≥ 1.0.0-beta.2) | ✅ Yes | Requires relations v2 |
+| v0.x stable | ❌ No | Relations v1 not supported |
+
+**Supported dialects:**
+- PostgreSQL
+- MySQL
+- SQLite
+
+**Node.js version:**
+- Node.js 18+ recommended
+- Bun 1.0+ supported
 
 ---
 

package/ROADMAP.md

@@ -1 +1,4 @@
+# Roadmap
+
 - Support the (`Views`)[https://orm.drizzle.team/docs/views] on future.
+- Support `format` in relations (joins). Not sure, as I dont know how to make right API for this

package/dist/core/dialect.mjs

@@ -0,0 +1,56 @@
+//#region src/core/dialect.ts
+/**
+* Encapsulates dialect-specific logic for different SQL databases.
+*
+* Provides helpers for determining returning-id behaviour and
+* lazily importing the correct Drizzle `alias()` function based on the dialect.
+*/
+var DialectHelper = class {
+	/** The dialect string identifying the target database engine. */
+	dialect;
+	constructor(dialect) {
+		this.dialect = dialect;
+	}
+	/**
+	* Returns `true` when the dialect only supports `$returningId()`
+	* instead of the standard `.returning()` method.
+	*
+	* Applies to MySQL, SingleStore and CockroachDB.
+	*/
+	isReturningIdOnly() {
+		return this.dialect === "MySQL" || this.dialect === "SingleStore" || this.dialect === "CockroachDB";
+	}
+	/**
+	* Creates a table alias using the dialect-specific Drizzle module.
+	*
+	* Dynamically imports the correct `alias` utility so the core
+	* does not carry a hard dependency on every dialect.
+	*
+	* @param table - The Drizzle table object to alias.
+	* @param aliasName - The SQL alias name.
+	* @returns The aliased table, or the original table if aliasing is unavailable.
+	*/
+	async createTableAlias(table, aliasName) {
+		const modulePath = this.getDialectModulePath();
+		if (!modulePath) return table;
+		const mod = await import(modulePath);
+		if (typeof mod.alias === "function") return mod.alias(table, aliasName);
+		return table;
+	}
+	/**
+	* Resolves the Drizzle ORM module path for the current dialect.
+	*
+	* @returns The import specifier, or `undefined` for unsupported dialects.
+	*/
+	getDialectModulePath() {
+		switch (this.dialect) {
+			case "PostgreSQL": return "drizzle-orm/pg-core";
+			case "MySQL": return "drizzle-orm/mysql-core";
+			case "SQLite": return "drizzle-orm/sqlite-core";
+			default: return;
+		}
+	}
+};
+
+//#endregion
+export { DialectHelper };