forge-sql-orm 2.1.1 → 2.1.3

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

@@ -1,28 +1,35 @@
 import {
-    MySqlRawQueryResult,
-    MySqlRemoteDatabase,
-    MySqlRemotePreparedQueryHKT,
-    MySqlRemoteQueryResultHKT,
+  MySqlRawQueryResult,
+  MySqlRemoteDatabase,
+  MySqlRemotePreparedQueryHKT,
+  MySqlRemoteQueryResultHKT,
 } from "drizzle-orm/mysql-proxy";
 
-import {SelectedFields} from "drizzle-orm/mysql-core/query-builders/select.types";
-import {applyFromDriverTransform, ForgeSqlOrmOptions, mapSelectFieldsWithAlias} from "../../..";
-import {MySqlSelectBase, MySqlSelectBuilder} from "drizzle-orm/mysql-core";
-import type {MySqlTable} from "drizzle-orm/mysql-core/table";
-import {MySqlDeleteBase, MySqlInsertBuilder, MySqlUpdateBuilder,} from "drizzle-orm/mysql-core/query-builders";
-import {clearCache, getFromCache, setCacheResult} from "../../../utils/cacheUtils";
+import { SelectedFields } from "drizzle-orm/mysql-core/query-builders/select.types";
+import { applyFromDriverTransform, ForgeSqlOrmOptions, mapSelectFieldsWithAlias } from "../../..";
+import { MySqlSelectBase, MySqlSelectBuilder } from "drizzle-orm/mysql-core";
+import type { MySqlTable } from "drizzle-orm/mysql-core/table";
+import {
+  MySqlDeleteBase,
+  MySqlInsertBuilder,
+  MySqlUpdateBuilder,
+} from "drizzle-orm/mysql-core/query-builders";
+import { clearCache, getFromCache, setCacheResult } from "../../../utils/cacheUtils";
 import {
-    cacheApplicationContext,
-    evictLocalCacheQuery,
-    getQueryLocalCacheQuery,
-    saveQueryLocalCacheQuery,
-    saveTableIfInsideCacheContext,
+  cacheApplicationContext,
+  evictLocalCacheQuery,
+  getQueryLocalCacheQuery,
+  saveQueryLocalCacheQuery,
+  saveTableIfInsideCacheContext,
 } from "../../../utils/cacheContextUtils";
-import {BuildQueryConfig, isSQLWrapper, SQLWrapper} from "drizzle-orm/sql/sql";
-import type {MySqlQueryResultKind} from "drizzle-orm/mysql-core/session";
-import {getTableColumns, Query} from "drizzle-orm";
-import {MySqlDialect} from "drizzle-orm/mysql-core/dialect";
-import type {GetSelectTableName, GetSelectTableSelection} from "drizzle-orm/query-builders/select.types";
+import { BuildQueryConfig, isSQLWrapper, SQLWrapper } from "drizzle-orm/sql/sql";
+import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
+import { getTableColumns, Query } from "drizzle-orm";
+import { MySqlDialect } from "drizzle-orm/mysql-core/dialect";
+import type {
+  GetSelectTableName,
+  GetSelectTableSelection,
+} from "drizzle-orm/query-builders/select.types";
 
 // ============================================================================
 // TYPES AND INTERFACES
