documentation for raw query updated

Author: siddharthtiwari-03

readme2.md

@@ -161,7 +161,7 @@ const { UnSQL } = require('unsql')
 const pool = require('path/to/your/db/service')
 
 /**
- * @class User
+ * @class
  * @extends UnSQL
  */
 class User extends UnSQL {
@@ -191,7 +191,7 @@ import { UnSQL } from 'unsql'
 import { pool } from 'path/to/your/db/service'
 
 /**
- * @class User
+ * @class
  * @extends UnSQL
  */
 export class User extends UnSQL {
@@ -306,7 +306,7 @@ Each of these properties is explained below:
                 }
             }
         ],
-        join: [{ table: 'order_history', using: ['orderId'] }] // ref. of join object
+        join: [{ table: 'order_items', using: ['orderId'] }] // ref. of join object
     })
     ```
     **Please note:** 
@@ -458,17 +458,55 @@ Each of these properties is explained below:
 
 ### 3.4 Raw Query Method
 
-`rawQuery` method is the most powerful method among all, unlike other methods that are limited to the base mapping, this method is not tied to any particular table, but utilizes the connection pool to execute queries on that database itself. It is capable of executing any and all types of queries including DDL, DML etc. It supports normal queries as well as placeholders: 
-   - In `mysql`: 
-     - Positional placeholders: `??`, `?`, 
-     - Named placeholders: `:namedVariable`, 
-     - user defined variables: `@userVariable`, 
-   - In `postgresql`: 
-     - Positional placeholder: `$1`, `$2`, `$3`...
-   - In `sqlite`:
-     - Positional placeholder: `?`,
-     - Named placeholders: `:namedVariable` or `$namedVariable` or `@namedVariable`,
-     - Indexed placeholder: `$1`, `$2`, `$3`... or `?1`, `?2`, `?3`...
+`rawQuery` method is the most powerful method among all, unlike other methods that are limited to the base mapping, this method is not tied to any particular table, but utilizes the connection pool to execute queries on that database itself. It is capable of executing any and all types of queries including **DDL, DML etc** (In `sqlite`, set `methodType: 'exec'`). 
+
+It supports various types of methods (as mentioned below) for `mysql` and `sqlite`, each method has specific capabilities:
+
+| Method Type | Dialect  | Description                                                                           |
+| ----------- | -------- | ------------------------------------------------------------------------------------- |
+| `execute`   | `mysql`  | supports **Session Manager**, and all type of queries (DML, DDL etc.)                 |
+| `query`     | `mysql`  | supports multiple sql statements in single query string, and all type of queries      |
+| `all`       | `sqlite` | supports **Session Manager and SELECT query** returns *record(s) as array*            |
+| `run`       | `sqlite` | supports **Session Manager, INSERT and UPDATE query**, *returns insertId and changes* |
+| `exec`      | `sqlite` | supports **CREATE, DROP ALTER and similar query**, returns nothing                    |
+
+It supports normal queries as well as placeholders: 
+ - In `mysql`: 
+   - Positional placeholders: `??`, `?`, 
+   - Named placeholders: `:namedVariable`, 
+   - user defined variables: `@userVariable`, 
+ - In `postgresql`: 
+   - Positional placeholder: `$1`, `$2`, `$3`...
+ - In `sqlite`:
+   - Positional placeholder: `?`,
+   - Named placeholders: `:namedVariable` or `$namedVariable` or `@namedVariable`,
+   - Indexed placeholder: `$1`, `$2`, `$3`... or `?1`, `?2`, `?3`...
+
+```javascript
+// Sample: (dialect: 'mysql')
+const response = await User.rawQuery({ // here user model is used just to utilize 'pool'
+    sql: `CREATE TABLE IF NOT EXISTS users (
+            userId INT(11) PRIMARY KEY AUTO_INCREMENT,
+            firstName VARCHAR(45) DEFAULT NULL,
+            lastName VARCHAR(45) DEFAULT NULL,
+            email VARCHAR(255) UNIQUE DEFAULT NOT NULL,
+            password VARCHAR(255) DEFAULT NOT NULL,
+            createdOn TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            lastUpdatedOn TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+            status TINYINT(1) DEFAULT 1
+        );
+        CREATE TABLE IF NOT EXISTS order_history (
+            orderId INT(11) PRIMARY KEY AUTO_INCREMENT,
+            amount DECIMAL (10,2) DEFAULT 0.00,
+            coupon VARCHAR(45) DEFAULT NULL,
+            discount DECIMAL (10,2) DEFAULT 0.00,
+            createdOn TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            lastUpdatedOn TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+            status TINYINT(1) DEFAULT 0
+        );`,
+    methodType: 'query' // this supports multiple statements in single query string
+})
+```
 
 ### 3.5 Export Method
 
@@ -1118,8 +1156,8 @@ All objects are explained below:
                     value: {
                         orderId: 'orderId',
                         purchaseDate: 'createdOn',
-                        orderAmount: 'totalAmount',
-                        orderStatus: 'orderStatus'
+                        total: 'amount',
+                        status: 'status'
                     },
                     table: 'order_history',
                     where: {
@@ -1530,6 +1568,10 @@ router.post('/orders', async (req,res) => {
 
 UnSQL uses `#` as prefix to identify if string is plain text, or column name if string does not start with `#`.
 
