forge-sql-orm 2.0.7 → 2.0.8

package/README.md

@@ -23,14 +23,53 @@ import { drizzle } from "drizzle-orm/mysql-core";
 import { forgeDriver } from "forge-sql-orm";
 const db = drizzle(forgeDriver);
 ```
-Best for: Simple CRUD operations without optimistic locking
+Best for: Simple CRUD operations without optimistic locking. Note that you need to manually set `mapSelectFieldsWithAlias` for select fields to prevent field name collisions in Atlassian Forge SQL.
 
 ### 2. Full Forge-SQL-ORM Usage
 ```typescript
 import ForgeSQL from "forge-sql-orm";
 const forgeSQL = new ForgeSQL();
 ```
-Best for: Advanced features like optimistic locking and automatic versioning
+Best for: Advanced features like optimistic locking, automatic versioning, and automatic field name collision prevention in complex queries.
+
+## Field Name Collision Prevention in Complex Queries
+
+When working with complex queries involving multiple tables (joins, inner joins, etc.), Atlassian Forge SQL has a specific behavior where fields with the same name from different tables get collapsed into a single field with a null value. This is not a Drizzle ORM issue but rather a characteristic of Atlassian Forge SQL's behavior.
+
+Forge-SQL-ORM provides two ways to handle this:
+
+### Using Forge-SQL-ORM
+```typescript
+import ForgeSQL from "forge-sql-orm";
+
+const forgeSQL = new ForgeSQL();
+
+// Automatic field name collision prevention
+await forgeSQL
+  .select({user: users, order: orders})
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+```
+
+### Using Direct Drizzle
+```typescript
+import { drizzle } from "drizzle-orm/mysql-core";
+import { forgeDriver, mapSelectFieldsWithAlias } from "forge-sql-orm";
+
+const db = drizzle(forgeDriver);
+
+// Manual field name collision prevention
+await db
+  .select(mapSelectFieldsWithAlias({user: users, order: orders}))
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+```
+
+### Important Notes
+- This is a specific behavior of Atlassian Forge SQL, not Drizzle ORM
+- For complex queries involving multiple tables, it's recommended to always specify select fields and avoid using `select()` without field selection
+- The solution automatically creates unique aliases for each field by prefixing them with the table name
+- This ensures that fields with the same name from different tables remain distinct in the query results
 
 ## Installation
 
@@ -40,7 +79,7 @@ Forge-SQL-ORM is designed to work with @forge/sql and requires some additional s
 
 ```sh
 npm install forge-sql-orm @forge/sql drizzle-orm momment -S
-npm install mysql2 @types/mysql2 drizzle-kit -D
+npm install mysql2 drizzle-kit inquirer@8.0.0  -D
 ```
 
 This will:
@@ -293,13 +332,13 @@ const users = await db.select().from(users);
 // Using forgeSQL.getDrizzleQueryBuilder()
 const user = await forgeSQL
   .getDrizzleQueryBuilder()
-  .select("*").from(Users)
+  .select().from(Users)
   .where(eq(Users.id, 1));
 
 // OR using direct drizzle with custom driver
 const db = drizzle(forgeDriver);
 const user = await db
-  .select("*").from(Users)
+  .select().from(Users)
   .where(eq(Users.id, 1));
 // Returns: { id: 1, name: "John Doe" }
 
@@ -309,7 +348,7 @@ const user = await forgeSQL
   .executeQueryOnlyOne(
     forgeSQL
       .getDrizzleQueryBuilder()
-      .select("*").from(Users)
+      .select().from(Users)
       .where(eq(Users.id, 1))
   );
 // Returns: { id: 1, name: "John Doe" }
@@ -322,67 +361,69 @@ const usersAlias = alias(Users, "u");
 const result = await forgeSQL
   .getDrizzleQueryBuilder()
   .select({
-    userId: rawSql`${usersAlias.id} as \`userId\``,
-    userName: rawSql`${usersAlias.name} as \`userName\``
+    userId: sql<string>`${usersAlias.id} as \`userId\``,
+    userName: sql<string>`${usersAlias.name} as \`userName\``
   }).from(usersAlias);
 
 // OR with direct drizzle
 const db = drizzle(forgeDriver);
 const result = await db
   .select({
-    userId: rawSql`${usersAlias.id} as \`userId\``,
-    userName: rawSql`${usersAlias.name} as \`userName\``
+    userId: sql<string>`${usersAlias.id} as \`userId\``,
+    userName: sql<string>`${usersAlias.name} as \`userName\``
   }).from(usersAlias);
 // Returns: { userId: 1, userName: "John Doe" }
