@shyk/kadak 0.1.0 → 0.1.5

package/README.md

@@ -1,8 +1,8 @@
 # Kadak ☕️
 
-**The strongest TypeScript ORM for PostgreSQL. Period.**
+**The PostgreSQL ORM that feels invisible to beginners and intelligent to experts.**
 
-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 (pronounced *Ka-dak*) is built for developers who want plain JavaScript ergonomics with production-grade PostgreSQL power. It keeps the common path simple, but still exposes raw SQL and typed validators when you need to push harder.
 
 [kadak.shyk.in](https://kadak.shyk.in) | [Documentation](https://kadak.shyk.in/docs) | [npm](https://www.npmjs.com/package/kadak)
 
@@ -14,13 +14,12 @@ Drizzle is great, but it has friction. Drizzle makes you repeat yourself (`'id',
 
 **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`.
+*   **Simple Mode First**: Define tables with string shorthand like `id`, `email`, and `int?`.
+*   **Hybrid Escape Hatch**: Mix simple strings with builders like `kadak.email().unique()`.
+*   **Plain Object Queries**: `db.users.findMany({ active: true, $limit: 50 })`
+*   **Built-in Zod**: Table schemas generate insert, update, and select validators.
+*   **Analyzer Warnings**: Kadak warns on risky queries without blocking them.
+*   **Raw SQL Always Available**: `db.sql\`SELECT * FROM users\``
 
 ---
 
@@ -36,14 +35,15 @@ pnpm add @shyk/kadak postgres zod
 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(),
+  id: 'id',
+  email: 'email',
+  name: 'text',
+  age: 'int?',
+  balance: kadak.decimal(),
+  isActive: 'boolean',
+}, {
+  timestamps: true,
+  softDelete: true,
 })
 
 export type User = Infer<typeof users>
@@ -57,34 +57,108 @@ import { users } from './schema'
 
 const db = connect(process.env.DATABASE_URL!, { users })
 
-// Type-safe queries with automatic snake_case mapping
+// Top-level object = filter
 const allUsers = await db.users.findMany({
-  where: { isActive: true },
-  orderBy: { createdAt: 'desc' },
-  limit: 10
+  isActive: true,
+  $order: { createdAt: 'desc' },
+  $limit: 10,
 })
 
-// Validation included
-const result = users.validator().safeParse(somePayload)
-if (result.success) {
-  await db.users.insert(result.data)
-}
+const firstUser = await db.users.findFirst({ email: 'hello@kadak.dev' })
+const updated = await db.users.update({ id: 1 }, { isActive: false })
+await db.users.delete({ id: 1 })
+
+const result = users.insertValidator().safeParse(somePayload)
+if (result.success) await db.users.insert(result.data)
+
+await db.transaction(async (tx) => {
+  await tx.users.update({ id: 1 }, { isActive: false })
+  await tx.users.insert({ email: 'new@kadak.dev', name: 'New User', isActive: true })
+})
+```
+
+### 3. Runtime Controls
+
+```ts
+const db = connect({
+  url: process.env.DATABASE_URL!,
+  readReplicas: [process.env.READ_REPLICA_URL!],
+  debug: true,
+  warnings: 'relaxed', // 'relaxed' | 'strict' | 'silent'
+  retryAttempts: 2,
+  retryDelayMs: 200,
+  retryOnCodes: ['08006', '08001', '57P01'],
+  retryWrites: false,
+  defaultLimit: 100,
+  validateResults: true,
+  slowQueryMs: 250,
+  largeResultRows: 1000,
+  repeatedQueryThreshold: 25,
+}, { users })
 ```
 
+`retryAttempts` defaults to `0` (no retry). `retryWrites` defaults to `false`, so only `SELECT` retries are enabled unless you explicitly opt in.
+
+### 4. Migrations
+
+```ts
+import { createMigration, runMigrations } from '@shyk/kadak'
+
+const filePath = await createMigration('create_users_table')
+console.log('Created:', filePath)
+
+await runMigrations({
+  url: process.env.DATABASE_URL!,
+  dir: './migrations',
+})
+```
+
+### 5. Observability
+
+```ts
+import { KadakMetrics, connect } from '@shyk/kadak'
+
+const metrics = new KadakMetrics()
+
+const db = connect({
+  url: process.env.DATABASE_URL!,
+  metrics,
+  onQuery: (event) => {
+    if (event.durationMs > 300) console.log('slow query', event.sql)
+  },
+  explainAnalyze: true,
+  explainThresholdMs: 300,
+}, { users })
+
+console.log(metrics.snapshot())
+console.log(metrics.exportPrometheus())
+```
+
+### 6. Soak Benchmark
+
+```bash
+BENCH_TOTAL=1000 BENCH_CONCURRENCY=50 pnpm exec tsx benchmark/soak.ts
+```
+
+### 7. Compatibility and Production Checklist
+
+See [PRODUCTION_CHECKLIST.md](./PRODUCTION_CHECKLIST.md) before launch.
+See [COMPATIBILITY.md](./COMPATIBILITY.md) for versioning guarantees.
+
 ---
 
 ## Features
 
 | Feature | Kadak | Drizzle |
 | --- | --- | --- |
-| **Default Context** | Required (Safe) | Nullable (Prone to bugs) |
-| **Column Naming** | Auto `snake_case` | Manual `name('name')` |
+| **Schema Start** | String shorthand | Builder-heavy |
+| **Column Naming** | Auto `snake_case` | Manual mapping |
 | **Validation** | First-class Zod | Separate packages |
-| **Soft Delete** | Native `.softDelete()` | Manual WHERE clauses |
-| **Primary Keys** | `IDENTITY` (Modern) | `SERIAL` (Legacy) |
+| **Query Shape** | Plain object filters | More ceremony |
+| **Escape Hatch** | Raw `postgres.js` | Varies |
 
 ---
 
 ## License
 
-MIT © [Shyam](https://github.com/shyk)
+MIT © [Shyam](https://github.com/shyamkuldiya)