@bhushanpawar/sqldb 1.0.24 → 1.0.26

package/README.md

@@ -1,2088 +1,813 @@
 # @bhushanpawar/sqldb
 
-> 🚀 **The MariaDB client that makes your database feel like Redis**
+> 🚀 **The TypeORM-like MariaDB client with Redis caching superpowers**
 
-Stop wasting hours on cache invalidation bugs. Stop paying for database CPU you don't need. Get **99% cache hit rates** and **sub-millisecond queries**—automatically.
+Stop writing boilerplate CRUD services. Stop managing cache keys. Stop worrying about stale data. Get **TypeORM-like ergonomics** with **automatic caching**, **intelligent invalidation**, and **sub-millisecond queries**—out of the box.
 
 [![npm version](https://img.shields.io/npm/v/@bhushanpawar/sqldb?color=blue&style=flat-square)](https://www.npmjs.com/package/@bhushanpawar/sqldb)
 [![TypeScript](https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-**[⚡ Quick Start](#getting-started-in-60-seconds)** • **[📖 Docs](#documentation)** • **[🎯 Examples](#examples)** • **[⭐ Star on GitHub](https://github.com/erBhushanPawar/sqldb)**
+**[⚡ Quick Start](#quick-start-repository-pattern)** • **[📖 Docs](#documentation)** • **[🎯 Examples](#examples)** • **[⭐ Star on GitHub](https://github.com/bhushanpawar/sqldb)**
 
 ---
 
 ## 💎 What Makes This Special?
 
-**Most database libraries make you choose:** 🐌 Simple & slow ORM **OR** ⚡ Fast but complex manual caching
+**Most database libraries make you choose:** 🐌 Simple ORM (slow) **OR** ⚡ Fast manual caching (complex)
 
-**SqlDB gives you both.**
+**SqlDB gives you both** + zero boilerplate:
 
 ```typescript
-// Replace this mess...
-const cacheKey = `users:${status}:${page}`;
-let users = await redis.get(cacheKey);
-if (!users) {
-  users = await db.query('SELECT * FROM users WHERE status = ?', [status]);
-  await redis.set(cacheKey, JSON.stringify(users), 'EX', 60);
-  // Hope you remembered all the cache keys to invalidate...
-} else {
-  users = JSON.parse(users);
-}
-
-// ...with this magic ✨
-const users = await db.users.findMany({ status });
-// Cached automatically. Invalidated intelligently. Type-safe. Done.
-```
-
-## 🎯 The Results Speak for Themselves
-
-<table>
-<tr>
-<td width="50%">
-
-**Before SqlDB** 😰
-```
-Average response:     250ms
-Database CPU:         85%
-Cache hit rate:       0%
-Stale data bugs:      Weekly
-Cache code:           500+ lines
-Developer happiness:  😫
-```
-
-</td>
-<td width="50%">
-
-**After SqlDB** 🎉
-```
-Average response:     <1ms  (250x faster ⚡)
-Database CPU:         15%  (85% reduction)
-Cache hit rate:       99%+ (automatic)
-Stale data bugs:      Never (intelligent invalidation)
-Cache code:           0 lines (built-in)
-Developer happiness:  😍
-```
-
-</td>
-</tr>
-</table>
-
-## ⚡ Key Features at a Glance
-
-| Feature | What You Get |
-|---------|--------------|
-| 🚀 **Automatic Caching** | Every query cached in Redis. 99%+ hit rate. <1ms response. |
-| 🧠 **Smart Invalidation** | Update `users`? We clear `posts` & `comments` too. Follows FKs. |
-| 🎯 **Auto-Warming** | ML-powered warming learns your patterns. No cold starts. Ever. |
-| 🔒 **Type-Safe** | Full TypeScript support. Autocomplete everything. Catch errors at compile-time. |
-| 📊 **Query Tracking** | See every query with timing. Find slow requests in milliseconds. |
-| 🎨 **Beautiful Logging** | ⚡🚀✅⚠️🐌 - Know performance at a glance. |
-| 🔗 **Zero Config** | Auto-discovers schema. Maps relationships. Just works. |
-| 🏗️ **Production Ready** | Singleton pattern. Health checks. Graceful shutdown. Connection pooling. |
-
-## 🎬 See It In Action
-
-```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
-
-// 1. Initialize (auto-discovers your entire schema)
-const db = await createSqlDB({
-  mariadb: { host: 'localhost', user: 'root', password: 'pass', database: 'mydb' },
-  redis: { host: 'localhost' }
-});
-
-// 2. Query with automatic caching ⚡
-const users = await db.users.findMany({ status: 'active' });
-// First call: 200ms (database)
-// Next calls: <1ms (cache)
-
-// 3. Update with cascade invalidation ✨
-await db.users.updateById(1, { name: 'Jane' });
-// Automatically clears:
-// ✓ All user queries
-// ✓ All post queries (has user_id FK)
-// ✓ All comment queries (has post_id → user_id FK)
-// Zero stale data. Zero manual work.
-
-// 4. Monitor everything 📊
-const stats = db.getCacheManager().getStats();
-console.log(stats.hitRate);  // "99.5%"
-```
-
-**That's it.** No cache keys. No invalidation logic. No stale data bugs at 3am.
-
----
-
-## Why @bhushanpawar/sqldb?
-
-**Stop writing boilerplate.** Stop managing cache keys. Stop worrying about stale data.
-
-Most ORMs and database clients make you choose between:
-- 🐌 **Simplicity** (but slow)
-- ⚡ **Performance** (but complex caching logic)
-
-**We give you both.**
-
-### The Problem
-
-```typescript
-// Traditional approach - SLOW ❌
-app.get('/users', async (req, res) => {
-  const users = await db.query('SELECT * FROM users');  // 200ms every time
-  res.json(users);
-});
-
-// Manual caching - COMPLEX ❌
-app.get('/users', async (req, res) => {
-  const cacheKey = 'users:all';
-  let users = await redis.get(cacheKey);
-
-  if (!users) {
-    users = await db.query('SELECT * FROM users');
-    await redis.set(cacheKey, JSON.stringify(users), 'EX', 60);
-  } else {
-    users = JSON.parse(users);
-  }
-
-  res.json(users);
-});
-
-// When updating - FRAGILE ❌
-app.post('/users', async (req, res) => {
-  await db.query('INSERT INTO users ...', [data]);
-  await redis.del('users:all');           // Did you remember all cache keys?
-  await redis.del('users:active');        // What about related tables?
-  await redis.del('posts:by-user:*');     // This is getting messy...
-});
-```
-
-### The Solution
-
-```typescript
-// SqlDB - SIMPLE ✅ FAST ✅ AUTOMATIC ✅
-app.get('/users', async (req, res) => {
-  const users = await db.users.findMany();  // 1ms (cached) after first request
-  res.json(users);
-});
-
-app.post('/users', async (req, res) => {
-  await db.users.insertOne(data);
-  // Cache automatically invalidated ✨
-  // Related tables (posts, comments) also invalidated ✨
-  // No manual cache management needed ✨
-});
-```
-
-## Features That Actually Matter
-
-### 🚀 **Automatic Caching** - Set It and Forget It
-Every query is automatically cached in Redis. **99%+ cache hit rate** in production. **Sub-millisecond** response times.
-
-```typescript
-// First call: queries database (200ms)
-const users = await db.users.findMany({ status: 'active' });
-
-// Next 100 calls: served from cache (<1ms)
-// Automatically expires after TTL or on updates
-```
-
-### 🧠 **Intelligent Cache Invalidation** - Never Serve Stale Data
-Updates to `users` automatically invalidate `posts` and `comments` caches. **Follows foreign keys**. Zero configuration.
-
-```typescript
-// Update a user
-await db.users.updateById(1, { name: 'Jane' });
-
-// SqlDB automatically clears:
-// ✓ users:* cache
-// ✓ posts:* cache (has user_id FK)
-// ✓ comments:* cache (has post_id FK → user_id FK)
-// ✓ All related queries
-```
-
-### 🎯 **Auto-Warming** - Always Fast, Even After Restart
-ML-powered cache warming learns your query patterns and pre-warms hot queries in the background. **No cold starts**.
-
-```typescript
-warming: {
-  enabled: true,
-  // Tracks query frequency, auto-warms top queries
-  // Runs in separate pool (zero impact on your app)
-  // Persists stats across restarts
-}
-
-// After deployment, your cache is already warm ✨
-```
-
-### 📊 **Query Tracking** - Debug Like a Pro
-Track every query with correlation IDs. Find slow requests in milliseconds.
-
-```typescript
-// Middleware adds correlation ID
-req.correlationId = generateQueryId();
-
-// All queries tracked automatically
-const queries = db.getQueries(req.correlationId);
-
-// See exactly what happened
-console.log(queries.map(q => ({
-  sql: q.sql,
-  time: q.executionTimeMs,
-  cached: q.resultCount
-})));
-```
-
-### 🎨 **Beautiful Query Logging** - Know What's Happening
-
-```
-✅ SELECT on users - 45ms - 10 rows
-🚀 SELECT on orders - 12ms - 5 rows (cached)
-⚠️  SELECT on products - 250ms - 100 rows
-   SQL: SELECT * FROM products WHERE category = 'electronics'
-```
-
-Performance at a glance: ⚡ <10ms | 🚀 <50ms | ✅ <200ms | ⚠️ <500ms | 🐌 ≥500ms
-
-### 🔒 **Type-Safe** - Full TypeScript Support
-
-```typescript
-interface User {
-  id: number;
-  email: string;
-  status: 'active' | 'inactive';
-}
-
-type MyDB = SqlDBWithTables<{ users: User }>;
-const db = await createSqlDB(config) as MyDB;
-
-// Full autocomplete and type checking ✨
-const users = await db.users.findMany();  // Type: User[]
-await db.users.updateById(1, { status: 'verified' }); // ✓ Type-safe
-await db.users.updateById(1, { invalid: 'field' });   // ❌ TypeScript error
-```
-
-### 🔗 **Zero Configuration** - Works Out of the Box
-
-```typescript
-const db = await createSqlDB({
-  mariadb: { host: 'localhost', user: 'root', password: 'pass', database: 'mydb' },
-  redis: { host: 'localhost' }
-});
-
-// That's it. Schema auto-discovered. Relationships mapped. Cache ready.
-```
-
-### 📈 **Production-Ready** - Battle-Tested at Scale
-
-- ⚡ **10,000+ queries/second** with Redis cache
-- 🎯 **99%+ cache hit rate** in production
-- 📊 **<1ms** cached query response time
-- 🔄 **Connection pooling** built-in
-- 🏥 **Health checks** included
-- 🎭 **Singleton pattern** for clean architecture
-- 🔥 **Zero downtime** schema refreshes
-
-## Real-World Performance
-
-**Before SqlDB:**
-```
-Average API response time: 250ms
-Database load: 85% CPU
-Redis: Not used
-Cache hit rate: 0%
-Lines of caching code: 500+
-```
-
-**After SqlDB:**
-```
-Average API response time: 12ms (20x faster ⚡)
-Database load: 15% CPU (85% reduction)
-Redis: 98% cache hit rate
-Cache invalidation: Automatic
-Lines of caching code: 0
-```
-
-## Quick Comparison
-
-| Feature | Traditional ORM | Manual Cache | **SqlDB** |
-|---------|----------------|--------------|-------------|
-| Query Speed | 🐌 200ms | ⚡ 2ms | ⚡ **<1ms** |
-| Auto-Caching | ❌ | ❌ | ✅ **Built-in** |
-| Cache Invalidation | ❌ Manual | ❌ Error-prone | ✅ **Automatic** |
-| Relationship Tracking | ⚠️ Limited | ❌ None | ✅ **Auto-discovered** |
-| Type Safety | ✅ | ❌ | ✅ **Full** |
-| Learning Curve | 📚 High | 📚 High | 📖 **Minimal** |
-| Boilerplate Code | 🔥 Lots | 🔥🔥 Tons | ✅ **Zero** |
-| Cache Warming | ❌ | ❌ Manual | ✅ **AI-Powered** |
-| Query Tracking | ⚠️ Basic | ❌ | ✅ **Advanced** |
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Getting Started in 60 Seconds](#getting-started-in-60-seconds)
-- [Complete Quick Start](#complete-quick-start)
-- [Core Concepts](#core-concepts)
-- [Examples (Simple → Complex)](#examples)
-- [Configuration](#configuration)
-- [CRUD Operations](#crud-operations)
-- [Cache Management](#cache-management)
-- [Performance Optimization](#performance-optimization)
-- [API Reference](#api-reference)
-- [Migration Guide](#migration-from-mariadb)
-- [Documentation](#documentation)
-
----
-
-## Installation
-
-```bash
-npm install @bhushanpawar/sqldb mariadb redis
-```
-
-## Getting Started in 60 Seconds
-
-### 1. Install
-```bash
-npm install @bhushanpawar/sqldb mariadb redis
-```
-
-### 2. Initialize
-```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
-
-const db = await createSqlDB({
-  mariadb: { host: 'localhost', user: 'root', password: 'pass', database: 'mydb' },
-  redis: { host: 'localhost' }
-});
-```
-
-### 3. Use
-```typescript
-// Query with automatic caching ⚡
-const users = await db.users.findMany({ status: 'active' });
-
-// Update with automatic cache invalidation ✨
-await db.users.updateById(1, { status: 'verified' });
-
-// That's it! No boilerplate, no cache keys, no invalidation logic.
-```
-
-### 4. Profit 📈
-```
-First request:  200ms (database)
-Next requests:  <1ms  (cache)
-Cache hit rate: 99%+
-Lines of code:  3 (vs 50+)
-```
-
-## Complete Quick Start
-
-Here's a more complete example with all the bells and whistles:
-
-```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
-
-const db = await createSqlDB({
-  // Database connection
-  mariadb: {
-    host: 'localhost',
-    port: 3306,
-    user: 'root',
-    password: 'password',
-    database: 'mydb',
-    connectionLimit: 10,
-    logging: true,  // See all queries with performance metrics
-  },
-
-  // Redis cache
-  redis: {
-    host: 'localhost',
-    port: 6379,
-    keyPrefix: 'myapp:',
-  },
-
-  // Caching configuration
-  cache: {
-    enabled: true,
-    defaultTTL: 60,              // Cache for 60 seconds
-    maxKeys: 1000,               // Max 1000 cache keys
-    invalidateOnWrite: true,     // Auto-clear on INSERT/UPDATE/DELETE
-    cascadeInvalidation: true,   // Clear related tables too
-  },
-
-  // Auto-discovery
-  discovery: {
-    autoDiscover: true,          // Discover schema on startup
-    refreshInterval: 3600000,    // Refresh every hour
-  },
-
-  // Auto-warming (optional but awesome)
-  warming: {
-    enabled: true,
-    intervalMs: 60000,           // Warm cache every minute
-    topQueriesPerTable: 10,      // Warm top 10 queries per table
-  },
-});
-
-// ========================================
-// READ - Automatically cached
-// ========================================
-
-// Find all
-const allUsers = await db.users.findMany();
-
-// Find with conditions
-const activeUsers = await db.users.findMany({ status: 'active' });
-
-// Find one
-const user = await db.users.findOne({ email: 'john@example.com' });
-
-// Find by ID (optimized)
-const userById = await db.users.findById(1);
-
-// Count
-const count = await db.users.count({ status: 'active' });
-
-// ========================================
-// WRITE - Automatically invalidates cache
-// ========================================
-
-// Insert
-const newUser = await db.users.insertOne({
-  name: 'John Doe',
-  email: 'john@example.com',
-  status: 'active'
-});
-
-// Update
-await db.users.updateById(1, { status: 'verified' });
-
-// Delete
-await db.users.deleteById(1);
-
-// ========================================
-// MONITORING - See what's happening
-// ========================================
-
-// Cache stats
-const stats = db.getCacheManager().getStats();
-console.log(`Cache hit rate: ${stats.hitRate}`);
-// Output: Cache hit rate: 99.5%
-
-// Query tracking
-const queries = db.getQueries(correlationId);
-console.log(`Total time: ${queries.reduce((sum, q) => sum + q.executionTimeMs, 0)}ms`);
-
-// Health check
-const health = await db.healthCheck();
-console.log(health);  // { mariadb: true, redis: true }
-
-// ========================================
-// CLEANUP
-// ========================================
-
-await db.close();
-```
-
-### Singleton Pattern (Recommended)
-
-For production applications, use singleton mode to share a single connection pool:
-
-```typescript
-import { createSqlDB, getSqlDB } from '@bhushanpawar/sqldb';
-
-// Initialize once at app startup
-const db = await createSqlDB({
-  mariadb: { /* config */ },
-  redis: { /* config */ },
-  cache: { enabled: true },
-}, { singleton: true }); // Enable singleton mode
-
-// Access anywhere in your app
-import { getSqlDB } from '@bhushanpawar/sqldb';
-
-const db = getSqlDB(); // Returns the same instance
-const users = db.getTableOperations('users');
-```
-
-See [SINGLETON_PATTERN.md](./docs/SINGLETON_PATTERN.md) for detailed usage.
-
-### Dynamic Table Access (TypeScript-Friendly)
-
-Access tables directly as properties with full type safety:
-
-```typescript
-import { createSqlDB, SqlDBWithTables } from '@bhushanpawar/sqldb';
-
-// Define your schema
-interface MySchema {
-  users: { id: number; name: string; email: string };
-  orders: { id: number; user_id: number; total: number };
-}
-
-type MyDB = SqlDBWithTables<MySchema>;
-
-const db = await createSqlDB(config) as MyDB;
-
-// Clean, typed access
-const users = await db.users.findMany();           // Type: MySchema['users'][]
-const order = await db.orders.findById(123);       // Type: MySchema['orders'] | null
-await db.users.updateById(1, { name: 'Jane' });    // Fully type-checked
-
-// Still works the old way too
-const usersTable = db.getTableOperations('users');
-```
-
-See [DYNAMIC_TABLE_ACCESS.md](./docs/DYNAMIC_TABLE_ACCESS.md) for detailed usage.
-
-### Raw Query Caching
-
-The `raw` method supports caching custom SQL queries with a configurable TTL (default: 1 minute):
-
-```typescript
-const users = db.getTableOperations('users');
-
-// First call - queries database and caches result for 60 seconds
-const results = await users.raw(
-  'SELECT * FROM users WHERE status = ? ORDER BY created_at DESC LIMIT 10',
-  ['active']
-);
-
-// Subsequent calls within 60 seconds - served from cache
-const cachedResults = await users.raw(
-  'SELECT * FROM users WHERE status = ? ORDER BY created_at DESC LIMIT 10',
-  ['active']
-);
-
-// Cache stats show hits and misses
-const stats = db.getCacheManager().getStats();
-console.log(stats);
-// { hits: 99, misses: 1, evictions: 0, hitRate: '99.00%' }
-```
-
-The raw query cache:
-- Uses the full SQL query and parameters as the cache key
-- Has a fixed 60-second TTL (optimized for dynamic queries)
-- Automatically expires when the table is modified
-- Supports correlation IDs for query tracking
-
-## Table of Contents
-
-- [Core Concepts](#core-concepts)
-- [Configuration](#configuration)
-- [CRUD Operations](#crud-operations)
-- [Cache Management](#cache-management)
-- [Query Tracking](#query-tracking)
-- [Smart Cache Invalidation](#smart-cache-invalidation)
-- [Performance Optimization](#performance-optimization)
-- [API Reference](#api-reference)
-
-## Core Concepts
-
-### Schema Discovery
-
-SqlDB automatically discovers your database schema on initialization:
-
-```typescript
-const db = await createSqlDB({
-  discovery: {
-    autoDiscover: true,
-    includedTables: ['users', 'posts', 'comments'], // Optional: specific tables
-    excludedTables: ['temp_*'], // Optional: exclude patterns
-    refreshInterval: 3600000, // Refresh every hour
-  },
-});
-
-// Get discovered tables
-const tables = db.getDiscoveredTables();
-console.log(tables); // ['users', 'posts', 'comments', ...]
-
-// Get dependency graph
-const graph = db.getDependencyGraph();
-const deps = graph.getDependencies('users'); // Tables that depend on users
-```
-
-### Relationship Mapping
-
-SqlDB automatically maps foreign key relationships:
-
-```typescript
-// Schema example:
-// posts (id, user_id, title)
-// comments (id, post_id, user_id, content)
-
-// Updating a user invalidates related posts and comments
-await users.updateById(1, { name: 'Jane' });
-// Cache invalidated: users:*, posts:*, comments:*
-
-// With cascadeInvalidation: false, only users cache is invalidated
-```
-
-### Cache Invalidation Strategies
-
-```typescript
-// 1. Automatic invalidation on write (recommended)
-await createSqlDB({
-  cache: {
-    invalidateOnWrite: true,
-    cascadeInvalidation: true, // Invalidate related tables
-  },
-});
-
-// 2. Manual invalidation
-const users = db.getTableOperations('users');
-await users.invalidateCache();
-
-// 3. Invalidation via manager
-const invalidationManager = db.getInvalidationManager();
-await invalidationManager.invalidateTable('users', { cascade: true });
-
-// 4. Clear entire cache
-const cacheManager = db.getCacheManager();
-await cacheManager.clear();
-```
-
-## Configuration
-
-### Complete Configuration Example
-
-```typescript
-import { createSqlDB, SqlDBConfig } from '@bhushanpawar/sqldb';
-
-const config: SqlDBConfig = {
-  // MariaDB connection
-  mariadb: {
-    host: 'localhost',
-    port: 3306,
-    user: 'root',
-    password: 'password',
-    database: 'mydb',
-    connectionLimit: 10,
-    acquireTimeout: 10000,
-    connectTimeout: 10000,
-  },
-
-  // Redis connection
-  redis: {
-    host: 'localhost',
-    port: 6379,
-    password: 'redis-password', // Optional
-    db: 0,
-    keyPrefix: 'myapp:',
-  },
-
-  // Cache configuration
-  cache: {
-    enabled: true,
-    defaultTTL: 60,              // Default: 60 seconds
-    maxKeys: 1000,               // Max cached queries
-    invalidateOnWrite: true,     // Auto-invalidate on INSERT/UPDATE/DELETE
-    cascadeInvalidation: true,   // Invalidate related tables
-  },
-
-  // Schema discovery
-  discovery: {
-    autoDiscover: true,
-    includedTables: [],          // Empty = all tables
-    excludedTables: [],
-    maxGraphDepth: 3,            // Cascade depth
-    refreshInterval: 3600000,    // 1 hour
-  },
-
-  // Logging
-  logging: {
-    level: 'info',               // 'debug' | 'info' | 'warn' | 'error'
-    logger: (level, message, meta) => {
-      console.log(`[${level}] ${message}`, meta);
-    },
-  },
-};
-
-const db = await createSqlDB(config);
-```
-
-### Configuration Options
-
-#### Cache Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | boolean | true | Enable/disable caching |
-| `defaultTTL` | number | 60 | Default cache TTL in seconds |
-| `maxKeys` | number | 1000 | Maximum cached keys (LRU eviction) |
-| `invalidateOnWrite` | boolean | true | Auto-invalidate on writes |
-| `cascadeInvalidation` | boolean | true | Cascade invalidation to related tables |
-
-#### Discovery Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `autoDiscover` | boolean | true | Auto-discover schema on init |
-| `includedTables` | string[] | [] | Tables to include (empty = all) |
-| `excludedTables` | string[] | [] | Tables to exclude (supports patterns) |
-| `maxGraphDepth` | number | 3 | Max cascade depth for relationships |
-| `refreshInterval` | number | 0 | Schema refresh interval (0 = disabled) |
-
-## CRUD Operations
-
-### Find Operations
-
-```typescript
-const users = db.getTableOperations<User>('users');
+// Before: 800+ lines of custom CRUD service 😰
+export class UnifiedCRUDService<T> {
+  // Custom query builder (200 lines)
+  // JSON aggregation for relations (100 lines)
+  // Lifecycle hooks management (100 lines)
+  // Case conversion (100 lines)
+  // Entity transformation (100 lines)
+  // Primary key handling (50 lines)
+  // ... 150 more lines
+}
 
-// Find all
-const all = await users.findMany();
+// After: 50 lines with SqlDB 🎉
+@Entity()
+class User {
+  @PrimaryColumn()
+  userId: string;
 
-// Find with conditions
-const active = await users.findMany({
-  status: 'active'
-});
+  @Column()
+  email: string;
 
-// Find with options
-const paginated = await users.findMany(
-  { status: 'active' },
-  {
-    limit: 10,
-    offset: 20,
-    orderBy: 'created_at',
-    order: 'DESC',
-    skipCache: false, // Force cache bypass
+  @BeforeInsert()
+  async hashPassword() {
+    this.password = await bcrypt.hash(this.password, 10);
   }
-);
-
-// Find one
-const user = await users.findOne({ email: 'john@example.com' });
-
-// Find by ID
-const userById = await users.findById(1);
-
-// Count
-const count = await users.count({ status: 'active' });
-```
-
-### Insert Operations
-
-```typescript
-// Insert one
-const newUser = await users.insertOne({
-  name: 'John Doe',
-  email: 'john@example.com',
-  status: 'active',
-});
-console.log(newUser.id); // Auto-generated ID
-
-// Insert many
-const newUsers = await users.insertMany([
-  { name: 'Alice', email: 'alice@example.com' },
-  { name: 'Bob', email: 'bob@example.com' },
-]);
-console.log(newUsers.map(u => u.id)); // [1, 2]
-```
-
-### Update Operations
-
-```typescript
-// Update one
-const updated = await users.updateOne(
-  { id: 1 },
-  { status: 'inactive' }
-);
-
-// Update many
-const count = await users.updateMany(
-  { status: 'pending' },
-  { status: 'active' }
-);
-console.log(`Updated ${count} users`);
-
-// Update by ID
-const user = await users.updateById(1, { name: 'Jane Doe' });
-```
 
-### Delete Operations
-
-```typescript
-// Delete one
-const deleted = await users.deleteOne({ id: 1 });
-console.log(deleted); // true/false
-
-// Delete many
-const count = await users.deleteMany({ status: 'inactive' });
-console.log(`Deleted ${count} users`);
+  @AfterLoad()
+  calculateFullName() {
+    this.fullName = `${this.firstName} ${this.lastName}`;
+  }
+}
 
-// Delete by ID
-const deleted = await users.deleteById(1);
+const userRepo = db.getRepository(User);
+const users = await userRepo.find({ where: { status: 'active' } });
 ```
 
-### Raw SQL Queries
+**Result: 94% less code, 250x faster queries.**
 
-```typescript
-// Raw query with caching (60s TTL)
-const results = await users.raw<User[]>(
-  'SELECT * FROM users WHERE created_at > ? ORDER BY id DESC',
-  ['2024-01-01']
-);
-
-// With correlation ID for tracking
-const correlationId = 'request-123';
-const results = await users.raw(
-  'SELECT COUNT(*) as total FROM users',
-  [],
-  correlationId
-);
-```
+---
 
-## Cache Management
+## 🎯 Quick Start: Repository Pattern
 
-### Cache Statistics
+SqlDB now offers a **TypeORM-like repository pattern** that eliminates boilerplate:
 
 ```typescript
-const cacheManager = db.getCacheManager();
-const stats = cacheManager.getStats();
-
-console.log(stats);
-// {
-//   hits: 1500,
-//   misses: 100,
-//   evictions: 50,
-//   size: 0,
-//   hitRate: '93.75%'
-// }
-
-// Reset stats
-cacheManager.resetStats();
-```
+import {
+  createSqlDB,
+  Entity,
+  PrimaryColumn,
+  Column,
+  BeforeInsert,
+  AfterLoad,
+} from '@bhushanpawar/sqldb';
+import bcrypt from 'bcrypt';
 
-### Manual Cache Control
+// 1. Define Entity with Decorators
+@Entity()
+class User {
+  @PrimaryColumn()
+  userId: string;
 
-```typescript
-// Check if cache is enabled
-if (cacheManager.isEnabled()) {
-  // Get cached value
-  const value = await cacheManager.get('cache:key');
+  @Column()
+  email: string;
 
-  // Set cached value
-  await cacheManager.set('cache:key', data, 120); // 120s TTL
+  @Column()
+  password: string;
 
-  // Delete specific key
-  await cacheManager.delete('cache:key');
+  @Computed()
+  fullName: string;
 
-  // Delete by pattern
-  const count = await cacheManager.deletePattern('users:*');
+  @BeforeInsert()
+  async hashPassword() {
+    this.password = await bcrypt.hash(this.password, 10);
+  }
 
-  // Clear all cache
-  await cacheManager.clear();
+  @AfterLoad()
+  calculateFullName() {
+    this.fullName = `${this.firstName} ${this.lastName}`;
+  }
 }
-```
-
-### Cache Warming
-
-```typescript
-const users = db.getTableOperations('users');
-
-// Pre-warm cache with common queries
-await users.warmCache({ status: 'active' });
-
-// This will now be served from cache
-const active = await users.findMany({ status: 'active' });
-```
 
-### Cache Warming with Relations
-
-Pre-warm cache for a table and all its related tables based on the dependency graph:
-
-```typescript
-const provider = db.getTableOperations('provider');
-
-// Warm cache for provider and all related tables
-await provider.warmCacheWithRelations({}, {
-  correlationId: 'startup-warming',
-  depth: 1,                    // How deep to traverse relationships
-  warmDependents: true,        // Warm tables that reference this table
-  warmDependencies: true,      // Warm tables this table references
+// 2. Initialize SqlDB
+const db = await createSqlDB({
+  mariadb: { host: 'localhost', user: 'root', password: 'pass', database: 'mydb' },
+  redis: { host: 'localhost' },
 });
 
-// Now provider and all related tables are cached:
-// - provider (main table)
-// - user (table that provider depends on)
-// - orders, services, bank_details, etc. (tables that depend on provider)
-```
-
-**Use Cases:**
-- **Application startup**: Pre-warm frequently accessed tables and their relations
-- **API endpoints**: Warm cache before handling requests for better response times
-- **Batch operations**: Pre-load related data before processing
-
-**Example - Warm on Startup:**
-```typescript
-async function warmCacheOnStartup(db: SqlDBClient) {
-  // Warm most frequently accessed tables with their relations
-  const provider = db.getTableOperations('provider');
-  const orders = db.getTableOperations('orders');
-
-  await Promise.all([
-    provider.warmCacheWithRelations({}, { depth: 1, warmDependents: true }),
-    orders.warmCacheWithRelations({}, { depth: 1, warmDependencies: true }),
-  ]);
-
-  console.log('Cache warmed successfully!');
-}
-```
-
-## Query Tracking
-
-Track queries with correlation IDs for debugging and performance monitoring:
-
-```typescript
-import { generateQueryId } from '@bhushanpawar/sqldb';
-
-// Generate correlation ID for a request
-const correlationId = generateQueryId();
-
-// Use across multiple operations
-const users = db.getTableOperations('users');
-await users.findMany({ status: 'active' }, { correlationId });
-await users.count({ status: 'active' }, correlationId);
-await users.findById(1, correlationId);
-
-// Get all queries for this correlation
-const queries = db.getQueries(correlationId);
+// 3. Get Repository
+const userRepo = db.getRepository(User);
 
-queries.forEach(q => {
-  console.log({
-    queryId: q.queryId,
-    sql: q.sql,
-    executionTime: q.executionTimeMs,
-    cached: q.resultCount,
-  });
+// 4. Use It (One-Liners!)
+const user = await userRepo.save({
+  email: 'john@example.com',
+  password: 'secret123', // Auto-hashed via @BeforeInsert
 });
 
-// Performance analysis
-const totalTime = queries.reduce((sum, q) => sum + (q.executionTimeMs || 0), 0);
-const avgTime = totalTime / queries.length;
-console.log(`Total: ${totalTime}ms, Average: ${avgTime}ms`);
-
-// Clean up
-db.clearQueries(correlationId);
-```
-
-### Query Metadata
-
-Each tracked query includes:
-
-```typescript
-interface QueryMetadata {
-  queryId: string;           // Unique UUID
-  correlationId?: string;    // Optional correlation ID
-  sql: string;              // SQL query
-  params?: any[];           // Query parameters
-  startTime: number;        // Unix timestamp
-  endTime?: number;         // Unix timestamp
-  executionTimeMs?: number; // Execution time
-  resultCount?: number;     // Rows returned/affected
-  error?: string;           // Error message if failed
-}
-```
-
-## Smart Cache Invalidation
-
-### How It Works
-
-```typescript
-// Database schema:
-// users (id, name)
-// posts (id, user_id, title)  -- FK to users
-// comments (id, post_id, content) -- FK to posts
-
-// When you update a user:
-await users.updateById(1, { name: 'Updated Name' });
-
-// SqlDB invalidates:
-// 1. users:* (direct table)
-// 2. posts:* (depends on users via user_id)
-// 3. comments:* (depends on posts via post_id)
-```
-
-### Dependency Graph
-
-```typescript
-const graph = db.getDependencyGraph();
-
-// Get tables that depend on 'users'
-const deps = graph.getDependencies('users');
-console.log(deps); // ['posts', 'comments']
-
-// Get all tables 'comments' depends on
-const parents = graph.getParents('comments');
-console.log(parents); // ['posts', 'users']
-
-// Check if there's a path
-const hasPath = graph.hasPath('users', 'comments');
-console.log(hasPath); // true
-
-// Get graph info
-const info = graph.getGraphInfo();
-console.log(info); // { tables: 3, relationships: 2 }
-```
-
-### Manual Invalidation
-
-```typescript
-const invalidationManager = db.getInvalidationManager();
-
-// Invalidate single table
-await invalidationManager.invalidateTable('users');
-
-// Invalidate with cascade
-await invalidationManager.invalidateTable('users', {
-  cascade: true
+const users = await userRepo.find({
+  where: { status: 'active' },
+  limit: 10,
 });
 
-// Invalidate multiple tables
-await invalidationManager.invalidateTables(['users', 'posts']);
-
-// Invalidate by operation
-const cacheManager = db.getCacheManager();
-await cacheManager.deletePattern('users:findMany:*');
-```
-
-## Performance Optimization
-
-### Best Practices
-
-1. **Configure Appropriate TTL**
-   ```typescript
-   // High-churn data: short TTL
-   cache: { defaultTTL: 30 }
-
-   // Stable data: longer TTL
-   cache: { defaultTTL: 300 }
-   ```
-
-2. **Use Selective Caching**
-   ```typescript
-   // Skip cache for real-time data
-   const users = await users.findMany(
-     { status: 'online' },
-     { skipCache: true }
-   );
-   ```
-
-3. **Warm Cache for Common Queries**
-   ```typescript
-   // Pre-warm after deployment
-   await users.warmCache({ status: 'active' });
-   await posts.warmCache({ published: true });
-   ```
-
-4. **Monitor Cache Performance**
-   ```typescript
-   const stats = db.getCacheManager().getStats();
-
-   if (parseFloat(stats.hitRate) < 80) {
-     console.warn('Low cache hit rate:', stats);
-   }
-   ```
-
-5. **Use Correlation IDs**
-   ```typescript
-   // Track request performance
-   app.use((req, res, next) => {
-     req.correlationId = generateQueryId();
-     next();
-   });
-
-   // Log slow requests
-   app.use((req, res, next) => {
-     const queries = db.getQueries(req.correlationId);
-     const totalTime = queries.reduce((sum, q) =>
-       sum + (q.executionTimeMs || 0), 0);
-
-     if (totalTime > 1000) {
-       console.warn('Slow request:', {
-         path: req.path,
-         time: totalTime,
-         queries: queries.length
-       });
-     }
-     next();
-   });
-   ```
-
-### Performance Testing
-
-```typescript
-// Example performance test
-const iterations = 100;
-const correlationId = generateQueryId();
-
-console.time('100 queries');
-for (let i = 0; i < iterations; i++) {
-  await users.findMany({ status: 'active' }, { correlationId });
-}
-console.timeEnd('100 queries');
-
-// Check cache effectiveness
-const stats = db.getCacheManager().getStats();
-console.log(`Hit rate: ${stats.hitRate}`);
-console.log(`Hits: ${stats.hits}, Misses: ${stats.misses}`);
-
-// Analyze query performance
-const queries = db.getQueries(correlationId);
-console.log(`Total queries executed: ${queries.length}`); // Should be 1 if cache works
-```
-
-## API Reference
-
-### SqlDBClient
-
-```typescript
-class SqlDBClient {
-  // Initialize client
-  async initialize(): Promise<void>;
-
-  // Get table operations
-  getTableOperations<T>(tableName: string): TableOperations<T>;
-
-  // Get managers
-  getCacheManager(): CacheManager;
-  getInvalidationManager(): InvalidationManager;
-  getDependencyGraph(): DependencyGraph;
-
-  // Schema discovery
-  getDiscoveredTables(): string[];
-  async refreshSchema(): Promise<void>;
-
-  // Query tracking
-  getQueries(correlationId?: string): QueryMetadata[];
-  clearQueries(correlationId?: string): void;
-
-  // Health and lifecycle
-  async healthCheck(): Promise<HealthStatus>;
-  async close(): Promise<void>;
-}
-```
-
-### TableOperations
-
-```typescript
-interface TableOperations<T> {
-  // Find operations
-  findOne(where: WhereClause<T>, options?: FindOptions): Promise<T | null>;
-  findMany(where?: WhereClause<T>, options?: FindOptions): Promise<T[]>;
-  findById(id: string | number, correlationId?: string): Promise<T | null>;
-  count(where?: WhereClause<T>, correlationId?: string): Promise<number>;
-
-  // Insert operations
-  insertOne(data: Omit<T, 'id'>, correlationId?: string): Promise<T>;
-  insertMany(data: Omit<T, 'id'>[], correlationId?: string): Promise<T[]>;
-
-  // Update operations
-  updateOne(where: WhereClause<T>, data: Partial<T>, correlationId?: string): Promise<T | null>;
-  updateMany(where: WhereClause<T>, data: Partial<T>, correlationId?: string): Promise<number>;
-  updateById(id: string | number, data: Partial<T>, correlationId?: string): Promise<T | null>;
-
-  // Delete operations
-  deleteOne(where: WhereClause<T>, correlationId?: string): Promise<boolean>;
-  deleteMany(where: WhereClause<T>, correlationId?: string): Promise<number>;
-  deleteById(id: string | number, correlationId?: string): Promise<boolean>;
-
-  // Raw queries
-  raw<R = any>(sql: string, params?: any[], correlationId?: string): Promise<R>;
-
-  // Cache management
-  invalidateCache(): Promise<void>;
-  warmCache(where?: WhereClause<T>, correlationId?: string): Promise<void>;
-}
-```
-
-### CacheManager
-
-```typescript
-class CacheManager {
-  async get<T>(key: string): Promise<T | null>;
-  async set(key: string, value: any, ttl?: number): Promise<void>;
-  async delete(key: string): Promise<void>;
-  async deletePattern(pattern: string): Promise<number>;
-  async exists(key: string): Promise<boolean>;
-  async clear(): Promise<void>;
-
-  getStats(): CacheStats;
-  resetStats(): void;
-  isEnabled(): boolean;
-  getKeyBuilder(): CacheKeyBuilder;
-}
+await userRepo.updateById(user.userId, { status: 'inactive' });
 ```
 
-## Who Is This For?
+**What You Get:**
+- ✅ **Zero boilerplate** - No custom CRUD services
+- ✅ **Automatic lifecycle hooks** - `@BeforeInsert`, `@AfterLoad`, etc.
+- ✅ **Type-safe queries** - Full autocomplete + type checking
+- ✅ **Automatic caching** - Redis-backed, FK-aware
+- ✅ **94% less code** compared to manual implementations
+- ✅ **Prisma-style operators** - `{ age: { gte: 18 } }`
+- ✅ **Relation loading** - N+1 prevention with batching
 
-### ✅ Perfect for you if:
-
-- 🚀 **You want better performance** without rewriting your app
-- 💰 **You're tired of paying for database CPU** that could be cached
-- 🐛 **You've debugged stale cache bugs** at 3am
-- 📚 **You hate writing cache invalidation logic**
-- ⚡ **You need <10ms API response times**
-- 🔥 **You're scaling and your database is the bottleneck**
-- 🎯 **You want type safety** without code generation
-- 📊 **You need query observability** built-in
-
-### ❌ Not for you if:
-
-- Your app has <100 requests/day (caching overhead not worth it)
-- You exclusively write data (writes bypass cache)
-- You don't have Redis available
-- You need MySQL-specific features (use MariaDB instead)
+📖 **[Read Full Repository Pattern Guide →](./docs/REPOSITORY_PATTERN.md)**
 
 ---
 
-## Migration from `mariadb` Package
-
-Migrating is trivial. Here's what changes:
-
-### Before (mariadb) - 15 lines of boilerplate
-
-```typescript
-import mariadb from 'mariadb';
-
-const pool = mariadb.createPool({
-  host: 'localhost',
-  user: 'root',
-  password: 'password',
-  database: 'mydb',
-  connectionLimit: 10
-});
-
-// Every query needs manual connection management
-const conn = await pool.getConnection();
-try {
-  const users = await conn.query('SELECT * FROM users WHERE status = ?', ['active']);
-  const count = await conn.query('SELECT COUNT(*) as total FROM users WHERE status = ?', ['active']);
-  return users;
-} finally {
-  conn.release();
-}
-
-// No caching
-// No type safety
-// Manual connection pooling
-// Verbose error handling
-```
+## 🔄 Easy Migration from Custom CRUD Services
 
-### After (@bhushanpawar/sqldb) - 5 lines with superpowers
+If you have existing code using custom `UnifiedCRUDService` or similar patterns, SqlDB's backward compatibility methods make migration seamless:
 
 ```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
-
-const db = await createSqlDB({
-  mariadb: { host: 'localhost', user: 'root', password: 'password', database: 'mydb' },
-  redis: { host: 'localhost' }
-});
-
-// Clean API + automatic caching + type safety
-const users = await db.users.findMany({ status: 'active' });
-const count = await db.users.count({ status: 'active' });
-
-// ✨ Cached automatically
-// ✨ Invalidated on writes
-// ✨ Type-safe
-// ✨ Connection pooling handled
-// ✨ Error handling built-in
-```
-
-### What You Gain
-
-| Before | After | Improvement |
-|--------|-------|-------------|
-| Manual `query()` calls | Clean `findMany()`, `findById()` | **10x less code** |
-| No caching | Automatic Redis cache | **20x faster** |
-| Manual connection management | Automatic pooling | **0 bugs** |
-| Raw SQL everywhere | Type-safe methods | **TypeScript bliss** |
-| No invalidation | Cascade invalidation | **0 stale data** |
-| Basic logging | Performance metrics | **Debug in seconds** |
-
-### Migration Checklist
-
-- [ ] Install packages: `npm install @bhushanpawar/sqldb mariadb redis`
-- [ ] Set up Redis (if not already running)
-- [ ] Replace `mariadb.createPool()` with `createSqlDB()`
-- [ ] Replace `conn.query()` with `db.table.findMany()`, `findById()`, etc.
-- [ ] Remove manual connection management (`getConnection()`, `release()`)
-- [ ] Remove manual caching logic (if any)
-- [ ] Add TypeScript interfaces for tables (optional but recommended)
-- [ ] Test and deploy
-- [ ] Watch your response times drop 📉
-- [ ] Celebrate 🎉
-
-## Performance Benchmarks
-
-Real-world results from production deployments:
-
-### Response Times
-```
-Database Query:     200ms  🐌
-Manual Cache:        15ms  ⚠️
-SqlDB (cold):      45ms  ✅
-SqlDB (warm):     0.8ms  ⚡ 250x faster!
-```
-
-### Metrics That Matter
-
-| Metric | Value | Impact |
-|--------|-------|--------|
-| **Cache Hit Rate** | 99.2% | Only 1 in 100 queries hits DB |
-| **P50 Response Time** | <1ms | Instant for users |
-| **P99 Response Time** | 12ms | Fast even at extremes |
-| **Throughput** | 10,000+ qps | Handle Black Friday traffic |
-| **DB CPU Reduction** | 85% ↓ | Save $$$$ on database |
-| **Memory per Query** | ~1KB | Efficient caching |
-| **Schema Discovery** | 2.2s | 9x faster than v1 |
+// Your old service code works immediately!
+const userRepo = db.getRepository(User);
 
-### Load Test Results
+// Legacy methods (drop-in replacements)
+await userRepo.findByPK(userId, ['orders', 'addresses']);
+await userRepo.findByPaginationQuery({ page: 1, limit: 20, orderBy: 'createdAt' });
+await userRepo.findBySearchFilterModel({ search: 'john', searchFields: ['email'] });
+await userRepo.countByQuery({ status: 'active' });
 
-```bash
-# 1000 concurrent users, 10,000 requests
-npm run usage perf
+// Then migrate incrementally to modern syntax
+await userRepo.findById(userId, { withRelations: { dependents: ['orders'] } });
+await userRepo.find({ limit: 20, offset: 20, orderBy: { column: 'createdAt', direction: 'DESC' } });
 ```
 
-**Results:**
-- Average response: **0.9ms**
-- P99 response: **8ms**
-- Throughput: **12,450 req/s**
-- Database queries: **124** (99% cache hit)
-- No errors, no timeouts, no cache misses
+**Available Legacy Methods:**
+- `findByPK(id, relationsToFetch?)` - Drop-in for custom `findByPK`
+- `findByQuery(query)` - Accepts legacy query objects
+- `findAllRecords(filters?)` - Replaces `findAllRecords`
+- `findByPaginationQuery(paginationQuery)` - Pagination helper
+- `findBySearchFilterModel(searchFilter)` - Search filter helper
+- `countByQuery(query)` / `countAll()` - Count helpers
+- `deleteByQuery(query)` - Delete with legacy format
 
-See [PERFORMANCE_RESULTS.md](./docs/PERFORMANCE_RESULTS.md) for detailed benchmarks.
+**Migration Strategy:**
+1. Replace `UnifiedCRUDService` extends with `db.getRepository(Entity)`
+2. Code works immediately (zero changes!)
+3. Migrate methods incrementally to modern syntax
+4. Enjoy 94% code reduction
 
 ---
 
-## Testing
-
-```bash
-# Run all tests
-npm test
-
-# Run with coverage
-npm run test:coverage
-
-# Run performance benchmarks
-npm run usage
-
-# Run specific example
-npm run usage -- examples/auto-warming-example.ts
-```
-
-## Examples
+## ⚡ Key Features at a Glance
 
-This section provides examples from simple to complex, helping you get started quickly and gradually explore advanced features.
+| Feature | What You Get |
+|---------|--------------|
+| 🎯 **Repository Pattern (NEW!)** | TypeORM-like API with zero boilerplate. |
+| 🔄 **Lifecycle Hooks (NEW!)** | `@BeforeInsert`, `@AfterLoad`, `@BeforeUpdate`, etc. |
+| 🚀 **Automatic Caching** | Every query cached in Redis. 99%+ hit rate. <1ms response. |
+| 🧠 **Smart Invalidation** | Update `users`? We clear `posts` & `comments` too. Follows FKs. |
+| 🎯 **Auto-Warming** | ML-powered warming learns your patterns. No cold starts. |
+| 🔒 **Type-Safe** | Full TypeScript support. Autocomplete everything. |
+| 📊 **Prisma-style Operators** | `{ age: { gte: 18 }, email: { contains: '@' } }` |
+| 🔍 **Full-text Search** | Built-in inverted index for fast search. |
+| 📍 **Geo-location Search** | Find by distance with clustering. |
+| 📈 **Query Tracking** | See every query with timing. Debug in seconds. |
+| 🎨 **Beautiful Logging** | ⚡🚀✅⚠️🐌 - Know performance at a glance. |
+| 🔗 **Zero Config** | Auto-discovers schema. Maps relationships. Just works. |
 
-### 1. Hello World - Minimal Setup
+---
 
-The simplest way to get started with SqlDB:
+## 🎬 See It In Action
 
+### Traditional Approach (Complex)
 ```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
-
-// Initialize with minimal config
-const db = await createSqlDB({
-  mariadb: {
-    host: 'localhost',
-    user: 'root',
-    password: 'password',
-    database: 'mydb',
-  },
-  redis: {
-    host: 'localhost',
-  },
-});
-
-// Query users - automatically cached!
-const users = await (db as any).users.findMany();
-console.log('Found users:', users.length);
+// Manual cache management 😰
+const cacheKey = `users:${status}:${page}`;
+let users = await redis.get(cacheKey);
+if (!users) {
+  users = await db.query('SELECT * FROM users WHERE status = ?', [status]);
+  await redis.set(cacheKey, JSON.stringify(users), 'EX', 60);
+  // Hope you remembered all the cache keys to invalidate...
+} else {
+  users = JSON.parse(users);
+}
 
-await db.close();
+// Update user - manual cache invalidation 😰
+await db.query('UPDATE users SET name = ? WHERE id = ?', [name, id]);
+await redis.del('users:all');
+await redis.del('users:active');
+await redis.del(`users:${id}`);
+await redis.del('posts:*'); // Related posts?
+// Did I forget any keys? 🤔
 ```
 
-**What this does:**
-- Connects to MariaDB and Redis
-- Auto-discovers all tables in your database
-- Enables caching with smart defaults (60s TTL)
-- Provides simple CRUD operations
-
----
-
-### 2. Basic CRUD Operations
-
-Learn all the basic operations with caching:
-
+### SqlDB Approach (Simple + Fast)
 ```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
-
-const db = await createSqlDB({
-  mariadb: { host: 'localhost', user: 'root', password: 'password', database: 'mydb' },
-  redis: { host: 'localhost' },
-  cache: {
-    enabled: true,
-    defaultTTL: 60,
-    invalidateOnWrite: true, // Auto-clear cache on INSERT/UPDATE/DELETE
-  },
-});
+// Repository pattern with auto-caching ✨
+const userRepo = db.getRepository(User);
+const users = await userRepo.find({ where: { status: 'active' } });
+// First call: 200ms (database)
+// Next calls: <1ms (cache)
 
-// READ operations (cached automatically)
-const allUsers = await (db as any).users.findMany();
-const activeUsers = await (db as any).users.findMany({ status: 'active' });
-const user = await (db as any).users.findById(1);
-const count = await (db as any).users.count({ status: 'active' });
+// Update with cascade invalidation ✨
+await userRepo.updateById(1, { name: 'Jane' });
+// Automatically clears:
+// ✓ All user queries
+// ✓ All post queries (has user_id FK)
+// ✓ All comment queries (has post_id → user_id FK)
+// Zero stale data. Zero manual work.
+```
 
-// CREATE operations (invalidates cache)
-const newUser = await (db as any).users.insertOne({
-  name: 'John Doe',
-  email: 'john@example.com',
-});
+**That's it.** No cache keys. No invalidation logic. No stale data bugs at 3am.
 
-// UPDATE operations (invalidates cache)
-await (db as any).users.updateById(1, { status: 'verified' });
-await (db as any).users.updateMany({ status: 'pending' }, { status: 'active' });
+---
 
-// DELETE operations (invalidates cache)
-await (db as any).users.deleteById(1);
-await (db as any).users.deleteMany({ status: 'inactive' });
+## 📊 The Results Speak for Themselves
 
-// Check cache performance
-const stats = db.getCacheManager().getStats();
-console.log('Cache hit rate:', stats.hitRate);
+<table>
+<tr>
+<td width="50%">
 
-await db.close();
+**Before SqlDB** 😰
+```
+Average response:     250ms
+Database CPU:         85%
+Cache hit rate:       0%
+Stale data bugs:      Weekly
+Boilerplate code:     800+ lines
+Developer happiness:  😫
 ```
 
-**New concepts:**
-- Automatic cache invalidation on writes
-- Multiple find/update/delete methods
-- Cache statistics monitoring
+</td>
+<td width="50%">
+
+**After SqlDB** 🎉
+```
+Average response:     <1ms  (250x faster ⚡)
+Database CPU:         15%  (85% reduction)
+Cache hit rate:       99%+ (automatic)
+Stale data bugs:      Never (intelligent invalidation)
+Boilerplate code:     0 lines (built-in)
+Developer happiness:  😍
+```
 
-**See:** [basic-usage.ts](./examples/basic-usage.ts)
+</td>
+</tr>
+</table>
 
 ---
 
-### 3. Type-Safe Queries with TypeScript
+## 🆕 NEW: Repository Pattern Features
 
-Add full type safety to your queries:
+### Lifecycle Hooks
+
+Execute code at specific points in an entity's lifecycle:
 
 ```typescript
-import { createSqlDB, SqlDBWithTables } from '@bhushanpawar/sqldb';
+@Entity()
+class User {
+  @BeforeInsert()
+  @BeforeUpdate()
+  async hashPassword() {
+    if (this.password) {
+      this.password = await bcrypt.hash(this.password, 10);
+    }
+  }
 
-// Define your schema
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  status: 'active' | 'inactive' | 'verified';
-  created_at: Date;
-}
+  @AfterLoad()
+  maskEmail() {
+    this.email = this.email.replace(/(.{2}).*(@.*)/, '$1***$2');
+  }
 
-interface Order {
-  id: number;
-  user_id: number;
-  total: number;
-  status: string;
+  @AfterLoad()
+  calculateFullName() {
+    this.fullName = `${this.firstName} ${this.lastName}`;
+  }
 }
+```
 
-interface MySchema {
-  users: User;
-  orders: Order;
-}
+**Available Hooks:**
+- `@AfterLoad` - After entity loaded from DB
+- `@BeforeInsert` / `@AfterInsert` - Before/after insert
+- `@BeforeUpdate` / `@AfterUpdate` - Before/after update
+- `@BeforeDelete` / `@AfterDelete` - Before/after delete
 
-// Create typed DB instance
-type MyDB = SqlDBWithTables<MySchema>;
-const db = await createSqlDB(config) as MyDB;
+### BaseRepository<T> API
 
-// Full type safety!
-const users = await db.users.findMany();           // Type: User[]
-const user = await db.users.findById(1);           // Type: User | null
-await db.users.updateById(1, { status: 'verified' }); // Type-checked!
+Type-safe repository with automatic entity management:
 
-// TypeScript will catch errors
-// await db.users.updateById(1, { invalid: 'field' }); // ❌ Error!
-```
+```typescript
+const userRepo = db.getRepository(User);
 
-**New concepts:**
-- TypeScript interfaces for your schema
-- Compile-time type checking
-- Auto-completion in your IDE
+// Create
+const user = await userRepo.save({ email: 'john@example.com' });
+const users = await userRepo.saveMany([{ email: 'a@b.com' }, { email: 'c@d.com' }]);
 
-**See:** [typed-tables-example.ts](./examples/typed-tables-example.ts), [DYNAMIC_TABLE_ACCESS.md](./docs/DYNAMIC_TABLE_ACCESS.md)
+// Read
+const one = await userRepo.findOne({ where: { email: 'john@example.com' } });
+const many = await userRepo.find({ where: { status: 'active' }, limit: 10 });
+const byId = await userRepo.findById(123);
+const all = await userRepo.findAll();
 
----
+// Update
+const updated = await userRepo.update({ status: 'pending' }, { status: 'active' });
+const updatedOne = await userRepo.updateById(123, { status: 'verified' });
+
+// Delete
+const deleted = await userRepo.delete({ status: 'inactive' });
+const deletedOne = await userRepo.deleteById(123);
 
-### 4. Query Tracking & Performance Monitoring
+// Helpers
+const count = await userRepo.count({ status: 'active' });
+const exists = await userRepo.exists({ email: 'john@example.com' });
+const results = await userRepo.search('john', { fields: ['name', 'email'] });
+```
 
-Track query performance with correlation IDs:
+### Prisma-style Query Operators
 
 ```typescript
-import { createSqlDB, generateQueryId } from '@bhushanpawar/sqldb';
-
-const db = await createSqlDB({
-  mariadb: { /* config */ },
-  redis: { /* config */ },
-  logging: { level: 'info' },
+// Number operators
+const adults = await userRepo.find({
+  where: { age: { gte: 18, lte: 65 } }
 });
 
-// Generate a correlation ID (e.g., per HTTP request)
-const correlationId = generateQueryId();
-
-// All queries with same correlationId are tracked together
-const users = await (db as any).users.findMany(
-  { status: 'active' },
-  { correlationId }
-);
-
-const count = await (db as any).users.count(
-  { status: 'active' },
-  correlationId
-);
+// String operators
+const gmailUsers = await userRepo.find({
+  where: { email: { contains: '@gmail.com', mode: 'insensitive' } }
+});
 
-// Analyze performance
-const queries = db.getQueries(correlationId);
-queries.forEach(q => {
-  console.log({
-    table: q.sql.match(/FROM (\w+)/)?.[1],
-    executionTime: q.executionTimeMs + 'ms',
-    cached: q.resultCount,
-  });
+// Array operators
+const activeOrPending = await userRepo.find({
+  where: { status: { in: ['active', 'pending'] } }
 });
 
-// Calculate total time
-const totalTime = queries.reduce((sum, q) => sum + (q.executionTimeMs || 0), 0);
-console.log(`Total query time: ${totalTime}ms`);
+// Logical operators
+const filtered = await userRepo.find({
+  where: {
+    AND: [
+      { status: 'active' },
+      { OR: [{ role: 'admin' }, { role: 'moderator' }] }
+    ]
+  }
+});
 
-// Clean up
-db.clearQueries(correlationId);
+// Null checks
+const noAvatar = await userRepo.find({
+  where: { avatarUrl: { isNull: true } }
+});
 ```
 
-**New concepts:**
-- Correlation IDs for request tracking
-- Query performance analysis
-- Debugging slow requests
+### Relation Loading
 
-**Use cases:**
-- HTTP request tracking
-- Performance monitoring
-- Identifying slow queries
+```typescript
+@Entity()
+class User {
+  @OneToMany(() => Order, order => order.user)
+  orders: Order[];
+}
 
-**See:** [query-tracking.ts](./examples/query-tracking.ts), [QUERY_TRACKING.md](./docs/QUERY_TRACKING.md)
+// Load with relations (batched to avoid N+1)
+const users = await userRepo.find({
+  where: { status: 'active' },
+  withRelations: { dependents: ['orders'] }
+});
 
----
+users.forEach(user => {
+  console.log(`${user.name} has ${user.orders.length} orders`);
+});
+```
 
-### 5. Enhanced Query Logging
+### Schema Registry (No Decorators!)
 
-Monitor all database queries with detailed logging:
+Don't want decorators? Use the schema registry instead:
 
 ```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
+import { defineEntitySchema } from '@bhushanpawar/sqldb';
 
-const db = await createSqlDB({
-  mariadb: {
-    host: 'localhost',
-    user: 'root',
-    password: 'password',
-    database: 'mydb',
-    logging: true, // Enable query logging
+class User {
+  userId: string;
+  email: string;
+  password: string;
+}
+
+defineEntitySchema(User, {
+  tableName: 'users',
+  columns: {
+    userId: { primary: true },
+    email: {},
+    password: {},
   },
-  redis: { host: 'localhost' },
-  logging: { level: 'info' },
 });
 
-// Run queries - they'll be logged automatically
-const users = await (db as any).users.findMany({ status: 'active' });
-const count = await (db as any).users.count({});
-
-// Console output shows:
-// ✅ SELECT on users - 45ms - 10 rows
-// 🚀 SELECT on users - 12ms - 1 rows
-// ⚠️  SELECT on orders - 250ms - 100 rows  (shows SQL for slow queries)
+// Use same repository API
+const repo = db.getRepository(User);
 ```
 
-**Logging features:**
-- Query type (SELECT, INSERT, UPDATE, DELETE)
-- Table name extraction
-- Execution time with performance emojis
-- Automatic SQL display for slow queries (>200ms)
-
-**Performance emojis:**
-- ⚡ Very fast (<10ms)
-- 🚀 Fast (<50ms)
-- ✅ Good (<200ms)
-- ⚠️ Slow (<500ms)
-- 🐌 Very slow (≥500ms)
-
-**See:** [query-logging-example.ts](./examples/query-logging-example.ts), [QUERY_LOGGING.md](./docs/QUERY_LOGGING.md)
+📖 **[Repository Pattern Guide](./docs/REPOSITORY_PATTERN.md)** | **[Before/After Comparison](./examples/before-after-comparison.md)** | **[Working Example](./examples/repository-pattern-example.ts)**
 
 ---
 
-### 6. Smart Cache Invalidation with Relations
+## 🚀 Installation & Setup
+
+```bash
+npm install @bhushanpawar/sqldb mariadb redis
+```
 
-Automatic cascade invalidation based on foreign keys:
+### Basic Setup
 
 ```typescript
-// Database schema:
-// users (id, name)
-// posts (id, user_id, title)       ← FK to users
-// comments (id, post_id, content)  ← FK to posts
+import { createSqlDB } from '@bhushanpawar/sqldb';
 
 const db = await createSqlDB({
-  mariadb: { /* config */ },
-  redis: { /* config */ },
+  mariadb: {
+    host: 'localhost',
+    user: 'root',
+    password: 'password',
+    database: 'mydb',
+  },
+  redis: {
+    host: 'localhost',
+  },
   cache: {
     enabled: true,
-    invalidateOnWrite: true,
-    cascadeInvalidation: true, // Enable cascade invalidation
-  },
-  discovery: {
-    autoDiscover: true, // Auto-discover relationships
+    defaultTTL: 60,
   },
 });
 
-// When you update a user...
-await (db as any).users.updateById(1, { name: 'Updated Name' });
-
-// SqlDB automatically invalidates:
-// 1. users:* (direct table)
-// 2. posts:* (depends on users via user_id)
-// 3. comments:* (depends on posts via post_id)
+// Use repository pattern
+const userRepo = db.getRepository(User);
+const users = await userRepo.find({ where: { status: 'active' } });
 
-// View the dependency graph
-const graph = db.getDependencyGraph();
-const dependencies = graph.getDependencies('users');
-console.log('Tables that depend on users:', dependencies); // ['posts', 'comments']
+// Or use table operations directly
+const users = await db.users.findMany({ status: 'active' });
 
-// Manual invalidation with cascade
-const invalidationManager = db.getInvalidationManager();
-await invalidationManager.invalidateTable('users', { cascade: true });
+await db.close();
 ```
 
-**New concepts:**
-- Automatic relationship discovery
-- Cascade cache invalidation
-- Dependency graph visualization
-
-**See:** [relationships-example.ts](./examples/relationships-example.ts)
-
----
-
-### 7. Singleton Pattern for Production
-
-Share a single SqlDB instance across your entire application:
+### Production Setup (Singleton Pattern)
 
 ```typescript
-// db.ts - Initialize once at app startup
+// db.ts - Initialize once
 import { createSqlDB } from '@bhushanpawar/sqldb';
 
-export const initializeDB = async () => {
+export const initDB = async () => {
   const db = await createSqlDB({
     mariadb: { /* config */ },
     redis: { /* config */ },
-    cache: { enabled: true },
-  }, { singleton: true }); // Enable singleton mode
-
+  }, { singleton: true }); // Enable singleton
   return db;
 };
 
 // server.ts - Initialize at startup
-import { initializeDB } from './db';
-
-const db = await initializeDB();
-console.log('Database initialized');
+await initDB();
 
 // userController.ts - Access anywhere
 import { getSqlDB } from '@bhushanpawar/sqldb';
 
-export const getUsers = async () => {
-  const db = getSqlDB(); // Returns the same instance
-  return await (db as any).users.findMany();
-};
+const db = getSqlDB(); // Same instance
+const userRepo = db.getRepository(User);
+```
 
-// orderController.ts - Access anywhere
-import { getSqlDB } from '@bhushanpawar/sqldb';
+---
 
-export const getOrders = async (userId: number) => {
-  const db = getSqlDB(); // Same instance
-  return await (db as any).orders.findMany({ user_id: userId });
-};
-```
+## ⚡ Core Features
 
-**Benefits:**
-- Single connection pool shared across app
-- No need to pass `db` around
-- Prevents multiple connections
-- Clean architecture
+### 1. Automatic Caching
 
-**See:** [singleton-example.ts](./examples/singleton-example.ts), [SINGLETON_PATTERN.md](./docs/SINGLETON_PATTERN.md)
+Every query is automatically cached in Redis:
 
----
+```typescript
+// First call: queries database (200ms)
+const users = await db.users.findMany({ status: 'active' });
+
+// Next 100 calls: served from cache (<1ms)
+```
 
-### 8. Cache Warming for Better Performance
+### 2. Intelligent Cache Invalidation
 
-Pre-warm cache on startup for frequently accessed queries:
+Updates automatically invalidate related tables by following foreign keys:
 
 ```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
+// Update a user
+await db.users.updateById(1, { name: 'Jane' });
+
+// SqlDB automatically clears:
+// ✓ users:* cache
+// ✓ posts:* cache (has user_id FK)
+// ✓ comments:* cache (has post_id FK → user_id FK)
+```
+
+### 3. Auto-Warming
 
+ML-powered cache warming learns your query patterns:
+
+```typescript
 const db = await createSqlDB({
-  mariadb: { /* config */ },
-  redis: { /* config */ },
-  cache: { enabled: true },
+  warming: {
+    enabled: true,
+    intervalMs: 60000,      // Warm every 60 seconds
+    topQueriesPerTable: 10, // Warm top 10 queries per table
+  },
 });
 
-// Warm cache for specific queries
-await (db as any).users.warmCache({ status: 'active' });
-await (db as any).products.warmCache({ featured: true });
-
-// Warm cache with related tables (follows foreign keys)
-await (db as any).orders.warmCacheWithRelations(
-  { status: 'pending' },
-  {
-    depth: 1,                    // How deep to traverse relationships
-    warmDependents: true,        // Warm tables that reference this table
-    warmDependencies: true,      // Warm tables this table references
-    correlationId: 'startup-warming',
-  }
-);
+// After deployment, your cache is already warm ✨
+```
 
-// This warms:
-// - orders (main table)
-// - users (orders.user_id → users.id)
-// - order_items (order_items.order_id → orders.id)
-// - products (order_items.product_id → products.id)
+### 4. Full-text Search
 
-// Now these queries are instant (served from cache)
-const orders = await (db as any).orders.findMany({ status: 'pending' });
-const user = await (db as any).users.findById(orders[0].user_id);
+Built-in inverted index for fast search:
+
+```typescript
+const userRepo = db.getRepository(User);
+const results = await userRepo.search('john', {
+  fields: ['name', 'email'],
+  fuzzy: true,
+  limit: 20,
+});
 ```
 
-**Use cases:**
-- Application startup optimization
-- Pre-loading frequently accessed data
-- Improving first request performance
+### 5. Geo-location Search
 
-**See:** Cache warming section above
+Find entities by distance:
 
----
+```typescript
+const providers = await db.providers.findMany({
+  latitude: 40.7128,
+  longitude: -74.0060,
+  radius: 10, // 10km radius
+});
+```
 
-### 9. Auto-Warming - Intelligent Background Cache Warming
+### 6. Query Tracking
 
-Automatically warm cache for your hottest queries:
+Track every query with correlation IDs:
 
 ```typescript
-import { createSqlDB } from '@bhushanpawar/sqldb';
+import { generateQueryId } from '@bhushanpawar/sqldb';
 
-const db = await createSqlDB({
-  mariadb: { /* config */ },
-  redis: { /* config */ },
-  cache: { enabled: true },
-  warming: {
-    enabled: true,                    // Enable auto-warming
-    intervalMs: 60000,                // Warm every 60 seconds
-    topQueriesPerTable: 10,           // Warm top 10 queries per table
-    minAccessCount: 3,                // Must be accessed at least 3 times
-    maxStatsAge: 3600000,             // Consider queries from last hour
-    useSeperatePool: true,            // Use separate connection pool
-    warmingPoolSize: 2,               // 2 connections for warming
-    trackInDatabase: true,            // Persist stats in database
-    statsTableName: '__sqldb_query_stats',
-
-    // Callbacks
-    onWarmingComplete: (stats) => {
-      console.log('Warming complete:', {
-        queriesWarmed: stats.queriesWarmed,
-        cacheHitRateBefore: (stats.cacheHitRateBefore * 100).toFixed(1) + '%',
-        cacheHitRateAfter: (stats.cacheHitRateAfter * 100).toFixed(1) + '%',
-      });
-    },
-    onWarmingError: (error) => {
-      console.error('Warming error:', error.message);
-    },
-  },
-});
+const correlationId = generateQueryId();
+const users = await db.users.findMany({ status: 'active' }, { correlationId });
 
-// Use your app normally - auto-warming tracks which queries are hot
-for (let i = 0; i < 10; i++) {
-  const users = await (db as any).users.findMany({ status: 'active' });
-  const orders = await (db as any).orders.findMany({ status: 'pending' });
-  await new Promise(r => setTimeout(r, 1000));
-}
+// Get all queries for this request
+const queries = db.getQueries(correlationId);
+const totalTime = queries.reduce((sum, q) => sum + q.executionTimeMs, 0);
+console.log(`Total query time: ${totalTime}ms`);
+```
 
-// After 60 seconds, auto-warming will:
-// 1. Identify the most frequently accessed queries
-// 2. Pre-warm them in the background
-// 3. Improve cache hit rate automatically
-
-// Check warming stats
-const warmingStats = db.getWarmingStats();
-console.log('Latest warming:', {
-  queriesWarmed: warmingStats.queriesWarmed,
-  totalTime: warmingStats.totalTimeMs + 'ms',
-  perTable: warmingStats.tables,
-});
+### 7. Beautiful Query Logging
 
-// Manually trigger warming
-const manualStats = await db.warmCache();
-console.log('Manual warming:', manualStats.queriesWarmed, 'queries');
+```
+✅ SELECT on users - 45ms - 10 rows
+🚀 SELECT on orders - 12ms - 5 rows (cached)
+⚠️  SELECT on products - 250ms - 100 rows
+   SQL: SELECT * FROM products WHERE category = 'electronics'
 ```
 
-**How it works:**
-1. Tracks query frequency per table in `__sqldb_query_stats` table
-2. Every X seconds, identifies the hottest queries
-3. Pre-warms them using a separate connection pool (no impact on app)
-4. Persists stats across restarts
+Performance at a glance: ⚡ <10ms | 🚀 <50ms | ✅ <200ms | ⚠️ <500ms | 🐌 ≥500ms
 
-**Benefits:**
-- Automatic - no manual configuration
-- Intelligent - only warms frequently used queries
-- Non-blocking - uses separate connection pool
-- Persistent - stats survive app restarts
-- Observable - callbacks for monitoring
+---
 
-**See:** [auto-warming-example.ts](./examples/auto-warming-example.ts), [AUTO_WARMING.md](./docs/AUTO_WARMING.md)
+## 📖 Comparison with Other Libraries
+
+### SqlDB vs TypeORM
+
+| Feature | SqlDB | TypeORM |
+|---------|-------|---------|
+| **Repository Pattern** | ✅ | ✅ |
+| **Lifecycle Hooks** | ✅ | ✅ |
+| **Entity Decorators** | ✅ | ✅ |
+| **Query Builder** | ✅ Prisma-style | ⚠️ Different |
+| **Automatic Caching** | ✅ Redis, FK-aware | ❌ |
+| **Case Conversion** | ✅ Automatic | ❌ Manual |
+| **Schema Registry** | ✅ No decorators! | ❌ |
+| **Full-text Search** | ✅ Built-in | ⚠️ DB only |
+| **Auto-warming** | ✅ Built-in | ❌ |
+| **Migrations** | ⚠️ External | ✅ Built-in |
+
+### SqlDB vs Prisma
+
+| Feature | SqlDB | Prisma |
+|---------|-------|--------|
+| **Type Safety** | ✅ | ✅ |
+| **Query Operators** | ✅ Inspired by Prisma | ✅ |
+| **Repository Pattern** | ✅ TypeORM-like | ❌ |
+| **Automatic Caching** | ✅ Redis | ❌ |
+| **Code Generation** | ❌ No need | ✅ Required |
+| **Migrations** | ⚠️ External | ✅ Built-in |
+| **Performance** | ⚡ Sub-ms (cached) | ⚡ Fast |
 
 ---
 
-### 10. Complete Production Example
+## 📚 Documentation
 
-A real-world production setup with all features:
+### Getting Started
+- **[Repository Pattern Guide](./docs/REPOSITORY_PATTERN.md)** - Complete guide with 50+ examples
+- **[Before/After Comparison](./examples/before-after-comparison.md)** - Real-world 800→50 line reduction
+- **[Repository Example](./examples/repository-pattern-example.ts)** - Working code
 
-```typescript
-import { createSqlDB, generateQueryId } from '@bhushanpawar/sqldb';
+### Core Guides
+- **[Query Tracking](./docs/QUERY_TRACKING.md)** - Track and debug queries
+- **[Query Logging](./docs/QUERY_LOGGING.md)** - Beautiful performance logs
+- **[Auto-Warming](./docs/AUTO_WARMING.md)** - Intelligent cache warming
+- **[Singleton Pattern](./docs/SINGLETON_PATTERN.md)** - Production setup
+- **[Dynamic Table Access](./docs/DYNAMIC_TABLE_ACCESS.md)** - Type-safe table access
+
+### Advanced Topics
+- **[Decorators Guide](./docs/DECORATORS.md)** - Full decorator reference
+- **[Schema Definition](./docs/SCHEMA_DEFINITION.md)** - Schema registry (no decorators)
+- **[Performance Testing](./docs/PERFORMANCE_TESTING.md)** - Benchmark your app
+- **[Performance Results](./docs/PERFORMANCE_RESULTS.md)** - Real-world benchmarks
+- **[Relation Loading Performance](./docs/PERFORMANCE_RELATIONS.md)** - Optimized relation queries
+- **[Schema Generator](./docs/SCHEMA_GENERATOR.md)** - Generate TypeScript schemas
+
+---
+
+## 🎯 Examples
+
+### Simple Examples
+- [basic-usage.ts](./examples/basic-usage.ts) - Basic CRUD operations
+- [repository-pattern-example.ts](./examples/repository-pattern-example.ts) - **NEW!** Repository pattern
+- [typed-tables-example.ts](./examples/typed-tables-example.ts) - TypeScript type safety
 
-// Production configuration
+### Advanced Examples
+- [query-tracking.ts](./examples/query-tracking.ts) - Query tracking with correlation IDs
+- [relationships-example.ts](./examples/relationships-example.ts) - Smart cache invalidation
+- [auto-warming-example.ts](./examples/auto-warming-example.ts) - Auto-warming system
+- [singleton-example.ts](./examples/singleton-example.ts) - Singleton pattern
+
+---
+
+## 🔧 Configuration
+
+### Complete Configuration
+
+```typescript
 const db = await createSqlDB({
+  // Database connection
   mariadb: {
-    host: process.env.DB_HOST,
-    port: parseInt(process.env.DB_PORT || '3306'),
-    user: process.env.DB_USER,
-    password: process.env.DB_PASSWORD,
-    database: process.env.DB_NAME,
-    connectionLimit: 20,
-    acquireTimeout: 10000,
-    connectTimeout: 10000,
-    logging: process.env.NODE_ENV === 'development',
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'password',
+    database: 'mydb',
+    connectionLimit: 10,
   },
+
+  // Redis cache
   redis: {
-    host: process.env.REDIS_HOST,
-    port: parseInt(process.env.REDIS_PORT || '6379'),
-    password: process.env.REDIS_PASSWORD,
+    host: 'localhost',
+    port: 6379,
     keyPrefix: 'myapp:',
   },
+
+  // Caching
   cache: {
     enabled: true,
-    defaultTTL: 300,              // 5 minutes
-    maxKeys: 10000,
+    defaultTTL: 60,
     invalidateOnWrite: true,
     cascadeInvalidation: true,
   },
+
+  // Schema discovery
   discovery: {
     autoDiscover: true,
-    excludedTables: ['migrations', 'temp_*'],
-    maxGraphDepth: 3,
-    refreshInterval: 3600000,     // Refresh schema every hour
+    refreshInterval: 3600000,
   },
+
+  // Auto-warming
   warming: {
-    enabled: process.env.NODE_ENV === 'production',
-    intervalMs: 300000,           // Warm every 5 minutes
-    topQueriesPerTable: 20,
-    minAccessCount: 5,
-    useSeperatePool: true,
-    trackInDatabase: true,
-    onWarmingComplete: (stats) => {
-      logger.info('Cache warming complete', {
-        queriesWarmed: stats.queriesWarmed,
-        hitRateImprovement:
-          ((stats.cacheHitRateAfter - stats.cacheHitRateBefore) * 100).toFixed(2) + '%',
-      });
-    },
-  },
-  logging: {
-    level: process.env.LOG_LEVEL || 'info',
-    logger: (level, message, meta) => {
-      // Use your preferred logger (Winston, Pino, etc.)
-      logger[level](message, meta);
-    },
+    enabled: true,
+    intervalMs: 60000,
+    topQueriesPerTable: 10,
   },
-}, { singleton: true });
-
-// Express middleware for request tracking
-app.use((req, res, next) => {
-  req.correlationId = generateQueryId();
-  res.on('finish', () => {
-    const queries = db.getQueries(req.correlationId);
-    const totalTime = queries.reduce((sum, q) => sum + (q.executionTimeMs || 0), 0);
-
-    // Log slow requests
-    if (totalTime > 1000) {
-      logger.warn('Slow request', {
-        path: req.path,
-        method: req.method,
-        totalTime,
-        queryCount: queries.length,
-        correlationId: req.correlationId,
-      });
-    }
-
-    db.clearQueries(req.correlationId);
-  });
-  next();
-});
-
-// Health check endpoint
-app.get('/health', async (req, res) => {
-  const health = await db.healthCheck();
-  const stats = db.getCacheManager().getStats();
-
-  res.json({
-    status: health.mariadb && health.redis ? 'healthy' : 'unhealthy',
-    ...health,
-    cache: stats,
-    timestamp: new Date().toISOString(),
-  });
-});
 
-// Graceful shutdown
-process.on('SIGTERM', async () => {
-  logger.info('SIGTERM received, closing connections...');
-  await db.close();
-  process.exit(0);
+  // Search
+  search: {
+    enabled: true,
+    invertedIndex: { enabled: true },
+    geo: { enabled: true },
+  },
 });
 ```
 
-**Production best practices:**
-- Environment-based configuration
-- Connection pooling optimization
-- Schema refresh scheduling
-- Auto-warming in production only
-- Request tracking middleware
-- Performance monitoring
-- Health checks
-- Graceful shutdown
-
 ---
 
-### More Examples
-
-For complete working examples, see the [examples](./examples) directory:
-
-- [basic-usage.ts](./examples/basic-usage.ts) - Basic CRUD operations
-- [typed-tables-example.ts](./examples/typed-tables-example.ts) - TypeScript type safety
-- [query-tracking.ts](./examples/query-tracking.ts) - Query tracking with correlation IDs
-- [query-logging-example.ts](./examples/query-logging-example.ts) - Enhanced query logging
-- [relationships-example.ts](./examples/relationships-example.ts) - Smart cache invalidation
-- [singleton-example.ts](./examples/singleton-example.ts) - Singleton pattern
-- [auto-warming-example.ts](./examples/auto-warming-example.ts) - Auto-warming system
-- [hooks-example.ts](./examples/hooks-example.ts) - Custom hooks and extensibility
-
-## Documentation
+## 🚀 Performance Benchmarks
 
-### Core Guides
-- 📖 [Query Tracking Guide](./QUERY_TRACKING.md) - Track and debug queries
-- 📊 [Query Logging](./QUERY_LOGGING.md) - Beautiful query logs with performance metrics
-- 🎯 [Auto-Warming](./AUTO_WARMING.md) - Intelligent cache warming system
-- 🎭 [Singleton Pattern](./docs/SINGLETON_PATTERN.md) - Production-ready singleton setup
-- 🔗 [Dynamic Table Access](./docs/DYNAMIC_TABLE_ACCESS.md) - Type-safe table access
-- 🗺️ [Schema Generator](./SCHEMA_GENERATOR.md) - Generate TypeScript schemas
+Real-world results from production:
 
-### Advanced Topics
-- ⚡ [Performance Testing](./PERFORMANCE_TESTING.md) - Benchmark your app
-- 📈 [Performance Results](./docs/PERFORMANCE_RESULTS.md) - Real-world benchmarks
-- 🔄 [CLI Usage](./CLI_USAGE.md) - Command-line tools
-- 📝 [Changelog](./CHANGELOG_QUERY_TRACKING.md) - What's new
+| Metric | Value | Impact |
+|--------|-------|--------|
+| **Cache Hit Rate** | 99.2% | Only 1 in 100 queries hits DB |
+| **P50 Response Time** | <1ms | Instant for users |
+| **P99 Response Time** | 12ms | Fast even at extremes |
+| **Throughput** | 10,000+ qps | Handle Black Friday traffic |
+| **DB CPU Reduction** | 85% ↓ | Save $$$$ on database |
+| **Code Reduction** | 94% ↓ | 800 lines → 50 lines |
 
 ---
 
-## Why You'll Love This
+## 🤝 Migration Guide
 
-### Developer Experience
-- ✅ **Zero Learning Curve** - If you know SQL, you know SqlDB
-- ✅ **TypeScript First** - Full type safety with autocomplete
-- ✅ **Beautiful Logs** - See performance at a glance
-- ✅ **Debugging Tools** - Find slow queries in seconds
-- ✅ **No Surprises** - Predictable, well-documented behavior
+### From TypeORM
 
-### Performance
-- ✅ **Instant Queries** - Sub-millisecond response times
-- ✅ **Smart Caching** - 99%+ hit rate without tuning
-- ✅ **Auto Warming** - No cold starts ever
-- ✅ **Scale Effortlessly** - Handle 10,000+ req/s
-
-### Reliability
-- ✅ **Battle-Tested** - Running in production
-- ✅ **No Stale Data** - Intelligent cache invalidation
-- ✅ **Connection Pooling** - Never run out of connections
-- ✅ **Health Checks** - Know when things break
+```typescript
+// Before (TypeORM)
+@Entity()
+class User {
+  @PrimaryGeneratedColumn()
+  id: number;
 
----
+  @Column()
+  email: string;
+}
 
-## Roadmap
+const userRepo = connection.getRepository(User);
+const users = await userRepo.find({ where: { status: 'active' } });
 
-Vote for features you want! 🗳️
+// After (SqlDB) - Almost identical!
+@Entity()
+class User {
+  @PrimaryColumn()
+  userId: string;
 
-### Coming Soon
-- [ ] Support for complex WHERE clauses (IN, LIKE, BETWEEN)
-- [ ] Built-in pagination with cursor support
-- [ ] Redis Cluster support
-- [ ] Query result transformers
-- [ ] Prisma-like schema migrations
-- [ ] Admin UI for cache monitoring
-- [ ] GraphQL integration
-- [ ] Read replicas support
-- [ ] Automatic query optimization suggestions
+  @Column()
+  email: string;
+}
 
-### Under Consideration
-- [ ] MongoDB adapter
-- [ ] PostgreSQL adapter
-- [ ] Write-through caching
-- [ ] Distributed tracing integration
-- [ ] Real-time query analytics dashboard
+const userRepo = db.getRepository(User);
+const users = await userRepo.find({ where: { status: 'active' } });
+```
 
-**Want a feature?** [Open an issue](https://github.com/erBhushanPawar/sqldb/issues) and let's discuss!
+**What's different:**
+- ✅ Automatic Redis caching
+- ✅ Automatic cache invalidation
+- ✅ Prisma-style operators: `{ age: { gte: 18 } }`
+- ✅ Auto-warming
+- ✅ Full-text search built-in
 
----
+### From Raw MariaDB
 
-## Contributing
+```typescript
+// Before (15 lines of boilerplate)
+const conn = await pool.getConnection();
+try {
+  const users = await conn.query('SELECT * FROM users WHERE status = ?', ['active']);
+  return users;
+} finally {
+  conn.release();
+}
 
-We love contributions! 🎉
+// After (1 line with superpowers)
+const users = await db.users.findMany({ status: 'active' });
+```
 
-### How to Contribute
-1. 🍴 Fork the repo
-2. 🌿 Create a feature branch (`git checkout -b feature/amazing`)
-3. ✨ Make your changes
-4. ✅ Add tests
-5. 📝 Update docs
-6. 🚀 Submit a PR
+**What you gain:**
+- ✅ 10x less code
+- ✅ 20x faster (caching)
+- ✅ Type-safe
+- ✅ Auto cache invalidation
+- ✅ No connection management
 
-### Development Setup
-```bash
-git clone https://github.com/erBhushanPawar/sqldb.git
-cd sqldb
-npm install
-npm test
-```
+---
 
-### Areas We Need Help
-- 📚 Documentation improvements
-- 🐛 Bug fixes
-- ✨ New features
-- 🧪 More test coverage
-- 📊 Performance optimizations
-- 🌍 Real-world use case examples
+## 🗺️ Roadmap
+
+### Recently Added ✅
+- ✅ Repository pattern (TypeORM-like)
+- ✅ Lifecycle hooks decorators
+- ✅ Prisma-style query operators
+- ✅ EntityManager
+- ✅ Schema registry (no decorators)
+
+### Coming Soon 🚀
+- [ ] Transactions support
+- [ ] Single-query JSON aggregation for relations
+- [ ] Soft deletes (`@SoftDelete`)
+- [ ] Custom repositories
+- [ ] Schema migrations CLI
+- [ ] GraphQL integration
 
 ---
 
-## Support
+## 💬 Support
 
 ### Getting Help
-- 📖 **Documentation**: You're reading it!
-- 💬 **GitHub Issues**: [Report bugs or request features](https://github.com/erBhushanPawar/sqldb/issues)
+- 📖 **Documentation**: See [docs](./docs) folder
+- 💬 **GitHub Issues**: [Report bugs or request features](https://github.com/bhushanpawar/sqldb/issues)
 - 📧 **Email**: For private inquiries
 
 ### Show Your Support
@@ -2090,13 +815,13 @@ If SqlDB saves you time and money:
 - ⭐ **Star this repo** on GitHub
 - 🐦 **Tweet** about your experience
 - 📝 **Write** a blog post
-- 💬 **Tell** a friend who's struggling with caching
+- 💬 **Tell** a friend
 
 ---
 
-## License
+## 📄 License
 
-MIT © [Bhushan Pawar](https://github.com/erBhushanPawar)
+MIT © [Bhushan Pawar](https://github.com/bhushanpawar)
 
 Free for personal and commercial use. Do whatever you want with it.
 
@@ -2104,7 +829,9 @@ Free for personal and commercial use. Do whatever you want with it.
 
 <div align="center">
 
-**Made with ❤️ for developers who hate writing cache logic**
+**Made with ❤️ for developers who hate writing boilerplate**
+
+**Stop writing cache logic. Start shipping features.**
 
 [⬆ Back to Top](#bhushanpawarsqldb)