nanodb-orm 0.0.3 → 0.0.4

package/README.md

@@ -1,503 +1,336 @@
 # nanodb-orm
 
-A production-ready, generic database package built on top of Drizzle ORM with automatic migrations, schema introspection, atomic transactions, and support for both local SQLite and remote Turso databases.
+A lightweight, schema-agnostic ORM wrapper for Drizzle ORM with automatic migrations, schema introspection, CLI tools, and support for SQLite/Turso databases.
 
 ## Features
 
-- 🚀 **Auto-Migrations**: Automatically creates and updates database schemas from Drizzle table definitions
-- 🔍 **Schema Introspection**: Comprehensive schema analysis and validation
-- 🌐 **Multi-Database Support**: Works with local SQLite and remote Turso databases
-- ⚡ **Atomic Transactions**: Full transaction support with rollback protection
-- 🛡️ **Type Safe**: Full TypeScript support with proper type inference
-- 🔒 **Security**: SQL injection protection and input validation
-- 🧵 **Thread Safe**: Race condition fixes and concurrent access protection
-- 📦 **NPM Package Ready**: Designed to be used as a standalone npm package
-- ⚙️ **Configurable**: Flexible migration and seeding options
-- 🧪 **Test Ready**: Built-in testing utilities and isolation
-- 🔧 **Production Ready**: Enhanced error handling and reliability features
+- **Auto-Migrations** — Automatically creates and updates database schemas from Drizzle tables
+- **Schema Introspection** — Comprehensive schema analysis and validation
+- **Multi-Database** — Works with local SQLite and remote Turso databases
+- **Transactions** — Full transaction support with automatic rollback
+- **CLI Tools** — Built-in commands including Drizzle Studio integration
+- **Type Safe** — Full TypeScript support with proper type inference
+- **Plugin System** — Extensible with hooks for audit, validation, transformations
+- **Minimal** — ~1K lines of code, zero bloat
 
 ## Installation
 
 ```bash
 npm install nanodb-orm
+
+# For Drizzle Studio support (optional)
+npm install drizzle-kit --save-dev
 ```
 
-## Quick Start
+## CLI
 
-### 1. Define Your Models with Drizzle
+nanodb-orm includes a CLI for common database operations:
 
-Create your Drizzle table definitions (e.g., `models/users.ts`):
+```bash
+# Launch Drizzle Studio (visual database browser)
+npx nanodb studio
 
-```typescript
-// models/users.ts
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+# With custom port
+npx nanodb studio --port 3000
 
-export const usersTable = sqliteTable('users', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-  age: integer('age').notNull(),
-  email: text('email').unique().notNull(),
-});
+# With specific database file
+npx nanodb studio --db ./data/myapp.db
 
-export type InsertUser = typeof usersTable.$inferInsert;
-export type SelectUser = typeof usersTable.$inferSelect;
+# Other commands
+npx nanodb setup      # Initialize schema and seed data
+npx nanodb reset      # Drop all tables and recreate
+npx nanodb status     # Show database health and stats
+npx nanodb validate   # Validate schema against database
+npx nanodb help       # Show all commands
 ```
 
-```typescript
-// models/posts.ts
-import { sql } from 'drizzle-orm';
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
-import { usersTable } from './users';
+### Drizzle Studio
 
-export const postsTable = sqliteTable('posts', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  title: text('title').notNull(),
-  content: text('content').notNull(),
-  userId: integer('user_id')
-    .notNull()
-    .references(() => usersTable.id, { onDelete: 'cascade' }),
-  createdAt: text('created_at')
-    .default(sql`(datetime('now'))`)
-    .notNull(),
-  updatedAt: text('updated_at').$onUpdate(() => new Date().toISOString()),
-});
+Launch a visual database browser at `https://local.drizzle.studio`:
 
-export type InsertPost = typeof postsTable.$inferInsert;
-export type SelectPost = typeof postsTable.$inferSelect;
+```bash
+npx nanodb studio
 ```
 