+```
+
+### Complex Queries
+```js
 
-// Using joins
+// Using joins with automatic field name collision prevention
 // With forgeSQL
 const orderWithUser = await forgeSQL
-  .getDrizzleQueryBuilder()
-  .select({
-    orderId: rawSql`${Orders.id} as \`orderId\``,
-    product: Orders.product,
-    userName: rawSql`${Users.name} as \`userName\``
-  }).from(Orders)
-  .innerJoin(Users, eq(Orders.userId, Users.id))
-  .where(eq(Orders.id, 1));
+  .select({user: users, order: orders})
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
 
 // OR with direct drizzle
 const db = drizzle(forgeDriver);
 const orderWithUser = await db
-  .select({
-    orderId: rawSql`${Orders.id} as \`orderId\``,
-    product: Orders.product,
-    userName: rawSql`${Users.name} as \`userName\``
-  }).from(Orders)
-  .innerJoin(Users, eq(Orders.userId, Users.id))
-  .where(eq(Orders.id, 1));
-// Returns: { orderId: 1, product: "Product 1", userName: "John Doe" }
-```
-
-### Complex Queries with Aggregations
+  .select(mapSelectFieldsWithAlias({user: users, order: orders}))
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
+// Returns: { 
+//   user_id: 1, 
+//   user_name: "John Doe",
+//   order_id: 1,
+//   order_product: "Product 1"
+// }
+
+// Using distinct select with automatic field name collision prevention
+const uniqueOrdersWithUsers = await forgeSQL
+  .selectDistinct({user: users, order: orders})
+  .from(orders)
+  .innerJoin(users, eq(orders.userId, users.id));
 
-```js
 // Finding duplicates
 // With forgeSQL
 const duplicates = await forgeSQL
   .getDrizzleQueryBuilder()
   .select({
     name: Users.name,
-    count: rawSql`COUNT(*) as \`count\``
+    count: sql<number>`COUNT(*) as \`count\``
   }).from(Users)
   .groupBy(Users.name)
-  .having(rawSql`COUNT(*) > 1`);
+  .having(sql`COUNT(*) > 1`);
 
 // OR with direct drizzle
 const db = drizzle(forgeDriver);
 const duplicates = await db
   .select({
     name: Users.name,
-    count: rawSql`COUNT(*) as \`count\``
+    count: sql<number>`COUNT(*) as \`count\``
   }).from(Users)
   .groupBy(Users.name)
-  .having(rawSql`COUNT(*) > 1`);
+  .having(sql`COUNT(*) > 1`);
 // Returns: { name: "John Doe", count: 2 }
 
 // Using executeQueryOnlyOne for unique results
@@ -392,8 +433,8 @@ const userStats = await forgeSQL
     forgeSQL
       .getDrizzleQueryBuilder()
       .select({
-        totalUsers: rawSql`COUNT(*) as \`totalUsers\``,
-        uniqueNames: rawSql`COUNT(DISTINCT name) as \`uniqueNames\``
+        totalUsers: sql`COUNT(*) as \`totalUsers\``,
+        uniqueNames: sql`COUNT(DISTINCT name) as \`uniqueNames\``
       }).from(Users)
   );
 // Returns: { totalUsers: 100, uniqueNames: 80 }

package/dist/ForgeSQLORM.js

@@ -2,7 +2,9 @@
 Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
 const drizzleOrm = require("drizzle-orm");
 const moment = require("moment");
-const sql = require("@forge/sql");
+const table = require("drizzle-orm/table");
+const sql = require("drizzle-orm/sql/sql");
+const sql$1 = require("@forge/sql");
 const mysql2 = require("drizzle-orm/mysql2");
 const mysqlCore = require("drizzle-orm/mysql-core");
 const moment$1 = require("moment/moment.js");
