forge-sql-orm 2.0.0 → 2.0.2

package/README.md

@@ -5,6 +5,7 @@
 **Forge-SQL-ORM** is an ORM designed for working with [@forge/sql](https://developer.atlassian.com/platform/forge/storage-reference/sql-tutorial/) in **Atlassian Forge**. It is built on top of [Drizzle ORM](https://orm.drizzle.team) and provides advanced capabilities for working with relational databases inside Forge.
 
 ## Key Features
+- ✅ **Custom Drizzle Driver** for direct integration with @forge/sql
 - ✅ **Supports complex SQL queries** with joins and filtering using Drizzle ORM
 - ✅ **Batch insert support** with duplicate key handling
 - ✅ **Schema migration support**, allowing automatic schema evolution
@@ -14,6 +15,23 @@
 - ✅ **Optimistic Locking** Ensures data consistency by preventing conflicts when multiple users update the same record
 - ✅ **Type Safety** Full TypeScript support with proper type inference
 
+## Usage Approaches
+
+### 1. Direct Drizzle Usage
+```typescript
+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
+
+### 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
+
 ## Installation
 
 Forge-SQL-ORM is designed to work with @forge/sql and requires some additional setup to ensure compatibility within Atlassian Forge.
@@ -22,8 +40,7 @@ Forge-SQL-ORM is designed to work with @forge/sql and requires some additional s
 
 ```sh
 npm install forge-sql-orm -S
-npm install @forge/sql -S
-npm install drizzle-orm mysql2
+npm install @forge/sql drizzle-orm -S
 npm install mysql2 @types/mysql2 -D
 ```
 
@@ -33,6 +50,38 @@ This will:
 - Install Drizzle ORM and its MySQL driver
 - Install TypeScript types for MySQL
 
+## Direct Drizzle Usage with Custom Driver
+
+If you prefer to use Drizzle ORM directly without the additional features of Forge-SQL-ORM (like optimistic locking), you can use the custom driver:
+
+```typescript
+import { drizzle } from "drizzle-orm/mysql-core";
+import { forgeDriver } from "forge-sql-orm";
+
+// Initialize drizzle with the custom driver
+const db = drizzle(forgeDriver);
+
+// Use drizzle directly
+const users = await db.select().from(users);
+```
+
+##  Drizzle Usage with forge-sql-orm
+
+If you prefer to use Drizzle ORM  with the additional features of Forge-SQL-ORM (like optimistic locking), you can use the custom driver:
+
+```typescript
+import ForgeSQL from "forge-sql-orm";
+const forgeSQL = new ForgeSQL();
+forgeSQL.crud().insert(...);
+forgeSQL.crud().updateById(...);
+const db = forgeSQL.getDrizzleQueryBuilder();
+
+// Use drizzle
+const users = await db.select().from(users);
+```
+
+This approach gives you direct access to all Drizzle ORM features while still using the @forge/sql backend.
+
 ## Step-by-Step Migration Workflow
 
 1. **Generate initial schema from an existing database**
@@ -155,6 +204,68 @@ export default (migrationRunner: MigrationRunner): MigrationRunner => {
 
 ---
 
+## Date and Time Types
+
+When working with date and time fields in your models, you should use the custom types provided by Forge-SQL-ORM to ensure proper handling of date/time values. This is necessary because Forge SQL has specific format requirements for date/time values:
+
+| Date type | Required Format | Example |
+|-----------|----------------|---------|
+| DATE | YYYY-MM-DD | 2024-09-19 |
+| TIME | HH:MM:SS[.fraction] | 06:40:34 |
+| TIMESTAMP | YYYY-MM-DD HH:MM:SS[.fraction] | 2024-09-19 06:40:34.999999 |
+
+```typescript
+// ❌ Don't use standard Drizzle date/time types
+export const testEntityTimeStampVersion = mysqlTable('test_entity', {
+  id: int('id').primaryKey().autoincrement(),
+  time_stamp: timestamp('times_tamp').notNull(),
+  date_time: datetime('date_time').notNull(),
+  time: time('time').notNull(),
+  date: date('date').notNull(),
+});
+
+// ✅ Use Forge-SQL-ORM custom types instead
+import { forgeDateTimeString, forgeDateString, forgeTimestampString, forgeTimeString } from 'forge-sql-orm'
+
+export const testEntityTimeStampVersion = mysqlTable('test_entity', {
+  id: int('id').primaryKey().autoincrement(),
+  time_stamp: forgeTimestampString('times_tamp').notNull(),
+  date_time: forgeDateTimeString('date_time').notNull(),
+  time: forgeTimeString('time').notNull(),
+  date: forgeDateString('date').notNull(),
+});
+```
+
+### Why Custom Types?
+
+The custom types in Forge-SQL-ORM handle the conversion between JavaScript Date objects and Forge SQL's required string formats automatically. Without these custom types, you would need to manually format dates like this:
+
+```typescript
+// Without custom types, you'd need to do this manually:
+const date = moment().format("YYYY-MM-DD");
+const time = moment().format("HH:mm:ss.SSS");
+const timestamp = moment().format("YYYY-MM-DDTHH:mm:ss.SSS");
+```
+
+Our custom types provide:
+- Automatic conversion between JavaScript Date objects and Forge SQL's required string formats
+- Consistent date/time handling across your application
+- Type safety for date/time fields
+- Proper handling of timezone conversions
+- Support for all Forge SQL date/time types (datetime, timestamp, date, time)
+
+### Available Custom Types
+
+- `forgeDateTimeString` - For datetime fields (YYYY-MM-DD HH:MM:SS[.fraction])
+- `forgeTimestampString` - For timestamp fields (YYYY-MM-DD HH:MM:SS[.fraction])
+- `forgeDateString` - For date fields (YYYY-MM-DD)
+- `forgeTimeString` - For time fields (HH:MM:SS[.fraction])
+
+Each type ensures that the data is properly formatted according to Forge SQL's requirements while providing a clean, type-safe interface for your application code.
+
+
+
+
 # Connection to ORM
 
 ```js
@@ -162,20 +273,35 @@ import ForgeSQL from "forge-sql-orm";
 
 const forgeSQL = new ForgeSQL();
 ```
+or 
+
+```typescript
+import { drizzle } from "drizzle-orm/mysql-core";
+import { forgeDriver } from "forge-sql-orm";
+
+// Initialize drizzle with the custom driver
+const db = drizzle(forgeDriver);
+
+// Use drizzle directly
+const users = await db.select().from(users);
+```
 
 ## Fetch Data
 
 ### Basic Fetch Operations
 
 ```js
-// Using executeQuery for single result
+// Using forgeSQL.getDrizzleQueryBuilder()
 const user = await forgeSQL
-  .fetch()
-  .executeQuery(
-    forgeSQL.getDrizzleQueryBuilder()
-      .select("*").from(Users)
-      .where(eq(Users.id, 1))
-  );
+  .getDrizzleQueryBuilder()
+  .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)
+  .where(eq(Users.id, 1));
 // Returns: { id: 1, name: "John Doe" }
 
 // Using executeQueryOnlyOne for single result with error handling