+![Drizzle Studio](https://orm.drizzle.team/images/drizzle-studio.png)
+
+## Quick Start
+
+### 1. Define Your Schema
+
 ```typescript
-// models/categories.ts
-import { sql } from 'drizzle-orm';
-import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { table, integer, text } from 'nanodb-orm';
 
-export const categoriesTable = sqliteTable('categories', {
+const users = table('users', {
   id: integer('id').primaryKey({ autoIncrement: true }),
   name: text('name').notNull(),
-  description: text('description'),
-  color: text('color').notNull().default('#000000'),
-  isActive: integer('is_active').notNull().default(1),
-  createdAt: text('created_at')
-    .default(sql`(datetime('now'))`)
-    .notNull(),
+  email: text('email').unique().notNull(),
+  age: integer('age'),
 });
 
-export type InsertCategory = typeof categoriesTable.$inferInsert;
-export type SelectCategory = typeof categoriesTable.$inferSelect;
-```
+const posts = table('posts', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  title: text('title').notNull(),
+  userId: integer('userId').notNull(),
+});
 
-```typescript
-// models/index.ts
-export * from './users';
-export * from './posts';
-export * from './categories';
-
-// Import tables for aggregation
-import { usersTable } from './users';
-import { postsTable } from './posts';
-import { categoriesTable } from './categories';
-
-// Export aggregated tables for nanodb-orm
-export const tables = {
-  users: usersTable,
-  posts: postsTable,
-  categories: categoriesTable,
-} as const;
+const tables = { users, posts };
 ```
 
-### 2. Initialize and Setup Database
+### 2. Create Database
 
 ```typescript
-import { initializeDatabase, DatabaseSync } from 'nanodb-orm';
-import { tables } from './models';
+import { createDatabase } from 'nanodb-orm';
 
-// Initialize the database package with your Drizzle tables
-initializeDatabase({
+// One line: creates tables, runs migrations, seeds data, returns db
+const db = await createDatabase({
   tables,
   seedData: {
-    users: [
-      { name: 'John Doe', age: 30, email: 'john@example.com' },
-      { name: 'Jane Smith', age: 25, email: 'jane@example.com' }
-    ],
-    posts: [
-      { title: 'Welcome Post', content: 'This is my first post!', userId: 1 },
-      { title: 'Getting Started', content: 'Here are some tips...', userId: 2 }
-    ],
-    categories: [
-      { name: 'Technology', description: 'Tech-related posts', color: '#3B82F6' },
-      { name: 'Lifestyle', description: 'Life and personal posts', color: '#10B981' }
-    ]
-  }
+    users: [{ name: 'Alice', email: 'alice@example.com', age: 28 }],
+  },
 });
 
-// Setup database (creates tables, runs migrations, seeds data)
-await DatabaseSync.setup();
+// Store db and use it everywhere - no need for getInstance() or getDb()
+export { db };
 ```
 
-### 3. Working with Drizzle Tables
-
-nanodb-orm works seamlessly with Drizzle ORM table definitions. Here are the key Drizzle column types and methods:
+### 3. Query with Type Safety
 
