Nuget Package Creation - v1.2.0

.github/workflows/publish-nuget-Package.yml

@@ -1,7 +1,7 @@
 name: Publish Nuget Package
 
 env:
-    NUGET_PACKAGE_NAME_VERSION: "QueryDB.1.1.0.nupkg"
+    NUGET_PACKAGE_NAME_VERSION: "QueryDB.1.2.0.nupkg"
 
 on:
   workflow_dispatch:

CHANGELOG.md

@@ -3,13 +3,23 @@ All notable changes to this project documented here.
 
 ## [Released]
 
+## [1.2.0](https://www.nuget.org/packages/QueryDB/1.2.0) - 2025-03-04
+### Added
+- Asynchronous operations
+    - `FetchDataAsync()`
+    - `ExecuteScalarAsync()`
+    - `ExecuteCommandAsync()`
+    - `ExecuteTransactionAsync()`
+### Changed
+-  Execute transaction to return transaction outcome and exception details in case of failure instead of logging into console.
+
+## [1.1.0](https://www.nuget.org/packages/QueryDB/1.1.0) - 2025-02-20
+### Added
+- Execute scalar queries (returning a single value).
+
 ## [1.0.0](https://www.nuget.org/packages/QueryDB/1.0.0) - 2025-02-18
 ### Added
 - QueryDB framework for simplified querying and executing transactions across multiple database systems.
     - Retrieve data from database.
     - Execute database commands.
-    - Execute transactions while maintaining atomicity.
-
-## [1.1.0](https://www.nuget.org/packages/QueryDB/1.1.0) - 2025-02-20
-### Added
-- Execute scalar queries (returning a single value).
+    - Execute transactions while maintaining atomicity.

QueryDB.Core.Tests/QueryDBTests.cs

