nanodb-orm 0.0.1 → 0.0.2

package/README.md

@@ -20,16 +20,108 @@ npm install nanodb-orm
 
 ## Quick Start
 
+### 1. Define Your Models with Drizzle
+
+Create your Drizzle table definitions (e.g., `models/users.ts`):
+
+```typescript
+// models/users.ts
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+export const usersTable = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  age: integer('age').notNull(),
+  email: text('email').unique().notNull(),
+});
+
+export type InsertUser = typeof usersTable.$inferInsert;
+export type SelectUser = typeof usersTable.$inferSelect;
+```
+
+```typescript
+// models/posts.ts
+import { sql } from 'drizzle-orm';
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { usersTable } from './users';
+
+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()),
+});
+
+export type InsertPost = typeof postsTable.$inferInsert;
+export type SelectPost = typeof postsTable.$inferSelect;
+```
+
+```typescript
+// models/categories.ts
+import { sql } from 'drizzle-orm';
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+export const categoriesTable = sqliteTable('categories', {
+  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(),
+});
+
+export type InsertCategory = typeof categoriesTable.$inferInsert;
+export type SelectCategory = typeof categoriesTable.$inferSelect;
+```
+
+```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;
+```
+
+### 2. Initialize and Setup Database
+
 ```typescript
 import { initializeDatabase, DatabaseSync } from 'nanodb-orm';
-import { tables } from './models'; // Your Drizzle table definitions
+import { tables } from './models';
 
-// Initialize the database package
+// Initialize the database package with your Drizzle tables
 initializeDatabase({
   tables,
   seedData: {
     users: [
-      { name: 'John Doe', age: 30, email: 'john@example.com' }
+      { 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' }
     ]
   }
 });
@@ -38,6 +130,51 @@ initializeDatabase({
 await DatabaseSync.setup();
 ```
 