+### 7.2 What will happen if secret/iv/sha is defined inside config, encryption and decrypt/encrypt property?
+
+When configurations like `secret` | `iv` | `sha` are declared in all places, `encryption` at method level will override `encryption` at `config`, similarly `decrypt` / `encrypt` inside special object will override all other.
+
 ### Support
 ![npm](https://img.shields.io/badge/npm-CB3837?style=for-the-badge&logo=npm&logoColor=white) 
 ![Yarn](https://img.shields.io/badge/yarn-%232C8EBB.svg?style=for-the-badge&logo=yarn&logoColor=white)

unsql.js

@@ -29,7 +29,7 @@ class UnSQL {
     static _variableCount = 0
     static isMySQL = false
     static isPostgreSQL = false
-    static SQLite = false
+    static isSQLite = false
 
     /**
      * Find method
@@ -362,13 +362,13 @@ class UnSQL {
      * @param {import("./defs/types").EncryptionConfig} [rawQueryParams.encryption] (optional) enables debug mode
      * @param {import("./defs/types").DebugTypes} [rawQueryParams.debug] (optional) enables debug mode
      * @param {Object} [rawQueryParams.session] (optional) global session reference for transactions and rollback
-     * @param {'run'|'all'|'exec'} [rawQueryParams.methodType=all] (optional) used only with 'sqlite'
+     * @param {'run'|'all'|'exec'|'execute'|'query'} [rawQueryParams.methodType=all] (optional) used only with 'sqlite'
      * @returns {Promise<{success:boolean, error?:object, result?:object}>} Promise resolving with two parameters: boolean 'success' and either 'error' or 'result'
      */
-    static async rawQuery({ sql = '', values = [], debug = false, encryption = undefined, session = undefined, methodType = 'all' }) {
+    static async rawQuery({ sql = '', values = [], debug = false, encryption = undefined, session = undefined, methodType = this?.isSQLite ? 'all' : 'execute' }) {
         switch (this?.config?.dialect) {
             case 'mysql':
-                return await executeMySQL({ sql, values, encryption, debug, session, config: this?.config, debugMessage: `Executed raw query in` })
+                return await executeMySQL({ sql, values, encryption, debug, session, config: this?.config, methodType, debugMessage: `Executed raw query in` })
             case 'postgresql':
                 return await executePostgreSQL({ sql, values, debug, config: this?.config, debugMessage: `Executed raw query in` })
             case 'sqlite':
@@ -498,30 +498,28 @@ class UnSQL {
  * @param {import("./defs/types").DebugTypes} [options.debug] enables debug mode
  * @param {Object} [options.session] global session reference for transactions and rollback
  * @param {Object} [options.config] global configuration object
+ * @param {'all'|'run'|'exec'|'execute'|'query'} [options.methodType=execute] global configuration object
  * @param {string} [options.debugMessage] global configuration object
  * @param {import("./defs/types").EncryptionConfig} [options.encryption] enables encryption
  * @returns {Promise<{success:false, error:*}|{success:true, result:*}>} Promise resolving with two parameters: boolean 'success' and either 'error' or 'results'
  */
-const executeMySQL = async ({ sql, values, debug = false, session = undefined, config, encryption = undefined, debugMessage = '' }) => {
-
+const executeMySQL = async ({ sql, values, debug = false, session = undefined, config, methodType = 'execute', encryption = undefined, debugMessage = '' }) => {
     const conn = await (session?.conn || config?.pool?.getConnection() || config?.connection)
-
-
     try {
         if (!session?.conn) await conn?.beginTransaction()
         if (debug === 'benchmark' || debug === 'benchmark-query' || debug === 'benchmark-error' || debug === true) console.time(`${colors.blue}UnSQL benchmark:${colors.reset} ${colors.cyan}${debugMessage}${colors.reset}`)
         if ((encryption?.mode && encryption?.mode != config?.dbEncryptionMode) || (config?.encryption?.mode && config?.encryption?.mode != config?.dbEncryptionMode)) {
             try {
                 const encPrepared = await conn.format('SET block_encryption_mode = ?', [encryption?.mode || config?.encryption?.mode])
-                const [encResp] = await conn?.execute(encPrepared)
+                const [encResp] = await conn?.[methodType](encPrepared)
                 if (!session?.conn) await conn?.commit()
             } catch (error) {
                 throw { message: `[Error]: ${error?.message} `, cause: `While setting encryption mode to: '${encryption?.mode || config?.encryption?.mode}'` }
             }
         }
         const prepared = conn.format(sql, values)
         handleQueryDebug(debug, sql, values, prepared)
-        const [result] = await conn.execute(prepared)
+        const [result] = await conn[methodType](prepared)
         if (!session?.conn) await conn?.commit()
         if (debug) console.info(colors.green, 'Query executed successfully!\n', colors.reset)
         if (debug === 'benchmark' || debug === 'benchmark-query' || debug === 'benchmark-error' || debug === true) console.timeEnd(`${colors.blue}UnSQL benchmark:${colors.reset} ${colors.cyan}${debugMessage}${colors.reset}\n`)
@@ -533,7 +531,6 @@ const executeMySQL = async ({ sql, values, debug = false, session = undefined, c
     } finally {
         if (config?.pool && !session?.conn) await conn?.release()
     }
-
 }
 
 /**
@@ -545,11 +542,8 @@ const executeMySQL = async ({ sql, values, debug = false, session = undefined, c
  * @author Siddharth Tiwari <[email protected]>
  */
 const executePostgreSQL = async ({ sql, values, debug = false, config, session = undefined, timezone = undefined, encryption = undefined, debugMessage = '' }) => {
-
     const client = await (session?.conn || config?.pool?.connect())
-
     const isBenchmarking = debug === 'benchmark' || debug === 'benchmark-query' || debug === 'benchmark-error' || debug === true
-
     handleQueryDebug(debug, sql, values)
     try {
         if (!session?.conn) await client.query('BEGIN')
@@ -580,7 +574,7 @@ const executePostgreSQL = async ({ sql, values, debug = false, config, session =
  * @param {Array} options.values
  * @param {import("./defs/types").DebugTypes} [options.debug]
  * @param {import("./defs/types").ConfigObject} [options.config]
- * @param {'all'|'run'|'exec'} [options.methodType=all]
+ * @param {'all'|'run'|'exec'|'execute'|'query'} [options.methodType=all]
  * @param {string} [options.debugMessage]
  * @param {*} [options.session]
  * @returns {Promise<{success:boolean, result?:Array, insertId?:number, changes?:number, error?:*}>}