@dockstat/sqlite-wrapper 1.0.0 → 1.1.0

package/README.md

@@ -1,138 +1,212 @@
-# @dockstat/sql-wrapper
+# @dockstat/sqlite-wrapper
 
-A tiny TypeScript wrapper around Bun's `bun:sqlite` (`Database`) that gives you:
+A comprehensive TypeScript wrapper around Bun's `bun:sqlite` with type-safe table creation, advanced query building, and full SQLite feature support.
 
-* **`DB`** (default export) — open/close DB, create tables, run `PRAGMA` statements, load extensions, and get a typed `QueryBuilder<T>`.
-* **`QueryBuilder<T>`** — expressive, chainable query builder with:
+## Features
 
-  **SELECT operations:**
-  * plain equality `.where(...)`
-  * regex `.whereRgx(...)` (applied client-side)
-  * raw fragments `.whereRaw(...)` / `.whereExpr(...)`
-  * `IN` helper `.whereIn(...)`
-  * operator helper `.whereOp(...)`
-  * ordering, limit, offset, and result helpers: `all()`, `get()`, `first()`, `count()`
-
-  **INSERT operations:**
-  * single/bulk inserts `.insert(...)`
-  * conflict resolution `.insertOrIgnore(...)`, `.insertOrReplace(...)`
-
-  **UPDATE operations:**
-  * safe updates `.update(...)` (requires WHERE conditions)
-
-  **DELETE operations:**
-  * safe deletes `.delete()` (requires WHERE conditions)
-
-> **Important** — Bun's `bun:sqlite` currently doesn't provide a JS `registerFunction` to add custom SQL functions. Regex conditions added with `whereRgx()` are collected and applied **in JavaScript** after fetching rows that match the non-regex SQL conditions. See the **Performance** section below for implications.
+* **Type-safe table creation** with column helpers and comprehensive constraint support
+* **Expressive QueryBuilder** with chainable operations for SELECT, INSERT, UPDATE, DELETE
+* **Advanced WHERE conditions** including regex filtering, raw SQL, operators, and more
+* **Conflict resolution** for INSERT operations (OR IGNORE, OR REPLACE, etc.)
+* **Safety features** requiring WHERE conditions for UPDATE/DELETE operations
+* **Full SQLite support** including JSON columns, generated columns, foreign keys, and more
+* **Performance optimizations** with proper parameter binding and transaction support
 
 ---
 
-## Quick start
+## Quick Start
 
 ```ts
-import DB, { QueryBuilder } from "./db";
+import { DB, column, sql } from "@dockstat/sqlite-wrapper";
 
 interface User {
-  id: number;
+  id?: number;
   name: string;
   email: string;
   type: string;
-  created_at: number;
+  active?: boolean;
+  metadata?: object;
+  created_at?: number;
+  updated_at?: number;
 }
 
-// Create DB with PRAGMA settings and an extension
+// Create database with optimized settings
 const db = new DB("app.db", {
   pragmas: [
     ["journal_mode", "WAL"],
     ["synchronous", "NORMAL"],
-    ["foreign_keys", "ON"]
-  ],
-  loadExtensions: [
-     "/absolute/path/to/my_extension" // optional compiled SQLite extension
+    ["foreign_keys", "ON"],
+    ["cache_size", -64000]
   ]
 });
 
-// create table (object style)
-db.createTable(
-  "users",
-  {
-    id: "INTEGER PRIMARY KEY AUTOINCREMENT",
-    name: "TEXT NOT NULL",
-    email: "TEXT UNIQUE NOT NULL",
-    type: "TEXT NOT NULL",
-    created_at: "INTEGER NOT NULL DEFAULT (strftime('%s','now'))"
-  },
-  { ifNotExists: true }
-);
+// Create table with type-safe column definitions
+db.createTable("users", {
+  id: column.id(), // INTEGER PRIMARY KEY AUTOINCREMENT
+  name: column.text({ notNull: true }),
+  email: column.text({ unique: true, notNull: true }),
+  type: column.enum(["admin", "user", "guest"], { default: "user" }),
+  active: column.boolean({ default: true }),
+  metadata: column.json({ validateJson: true }),
+  created_at: column.createdAt(), // Auto-timestamp
+  updated_at: column.updatedAt()
+});
 
-// SELECT - basic select (SQL filter only)
-const containers = db
-  .table<User>("users")
+// Query with the powerful QueryBuilder
+const users = db.table<User>("users")
   .select(["id", "name", "email"])
-  .where({ type: "container" }) // SQL: type = 'container'
-  .orderBy("id")
+  .where({ active: true })
+  .whereRgx({ email: /@company\.com$/i })
+  .orderBy("created_at")
   .desc()
   .limit(10)
   .all();
 
-console.log(containers);
+console.log(users);
+```
 