@@ -40,35 +47,22 @@ interface QueryBuilder {
 /**
  * Error codes that should not trigger cache clearing
  */
-const NON_CACHE_CLEARING_ERROR_CODES = [
-  "VALIDATION_ERROR",
-  "CONSTRAINT_ERROR"
-] as const;
+const NON_CACHE_CLEARING_ERROR_CODES = ["VALIDATION_ERROR", "CONSTRAINT_ERROR"] as const;
 
 /**
  * Error codes that should trigger cache clearing
  */
-const CACHE_CLEARING_ERROR_CODES = [
-  "DEADLOCK",
-  "LOCK_WAIT_TIMEOUT", 
-  "CONNECTION_ERROR"
-] as const;
+const CACHE_CLEARING_ERROR_CODES = ["DEADLOCK", "LOCK_WAIT_TIMEOUT", "CONNECTION_ERROR"] as const;
 
 /**
  * Error message patterns that should not trigger cache clearing
  */
-const NON_CACHE_CLEARING_PATTERNS = [
-  /validation/i,
-  /constraint/i
-] as const;
+const NON_CACHE_CLEARING_PATTERNS = [/validation/i, /constraint/i] as const;
 
 /**
  * Error message patterns that should trigger cache clearing
  */
-const CACHE_CLEARING_PATTERNS = [
-  /timeout/i,
-  /connection/i
-] as const;
+const CACHE_CLEARING_PATTERNS = [/timeout/i, /connection/i] as const;
 
 // ============================================================================
 // CACHE MANAGEMENT UTILITIES
@@ -87,7 +81,10 @@ function shouldClearCacheOnError(error: any): boolean {
     return false;
   }
 
-  if (error?.message && NON_CACHE_CLEARING_PATTERNS.some(pattern => pattern.test(error.message))) {
+  if (
+    error?.message &&
+    NON_CACHE_CLEARING_PATTERNS.some((pattern) => pattern.test(error.message))
+  ) {
     return false;
   }
 
@@ -96,7 +93,7 @@ function shouldClearCacheOnError(error: any): boolean {
     return true;
   }
 
-  if (error?.message && CACHE_CLEARING_PATTERNS.some(pattern => pattern.test(error.message))) {
+  if (error?.message && CACHE_CLEARING_PATTERNS.some((pattern) => pattern.test(error.message))) {
     return true;
   }
 
@@ -142,41 +139,82 @@ export type SelectAliasedDistinctCacheableType = <TSelection extends SelectedFie
  * Type for select queries from table with field aliasing
  */
 export type SelectAllFromAliasedType = <T extends MySqlTable>(
-    table: T,
-) =>  MySqlSelectBase<GetSelectTableName<T>, T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"], T["_"]["columns"] extends undefined ? "single" : "partial", MySqlRemotePreparedQueryHKT, GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {}, false, never, any>;
+  table: T,
+) => MySqlSelectBase<
+  GetSelectTableName<T>,
+  T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
+  T["_"]["columns"] extends undefined ? "single" : "partial",
+  MySqlRemotePreparedQueryHKT,
+  GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
+  false,
+  never,
+  any
+>;
 
 /**
  * Type for select distinct queries from table with field aliasing
  */
 export type SelectAllDistinctFromAliasedType = <T extends MySqlTable>(
-    table: T,
-) => MySqlSelectBase<GetSelectTableName<T>, T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"], T["_"]["columns"] extends undefined ? "single" : "partial", MySqlRemotePreparedQueryHKT, GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {}, false, never, any>;
+  table: T,
+) => MySqlSelectBase<
+  GetSelectTableName<T>,
+  T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
+  T["_"]["columns"] extends undefined ? "single" : "partial",
+  MySqlRemotePreparedQueryHKT,
+  GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
+  false,
+  never,
+  any
+>;
 
 /**
  * Type for select queries from table with field aliasing and caching
  */
 export type SelectAllFromCacheableAliasedType = <T extends MySqlTable>(
-    table: T,
-    cacheTtl?: number,
-) => MySqlSelectBase<GetSelectTableName<T>, T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"], T["_"]["columns"] extends undefined ? "single" : "partial", MySqlRemotePreparedQueryHKT, GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {}, false, never, any>;
+  table: T,
+  cacheTtl?: number,
+) => MySqlSelectBase<
+  GetSelectTableName<T>,
+  T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
+  T["_"]["columns"] extends undefined ? "single" : "partial",
+  MySqlRemotePreparedQueryHKT,
+  GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
+  false,
+  never,
+  any
+>;
 
 /**
  * Type for select distinct queries from table with field aliasing and caching
  */
 export type SelectAllDistinctFromCacheableAliasedType = <T extends MySqlTable>(
-    table: T,
-    cacheTtl?: number,
-) => MySqlSelectBase<GetSelectTableName<T>, T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"], T["_"]["columns"] extends undefined ? "single" : "partial", MySqlRemotePreparedQueryHKT, GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {}, false, never, any>;
+  table: T,
+  cacheTtl?: number,
+) => MySqlSelectBase<
+  GetSelectTableName<T>,
+  T["_"]["columns"] extends undefined ? GetSelectTableSelection<T> : T["_"]["columns"],
+  T["_"]["columns"] extends undefined ? "single" : "partial",
+  MySqlRemotePreparedQueryHKT,
+  GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
+  false,
+  never,
+  any
+>;
 
 /**
  * Type for executing raw SQL queries with local cache
  */
