@groundbrick/db-core 0.0.1

package/README.md

@@ -0,0 +1,214 @@
+
+# @groundbrick/db-core
+
+**Database abstraction core for the BitBrick microframework**
+
+This package provides the backbone for integrating with relational databases (PostgreSQL or MySQL), offering a unified layer for connection handling, querying, transactions, and migrations.
+
+---
+
+## 🔧 Key Features
+
+- Unified interface for database clients
+- Adapter support for PostgreSQL and MySQL (via external factories)
+- Full support for transactions
+- Strongly-typed migration system
+- Configuration validation and health checks
+- Granular error handling by operation type
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @groundbrick/db-core
+```
+
+> You will also need to install a specific adapter package such as `@groundbrick/db-postgres` or `@groundbrick/db-mysql`.
+
+---
+
+## 🚀 Quick Start
+
+```ts
+import { DatabaseAdapter } from '@groundbrick/db-core';
+
+const adapter = new DatabaseAdapter({
+  type: 'postgresql',
+  host: 'localhost',
+  user: 'admin',
+  password: 'secret',
+  database: 'mydb',
+  port: 5432
+});
+
+await adapter.initialize();
+
+const users = await adapter.query('SELECT * FROM users WHERE active = $1', [true]);
+
+await adapter.close();
+```
+
+---
+
+## 🔄 Transactions
+
+```ts
+await adapter.transaction(async (trx) => {
+  await trx.query('INSERT INTO logs (event, ts) VALUES ($1, now())', ['create_user']);
+
+  const result = await trx.query<{ id: number }>(
+    'INSERT INTO users (email, active) VALUES ($1, $2) RETURNING id',
+    ['user@example.com', true]
+  );
+
+  const userId = result.rows[0].id;
+
+  await trx.query('INSERT INTO profiles (user_id) VALUES ($1)', [userId]);
+});
+```
+
+- The transaction will automatically **commit** if successful
+- Any thrown error will **rollback** the transaction
+- Nested transactions are not natively supported
+
+---
+
+## 🧪 Health Check
+
+```ts
+const status = await adapter.healthCheck();
+
+if (status.status !== 'ok') {
+  throw new Error(`Database unavailable: ${status.reason}`);
+}
+```
+
+---
+
+## 🔍 Pool Info (if supported by the adapter)
+
+```ts
+const pool = adapter.getClient().getConnectionInfo?.();
+if (pool) {
+  console.log(`Pool: total=${pool.total}, idle=${pool.idle}, waiting=${pool.waiting}`);
+}
+```
+
+---
+
+## ⏱ Readiness Check
+
+```ts
+if (!adapter.isReady()) {
+  console.warn('Adapter is not ready yet.');
+}
+```
+
+---
+
+## 📦 Architecture Overview
+
+### 🔌 DatabaseAdapter
+
+This class encapsulates adapter selection (PostgreSQL or MySQL), dynamically initializes the correct client, and exposes high-level methods:
+
+- `.initialize()` / `.close()`
+- `.query(sql, params)`
+- `.transaction(cb)`
+- `.healthCheck()`
+- `.getClient()` (direct access to `DatabaseClient`)
+
+> The dynamic loading logic (e.g., `PostgresFactory.getInstance`) must be implemented in the actual adapter packages.
+
+### 🧠 `DatabaseClient` Interface
+
+Contract that all database adapters must implement:
+
+```ts
+interface DatabaseClient {
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  query<T>(sql: string, params?: any[]): Promise<QueryResult<T>>;
+  transaction<T>(cb: (trx: DatabaseTransaction) => Promise<T>): Promise<T>;
+  healthCheck(): Promise<HealthCheckResult>;
+  isReady(): boolean;
+}
+```
+
+### 🔄 `DatabaseTransaction`
+
+Within a transaction, the callback receives a `DatabaseTransaction` instance, allowing you to perform isolated queries.
+
+---
+
+## 📁 Project Structure
+
+```
+db-core/
+├── src/
+│   ├── adapters/              # Generic adapter layer
+│   ├── base/                  # Reusable base logic (e.g., transactions)
+│   ├── custom-types/          # Utility and internal types
+│   ├── error-handling/        # Operation-specific error classes
+│   ├── interfaces/            # Public contract definitions
+│   └── index.ts               # Entry point
+```
+
+---
+
+## 🧬 Migrations
+
+The core defines types for managing and recording schema migrations. You can implement your own `MigrationManager`:
+
+```ts
+const manager: MigrationManager = getCustomMigrationManager();
+
+const pending = await manager.getPendingMigrations();
+
+for (const migration of pending) {
+  try {
+    await manager.applyMigration(migration);
+    console.log(`Migration ${migration.version} applied`);
+  } catch (err) {
+    console.error(`Failed to apply migration ${migration.version}:`, err);
+    break;
+  }
+}
+```
+
+Each migration should follow the `Migration` type contract with `up`, `down`, and `version` fields.
+
+---
+
+## 💣 Error Handling
+
+All operations raise specific error classes for easier diagnosis:
+
+- `ConnectionError`
+- `QueryError`
+- `MigrationError`
+- `TransactionError`
+- `DatabaseError` (generic base class)
+
+---
+
+## 🧩 Creating a Custom Adapter
+
+Example: PostgreSQL Adapter Factory
+
+```ts
+export class PostgresFactory {
+  static getInstance(config: DatabaseConfig, logger: Logger): DatabaseClient {
+    return new PostgresClient(config, logger);
+  }
+}
+```
+
+Inside `DatabaseAdapter`, you would dynamically import and use this factory depending on the type.
+
+---
+
+## 📝 License
+
+MIT — © 200Systems

package/dist/adapters/BaseSqlAdapter.d.ts

@@ -0,0 +1,14 @@
+import { SqlAdapter } from "../interfaces/SqlAdapter.js";
+export declare abstract class BaseSqlAdapter implements SqlAdapter {
+    abstract adaptSql(sql: string): string;
+    abstract getDatabaseType(): 'postgresql' | 'mysql';
+    abstract supportsReturning(): boolean;
+    createInsertSql(tableName: string, columns: string[]): string;
+    createUpdateSql(tableName: string, columns: string[]): string;
+    createDeleteSql(tableName: string): string;
+    getNowFunction(): string;
+    getLimitClause(limit: number, offset?: number): string;
+    protected abstract createPlaceholder(index: number): string;
+    protected createPlaceholders(count: number): string;
+}
+//# sourceMappingURL=BaseSqlAdapter.d.ts.map

package/dist/adapters/BaseSqlAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseSqlAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/BaseSqlAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,8BAAsB,cAAe,YAAW,UAAU;IACtD,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IACtC,QAAQ,CAAC,eAAe,IAAI,YAAY,GAAG,OAAO;IAClD,QAAQ,CAAC,iBAAiB,IAAI,OAAO;IAErC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM;IAW7D,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM;IAe7D,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAI1C,cAAc,IAAI,MAAM;IAIxB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,MAAM;IAOzD,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAE3D,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAGtD"}

package/dist/adapters/BaseSqlAdapter.js

@@ -0,0 +1,37 @@
+export class BaseSqlAdapter {
+    createInsertSql(tableName, columns) {
+        const placeholders = this.createPlaceholders(columns.length);
+        let sql = `INSERT INTO ${tableName} (${columns.join(', ')}) VALUES (${placeholders})`;
+        if (this.supportsReturning()) {
+            sql += ' RETURNING *';
+        }
+        return sql;
+    }
+    createUpdateSql(tableName, columns) {
+        const setParts = columns.map((col, index) => {
+            return `${col} = ${this.createPlaceholder(index + 1)}`;
+        });
+        const idPlaceholder = this.createPlaceholder(columns.length + 1);
+        let sql = `UPDATE ${tableName} SET ${setParts.join(', ')} WHERE id = ${idPlaceholder}`;
+        if (this.supportsReturning()) {
+            sql += ' RETURNING *';
+        }
+        return sql;
+    }
+    createDeleteSql(tableName) {
+        return this.adaptSql(`DELETE FROM ${tableName} WHERE id = ?`);
+    }
+    getNowFunction() {
+        return 'NOW()';
+    }
+    getLimitClause(limit, offset = 0) {
+        if (offset > 0) {
+            return `LIMIT ${limit} OFFSET ${offset}`;
+        }
+        return `LIMIT ${limit}`;
+    }
+    createPlaceholders(count) {
+        return Array.from({ length: count }, (_, i) => this.createPlaceholder(i + 1)).join(', ');
+    }
+}
+//# sourceMappingURL=BaseSqlAdapter.js.map

package/dist/adapters/BaseSqlAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseSqlAdapter.js","sourceRoot":"","sources":["../../src/adapters/BaseSqlAdapter.ts"],"names":[],"mappings":"AAEA,MAAM,OAAgB,cAAc;IAKhC,eAAe,CAAC,SAAiB,EAAE,OAAiB;QAChD,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7D,IAAI,GAAG,GAAG,eAAe,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,YAAY,GAAG,CAAC;QAEtF,IAAI,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;YAC3B,GAAG,IAAI,cAAc,CAAC;QAC1B,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;IAED,eAAe,CAAC,SAAiB,EAAE,OAAiB;QAChD,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YACxC,OAAO,GAAG,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;QAC3D,CAAC,CAAC,CAAC;QAEH,MAAM,aAAa,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACjE,IAAI,GAAG,GAAG,UAAU,SAAS,QAAQ,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,aAAa,EAAE,CAAC;QAEvF,IAAI,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;YAC3B,GAAG,IAAI,cAAc,CAAC;QAC1B,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;IAED,eAAe,CAAC,SAAiB;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,eAAe,SAAS,eAAe,CAAC,CAAC;IAClE,CAAC;IAED,cAAc;QACV,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,cAAc,CAAC,KAAa,EAAE,SAAiB,CAAC;QAC5C,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACb,OAAO,SAAS,KAAK,WAAW,MAAM,EAAE,CAAC;QAC7C,CAAC;QACD,OAAO,SAAS,KAAK,EAAE,CAAC;IAC5B,CAAC;IAIS,kBAAkB,CAAC,KAAa;QACtC,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7F,CAAC;CACJ"}

package/dist/adapters/DatabaseAdapter.d.ts

@@ -0,0 +1,59 @@
+import { Logger } from '@groundbrick/logger';
+import { DatabaseClient, DatabaseConfig } from '../interfaces/index.js';
+export type DatabaseType = 'postgresql' | 'mysql';
+export interface AdapterConfig extends DatabaseConfig {
+    type: DatabaseType;
+}
+/**
+ * Database Adapter that provides a unified interface for both PostgreSQL and MySQL
+ * This allows easy switching between database types without changing application code
+ */
+export declare class DatabaseAdapter {
+    private client;
+    private logger;
+    private dbType;
+    constructor(config: AdapterConfig, logger?: Logger);
+    private createPostgresClient;
+    private createMySQLClient;
+    /**
+     * Get the database type
+     */
+    getDatabaseType(): DatabaseType;
+    /**
+     * Initialize the database connection
+     */
+    initialize(): Promise<void>;
+    /**
+     * Close the database connection
+     */
+    close(): Promise<void>;
+    /**
+     * Get the underlying database client
+     * This allows access to all database-specific methods
+     */
+    getClient(): DatabaseClient;
+    /**
+     * Execute a database-agnostic query
+     */
+    query<T = any>(sql: string, params?: any[]): Promise<{
+        rows: T[];
+        rowCount: number;
+    }>;
+    /**
+     * Execute a transaction with unified interface
+     */
+    transaction<T>(callback: (client: DatabaseClient) => Promise<T>): Promise<T>;
+    /**
+     * Health check
+     */
+    healthCheck(): Promise<{
+        status: 'ok' | 'error';
+        timestamp: Date;
+        reason?: string;
+    }>;
+    /**
+     * Check if adapter is ready
+     */
+    isReady(): boolean;
+}
+//# sourceMappingURL=DatabaseAdapter.d.ts.map

package/dist/adapters/DatabaseAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DatabaseAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/DatabaseAdapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExE,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,aAAc,SAAQ,cAAc;IACjD,IAAI,EAAE,YAAY,CAAC;CACtB;AAED;;;GAGG;AACH,qBAAa,eAAe;IACxB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,MAAM;IAmBlD,OAAO,CAAC,oBAAoB;IAU5B,OAAO,CAAC,iBAAiB;IAUzB;;OAEG;IACH,eAAe,IAAI,YAAY;IAI/B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B;;;OAGG;IACH,SAAS,IAAI,cAAc;IAI3B;;OAEG;IACG,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ3F;;OAEG;IACG,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAalF;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,SAAS,EAAE,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAa1F;;OAEG;IACH,OAAO,IAAI,OAAO;CAGrB"}

package/dist/adapters/DatabaseAdapter.js

@@ -0,0 +1,120 @@
+import { createLogger } from '@groundbrick/logger';
+/**
+ * Database Adapter that provides a unified interface for both PostgreSQL and MySQL
+ * This allows easy switching between database types without changing application code
+ */
+export class DatabaseAdapter {
+    client;
+    logger;
+    dbType;
+    constructor(config, logger) {
+        this.logger = logger || createLogger({ context: 'database-adapter' });
+        this.dbType = config.type;
+        // Create the appropriate database client based on the type
+        switch (config.type) {
+            case 'postgresql':
+                this.client = this.createPostgresClient(config);
+                break;
+            case 'mysql':
+                this.client = this.createMySQLClient(config);
+                break;
+            default:
+                throw new Error(`Unsupported database type: ${config.type}`);
+        }
+        this.logger.info('Database adapter created', { type: config.type });
+    }
+    createPostgresClient(config) {
+        try {
+            // Use dynamic import to avoid bundling unused drivers
+            const { PostgresFactory } = require('@groundbrick/db-postgres');
+            return PostgresFactory.getInstance(config, this.logger);
+        }
+        catch (error) {
+            throw new Error(`Failed to load PostgreSQL driver: ${error instanceof Error ? error.message : 'Unknown error'}. Make sure @groundbrick/db-postgres is installed.`);
+        }
+    }
+    createMySQLClient(config) {
+        try {
+            // Use dynamic import to avoid bundling unused drivers
+            const { MySQLFactory } = require('@groundbrick/db-mysql');
+            return MySQLFactory.getInstance(config, this.logger);
+        }
+        catch (error) {
+            throw new Error(`Failed to load MySQL driver: ${error instanceof Error ? error.message : 'Unknown error'}. Make sure @groundbrick/db-mysql is installed.`);
+        }
+    }
+    /**
+     * Get the database type
+     */
+    getDatabaseType() {
+        return this.dbType;
+    }
+    /**
+     * Initialize the database connection
+     */
+    async initialize() {
+        await this.client.initialize();
+        this.logger.info('Database adapter initialized');
+    }
+    /**
+     * Close the database connection
+     */
+    async close() {
+        await this.client.close();
+        this.logger.info('Database adapter closed');
+    }
+    /**
+     * Get the underlying database client
+     * This allows access to all database-specific methods
+     */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Execute a database-agnostic query
+     */
+    async query(sql, params) {
+        const result = await this.client.query(sql, params);
+        return {
+            rows: result.rows,
+            rowCount: result.rowCount ?? 0
+        };
+    }
+    /**
+     * Execute a transaction with unified interface
+     */
+    async transaction(callback) {
+        return await this.client.transaction(async (trx) => {
+            // Create a wrapper that looks like a DatabaseClient but uses the transaction
+            const transactionClient = {
+                ...this.client,
+                query: trx.query.bind(trx),
+                transaction: () => Promise.reject(new Error('Nested transactions not supported'))
+            };
+            return await callback(transactionClient);
+        });
+    }
+    /**
+     * Health check
+     */
+    async healthCheck() {
+        try {
+            await this.client.query('SELECT 1');
+            return { status: 'ok', timestamp: new Date() };
+        }
+        catch (error) {
+            return {
+                status: 'error',
+                timestamp: new Date(),
+                reason: error instanceof Error ? error.message : 'Unknown error'
+            };
+        }
+    }
+    /**
+     * Check if adapter is ready
+     */
+    isReady() {
+        return !!this.client;
+    }
+}
+//# sourceMappingURL=DatabaseAdapter.js.map

package/dist/adapters/DatabaseAdapter.js.map

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

package/dist/base/BaseTransaction.d.ts

@@ -0,0 +1,65 @@
+import { DatabaseTransaction } from '../interfaces/DatabaseTransaction.js';
+import { QueryResult } from '../interfaces/QueryResult.js';
+import { Logger } from '@groundbrick/logger';
+/**
+ * Base transaction class that provides common transaction logic with database type awareness
+ * This ensures consistent behavior across different database implementations
+ */
+export declare abstract class BaseTransaction implements DatabaseTransaction {
+    protected readonly logger: Logger;
+    protected readonly dbType: 'postgresql' | 'mysql';
+    protected completed: boolean;
+    constructor(logger: Logger, dbType: 'postgresql' | 'mysql');
+    abstract query<T = any>(text: string, params?: any[]): Promise<QueryResult<T>>;
+    /**
+     * NEW: Get the database type for this transaction
+     */
+    getDatabaseType(): 'postgresql' | 'mysql';
+    /**
+     * NEW: Check if this database supports RETURNING clause
+     */
+    supportsReturning(): boolean;
+    /**
+     * NEW: Adapt SQL query for database-specific syntax
+     */
+    adaptSql(sql: string): string;
+    /**
+     * NEW: Create database-specific INSERT SQL
+     */
+    createInsertSql(tableName: string, columns: string[]): string;
+    /**
+     * NEW: Create database-specific UPDATE SQL
+     */
+    createUpdateSql(tableName: string, columns: string[]): string;
+    /**
+     * Template method for committing transaction
+     * Subclasses implement doCommit() for database-specific logic
+     */
+    commit(): Promise<void>;
+    /**
+     * Template method for rolling back transaction
+     * Subclasses implement doRollback() for database-specific logic
+     */
+    rollback(): Promise<void>;
+    /**
+     * Check if transaction is completed
+     */
+    isCompleted(): boolean;
+    /**
+     * Database-specific commit implementation
+     */
+    protected abstract doCommit(): Promise<void>;
+    /**
+     * Database-specific rollback implementation
+     */
+    protected abstract doRollback(): Promise<void>;
+    /**
+     * Database-specific cleanup (connection release, etc.)
+     */
+    protected abstract doCleanup(): Promise<void>;
+    /**
+     * Ensure cleanup happens in both success and error cases
+     */
+    protected ensureCleanup(): Promise<void>;
+}
+//# sourceMappingURL=BaseTransaction.d.ts.map

package/dist/base/BaseTransaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseTransaction.d.ts","sourceRoot":"","sources":["../../src/base/BaseTransaction.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAE3D,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C;;;GAGG;AACH,8BAAsB,eAAgB,YAAW,mBAAmB;IAI5D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACjC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;IAJrD,SAAS,CAAC,SAAS,UAAS;gBAGL,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GAAG,OAAO;IAGrD,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAE9E;;OAEG;IACH,eAAe,IAAI,YAAY,GAAG,OAAO;IAIzC;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAU7B;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM;IAc7D;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM;IAgB7D;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB7B;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB/B;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAE5C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAE9C;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAE7C;;OAEG;cACa,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CAWjD"}

package/dist/base/BaseTransaction.js

@@ -0,0 +1,134 @@
+import { TransactionError } from '../error-handling/TransactionError.js';
+/**
+ * Base transaction class that provides common transaction logic with database type awareness
+ * This ensures consistent behavior across different database implementations
+ */
+export class BaseTransaction {
+    logger;
+    dbType;
+    completed = false;
+    constructor(logger, dbType // NEW: Database type awareness
+    ) {
+        this.logger = logger;
+        this.dbType = dbType;
+    }
+    /**
+     * NEW: Get the database type for this transaction
+     */
+    getDatabaseType() {
+        return this.dbType;
+    }
+    /**
+     * NEW: Check if this database supports RETURNING clause
+     */
+    supportsReturning() {
+        return this.dbType === 'postgresql';
+    }
+    /**
+     * NEW: Adapt SQL query for database-specific syntax
+     */
+    adaptSql(sql) {
+        if (this.dbType === 'postgresql') {
+            // Convert ? placeholders to $1, $2, etc.
+            let index = 1;
+            return sql.replace(/\?/g, () => `$${index++}`);
+        }
+        // MySQL uses ? placeholders as-is
+        return sql;
+    }
+    /**
+     * NEW: Create database-specific INSERT SQL
+     */
+    createInsertSql(tableName, columns) {
+        const placeholders = columns.map((_, index) => {
+            return this.dbType === 'postgresql' ? `$${index + 1}` : '?';
+        }).join(', ');
+        let sql = `INSERT INTO ${tableName} (${columns.join(', ')}) VALUES (${placeholders})`;
+        if (this.supportsReturning()) {
+            sql += ' RETURNING *';
+        }
+        return sql;
+    }
+    /**
+     * NEW: Create database-specific UPDATE SQL
+     */
+    createUpdateSql(tableName, columns) {
+        const setParts = columns.map((col, index) => {
+            const placeholder = this.dbType === 'postgresql' ? `$${index + 1}` : '?';
+            return `${col} = ${placeholder}`;
+        });
+        const idPlaceholder = this.dbType === 'postgresql' ? `$${columns.length + 1}` : '?';
+        let sql = `UPDATE ${tableName} SET ${setParts.join(', ')} WHERE id = ${idPlaceholder}`;
+        if (this.supportsReturning()) {
+            sql += ' RETURNING *';
+        }
+        return sql;
+    }
+    /**
+     * Template method for committing transaction
+     * Subclasses implement doCommit() for database-specific logic
+     */
+    async commit() {
+        if (this.completed) {
+            throw new TransactionError('Transaction has already been completed');
+        }
+        try {
+            this.logger.debug('Committing transaction', { dbType: this.dbType });
+            await this.doCommit();
+            this.completed = true;
+            this.logger.debug('Transaction committed successfully', { dbType: this.dbType });
+        }
+        catch (error) {
+            this.logger.error('Failed to commit transaction', error instanceof Error ? error : new Error(String(error)), {
+                error,
+                dbType: this.dbType
+            });
+            throw new TransactionError(`Failed to commit transaction: ${error.message}`, error);
+        }
+    }
+    /**
+     * Template method for rolling back transaction
+     * Subclasses implement doRollback() for database-specific logic
+     */
+    async rollback() {
+        if (this.completed) {
+            this.logger.debug('Transaction already completed, nothing to rollback', { dbType: this.dbType });
+            return;
+        }
+        try {
+            this.logger.debug('Rolling back transaction', { dbType: this.dbType });
+            await this.doRollback();
+            this.completed = true;
+            this.logger.debug('Transaction rolled back successfully', { dbType: this.dbType });
+        }
+        catch (error) {
+            this.logger.error('Failed to rollback transaction', error instanceof Error ? error : new Error(String(error)), {
+                error,
+                dbType: this.dbType
+            });
+            throw new TransactionError(`Failed to rollback transaction: ${error.message}`, error);
+        }
+    }
+    /**
+     * Check if transaction is completed
+     */
+    isCompleted() {
+        return this.completed;
+    }
+    /**
+     * Ensure cleanup happens in both success and error cases
+     */
+    async ensureCleanup() {
+        try {
+            await this.doCleanup();
+        }
+        catch (error) {
+            // Don't throw here as we don't want cleanup errors to mask the original error
+            this.logger.error('Failed to cleanup transaction resources', error instanceof Error ? error : new Error(String(error)), {
+                error,
+                dbType: this.dbType
+            });
+        }
+    }
+}
+//# sourceMappingURL=BaseTransaction.js.map

package/dist/base/BaseTransaction.js.map

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