nanodb-orm 0.0.3 → 0.0.5

package/dist/types/types.js

@@ -1,6 +0,0 @@
-"use strict";
-/**
- * Database-related TypeScript interfaces and types
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/types/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../types/types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/llm.txt

@@ -1,336 +0,0 @@
-# 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.3
-- **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. **Atomic Transactions**: Full transaction support with rollback protection
-6. **TypeScript Support**: Full TypeScript definitions and type safety
-7. **Data Seeding**: Built-in seed data management
-8. **Health Checks**: Database health monitoring and validation
-9. **Thread Safety**: Race condition fixes and concurrent access protection
-10. **Security**: SQL injection protection and input validation
-11. **Error Handling**: Standardized error handling and recovery
-
-## 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
-  TransactionManager,   // NEW: Transaction management
-  ErrorHandler,         // NEW: Standardized error handling
-  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
-
-## NEW in v0.0.3: Transaction Support
-
-### TransactionManager
-```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
-});
-
-// Batch operations
-await TransactionManager.executeBatch([
-  async (db) => await db.run('INSERT INTO users ...'),
-  async (db) => await db.run('INSERT INTO posts ...')
-]);
-
-// Table recreation with transactions
-await TransactionManager.recreateTable('users', async (db) => {
-  await db.run('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-});
-
-// Check transaction support
-const supportsTransactions = await TransactionManager.supportsTransactions();
-const status = await TransactionManager.getTransactionStatus();
-```
-
-### Enhanced Error Handling
-```typescript
-import { ErrorHandler, DatabaseError } from 'nanodb-orm';
-
-// Standardized error handling
-try {
-  await DatabaseSync.setup();
-} catch (error) {
-  if (error instanceof DatabaseError) {
-    console.log('Operation:', error.operation);
-    console.log('Context:', error.message);
-  }
-}
-
-// Non-throwing error handling
-const result = ErrorHandler.handleNonThrowingError(
-  someError, 
-  'optional-operation', 
-  'This operation is optional'
-);
-```
-
-### Thread-Safe Connections
-```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();
-```
-
-## 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