-// SELECT - regex + SQL filters together
-const gmailUsers = db
-  .table<User>("users")
-  .select(["id", "email"])
-  .where({ type: "container" }) // SQL
-  .whereRgx({ email: /@gmail\.com$/i }) // client-side regex
-  .all();
+---
 
-console.log(gmailUsers);
-
-// INSERT - single row
-const insertResult = db
-  .table<User>("users")
-  .insert({
-    name: "John Doe",
-    email: "john@example.com",
-    type: "container"
-  });
-
-console.log(`Inserted user with ID: ${insertResult.insertId}`);
-
-// INSERT - multiple rows with conflict resolution
-const bulkResult = db
-  .table<User>("users")
-  .insertOrIgnore([
-    { name: "Alice", email: "alice@example.com", type: "container" },
-    { name: "Bob", email: "bob@example.com", type: "container" }
-  ]);
-
-console.log(`Inserted ${bulkResult.changes} users`);
-
-// UPDATE - with WHERE conditions
-const updateResult = db
-  .table<User>("users")
-  .where({ type: "container" })
-  .whereRgx({ email: /@gmail\.com$/i })
-  .update({ type: "gmail_user" });
-
-console.log(`Updated ${updateResult.changes} users`);
-
-// DELETE - with WHERE conditions
-const deleteResult = db
-  .table<User>("users")
-  .where({ type: "gmail_user" })
-  .delete();
+## Table Creation
+
+### Modern Column Helpers (Recommended)
 
-console.log(`Deleted ${deleteResult.changes} users`);
+Create tables with type-safe column definitions and comprehensive SQLite feature support:
 
-db.close();
+```ts
+import { DB, column, sql } from "@dockstat/sqlite-wrapper";
+
+db.createTable("products", {
+  // Primary keys and auto-increment
+  id: column.id(), // INTEGER PRIMARY KEY AUTOINCREMENT
+  uuid: column.uuid({ generateDefault: true }),
+  
+  // Text columns with constraints
+  name: column.text({ notNull: true }),
+  description: column.text({ length: 1000 }),
+  sku: column.varchar(50, { unique: true }),
+  
+  // Numeric columns
+  price: column.numeric({ precision: 10, scale: 2, check: "price > 0" }),
+  quantity: column.integer({ default: 0, check: "quantity >= 0" }),
+  weight: column.real(),
+  
+  // Boolean with validation
+  active: column.boolean({ default: true }),
+  
+  // Enums with validation
+  category: column.enum(["electronics", "clothing", "books"], {
+    default: "electronics"
+  }),
+  
+  // JSON data
+  specifications: column.json({ validateJson: true }),
+  tags: column.json(),
+  
+  // Dates and timestamps
+  manufactured_date: column.date(),
+  created_at: column.createdAt(), // Auto-managed
+  updated_at: column.updatedAt(),
+  
+  // Foreign keys
+  supplier_id: column.foreignKey("suppliers", "id", {
+    onDelete: "SET NULL",
+    onUpdate: "CASCADE"
+  }),
+  
+  // Generated columns
+  display_price: {
+    type: "TEXT",
+    generated: {
+      expression: "printf('$%.2f', price)",
+      stored: false // VIRTUAL column
+    }
+  }
+}, {
+  constraints: {
+    // Table-level constraints
+    unique: [["sku", "supplier_id"]], // Composite unique
+    check: ["price > 0 OR category = 'free'"],
+    foreignKeys: [{
+      columns: ["supplier_id"],
+      references: {
+        table: "suppliers",
+        columns: ["id"],
+        onDelete: "CASCADE"
+      }
+    }]
+  },
+  comment: "Product catalog with full specifications"
+});
 ```
 
----
+### Available Column Types
+
+```ts
+// Integer types
+column.integer()
+column.integer({ size: "BIGINT" })
+column.id() // INTEGER PRIMARY KEY AUTOINCREMENT
+
+// Text types
+column.text()
+column.varchar(255)
+column.char(10)
+column.uuid()
+
+// Numeric types
+column.real()
+column.numeric({ precision: 10, scale: 2 })
+column.numeric({ variant: "DECIMAL" })
+
+// Date/Time types
+column.date()
+column.time()
+column.datetime()
+column.timestamp()
+column.createdAt() // Auto-managed creation timestamp
+column.updatedAt() // Auto-managed update timestamp
+
+// Special types
+column.boolean() // INTEGER with CHECK constraint
+column.json() // TEXT with optional validation
+column.blob()
+column.enum(["value1", "value2"])
+
+// Foreign keys
+column.foreignKey("other_table", "other_column", {
+  onDelete: "CASCADE",
+  onUpdate: "RESTRICT"
+})
+```
+
+### Column Constraints
+
+All column helpers support comprehensive constraints:
+
+```ts
+column.text({
+  notNull: true,
+  unique: true,
+  default: "default_value",
+  check: "length(column_name) > 0",
+  collate: "NOCASE",
+  comment: "User description"
+})
+
+// Default value expressions
+column.timestamp({
+  default: sql.currentTimestamp()
+})
+
+column.text({
+  default: sql.raw("upper(hex(randomblob(16)))")
+})
+```
 
