nanodb-orm 0.0.1 → 0.0.3

package/README.md

@@ -1,16 +1,20 @@
 # nanodb-orm
 
-A generic, flexible database package built on top of Drizzle ORM with automatic migrations, schema introspection, and support for both local SQLite and remote Turso databases.
+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.
 
 ## 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
-- 📦 **NPM Package Ready**: Designed to be used as a standalone npm package
+- ⚡ **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
 
 ## Installation
 
@@ -20,16 +24,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 +134,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)`
@@ -200,6 +341,71 @@ initializeDatabase({
 });
 ```
 
+### 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
+});
+
+// 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 ...')
+]);
+
+// Table recreation with transactions
+await TransactionManager.recreateTable('users', async (db) => {
+  await db.run('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+});
+```
+
+### 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
@@ -279,7 +485,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/dist/core/connection.d.ts

@@ -1,15 +1,27 @@
+import { drizzle } from 'drizzle-orm/libsql';
 /**
  * Database connection management
  * Handles the creation and configuration of database connections
  */
 export declare class DatabaseConnection {
     private static instance;
+    private static isCreating;
+    private static creationPromise;
     /**
-     * Get or create the database connection instance
+     * Get or create the database connection instance (thread-safe)
      */
-    static getInstance(): import("drizzle-orm/libsql").LibSQLDatabase<Record<string, unknown>> & {
+    static getInstance(): Promise<ReturnType<typeof drizzle>>;
+    /**
+     * Synchronous getter for backward compatibility (deprecated)
+     * @deprecated Use getInstance() instead for thread safety
+     */
+    static getInstanceSync(): import("drizzle-orm/libsql").LibSQLDatabase<Record<string, unknown>> & {
         $client: import("@libsql/client").Client;
     };
+    /**
+     * Create a new database connection asynchronously
+     */
+    private static createConnectionAsync;
     /**
      * Create a new database connection
      */

package/dist/core/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../core/connection.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2C;IAElE;;OAEG;IACH,MAAM,CAAC,WAAW;;;IAOlB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAmC/B;;OAEG;IACH,MAAM,CAAC,KAAK;IAIZ;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,OAAO;CAG9B;AAGD,eAAO,MAAM,EAAE;;CAAmC,CAAC"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../core/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAK7C;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2C;IAClE,OAAO,CAAC,MAAM,CAAC,UAAU,CAAS;IAClC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAoD;IAElF;;OAEG;WACU,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;IAqB/D;;;OAGG;IACH,MAAM,CAAC,eAAe;;;IAOtB;;OAEG;mBACkB,qBAAqB;IAI1C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAmC/B;;OAEG;IACH,MAAM,CAAC,KAAK;IAMZ;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,OAAO;CAG9B;AAGD,eAAO,MAAM,EAAE;;CAAuC,CAAC"}

package/dist/core/connection.js

@@ -11,14 +11,42 @@ const errors_1 = require("../types/errors");
  */
 class DatabaseConnection {
     /**
-     * Get or create the database connection instance
+     * Get or create the database connection instance (thread-safe)
      */
-    static getInstance() {
+    static async getInstance() {
+        if (this.instance) {
+            return this.instance;
+        }
+        if (this.isCreating && this.creationPromise) {
+            return this.creationPromise;
+        }
+        this.isCreating = true;
+        this.creationPromise = this.createConnectionAsync();
+        try {
+            this.instance = await this.creationPromise;
+            return this.instance;
+        }
+        finally {
+            this.isCreating = false;
+            this.creationPromise = null;
+        }
+    }
+    /**
+     * Synchronous getter for backward compatibility (deprecated)
+     * @deprecated Use getInstance() instead for thread safety
+     */
+    static getInstanceSync() {
         if (!this.instance) {
             this.instance = this.createConnection();
         }
         return this.instance;
     }
+    /**
+     * Create a new database connection asynchronously
+     */
+    static async createConnectionAsync() {
+        return this.createConnection();
+    }
     /**
      * Create a new database connection
      */
@@ -62,6 +90,8 @@ class DatabaseConnection {
      */
     static reset() {
         this.instance = null;
+        this.isCreating = false;
+        this.creationPromise = null;
     }
     /**
      * Check if connection is established
@@ -72,6 +102,8 @@ class DatabaseConnection {
 }
 exports.DatabaseConnection = DatabaseConnection;
 DatabaseConnection.instance = null;
-// Export the database instance for convenience
-exports.db = DatabaseConnection.getInstance();
+DatabaseConnection.isCreating = false;
+DatabaseConnection.creationPromise = null;
+// Export the database instance for convenience (deprecated - use getInstance() instead)
+exports.db = DatabaseConnection.getInstanceSync();
 //# sourceMappingURL=connection.js.map

package/dist/core/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../core/connection.ts"],"names":[],"mappings":";;;AAAA,+CAA6C;AAC7C,2CAA8C;AAC9C,qCAA6C;AAC7C,4CAAgD;AAEhD;;;GAGG;AACH,MAAa,kBAAkB;IAG7B;;OAEG;IACH,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1C,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,gBAAgB;QAC7B,IAAI,CAAC;YACH,4EAA4E;YAC5E,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,MAAM,EAAE,CAAC;gBAC7E,iEAAiE;gBACjE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;gBACpG,OAAO,CAAC,GAAG,CAAC,4CAA4C,UAAU,EAAE,CAAC,CAAC;gBACtE,MAAM,MAAM,GAAG,IAAA,qBAAY,EAAC;oBAC1B,GAAG,EAAE,QAAQ,UAAU,EAAE;iBAC1B,CAAC,CAAC;gBACH,OAAO,IAAA,gBAAO,EAAC,MAAM,CAAC,CAAC;YACzB,CAAC;YAED,2EAA2E;YAC3E,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAA,0BAAiB,GAAE,CAAC;gBACnC,MAAM,MAAM,GAAG,IAAA,qBAAY,EAAC;oBAC1B,GAAG,EAAE,MAAM,CAAC,aAAa;oBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;iBAC5B,CAAC,CAAC;gBACH,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;gBAC3C,OAAO,IAAA,gBAAO,EAAC,MAAM,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,WAAW,EAAE,CAAC;gBACrB,oCAAoC;gBACpC,OAAO,CAAC,GAAG,CAAC,qDAAqD,CAAC,CAAC;gBACnE,MAAM,MAAM,GAAG,IAAA,qBAAY,EAAC;oBAC1B,GAAG,EAAE,kBAAkB;iBACxB,CAAC,CAAC;gBACH,OAAO,IAAA,gBAAO,EAAC,MAAM,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,sBAAa,CAAC,yCAA0C,KAAe,CAAC,OAAO,EAAE,EAAE,YAAY,EAAE,KAAc,CAAC,CAAC;QAC7H,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK;QACV,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,WAAW;QAChB,OAAO,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC;IAChC,CAAC;;AA/DH,gDAgEC;AA/DgB,2BAAQ,GAAsC,IAAI,CAAC;AAiEpE,+CAA+C;AAClC,QAAA,EAAE,GAAG,kBAAkB,CAAC,WAAW,EAAE,CAAC"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../core/connection.ts"],"names":[],"mappings":"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"}

package/dist/types/database.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Database type definitions for better type safety
+ */
+export interface DatabaseClient {
+    run(query: string, params?: any[]): Promise<{
+        rows: any[];
+    }>;
+    $client?: {
+        sync?: () => Promise<void>;
+        [key: string]: any;
+    };
+}
+export interface TableColumn {
+    name: string;
+    dataType: string;
+    primary?: boolean;
+    autoIncrement?: boolean;
+    notNull?: boolean;
+    unique?: boolean;
+    default?: any;
+    references?: {
+        table: string;
+        column: string;
+        onDelete?: string;
+    };
+}
+export interface TableDefinition {
+    name: string;
+    columns: Record<string, TableColumn>;
+    primaryKey: string[];
+    foreignKeys: Array<{
+        column: string;
+        references: string;
+        table: string;
+    }>;
+    indexes: string[];
+}
+export interface DatabaseRow {
+    [key: string]: any;
+}
+export interface QueryResult {
+    rows: DatabaseRow[];
+    changes?: number;
+    lastInsertRowid?: number;
+}
+export interface MigrationResult {
+    success: boolean;
+    message: string;
+    tablesAffected: string[];
+    errors: string[];
+}
+export interface SchemaValidationResult {
+    isValid: boolean;
+    missingTables: string[];
+    extraTables: string[];
+    errors: string[];
+}
+export interface DatabaseInfoExtended {
+    tables: string[];
+    tableCounts: Record<string, number>;
+    totalRecords: number;
+    schemaValid: boolean;
+    syncSupported: boolean;
+}
+export interface HealthCheckResultExtended {
+    healthy: boolean;
+    tables: string[];
+    tableCounts: Record<string, number>;
+    totalRecords: number;
+    schemaValid: boolean;
+    syncSupported: boolean;
+    errors: string[];
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/types/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../types/database.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,UAAU,CAAC,EAAE;QACX,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,KAAK,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/dist/types/database.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Database type definitions for better type safety
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=database.js.map

package/dist/types/database.js.map

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

package/dist/types/index.d.ts

@@ -4,4 +4,5 @@
  */
 export * from './types';
 export * from './errors';
+export * from './database';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}

package/dist/types/index.js

@@ -20,4 +20,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types"), exports);
 __exportStar(require("./errors"), exports);
+__exportStar(require("./database"), exports);
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,2CAAyB;AACzB,6CAA2B"}

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Standardized error handling utilities for database operations
+ */
+import { DatabaseError } from '../types/errors';
+export interface ErrorHandlerOptions {
+    operation: string;
+    context?: string | undefined;
+    throwError?: boolean;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+/**
+ * Standardized error handling for database operations
+ */
+export declare class ErrorHandler {
+    /**
+     * Handle database errors with consistent logging and error creation
+     */
+    static handleError(error: unknown, options: ErrorHandlerOptions): DatabaseError | null;
+    /**
+     * Handle errors that should not throw (e.g., validation failures)
+     */
+    static handleNonThrowingError(error: unknown, operation: string, context?: string): DatabaseError;
+    /**
+     * Handle errors that should be logged but not thrown (e.g., optional operations)
+     */
+    static handleOptionalError(error: unknown, operation: string, context?: string): void;
+    /**
+     * Wrap async operations with standardized error handling
+     */
+    static wrapAsync<T>(operation: () => Promise<T>, options: ErrorHandlerOptions): Promise<T>;
+    /**
+     * Wrap sync operations with standardized error handling
+     */
+    static wrapSync<T>(operation: () => T, options: ErrorHandlerOptions): T;
+}
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/utils/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../utils/error-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB;;OAEG;IACH,MAAM,CAAC,WAAW,CAChB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,mBAAmB,GAC3B,aAAa,GAAG,IAAI;IAuCvB;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAC3B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,aAAa;IAUhB;;OAEG;IACH,MAAM,CAAC,mBAAmB,CACxB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,IAAI;IASP;;OAEG;WACU,SAAS,CAAC,CAAC,EACtB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC;IASb;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,CAAC,EACf,SAAS,EAAE,MAAM,CAAC,EAClB,OAAO,EAAE,mBAAmB,GAC3B,CAAC;CAQL"}

package/dist/utils/error-handler.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Standardized error handling utilities for database operations
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorHandler = void 0;
+const logger_1 = require("./logger");
+const errors_1 = require("../types/errors");
+/**
+ * Standardized error handling for database operations
+ */
+class ErrorHandler {
+    /**
+     * Handle database errors with consistent logging and error creation
+     */
+    static handleError(error, options) {
+        const { operation, context, throwError = true, logLevel = 'error' } = options;
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const fullMessage = context
+            ? `${context}: ${errorMessage}`
+            : errorMessage;
+        const dbError = new errors_1.DatabaseError(fullMessage, operation, error instanceof Error ? error : undefined);
+        // Log with appropriate level
+        switch (logLevel) {
+            case 'debug':
+                logger_1.logger.debug(dbError.message, dbError);
+                break;
+            case 'info':
+                logger_1.logger.info(dbError.message, dbError);
+                break;
+            case 'warn':
+                logger_1.logger.warn(dbError.message, dbError);
+                break;
+            case 'error':
+            default:
+                logger_1.logger.error(dbError.message, dbError);
+                break;
+        }
+        if (throwError) {
+            throw dbError;
+        }
+        return dbError;
+    }
+    /**
+     * Handle errors that should not throw (e.g., validation failures)
+     */
+    static handleNonThrowingError(error, operation, context) {
+        const result = this.handleError(error, {
+            operation,
+            context,
+            throwError: false,
+            logLevel: 'warn'
+        });
+        return result; // We know it won't be null because throwError is false
+    }
+    /**
+     * Handle errors that should be logged but not thrown (e.g., optional operations)
+     */
+    static handleOptionalError(error, operation, context) {
+        this.handleError(error, {
+            operation,
+            context,
+            throwError: false,
+            logLevel: 'info'
+        });
+    }
+    /**
+     * Wrap async operations with standardized error handling
+     */
+    static async wrapAsync(operation, options) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            this.handleError(error, options);
+            throw error; // This will never be reached due to handleError throwing
+        }
+    }
+    /**
+     * Wrap sync operations with standardized error handling
+     */
+    static wrapSync(operation, options) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            this.handleError(error, options);
+            throw error; // This will never be reached due to handleError throwing
+        }
+    }
+}
+exports.ErrorHandler = ErrorHandler;
+//# sourceMappingURL=error-handler.js.map

package/dist/utils/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../utils/error-handler.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,qCAAkC;AAClC,4CAAgD;AAShD;;GAEG;AACH,MAAa,YAAY;IACvB;;OAEG;IACH,MAAM,CAAC,WAAW,CAChB,KAAc,EACd,OAA4B;QAE5B,MAAM,EACJ,SAAS,EACT,OAAO,EACP,UAAU,GAAG,IAAI,EACjB,QAAQ,GAAG,OAAO,EACnB,GAAG,OAAO,CAAC;QAEZ,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,WAAW,GAAG,OAAO;YACzB,CAAC,CAAC,GAAG,OAAO,KAAK,YAAY,EAAE;YAC/B,CAAC,CAAC,YAAY,CAAC;QAEjB,MAAM,OAAO,GAAG,IAAI,sBAAa,CAAC,WAAW,EAAE,SAAS,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAEtG,6BAA6B;QAC7B,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,OAAO;gBACV,eAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACvC,MAAM;YACR,KAAK,MAAM;gBACT,eAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACtC,MAAM;YACR,KAAK,MAAM;gBACT,eAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACtC,MAAM;YACR,KAAK,OAAO,CAAC;YACb;gBACE,eAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBACvC,MAAM;QACV,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,OAAO,CAAC;QAChB,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAC3B,KAAc,EACd,SAAiB,EACjB,OAAgB;QAEhB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE;YACrC,SAAS;YACT,OAAO;YACP,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QACH,OAAO,MAAO,CAAC,CAAC,uDAAuD;IACzE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,mBAAmB,CACxB,KAAc,EACd,SAAiB,EACjB,OAAgB;QAEhB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE;YACtB,SAAS;YACT,OAAO;YACP,UAAU,EAAE,KAAK;YACjB,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,SAAS,CACpB,SAA2B,EAC3B,OAA4B;QAE5B,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACjC,MAAM,KAAK,CAAC,CAAC,yDAAyD;QACxE,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAQ,CACb,SAAkB,EAClB,OAA4B;QAE5B,IAAI,CAAC;YACH,OAAO,SAAS,EAAE,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACjC,MAAM,KAAK,CAAC,CAAC,yDAAyD;QACxE,CAAC;IACH,CAAC;CACF;AA5GD,oCA4GC"}

package/dist/utils/index.d.ts

@@ -7,4 +7,6 @@ export { DatabaseMigrations } from './migrations';
 export { DatabaseSeeds } from './seeds';
 export { SchemaIntrospection } from './schema-introspection';
 export { logger } from './logger';
+export { ErrorHandler } from './error-handler';
+export { TransactionManager } from './transactions';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}