-#### Drizzle Column Types
-- `integer()` - Integer numbers
-- `text()` - Text strings  
-- `real()` - Floating point numbers
-- `blob()` - Binary data
-
-#### Drizzle Column Methods
-- `.primaryKey({ autoIncrement: true })` - Primary key with auto-increment
-- `.notNull()` - NOT NULL constraint
-- `.unique()` - UNIQUE constraint
-- `.default(value)` - Default value
-- `.references(table.column)` - Foreign key reference
-
-#### Example Drizzle Column Definitions
 ```typescript
-// Primary key with auto-increment
-id: integer('id').primaryKey({ autoIncrement: true })
-
-// Required text field
-name: text('name').notNull()
+import { eq, gte } from 'nanodb-orm';
 
-// Optional text field with default
-color: text('color').notNull().default('#000000')
+// SELECT
+const allUsers = await db.select().from(users);
+const adults = await db.select().from(users).where(gte(users.age, 18));
 
-// Unique email field
-email: text('email').unique().notNull()
+// INSERT
+await db.insert(users).values({ name: 'Bob', email: 'bob@example.com' });
 
-// Boolean field (stored as integer)
-isActive: integer('is_active').notNull().default(1)
+// UPDATE
+await db.update(users).set({ name: 'Robert' }).where(eq(users.email, 'bob@example.com'));
 
-// Timestamp field with SQL function
-createdAt: text('created_at')
-  .default(sql`(datetime('now'))`)
-  .notNull()
-
-// Foreign key reference
-userId: integer('user_id')
-  .notNull()
-  .references(() => usersTable.id, { onDelete: 'cascade' })
+// DELETE
+await db.delete(users).where(eq(users.email, 'bob@example.com'));
 ```
 
 ## API Reference
 
-### `initializeDatabase(schemaData: SchemaData)`
+### `createDatabase(config)`
 
-Initializes the database package with your schema data.
+Create and initialize database. Returns `db` with all utilities attached.
 
 ```typescript
-interface SchemaData {
-  tables: Record<string, any>;           // Your Drizzle table definitions
-  seedData?: Record<string, any[]>;      // Optional seed data
-  migrationConfig?: MigrationConfig;     // Optional migration configuration
-}
-
-interface MigrationConfig {
-  preserveData?: boolean;    // Preserve existing data (default: true)
-  autoMigrate?: boolean;     // Enable auto-migrations (default: true)
-  dropTables?: boolean;      // Allow dropping tables (default: false)
-}
+const db = await createDatabase({
+  tables: { users, posts },
+  seedData: { users: [...] },
+  migrationConfig: {
+    preserveData: true,   // default: true
+    autoMigrate: true,    // default: true
+    dropTables: false,    // default: false
+  },
+  plugins: [auditPlugin, validationPlugin], // optional
+});
 ```
 
-### `DatabaseSync`
-
-Main database synchronization class.
+### Database Operations (from `db`)
 
 ```typescript
-// Setup database (create tables, migrate, seed)
-await DatabaseSync.setup();
-
-// Reset database (drop all tables and recreate)
-await DatabaseSync.reset();
-
-// Check if database is ready
-const isReady = await DatabaseSync.isReady();
+// Health & Status
+await db.healthCheck();    // { healthy, tables, totalRecords, ... }
+await db.isReady();        // true/false
+await db.sync();           // Sync with Turso (if remote)
+
+// Reset & Seed
+await db.reset();          // Drop all, recreate, reseed
+await db.seed();           // Re-seed data
+await db.clearData();      // Delete all data (keep tables)
 ```
 
-### `SchemaIntrospection`
-
-Comprehensive schema analysis utilities.
+### Schema Introspection (from `db.schema`)
 
 ```typescript
-// Get all table names
-const tableNames = SchemaIntrospection.getAllTableNames();
-
-// Get table information
-const tableInfo = SchemaIntrospection.getTableInfo('users');
+db.schema.tables();              // ['users', 'posts']
+db.schema.getTable('users');     // { columns, primaryKey, indexes }
+db.schema.getColumns('users');   // ['id', 'name', 'email']
+await db.schema.validate();      // { isValid, missingTables, ... }
+db.schema.stats();               // Full schema statistics
+db.schema.relationships();       // Foreign key relationships
+```
 
-// Get schema statistics
-const stats = SchemaIntrospection.getSchemaStats();
+### Migrations (from `db.migrations`)
 
-// Validate schema
-const validation = await SchemaIntrospection.validateSchema();
+```typescript
+await db.migrations.run();         // Run pending migrations
+await db.migrations.validate();    // Validate schema vs DB
+await db.migrations.checkTables(); // { users: true, posts: true }
 ```
 