-## 1) Creating tables
+### Legacy Table Creation
 
-**Object style (recommended):**
+Object-style (still supported):
 
 ```ts
 db.createTable("posts", {
@@ -144,435 +218,652 @@ db.createTable("posts", {
 }, { ifNotExists: true });
 ```
 
-**String style:**
+String-style (still supported):
 
 ```ts
-db.createTable(
-  "events",
-  `id INTEGER PRIMARY KEY,
-   name TEXT NOT NULL,
-   occurred_at INTEGER NOT NULL`
-);
+db.createTable("events", `
+  id INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  occurred_at INTEGER NOT NULL
+`);
 ```
 
 ---
 
-## 2) Running PRAGMA statements
+## Query Building
 
-You can pass PRAGMAs at construction:
+### SELECT Operations
 
 ```ts
-const db = new DB("app.db", {
-  pragmas: [
-    ["journal_mode", "WAL"],
-    ["cache_size", -64000]
-  ]
-});
+// Basic selection
+const users = db.table<User>("users")
+  .select(["id", "name", "email"])
+  .where({ active: true })
+  .all();
+
+// Complex conditions
+const results = db.table<User>("users")
+  .where({ type: "admin" })
+  .whereIn("id", [1, 2, 3, 4, 5])
+  .whereOp("created_at", ">", Date.now() - 86400000)
+  .whereRaw("name LIKE ?", ["%admin%"])
+  .whereRgx({ email: /@company\.com$/i }) // Client-side regex
+  .orderBy("created_at")
+  .desc()
+  .limit(50)
+  .offset(100)
+  .all();
+
+// Result methods
+const allUsers = db.table<User>("users").all();
+const firstUser = db.table<User>("users").first();
+const singleUser = db.table<User>("users").where({ id: 1 }).get();
+const userCount = db.table<User>("users").where({ active: true }).count();
+const userExists = db.table<User>("users").where({ email: "test@example.com" }).exists();
+
+// Single values
+const userName = db.table<User>("users").where({ id: 1 }).value("name");
+const allNames = db.table<User>("users").pluck("name");
 ```
 
-Or run them later:
+### INSERT Operations
 
 ```ts
-db.pragma("cache_size", -32000);
-const foreignKeysOn = db.pragma("foreign_keys");
-console.log(foreignKeysOn); // should print ON
-```
+// Single insert
+const result = db.table<User>("users").insert({
+  name: "John Doe",
+  email: "john@example.com",
+  type: "user"
+});
+console.log(`Inserted user with ID: ${result.insertId}`);
 
----
+// Bulk insert
+const users = [
+  { name: "Alice", email: "alice@example.com" },
+  { name: "Bob", email: "bob@example.com" }
+];
+const bulkResult = db.table<User>("users").insert(users);
 
-## 3) Loading SQLite extensions
+// Conflict resolution
+db.table<User>("users").insertOrIgnore(userData);
+db.table<User>("users").insertOrReplace(userData);
 
-At DB construction:
+// Custom conflict resolution
+db.table<User>("users").insert(userData, {
+  orIgnore: true,
+  orReplace: false,
+  orAbort: false,
+  orFail: false,
+  orRollback: false
+});
 
-```ts
-const db = new DB("app.db", {
-  loadExtensions: [
-    "/absolute/path/to/regexp_extension"
-  ]
+// Insert and get back the row
+const newUser = db.table<User>("users").insertAndGet({
+  name: "Jane",
+  email: "jane@example.com"
 });
+
+// Batch insert with transaction
+db.table<User>("users").insertBatch(largeUserArray);
 ```
 
-Or after creation:
+### UPDATE Operations
 
-```ts
-db.loadExtension("/absolute/path/to/my_extension");
-```
+All UPDATE operations require WHERE conditions for safety:
 
----
+```ts
+// Basic update
+const result = db.table<User>("users")
+  .where({ id: 1 })
+  .update({ name: "Updated Name" });
 
-## 4) Basic QueryBuilder usage
+// Complex conditions
+db.table<User>("users")
+  .where({ type: "user" })
+  .whereRgx({ email: /@oldcompany\.com$/i })
+  .update({ type: "migrated_user" });
 
-**Select specific columns:**
+// Increment/decrement
+db.table<User>("users")
+  .where({ id: 1 })
+  .increment("login_count", 1);
 
-```ts
-const users = db
-  .table<User>("users")
-  .select(["id", "name"])
-  .where({ type: "container" })
-  .all();
-```
+// Upsert (insert or update)
+db.table<User>("users").upsert({
+  id: 1,
+  name: "John",
+  email: "john@example.com"
+});
 
-**Select all columns:**
+// Update and get affected rows
+const updatedUsers = db.table<User>("users")
+  .where({ active: false })
+  .updateAndGet({ active: true });
 
-```ts
-const allUsers = db.table<User>("users").select(["*"]).all();
+// Batch update
+db.table<User>("users").updateBatch([
+  { where: { id: 1 }, data: { name: "User 1" } },
+  { where: { id: 2 }, data: { name: "User 2" } }
+]);
 ```
 
-**Get a single row:**
+### DELETE Operations
+
+All DELETE operations require WHERE conditions for safety:
 
 ```ts
