nanodb-orm 0.0.2 → 0.0.3

package/dist/utils/transactions.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Transaction utilities for atomic database operations
+ */
+import { DatabaseClient } from '../types/database';
+export interface TransactionOptions {
+    isolationLevel?: 'READ_UNCOMMITTED' | 'READ_COMMITTED' | 'REPEATABLE_READ' | 'SERIALIZABLE';
+    timeout?: number;
+}
+export interface TransactionResult<T> {
+    success: boolean;
+    result?: T;
+    error?: Error;
+    rollbackError?: Error;
+}
+/**
+ * Transaction management utilities
+ */
+export declare class TransactionManager {
+    /**
+     * Execute a function within a database transaction
+     */
+    static execute<T>(operation: (db: DatabaseClient) => Promise<T>, options?: TransactionOptions): Promise<TransactionResult<T>>;
+    /**
+     * Execute multiple operations in a single transaction
+     */
+    static executeBatch<T>(operations: Array<(db: DatabaseClient) => Promise<T>>, options?: TransactionOptions): Promise<TransactionResult<T[]>>;
+    /**
+     * Execute a migration operation with transaction support
+     */
+    static executeMigration(migrationOperation: (db: DatabaseClient) => Promise<void>, options?: TransactionOptions): Promise<TransactionResult<void>>;
+    /**
+     * Execute table recreation with transaction support
+     */
+    static recreateTable(tableName: string, createOperation: (db: DatabaseClient) => Promise<void>, options?: TransactionOptions): Promise<TransactionResult<void>>;
+    /**
+     * Execute data seeding with transaction support
+     */
+    static seedData(seedOperation: (db: DatabaseClient) => Promise<void>, options?: TransactionOptions): Promise<TransactionResult<void>>;
+    /**
+     * Execute database reset with transaction support
+     */
+    static resetDatabase(resetOperation: (db: DatabaseClient) => Promise<void>, options?: TransactionOptions): Promise<TransactionResult<void>>;
+    /**
+     * Check if the database supports transactions
+     */
+    static supportsTransactions(): Promise<boolean>;
+    /**
+     * Get transaction status
+     */
+    static getTransactionStatus(): Promise<{
+        inTransaction: boolean;
+        supportsTransactions: boolean;
+    }>;
+}
+//# sourceMappingURL=transactions.d.ts.map

package/dist/utils/transactions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactions.d.ts","sourceRoot":"","sources":["../../utils/transactions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IACjC,cAAc,CAAC,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,cAAc,CAAC;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,KAAK,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,kBAAkB;IAC7B;;OAEG;WACU,OAAO,CAAC,CAAC,EACpB,SAAS,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7C,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAgDhC;;OAEG;WACU,YAAY,CAAC,CAAC,EACzB,UAAU,EAAE,KAAK,CAAC,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EACrD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;IAalC;;OAEG;WACU,gBAAgB,CAC3B,kBAAkB,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EACzD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAQnC;;OAEG;WACU,aAAa,CACxB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EACtD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAgBnC;;OAEG;WACU,QAAQ,CACnB,aAAa,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EACpD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAQnC;;OAEG;WACU,aAAa,CACxB,cAAc,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,EACrD,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAQnC;;OAEG;WACU,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;IAgBrD;;OAEG;WACU,oBAAoB,IAAI,OAAO,CAAC;QAC3C,aAAa,EAAE,OAAO,CAAC;QACvB,oBAAoB,EAAE,OAAO,CAAC;KAC/B,CAAC;CAuBH"}