-### `DatabaseMigrations`
+### `transaction(fn)`
 
-Migration management utilities.
+Execute operations atomically.
 
 ```typescript
-// Initialize schema
-await DatabaseMigrations.initializeSchema();
+import { transaction, sql } from 'nanodb-orm';
 
-// Check table existence
-const existence = await DatabaseMigrations.checkTableExistence();
+const result = await transaction(async (tx) => {
+  await tx.run(sql`INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')`);
+  await tx.run(sql`INSERT INTO posts (title, userId) VALUES ('Hello', 1)`);
+  return { created: true };
+});
 
-// Validate schema
-const validation = await DatabaseMigrations.validateSchema();
+if (result.success) {
+  console.log(result.result);
+} else {
+  console.log('Rolled back:', result.error?.message);
+}
 ```
 
-### `DatabaseSeeds`
+### `parseDbError(error, context)`
 
-Database seeding utilities.
+Parse SQLite errors into user-friendly messages.
 
 ```typescript
-// Seed database
-await DatabaseSeeds.seedDatabase();
+import { parseDbError } from 'nanodb-orm';
 
-// Check if database has data
-const hasData = await DatabaseSeeds.hasData();
-
-// Clear all data
-await DatabaseSeeds.clearAllData();
+try {
+  await db.run('INSERT INTO users ...');
+} catch (error) {
+  const parsed = parseDbError(error, { table: 'users', operation: 'insert' });
+  console.log(parsed.message); // "Column 'email' does not exist"
+}
 ```
 
-## Configuration
-
-### Environment Variables
-
-```bash
-# Turso Database (optional)
-TURSO_CONNECTION_URL=libsql://your-database.turso.io
-TURSO_AUTH_TOKEN=your-auth-token
+## Plugins
 
-# Force local database (for testing)
-FORCE_LOCAL_DB=true
-NODE_ENV=test
-```
+Extend nanodb-orm with custom hooks that run automatically on database operations.
 
-### Migration Configuration
+### Plugin Interface
 
 ```typescript