-const userOrNull = db.table<User>("users").where({ id: 1 }).get();
-```
+// Basic delete
+const result = db.table<User>("users")
+  .where({ active: false })
+  .delete();
 
-**Get first matching row:**
+// Complex conditions
+db.table<User>("users")
+  .where({ type: "temporary" })
+  .whereOp("created_at", "<", Date.now() - 604800000)
+  .delete();
 
-```ts
-const first = db.table<User>("users").where({ type: "container" }).first();
-```
+// Delete and get deleted rows
+const deletedUsers = db.table<User>("users")
+  .where({ active: false })
+  .deleteAndGet();
 
-**Count rows:**
+// Soft delete
+db.table<User>("users")
+  .where({ id: 1 })
+  .softDelete("deleted_at", Date.now());
 
-```ts
-const count = db.table<User>("users").where({ type: "container" }).count();
+// Restore soft deleted
+db.table<User>("users")
+  .where({ id: 1 })
+  .restore("deleted_at");
+
+// Utility methods
+db.table<User>("users").deleteOlderThan("created_at", Date.now() - 2592000000);
+db.table<User>("users").deleteDuplicates(["email"]);
+db.table<User>("users").truncate(); // Delete all rows
+
+// Batch delete
+db.table<User>("users").deleteBatch([
+  { type: "temp" },
+  { active: false }
+]);
 ```
 
 ---
 
-## 5) Mixing equality and regex
+## Advanced Features
 
-Plain equality uses `.where()` (SQL). Regex uses `.whereRgx()` (client-side):
+### JSON Column Support
 
 ```ts
-const matches = db
-  .table<User>("users")
-  .select(["id", "name", "email", "type"])
-  .where({ type: "container" }) // SQL
-  .whereRgx({ email: /@example\.com$/i }) // JS regex after SQL fetch
-  .orderBy("created_at")
-  .desc()
-  .limit(50)
-  .all();
-```
+interface UserWithMetadata {
+  id: number;
+  name: string;
+  metadata: {
+    preferences: object;
+    settings: object;
+  };
+}
 
-> **Note:** If `.whereRgx()` is used, ordering, offset, and limit are applied in JS after regex filtering.
+// Configure JSON columns for automatic serialization/deserialization
+const users = db.table<UserWithMetadata>("users", {
+  jsonColumns: ["metadata"]
+});
 
----
+// Insert with automatic JSON serialization
+users.insert({
+  name: "John",
+  metadata: {
+    preferences: { theme: "dark" },
+    settings: { notifications: true }
+  }
+});
 
-## 6) Raw expressions, IN, and operators
+// Query returns properly deserialized objects
+const user = users.where({ id: 1 }).first();
+console.log(user.metadata.preferences.theme); // "dark"
+```
 
-**Raw WHERE fragment:**
+### Regex Filtering
 
 ```ts
-const rows = db
-  .table<User>("users")
-  .whereRaw("created_at > ? AND published = ?", [1625097600, 1])
+// Client-side regex filtering
+const gmailUsers = db.table<User>("users")
+  .where({ active: true }) // SQL filter first
+  .whereRgx({ email: /@gmail\.com$/i }) // Then regex filter
   .all();
-```
 
-**IN clause:**
-
-```ts
-const some = db.table<User>("users").whereIn("id", [1, 2, 5, 7]).all();
+// Multiple regex conditions
+const results = db.table<User>("users")
+  .whereRgx({
+    email: /@(gmail|yahoo)\.com$/i,
+    name: /^[A-Z]/
+  })
+  .all();
 ```
 
-**Operator helper:**
+### Raw SQL and Advanced Conditions
 
 ```ts
+// Raw WHERE expressions
 db.table<User>("users")
-  .whereOp("created_at", ">", 1622505600)
-  .whereOp("email", "LIKE", "%@gmail.com")
+  .whereRaw("created_at > ? AND (type = ? OR type = ?)", [
+    Date.now() - 86400000,
+    "admin",
+    "moderator"
+  ])
   .all();
-```
 
----
+// Operator helpers
+db.table<User>("users")
+  .whereOp("created_at", ">=", startDate)
+  .whereOp("created_at", "<=", endDate)
+  .whereOp("name", "LIKE", "%john%")
+  .all();
 
-## 7) Pagination
+// BETWEEN clauses
+db.table<User>("users")
+  .whereBetween("created_at", startDate, endDate)
+  .whereNotBetween("age", 0, 18)
+  .all();
 