@@ -191,34 +317,47 @@ const user = await forgeSQL
 // Throws error if multiple records found
 // Returns undefined if no records found
 
-// Using executeQuery with aliases
+// Using with aliases
+// With forgeSQL
 const usersAlias = alias(Users, "u");
 const result = await forgeSQL
-  .fetch()
-  .executeQuery(
-    forgeSQL
-      .getDrizzleQueryBuilder()
-      .select({
-        userId: rawSql`${usersAlias.id} as \`userId\``,
-        userName: rawSql`${usersAlias.name} as \`userName\``
-      }).from(usersAlias)
-  );
+  .getDrizzleQueryBuilder()
+  .select({
+    userId: rawSql`${usersAlias.id} as \`userId\``,
+    userName: rawSql`${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\``
+  }).from(usersAlias);
 // Returns: { userId: 1, userName: "John Doe" }
 
-// Using executeQuery with joins
+// Using joins
+// With forgeSQL
 const orderWithUser = await forgeSQL
-  .fetch()
-  .executeQuery(
-    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))
-  );
+  .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));
+
+// 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" }
 ```
 
@@ -226,18 +365,25 @@ const orderWithUser = await forgeSQL
 
 ```js
 // Finding duplicates
+// With forgeSQL
 const duplicates = await forgeSQL
