@shyk/kadak 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shyam Choudhary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# Kadak ☕️
+
+**The strongest TypeScript ORM for PostgreSQL. Period.**
+
+Kadak (pronounced *Ka-dak*) is built for developers who find Drizzle too verbose and Prisma too heavy. It's a thin, type-safe layer over PostgreSQL that prioritizes **Developer Experience (DX)** above everything else.
+
+[kadak.shyk.in](https://kadak.shyk.in) | [Documentation](https://kadak.shyk.in/docs) | [npm](https://www.npmjs.com/package/kadak)
+
+---
+
+## Why Kadak?
+
+Drizzle is great, but it has friction. Drizzle makes you repeat yourself (`'id', serial('id')`), forces you to think about nullable-by-default (silently causing bugs), and leaves you figuring out Zod validation yourself.
+
+**Kadak solves this.**
+
+*   **Required by Default**: Columns are NOT NULL unless you explicitly say `.optional()`.
+*   **Zero Repetition**: No more writing column names twice.
+*   **Built-in Zod**: Table schemas auto-generate Zod validators for Insert, Update, and Select.
+*   **Modern PostgreSQL**: Defaults to `IDENTITY` columns (modern standard) instead of legacy `SERIAL`.
+*   **Automatic Mapping**: Write `camelCase` in TS, get `snake_case` in PG. No mapping manual effort.
+*   **Soft Deletes & AutoUpdate**: First-class support for `deleted_at` and `updated_at` patterns.
+*   **Lightweight**: Only two runtime dependencies: `postgres.js` and `zod`.
+
+---
+
+## Getting Started
+
+```bash
+pnpm add @shyk/kadak postgres zod
+```
+
+### 1. Define your Schema
+
+```ts
+import { table, kadak, type Infer } from '@shyk/kadak'
+
+export const users = table('users', {
+  id: kadak.id(),              // IDENTITY Primary Key
+  name: kadak.text().required().max(100),
+  email: kadak.email().unique(),
+  age: kadak.int().optional(),
+  balance: kadak.decimal(),    // Precision safe (returns string)
+  createdAt: kadak.timestamp().default('now'),
+  updatedAt: kadak.timestamp().autoUpdate(),
+  deletedAt: kadak.timestamp().softDelete(),
+})
+
+export type User = Infer<typeof users>
+```
+
+### 2. Connect and Query
+
+```ts
+import { connect } from '@shyk/kadak'
+import { users } from './schema'
+
+const db = connect(process.env.DATABASE_URL!, { users })
+
+// Type-safe queries with automatic snake_case mapping
+const allUsers = await db.users.findMany({
+  where: { isActive: true },
+  orderBy: { createdAt: 'desc' },
+  limit: 10
+})
+
+// Validation included
+const result = users.validator().safeParse(somePayload)
+if (result.success) {
+  await db.users.insert(result.data)
+}
+```
+
+---
+
+## Features
+
+| Feature | Kadak | Drizzle |
+| --- | --- | --- |
+| **Default Context** | Required (Safe) | Nullable (Prone to bugs) |
+| **Column Naming** | Auto `snake_case` | Manual `name('name')` |
+| **Validation** | First-class Zod | Separate packages |
+| **Soft Delete** | Native `.softDelete()` | Manual WHERE clauses |
+| **Primary Keys** | `IDENTITY` (Modern) | `SERIAL` (Legacy) |
+
+---
+
+## License
+
+MIT © [Shyam](https://github.com/shyk)

package/dist/index.cjs

@@ -0,0 +1,548 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let zod = require("zod");
+let postgres = require("postgres");
+postgres = __toESM(postgres);
+//#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
+		});
+	}
+	/** 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()" },
+			UUID: { uuid: "gen_random_uuid()" }
+		}[this._config.pgType] ?? {};
+		const sqlExpr = typeof value === "string" ? shortcuts[value] : void 0;
+		return new Column({
+			...this._config,
+			hasDefault: true,
+			defaultValue: sqlExpr ? void 0 : value,
+			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,
+			autoUpdate: true,
+			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,
+			softDelete: true,
+			nullable: true,
+			hasDefault: true
+		});
+	}
+};
+/** Base config with required-by-default semantics */
+function baseConfig(pgType) {
+	return {
+		pgType,
+		nullable: false,
+		hasDefault: false,
+		isPrimaryKey: false,
+		isUnique: false,
+		isGenerated: false,
+		autoUpdate: false,
+		softDelete: 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"),
+		isPrimaryKey: true,
+		isGenerated: true,
+		hasDefault: true
+	}),
+	uuidId: () => new Column({
+		...baseConfig("UUID"),
+		isPrimaryKey: true,
+		hasDefault: true,
+		defaultSql: "gen_random_uuid()"
+	}),
+	serialId: () => new Column({
+		...baseConfig("SERIAL"),
+		isPrimaryKey: true,
+		isGenerated: true,
+		hasDefault: true
+	}),
+	text: () => new Column(baseConfig("TEXT")),
+	int: () => new Column(baseConfig("INTEGER")),
+	number: () => new Column(baseConfig("INTEGER")),
+	float: () => new Column(baseConfig("FLOAT8")),
+	decimal: () => new Column(baseConfig("NUMERIC")),
+	boolean: () => new Column(baseConfig("BOOLEAN")),
+	timestamp: () => new Column(baseConfig("TIMESTAMPTZ")),
+	email: () => new Column({
+		...baseConfig("TEXT"),
+		zodCheck: "email"
+	}),
+	uuid: () => new Column({
+		...baseConfig("UUID"),
+		zodCheck: "uuid"
+	}),
+	json: (schema) => new Column({
+		...baseConfig("JSONB"),
+		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;
+		this._columns = columns;
+		this._options = options;
+		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 zod.z.object(this._buildShape("insert"));
+	}
+	/** Validates data for SELECT — all columns present, nullability applied */
+	selectValidator() {
+		return zod.z.object(this._buildShape("select"));
+	}
+	/** Validates data for UPDATE — everything optional (partial update) */
+	updateValidator() {
+		return zod.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();
+			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) {
+			case "TEXT": {
+				let s = zod.z.string();
+				if (config.zodCheck === "email") s = s.email();
+				if (config.min !== void 0) s = s.min(config.min);
+				if (config.max !== void 0) s = s.max(config.max);
+				return s;
+			}
+			case "INTEGER": {
+				let n = zod.z.number().int();
+				if (config.min !== void 0) n = n.min(config.min);
+				if (config.max !== void 0) n = n.max(config.max);
+				return n;
+			}
+			case "FLOAT8": {
+				let n = zod.z.number();
+				if (config.min !== void 0) n = n.min(config.min);
+				if (config.max !== void 0) n = n.max(config.max);
+				return n;
+			}
+			case "NUMERIC": return zod.z.string().regex(/^-?\d+(\.\d+)?$/, "Must be a valid decimal number");
+			case "BOOLEAN": return zod.z.boolean();
+			case "TIMESTAMPTZ": return zod.z.coerce.date();
+			case "UUID": return zod.z.string().uuid();
+			case "SERIAL": return zod.z.number().int();
+			default: return zod.z.unknown();
+		}
+	}
+};
+/**
+* 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 table(name, columns, options) {
+	return new Table(name, columns, options);
+}
+//#endregion
+//#region src/error.ts
+/** Maps PostgreSQL error codes to human-readable KadakORM codes + hints */
+const PG_ERROR_MAP = {
+	"23505": {
+		code: "UNIQUE_VIOLATION",
+		hint: "A row with this value already exists. Check your unique columns."
+	},
+	"23502": {
+		code: "NOT_NULL_VIOLATION",
+		hint: "A required column is missing. Add .optional() if it should be nullable."
+	},
+	"23503": {
+		code: "FOREIGN_KEY_VIOLATION",
+		hint: "The referenced row does not exist in the related table."
+	},
+	"42P01": {
+		code: "TABLE_NOT_FOUND",
+		hint: "Did you run migrations? The table does not exist yet."
+	},
+	"42703": {
+		code: "COLUMN_NOT_FOUND",
+		hint: "Check your schema — this column is not in the table."
+	},
+	"08006": {
+		code: "CONNECTION_ERROR",
+		hint: "Cannot reach the database. Check your DATABASE_URL and network."
+	},
+	"08001": {
+		code: "CONNECTION_ERROR",
+		hint: "Connection refused. Is PostgreSQL running?"
+	},
+	"28P01": {
+		code: "AUTH_ERROR",
+		hint: "Wrong username or password in your connection string."
+	},
+	"3D000": {
+		code: "CONNECTION_ERROR",
+		hint: "This database does not exist. Check the database name in your URL."
+	},
+	"57014": {
+		code: "QUERY_TIMEOUT",
+		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);
+		this.name = "KadakError";
+		this.code = opts.code;
+		this.hint = opts.hint;
+		this.table = opts.table;
+		this.column = opts.column;
+		this.constraint = opts.constraint;
+		this.originalError = opts.originalError;
+	}
+};
+/** Wraps any postgres.js error into a KadakError with context */
+function wrapPgError(err, tableName) {
+	const pgErr = err;
+	const mapped = PG_ERROR_MAP[pgErr?.code ?? ""] ?? {
+		code: "UNKNOWN",
+		hint: "An unexpected database error occurred."
+	};
+	const table = pgErr?.table_name ?? 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?`;
+	return new KadakError({
+		code: mapped.code,
+		message,
+		hint: mapped.hint,
+		table,
+		column,
+		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.
+*/
+var TableClient = class {
+	constructor(sql, table) {
+		this._sql = sql;
+		this._table = table;
+		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 findFirst(options) {
+		return (await this.findMany({
+			...options,
+			limit: 1
+		}))[0] ?? null;
+	}
+	async insert(data) {
+		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);
+		}
+	}
+	async update(options) {
+		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);
+		}
+	}
+	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() }
+			});
+		}
+		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);
+		}
+	}
+	/** 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}`);
+		}
+		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`);
+		}
+		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;
+	}
+	/** 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;
+		return result;
+	}
+};
+//#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 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 = (0, postgres.default)(url, {
+		max: opts.max ?? 10,
+		idle_timeout: 20,
+		connect_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;
+	}
+	db.close = () => sql.end();
+	db.sql = sql;
+	return db;
+}
+//#endregion
+exports.Column = Column;
+exports.KadakError = KadakError;
+exports.Table = Table;
+exports.TableClient = TableClient;
+exports.camelToSnake = camelToSnake;
+exports.connect = connect;
+exports.kadak = kadak;
+exports.table = table;
+exports.wrapPgError = wrapPgError;
+
+//# sourceMappingURL=index.cjs.map