package/dist/utils/transactions.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Transaction utilities for atomic database operations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionManager = void 0;
+const connection_1 = require("../core/connection");
+const logger_1 = require("./logger");
+const error_handler_1 = require("./error-handler");
+/**
+ * Transaction management utilities
+ */
+class TransactionManager {
+    /**
+     * Execute a function within a database transaction
+     */
+    static async execute(operation, options = {}) {
+        const db = await connection_1.DatabaseConnection.getInstance();
+        const client = db;
+        try {
+            logger_1.logger.debug('Starting database transaction');
+            // Begin transaction
+            await client.run('BEGIN TRANSACTION');
+            // Set isolation level if specified
+            if (options.isolationLevel) {
+                await client.run(`SET TRANSACTION ISOLATION LEVEL ${options.isolationLevel}`);
+            }
+            // Execute the operation
+            const result = await operation(client);
+            // Commit transaction
+            await client.run('COMMIT');
+            logger_1.logger.debug('Transaction committed successfully');
+            return {
+                success: true,
+                result
+            };
+        }
+        catch (error) {
+            logger_1.logger.error('Transaction failed, attempting rollback:', error);
+            try {
+                await client.run('ROLLBACK');
+                logger_1.logger.debug('Transaction rolled back successfully');
+            }
+            catch (rollbackError) {
+                logger_1.logger.error('Failed to rollback transaction:', rollbackError);
+                return {
+                    success: false,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    rollbackError: rollbackError instanceof Error ? rollbackError : new Error(String(rollbackError))
+                };
+            }
+            return {
+                success: false,
+                error: error instanceof Error ? error : new Error(String(error))
+            };
+        }
+    }
+    /**
+     * Execute multiple operations in a single transaction
+     */
+    static async executeBatch(operations, options = {}) {
+        return this.execute(async (db) => {
+            const results = [];
+            for (const operation of operations) {
+                const result = await operation(db);
+                results.push(result);
+            }
+            return results;
+        }, options);
+    }
+    /**
+     * Execute a migration operation with transaction support
+     */
+    static async executeMigration(migrationOperation, options = {}) {
+        return this.execute(async (db) => {
+            logger_1.logger.info('Executing migration within transaction');
+            await migrationOperation(db);
+            logger_1.logger.info('Migration completed successfully');
+        }, options);
+    }
+    /**
+     * Execute table recreation with transaction support
+     */
+    static async recreateTable(tableName, createOperation, options = {}) {
+        return this.execute(async (db) => {
+            logger_1.logger.info(`Recreating table ${tableName} within transaction`);
+            // Drop table if exists
+            await db.run(`DROP TABLE IF EXISTS ${tableName}`);
+            logger_1.logger.debug(`Dropped table ${tableName}`);
+            // Create new table
+            await createOperation(db);
+            logger_1.logger.debug(`Created table ${tableName}`);
+            logger_1.logger.info(`Table ${tableName} recreated successfully`);
+        }, options);
+    }
+    /**
+     * Execute data seeding with transaction support
+     */
+    static async seedData(seedOperation, options = {}) {
+        return this.execute(async (db) => {
+            logger_1.logger.info('Seeding data within transaction');
+            await seedOperation(db);
+            logger_1.logger.info('Data seeding completed successfully');
+        }, options);
+    }
+    /**
+     * Execute database reset with transaction support
+     */
+    static async resetDatabase(resetOperation, options = {}) {
+        return this.execute(async (db) => {
+            logger_1.logger.warn('Resetting database within transaction');
+            await resetOperation(db);
+            logger_1.logger.info('Database reset completed successfully');
+        }, options);
+    }
+    /**
+     * Check if the database supports transactions
+     */
+    static async supportsTransactions() {
+        try {
+            const db = await connection_1.DatabaseConnection.getInstance();
+            const client = db;
+            // Try to start a transaction
+            await client.run('BEGIN TRANSACTION');
+            await client.run('ROLLBACK');
+            return true;
+        }
+        catch (error) {
+            error_handler_1.ErrorHandler.handleOptionalError(error, 'check-transaction-support', 'Database does not support transactions');
+            return false;
+        }
+    }
+    /**
+     * Get transaction status
+     */
+    static async getTransactionStatus() {
+        try {
+            const db = await connection_1.DatabaseConnection.getInstance();
+            const client = db;
+            // Check if we're in a transaction
+            const result = await client.run('SELECT * FROM pragma_transaction_state');
+            const inTransaction = result.rows.length > 0 && result.rows[0].state === 'active';
+            const supportsTransactions = await this.supportsTransactions();
+            return {
+                inTransaction,
+                supportsTransactions
+            };
+        }
+        catch (error) {
+            error_handler_1.ErrorHandler.handleNonThrowingError(error, 'get-transaction-status', 'Failed to get transaction status');
+            return {
+                inTransaction: false,
+                supportsTransactions: false
+            };
+        }
+    }
+}
+exports.TransactionManager = TransactionManager;
+//# sourceMappingURL=transactions.js.map

package/dist/utils/transactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactions.js","sourceRoot":"","sources":["../../utils/transactions.ts"],"names":[],"mappings":"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"}

package/llm.txt

@@ -5,7 +5,7 @@ nanodb-orm is a generic, flexible database package built on top of Drizzle ORM.
 
 ## Package Information
 - **Name**: nanodb-orm
-- **Version**: 0.0.2
+- **Version**: 0.0.3
 - **License**: MIT
 - **Repository**: https://github.com/damilolaalao/nanodb-orm
 - **NPM**: https://www.npmjs.com/package/nanodb-orm
@@ -20,9 +20,13 @@ npm install nanodb-orm
 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
+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
@@ -33,6 +37,8 @@ import {
   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';
 ```
@@ -139,6 +145,68 @@ The package automatically detects the environment and uses:
 - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nanodb-orm",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Generic database package with Drizzle ORM, auto-migrations, and schema introspection",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",