@@ -1,5 +1,6 @@
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 using System.Collections.Generic;
+using System.Threading.Tasks;
 
 namespace QueryDB.Core.Tests
 {
@@ -23,17 +24,14 @@ public void ExecuteCommand_UnknownDB_ReturnsNegativeOne()
 
         [TestMethod]
         [TestCategory(DB_TESTS), TestCategory(UNKNOW_DB_TESTS)]
-        public void ExecuteTransaction_UnknownDB_ReturnsFalse()
+        public async Task ExecuteCommandAsync_UnknownDB_ReturnsNegativeOne()
         {
-            var sqlStatements = new List<string>
-            {
-                "DELETE FROM users"
-            };
+            string sqlStatement = "DELETE FROM users";
 
             var dbContext = new DBContext((DB)999, "some_invalid_connection_string");
-            var result = dbContext.ExecuteTransaction(sqlStatements);
+            var result = await dbContext.ExecuteCommandAsync(sqlStatement);
 
-            Assert.IsFalse(result);
+            Assert.AreEqual(-1, result);
         }
 
         #endregion

QueryDB/IDBContext.cs

@@ -1,5 +1,6 @@
 using QueryDB.Resources;
 using System.Collections.Generic;
+using System.Threading.Tasks;
 
 namespace QueryDB
 {
@@ -9,52 +10,120 @@ namespace QueryDB
     interface IDBContext
     {
         /// <summary>
-        /// Retrieves records for 'Select' queries from the database.
+        /// Executes and retrieves records for 'Select' queries from the database.
         /// </summary>
         /// <param name="selectSql">'Select' query.</param>
-        /// <param name="upperCaseKeys">Boolean parameter to return dictionary keys in uppercase. Default - 'false'.</param>
-        /// <returns>List of data Dictionary with column names as keys holding values into a list for multiple rows of data.</returns>
+        /// <param name="upperCaseKeys">Boolean parameter to return dictionary keys in uppercase. Default - <c>false</c>.</param>
+        /// <returns>List of <see cref="DataDictionary"/> with column names as keys holding values into a list for multiple rows of data.</returns>
         List<DataDictionary> FetchData(string selectSql, bool upperCaseKeys = false);
 
         /// <summary>
-        ///  Retrieves records for 'Select' queries from the database.
+        /// Executes and retrieves records for 'Select' queries from the database.
         /// </summary>
         /// <typeparam name="T">Object entity to return data mapped into.</typeparam>
         /// <param name="selectSql">'Select' query.</param>
-        /// <param name="strict">Enables fetch data only for object <T> properties existing in database query result. Default - 'false'.</param>
-        /// <returns>List of data rows mapped into object entity into a list for multiple rows of data.</returns>
+        /// <param name="strict">Enables fetch data only for object type <typeparamref name="T"/> properties existing in database query result. Default - <c>false</c>.</param>
+        /// <returns>List of data rows mapped into object of type <typeparamref name="T"/>.</returns>
         List<T> FetchData<T>(string selectSql, bool strict = false) where T : new();
 
         /// <summary>
-        /// Executes a SQL query and returns the result as a string.
+        /// Asynchronously executes and retrieves records for 'Select' queries from the database.
         /// </summary>
-        /// <param name="sqlStatement">The SQL query to execute.</param>
-        /// <returns>A string representing the result of the query. If the result is DBNull, an empty string is returned.</returns>
+        /// <param name="selectSql">'Select' query.</param>
+        /// <param name="upperCaseKeys">Boolean parameter to return dictionary keys in uppercase. Default - <c>false</c>.</param>
+        /// <returns>List of <see cref="DataDictionary"/> with column names as keys holding values into a list for multiple rows of data.</returns>
+        Task<List<DataDictionary>> FetchDataAsync(string selectSql, bool upperCaseKeys = false);
+
+        /// <summary>
+        /// Asynchronously executes and retrieves records for 'Select' queries from the database.
+        /// </summary>
+        /// <typeparam name="T">Object entity to return data mapped into.</typeparam>
+        /// <param name="selectSql">'Select' query.</param>
+        /// <param name="strict">Enables fetch data only for object type <typeparamref name="T"/> properties existing in database query result. Default - <c>false</c>.</param>
+        Task<List<T>> FetchDataAsync<T>(string selectSql, bool strict = false) where T : new();
+
+        /// <summary>
+        /// Executes the provided SQL statement and returns the first column of the first row in the result set.
+        /// If the result is DBNull, an empty string is returned.
+        /// </summary>
+        /// <param name="sqlStatement">The SQL statement to execute. It should be a query that returns a single value.</param>
+        /// <returns>
+        /// A <see cref="string"/> representing the value of the first column of the first row in the result set,
+        /// or an empty string if the result is DBNull.
+        /// </returns>
         string ExecuteScalar(string sqlStatement);
 
         /// <summary>
-        /// Executes a SQL query and returns the result as the specified type.
+        /// Executes the provided SQL statement and returns the first column of the first row in the result set,
+        /// converted to the specified type <typeparamref name="T"/>. If the result is DBNull, the default value of <typeparamref name="T"/> is returned.
         /// </summary>
         /// <typeparam name="T">The type to which the result should be converted.</typeparam>
-        /// <param name="sqlStatement">The SQL query to execute.</param>
-        /// <returns>The result of the query, converted to the specified type. If the result is DBNull, the default value for the type is returned.</returns>
+        /// <param name="sqlStatement">The SQL statement to execute. It should be a query that returns a single value.</param>
+        /// <returns>
+        /// The value of the first column of the first row in the result set, converted to type <typeparamref name="T"/>,
+        /// or the default value of <typeparamref name="T"/> if the result is DBNull.
+        /// </returns>
         T ExecuteScalar<T>(string sqlStatement);
 
         /// <summary>
-        /// Executes SQL commands.
+        /// Asynchronously executes the provided SQL statement and returns the first column of the first row in the result set.
+        /// If the result is DBNull, an empty string is returned.
         /// </summary>
-        /// <param name="sqlStatement">SQL statement as command.</param>
-        /// <returns>The number of rows affected.</returns>
+        /// <param name="sqlStatement">The SQL statement to execute. It should be a query that returns a single value.</param>
+        /// <returns>
+        /// A <see cref="string"/> representing the value of the first column of the first row in the result set,
+        /// or an empty string if the result is DBNull.
+        /// </returns>
+        Task<string> ExecuteScalarAsync(string sqlStatement);
+
+        /// <summary>
+        /// Asynchronously executes the provided SQL statement and returns the first column of the first row in the result set,
+        /// converted to the specified type <typeparamref name="T"/>. If the result is DBNull, the default value of <typeparamref name="T"/> is returned.
+        /// </summary>
+        /// <typeparam name="T">The type to which the result should be converted.</typeparam>
+        /// <param name="sqlStatement">The SQL statement to execute. It should be a query that returns a single value.</param>
+        /// <returns>
+        /// The value of the first column of the first row in the result set, converted to type <typeparamref name="T"/>,
+        /// or the default value of <typeparamref name="T"/> if the result is DBNull.
+        /// </returns>
+        Task<T> ExecuteScalarAsync<T>(string sqlStatement);
+
+        /// <summary>
+        /// Executes a SQL statement that does not return a result set.
+        /// </summary>
+        /// <param name="sqlStatement">SQL statement to execute.</param>
+        /// <returns>The number of rows affected by the execution of the SQL statement.</returns>
         int ExecuteCommand(string sqlStatement);
 
+        /// <summary>
+        /// Asynchronously executes a SQL statement that does not return a result set.
+        /// </summary>
+        /// <param name="sqlStatement">SQL statement to execute.</param>
+        /// <returns>The number of rows affected by the execution of the SQL statement.</returns>
+        Task<int> ExecuteCommandAsync(string sqlStatement);
+
         /// <summary>
         /// Executes multiple SQL statements within a transaction, ensuring that all statements are executed together.
         /// </summary>
         /// <param name="sqlStatements">A list of SQL statements to execute.</param>
         /// <returns>
-        /// Returns <c>true</c> if all statements are executed successfully and the transaction is committed;
-        /// <c>false</c> if any statement fails and the transaction is rolled back.
+        /// A <see cref="Result"/> object indicating the outcome of the transaction.
+        /// The <see cref="Result.Success"/> property is <c>true</c> if the transaction is committed successfully; 
+        /// otherwise, <c>false</c> if an error occurs and the transaction is rolled back.
+        /// If an error occurs, the <see cref="Result.Exception"/> property contains the exception details.
+        /// </returns>
+        Result ExecuteTransaction(List<string> sqlStatements);
+
+        /// <summary>
+        /// Asynchronously executes multiple SQL statements within a transaction, ensuring that all statements are executed together.
+        /// </summary>
+        /// <param name="sqlStatements">A list of SQL statements to execute.</param>
+        /// <returns>
+        /// A <see cref="Result"/> object indicating the outcome of the transaction.
+        /// The <see cref="Result.Success"/> property is <c>true</c> if the transaction is committed successfully; 
+        /// otherwise, <c>false</c> if an error occurs and the transaction is rolled back.
+        /// If an error occurs, the <see cref="Result.Exception"/> property contains the exception details.
         /// </returns>
-        bool ExecuteTransaction(List<string> sqlStatements);
+        Task<Result> ExecuteTransactionAsync(List<string> sqlStatements);
     }
 }