+### 3. Working with Drizzle Tables
+
+nanodb-orm works seamlessly with Drizzle ORM table definitions. Here are the key Drizzle column types and methods:
+
+#### 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()
+
+// Optional text field with default
+color: text('color').notNull().default('#000000')
+
+// Unique email field
+email: text('email').unique().notNull()
+
+// Boolean field (stored as integer)
+isActive: integer('is_active').notNull().default(1)
+
+// 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' })
+```
+
 ## API Reference
 
 ### `initializeDatabase(schemaData: SchemaData)`
@@ -279,7 +416,16 @@ MIT © Damilola Alao
 
 ## Changelog
 
-### 1.0.0
+### 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

package/llm.txt

@@ -0,0 +1,268 @@
+# nanodb-orm - LLM Documentation
+
+## Package Overview
+nanodb-orm is a generic, flexible database package built on top of Drizzle ORM. It provides auto-migrations, schema introspection, and multi-database support for SQLite and Turso databases.
+
+## Package Information
+- **Name**: nanodb-orm
+- **Version**: 0.0.2
+- **License**: MIT
+- **Repository**: https://github.com/damilolaalao/nanodb-orm
+- **NPM**: https://www.npmjs.com/package/nanodb-orm
+
+## Installation
+```bash
+npm install nanodb-orm
+```
+
+## Core Features
+1. **Generic Database Operations**: Works with any table structure defined in schema
+2. **Auto-Migrations**: Automatic schema creation and migration handling
+3. **Schema Introspection**: Dynamic schema analysis and validation
+4. **Multi-Database Support**: SQLite (local) and Turso (cloud) databases
+5. **TypeScript Support**: Full TypeScript definitions and type safety
+6. **Data Seeding**: Built-in seed data management
+7. **Health Checks**: Database health monitoring and validation
+
+## Main Exports
+```typescript
+import { 
+  initializeDatabase,    // Initialize the package with schema
+  DatabaseSync,         // Database operations and health checks
+  SchemaIntrospection,  // Schema analysis utilities
+  DatabaseMigrations,   // Migration management
+  DatabaseSeeds,        // Seed data management
+  DatabaseConnection,   // Database connection management
+  logger               // Logging utilities
+} from 'nanodb-orm';
+```
+
+## Basic Usage Pattern
+```typescript
+// 1. Define your Drizzle tables (models/users.ts)
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+export const usersTable = sqliteTable('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  age: integer('age').notNull(),
+  email: text('email').unique().notNull(),
+});
+
+// models/posts.ts
+import { sql } from 'drizzle-orm';
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+import { usersTable } from './users';
+
+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(),
+});
+
+// models/index.ts
+import { usersTable } from './users';
+import { postsTable } from './posts';
+
+export const tables = {
+  users: usersTable,
+  posts: postsTable,
+} as const;
+
+// 2. Initialize the package
+initializeDatabase({ 
+  tables,
+  seedData: {
+    users: [{ name: 'John Doe', age: 30, email: 'john@example.com' }],
+    posts: [{ title: 'Welcome', content: 'First post!', userId: 1 }]
+  }
+});
+
+// 3. Setup database
+await DatabaseSync.setup();
+
+// 4. Use the database
+const health = await DatabaseSync.healthCheck();
+```
+
+## Schema Definition Format
+nanodb-orm works with Drizzle ORM table definitions. Tables are defined using Drizzle's `sqliteTable` function:
+
+```typescript
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+export const tableName = sqliteTable('table_name', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  email: text('email').unique().notNull(),
+  isActive: integer('is_active').notNull().default(1),
+  createdAt: text('created_at').default(sql`(datetime('now'))`).notNull()
+});
+```
+
+### Drizzle Column Types and Methods:
+- **Types**: `integer()`, `text()`, `real()`, `blob()`
+- **Methods**: `.primaryKey()`, `.notNull()`, `.unique()`, `.default()`, `.references()`
+
+## Database Configuration
+The package automatically detects the environment and uses:
+- **Local SQLite**: When no Turso configuration is found
+- **Turso**: When TURSO_DATABASE_URL and TURSO_AUTH_TOKEN are set
+
+## Key Classes and Methods
+
+### DatabaseSync
+- `setup()`: Initialize database schema and seed data
+- `healthCheck()`: Check database health and schema validity
+- `reset()`: Reset database (drop, recreate, seed)
+- `getDatabaseInfo()`: Get comprehensive database information
+
+### SchemaIntrospection
+- `getAllTableNames()`: Get all table names from schema
+- `getTable(tableName)`: Get table definition
+- `getColumnNames(tableName)`: Get column names for a table
+- `getSchemaStats()`: Get schema statistics
+- `validateSchema()`: Validate database schema matches definition
+
+### DatabaseMigrations
+- `initializeSchema()`: Create tables using Drizzle
+- `validateSchema()`: Validate schema integrity
+- `checkTableExistence()`: Check which tables exist
+
+### DatabaseSeeds
+- `seedDatabase()`: Seed database with sample data
+- `hasData()`: Check if database has existing data
+
+## Error Handling
+The package provides custom error classes:
+- `DatabaseError`: Base database error
+- `SchemaError`: Schema-related errors
+- `SyncError`: Synchronization errors
+- `ConnectionError`: Connection-related errors
+- `ValidationError`: Validation errors
+
+## Logging
+Built-in logging system with different levels:
+- `logger.info()`: Information messages
+- `logger.warn()`: Warning messages
+- `logger.error()`: Error messages
+- `logger.debug()`: Debug messages
+
+## Testing
+The package includes comprehensive tests:
+- Package initialization tests
+- Schema introspection tests
+- Database setup tests
+- Health check tests
+
+## File Structure
+```
+nanodb-orm/
+├── core/           # Core database functionality
+├── utils/          # Utility classes and functions
+├── types/          # TypeScript type definitions
+├── constants/      # Package constants
+├── dist/           # Compiled JavaScript output
+├── __tests__/      # Test files
+├── example.ts      # Usage example
+└── package.json    # Package configuration
+```
+
+## Dependencies
+- **@libsql/client**: Turso database client
+- **drizzle-orm**: Database ORM
+- **dotenv**: Environment variable management (peer dependency)
+
+## Development Dependencies
+- **TypeScript**: Type checking and compilation
+- **Jest**: Testing framework
+- **@types/node**: Node.js type definitions
+
+## Environment Variables
+- `TURSO_DATABASE_URL`: Turso database URL
+- `TURSO_AUTH_TOKEN`: Turso authentication token
+- `NODE_ENV`: Environment (development, production, test)
+- `FORCE_LOCAL_DB`: Force local SQLite usage
+
+## Migration Configuration
+```typescript
+const migrationConfig = {
+  preserveData: true,    // Preserve existing data during migrations
+  autoMigrate: true,     // Enable automatic migrations
+  dropTables: false      // Don't drop tables by default
+};
+```
+
+## Seed Data Format
+```typescript
+const seedData = {
+  tableName: [
+    { column1: 'value1', column2: 'value2' },
+    { column1: 'value3', column2: 'value4' }
+  ]
+};
+```
+
+## Health Check Response
+```typescript
+{
+  healthy: boolean,
+  tables: string[],
+  tableCounts: Record<string, number>,
+  totalRecords: number,
+  schemaValid: boolean,
+  syncSupported: boolean,
+  errors: string[]
+}
+```
+
+## Best Practices
+1. Always initialize the package before using any database operations
+2. Use TypeScript for better type safety
+3. Define clear schema structures
+4. Handle errors appropriately
+5. Use health checks in production
+6. Test with different database configurations
+
+## Common Use Cases
+1. **Rapid Prototyping**: Quick database setup for new projects
+2. **Microservices**: Lightweight database layer for services
+3. **Full-Stack Applications**: Backend database management
+4. **Testing**: Database utilities for test suites
+5. **Data Migration**: Schema migration and data seeding
+
+## Support and Documentation
+- **GitHub**: https://github.com/damilolaalao/nanodb-orm
+- **NPM**: https://www.npmjs.com/package/nanodb-orm
+- **Issues**: https://github.com/damilolaalao/nanodb-orm/issues
+
+## License
+MIT License - see LICENSE file for details.
+
+## Author
+Damilola Alao
+
+## Version History
+### 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 (SQLite, Turso)
+- TypeScript support
+- Testing utilities
+- Comprehensive documentation

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "nanodb-orm",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Generic database package with Drizzle ORM, auto-migrations, and schema introspection",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist/**/*",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "llm.txt"
   ],
   "scripts": {
     "build": "tsc",