forge-sql-orm 2.0.18 → 2.0.19

package/dist/ForgeSQLORM.mjs

@@ -62,7 +62,7 @@ function processForeignKeys(table, foreignKeysSymbol, extraSymbol) {
       const configBuilderData = extraConfigBuilder(table);
       if (configBuilderData) {
         const configBuilders = Array.isArray(configBuilderData) ? configBuilderData : Object.values(configBuilderData).map(
-          (item) => item.value || item
+          (item) => item.value ?? item
         );
         configBuilders.forEach((builder) => {
           if (!builder?.constructor) return;
@@ -97,7 +97,7 @@ function getTableMetadata(table) {
       const configBuilderData = extraConfigBuilder(table);
       if (configBuilderData) {
         const configBuilders = Array.isArray(configBuilderData) ? configBuilderData : Object.values(configBuilderData).map(
-          (item) => item.value || item
+          (item) => item.value ?? item
         );
         configBuilders.forEach((builder) => {
           if (!builder?.constructor) return;
@@ -127,13 +127,9 @@ function getTableMetadata(table) {
 }
 function generateDropTableStatements(tables) {
   const dropStatements = [];
-  tables.forEach((table) => {
-    const tableMetadata = getTableMetadata(table);
-    if (tableMetadata.tableName) {
-      dropStatements.push(`DROP TABLE IF EXISTS \`${tableMetadata.tableName}\`;`);
-    }
+  tables.forEach((tableName) => {
+    dropStatements.push(`DROP TABLE IF EXISTS \`${tableName}\`;`);
   });
-  dropStatements.push(`DELETE FROM __migrations;`);
   return dropStatements;
 }
 function mapSelectTableToAlias(table, uniqPrefix, aliasMap) {
@@ -191,9 +187,9 @@ function getAliasFromDrizzleAlias(value) {
       const aliasNameChunk = queryChunks[queryChunks.length - 2];
       if (isSQLWrapper(aliasNameChunk) && "queryChunks" in aliasNameChunk) {
         const aliasNameChunkSql = aliasNameChunk;
-        if (aliasNameChunkSql && aliasNameChunkSql.queryChunks.length === 1) {
+        if (aliasNameChunkSql.queryChunks?.length === 1 && aliasNameChunkSql.queryChunks[0]) {
           const queryChunksStringChunc = aliasNameChunkSql.queryChunks[0];
-          if (queryChunksStringChunc && "value" in queryChunksStringChunc) {
+          if ("value" in queryChunksStringChunc) {
             const values = queryChunksStringChunc.value;
             if (values && values.length === 1) {
               return values[0];
@@ -245,7 +241,7 @@ function applyFromDriverTransform(rows, selections, aliasMap) {
   });
 }
 function processNullBranches(obj) {
-  if (obj === null || typeof obj !== "object" || obj === void 0) {
+  if (obj === null || typeof obj !== "object") {
     return obj;
   }
   if (obj.constructor && obj.constructor.name !== "Object") {
@@ -258,7 +254,7 @@ function processNullBranches(obj) {
       result[key] = null;
       continue;
     }
-    if (typeof value === "object" && value !== null && value !== void 0) {
+    if (typeof value === "object") {
       const processed = processNullBranches(value);
       result[key] = processed;
       if (processed !== null) {
@@ -608,9 +604,8 @@ class ForgeSQLSelectOperations {
    */
   async executeRawSQL(query, params) {
     if (this.options.logRawSqlQuery) {
-      console.debug(
-        `Executing with SQL ${query}` + params ? `, with params: ${JSON.stringify(params)}` : ""
-      );
+      const paramsStr = params ? `, with params: ${JSON.stringify(params)}` : "";
+      console.debug(`Executing with SQL ${query}${paramsStr}`);
     }
     const sqlStatement = sql$1.prepare(query);
     if (params) {
@@ -632,7 +627,7 @@ class ForgeSQLSelectOperations {
     }
     if (this.options.logRawSqlQuery) {
       console.debug(
-        `Executing Update with SQL ${query}` + params ? `, with params: ${JSON.stringify(params)}` : ""
+        `Executing Update with SQL ${query}` + (params ? `, with params: ${JSON.stringify(params)}` : "")
       );
     }
     const updateQueryResponseResults = await sqlStatement.execute();
@@ -697,7 +692,7 @@ function injectSqlHints(query, hints) {
 function createForgeDriverProxy(options, logRawSqlQuery) {
   return async (query, params, method) => {
     const modifiedQuery = injectSqlHints(query, options);
-    if (options && logRawSqlQuery) {
+    if (options && logRawSqlQuery && modifiedQuery !== query) {
       console.warn("modified query: " + modifiedQuery);
     }
     return forgeDriver(modifiedQuery, params, method);
@@ -746,11 +741,239 @@ function patchDbWithSelectAliased(db) {
   };
   return db;
 }
+class ForgeSQLAnalyseOperation {
+  forgeOperations;
+  /**
+   * Creates a new instance of ForgeSQLAnalizeOperation.
+   * @param {ForgeSqlOperation} forgeOperations - The ForgeSQL operations instance
+   */
+  constructor(forgeOperations) {
+    this.forgeOperations = forgeOperations;
+    this.mapToCamelCaseClusterStatement = this.mapToCamelCaseClusterStatement.bind(this);
+  }
+  /**
+   * Executes EXPLAIN on a raw SQL query.
+   * @param {string} query - The SQL query to analyze
+   * @param {unknown[]} bindParams - The query parameters
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  async explainRaw(query, bindParams) {
+    const results = await this.forgeOperations.fetch().executeRawSQL(`EXPLAIN ${query}`, bindParams);
+    return results.map((row) => ({
+      id: row.id,
+      estRows: row.estRows,
+      actRows: row.actRows,
+      task: row.task,
+      accessObject: row["access object"],
+      executionInfo: row["execution info"],
+      operatorInfo: row["operator info"],
+      memory: row.memory,
+      disk: row.disk
+    }));
+  }
+  /**
+   * Executes EXPLAIN on a Drizzle query.
+   * @param {{ toSQL: () => Query }} query - The Drizzle query to analyze
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  async explain(query) {
+    const { sql: sql2, params } = query.toSQL();
+    return this.explainRaw(sql2, params);
+  }
+  /**
+   * Executes EXPLAIN ANALYZE on a raw SQL query.
+   * @param {string} query - The SQL query to analyze
+   * @param {unknown[]} bindParams - The query parameters
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  async explainAnalyzeRaw(query, bindParams) {
+    const results = await this.forgeOperations.fetch().executeRawSQL(`EXPLAIN ANALYZE ${query}`, bindParams);
+    return results.map((row) => ({
+      id: row.id,
+      estRows: row.estRows,
+      actRows: row.actRows,
+      task: row.task,
+      accessObject: row["access object"],
+      executionInfo: row["execution info"],
+      operatorInfo: row["operator info"],
+      memory: row.memory,
+      disk: row.disk
+    }));
+  }
+  /**
+   * Executes EXPLAIN ANALYZE on a Drizzle query.
+   * @param {{ toSQL: () => Query }} query - The Drizzle query to analyze
+   * @returns {Promise<ExplainAnalyzeRow[]>} The execution plan analysis results
+   */
+  async explainAnalyze(query) {
+    const { sql: sql2, params } = query.toSQL();
+    return this.explainAnalyzeRaw(sql2, params);
+  }
+  /**
+   * Decodes a query execution plan from its string representation.
+   * @param {string} input - The raw execution plan string
+   * @returns {ExplainAnalyzeRow[]} The decoded execution plan rows
+   */
+  decodedPlan(input) {
+    if (!input) {
+      return [];
+    }
+    const lines = input.trim().split("\n");
+    if (lines.length < 2) return [];
+    const headersRaw = lines[0].split("	").map((h) => h.trim()).filter(Boolean);
+    const headers = headersRaw.map((h) => {
+      return h.replace(/\s+/g, " ").replace(/[-\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^./, (s) => s.toLowerCase());
+    });
+    return lines.slice(1).map((line) => {
+      const values = line.split("	").map((s) => s.trim()).filter(Boolean);
+      const row = {};
+      headers.forEach((key, i) => {
+        row[key] = values[i] ?? "";
+      });
+      return row;
+    });
+  }
+  /**
+   * Normalizes a raw slow query row into a more structured format.
+   * @param {SlowQueryRaw} row - The raw slow query data
+   * @returns {SlowQueryNormalized} The normalized slow query data
+   */
+  normalizeSlowQuery(row) {
+    return {
+      time: row.Time,
+      txnStartTs: row.Txn_start_ts,
+      user: row.User,
+      host: row.Host,
+      connId: row.Conn_ID,
+      db: row.DB,
+      query: row.Query,
+      digest: row.Digest,
+      queryTime: row.Query_time,
+      compileTime: row.Compile_time,
+      optimizeTime: row.Optimize_time,
+      processTime: row.Process_time,
+      waitTime: row.Wait_time,
+      parseTime: row.Parse_time,
+      rewriteTime: row.Rewrite_time,
+      copTime: row.Cop_time,
+      copProcAvg: row.Cop_proc_avg,
+      copProcMax: row.Cop_proc_max,
+      copProcP90: row.Cop_proc_p90,
+      copProcAddr: row.Cop_proc_addr,
+      copWaitAvg: row.Cop_wait_avg,
+      copWaitMax: row.Cop_wait_max,
+      copWaitP90: row.Cop_wait_p90,
+      copWaitAddr: row.Cop_wait_addr,
+      memMax: row.Mem_max,
+      diskMax: row.Disk_max,
+      totalKeys: row.Total_keys,
+      processKeys: row.Process_keys,
+      requestCount: row.Request_count,
+      kvTotal: row.KV_total,
+      pdTotal: row.PD_total,
+      resultRows: row.Result_rows,
+      rocksdbBlockCacheHitCount: row.Rocksdb_block_cache_hit_count,
+      rocksdbBlockReadCount: row.Rocksdb_block_read_count,
+      rocksdbBlockReadByte: row.Rocksdb_block_read_byte,
+      plan: row.Plan,
+      binaryPlan: row.Binary_plan,
+      planDigest: row.Plan_digest,
+      parsedPlan: this.decodedPlan(row.Plan)
+    };
+  }
+  /**
+   * Builds a SQL query for retrieving cluster statement history.
+   * @param {string[]} tables - The tables to analyze
+   * @param {Date} [from] - The start date for the analysis
+   * @param {Date} [to] - The end date for the analysis
+   * @returns {string} The SQL query for cluster statement history
+   */
+  buildClusterStatementQuery(tables, from, to) {
+    const formatDateTime = (date) => moment(date).format("YYYY-MM-DDTHH:mm:ss.SSS");
+    const tableConditions = tables.map((table) => `TABLE_NAMES LIKE CONCAT(SCHEMA_NAME, '.', '%', '${table}', '%')`).join(" OR ");
+    const timeConditions = [];
+    if (from) {
+      timeConditions.push(`SUMMARY_BEGIN_TIME >= '${formatDateTime(from)}'`);
+    }
+    if (to) {
+      timeConditions.push(`SUMMARY_END_TIME <= '${formatDateTime(to)}'`);
+    }
+    let whereClauses;
+    if (tableConditions?.length) {
+      whereClauses = [tableConditions ? `(${tableConditions})` : "", ...timeConditions];
+    } else {
+      whereClauses = timeConditions;
+    }
+    return `
+      SELECT *
+      FROM (
+        SELECT * FROM INFORMATION_SCHEMA.CLUSTER_STATEMENTS_SUMMARY
+        UNION ALL
+        SELECT * FROM INFORMATION_SCHEMA.CLUSTER_STATEMENTS_SUMMARY_HISTORY
+      ) AS combined
+      ${whereClauses?.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : ""}
+    `;
+  }
+  /**
+   * Retrieves and analyzes slow queries from the database.
+   * @returns {Promise<SlowQueryNormalized[]>} The normalized slow query data
+   */
+  async analyzeSlowQueries() {
+    const results = await this.forgeOperations.fetch().executeRawSQL(`
+      SELECT *
+      FROM information_schema.slow_query
+      ORDER BY time DESC
+    `);
+    return results.map((row) => this.normalizeSlowQuery(row));
+  }
+  /**
+   * Converts a cluster statement row to camelCase format.
+   * @param {Record<string, any>} input - The input row data
+   * @returns {ClusterStatementRowCamelCase} The converted row data
+   */
+  mapToCamelCaseClusterStatement(input) {
+    if (!input) {
+      return {};
+    }
+    const result = {};
+    result.parsedPlan = this.decodedPlan(input["PLAN"] ?? "");
+    for (const key in input) {
+      const camelKey = key.toLowerCase().replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+      result[camelKey] = input[key];
+    }
+    return result;
+  }
+  /**
+   * Analyzes query history for specific tables using raw table names.
+   * @param {string[]} tables - The table names to analyze
+   * @param {Date} [fromDate] - The start date for the analysis
+   * @param {Date} [toDate] - The end date for the analysis
+   * @returns {Promise<ClusterStatementRowCamelCase[]>} The analyzed query history
+   */
+  async analyzeQueriesHistoryRaw(tables, fromDate, toDate) {
+    const results = await this.forgeOperations.fetch().executeRawSQL(
+      this.buildClusterStatementQuery(tables ?? [], fromDate, toDate)
+    );
+    return results.map((r) => this.mapToCamelCaseClusterStatement(r));
+  }
+  /**
+   * Analyzes query history for specific tables using Drizzle table objects.
+   * @param {AnyMySqlTable[]} tables - The Drizzle table objects to analyze
+   * @param {Date} [fromDate] - The start date for the analysis
+   * @param {Date} [toDate] - The end date for the analysis
+   * @returns {Promise<ClusterStatementRowCamelCase[]>} The analyzed query history
+   */
+  async analyzeQueriesHistory(tables, fromDate, toDate) {
+    const tableNames = tables?.map((table) => getTableName(table)) ?? [];
+    return this.analyzeQueriesHistoryRaw(tableNames, fromDate, toDate);
+  }
+}
 class ForgeSQLORMImpl {
   static instance = null;
   drizzle;
   crudOperations;
   fetchOperations;
+  analyzeOperations;
   /**
    * Private constructor to enforce singleton behavior.
    * @param options - Options for configuring ForgeSQL ORM behavior.
@@ -770,20 +993,26 @@ class ForgeSQLORMImpl {
       );
       this.crudOperations = new ForgeSQLCrudOperations(this, newOptions);
       this.fetchOperations = new ForgeSQLSelectOperations(newOptions);
+      this.analyzeOperations = new ForgeSQLAnalyseOperation(this);
     } catch (error) {
       console.error("ForgeSQLORM initialization failed:", error);
       throw error;
     }
   }
+  /**
+   * Create the modify operations instance.
+   * @returns modify operations.
+   */
+  modify() {
+    return this.crudOperations;
+  }
   /**
    * Returns the singleton instance of ForgeSQLORMImpl.
    * @param options - Options for configuring ForgeSQL ORM behavior.
    * @returns The singleton instance of ForgeSQLORMImpl.
    */
   static getInstance(options) {
-    if (!ForgeSQLORMImpl.instance) {
-      ForgeSQLORMImpl.instance = new ForgeSQLORMImpl(options);
-    }
+    ForgeSQLORMImpl.instance ??= new ForgeSQLORMImpl(options);
     return ForgeSQLORMImpl.instance;
   }
   /**
@@ -791,7 +1020,7 @@ class ForgeSQLORMImpl {
    * @returns CRUD operations.
    */
   crud() {
-    return this.crudOperations;
+    return this.modify();
   }
   /**
    * Retrieves the fetch operations instance.
@@ -800,6 +1029,9 @@ class ForgeSQLORMImpl {
   fetch() {
     return this.fetchOperations;
   }
+  analyze() {
+    return this.analyzeOperations;
+  }
   /**
    * Returns a Drizzle query builder instance.
    *
@@ -887,7 +1119,7 @@ class ForgeSQLORM {
    *
    * @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
+   * @returns {MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>} A distinct select query builder with unique field aliases
    * @throws {Error} If fields parameter is empty
    * @example
    * ```typescript
@@ -905,7 +1137,14 @@ class ForgeSQLORM {
    * @returns CRUD operations.
    */
   crud() {
-    return this.ormInstance.crud();
+    return this.ormInstance.modify();
+  }
+  /**
+   * Proxies the `modify` method from `ForgeSQLORMImpl`.
+   * @returns Modify operations.
+   */
+  modify() {
+    return this.ormInstance.modify();
   }
   /**
    * Proxies the `fetch` method from `ForgeSQLORMImpl`.
@@ -914,6 +1153,13 @@ class ForgeSQLORM {
   fetch() {
     return this.ormInstance.fetch();
   }
+  /**
+   * Provides query analysis capabilities including EXPLAIN ANALYZE and slow query analysis.
+   * @returns {SchemaAnalyzeForgeSql} Interface for analyzing query performance
+   */
+  analyze() {
+    return this.ormInstance.analyze();
+  }
   /**
    * Returns a Drizzle query builder instance.
    *
@@ -974,8 +1220,19 @@ const forgeTimeString = customType({
     return parseDateTime(value, "HH:mm:ss.SSS");
   }
 });
-async function dropSchemaMigrations(tables) {
+const migrations = mysqlTable("__migrations", {
+  id: bigint("id", { mode: "number" }).primaryKey().autoincrement(),
+  name: varchar("name", { length: 255 }).notNull(),
+  migratedAt: timestamp("migratedAt").defaultNow().notNull()
+});
+async function getTables() {
+  const tables = await sql$1.executeDDL("SHOW TABLES");
+  return tables.rows.flatMap((tableInfo) => Object.values(tableInfo));
+}
+const forgeSystemTables = [migrations];
+async function dropSchemaMigrations() {
   try {
+    const tables = await getTables();
     const dropStatements = generateDropTableStatements(tables);
     for (const statement of dropStatements) {
       console.warn(statement);
@@ -986,32 +1243,41 @@ async function dropSchemaMigrations(tables) {
       "⚠️ All data in these tables has been permanently deleted. This operation cannot be undone."
     );
   } catch (error) {
+    console.error(error);
     const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
     return getHttpResponse(500, errorMessage);
   }
 }
 const applySchemaMigrations = async (migration) => {
-  console.log("Provisioning the database");
-  await sql$1._provision();
-  console.info("Running schema migrations");
-  const migrations2 = await migration(migrationRunner);
-  const successfulMigrations = await migrations2.run();
-  console.info("Migrations applied:", successfulMigrations);
-  const migrationHistory = (await 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"] },
-    statusCode: 200,
-    statusText: "OK",
-    body: "Migrations successfully executed"
-  };
+  try {
+    if (typeof migration !== "function") {
+      throw new Error("migration is not a function");
+    }
+    console.log("Provisioning the database");
+    await sql$1._provision();
+    console.info("Running schema migrations");
+    const migrations2 = await migration(migrationRunner);
+    const successfulMigrations = await migrations2.run();
+    console.info("Migrations applied:", successfulMigrations);
+    const migrationList = await migrationRunner.list();
+    const migrationHistory = Array.isArray(migrationList) && migrationList.length > 0 ? migrationList.map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toUTCString()}`).join("\n") : "No migrations found";
+    console.info("Migrations history:\nid, name, migrated_at\n", migrationHistory);
+    return {
+      headers: { "Content-Type": ["application/json"] },
+      statusCode: 200,
+      statusText: "OK",
+      body: "Migrations successfully executed"
+    };
+  } catch (error) {
+    console.error("Error during migration:", error);
+    return {
+      headers: { "Content-Type": ["application/json"] },
+      statusCode: 500,
+      statusText: "Internal Server Error",
+      body: error instanceof Error ? error.message : "Unknown error during migration"
+    };
+  }
 };
-const migrations = mysqlTable("__migrations", {
-  id: bigint("id", { mode: "number" }).primaryKey().autoincrement(),
-  name: varchar("name", { length: 255 }).notNull(),
-  migratedAt: timestamp("migratedAt").defaultNow().notNull()
-});
-const forgeSystemTables = [migrations];
 async function fetchSchemaWebTrigger() {
   try {
     const tables = await getTables();
@@ -1024,14 +1290,10 @@ async function fetchSchemaWebTrigger() {
     return getHttpResponse(500, errorMessage);
   }
 }
-async function getTables() {
-  const tables = await sql$1.executeDDL("SHOW TABLES");
-  return tables.rows.flatMap((tableInfo) => Object.values(tableInfo));
-}
 async function generateCreateTableStatements(tables) {
   const statements = [];
   for (const table of tables) {
-    const createTableResult = await sql$1.executeDDL(`SHOW CREATE TABLE ${table}`);
+    const createTableResult = await sql$1.executeDDL(`SHOW CREATE TABLE "${table}"`);
     const createTableStatements = createTableResult.rows.filter((row) => !isSystemTable(row.Table)).map((row) => formatCreateTableStatement(row["Create Table"]));
     statements.push(...createTableStatements);
   }
@@ -1071,14 +1333,17 @@ export {
   forgeDateString,
   forgeDateTimeString,
   forgeDriver,
+  forgeSystemTables,
   forgeTimeString,
   forgeTimestampString,
   generateDropTableStatements,
   getHttpResponse,
   getPrimaryKeys,
   getTableMetadata,
+  getTables,
   mapSelectAllFieldsToAlias,
   mapSelectFieldsWithAlias,
+  migrations,
   parseDateTime,
   patchDbWithSelectAliased
 };