@vertz/db 0.2.15 → 0.2.17

package/dist/d1/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>;
@@ -85,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[];
@@ -173,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 D1DatabaseBinding {
 	prepare(sql: string): D1PreparedStatement;

package/dist/d1/index.js

@@ -1,7 +1,7 @@
 import {
   createD1Adapter,
   createD1Driver
-} from "../shared/chunk-ndxe1h28.js";
+} from "../shared/chunk-tnaf4hbj.js";
 export {
   createD1Driver,
   createD1Adapter