@apisr/drizzle-model 0.0.4 → 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/DISCLAIMER.md

@@ -0,0 +1,5 @@
+# DISCLAIMER
+
+### What is still not in package
+- Custom columns (Still not planned)
+- Views (Still not planned)

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,64 +1,11 @@
-- * Add all essential functions as `update`, `insert`, `delete`, `findMany`, `findFirst`
-- Make `route` function (Just duplicate):
-```ts
-const [val1, val2] = await userModel.name({
-  like: "A%"
-}).route(
-  (userModel) => userModel.isVerified(true).findMany(),
-  (userModel) => userModel.isVerified(false).age({
-    lte: 18
-  }).findMany()
-  // ...args[]
-)
-```
-- Make built in `paginate` which is pagination function, used as:
-```ts
-const userModel = model({
-  table: userTable,
-  
-  // Optional
-  pagination: {
-    max: 10
-  }
-})
+# TODO:
 
-const page = 1;
-
-userModel.name({
-  like: "A%"
-}).userId(userId).paginate(page)
-```
-* Make built in `upsert`, as:
+- DONE => `count()` function to count rows
+- DONE => Fix types. On insert, and add Simplify<> = for more readable queries.
+- 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
-userModel.id(123).upsert({
-  // create obj
-}, {
-  // update obj 
-}, /* options */)
-```
-
-* Transactions:
-```ts
-userModel.transaction(tx => ...);
-
-// With other models
-userModel.transaction(tx => {
-  postsModel.db(tx).insert({
-    userId: 123,
-    content: ...
-  })
-  
-  // or
-  
-  const txPostsModel = postsModel.db(tx);
-  
-  txPostsModel.insert({
-    userId: 123,
-    content: ...
-  })
-  
-  txPostsModel.userId(123).delete()
-});
+const { data: user, error } = userModel.findFirst().safe();
 ```
-- / Soft delete?
-- * Dialect based configuration `mysql`, `pgsql` and etc... like `returning()` on pgsql and `$returningId()` on mysql

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apisr/drizzle-model",
-  "version": "0.0.4",
+  "version": "2.0.1",
   "private": false,
   "scripts": {
     "lint": "eslint . --max-warnings 0",
@@ -8,11 +8,13 @@
     "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": "*",
     "@repo/typescript-config": "*",
+    "@apisr/logger": "^0.0.3",
     "@types/bun": "latest",
     "@types/node": "^22.15.3",
     "@types/pg": "^8.15.6",
@@ -30,6 +32,6 @@
   },
   "type": "module",
   "dependencies": {
-    "pg": "^8.16.3"
+    "type-fest": "^5.4.4"
   }
 }

package/src/core/dialect.ts

@@ -0,0 +1,81 @@
+import type { ModelDialect } from "../model/dialect.ts";
+
+/** Alias for a generic record with string keys. */
+type AnyRecord = Record<string, unknown>;
+
+/**
+ * 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.
+ */
+export class DialectHelper {
+	/** The dialect string identifying the target database engine. */
+	readonly dialect: ModelDialect;
+
+	constructor(dialect: ModelDialect) {
+		this.dialect = dialect;
+	}
+
+	/**
+	 * Returns `true` when the dialect only supports `$returningId()`
+	 * instead of the standard `.returning()` method.
+	 *
+	 * Applies to MySQL, SingleStore and CockroachDB.
+	 */
+	isReturningIdOnly(): boolean {
+		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: AnyRecord,
+		aliasName: string
+	): Promise<AnyRecord> {
+		const modulePath = this.getDialectModulePath();
+		if (!modulePath) {
+			return table;
+		}
+
+		const mod: AnyRecord = await import(modulePath);
+		if (typeof mod.alias === "function") {
+			return (mod.alias as (t: AnyRecord, name: string) => AnyRecord)(
+				table,
+				aliasName
+			);
+		}
+
+		return table;
+	}
+
+	/**
+	 * Resolves the Drizzle ORM module path for the current dialect.
+	 *
+	 * @returns The import specifier, or `undefined` for unsupported dialects.
+	 */
+	private getDialectModulePath(): string | undefined {
+		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 undefined;
+		}
+	}
+}

package/src/core/index.ts

@@ -0,0 +1,24 @@
+// Core v2 — public API
+export { DialectHelper } from "./dialect.ts";
+export { QueryError } from "./query/error.ts";
+export {
+	JoinExecutor,
+	type JoinExecutorConfig,
+	type JoinNode,
+} from "./query/joins.ts";
+export {
+	ProjectionBuilder,
+	type ProjectionResult,
+} from "./query/projection.ts";
+export { WhereCompiler } from "./query/where.ts";
+export {
+	type MutateKind,
+	MutateResult,
+	type MutateState,
+	QueryResult,
+	type QueryState,
+	type SafeResult,
+	ThenableResult,
+} from "./result.ts";
+export { ModelRuntime, type ModelRuntimeConfig } from "./runtime.ts";
+export { ResultTransformer } from "./transform.ts";

package/src/core/query/error.ts

@@ -0,0 +1,15 @@
+/**
+ * Represents an error that occurred during query compilation or execution.
+ *
+ * Extends the native `Error` class so it can be caught independently
+ * from generic runtime errors.
+ */
+export class QueryError extends Error {
+	/** Discriminator for runtime type checks. */
+	readonly kind = "QueryError" as const;
+
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "QueryError";
+	}
+}