forge-sql-orm 2.0.11 → 2.0.12

package/src/core/ForgeSQLQueryBuilder.ts

@@ -0,0 +1,351 @@
+import { UpdateQueryResponse } from "@forge/sql";
+import { SqlParameters } from "@forge/sql/out/sql-statement";
+import {
+  AnyMySqlSelectQueryBuilder,
+  AnyMySqlTable,
+  customType,
+  MySqlSelectBuilder,
+} from "drizzle-orm/mysql-core";
+import {
+  MySqlSelectDynamic,
+  type SelectedFields,
+} from "drizzle-orm/mysql-core/query-builders/select.types";
+import { InferInsertModel, SQL } from "drizzle-orm";
+import moment from "moment/moment";
+import { parseDateTime } from "../utils/sqlUtils";
+import { MySqlRemoteDatabase, MySqlRemotePreparedQueryHKT } from "drizzle-orm/mysql-proxy/index";
+
+// ============= Core Types =============
+
+/**
+ * Interface representing the main ForgeSQL operations.
+ * Provides access to CRUD operations and schema-level SQL operations.
+ */
+export interface ForgeSqlOperation extends QueryBuilderForgeSql {
+  /**
+   * Provides CRUD (Create, Read, Update, Delete) operations.
+   * @returns {CRUDForgeSQL} Interface for performing CRUD operations
+   */
+  crud(): CRUDForgeSQL;
+
+  /**
+   * Provides schema-level SQL fetch operations.
+   * @returns {SchemaSqlForgeSql} Interface for executing schema-bound SQL queries
+   */
+  fetch(): SchemaSqlForgeSql;
+}
+
+/**
+ * Interface for Query Builder operations.
+ * Provides access to the underlying Drizzle ORM query builder.
+ */
+export interface QueryBuilderForgeSql {
+  /**
+   * Creates a new query builder for the given entity.
+   * @returns {MySql2Database<Record<string, unknown>>} The Drizzle database instance for building queries
+   */
+  getDrizzleQueryBuilder(): MySqlRemoteDatabase<Record<string, unknown>>;
+
+  /**
+   * 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, MySqlRemotePreparedQueryHKT>} 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<TSelection extends SelectedFields>(
+    fields: TSelection,
+  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+
+  /**
+   * 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, MySqlRemotePreparedQueryHKT>} 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<TSelection extends SelectedFields>(
+    fields: TSelection,
+  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+}
+
+// ============= CRUD Operations =============
+
+/**
+ * Interface for CRUD (Create, Read, Update, Delete) operations.
+ * Provides methods for basic database operations with support for optimistic locking.
+ */
+export interface CRUDForgeSQL {
+  /**
+   * Inserts multiple records into the database.
+   * @template T - The type of the table schema
+   * @param {T} schema - The entity schema
+   * @param {Partial<InferInsertModel<T>>[]} models - The list of entities to insert
+   * @param {boolean} [updateIfExists] - Whether to update the row if it already exists (default: false)
+   * @returns {Promise<number>} The number of inserted rows
+   * @throws {Error} If the insert operation fails
+   */
+  insert<T extends AnyMySqlTable>(
+    schema: T,
+    models: Partial<InferInsertModel<T>>[],
+    updateIfExists?: boolean,
+  ): Promise<number>;
+
+  /**
+   * Deletes a record by its ID.
+   * @template T - The type of the table schema
+   * @param {unknown} id - The ID of the record to delete
+   * @param {T} schema - The entity schema
+   * @returns {Promise<number>} The number of rows affected
+   * @throws {Error} If the delete operation fails
+   */
+  deleteById<T extends AnyMySqlTable>(id: unknown, schema: T): Promise<number>;
+
+  /**
+   * Updates a record by its ID with optimistic locking support.
+   * If a version field is defined in the schema, versioning is applied:
+   * - the current record version is retrieved
+   * - checked for concurrent modifications
+   * - and then incremented
+   *
+   * @template T - The type of the table schema
+   * @param {Partial<InferInsertModel<T>>} entity - The entity with updated values
+   * @param {T} schema - The entity schema
+   * @returns {Promise<number>} The number of rows affected
+   * @throws {Error} If the primary key is not included in the update fields
+   * @throws {Error} If optimistic locking check fails
+   */
+  updateById<T extends AnyMySqlTable>(
+    entity: Partial<InferInsertModel<T>>,
+    schema: T,
+  ): Promise<number>;
+
+  /**
+   * Updates specified fields of records based on provided conditions.
+   * If the "where" parameter is not provided, the WHERE clause is built from the entity fields
+   * that are not included in the list of fields to update.
+   *
+   * @template T - The type of the table schema
+   * @param {Partial<InferInsertModel<T>>} updateData - The object containing values to update
+   * @param {T} schema - The entity schema
+   * @param {SQL<unknown>} [where] - Optional filtering conditions for the WHERE clause
+   * @returns {Promise<number>} The number of affected rows
+   * @throws {Error} If no filtering criteria are provided
+   * @throws {Error} If the update operation fails
+   */
+  updateFields<T extends AnyMySqlTable>(
+    updateData: Partial<InferInsertModel<T>>,
+    schema: T,
+    where?: SQL<unknown>,
+  ): Promise<number>;
+}
+
+// ============= Schema SQL Operations =============
+
+/**
+ * Interface for schema-level SQL operations.
+ * Provides methods for executing SQL queries with schema binding and type safety.
+ */
+export interface SchemaSqlForgeSql {
+  /**
+   * Executes a Drizzle query and returns a single result.
+   * @template T - The type of the query builder
+   * @param {T} query - The Drizzle query to execute
+   * @returns {Promise<Awaited<T> extends Array<any> ? Awaited<T>[number] | undefined : Awaited<T> | undefined>} A single result object or undefined
+   * @throws {Error} If more than one record is returned
+   * @throws {Error} If the query execution fails
+   */
+  executeQueryOnlyOne<T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>>(
+    query: T,
+  ): Promise<
+    Awaited<T> extends Array<any> ? Awaited<T>[number] | undefined : Awaited<T> | undefined
+  >;
+
+  /**
+   * Executes a raw SQL query and returns the results.
+   * @template T - The type of the result objects
+   * @param {string} query - The raw SQL query
+   * @param {SqlParameters[]} [params] - Optional SQL parameters
+   * @returns {Promise<T[]>} A list of results as objects
+   * @throws {Error} If the query execution fails
+   */
+  executeRawSQL<T extends object | unknown>(query: string, params?: SqlParameters[]): Promise<T[]>;
+
+  /**
+   * Executes a raw SQL update query.
+   * @param {string} query - The raw SQL update query
+   * @param {SqlParameters[]} [params] - Optional SQL parameters
+   * @returns {Promise<UpdateQueryResponse>} The update response containing affected rows
+   * @throws {Error} If the update operation fails
+   */
+  executeRawUpdateSQL(query: string, params?: unknown[]): Promise<UpdateQueryResponse>;
+}
+
+// ============= Configuration Types =============
+
+/**
+ * Interface for version field metadata.
+ * Defines the configuration for optimistic locking version fields.
+ */
+export interface VersionFieldMetadata {
+  /** Name of the version field */
+  fieldName: string;
+}
+
+/**
+ * Interface for table metadata.
+ * Defines the configuration for a specific table.
+ */
+export interface TableMetadata {
+  /** Name of the table */
+  tableName: string;
+  /** Version field configuration for optimistic locking */
+  versionField: VersionFieldMetadata;
+}
+
+/**
+ * Type for additional metadata configuration.
+ * Maps table names to their metadata configuration.
+ */
+export type AdditionalMetadata = Record<string, TableMetadata>;
+
+/**
+ * Options for configuring ForgeSQL ORM behavior.
+ */
+export interface ForgeSqlOrmOptions {
+  /**
+   * Enables logging of raw SQL queries in the Atlassian Forge Developer Console.
+   * Useful for debugging and monitoring SQL operations.
+   * @default false
+   */
+  logRawSqlQuery?: boolean;
+
+  /**
+   * Disables optimistic locking for all operations.
+   * When enabled, version checks are skipped during updates.
+   * @default false
+   */
+  disableOptimisticLocking?: boolean;
+
+  /**
+   * Additional metadata for table configuration.
+   * Allows specifying table-specific settings and behaviors.
+   * @example
+   * ```typescript
+   * {
+   *   users: {
+   *     tableName: "users",
+   *     versionField: {
+   *       fieldName: "updatedAt",
+   *       type: "datetime",
+   *       nullable: false
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  additionalMetadata?: AdditionalMetadata;
+}
+
+// ============= Custom Types =============
+
+/**
+ * Custom type for MySQL datetime fields.
+ * Handles conversion between JavaScript Date objects and MySQL datetime strings.
+ */
+export const forgeDateTimeString = customType<{
+  data: Date;
+  driver: string;
+  config: { format?: string };
+}>({
+  dataType() {
+    return "datetime";
+  },
+  toDriver(value: Date) {
+    return moment(value as Date).format("YYYY-MM-DDTHH:mm:ss.SSS");
+  },
+  fromDriver(value: unknown) {
+    const format = "YYYY-MM-DDTHH:mm:ss.SSS";
+    return parseDateTime(value as string, format);
+  },
+});
+
+/**
+ * Custom type for MySQL timestamp fields.
+ * Handles conversion between JavaScript Date objects and MySQL timestamp strings.
+ */
+export const forgeTimestampString = customType<{
+  data: Date;
+  driver: string;
+  config: { format?: string };
+}>({
+  dataType() {
+    return "timestamp";
+  },
+  toDriver(value: Date) {
+    return moment(value as Date).format("YYYY-MM-DDTHH:mm:ss.SSS");
+  },
+  fromDriver(value: unknown) {
+    const format = "YYYY-MM-DDTHH:mm:ss.SSS";
+    return parseDateTime(value as string, format);
+  },
+});
+
+/**
+ * Custom type for MySQL date fields.
+ * Handles conversion between JavaScript Date objects and MySQL date strings.
+ */
+export const forgeDateString = customType<{
+  data: Date;
+  driver: string;
+  config: { format?: string };
+}>({
+  dataType() {
+    return "date";
+  },
+  toDriver(value: Date) {
+    return moment(value as Date).format("YYYY-MM-DD");
+  },
+  fromDriver(value: unknown) {
+    const format = "YYYY-MM-DD";
+    return parseDateTime(value as string, format);
+  },
+});
+
+/**
+ * Custom type for MySQL time fields.
+ * Handles conversion between JavaScript Date objects and MySQL time strings.
+ */
+export const forgeTimeString = customType<{
+  data: Date;
+  driver: string;
+  config: { format?: string };
+}>({
+  dataType() {
+    return "time";
+  },
+  toDriver(value: Date) {
+    return moment(value as Date).format("HH:mm:ss.SSS");
+  },
+  fromDriver(value: unknown) {
+    return parseDateTime(value as string, "HH:mm:ss.SSS");
+  },
+});

package/src/core/ForgeSQLSelectOperations.ts

@@ -0,0 +1,93 @@
+import { sql, UpdateQueryResponse } from "@forge/sql";
+import { ForgeSqlOrmOptions, SchemaSqlForgeSql } from "./ForgeSQLQueryBuilder";
+import {
+  AnyMySqlSelectQueryBuilder,
+  MySqlSelectDynamic,
+} from "drizzle-orm/mysql-core/query-builders/select.types";
+
+/**
+ * Class implementing SQL select operations for ForgeSQL ORM.
+ * Provides methods for executing queries and mapping results to entity types.
+ */
+export class ForgeSQLSelectOperations implements SchemaSqlForgeSql {
+  private readonly options: ForgeSqlOrmOptions;
+
+  /**
+   * Creates a new instance of ForgeSQLSelectOperations.
+   * @param {ForgeSqlOrmOptions} options - Configuration options for the ORM
+   */
+  constructor(options: ForgeSqlOrmOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Executes a Drizzle query and returns a single result.
+   * Throws an error if more than one record is returned.
+   *
+   * @template T - The type of the query builder
+   * @param {T} query - The Drizzle query to execute
+   * @returns {Promise<Awaited<T> extends Array<any> ? Awaited<T>[number] | undefined : Awaited<T> | undefined>} A single result object or undefined
+   * @throws {Error} If more than one record is returned
+   */
+  async executeQueryOnlyOne<T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>>(
+    query: T,
+  ): Promise<
+    Awaited<T> extends Array<any> ? Awaited<T>[number] | undefined : Awaited<T> | undefined
+  > {
+    const results: Awaited<T> = await query;
+    const datas = results as unknown[];
+    if (!datas.length) {
+      return undefined;
+    }
+    if (datas.length > 1) {
+      throw new Error(`Expected 1 record but returned ${datas.length}`);
+    }
+
+    return datas[0] as Awaited<T> extends Array<any> ? Awaited<T>[number] : Awaited<T>;
+  }
+
+  /**
+   * Executes a raw SQL query and returns the results.
+   * Logs the query if logging is enabled.
+   *
+   * @template T - The type of the result objects
+   * @param {string} query - The raw SQL query to execute
+   * @param {SqlParameters[]} [params] - Optional SQL parameters
+   * @returns {Promise<T[]>} A list of results as objects
+   */
+  async executeRawSQL<T extends object | unknown>(query: string, params?: unknown[]): Promise<T[]> {
+    if (this.options.logRawSqlQuery) {
+      console.debug(
+        `Executing with SQL ${query}` + params ? `, with params: ${JSON.stringify(params)}` : "",
+      );
+    }
+    const sqlStatement = sql.prepare<T>(query);
+    if (params) {
+      sqlStatement.bindParams(...params);
+    }
+    const result = await sqlStatement.execute();
+    return result.rows as T[];
+  }
+
+  /**
+   * Executes a raw SQL update query.
+   * @param {string} query - The raw SQL update query
+   * @param {SqlParameters[]} [params] - Optional SQL parameters
+   * @returns {Promise<UpdateQueryResponse>} The update response containing affected rows
+   */
+  async executeRawUpdateSQL(query: string, params?: unknown[]): Promise<UpdateQueryResponse> {
+    const sqlStatement = sql.prepare<UpdateQueryResponse>(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;
+  }
+}

package/src/core/SystemTables.ts

@@ -0,0 +1,10 @@
+import { bigint, mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core";
+import { Table } from "drizzle-orm";
+
+export const migrations = mysqlTable("__migrations", {
+  id: bigint("id", { mode: "number" }).primaryKey().autoincrement(),
+  name: varchar("name", { length: 255 }).notNull(),
+  migratedAt: timestamp("migratedAt").defaultNow().notNull(),
+});
+
+export const forgeSystemTables: Table[] = [migrations];

package/src/index.ts

@@ -0,0 +1,11 @@
+import ForgeSQLORM from "./core/ForgeSQLORM";
+
+export * from "./core/ForgeSQLQueryBuilder";
+export * from "./core/ForgeSQLCrudOperations";
+export * from "./core/ForgeSQLSelectOperations";
+export * from "./utils/sqlUtils";
+export * from "./utils/forgeDriver";
+export * from "./webtriggers";
+export * from "./lib/drizzle/extensions/selectAliased";
+
+export default ForgeSQLORM;

package/src/lib/drizzle/extensions/selectAliased.ts

@@ -0,0 +1,74 @@
+import {MySqlRemoteDatabase} from "drizzle-orm/mysql-proxy";
+import type {SelectedFields} from "drizzle-orm/mysql-core/query-builders/select.types";
+import {applyFromDriverTransform, mapSelectFieldsWithAlias} from "../../..";
+import {MySqlSelectBuilder} from "drizzle-orm/mysql-core";
+import {MySqlRemotePreparedQueryHKT} from "drizzle-orm/mysql-proxy";
+
+function createAliasedSelectBuilder<TSelection extends SelectedFields>(
+    db: MySqlRemoteDatabase<any>,
+    fields: TSelection,
+    selectFn: (selections: any) => MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>
+): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT> {
+    const { selections, aliasMap } = mapSelectFieldsWithAlias(fields);
+    const builder = selectFn(selections);
+
+    const wrapBuilder = (rawBuilder: any): any => {
+        return new Proxy(rawBuilder, {
+            get(target, prop, receiver) {
+                if (prop === 'execute') {
+                    return async (...args: any[]) => {
+                        const rows = await target.execute(...args);
+                        return applyFromDriverTransform(rows, selections, aliasMap);
+                    };
+                }
+
+                if (prop === 'then') {
+                    return (onfulfilled: any, onrejected: any) =>
+                        target.execute().then(
+                            (rows: unknown[]) => {
+                                const transformed = applyFromDriverTransform(rows, selections, aliasMap);
+                                return onfulfilled?.(transformed);
+                            },
+                            onrejected,
+                        );
+                }
+
+                const value = Reflect.get(target, prop, receiver);
+
+                if (typeof value === 'function') {
+                    return (...args: any[]) => {
+                        const result = value.apply(target, args);
+
+                        if (typeof result === 'object' && result !== null && 'execute' in result) {
+                            return wrapBuilder(result);
+                        }
+
+                        return result;
+                    };
+                }
+
+                return value;
+            },
+        });
+    };
+
+    return wrapBuilder(builder);
+}
+
+export function patchDbWithSelectAliased(db: MySqlRemoteDatabase<any>): MySqlRemoteDatabase<any> & {
+    selectAliased:<TSelection extends SelectedFields>(
+        fields: TSelection,
+    )=> MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>,
+    selectAliasedDistinct:<TSelection extends SelectedFields>(
+        fields: TSelection,
+    )=> MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>  } {
+    db.selectAliased = function <TSelection extends SelectedFields>(fields: TSelection) {
+        return createAliasedSelectBuilder(db, fields, (selections) => db.select(selections));
+    };
+
+    db.selectAliasedDistinct = function <TSelection extends SelectedFields>(fields: TSelection) {
+        return createAliasedSelectBuilder(db, fields, (selections) => db.selectDistinct(selections));
+    };
+
+    return db;
+}

package/src/lib/drizzle/extensions/types.d.ts

@@ -0,0 +1,14 @@
+import { SelectedFields } from 'drizzle-orm';
+import {MySqlSelectBuilder} from "drizzle-orm/mysql-core";
+import {MySqlRemotePreparedQueryHKT} from "drizzle-orm/mysql-proxy";
+
+declare module 'drizzle-orm/mysql-proxy' {
+    interface MySqlRemoteDatabase<> {
+        selectAliased<TSelection extends SelectedFields>(
+            fields: TSelection,
+        ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+        selectAliasedDistinct<TSelection extends SelectedFields>(
+            fields: TSelection,
+        ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+    }
+}

package/src/utils/forgeDriver.ts

@@ -0,0 +1,39 @@
+import { sql, UpdateQueryResponse } from "@forge/sql";
+
+interface ForgeSQLResult {
+  rows: Record<string, unknown>[] | Record<string, unknown>;
+}
+
+export const forgeDriver = async (
+  query: string,
+  params: any[],
+  method: "all" | "execute",
+): Promise<{
+  rows: any[];
+  insertId?: number;
+  affectedRows?: number;
+}> => {
+  try {
+    if (method == "execute") {
+      const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
+      if (params) {
+        sqlStatement.bindParams(...params);
+      }
+      const updateQueryResponseResults = await sqlStatement.execute();
+      let result = updateQueryResponseResults.rows as any;
+      return { ...result, rows: [result] };
+    } else {
+      const sqlStatement = await sql.prepare<unknown>(query);
+      if (params) {
+        await sqlStatement.bindParams(...params);
+      }
+      const result = (await sqlStatement.execute()) as ForgeSQLResult;
+      let rows;
+      rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
+      return { rows: rows };
+    }
+  } catch (error) {
+    console.error("SQL Error:", JSON.stringify(error));
+    throw error;
+  }
+};