-```ts
-const page = 2;
-const pageSize = 20;
+// NULL checks
+db.table<User>("users")
+  .whereNull("deleted_at")
+  .whereNotNull("email")
+  .all();
 
-const paged = db
-  .table<User>("users")
-  .where({ type: "container" })
-  .orderBy("created_at")
-  .desc()
-  .offset((page - 1) * pageSize)
-  .limit(pageSize)
+// IN clauses
+db.table<User>("users")
+  .whereIn("type", ["admin", "moderator"])
+  .whereNotIn("status", ["banned", "suspended"])
   .all();
 ```
 
-> With `.whereRgx()`, paging happens in JS after filtering.
+### Database Configuration
 
----
+```ts
+// Constructor options
+const db = new DB("app.db", {
+  pragmas: [
+    ["journal_mode", "WAL"],
+    ["synchronous", "NORMAL"],
+    ["foreign_keys", "ON"],
+    ["cache_size", -64000],
+    ["temp_store", "memory"]
+  ],
+  loadExtensions: [
+    "/path/to/regexp_extension.so"
+  ]
+});
 
-## 8) INSERT operations
+// Runtime PRAGMA management
+db.pragma("cache_size", -32000);
+const journalMode = db.pragma("journal_mode");
 
-**Single row insert:**
+// Extension loading
+db.loadExtension("/path/to/custom_extension.so");
 
-```ts
-const result = db
-  .table<User>("users")
-  .insert({
-    name: "John Doe",
-    email: "john@example.com",
-    type: "container"
-  });
-
-console.log(result.insertId, result.changes);
+// Database info
+const tableInfo = db.getTableInfo("users");
+const foreignKeys = db.getForeignKeys("users");
+const indexes = db.getIndexes("users");
 ```
 
-**Bulk insert:**
+---
 
-```ts
-const users = [
-  { name: "Alice", email: "alice@example.com", type: "container" },
-  { name: "Bob", email: "bob@example.com", type: "container" }
-];
+## Performance Considerations
 
-const result = db.table<User>("users").insert(users);
-console.log(`Inserted ${result.changes} users`);
-```
+### Query Optimization
 
-**Insert with conflict resolution:**
+1. **Use SQL filters before regex**: Always use `.where()` conditions to reduce the dataset before applying `.whereRgx()` filters.
 
 ```ts
-// INSERT OR IGNORE - skip duplicates
-const result1 = db.table<User>("users").insertOrIgnore({
-  name: "Duplicate User",
-  email: "existing@example.com"
-});
-
-// INSERT OR REPLACE - replace duplicates
-const result2 = db.table<User>("users").insertOrReplace({
-  name: "Updated User",
-  email: "existing@example.com"
-});
+// Good: SQL filter first, then regex
+db.table<User>("users")
+  .where({ active: true, type: "user" }) // Reduces dataset
+  .whereRgx({ email: /@company\.com$/i }) // Then regex filter
+  .all();
 
-// Custom conflict resolution
-const result3 = db.table<User>("users").insert(userData, {
-  orIgnore: true,
-  // or: orReplace, orAbort, orFail, orRollback
-});
+// Avoid: Regex on entire table
+db.table<User>("users")
+  .whereRgx({ email: /@company\.com$/i })
+  .all();
 ```
 
----
-
-## 9) UPDATE operations
-
-**Basic update (requires WHERE conditions):**
+2. **Use appropriate indexes**: Create indexes on frequently queried columns.
 
 ```ts
-const result = db
-  .table<User>("users")
-  .where({ id: 1 })
-  .update({ name: "Updated Name", type: "admin" });
-
-console.log(`Updated ${result.changes} rows`);
+db.createIndex("idx_users_email", "users", "email", { unique: true });
+db.createIndex("idx_users_created_at", "users", "created_at");
+db.createIndex("idx_users_type_active", "users", ["type", "active"]);
 ```
 
-**Update with complex conditions:**
+3. **Batch operations**: Use bulk operations for better performance.
 
 ```ts
-const result = db
-  .table<User>("users")
-  .where({ type: "container" })
-  .whereRgx({ email: /@gmail\.com$/i })
-  .update({ type: "gmail_container" });
+// Good: Bulk insert
+db.table<User>("users").insertBatch(largeArray);
+
+// Avoid: Individual inserts
+largeArray.forEach(user => db.table<User>("users").insert(user));
 ```
 
-**Update with raw WHERE conditions:**
+### Transaction Management
 
 ```ts