-export type ExecuteQuery = (query: SQLWrapper | string) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+export type ExecuteQuery = (
+  query: SQLWrapper | string,
+) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
 
 /**
  * Type for executing raw SQL queries with local and global cache
  */
-export type ExecuteQueryCacheable = (query: SQLWrapper | string, cacheTtl?: number) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+export type ExecuteQueryCacheable = (
+  query: SQLWrapper | string,
+  cacheTtl?: number,
+) => Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
 
 /**
  * Type for insert operations with cache eviction
@@ -229,8 +267,8 @@ async function handleSuccessfulExecution(
     if (shouldClearCacheOnError(error)) {
       await evictLocalCacheQuery(table, options);
       if (isCached) {
-        await clearCache(table, options).catch(() => {
-          console.warn("Ignore cache clear errors");
+        await clearCache(table, options).catch((e) => {
+          console.warn("Ignore cache clear errors", e);
         });
       } else {
         await saveTableIfInsideCacheContext(table);
@@ -406,7 +444,7 @@ async function handleCachedQuery(
   onrejected?: any,
 ): Promise<any> {
   try {
-    const localCached = await getQueryLocalCacheQuery(target);
+    const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
       return onfulfilled?.(localCached);
     }
@@ -416,7 +454,7 @@ async function handleCachedQuery(
     }
     const rows = await target.execute();
     const transformed = applyFromDriverTransform(rows, selections, aliasMap);
-    await saveQueryLocalCacheQuery(target, transformed);
+    await saveQueryLocalCacheQuery(target, transformed, options);
     await setCacheResult(target, options, transformed, cacheTtl).catch((cacheError) => {
       // Log cache error but don't fail the query
       console.warn("Cache set error:", cacheError);
@@ -432,6 +470,7 @@ async function handleCachedQuery(
  * Handles non-cached query execution.
  *
  * @param target - The query target
+ * @param options - ForgeSQL ORM options
  * @param selections - Field selections
  * @param aliasMap - Field alias mapping
  * @param onfulfilled - Success callback
@@ -440,19 +479,20 @@ async function handleCachedQuery(
  */
 async function handleNonCachedQuery(
   target: any,
+  options: any,
   selections: any,
   aliasMap: any,
   onfulfilled?: any,
   onrejected?: any,
 ): Promise<any> {
   try {
-    const localCached = await getQueryLocalCacheQuery(target);
+    const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
       return onfulfilled?.(localCached);
     }
     const rows = await target.execute();
     const transformed = applyFromDriverTransform(rows, selections, aliasMap);
-    await saveQueryLocalCacheQuery(target, transformed);
+    await saveQueryLocalCacheQuery(target, transformed, options);
     return onfulfilled?.(transformed);
   } catch (error) {
     return onrejected?.(error);
@@ -505,7 +545,14 @@ function createAliasedSelectBuilder<TSelection extends SelectedFields>(
                 onrejected,
               );
             } else {
-              return handleNonCachedQuery(target, selections, aliasMap, onfulfilled, onrejected);
+              return handleNonCachedQuery(
+                target,
+                options,
+                selections,
+                aliasMap,
+                onfulfilled,
+                onrejected,
+              );
             }
           };
         }