@@ -17,8 +19,8 @@ function extractAlias(query) {
   const match = query.match(/\bas\s+(['"`]?)([\w*]+)\1$/i);
   return match ? match[2] : query;
 }
-function getPrimaryKeys(table) {
-  const { columns, primaryKeys } = getTableMetadata(table);
+function getPrimaryKeys(table2) {
+  const { columns, primaryKeys } = getTableMetadata(table2);
   const columnPrimaryKeys = Object.entries(columns).filter(([, column]) => column.primary);
   if (columnPrimaryKeys.length > 0) {
     return columnPrimaryKeys;
@@ -36,10 +38,10 @@ function getPrimaryKeys(table) {
   }
   return [];
 }
-function processForeignKeys(table, foreignKeysSymbol, extraSymbol) {
+function processForeignKeys(table2, foreignKeysSymbol, extraSymbol) {
   const foreignKeys = [];
   if (foreignKeysSymbol) {
-    const fkArray = table[foreignKeysSymbol];
+    const fkArray = table2[foreignKeysSymbol];
     if (fkArray) {
       fkArray.forEach((fk) => {
         if (fk.reference) {
@@ -50,9 +52,9 @@ function processForeignKeys(table, foreignKeysSymbol, extraSymbol) {
     }
   }
   if (extraSymbol) {
-    const extraConfigBuilder = table[extraSymbol];
+    const extraConfigBuilder = table2[extraSymbol];
     if (extraConfigBuilder && typeof extraConfigBuilder === "function") {
-      const configBuilderData = extraConfigBuilder(table);
+      const configBuilderData = extraConfigBuilder(table2);
       if (configBuilderData) {
         const configBuilders = Array.isArray(configBuilderData) ? configBuilderData : Object.values(configBuilderData).map(
           (item) => item.value || item
@@ -69,8 +71,8 @@ function processForeignKeys(table, foreignKeysSymbol, extraSymbol) {
   }
   return foreignKeys;
 }
-function getTableMetadata(table) {
-  const symbols = Object.getOwnPropertySymbols(table);
+function getTableMetadata(table2) {
+  const symbols = Object.getOwnPropertySymbols(table2);
   const nameSymbol = symbols.find((s) => s.toString().includes("Name"));
   const columnsSymbol = symbols.find((s) => s.toString().includes("Columns"));
   const foreignKeysSymbol = symbols.find((s) => s.toString().includes("ForeignKeys)"));
@@ -83,11 +85,11 @@ function getTableMetadata(table) {
     uniqueConstraints: [],
     extras: []
   };
-  builders.foreignKeys = processForeignKeys(table, foreignKeysSymbol, extraSymbol);
+  builders.foreignKeys = processForeignKeys(table2, foreignKeysSymbol, extraSymbol);
   if (extraSymbol) {
-    const extraConfigBuilder = table[extraSymbol];
+    const extraConfigBuilder = table2[extraSymbol];
     if (extraConfigBuilder && typeof extraConfigBuilder === "function") {
-      const configBuilderData = extraConfigBuilder(table);
+      const configBuilderData = extraConfigBuilder(table2);
       if (configBuilderData) {
         const configBuilders = Array.isArray(configBuilderData) ? configBuilderData : Object.values(configBuilderData).map(
           (item) => item.value || item
@@ -113,15 +115,15 @@ function getTableMetadata(table) {
     }
   }
   return {
-    tableName: nameSymbol ? table[nameSymbol] : "",
-    columns: columnsSymbol ? table[columnsSymbol] : {},
+    tableName: nameSymbol ? table2[nameSymbol] : "",
+    columns: columnsSymbol ? table2[columnsSymbol] : {},
     ...builders
   };
 }
 function generateDropTableStatements(tables) {
   const dropStatements = [];
-  tables.forEach((table) => {
-    const tableMetadata = getTableMetadata(table);
+  tables.forEach((table2) => {
+    const tableMetadata = getTableMetadata(table2);
     if (tableMetadata.tableName) {
       dropStatements.push(`DROP TABLE IF EXISTS \`${tableMetadata.tableName}\`;`);
     }
@@ -129,6 +131,47 @@ function generateDropTableStatements(tables) {
   dropStatements.push(`DELETE FROM __migrations;`);
   return dropStatements;
 }
+function mapSelectTableToAlias(table2) {
+  const { columns, tableName } = getTableMetadata(table2);
+  const selectionsTableFields = {};
+  Object.keys(columns).forEach((name) => {
+    const column = columns[name];
+    const fieldAlias = drizzleOrm.sql.raw(`${tableName}_${column.name}`);
+    selectionsTableFields[name] = drizzleOrm.sql`${column} as \`${fieldAlias}\``;
+  });
+  return selectionsTableFields;
+}
+function isDrizzleColumn(column) {
+  return column && typeof column === "object" && "table" in column;
+}
+function mapSelectAllFieldsToAlias(selections, name, fields) {
+  if (drizzleOrm.isTable(fields)) {
+    selections[name] = mapSelectTableToAlias(fields);
+  } else if (isDrizzleColumn(fields)) {
+    const column = fields;
+    let aliasName = drizzleOrm.sql.raw(`${table.getTableName(column.table)}_${column.name}`);
+    selections[name] = drizzleOrm.sql`${column} as \`${aliasName}\``;
+  } else if (sql.isSQLWrapper(fields)) {
+    selections[name] = fields;
+  } else {
+    const innerSelections = {};
+    Object.entries(fields).forEach(([iname, ifields]) => {
+      mapSelectAllFieldsToAlias(innerSelections, iname, ifields);
+    });
+    selections[name] = innerSelections;
+  }
+  return selections;
+}
+function mapSelectFieldsWithAlias(fields) {
+  if (!fields) {
+    throw new Error("fields is empty");
+  }
+  const selections = {};
+  Object.entries(fields).forEach(([name, fields2]) => {
+    mapSelectAllFieldsToAlias(selections, name, fields2);
+  });
+  return selections;
+}
 class ForgeSQLCrudOperations {
   forgeOperations;
   options;
@@ -450,13 +493,12 @@ class ForgeSQLSelectOperations {
    */
   async executeRawSQL(query, params) {
     if (this.options.logRawSqlQuery) {
-      console.debug("Executing raw SQL: " + query);
+      console.debug(
+        `Executing with SQL ${query}` + params ? `, with params: ${JSON.stringify(params)}` : ""
+      );
     }
-    const sqlStatement = sql.sql.prepare(query);
+    const sqlStatement = sql$1.sql.prepare(query);
     if (params) {
-      if (this.options.logRawSqlQuery && this.options.logRawSqlQueryParams) {
-        console.debug("Executing with SQL Params: " + JSON.stringify(params));
-      }
       sqlStatement.bindParams(...params);
     }
     const result = await sqlStatement.execute();
@@ -469,10 +511,15 @@ class ForgeSQLSelectOperations {
    * @returns {Promise<UpdateQueryResponse>} The update response containing affected rows
    */
   async executeRawUpdateSQL(query, params) {
-    const sqlStatement = sql.sql.prepare(query);
+    const sqlStatement = sql$1.sql.prepare(query);
     if (params) {
       sqlStatement.bindParams(...params);
     }
+    if (this.options.logRawSqlQuery) {
+      console.debug(
+        `Executing Update with SQL ${query}` + params ? `, with params: ${JSON.stringify(params)}` : ""
+      );
+    }
     const updateQueryResponseResults = await sqlStatement.execute();
     return updateQueryResponseResults.rows;
   }
@@ -480,20 +527,16 @@ class ForgeSQLSelectOperations {
 const forgeDriver = {
   query: async (query, params) => {
     try {
-      const sqlStatement = await sql.sql.prepare(query.sql);
+      const sqlStatement = await sql$1.sql.prepare(query.sql);
       if (params) {
         await sqlStatement.bindParams(...params);
       }
       const result = await sqlStatement.execute();
       let rows;
       if (Array.isArray(result.rows)) {
-        rows = [
-          result.rows.map((r) => Object.values(r))
-        ];
+        rows = [result.rows.map((r) => Object.values(r))];
       } else {
-        rows = [
-          result.rows
-        ];
+        rows = [result.rows];
       }
       return rows;
     } catch (error) {
@@ -520,7 +563,7 @@ class ForgeSQLORMImpl {
       if (newOptions.logRawSqlQuery) {
         console.debug("Initializing ForgeSQLORM...");
       }
-      this.drizzle = mysql2.drizzle(forgeDriver);
+      this.drizzle = mysql2.drizzle(forgeDriver, { logger: newOptions.logRawSqlQuery });
       this.crudOperations = new ForgeSQLCrudOperations(this, newOptions);
       this.fetchOperations = new ForgeSQLSelectOperations(newOptions);
     } catch (error) {
@@ -565,12 +608,94 @@ class ForgeSQLORMImpl {
   getDrizzleQueryBuilder() {
     return this.drizzle;
   }
+  /**
+   * Creates a select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   * 
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .select({user: users, order: orders})
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
+  select(fields) {
+    if (!fields) {
+      throw new Error("fields is empty");
+    }
+    return this.drizzle.select(mapSelectFieldsWithAlias(fields));
+  }
+  /**
+   * Creates a distinct select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   * 
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A distinct select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .selectDistinct({user: users, order: orders})
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
+  selectDistinct(fields) {
+    if (!fields) {
+      throw new Error("fields is empty");
+    }
+    return this.drizzle.selectDistinct(mapSelectFieldsWithAlias(fields));
+  }
 }
 class ForgeSQLORM {
   ormInstance;
   constructor(options) {
     this.ormInstance = ForgeSQLORMImpl.getInstance(options);
   }
+  /**
+   * Creates a select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   * 
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .select({user: users, order: orders})
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
+  select(fields) {
+    return this.ormInstance.getDrizzleQueryBuilder().select(mapSelectFieldsWithAlias(fields));
+  }
+  /**
+   * Creates a distinct select query with unique field aliases to prevent field name collisions in joins.
+   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
+   * 
+   * @template TSelection - The type of the selected fields
+   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
+   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A distinct select query builder with unique field aliases
+   * @throws {Error} If fields parameter is empty
+   * @example
+   * ```typescript
+   * await forgeSQL
+   *   .selectDistinct({user: users, order: orders})
+   *   .from(orders)
+   *   .innerJoin(users, eq(orders.userId, users.id));
+   * ```
+   */
+  selectDistinct(fields) {
+    return this.ormInstance.getDrizzleQueryBuilder().selectDistinct(mapSelectFieldsWithAlias(fields));
+  }
   /**
    * Proxies the `crud` method from `ForgeSQLORMImpl`.
    * @returns CRUD operations.
@@ -650,13 +775,12 @@ async function dropSchemaMigrations(tables) {
     const dropStatements = generateDropTableStatements(tables);
     for (const statement of dropStatements) {
       console.warn(statement);
-      await sql.sql.executeDDL(statement);
+      await sql$1.sql.executeDDL(statement);
     }
-    const droppedTables = tables.map((table) => {
-      const metadata = getTableMetadata(table);
-      return metadata.tableName;
-    }).filter(Boolean);
-    return getHttpResponse(200, "⚠️ All data in these tables has been permanently deleted. This operation cannot be undone.");
+    return getHttpResponse(
+      200,
+      "⚠️ All data in these tables has been permanently deleted. This operation cannot be undone."
+    );
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
     return getHttpResponse(500, errorMessage);
@@ -664,12 +788,12 @@ async function dropSchemaMigrations(tables) {
 }
 const applySchemaMigrations = async (migration) => {
   console.log("Provisioning the database");
-  await sql.sql._provision();
+  await sql$1.sql._provision();
   console.info("Running schema migrations");
-  const migrations = await migration(sql.migrationRunner);
+  const migrations = await migration(sql$1.migrationRunner);
   const successfulMigrations = await migrations.run();
   console.info("Migrations applied:", successfulMigrations);
-  const migrationHistory = (await sql.migrationRunner.list()).map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toUTCString()}`).join("\n");
+  const migrationHistory = (await sql$1.migrationRunner.list()).map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toUTCString()}`).join("\n");
   console.info("Migrations history:\nid, name, migrated_at\n", migrationHistory);
   return {
     headers: { "Content-Type": ["application/json"] },
@@ -707,5 +831,8 @@ exports.generateDropTableStatements = generateDropTableStatements;
 exports.getHttpResponse = getHttpResponse;
 exports.getPrimaryKeys = getPrimaryKeys;
 exports.getTableMetadata = getTableMetadata;
+exports.mapSelectAllFieldsToAlias = mapSelectAllFieldsToAlias;
+exports.mapSelectFieldsWithAlias = mapSelectFieldsWithAlias;
+exports.mapSelectTableToAlias = mapSelectTableToAlias;
 exports.parseDateTime = parseDateTime;
 //# sourceMappingURL=ForgeSQLORM.js.map