-const migrationConfig = {
-  preserveData: true,    // Always try to preserve existing data
-  autoMigrate: true,     // Automatically handle schema changes
-  dropTables: false      // Don't drop tables by default
+import { NanoPlugin } from 'nanodb-orm';
+
+const myPlugin: NanoPlugin = {
+  name: 'my-plugin',
+  
+  // Lifecycle
+  install: (db) => db,           // Modify db instance
+  onReady: (db) => {},           // Called after createDatabase
+  onError: (err, op, table) => {},  // Called on hook errors
+  
+  // Auto hooks (run automatically)
+  beforeInsert: (table, data) => data,   // Transform data before insert
+  afterInsert: (table, data, result) => {},
+  beforeUpdate: (table, data) => data,   // Transform data before update
+  afterUpdate: (table, data, result) => {},
+  beforeDelete: (table, condition) => condition,
+  afterDelete: (table, condition, result) => {},
+  
+  // Query hooks (also auto-triggered)
+  beforeQuery: (table, fields) => fields,
+  afterQuery: (table, fields, result) => {},
 };
-
-initializeDatabase({
-  tables,
-  migrationConfig
-});
 ```
 
-## Usage Examples
+### Example Plugins
 
-### Basic Setup
+These are **example plugins you can create** - nanodb-orm provides the plugin system, you build the plugins:
 
 ```typescript
-import { initializeDatabase, DatabaseSync } from 'nanodb-orm';
-import { usersTable, postsTable } from './models';
-
-const tables = {
-  users: usersTable,
-  posts: postsTable
+// Example: Audit logging with timing
+const timers = new Map<string, number>();
+const auditPlugin: NanoPlugin = {
+  name: 'audit',
+  beforeInsert: (table) => { timers.set('op', performance.now()); console.log(`INSERT ${table}`); },
+  afterInsert: () => { console.log(`  ↳ ${(performance.now() - timers.get('op')!).toFixed(1)}ms`); },
+  beforeQuery: (table) => { timers.set('op', performance.now()); console.log(`SELECT ${table}`); },
+  afterQuery: (t, _, rows) => { console.log(`  ↳ ${rows.length} rows in ${(performance.now() - timers.get('op')!).toFixed(1)}ms`); },
 };
 
-initializeDatabase({ tables });
-await DatabaseSync.setup();
-```
-
-### With Seed Data
-
-```typescript
-const seedData = {
-  users: [
-    { name: 'Alice', age: 25, email: 'alice@example.com' },
-    { name: 'Bob', age: 30, email: 'bob@example.com' }
-  ],
-  posts: [
-    { title: 'Hello World', content: 'My first post', userId: 1 },
-    { title: 'Second Post', content: 'Another post', userId: 2 }
-  ]
+// Auto-generate slugs
+const slugPlugin: NanoPlugin = {
+  name: 'slug',
+  beforeInsert: (table, data) => {
+    if (table === 'posts' && data.title && !data.slug) {
+      return { ...data, slug: data.title.toLowerCase().replace(/\s+/g, '-') };
+    }
+    return data;
+  },
 };
 
-initializeDatabase({ tables, seedData });
-await DatabaseSync.setup();
-```
-
-### Custom Migration Config
-
-```typescript
-const migrationConfig = {
-  preserveData: false,   // Allow data loss for development
-  autoMigrate: true,     // Enable auto-migrations
-  dropTables: true       // Allow dropping tables
+// Validation
+const validationPlugin: NanoPlugin = {
+  name: 'validation',
+  beforeInsert: (table, data) => {
+    if (table === 'users' && !data.email?.includes('@')) {
+      throw new Error('Invalid email format');
+    }
+    return data;
+  },
 };
 
-initializeDatabase({ 
-  tables, 
-  migrationConfig 
-});
-```
-
-### Transaction Support (NEW in v0.0.3)
-
-```typescript
-import { TransactionManager } from 'nanodb-orm';
-
-// Atomic operations
-await TransactionManager.execute(async (db) => {
-  await db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
-  await db.run('INSERT INTO posts (title, content, userId) VALUES (?, ?, ?)', ['Hello', 'World', 1]);
-  // All operations succeed or all fail
+// Use plugins
+const db = await createDatabase({
+  tables,
+  plugins: [auditPlugin, slugPlugin, validationPlugin],
 });
 
-// Batch operations
-await TransactionManager.executeBatch([
-  async (db) => await db.run('INSERT INTO users ...'),
-  async (db) => await db.run('INSERT INTO posts ...'),
-  async (db) => await db.run('UPDATE stats ...')
-]);
+// Hooks run automatically
+await db.insert(posts).values({ title: 'My Post' }); // slug auto-generated
+await db.insert(users).values({ email: 'invalid' }); // throws error
 
-// Table recreation with transactions
-await TransactionManager.recreateTable('users', async (db) => {
-  await db.run('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-});
+// Check loaded plugins
+db.plugins.list(); // ['audit', 'slug', 'validation']
 ```
 
-### Enhanced Error Handling (NEW in v0.0.3)
-
-```typescript
-import { ErrorHandler, DatabaseError } from 'nanodb-orm';
-
-try {
-  await DatabaseSync.setup();
-} catch (error) {
-  if (error instanceof DatabaseError) {
-    console.log('Operation:', error.operation);
-    console.log('Context:', error.message);
-    console.log('Original Error:', error.originalError);
-  }
-}
-
-// Non-throwing error handling
-const result = ErrorHandler.handleNonThrowingError(
-  someError, 
-  'optional-operation', 
-  'This operation is optional'
-);
-```
-
-### Thread-Safe Connections (NEW in v0.0.3)
-
-```typescript
-import { DatabaseConnection } from 'nanodb-orm';
-
-// NEW: Async connection (recommended)
-const db = await DatabaseConnection.getInstance();
-
-// OLD: Synchronous connection (deprecated but still works)
-const db = DatabaseConnection.getInstanceSync();
-
-// Check connection status
-if (DatabaseConnection.isConnected()) {
-  console.log('Database is connected');
-}
-```
-
-### Schema Introspection
-
-```typescript
-import { SchemaIntrospection } from 'nanodb-orm';
-
-// Get comprehensive schema information
-const schemaInfo = SchemaIntrospection.getSchemaStats();
-console.log('Total tables:', schemaInfo.totalTables);
-console.log('Table details:', schemaInfo.tableDetails);
-
-// Validate schema integrity
-const validation = await SchemaIntrospection.validateSchema();
-if (!validation.isValid) {
-  console.log('Schema issues:', validation.errors);
-}
-```
-
-## Testing
-
-The package includes built-in testing utilities:
+## Configuration
 
-```typescript
-import { DatabaseSync } from 'nanodb-orm';
+### Environment Variables
 
-describe('My Tests', () => {
-  beforeEach(async () => {
-    // Reset database for each test
-    await DatabaseSync.reset();
-  });
+```bash
+# Remote Turso database
+TURSO_CONNECTION_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-token
 
-  test('should work with clean database', async () => {
-    // Your test code here
-  });
-});
+# Force local SQLite (for testing)
+FORCE_LOCAL_DB=true
 ```
 
-## Database Support
-
-### Local SQLite
-- Automatically used when Turso credentials are not available
-- Perfect for development and testing
-- File-based storage
+### Database Selection
 
-### Remote Turso
-- Cloud-hosted SQLite database
-- Requires `TURSO_CONNECTION_URL` and `TURSO_AUTH_TOKEN`
-- Production-ready with global replication
+- **Turso** — Used when `TURSO_CONNECTION_URL` and `TURSO_AUTH_TOKEN` are set
+- **Local SQLite** — Fallback when Turso credentials are missing
+- **Test Mode** — Isolated `test.db` when `NODE_ENV=test`
 
 ## Error Handling
 
-The package provides comprehensive error handling:
+Errors are automatically parsed into user-friendly messages:
 
 ```typescript
-import { DatabaseError } from 'nanodb-orm';
+import { DatabaseError, SchemaError, SeedError, parseDbError } from 'nanodb-orm';
 
 try {
   await DatabaseSync.setup();
 } catch (error) {
   if (error instanceof DatabaseError) {
-    console.log('Database error:', error.message);
-    console.log('Operation:', error.operation);
+    console.log(error.message);    // User-friendly message
+    console.log(error.operation);  // 'seed', 'migration', etc.
+    console.log(error.table);      // Table name if applicable
+    console.log(error.detail);     // Additional context
   }
 }
 ```
 
-## Contributing
+Error output is clean and actionable:
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+```
+┌─ nanodb-orm error ─────────────────────────────
+│ Column "email" does not exist
+│ Table: users
+│ Operation: seed
+│ Detail: Row data: {"name":"Alice","email":"alice@example.com"}
+└────────────────────────────────────────────────
+```
 
 ## License
 
 MIT © Damilola Alao
-
-## Changelog
-
-### 0.0.2
-- **Enhanced Documentation**: Added comprehensive Drizzle ORM integration examples
-- **Real Model Examples**: Updated documentation with actual Drizzle table definitions
-- **Schema Validation Fix**: Fixed table existence validation logic for proper health checks
-- **LLM Documentation**: Added detailed `llm.txt` file for AI/LLM integration
-- **Column Types Guide**: Added complete Drizzle column types and methods documentation
-- **Foreign Key Support**: Documented foreign key relationships and cascade deletes
-- **Type Safety**: Enhanced TypeScript integration examples with Drizzle's type inference
-
-### 0.0.1
-- Initial release
-- Auto-migration system
-- Schema introspection
-- Multi-database support
-- TypeScript support
-- Testing utilities