@shyk/kadak 0.1.0 → 0.1.5

package/dist/index.mjs

@@ -1,60 +1,34 @@
-import { z } from "zod";
+import { ZodError, z } from "zod";
 import postgres from "postgres";
+import fs from "node:fs/promises";
+import path from "node:path";
 //#region src/schema.ts
-/** Converts camelCase to snake_case for PostgreSQL column naming */
 function camelToSnake(str) {
 	return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
-/**
-* A column definition carrying runtime metadata AND compile-time types.
-*
-* Three generics flow through the entire ORM:
-* - TType: JS type (string, number, boolean, Date)
-* - TNullable: whether NULL is allowed (adds `| null`)
-* - THasDefault: whether INSERT can omit this (adds `?`)
-*
-* Every modifier returns a NEW Column — immutable builder.
-*/
 var Column = class Column {
 	constructor(config) {
 		this._config = Object.freeze({ ...config });
 	}
-	/** NOT NULL — already the default. Exists for explicit readability. */
-	required() {
-		return new Column({
-			...this._config,
-			nullable: false
-		});
-	}
-	/** Allow NULL — column type becomes TType | null in TypeScript */
 	optional() {
 		return new Column({
 			...this._config,
-			nullable: true
+			nullable: true,
+			isOptional: true
 		});
 	}
-	/** Add UNIQUE constraint */
 	unique() {
 		return new Column({
 			...this._config,
 			isUnique: true
 		});
 	}
-	/** Mark as PRIMARY KEY */
 	primaryKey() {
 		return new Column({
 			...this._config,
 			isPrimaryKey: true
 		});
 	}
-	/**
-	* Set default value — makes field optional in INSERT.
-	*
-	* Named shortcuts are resolved per column type to avoid ambiguity:
-	* - 'now' on TIMESTAMPTZ → SQL DEFAULT now()
-	* - 'uuid' on UUID → SQL DEFAULT gen_random_uuid()
-	* On other types, these strings are treated as literal values.
-	*/
 	default(value) {
 		const shortcuts = {
 			TIMESTAMPTZ: { now: "now()" },
@@ -68,21 +42,18 @@ var Column = class Column {
 			defaultSql: sqlExpr ?? this._config.defaultSql
 		});
 	}
-	/** Min constraint — string length for text, numeric value for numbers */
 	min(n) {
 		return new Column({
 			...this._config,
 			min: n
 		});
 	}
-	/** Max constraint — string length for text, numeric value for numbers */
 	max(n) {
 		return new Column({
 			...this._config,
 			max: n
 		});
 	}
-	/** Auto-update on every UPDATE query — designed for updatedAt columns */
 	autoUpdate() {
 		return new Column({
 			...this._config,
@@ -90,12 +61,6 @@ var Column = class Column {
 			hasDefault: true
 		});
 	}
-	/**
-	* Soft delete marker. When set on a column:
-	* - findMany() auto-adds WHERE column IS NULL
-	* - delete() sets this column to now() instead of DELETE
-	* - findMany({ withDeleted: true }) bypasses the filter
-	*/
 	softDelete() {
 		return new Column({
 			...this._config,
@@ -105,7 +70,6 @@ var Column = class Column {
 		});
 	}
 };
-/** Base config with required-by-default semantics */
 function baseConfig(pgType) {
 	return {
 		pgType,
@@ -115,20 +79,10 @@ function baseConfig(pgType) {
 		isUnique: false,
 		isGenerated: false,
 		autoUpdate: false,
-		softDelete: false
+		softDelete: false,
+		isOptional: false
 	};
 }
-/**
-* Column factory namespace. Every column definition starts here.
-*
-* ```ts
-* const users = table('users', {
-*   id: kadak.id(),
-*   name: kadak.text().required(),
-*   email: kadak.email().unique(),
-* })
-* ```
-*/
 const kadak = {
 	id: () => new Column({
 		...baseConfig("INTEGER"),
@@ -168,10 +122,6 @@ const kadak = {
 		zodSchema: schema
 	})
 };
-/**
-* A table definition. Created via the `table()` function.
-* Holds column metadata and generates typed Zod validators.
-*/
 var Table = class {
 	constructor(name, columns, options) {
 		this._name = name;
@@ -180,35 +130,29 @@ var Table = class {
 		this._columnMap = {};
 		for (const key of Object.keys(columns)) this._columnMap[key] = camelToSnake(key);
 	}
-	/** Alias for insertValidator() — the most common use case (validating user input) */
 	validator() {
 		return this.insertValidator();
 	}
-	/** Validates data for INSERT — generated/defaulted fields are optional */
 	insertValidator() {
 		return z.object(this._buildShape("insert"));
 	}
-	/** Validates data for SELECT — all columns present, nullability applied */
 	selectValidator() {
 		return z.object(this._buildShape("select"));
 	}
-	/** Validates data for UPDATE — everything optional (partial update) */
 	updateValidator() {
 		return z.object(this._buildShape("update"));
 	}
-	/** @internal Builds Zod shape for a given operation mode */
 	_buildShape(mode) {
 		const shape = {};
 		for (const [key, col] of Object.entries(this._columns)) {
 			let zodType = this._baseZodType(col._config);
 			if (col._config.nullable) zodType = zodType.nullable();
-			if (mode === "insert" && (col._config.hasDefault || col._config.isGenerated)) zodType = zodType.optional();
+			if (mode === "insert" && (col._config.hasDefault || col._config.isGenerated || col._config.isOptional)) zodType = zodType.optional();
 			else if (mode === "update") zodType = zodType.optional();
 			shape[key] = zodType;
 		}
 		return shape;
 	}
-	/** @internal Creates the base Zod type for a column, without nullable/optional */
 	_baseZodType(config) {
 		if (config.pgType === "JSONB" && config.zodSchema) return config.zodSchema;
 		switch (config.pgType) {
@@ -240,25 +184,66 @@ var Table = class {
 		}
 	}
 };
-/**
-* Define a table. This is the primary API for declaring your database schema.
-*
-* ```ts
-* export const users = table('users', {
-*   id: kadak.id(),
-*   name: kadak.text().required(),
-*   email: kadak.email().unique(),
-*   age: kadak.int().optional(),
-*   createdAt: kadak.timestamp().default('now'),
-* })
-* ```
-*/
+function fromShorthand(key, definition) {
+	const optional = definition.endsWith("?");
+	const base = optional ? definition.slice(0, -1) : definition;
+	let column;
+	switch (base) {
+		case "id":
+			column = kadak.id();
+			break;
+		case "uuidId":
+			column = kadak.uuidId();
+			break;
+		case "serialId":
+			column = kadak.serialId();
+			break;
+		case "text":
+			column = kadak.text();
+			break;
+		case "int":
+			column = kadak.int();
+			break;
+		case "number":
+			column = kadak.number();
+			break;
+		case "float":
+			column = kadak.float();
+			break;
+		case "decimal":
+			column = kadak.decimal();
+			break;
+		case "boolean":
+			column = kadak.boolean();
+			break;
+		case "timestamp":
+			column = kadak.timestamp();
+			break;
+		case "email":
+			column = kadak.email().unique();
+			break;
+		case "uuid":
+			column = kadak.uuid();
+			break;
+		default: throw new Error(`Unsupported shorthand '${definition}' for column '${key}'`);
+	}
+	return optional ? column.optional() : column;
+}
+function normalizeColumns(columns, options) {
+	const normalized = {};
+	for (const [key, value] of Object.entries(columns)) normalized[key] = typeof value === "string" ? fromShorthand(key, value) : value;
+	if (options?.timestamps) {
+		if (!("createdAt" in normalized)) normalized.createdAt = kadak.timestamp().default("now");
+		if (!("updatedAt" in normalized)) normalized.updatedAt = kadak.timestamp().default("now").autoUpdate();
+	}
+	if (options?.softDelete && !("deletedAt" in normalized)) normalized.deletedAt = kadak.timestamp().softDelete();
+	return normalized;
+}
 function table(name, columns, options) {
-	return new Table(name, columns, options);
+	return new Table(name, normalizeColumns(columns, options), options);
 }
 //#endregion
 //#region src/error.ts
-/** Maps PostgreSQL error codes to human-readable KadakORM codes + hints */
 const PG_ERROR_MAP = {
 	"23505": {
 		code: "UNIQUE_VIOLATION",
@@ -266,7 +251,7 @@ const PG_ERROR_MAP = {
 	},
 	"23502": {
 		code: "NOT_NULL_VIOLATION",
-		hint: "A required column is missing. Add .optional() if it should be nullable."
+		hint: "A required column is missing. Add ? in schema if it should be optional."
 	},
 	"23503": {
 		code: "FOREIGN_KEY_VIOLATION",
@@ -301,10 +286,6 @@ const PG_ERROR_MAP = {
 		hint: "Query took too long. Consider adding an index or simplifying the query."
 	}
 };
-/**
-* The one error class users ever see from KadakORM.
-* Always includes: what went wrong, which table/column, and how to fix it.
-*/
 var KadakError = class extends Error {
 	constructor(opts) {
 		super(opts.message);
@@ -317,7 +298,27 @@ var KadakError = class extends Error {
 		this.originalError = opts.originalError;
 	}
 };
-/** Wraps any postgres.js error into a KadakError with context */
+function fromValidationError(error, tableName) {
+	if (error instanceof ZodError) {
+		const issue = error.issues[0];
+		const path = issue?.path.join(".") || "payload";
+		return new KadakError({
+			code: "VALIDATION_ERROR",
+			message: `Missing or invalid field: ${path}`,
+			hint: `Fix: ${issue?.message ?? "Check the value against your schema."}`,
+			table: tableName,
+			column: path,
+			originalError: error
+		});
+	}
+	return new KadakError({
+		code: "VALIDATION_ERROR",
+		message: "Invalid input for this query.",
+		hint: "Check the payload against your schema validators.",
+		table: tableName,
+		originalError: error
+	});
+}
 function wrapPgError(err, tableName) {
 	const pgErr = err;
 	const mapped = PG_ERROR_MAP[pgErr?.code ?? ""] ?? {
@@ -328,147 +329,553 @@ function wrapPgError(err, tableName) {
 	const column = pgErr?.column_name;
 	const constraint = pgErr?.constraint_name;
 	let message = pgErr?.message ?? "Unknown database error";
-	if (mapped.code === "NOT_NULL_VIOLATION" && column) message = `Column '${column}' in table '${table}' cannot be null. Did you forget to pass '${column}'?`;
-	else if (mapped.code === "UNIQUE_VIOLATION" && constraint) message = `Duplicate value violates constraint '${constraint}' on table '${table}'.`;
-	else if (mapped.code === "TABLE_NOT_FOUND") message = `Table '${table ?? "unknown"}' does not exist. Have you run your migrations?`;
+	if (mapped.code === "NOT_NULL_VIOLATION" && column) message = `Missing required field: ${column}`;
+	else if (mapped.code === "UNIQUE_VIOLATION") message = constraint ? `A record already exists with this value (violates '${constraint}')` : "A duplicate record already exists.";
+	else if (mapped.code === "TABLE_NOT_FOUND") message = `Table '${table ?? "unknown"}' does not exist.`;
 	return new KadakError({
 		code: mapped.code,
 		message,
 		hint: mapped.hint,
 		table,
-		column,
+		column: column || (constraint?.includes(table || "") ? constraint.replace(table + "_", "").replace("_key", "") : void 0),
 		constraint,
 		originalError: err
 	});
 }
 //#endregion
-//#region src/query.ts
-/**
-* Query client for a single table. Created by `connect()` — never instantiated directly.
-* Provides findMany, findFirst, insert, update, delete with full type safety.
-*/
+//#region src/query/analyzer.ts
+function collectFields(condition) {
+	if (!condition) return [];
+	if (condition.isInternal) return [];
+	switch (condition.type) {
+		case "eq":
+		case "isNull":
+		case "in":
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte": return [condition.field];
+		case "and":
+		case "or": return condition.conditions.flatMap((entry) => collectFields(entry));
+	}
+}
+function isIndexedField(table, dbField) {
+	const jsField = Object.entries(table._columnMap).find(([, value]) => value === dbField)?.[0];
+	if (!jsField) return false;
+	const column = table._columns[jsField];
+	if (!column) return false;
+	return column._config.isPrimaryKey || column._config.isUnique;
+}
+function hasUserFilter(condition) {
+	if (!condition) return false;
+	if (condition.isInternal) return false;
+	if (condition.type === "and" || condition.type === "or") return condition.conditions.some((c) => hasUserFilter(c));
+	return true;
+}
+function analyzeAst(ast, table, config) {
+	const warnings = [];
+	const where = ast.type === "insert" ? void 0 : ast.where;
+	const hasFilter = hasUserFilter(where);
+	if (ast.type === "select" && !hasFilter) warnings.push({
+		code: "full_scan",
+		message: `Query on "${ast.table}" has no filter. This may cause a full table scan.`,
+		suggestion: "Add a filter like { id: 1 } or another narrowing field."
+	});
+	if (ast.type === "select" && ast.limit === void 0) warnings.push({
+		code: "missing_limit",
+		message: `Query on "${ast.table}" has no limit. This may load large datasets.`,
+		suggestion: "Add $limit: 100"
+	});
+	if (ast.type === "select" && ast.limit !== void 0 && ast.limit > config.largeLimitThreshold) warnings.push({
+		code: "large_limit",
+		message: `Query on "${ast.table}" uses a large limit (${ast.limit}).`,
+		suggestion: "Reduce the limit or paginate in smaller batches."
+	});
+	if ((ast.type === "update" || ast.type === "delete") && !hasFilter) warnings.push({
+		code: "unsafe_mutation",
+		message: `${ast.type.toUpperCase()} on "${ast.table}" has no filter and will affect every row.`,
+		suggestion: `Add a filter to ${ast.type} only the rows you intend to change.`
+	});
+	const nonIndexedFields = Array.from(new Set(collectFields(where))).filter((field) => !isIndexedField(table, field));
+	if (nonIndexedFields.length > 0 && (ast.type === "select" || ast.type === "update" || ast.type === "delete")) warnings.push({
+		code: "index_hint",
+		message: `Query on "${ast.table}" filters on non-indexed fields: ${nonIndexedFields.join(", ")}.`,
+		suggestion: "Consider adding an index if this query is common."
+	});
+	return warnings;
+}
+function analyzeExecutionWithConfig(ast, metrics, config) {
+	const warnings = [];
+	if (metrics.durationMs >= config.slowQueryMs) warnings.push({
+		code: "slow_query",
+		message: `Query on "${ast.table}" took ${metrics.durationMs}ms.`,
+		suggestion: "Check filters, indexes, or reduce the result size."
+	});
+	if (metrics.rows >= config.largeResultRows) warnings.push({
+		code: "large_result",
+		message: `Query on "${ast.table}" returned ${metrics.rows} rows.`,
+		suggestion: "Add a stricter filter or a smaller $limit."
+	});
+	return warnings;
+}
+function repeatedQueryWarning(table, count) {
+	return {
+		code: "repeated_query",
+		message: `Query pattern on "${table}" repeated ${count} times in this process.`,
+		suggestion: "Consider caching, batching, or moving this pattern behind a single query."
+	};
+}
+function formatWarning(warning) {
+	const lines = ["Kadak Warning:", warning.message];
+	if (warning.suggestion) lines.push("", "Suggestion:", `-> ${warning.suggestion}`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/query/ast.ts
+function andConditions(conditions) {
+	const compact = conditions.filter((condition) => Boolean(condition));
+	if (compact.length === 0) return void 0;
+	if (compact.length === 1) return compact[0];
+	return {
+		type: "and",
+		conditions: compact
+	};
+}
+function orConditions(conditions) {
+	const compact = conditions.filter((condition) => Boolean(condition));
+	if (compact.length === 0) return void 0;
+	if (compact.length === 1) return compact[0];
+	return {
+		type: "or",
+		conditions: compact
+	};
+}
+//#endregion
+//#region src/query/normalize.ts
+function isOperatorObject(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value) || value instanceof Date) return false;
+	return Object.keys(value).some((key) => key.startsWith("$"));
+}
+function normalizeFieldValue(field, value) {
+	if (value === void 0) return void 0;
+	if (value === null) return {
+		type: "isNull",
+		field
+	};
+	if (Array.isArray(value)) return {
+		type: "in",
+		field,
+		values: value
+	};
+	if (!isOperatorObject(value)) return {
+		type: "eq",
+		field,
+		value
+	};
+	const operatorValue = value;
+	return andConditions([
+		operatorValue.$in ? {
+			type: "in",
+			field,
+			values: operatorValue.$in
+		} : void 0,
+		operatorValue.$gt !== void 0 ? {
+			type: "gt",
+			field,
+			value: operatorValue.$gt
+		} : void 0,
+		operatorValue.$gte !== void 0 ? {
+			type: "gte",
+			field,
+			value: operatorValue.$gte
+		} : void 0,
+		operatorValue.$lt !== void 0 ? {
+			type: "lt",
+			field,
+			value: operatorValue.$lt
+		} : void 0,
+		operatorValue.$lte !== void 0 ? {
+			type: "lte",
+			field,
+			value: operatorValue.$lte
+		} : void 0
+	]);
+}
+function normalizeWhere(table, input) {
+	if (!input) return void 0;
+	const { $or, $limit, $order, ...plainFields } = input;
+	const conditions = [];
+	for (const [key, value] of Object.entries(plainFields)) {
+		const field = table._columnMap[key] ?? key;
+		conditions.push(normalizeFieldValue(field, value));
+	}
+	if (Array.isArray($or)) conditions.push(orConditions($or.map((entry) => normalizeWhere(table, entry))));
+	return andConditions(conditions);
+}
+function normalizeOrder(table, order) {
+	return Object.entries(order ?? {}).map(([key, direction]) => ({
+		field: table._columnMap[key] ?? key,
+		direction: direction === "desc" ? "desc" : "asc"
+	}));
+}
+function normalizeSelect(table, query, options) {
+	const softDeleteCondition = options?.includeSoftDeleted ? void 0 : normalizeSoftDelete(table);
+	const explicitLimit = typeof query?.$limit === "number" ? query.$limit : void 0;
+	return {
+		type: "select",
+		table: table._name,
+		where: andConditions([normalizeWhere(table, query), softDeleteCondition]),
+		order: normalizeOrder(table, query?.$order),
+		limit: explicitLimit ?? options?.defaultLimit
+	};
+}
+function normalizeUpdate(table, filter, data) {
+	const entries = Object.entries(data).filter(([, value]) => value !== void 0).map(([key, value]) => ({
+		field: table._columnMap[key] ?? key,
+		value
+	}));
+	return {
+		type: "update",
+		table: table._name,
+		where: normalizeWhere(table, filter),
+		data: entries
+	};
+}
+function normalizeDelete(table, filter) {
+	return {
+		type: "delete",
+		table: table._name,
+		where: normalizeWhere(table, filter)
+	};
+}
+function normalizeInsert(table, rows) {
+	const jsColumns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
+	return {
+		type: "insert",
+		table: table._name,
+		columns: jsColumns.map((key) => table._columnMap[key] ?? key),
+		rows: rows.map((row) => jsColumns.map((columnKey) => columnKey in row ? {
+			kind: "value",
+			value: row[columnKey]
+		} : { kind: "default" }))
+	};
+}
+function normalizeSoftDelete(table) {
+	for (const [key, column] of Object.entries(table._columns)) if (column._config.softDelete) return {
+		type: "isNull",
+		field: table._columnMap[key],
+		isInternal: true
+	};
+}
+//#endregion
+//#region src/query/sql.ts
+function quoteIdentifier(value) {
+	return `"${value.replace(/"/g, "\"\"")}"`;
+}
+function buildCondition(condition, params) {
+	if (!condition) return "";
+	switch (condition.type) {
+		case "eq":
+			params.push(condition.value);
+			return `${quoteIdentifier(condition.field)} = $${params.length}`;
+		case "isNull": return `${quoteIdentifier(condition.field)} IS NULL`;
+		case "in":
+			if (condition.values.length === 0) return "FALSE";
+			return `${quoteIdentifier(condition.field)} IN (${condition.values.map((value) => {
+				params.push(value);
+				return `$${params.length}`;
+			}).join(", ")})`;
+		case "gt":
+			params.push(condition.value);
+			return `${quoteIdentifier(condition.field)} > $${params.length}`;
+		case "gte":
+			params.push(condition.value);
+			return `${quoteIdentifier(condition.field)} >= $${params.length}`;
+		case "lt":
+			params.push(condition.value);
+			return `${quoteIdentifier(condition.field)} < $${params.length}`;
+		case "lte":
+			params.push(condition.value);
+			return `${quoteIdentifier(condition.field)} <= $${params.length}`;
+		case "and": return `(${condition.conditions.map((entry) => buildCondition(entry, params)).join(" AND ")})`;
+		case "or": return `(${condition.conditions.map((entry) => buildCondition(entry, params)).join(" OR ")})`;
+	}
+}
+function buildWhere(where, params) {
+	const sql = buildCondition(where, params);
+	return sql ? ` WHERE ${sql}` : "";
+}
+function buildSelect(ast) {
+	const params = [];
+	const where = buildWhere(ast.where, params);
+	const order = ast.order.length > 0 ? ` ORDER BY ${ast.order.map((entry) => `${quoteIdentifier(entry.field)} ${entry.direction.toUpperCase()}`).join(", ")}` : "";
+	const limit = ast.limit !== void 0 ? ` LIMIT ${ast.limit}` : "";
+	return {
+		text: `SELECT * FROM ${quoteIdentifier(ast.table)}${where}${order}${limit}`,
+		params
+	};
+}
+function buildUpdate(ast) {
+	const params = [];
+	const setSql = ast.data.map((entry) => {
+		params.push(entry.value);
+		return `${quoteIdentifier(entry.field)} = $${params.length}`;
+	}).join(", ");
+	const where = ast.where ? ` WHERE ${buildCondition(ast.where, params)}` : "";
+	return {
+		text: `UPDATE ${quoteIdentifier(ast.table)} SET ${setSql}${where} RETURNING *`,
+		params
+	};
+}
+function buildDelete(ast) {
+	const params = [];
+	const where = buildWhere(ast.where, params);
+	return {
+		text: `DELETE FROM ${quoteIdentifier(ast.table)}${where} RETURNING *`,
+		params
+	};
+}
+function buildInsert(ast) {
+	if (ast.columns.length === 0) return {
+		text: `INSERT INTO ${quoteIdentifier(ast.table)} DEFAULT VALUES RETURNING *`,
+		params: []
+	};
+	const params = [];
+	const values = ast.rows.map((row) => `(${row.map((cell) => {
+		if (cell.kind === "default") return "DEFAULT";
+		params.push(cell.value);
+		return `$${params.length}`;
+	}).join(", ")})`).join(", ");
+	return {
+		text: `INSERT INTO ${quoteIdentifier(ast.table)} (${ast.columns.map(quoteIdentifier).join(", ")}) VALUES ${values} RETURNING *`,
+		params
+	};
+}
+function buildSql(ast) {
+	switch (ast.type) {
+		case "select": return buildSelect(ast);
+		case "update": return buildUpdate(ast);
+		case "delete": return buildDelete(ast);
+		case "insert": return buildInsert(ast);
+	}
+}
+//#endregion
+//#region src/query/index.ts
 var TableClient = class {
-	constructor(sql, table) {
+	constructor(sql, table, config = {}) {
 		this._sql = sql;
+		this._readSql = config.readSql ?? [];
 		this._table = table;
+		this._debug = config.debug ?? false;
+		this._warn = config.warn ?? ((message) => console.warn(message));
+		this._onQuery = config.onQuery;
+		this._warningMode = config.warningMode ?? "relaxed";
+		this._retryAttempts = Math.max(0, config.retryAttempts ?? 0);
+		this._retryDelayMs = Math.max(0, config.retryDelayMs ?? 200);
+		this._retryOnCodes = new Set(config.retryOnCodes ?? [
+			"08006",
+			"08001",
+			"57P01",
+			"40001",
+			"40P01"
+		]);
+		this._retryWrites = config.retryWrites ?? false;
+		this._defaultLimit = config.defaultLimit;
+		this._validateResults = config.validateResults ?? false;
+		this._analyzerConfig = {
+			slowQueryMs: config.slowQueryMs ?? 250,
+			largeResultRows: config.largeResultRows ?? 1e3,
+			largeLimitThreshold: config.largeLimitThreshold ?? 1e3
+		};
+		this._repeatedQueryThreshold = config.repeatedQueryThreshold ?? 25;
+		this._queryFingerprintCount = /* @__PURE__ */ new Map();
+		this._selectValidator = table.selectValidator();
+		this._explainAnalyze = config.explainAnalyze ?? false;
+		this._explainThresholdMs = config.explainThresholdMs ?? 300;
+		this._metrics = config.metrics;
+		this._replicaIndex = 0;
 		this._reverseMap = {};
 		for (const [camel, snake] of Object.entries(table._columnMap)) this._reverseMap[snake] = camel;
 	}
-	async findMany(options) {
-		try {
-			const sql = this._sql;
-			const t = this._table;
-			const cols = options?.select ? Object.keys(options.select).filter((k) => options.select[k]).map((k) => t._columnMap[k] ?? k) : Object.values(t._columnMap);
-			const whereFragment = this._buildWhere(options?.where, options?.withDeleted);
-			const orderFragment = this._buildOrderBy(options?.orderBy);
-			const limitFragment = options?.limit !== void 0 ? sql`LIMIT ${options.limit}` : sql``;
-			const offsetFragment = options?.offset !== void 0 ? sql`OFFSET ${options.offset}` : sql``;
-			return (await sql`
-        SELECT ${sql(cols)} FROM ${sql(t._name)}
-        ${whereFragment} ${orderFragment} ${limitFragment} ${offsetFragment}
-      `).map((row) => this._toJs(row));
-		} catch (err) {
-			throw wrapPgError(err, this._table._name);
-		}
+	async findMany(query) {
+		const ast = normalizeSelect(this._table, query, { defaultLimit: this._defaultLimit });
+		return this._executeAst(ast);
 	}
-	async findFirst(options) {
+	async findFirst(query) {
 		return (await this.findMany({
-			...options,
-			limit: 1
+			...query ?? {},
+			$limit: 1
 		}))[0] ?? null;
 	}
 	async insert(data) {
+		const isBulk = Array.isArray(data);
+		const validator = this._table.insertValidator();
+		const rawRows = (isBulk ? data : [data]).map((row) => this._applyInsertAutomation(this._parseOrThrow(validator, row)));
+		const ast = normalizeInsert(this._table, rawRows);
+		const rows = await this._executeAst(ast);
+		return isBulk ? rows : rows[0];
+	}
+	async update(filter, data) {
+		const parsed = this._applyUpdateAutomation(this._parseOrThrow(this._table.updateValidator(), data));
+		const ast = normalizeUpdate(this._table, filter, parsed);
+		if (ast.data.length === 0) throw new KadakError({
+			code: "VALIDATION_ERROR",
+			message: `Nothing to update in table '${this._table._name}'.`,
+			hint: "Pass at least one defined field in the update payload.",
+			table: this._table._name,
+			originalError: null
+		});
+		return this._executeAst(ast);
+	}
+	async delete(filter) {
+		const softDeleteKey = this._getSoftDeleteKey();
+		if (softDeleteKey) return this.update(filter, { [softDeleteKey]: /* @__PURE__ */ new Date() });
+		return this.hardDelete(filter);
+	}
+	async hardDelete(filter) {
+		const ast = normalizeDelete(this._table, filter);
+		return this._executeAst(ast);
+	}
+	async _executeAst(ast) {
+		const statement = buildSql(ast);
+		this._registerQueryFingerprint(ast, statement.text);
+		const astWarnings = analyzeAst(ast, this._table, this._analyzerConfig);
+		this._handleWarnings(astWarnings, ast);
+		const startedAt = Date.now();
 		try {
-			const sql = this._sql;
-			const t = this._table;
-			const isBulk = Array.isArray(data);
-			const snakeItems = (isBulk ? data : [data]).map((item) => this._toDb(item));
-			const cols = Object.keys(snakeItems[0]);
-			const result = (await sql`
-        INSERT INTO ${sql(t._name)} ${sql(snakeItems, ...cols)} RETURNING *
-      `).map((row) => this._toJs(row));
-			return isBulk ? result : result[0];
-		} catch (err) {
-			throw wrapPgError(err, this._table._name);
+			const rows = await this._executeWithRetry(ast, () => this._pickSqlClient(ast).unsafe(statement.text, statement.params));
+			const durationMs = Date.now() - startedAt;
+			const executionWarnings = analyzeExecutionWithConfig(ast, {
+				durationMs,
+				rows: rows.length
+			}, this._analyzerConfig);
+			this._handleWarnings(executionWarnings, ast);
+			if (this._explainAnalyze && ast.type === "select" && durationMs >= this._explainThresholdMs) {
+				const explainWarnings = await this._explainWarnings(statement.text, statement.params, ast.table);
+				this._handleWarnings(explainWarnings, ast);
+			}
+			if (this._debug) this._logDebug(ast.type, statement.text, durationMs, rows.length);
+			this._recordTelemetry({
+				table: ast.table,
+				operation: ast.type,
+				sql: statement.text,
+				durationMs,
+				rows: rows.length,
+				warned: astWarnings.length + executionWarnings.length > 0,
+				warningCount: astWarnings.length + executionWarnings.length
+			});
+			return rows.map((row) => this._parseResultOrThrow(this._toJs(row)));
+		} catch (error) {
+			throw wrapPgError(error, this._table._name);
 		}
 	}
-	async update(options) {
+	_pickSqlClient(ast) {
+		if (ast.type !== "select") return this._sql;
+		if (this._readSql.length === 0) return this._sql;
+		const client = this._readSql[this._replicaIndex % this._readSql.length];
+		this._replicaIndex += 1;
+		return client;
+	}
+	async _explainWarnings(sqlText, params, table) {
 		try {
-			const sql = this._sql;
-			const t = this._table;
-			const snakeData = {};
-			for (const [key, value] of Object.entries(options.data)) if (value !== void 0) snakeData[t._columnMap[key] ?? key] = value;
-			for (const [key, col] of Object.entries(t._columns)) if (col._config.autoUpdate) snakeData[t._columnMap[key]] = /* @__PURE__ */ new Date();
-			const whereFragment = this._buildWhere(options.where, false);
-			return (await sql`
-        UPDATE ${sql(t._name)} SET ${sql(snakeData)} ${whereFragment} RETURNING *
-      `).map((row) => this._toJs(row));
-		} catch (err) {
-			throw wrapPgError(err, this._table._name);
+			const plan = (await this._sql.unsafe(`EXPLAIN (ANALYZE, FORMAT JSON) ${sqlText}`, params))?.[0]?.["QUERY PLAN"]?.[0]?.Plan;
+			if (!plan) return [];
+			const warnings = [];
+			if (plan["Node Type"] === "Seq Scan") warnings.push({
+				code: "index_hint",
+				message: `EXPLAIN on "${table}" shows a sequential scan.`,
+				suggestion: "Consider adding an index for frequent filter columns."
+			});
+			return warnings;
+		} catch {
+			return [];
 		}
 	}
-	async delete(options) {
-		const softDeleteEntry = Object.entries(this._table._columns).find(([_, col]) => col._config.softDelete);
-		if (softDeleteEntry) {
-			const [key] = softDeleteEntry;
-			this._table._columnMap[key];
-			return this.update({
-				where: options.where,
-				data: { [key]: /* @__PURE__ */ new Date() }
+	async _executeWithRetry(ast, fn) {
+		let attempt = 0;
+		while (true) try {
+			return await fn();
+		} catch (error) {
+			if (!this._shouldRetry(ast, error, attempt)) throw error;
+			attempt += 1;
+			await this._sleep(this._retryDelayMs * attempt);
+		}
+	}
+	_shouldRetry(ast, error, attempt) {
+		if (attempt >= this._retryAttempts) return false;
+		if (ast.type !== "select" && !this._retryWrites) return false;
+		const code = error?.code;
+		return Boolean(code && this._retryOnCodes.has(code));
+	}
+	_sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+	_registerQueryFingerprint(ast, sqlText) {
+		const key = `${ast.type}:${sqlText}`;
+		const count = (this._queryFingerprintCount.get(key) ?? 0) + 1;
+		this._queryFingerprintCount.set(key, count);
+		if (count === this._repeatedQueryThreshold) this._handleWarnings([repeatedQueryWarning(ast.table, count)], ast);
+	}
+	_handleWarnings(warnings, ast) {
+		if (this._warningMode === "silent") return;
+		for (const warning of warnings) {
+			const message = formatWarning(warning);
+			if (this._warningMode === "strict") throw new KadakError({
+				code: "QUERY_WARNING",
+				message,
+				hint: `Fix the warning or switch warnings mode from 'strict'.`,
+				table: ast.table,
+				originalError: warning
 			});
+			this._warn(message);
 		}
-		return this.hardDelete(options);
 	}
-	/** Always performs a real DELETE — bypasses soft delete */
-	async hardDelete(options) {
-		try {
-			const sql = this._sql;
-			const whereFragment = this._buildWhere(options.where, true);
-			return (await sql`
-        DELETE FROM ${sql(this._table._name)} ${whereFragment} RETURNING *
-      `).map((row) => this._toJs(row));
-		} catch (err) {
-			throw wrapPgError(err, this._table._name);
+	_applyInsertAutomation(data) {
+		const next = { ...data };
+		for (const [key, column] of Object.entries(this._table._columns)) {
+			const config = column._config;
+			if (next[key] !== void 0) continue;
+			if (config.autoUpdate) next[key] = /* @__PURE__ */ new Date();
+			else if (config.defaultValue !== void 0 && !config.defaultSql) next[key] = config.defaultValue;
 		}
+		return next;
 	}
-	/** Builds a WHERE fragment from a JS object, including soft delete filter */
-	_buildWhere(where, withDeleted) {
-		const sql = this._sql;
-		const conditions = [];
-		if (where) for (const [key, value] of Object.entries(where)) {
-			const col = this._table._columnMap[key] ?? key;
-			if (value === void 0) continue;
-			if (value === null) conditions.push(sql`${sql(col)} IS NULL`);
-			else conditions.push(sql`${sql(col)} = ${value}`);
+	_applyUpdateAutomation(data) {
+		const next = { ...data };
+		for (const [key, column] of Object.entries(this._table._columns)) if (column._config.autoUpdate) next[key] = /* @__PURE__ */ new Date();
+		return next;
+	}
+	_parseOrThrow(validator, data) {
+		try {
+			return validator.parse(data);
+		} catch (error) {
+			throw fromValidationError(error, this._table._name);
 		}
-		if (!withDeleted) {
-			for (const [key, col] of Object.entries(this._table._columns)) if (col._config.softDelete) conditions.push(sql`${sql(this._table._columnMap[key])} IS NULL`);
+	}
+	_parseResultOrThrow(row) {
+		if (!this._validateResults) return row;
+		try {
+			return this._selectValidator.parse(row);
+		} catch (error) {
+			throw fromValidationError(error, this._table._name);
 		}
-		if (conditions.length === 0) return sql``;
-		let combined = conditions[0];
-		for (let i = 1; i < conditions.length; i++) combined = sql`${combined} AND ${conditions[i]}`;
-		return sql`WHERE ${combined}`;
-	}
-	/** Builds an ORDER BY fragment */
-	_buildOrderBy(orderBy) {
-		const sql = this._sql;
-		if (!orderBy) return sql``;
-		const entries = Object.entries(orderBy);
-		if (entries.length === 0) return sql``;
-		const parts = entries.map(([key, dir]) => {
-			return sql`${sql(this._table._columnMap[key] ?? key)} ${dir === "desc" ? sql`DESC` : sql`ASC`}`;
-		});
-		let combined = parts[0];
-		for (let i = 1; i < parts.length; i++) combined = sql`${combined}, ${parts[i]}`;
-		return sql`ORDER BY ${combined}`;
 	}
-	/** Converts a JS object (camelCase) to DB format (snake_case) */
-	_toDb(obj) {
-		const result = {};
-		for (const [key, value] of Object.entries(obj)) if (value !== void 0) result[this._table._columnMap[key] ?? key] = value;
-		return result;
+	_recordTelemetry(event) {
+		this._metrics?.record(event);
+		this._onQuery?.(event);
+	}
+	_getSoftDeleteKey() {
+		for (const [key, column] of Object.entries(this._table._columns)) if (column._config.softDelete) return key;
+	}
+	_logDebug(operation, sqlText, durationMs, rows) {
+		console.log([
+			"[Kadak]",
+			`Query: ${this._table._name}.${operation}`,
+			`SQL: ${sqlText}`,
+			`Time: ${durationMs}ms`,
+			`Rows: ${rows}`
+		].join("\n"));
 	}
-	/** Converts a DB row (snake_case) back to JS format (camelCase) */
 	_toJs(row) {
 		const result = {};
 		for (const [snake, value] of Object.entries(row)) result[this._reverseMap[snake] ?? snake] = value;
@@ -477,40 +884,168 @@ var TableClient = class {
 };
 //#endregion
 //#region src/connect.ts
-/**
-* Connect to PostgreSQL and create a typed database client.
-*
-* ```ts
-* const db = connect('postgresql://user:pass@localhost/mydb', { users, posts })
-* const allUsers = await db.users.findMany()
-* await db.close()
-* ```
-*/
+function buildDatabase(sql, readSql, tables, runtimeConfig, canClose) {
+	const db = {};
+	for (const [key, table] of Object.entries(tables)) db[key] = new TableClient(sql, table, {
+		readSql,
+		debug: runtimeConfig.debug,
+		warn: runtimeConfig.onWarn,
+		onQuery: runtimeConfig.onQuery,
+		warningMode: runtimeConfig.warnings,
+		retryAttempts: runtimeConfig.retryAttempts,
+		retryDelayMs: runtimeConfig.retryDelayMs,
+		retryOnCodes: runtimeConfig.retryOnCodes,
+		retryWrites: runtimeConfig.retryWrites,
+		defaultLimit: runtimeConfig.defaultLimit,
+		validateResults: runtimeConfig.validateResults,
+		slowQueryMs: runtimeConfig.slowQueryMs,
+		largeResultRows: runtimeConfig.largeResultRows,
+		largeLimitThreshold: runtimeConfig.largeLimitThreshold,
+		repeatedQueryThreshold: runtimeConfig.repeatedQueryThreshold,
+		explainAnalyze: runtimeConfig.explainAnalyze,
+		explainThresholdMs: runtimeConfig.explainThresholdMs,
+		metrics: runtimeConfig.metrics
+	});
+	db.close = async () => {
+		if (!canClose) return;
+		await Promise.all([sql.end(), ...readSql.map((replica) => replica.end())]);
+	};
+	db.sql = sql;
+	db.readSql = readSql;
+	db.transaction = async (fn) => {
+		return sql.begin(async (txSql) => {
+			return fn(buildDatabase(txSql, [], tables, runtimeConfig, false));
+		});
+	};
+	return db;
+}
 function connect(config, tables) {
 	const isString = typeof config === "string";
 	const url = isString ? config : config.url;
 	const opts = isString ? {} : config;
 	const isLocal = url.includes("localhost") || url.includes("127.0.0.1");
 	const ssl = opts.ssl ?? (isLocal ? false : "require");
-	const sql = postgres(url, {
+	return buildDatabase(postgres(url, {
 		max: opts.max ?? 10,
 		idle_timeout: 20,
-		connect_timeout: 30,
+		connect_timeout: opts.timeout ?? 30,
 		ssl,
 		max_lifetime: 1800,
 		onnotice: () => {}
-	});
-	const db = {};
-	for (const [key, table] of Object.entries(tables)) {
-		const client = new TableClient(sql, table);
-		if (opts.onError) client._onError = opts.onError;
-		db[key] = client;
+	}), (opts.readReplicas ?? []).map((replicaUrl) => postgres(replicaUrl, {
+		max: opts.max ?? 10,
+		idle_timeout: 20,
+		connect_timeout: opts.timeout ?? 30,
+		ssl,
+		max_lifetime: 1800,
+		onnotice: () => {}
+	})), tables, opts, true);
+}
+//#endregion
+//#region src/migrate.ts
+async function ensureMigrationTable(sql, tableName) {
+	await sql.unsafe(`
+    CREATE TABLE IF NOT EXISTS "${tableName}" (
+      id BIGSERIAL PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    )
+  `);
+}
+async function runMigrations(config) {
+	const dir = config.dir ?? path.resolve(process.cwd(), "migrations");
+	const tableName = config.tableName ?? "kadak_migrations";
+	const sql = postgres(config.url);
+	try {
+		await ensureMigrationTable(sql, tableName);
+		const files = (await fs.readdir(dir).catch(() => [])).filter((entry) => entry.endsWith(".sql")).sort();
+		const rows = await sql.unsafe(`SELECT name FROM "${tableName}"`);
+		const appliedSet = new Set(rows.map((row) => row.name));
+		const applied = [];
+		const skipped = [];
+		for (const file of files) {
+			if (appliedSet.has(file)) {
+				skipped.push(file);
+				continue;
+			}
+			const sqlText = await fs.readFile(path.join(dir, file), "utf8");
+			await sql.begin(async (tx) => {
+				await tx.unsafe(sqlText);
+				await tx.unsafe(`INSERT INTO "${tableName}" (name) VALUES ($1)`, [file]);
+			});
+			applied.push(file);
+		}
+		return {
+			applied,
+			skipped
+		};
+	} finally {
+		await sql.end();
 	}
-	db.close = () => sql.end();
-	db.sql = sql;
-	return db;
 }
+async function createMigration(name, dir = path.resolve(process.cwd(), "migrations")) {
+	const safeName = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+	const fileName = `${(/* @__PURE__ */ new Date()).toISOString().replace(/[-:TZ.]/g, "").slice(0, 14)}_${safeName || "migration"}.sql`;
+	const filePath = path.join(dir, fileName);
+	await fs.mkdir(dir, { recursive: true });
+	await fs.writeFile(filePath, "-- Write your SQL migration here\n");
+	return filePath;
+}
+//#endregion
+//#region src/observability.ts
+var KadakMetrics = class {
+	constructor() {
+		this.totalQueries = 0;
+		this.totalDurationMs = 0;
+		this.warningQueries = 0;
+		this.byOperation = {};
+	}
+	record(event) {
+		this.totalQueries += 1;
+		this.totalDurationMs += event.durationMs;
+		if (event.warned) this.warningQueries += 1;
+		const bucket = this.byOperation[event.operation] ?? {
+			count: 0,
+			totalDurationMs: 0,
+			rows: 0
+		};
+		bucket.count += 1;
+		bucket.totalDurationMs += event.durationMs;
+		bucket.rows += event.rows;
+		this.byOperation[event.operation] = bucket;
+	}
+	snapshot() {
+		return {
+			totalQueries: this.totalQueries,
+			totalDurationMs: this.totalDurationMs,
+			avgDurationMs: this.totalQueries === 0 ? 0 : this.totalDurationMs / this.totalQueries,
+			warningQueries: this.warningQueries,
+			byOperation: { ...this.byOperation }
+		};
+	}
+	exportPrometheus(prefix = "kadak") {
+		const lines = [];
+		lines.push(`# HELP ${prefix}_queries_total Total queries executed`);
+		lines.push(`# TYPE ${prefix}_queries_total counter`);
+		lines.push(`${prefix}_queries_total ${this.totalQueries}`);
+		lines.push(`# HELP ${prefix}_query_duration_ms_total Total query duration in milliseconds`);
+		lines.push(`# TYPE ${prefix}_query_duration_ms_total counter`);
+		lines.push(`${prefix}_query_duration_ms_total ${this.totalDurationMs}`);
+		lines.push(`# HELP ${prefix}_warning_queries_total Queries that emitted at least one warning`);
+		lines.push(`# TYPE ${prefix}_warning_queries_total counter`);
+		lines.push(`${prefix}_warning_queries_total ${this.warningQueries}`);
+		for (const [operation, value] of Object.entries(this.byOperation)) {
+			lines.push(`${prefix}_operation_queries_total{operation="${operation}"} ${value.count}`);
+			lines.push(`${prefix}_operation_duration_ms_total{operation="${operation}"} ${value.totalDurationMs}`);
+			lines.push(`${prefix}_operation_rows_total{operation="${operation}"} ${value.rows}`);
+		}
+		return lines.join("\n");
+	}
+};
+//#endregion
+//#region src/version.ts
+const KADAK_API_VERSION = "1.0.0";
 //#endregion
-export { Column, KadakError, Table, TableClient, camelToSnake, connect, kadak, table, wrapPgError };
+export { Column, KADAK_API_VERSION, KadakError, KadakMetrics, Table, TableClient, camelToSnake, connect, createMigration, kadak, runMigrations, table, wrapPgError };
 
 //# sourceMappingURL=index.mjs.map