@@ -553,34 +600,36 @@ const DEFAULT_OPTIONS: ForgeSqlOrmOptions = {
 // QUERY BUILDER FACTORIES
 // ============================================================================
 
-
 /**
  * Creates a raw SQL query executor with caching support
  */
 function createRawQueryExecutor(
   db: MySqlRemoteDatabase<any>,
   options: ForgeSqlOrmOptions,
-  useGlobalCache: boolean = false
+  useGlobalCache: boolean = false,
 ) {
   return async function <T extends { [column: string]: any }>(
     query: SQLWrapper | string,
-    cacheTtl?: number
+    cacheTtl?: number,
   ): Promise<MySqlRawQueryResult> {
     let sql: Query;
-    
+
     if (isSQLWrapper(query)) {
       const sqlWrapper = query as SQLWrapper;
-      sql = sqlWrapper.getSQL()
-        .toQuery(((db as unknown as { dialect: MySqlDialect }).dialect) as unknown as BuildQueryConfig);
+      sql = sqlWrapper
+        .getSQL()
+        .toQuery(
+          (db as unknown as { dialect: MySqlDialect }).dialect as unknown as BuildQueryConfig,
+        );
     } else {
       sql = {
         sql: query,
-        params: []
+        params: [],
       };
     }
 
     // Check local cache first
-    const localCacheResult = await getQueryLocalCacheQuery(sql);
+    const localCacheResult = await getQueryLocalCacheQuery(sql, options);
     if (localCacheResult) {
       return localCacheResult as MySqlRawQueryResult;
     }
@@ -595,20 +644,20 @@ function createRawQueryExecutor(
 
     // Execute query
     const results = await db.execute<T>(query);
-    
+
     // Save to local cache
-    await saveQueryLocalCacheQuery(sql, results);
-    
+    await saveQueryLocalCacheQuery(sql, results, options);
+
     // Save to global cache if enabled
     if (useGlobalCache) {
       await setCacheResult(
-        { toSQL: () => sql }, 
-        options, 
-        results, 
-        cacheTtl ?? options.cacheTTL ?? 120
+        { toSQL: () => sql },
+        options,
+        results,
+        cacheTtl ?? options.cacheTTL ?? 120,
       );
     }
-    
+
     return results;
   };
 }
@@ -821,7 +870,7 @@ export function patchDbWithSelectAliased(
    * ```typescript
    * // Using SQLWrapper
    * const result = await db.executeQuery(sql`SELECT * FROM users WHERE id = ${userId}`);
-   * 
+   *
    * // Using string
    * const result = await db.executeQuery("SELECT * FROM users WHERE status = 'active'");
    * ```
@@ -841,7 +890,7 @@ export function patchDbWithSelectAliased(
    * ```typescript
    * // Using SQLWrapper with custom TTL
    * const result = await db.executeQueryCacheable(sql`SELECT * FROM users WHERE id = ${userId}`, 300);
-   * 
+   *
    * // Using string with default TTL
    * const result = await db.executeQueryCacheable("SELECT * FROM users WHERE status = 'active'");
    * ```

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

@@ -1,12 +1,17 @@
 import {
-    DeleteAndEvictCacheType, ExecuteQuery, ExecuteQueryCacheable,
-    InsertAndEvictCacheType,
-    SelectAliasedCacheableType,
-    SelectAliasedDistinctCacheableType,
-    SelectAliasedDistinctType,
-    SelectAliasedType, SelectAllDistinctFromAliasedType,
-    SelectAllDistinctFromCacheableAliasedType, SelectAllFromAliasedType, SelectAllFromCacheableAliasedType,
-    UpdateAndEvictCacheType,
+  DeleteAndEvictCacheType,
+  ExecuteQuery,
+  ExecuteQueryCacheable,
+  InsertAndEvictCacheType,
+  SelectAliasedCacheableType,
+  SelectAliasedDistinctCacheableType,
+  SelectAliasedDistinctType,
+  SelectAliasedType,
+  SelectAllDistinctFromAliasedType,
+  SelectAllDistinctFromCacheableAliasedType,
+  SelectAllFromAliasedType,
+  SelectAllFromCacheableAliasedType,
+  UpdateAndEvictCacheType,
 } from "./additionalActions";
 
 declare module "drizzle-orm/mysql-proxy" {
@@ -25,7 +30,7 @@ declare module "drizzle-orm/mysql-proxy" {
      * Select with field aliasing support for all table columns
      */
     selectFrom: SelectAllFromAliasedType;
-    
+
     /**
      * Select distinct with field aliasing support for all table columns
      */
@@ -50,12 +55,12 @@ declare module "drizzle-orm/mysql-proxy" {
      * Select with field aliasing and caching support for all table columns
      */
     selectFromCacheable: SelectAllFromCacheableAliasedType;
-    
+
     /**
      * Select distinct with field aliasing and caching support for all table columns
      */
     selectDistinctFromCacheable: SelectAllDistinctFromCacheableAliasedType;
-    
+
     /**
      * Execute raw SQL query with both local and global cache support
      */

package/src/utils/cacheContextUtils.ts

@@ -78,6 +78,7 @@ export async function saveTableIfInsideCacheContext<T extends AnyMySqlTable>(
  *
  * @param query - The Drizzle query to cache
  * @param rows - The query result data to cache
+ * @param options - ForgeSqlOrm options
  * @returns Promise that resolves when the data is saved to local cache
  *
  * @example
@@ -89,7 +90,7 @@ export async function saveTableIfInsideCacheContext<T extends AnyMySqlTable>(
  */
 export async function saveQueryLocalCacheQuery<
   T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>,
->(query: T, rows: unknown[]): Promise<void> {
+>(query: T, rows: unknown[], options: ForgeSqlOrmOptions): Promise<void> {
   const context = localCacheApplicationContext.getStore();
   if (context) {
     if (!context.cache) {
@@ -101,6 +102,12 @@ export async function saveQueryLocalCacheQuery<
       sql: sql.toSQL().sql.toLowerCase(),
       data: rows,
     };
+    if (options.logRawSqlQuery) {
+      const q = sql.toSQL();
+      console.debug(
+        `[forge-sql-orm][local-cache][SAVE] Stored result in cache. sql="${q.sql}", params=${JSON.stringify(q.params)}`,
+      );
+    }
   }
 }
 
@@ -109,6 +116,7 @@ export async function saveQueryLocalCacheQuery<
  * This function checks if a query result is already cached in memory.
  *
  * @param query - The Drizzle query to check for cached results
+ * @param options - Option Property
  * @returns Promise that resolves to cached data if found, undefined otherwise
  *
  * @example
@@ -123,7 +131,7 @@ export async function saveQueryLocalCacheQuery<
  */
 export async function getQueryLocalCacheQuery<
   T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>,
->(query: T): Promise<unknown[] | undefined> {
+>(query: T, options: ForgeSqlOrmOptions): Promise<unknown[] | undefined> {
   const context = localCacheApplicationContext.getStore();
   if (context) {
     if (!context.cache) {
@@ -132,14 +140,18 @@ export async function getQueryLocalCacheQuery<
     const sql = query as { toSQL: () => Query };
     const key = hashKey(sql.toSQL());
     if (context.cache[key] && context.cache[key].sql === sql.toSQL().sql.toLowerCase()) {
+      if (options.logRawSqlQuery) {
+        const q = sql.toSQL();
+        console.debug(
+          `[forge-sql-orm][local-cache][HIT] Returned cached result. sql="${q.sql}", params=${JSON.stringify(q.params)}`,
+        );
+      }
       return context.cache[key].data;
     }
   }
   return undefined;
 }
 
-
-
 /**
  * Evicts cached queries from the local cache context that involve the specified table.
  * This function removes cached query results that contain the given table name.

package/src/utils/cacheUtils.ts

@@ -287,7 +287,9 @@ export async function clearExpiredCache(options: ForgeSqlOrmOptions): Promise<vo
     );
   } finally {
     const duration = DateTime.now().toSeconds() - startTime.toSeconds();
-    console.info(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
+    if (options?.logRawSqlQuery) {
+      console.debug(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
+    }
   }
 }
 

package/src/utils/forgeDriver.ts

@@ -13,27 +13,22 @@ export const forgeDriver = async (
   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 };
+  if (method == "execute") {
+    const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
+    if (params) {
+      sqlStatement.bindParams(...params);
     }
-  } catch (error) {
-    console.error("SQL Error:", JSON.stringify(error));
-    throw error;
+    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 };
   }
 };

package/src/utils/forgeDriverProxy.ts

@@ -19,9 +19,16 @@ export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: bool
     const modifiedQuery = injectSqlHints(query, options);
 
     if (options && logRawSqlQuery && modifiedQuery !== query) {
-      console.warn("modified query: " + modifiedQuery);
+      console.debug("injected Hints: " + modifiedQuery);
+    }
+    try {
+      // Call the original forgeDriver with the modified query
+      return await forgeDriver(modifiedQuery, params, method);
+    } catch (error) {
+      if (logRawSqlQuery) {
+        console.debug("SQL Error:", JSON.stringify(error));
+      }
+      throw error;
     }
-    // Call the original forgeDriver with the modified query
-    return forgeDriver(modifiedQuery, params, method);
   };
 }