-const result = db
-  .table<User>("users")
-  .whereRaw("created_at > ? AND active = ?", [Date.now() - 86400000, true])
-  .update({ last_active: Date.now() });
+// Manual transactions
+db.begin();
+try {
+  db.table<User>("users").insert(userData1);
+  db.table<User>("users").insert(userData2);
+  db.commit();
+} catch (error) {
+  db.rollback();
+  throw error;
+}
+
+// Automatic transaction wrapper
+const result = db.transaction(() => {
+  const user = db.table<User>("users").insert(userData);
+  db.table("audit_log").insert({ action: "user_created", user_id: user.insertId });
+  return user;
+});
 ```
 
-> **Safety Note:** UPDATE operations require at least one WHERE condition to prevent accidental full table updates.
+### Memory and Performance Tips
+
+- Use `PRAGMA cache_size` to tune memory usage
+- Enable WAL mode for better concurrency
+- Use `PRAGMA optimize` periodically for query optimization
+- Consider `WITHOUT ROWID` tables for specific use cases
+- Use `PRAGMA vacuum` to reclaim space after large deletions
 
 ---
 
-## 10) DELETE operations
+## Error Handling and Safety
+
+### Required WHERE Conditions
 
-**Basic delete (requires WHERE conditions):**
+UPDATE and DELETE operations require WHERE conditions to prevent accidental data modification:
 
 ```ts
-const result = db
-  .table<User>("users")
-  .where({ active: false })
-  .delete();
+// This will throw an error
+try {
+  db.table<User>("users").update({ active: false });
+} catch (error) {
+  console.error("UPDATE requires WHERE conditions");
+}
 
-console.log(`Deleted ${result.changes} rows`);
+// This is safe
+db.table<User>("users")
+  .where({ type: "temporary" })
+  .update({ active: false });
 ```
 
-**Delete with complex conditions:**
+### Type Safety
+
+The library provides comprehensive TypeScript support:
 
 ```ts
-const result = db
-  .table<User>("users")
-  .where({ type: "temporary" })
-  .whereOp("created_at", "<", Date.now() - 604800000) // older than 1 week
-  .delete();
-```
+interface StrictUser {
+  id: number;
+  name: string;
+  email: string;
+}
 
-**Delete with regex conditions:**
+const users = db.table<StrictUser>("users");
 
-```ts
-const result = db
-  .table<User>("users")
-  .whereRgx({ email: /^test.*@example\.com$/i })
-  .delete();
-```
+// TypeScript will enforce correct column names
+users.select(["id", "name"]); // ✓ Valid
+users.select(["invalid_column"]); // ✗ TypeScript error
 
-> **Safety Note:** DELETE operations require at least one WHERE condition to prevent accidental full table deletion.
+// TypeScript will enforce correct data types
+users.insert({ name: "John", email: "john@example.com" }); // ✓ Valid
+users.insert({ name: 123 }); // ✗ TypeScript error
+```
 
----
+### Parameter Binding
 
-## 11) Complex query example
+All queries use proper parameter binding to prevent SQL injection:
 
 ```ts
-const results = db
-  .table<User>("users")
-  .select(["id", "name", "email", "created_at"])
-  .whereRaw("created_at > ?", [1672531200])
-  .whereIn("id", [10, 20, 30, 40])
-  .whereRgx({ email: /\b(hey@example|test@example)\.com$/i })
-  .orderBy("created_at")
-  .desc()
-  .limit(100)
+// Safe - uses parameter binding
+db.table<User>("users")
+  .whereRaw("name = ? AND email = ?", [userName, userEmail])
+  .all();
+
+// Parameters are automatically escaped
+db.table<User>("users")
+  .where({ name: "O'Reilly" }) // Automatically handled
   .all();
 ```
 
 ---
 
-## 12) Result types and error handling
+## API Reference
 
-**INSERT results:**
+### DB Class
 
 ```ts
-interface InsertResult {
-  insertId: number;  // rowid of the last inserted row
-  changes: number;   // number of rows inserted
-}
+constructor(path: string, options?: {
+  pragmas?: Array<[string, any]>;
+  loadExtensions?: string[];
+})
+
+// Table operations
+table<T>(tableName: string, jsonConfig?: JsonColumnConfig<T>): QueryBuilder<T>
+createTable(tableName: string, columns: CreateTableColumns, options?: TableOptions): void
+dropTable(tableName: string, options?: { ifExists?: boolean }): void
+
+// Index operations
+createIndex(name: string, table: string, columns: string | string[], options?: IndexOptions): void
+dropIndex(name: string, options?: { ifExists?: boolean }): void
+
+// Database operations
+pragma(name: string, value?: any): any
+loadExtension(path: string): void
+exec(sql: string): void
+prepare(sql: string): Statement
+transaction<T>(fn: () => T): T
+begin(): void
+commit(): void
+rollback(): void
+close(): void
+
+// Introspection
+getTableInfo(tableName: string): TableInfo[]
+getForeignKeys(tableName: string): ForeignKeyInfo[]
+getIndexes(tableName: string): IndexInfo[]
+getSchema(): SchemaInfo[]
 ```
 
