forge-sql-orm 2.0.9 → 2.0.11

package/src/core/ForgeSQLQueryBuilder.ts

@@ -1,319 +0,0 @@
-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>>;
-
-  select<TSelection extends SelectedFields>(
-    fields: TSelection,
-  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
-
-  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

@@ -1,93 +0,0 @@
-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

@@ -1,7 +0,0 @@
-import { int, mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core/index";
-
-export const migrations = mysqlTable("__migrations", {
-  id: int("id").primaryKey().autoincrement(),
-  name: varchar("name", { length: 255 }).notNull(),
-  created_at: timestamp("created_at").defaultNow().notNull(),
-});

package/src/index.ts

@@ -1,10 +0,0 @@
-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 default ForgeSQLORM;

package/src/utils/forgeDriver.ts

@@ -1,39 +0,0 @@
-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;
-  }
-};