@vertz/db 0.2.14 → 0.2.16

package/dist/postgres/index.d.ts

@@ -29,6 +29,12 @@ interface DbDriver {
 		rowsAffected: number;
 	}>;
 	/**
+	* Execute a callback within a database transaction.
+	* The callback receives a transaction-scoped QueryFn.
+	* Optional — not all drivers support transactions (e.g., D1).
+	*/
+	beginTransaction?<T>(fn: (txQueryFn: QueryFn) => Promise<T>): Promise<T>;
+	/**
 	* Close the database connection.
 	*/
 	close(): Promise<void>;

package/dist/postgres/index.js

@@ -1,6 +1,6 @@
 import {
   createPostgresDriver
-} from "../shared/chunk-rqe0prft.js";
+} from "../shared/chunk-rjry8vc2.js";
 import"../shared/chunk-j4kwq1gh.js";
 export {
   createPostgresDriver

package/dist/shared/{chunk-pxjcpnpx.js → chunk-3a9nybt2.js}

@@ -160,7 +160,9 @@ function buildFilterClauses(filter, paramOffset, overrides, dialect) {
       continue;
     }
     const columnRef = resolveColumnRef(key, overrides, dialect);
-    if (isOperatorObject(value)) {
+    if (value === null) {
+      clauses.push(`${columnRef} IS NULL`);
+    } else if (isOperatorObject(value)) {
       const result = buildOperatorCondition(columnRef, value, idx, dialect);
       clauses.push(...result.clauses);
       allParams.push(...result.params);
@@ -372,7 +374,10 @@ function buildSelect(options, dialect = options.dialect ?? defaultPostgresDialec
     parts.push(`WHERE ${whereClauses.join(" AND ")}`);
   }
   if (options.orderBy) {
-    const orderClauses = Object.entries(options.orderBy).map(([col, dir]) => `"${camelToSnake(col, casingOverrides)}" ${dir.toUpperCase()}`);
+    const orderClauses = Object.entries(options.orderBy).map(([col, dir]) => {
+      const safeDir = dir.toUpperCase() === "DESC" ? "DESC" : "ASC";
+      return `"${camelToSnake(col, casingOverrides)}" ${safeDir}`;
+    });
     if (orderClauses.length > 0) {
       parts.push(`ORDER BY ${orderClauses.join(", ")}`);
     }

package/dist/shared/{chunk-pkv8w501.js → chunk-ed82s3sa.js}

@@ -122,10 +122,14 @@ function buildWhereClause(where, columns) {
   const clauses = [];
   const params = [];
   for (const [key, value] of Object.entries(where)) {
-    clauses.push(`${key} = ?`);
-    const colMeta = columns[key]?._meta;
-    const convertedValue = convertValueForSql(value, colMeta?.sqlType);
-    params.push(convertedValue);
+    if (value === null) {
+      clauses.push(`${key} IS NULL`);
+    } else {
+      clauses.push(`${key} = ?`);
+      const colMeta = columns[key]?._meta;
+      const convertedValue = convertValueForSql(value, colMeta?.sqlType);
+      params.push(convertedValue);
+    }
   }
   return { clauses, params };
 }

package/dist/shared/{chunk-2gd1fqcw.js → chunk-p2x2vmg5.js}

@@ -1,6 +1,6 @@
 import {
   createPostgresDriver
-} from "./chunk-rqe0prft.js";
+} from "./chunk-rjry8vc2.js";
 import"./chunk-j4kwq1gh.js";
 export {
   createPostgresDriver

package/dist/shared/{chunk-rqe0prft.js → chunk-rjry8vc2.js}

@@ -63,6 +63,29 @@ function createPostgresDriver(url, pool) {
       const result = await queryFn(sql2, params ?? []);
       return { rowsAffected: result.rowCount };
     },
+    async beginTransaction(fn) {
+      return sql.begin(async (txSql) => {
+        const txQueryFn = async (sqlStr, params) => {
+          try {
+            const result = await txSql.unsafe(sqlStr, params);
+            const rows = result.map((row) => {
+              const mapped = {};
+              for (const [key, value] of Object.entries(row)) {
+                mapped[key] = coerceValue(value);
+              }
+              return mapped;
+            });
+            return {
+              rows,
+              rowCount: result.count ?? rows.length
+            };
+          } catch (error) {
+            adaptPostgresError(error);
+          }
+        };
+        return fn(txQueryFn);
+      });
+    },
     async close() {
       await sql.end();
     },

package/dist/shared/{chunk-ndxe1h28.js → chunk-tnaf4hbj.js}

@@ -2,7 +2,7 @@ import {
   BaseSqlAdapter,
   generateCreateTableSql,
   generateIndexSql
-} from "./chunk-pkv8w501.js";
+} from "./chunk-ed82s3sa.js";
 
 // src/adapters/d1-adapter.ts
 function createD1Driver(d1) {

package/dist/sql/index.js

@@ -4,7 +4,7 @@ import {
   buildSelect,
   buildUpdate,
   buildWhere
-} from "../shared/chunk-pxjcpnpx.js";
+} from "../shared/chunk-3a9nybt2.js";
 import {
   camelToSnake,
   snakeToCamel

package/dist/sqlite/index.d.ts

@@ -1,4 +1,17 @@
 /**
+* Query executor — wraps raw SQL execution with error mapping.
+*
+* Takes a query function (from the database driver) and wraps it to:
+* 1. Execute parameterized SQL
+* 2. Map PG errors to typed DbError subclasses
+* 3. Return typed QueryResult
+*/
+interface ExecutorResult<T> {
+	readonly rows: readonly T[];
+	readonly rowCount: number;
+}
+type QueryFn = <T>(sql: string, params: readonly unknown[]) => Promise<ExecutorResult<T>>;
+/**
 * Database driver interface.
 *
 * Provides a unified interface for different database backends
@@ -16,6 +29,12 @@ interface DbDriver {
 		rowsAffected: number;
 	}>;
 	/**
+	* Execute a callback within a database transaction.
+	* The callback receives a transaction-scoped QueryFn.
+	* Optional — not all drivers support transactions (e.g., D1).
+	*/
+	beginTransaction?<T>(fn: (txQueryFn: QueryFn) => Promise<T>): Promise<T>;
+	/**
 	* Close the database connection.
 	*/
 	close(): Promise<void>;
@@ -54,6 +73,7 @@ interface ColumnBuilder<
 	readonly _meta: TMeta;
 	primary(options?: {
 		generate?: "cuid" | "uuid" | "nanoid";
+		generated?: boolean;
 	}): ColumnBuilder<TType, Omit<TMeta, "primary" | "hasDefault" | "generate"> & {
 		readonly primary: true;
 		readonly hasDefault: true;
@@ -84,6 +104,20 @@ interface ColumnBuilder<
 	}>;
 }
 type InferColumnType<C> = C extends ColumnBuilder<infer T, ColumnMetadata> ? T : never;
+interface ThroughDef<TJoin extends TableDef<ColumnRecord> = TableDef<ColumnRecord>> {
+	readonly table: () => TJoin;
+	readonly thisKey: string;
+	readonly thatKey: string;
+}
+interface RelationDef<
+	TTarget extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
+	TType extends "one" | "many" = "one" | "many"
+> {
+	readonly _type: TType;
+	readonly _target: () => TTarget;
+	readonly _foreignKey: string | null;
+	readonly _through: ThroughDef | null;
+}
 type IndexType = "btree" | "hash" | "gin" | "gist" | "brin";
 interface IndexDef {
 	readonly columns: readonly string[];
@@ -172,28 +206,129 @@ interface TableDef<TColumns extends ColumnRecord = ColumnRecord> {
 	/** Mark this table as shared / cross-tenant. */
 	shared(): TableDef<TColumns>;
 }
+/** Operators available for comparable types (number, string, Date, bigint). */
+interface ComparisonOperators<T> {
+	readonly eq?: T;
+	readonly ne?: T;
+	readonly gt?: T;
+	readonly gte?: T;
+	readonly lt?: T;
+	readonly lte?: T;
+	readonly in?: readonly T[];
+	readonly notIn?: readonly T[];
+}
+/** Additional operators for string columns. */
+interface StringOperators {
+	readonly contains?: string;
+	readonly startsWith?: string;
+	readonly endsWith?: string;
+}
+/** The `isNull` operator — only available for nullable columns. */
+interface NullOperator {
+	readonly isNull?: boolean;
+}
 /**
-* Database Adapter Types for @vertz/db
+* Resolves the filter operators for a single column based on its inferred type
+* and nullable metadata.
 *
-* Generic adapter interface that abstracts database operations.
-* Implemented by SQLite, D1, and other database adapters.
+* - All types get comparison + in/notIn
+* - String types additionally get contains, startsWith, endsWith
+* - Nullable columns additionally get isNull
+*
+* Uses [T] extends [string] to prevent union distribution -- ensures that a
+* union like 'admin' | 'editor' keeps the full union in each operator slot.
 */
-interface ListOptions {
+type ColumnFilterOperators<
+	TType,
+	TNullable extends boolean
+> = ([TType] extends [string] ? ComparisonOperators<TType> & StringOperators : ComparisonOperators<TType>) & (TNullable extends true ? NullOperator : unknown);
+/** Determine whether a column is nullable from its metadata. */
+type IsNullable<C> = C extends ColumnBuilder<unknown, infer M> ? M extends {
+	readonly nullable: true;
+} ? true : false : false;
+/**
+* FilterType<TColumns> — typed where clause.
+*
+* Each key maps to either:
+* - A direct value (shorthand for `{ eq: value }`)
+* - An object with typed filter operators
+*/
+type FilterType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : InferColumnType<TColumns[K]> | ColumnFilterOperators<InferColumnType<TColumns[K]>, IsNullable<TColumns[K]>> };
+type OrderByType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : "asc" | "desc" };
+/** Relations record — maps relation names to RelationDef. */
+type RelationsRecord = Record<string, RelationDef>;
+/**
+* The shape of include options for a given relations record.
+* Each relation can be:
+* - `true` — include with default fields
+* - An object with `select`, `where`, `orderBy`, `limit` constrained to target table columns
+*/
+type IncludeOption<TRelations extends RelationsRecord> = { [K in keyof TRelations]? : true | (RelationTarget<TRelations[K]> extends TableDef<infer TCols> ? {
+	select?: { [C in keyof TCols]? : true };
+	where?: FilterType<TCols>;
+	orderBy?: OrderByType<TCols>;
+	limit?: number;
+	/** Nested includes — untyped until full model registry is threaded through. */
+	include?: Record<string, unknown>;
+} : never) };
+/** Extract the target table from a RelationDef. */
+type RelationTarget<R> = R extends RelationDef<infer TTarget, "one" | "many"> ? TTarget : never;
+/** A model entry in the database registry, pairing a table with its relations. */
+interface ModelEntry<
+	TTable extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
+	TRelations extends RelationsRecord = RelationsRecord
+> {
+	readonly table: TTable;
+	readonly relations: TRelations;
+}
+/** A single include entry with optional query constraints. */
+interface AdapterIncludeEntry {
+	select?: Record<string, true>;
 	where?: Record<string, unknown>;
 	orderBy?: Record<string, "asc" | "desc">;
 	limit?: number;
+	include?: Record<string, unknown>;
+}
+/** Include specification: maps relation names to `true` or structured entries. */
+type AdapterIncludeSpec = Record<string, true | AdapterIncludeEntry>;
+/**
+* Resolves the where clause type for a given entry.
+* When TEntry is the default (unparameterized), falls back to Record<string, unknown>.
+*/
+type ResolveWhere<TEntry extends ModelEntry> = TEntry extends ModelEntry<infer TTable> ? TTable extends TableDef<infer TCols> ? [ColumnRecord] extends [TCols] ? Record<string, unknown> : FilterType<TCols> : Record<string, unknown> : Record<string, unknown>;
+/**
+* Resolves the orderBy type for a given entry.
+* When TEntry is the default (unparameterized), falls back to Record<string, 'asc' | 'desc'>.
+*/
+type ResolveOrderBy<TEntry extends ModelEntry> = TEntry extends ModelEntry<infer TTable> ? TTable extends TableDef<infer TCols> ? [ColumnRecord] extends [TCols] ? Record<string, "asc" | "desc"> : OrderByType<TCols> : Record<string, "asc" | "desc"> : Record<string, "asc" | "desc">;
+/**
+* Resolves the include type for a given entry.
+* When TEntry is the default (unparameterized), falls back to AdapterIncludeSpec.
+*/
+type ResolveInclude<TEntry extends ModelEntry> = TEntry extends ModelEntry<TableDef<ColumnRecord>, infer TRels> ? [Record<string, never>] extends [TRels] ? AdapterIncludeSpec : IncludeOption<TRels> : AdapterIncludeSpec;
+interface ListOptions<TEntry extends ModelEntry = ModelEntry> {
+	where?: ResolveWhere<TEntry>;
+	orderBy?: ResolveOrderBy<TEntry>;
+	limit?: number;
 	/** Cursor-based pagination: fetch records after this ID. */
 	after?: string;
+	/** Relation include specification for relation loading. */
+	include?: ResolveInclude<TEntry>;
+}
+/** Options for get-by-id operations. */
+interface GetOptions<TEntry extends ModelEntry = ModelEntry> {
+	/** Relation include specification for relation loading. */
+	include?: ResolveInclude<TEntry>;
 }
-interface EntityDbAdapter {
-	get(id: string): Promise<Record<string, unknown> | null>;
-	list(options?: ListOptions): Promise<{
-		data: Record<string, unknown>[];
+interface EntityDbAdapter<TEntry extends ModelEntry = ModelEntry> {
+	get(id: string, options?: GetOptions<TEntry>): Promise<TEntry["table"]["$response"] | null>;
+	list(options?: ListOptions<TEntry>): Promise<{
+		data: TEntry["table"]["$response"][];
 		total: number;
 	}>;
-	create(data: Record<string, unknown>): Promise<Record<string, unknown>>;
-	update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
-	delete(id: string): Promise<Record<string, unknown> | null>;
+	create(data: TEntry["table"]["$create_input"]): Promise<TEntry["table"]["$response"]>;
+	update(id: string, data: TEntry["table"]["$update_input"]): Promise<TEntry["table"]["$response"]>;
+	delete(id: string): Promise<TEntry["table"]["$response"] | null>;
 }
 interface SqliteAdapterOptions<T extends ColumnRecord> {
 	/** The table schema definition */

package/dist/sqlite/index.js

@@ -2,7 +2,7 @@ import {
   BaseSqlAdapter,
   generateCreateTableSql,
   generateIndexSql
-} from "../shared/chunk-pkv8w501.js";
+} from "../shared/chunk-ed82s3sa.js";
 import {
   __commonJS,
   __require

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/db",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "type": "module",
   "license": "MIT",
   "description": "Database layer for Vertz — typed queries, migrations, codegen",
@@ -81,8 +81,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@vertz/errors": "^0.2.13",
-    "@vertz/schema": "^0.2.13",
+    "@vertz/errors": "^0.2.15",
+    "@vertz/schema": "^0.2.15",
     "@paralleldrive/cuid2": "^3.3.0",
     "nanoid": "^5.1.5",
     "uuid": "^13.0.0"