-**UPDATE/DELETE results:**
+### QueryBuilder Class
 
 ```ts
-interface UpdateResult {
-  changes: number;   // number of rows affected
-}
-
-interface DeleteResult {
-  changes: number;   // number of rows deleted
-}
+// WHERE conditions
+where(conditions: WhereCondition<T>): this
+whereRgx(conditions: RegexCondition<T>): this
+whereRaw(expr: string, params?: any[]): this
+whereExpr(expr: string, params?: any[]): this
+whereIn(column: keyof T, values: any[]): this
+whereNotIn(column: keyof T, values: any[]): this
+whereOp(column: keyof T, op: string, value: any): this
+whereBetween(column: keyof T, min: any, max: any): this
+whereNotBetween(column: keyof T, min: any, max: any): this
+whereNull(column: keyof T): this
+whereNotNull(column: keyof T): this
+
+// SELECT operations
+select(columns: ColumnNames<T>): this
+orderBy(column: keyof T): this
+asc(): this
+desc(): this
+limit(amount: number): this
+offset(start: number): this
+
+// Result execution
+all(): T[]
+get(): T | null
+first(): T | null
+count(): number
+exists(): boolean
+value<K extends keyof T>(column: K): T[K] | null
+pluck<K extends keyof T>(column: K): T[K][]
+
+// INSERT operations
+insert(data: Partial<T> | Partial<T>[], options?: InsertOptions): InsertResult
+insertOrIgnore(data: Partial<T> | Partial<T>[]): InsertResult
+insertOrReplace(data: Partial<T> | Partial<T>[]): InsertResult
+insertAndGet(data: Partial<T>, options?: InsertOptions): T | null
+insertBatch(rows: Partial<T>[], options?: InsertOptions): InsertResult
+
+// UPDATE operations
+update(data: Partial<T>): UpdateResult
+upsert(data: Partial<T>): UpdateResult
+increment(column: keyof T, amount?: number): UpdateResult
+decrement(column: keyof T, amount?: number): UpdateResult
+updateAndGet(data: Partial<T>): T[]
+updateBatch(updates: Array<{ where: Partial<T>; data: Partial<T> }>): UpdateResult
+
+// DELETE operations
+delete(): DeleteResult
+deleteAndGet(): T[]
+softDelete(deletedColumn?: keyof T, deletedValue?: any): DeleteResult
+restore(deletedColumn?: keyof T): DeleteResult
+deleteBatch(conditions: Array<Partial<T>>): DeleteResult
+truncate(): DeleteResult
+deleteOlderThan(timestampColumn: keyof T, olderThan: number): DeleteResult
+deleteDuplicates(columns: Array<keyof T>): DeleteResult
 ```
 
-**Error handling:**
+### Result Types
 
 ```ts
-try {
-  // This will throw - UPDATE without WHERE conditions
-  db.table<User>("users").update({ active: true });
-} catch (error) {
-  console.error("UPDATE operation requires WHERE conditions");
+interface InsertResult {
+  insertId: number;
+  changes: number;
 }
 
-try {
-  // This will throw - empty insert data
-  db.table<User>("users").insert({});
-} catch (error) {
-  console.error("Insert data cannot be empty");
+interface UpdateResult {
+  changes: number;
+}
+
+interface DeleteResult {
+  changes: number;
+}
+
+interface InsertOptions {
+  orIgnore?: boolean;
+  orReplace?: boolean;
+  orAbort?: boolean;
+  orFail?: boolean;
+  orRollback?: boolean;
 }
 ```
 
 ---
 
-## Advanced: Native `REGEXP` support
+## Examples
 
-If you load a compiled SQLite extension that adds `REGEXP`, you can do regex filtering directly in SQL:
+### E-commerce Product Catalog
 
 ```ts
-db.loadExtension("/path/to/regexp_extension");
-const rows = db
-  .table<User>("users")
-  .whereExpr("email REGEXP ?", ["@example\\.com$"])
-  .all();
-```
+import { DB, column, sql } from "@dockstat/sqlite-wrapper";
 
----
+interface Product {
+  id?: number;
+  name: string;
+  sku: string;
+  price: number;
+  category: string;
+  specifications?: object;
+  active?: boolean;
+  created_at?: number;
+  updated_at?: number;
+}
 
-## Performance & Practical tips
+const db = new DB("ecommerce.db");
+
+// Create products table
+db.createTable("products", {
+  id: column.id(),
+  name: column.text({ notNull: true }),
+  sku: column.varchar(50, { unique: true, notNull: true }),
+  price: column.numeric({ precision: 10, scale: 2, check: "price > 0" }),
+  category: column.enum(["electronics", "clothing", "books"], {
+    default: "electronics"
+  }),
+  specifications: column.json({ validateJson: true }),
+  active: column.boolean({ default: true }),
+  created_at: column.createdAt(),
+  updated_at: column.updatedAt()
+});
 