-  .fetch()
-  .executeQuery(
-    forgeSQL
-      .getDrizzleQueryBuilder()
-      .select({
-        name: Users.name,
-        count: rawSql`COUNT(*) as \`count\``
-      }).from(Users)
-      .groupBy(Users.name)
-      .having(rawSql`COUNT(*) > 1`)
-  );
+  .getDrizzleQueryBuilder()
+  .select({
+    name: Users.name,
+    count: rawSql`COUNT(*) as \`count\``
+  }).from(Users)
+  .groupBy(Users.name)
+  .having(rawSql`COUNT(*) > 1`);
+
+// OR with direct drizzle
+const db = drizzle(forgeDriver);
+const duplicates = await db
+  .select({
+    name: Users.name,
+    count: rawSql`COUNT(*) as \`count\``
+  }).from(Users)
+  .groupBy(Users.name)
+  .having(rawSql`COUNT(*) > 1`);
 // Returns: { name: "John Doe", count: 2 }
 
 // Using executeQueryOnlyOne for unique results

package/dist/ForgeSQLORM.js

@@ -124,8 +124,8 @@ class ForgeSQLCrudOperations {
     if (this.options?.logRawSqlQuery) {
       console.debug("INSERT SQL:", query.sql);
     }
-    const result = await this.forgeOperations.fetch().executeRawUpdateSQL(query.sql, query.params);
-    return result.insertId;
+    const result = await finalQuery;
+    return result[0].insertId;
   }
   /**
    * Deletes a record by its primary key with optional version check.
@@ -161,8 +161,8 @@ class ForgeSQLCrudOperations {
     if (this.options?.logRawSqlQuery) {
       console.debug("DELETE SQL:", queryBuilder.toSQL().sql);
     }
-    const result = await this.forgeOperations.fetch().executeRawUpdateSQL(queryBuilder.toSQL().sql, queryBuilder.toSQL().params);
-    return result.affectedRows;
+    const result = await queryBuilder;
+    return result[0].affectedRows;
   }
   /**
    * Updates a record by its primary key with optimistic locking support.
@@ -211,13 +211,13 @@ class ForgeSQLCrudOperations {
     if (this.options?.logRawSqlQuery) {
       console.debug("UPDATE SQL:", queryBuilder.toSQL().sql);
     }
-    const result = await this.forgeOperations.fetch().executeRawUpdateSQL(queryBuilder.toSQL().sql, queryBuilder.toSQL().params);
-    if (versionMetadata && result.affectedRows === 0) {
+    const result = await queryBuilder;
+    if (versionMetadata && result[0].affectedRows === 0) {
       throw new Error(
         `Optimistic locking failed: record with primary key ${entity[primaryKeyName]} has been modified`
       );
     }
-    return result.affectedRows;
+    return result[0].affectedRows;
   }
   /**
    * Updates specified fields of records based on provided conditions.
@@ -239,8 +239,8 @@ class ForgeSQLCrudOperations {
     if (this.options?.logRawSqlQuery) {
       console.debug("UPDATE SQL:", queryBuilder.toSQL().sql);
     }
-    const result = await this.forgeOperations.fetch().executeRawUpdateSQL(queryBuilder.toSQL().sql, queryBuilder.toSQL().params);
-    return result.affectedRows;
+    const result = await queryBuilder;
+    return result[0].affectedRows;
   }
   // Helper methods
   /**
@@ -387,105 +387,6 @@ class ForgeSQLSelectOperations {
   constructor(options) {
     this.options = options;
   }
-  /**
-   * Executes a Drizzle query and returns the results.
-   * Maps the raw database results to the appropriate entity types.
-   *
-   * @template T - The type of the query builder
-   * @param {T} query - The Drizzle query to execute
-   * @returns {Promise<Awaited<T>>} The query results mapped to entity types
-   */
-  async executeQuery(query) {
-    const queryType = query;
-    const querySql = queryType.toSQL();
-    const datas = await this.executeRawSQL(querySql.sql, querySql.params);
-    if (!datas.length) return [];
-    return datas.map((r) => {
-      const rawModel = r;
-      const newModel = {};
-      const columns = queryType.config.fields;
-      Object.entries(columns).forEach(([name, column]) => {
-        const { realColumn, aliasName } = this.extractColumnInfo(column);
-        const value = rawModel[aliasName];
-        if (value === null || value === void 0) {
-          newModel[name] = value;
-          return;
-        }
-        newModel[name] = this.parseColumnValue(realColumn, value);
-      });
-      return newModel;
-    });
-  }
-  /**
-   * Extracts column information and alias name from a column definition.
-   * @param {any} column - The column definition from Drizzle
-   * @returns {Object} Object containing the real column and its alias name
-   */
-  extractColumnInfo(column) {
-    if (column instanceof drizzleOrm.SQL) {
-      const realColumnSql = column;
-      const realColumn = realColumnSql.queryChunks.find(
-        (q) => q instanceof drizzleOrm.Column
-      );
-      let stringChunk = this.findAliasChunk(realColumnSql);
-      let withoutAlias = false;
-      if (!realColumn && (!stringChunk || !stringChunk.value || !stringChunk.value?.length)) {
-        stringChunk = realColumnSql.queryChunks.filter((q) => q instanceof drizzleOrm.StringChunk).find((q) => q.value[0]);
-        withoutAlias = true;
-      }
-      const aliasName = this.resolveAliasName(stringChunk, realColumn, withoutAlias);
-      return { realColumn, aliasName };
-    }
-    return { realColumn: column, aliasName: column.name };
-  }
-  /**
-   * Finds the alias chunk in SQL query chunks.
-   * @param {SQL} realColumnSql - The SQL query chunks
-   * @returns {StringChunk | undefined} The string chunk containing the alias or undefined
-   */
-  findAliasChunk(realColumnSql) {
-    return realColumnSql.queryChunks.filter((q) => q instanceof drizzleOrm.StringChunk).find(
-      (q) => q.value.find((f) => f.toLowerCase().includes("as"))
-    );
-  }
-  /**
-   * Resolves the alias name from the string chunk or column.
-   * @param {StringChunk | undefined} stringChunk - The string chunk containing the alias
-   * @param {Column | undefined} realColumn - The real column definition
-   * @param {boolean} withoutAlias - Whether the column has no alias
-   * @returns {string} The resolved alias name
-   */
-  resolveAliasName(stringChunk, realColumn, withoutAlias) {
-    if (stringChunk) {
-      if (withoutAlias) {
-        return stringChunk.value[0];
-      }
-      const asClause = stringChunk.value.find((f) => f.toLowerCase().includes("as"));
-      return asClause ? extractAlias(asClause.trim()) : realColumn?.name || "";
-    }
-    return realColumn?.name || "";
-  }
-  /**
-   * Parses a column value based on its SQL type.
-   * Handles datetime, date, and time types with appropriate formatting.
-   *
-   * @param {Column} column - The column definition
-   * @param {unknown} value - The raw value to parse
-   * @returns {unknown} The parsed value
-   */
-  parseColumnValue(column, value) {
-    if (!column) return value;
-    switch (column.getSQLType()) {
-      case "datetime":
-        return parseDateTime(value, "YYYY-MM-DDTHH:mm:ss.SSS");
-      case "date":
-        return parseDateTime(value, "YYYY-MM-DD");
-      case "time":
-        return parseDateTime(value, "HH:mm:ss.SSS");
-      default:
-        return value;
-    }
-  }
   /**
    * Executes a Drizzle query and returns a single result.
    * Throws an error if more than one record is returned.
@@ -496,7 +397,7 @@ class ForgeSQLSelectOperations {
    * @throws {Error} If more than one record is returned
    */
   async executeQueryOnlyOne(query) {
-    const results = await this.executeQuery(query);
+    const results = await query;
     const datas = results;
     if (!datas.length) {
       return void 0;
@@ -544,6 +445,33 @@ class ForgeSQLSelectOperations {
     return updateQueryResponseResults.rows;
   }
 }
+const forgeDriver = {
+  query: async (query, params) => {
+    try {
+      const sqlStatement = await sql.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))
+        ];
+      } else {
+        rows = [
+          result.rows
+        ];
+      }
+      return rows;
+    } catch (error) {
+      console.error("SQL Error:", JSON.stringify(error));
+      throw error;
+    }
+  },
+  transaction: async (transactionFn) => {
+  }
+};
 class ForgeSQLORMImpl {
   static instance = null;
   drizzle;
@@ -562,7 +490,7 @@ class ForgeSQLORMImpl {
       if (newOptions.logRawSqlQuery) {
         console.debug("Initializing ForgeSQLORM...");
       }
-      this.drizzle = mysql2.drizzle("");
+      this.drizzle = mysql2.drizzle(forgeDriver);
       this.crudOperations = new ForgeSQLCrudOperations(this, newOptions);
       this.fetchOperations = new ForgeSQLSelectOperations(newOptions);
     } catch (error) {
@@ -640,7 +568,7 @@ class ForgeSQLORM {
     return this.ormInstance.getDrizzleQueryBuilder();
   }
 }
-const mySqlDateTimeString = mysqlCore.customType({
+const forgeDateTimeString = mysqlCore.customType({
   dataType() {
     return "datetime";
   },
@@ -652,7 +580,7 @@ const mySqlDateTimeString = mysqlCore.customType({
     return parseDateTime(value, format);
   }
 });
-const mySqlTimestampString = mysqlCore.customType({
+const forgeTimestampString = mysqlCore.customType({
   dataType() {
     return "timestamp";
   },
@@ -664,7 +592,7 @@ const mySqlTimestampString = mysqlCore.customType({
     return parseDateTime(value, format);
   }
 });
-const mySqlDateString = mysqlCore.customType({
+const forgeDateString = mysqlCore.customType({
   dataType() {
     return "date";
   },
@@ -676,7 +604,7 @@ const mySqlDateString = mysqlCore.customType({
     return parseDateTime(value, format);
   }
 });
-const mySqlTimeString = mysqlCore.customType({
+const forgeTimeString = mysqlCore.customType({
   dataType() {
     return "time";
   },
@@ -691,11 +619,12 @@ exports.ForgeSQLCrudOperations = ForgeSQLCrudOperations;
 exports.ForgeSQLSelectOperations = ForgeSQLSelectOperations;
 exports.default = ForgeSQLORM;
 exports.extractAlias = extractAlias;
+exports.forgeDateString = forgeDateString;
+exports.forgeDateTimeString = forgeDateTimeString;
+exports.forgeDriver = forgeDriver;
+exports.forgeTimeString = forgeTimeString;
+exports.forgeTimestampString = forgeTimestampString;
 exports.getPrimaryKeys = getPrimaryKeys;
 exports.getTableMetadata = getTableMetadata;
-exports.mySqlDateString = mySqlDateString;
-exports.mySqlDateTimeString = mySqlDateTimeString;
-exports.mySqlTimeString = mySqlTimeString;
-exports.mySqlTimestampString = mySqlTimestampString;
 exports.parseDateTime = parseDateTime;
 //# sourceMappingURL=ForgeSQLORM.js.map