-### SELECT performance:
-* Prefer `.where()` SQL filters for large datasets — `.whereRgx()` fetches rows and filters in JS.
-* Use `.whereIn()` and `.whereRaw()` to reduce rows before regex filtering.
-* Use indexes on frequently queried columns.
+// Query products
+const activeProducts = db.table<Product>("products")
+  .where({ active: true })
+  .whereOp("price", "<=", 100)
+  .orderBy("created_at")
+  .desc()
+  .all();
 
-### INSERT performance:
-* Use bulk inserts with arrays for multiple rows instead of individual insert calls.
-* Consider transaction wrapping for large batch operations.
-* Use appropriate conflict resolution (`OR IGNORE`, `OR REPLACE`) to avoid exception handling.
+// Update pricing
+db.table<Product>("products")
+  .where({ category: "electronics" })
+  .whereOp("price", ">", 1000)
+  .increment("price", -50); // $50 discount
+```
 
-### UPDATE/DELETE with regex:
-* When using `.whereRgx()`, the operation fetches candidate rows first, then applies regex filtering client-side.
-* For better performance with regex conditions, consider using SQL `LIKE` patterns where possible.
+### User Management System
 
-### General tips:
-* Use PRAGMAs to tune performance (e.g. WAL mode, cache size).
-* Load extensions to enable advanced SQLite features without manual filtering.
-* Always use WHERE conditions for UPDATE/DELETE to prevent accidents.
-* The library automatically handles parameter binding to prevent SQL injection.
+```ts
+interface User {
+  id?: number;
+  username: string;
+  email: string;
+  role: string;
+  profile?: object;
+  active?: boolean;
+  last_login?: number;
+  created_at?: number;
+}
 
----
+// Create users with comprehensive constraints
+db.createTable("users", {
+  id: column.id(),
+  username: column.varchar(50, { 
+    unique: true, 
+    notNull: true,
+    check: "length(username) >= 3"
+  }),
+  email: column.text({ 
+    unique: true, 
+    notNull: true,
+    check: "email LIKE '%@%.%'"
+  }),
+  role: column.enum(["admin", "moderator", "user"], { default: "user" }),
+  profile: column.json(),
+  active: column.boolean({ default: true }),
+  last_login: column.timestamp(),
+  created_at: column.createdAt()
+}, {
+  constraints: {
+    unique: [["username", "email"]]
+  }
+});
 
-## API Reference
+// Find inactive users
+const inactiveUsers = db.table<User>("users")
+  .where({ active: true })
+  .whereOp("last_login", "<", Date.now() - 2592000000) // 30 days
+  .all();
+
+// Bulk role assignment
+db.table<User>("users")
+  .whereIn("id", [1, 2, 3, 4, 5])
+  .update({ role: "moderator" });
+```
 
-### `DB` (default export)
-
-* `constructor(path: string, opts?: { pragmas?: [string, any][], loadExtensions?: string[] })`
-* `table<T>(tableName: string): QueryBuilder<T>`
-* `createTable(tableName: string, columns: string | Record<string,string>, options?: { ifNotExists?: boolean; withoutRowId?: boolean })`
-* `pragma(name: string, value?: any): any`
-* `loadExtension(path: string): void`
-* `close(): void`
-
-### `QueryBuilder<T>` (named export)
-
-**WHERE methods (shared across operations):**
-* `where(cond: Partial<Record<keyof T, string | number | boolean | null>>)`
-* `whereRgx(cond: Partial<Record<keyof T, string | RegExp>>)`
-* `whereExpr(expr: string, params?: any[])`
-* `whereRaw(expr: string, params?: any[])`
-* `whereIn(column: keyof T, values: any[])`
-* `whereOp(column: keyof T, op: string, value: any)`
-
-**SELECT methods:**
-* `select(columns: Array<keyof T> | ["*"])`
-* `orderBy(column: keyof T)`
-* `asc()`, `desc()`
-* `limit(n)`, `offset(n)`
-* `all(): T[]`, `get(): T | null`, `first(): T | null`, `count(): number`
-
-**INSERT methods:**
-* `insert(data: Partial<T> | Partial<T>[], options?: InsertOptions): InsertResult`
-* `insertOrIgnore(data: Partial<T> | Partial<T>[]): InsertResult`
-* `insertOrReplace(data: Partial<T> | Partial<T>[]): InsertResult`
-
-**UPDATE methods:**
-* `update(data: Partial<T>): UpdateResult` *(requires WHERE conditions)*
-
-**DELETE methods:**
-* `delete(): DeleteResult` *(requires WHERE conditions)*
-
-### Types (named exports)
-
-* `InsertResult` — `{ insertId: number, changes: number }`
-* `UpdateResult` — `{ changes: number }`
-* `DeleteResult` — `{ changes: number }`
-* `InsertOptions` — conflict resolution options
-* `ColumnNames<T>` — column selection type
-* `WhereCondition<T>` — WHERE condition type
-* `RegexCondition<T>` — regex condition type
+This comprehensive wrapper provides everything you need for robust SQLite operations in TypeScript applications with type safety, performance optimizations, and modern development practices.