forge-sql-orm 2.1.22 → 2.1.24

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

@@ -1,3 +1,4 @@
+// qlty-ignore: +qlty:file-complexity
 import {
   MySqlRawQueryResult,
   MySqlRemoteDatabase,
@@ -6,7 +7,12 @@ import {
 } from "drizzle-orm/mysql-proxy";
 
 import { SelectedFields } from "drizzle-orm/mysql-core/query-builders/select.types";
-import { applyFromDriverTransform, ForgeSqlOrmOptions, mapSelectFieldsWithAlias } from "../../..";
+import {
+  applyFromDriverTransform,
+  ForgeSqlOrmOptions,
+  mapSelectFieldsWithAlias,
+  SelectFromReturnType,
+} from "../../..";
 import { MySqlSelectBase, MySqlSelectBuilder } from "drizzle-orm/mysql-core";
 import { MySqlTable } from "drizzle-orm/mysql-core/table";
 import {
@@ -308,25 +314,26 @@ async function handleSuccessfulExecution(
   }
 }
 
+/**
+ * Configuration for function call handling.
+ */
+interface FunctionCallConfig {
+  value: Function;
+  target: any;
+  args: any[];
+  table: MySqlTable;
+  options: ForgeSqlOrmOptions;
+  isCached: boolean;
+}
+
 /**
  * Handles function calls on the wrapped builder.
  *
- * @param value - The function to call
- * @param target - The target object
- * @param args - Function arguments
- * @param table - The table being modified
- * @param options - ForgeSQL ORM options
- * @param isCached - Whether to clear cache immediately
+ * @param config - Configuration for function call handling
  * @returns Function result or wrapped builder
  */
-function handleFunctionCall(
-  value: Function,
-  target: any,
-  args: any[],
-  table: MySqlTable,
-  options: ForgeSqlOrmOptions,
-  isCached: boolean,
-): any {
+function handleFunctionCall(config: FunctionCallConfig): any {
+  const { value, target, args, table, options, isCached } = config;
   const result = value.apply(target, args);
   if (typeof result === "object" && result !== null && "execute" in result) {
     return wrapCacheEvictBuilder(result as QueryBuilder, table, options, isCached);
@@ -367,7 +374,14 @@ const wrapCacheEvictBuilder = <TTable extends MySqlTable>(
 
       if (typeof value === "function") {
         return (...args: any[]) =>
-          handleFunctionCall(value, target, args, table, options, isCached);
+          handleFunctionCall({
+            value,
+            target,
+            args,
+            table,
+            options,
+            isCached,
+          });
       }
 
       return value;
@@ -375,6 +389,19 @@ const wrapCacheEvictBuilder = <TTable extends MySqlTable>(
   });
 };
 
+/**
+ * Creates a query builder with cache eviction wrapper.
+ * Generic helper to reduce duplication between insert/update/delete builders.
+ */
+function createCacheEvictBuilder<TTable extends MySqlTable, TBuilder>(
+  builder: QueryBuilder,
+  table: TTable,
+  options: ForgeSqlOrmOptions,
+  isCached: boolean,
+): TBuilder {
+  return wrapCacheEvictBuilder(builder, table, options, isCached) as unknown as TBuilder;
+}
+
 /**
  * Creates an insert query builder that automatically evicts cache after execution.
  *
@@ -390,16 +417,10 @@ function insertAndEvictCacheBuilder<TTable extends MySqlTable>(
   isCached: boolean,
 ): MySqlInsertBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
   const builder = db.insert(table);
-  return wrapCacheEvictBuilder(
-    builder as unknown as QueryBuilder,
-    table,
-    options,
-    isCached,
-  ) as unknown as MySqlInsertBuilder<
+  return createCacheEvictBuilder<
     TTable,
-    MySqlRemoteQueryResultHKT,
-    MySqlRemotePreparedQueryHKT
-  >;
+    MySqlInsertBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>
+  >(builder as unknown as QueryBuilder, table, options, isCached);
 }
 
 /**
@@ -417,16 +438,10 @@ function updateAndEvictCacheBuilder<TTable extends MySqlTable>(
   isCached: boolean,
 ): MySqlUpdateBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
   const builder = db.update(table);
-  return wrapCacheEvictBuilder(
-    builder as unknown as QueryBuilder,
-    table,
-    options,
-    isCached,
-  ) as unknown as MySqlUpdateBuilder<
+  return createCacheEvictBuilder<
     TTable,
-    MySqlRemoteQueryResultHKT,
-    MySqlRemotePreparedQueryHKT
-  >;
+    MySqlUpdateBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>
+  >(builder as unknown as QueryBuilder, table, options, isCached);
 }
 
 /**
@@ -444,35 +459,33 @@ function deleteAndEvictCacheBuilder<TTable extends MySqlTable>(
   isCached: boolean,
 ): MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
   const builder = db.delete(table);
-  return wrapCacheEvictBuilder(
-    builder as unknown as QueryBuilder,
-    table,
-    options,
-    isCached,
-  ) as unknown as MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+  return createCacheEvictBuilder<
+    TTable,
+    MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>
+  >(builder as unknown as QueryBuilder, table, options, isCached);
+}
+
+/**
+ * Configuration for cached query handling.
+ */
+interface CachedQueryConfig {
+  target: any;
+  options: ForgeSqlOrmOptions;
+  cacheTtl: number;
+  selections: any;
+  aliasMap: any;
+  onfulfilled?: any;
+  onrejected?: any;
 }
 
 /**
  * Handles cached query execution with proper error handling.
  *
- * @param target - The query target
- * @param options - ForgeSQL ORM options
- * @param cacheTtl - Cache TTL
- * @param selections - Field selections
- * @param aliasMap - Field alias mapping
- * @param onfulfilled - Success callback
- * @param onrejected - Error callback
+ * @param config - Configuration for cached query handling
  * @returns Promise with cached result
  */
-async function handleCachedQuery(
-  target: any,
-  options: ForgeSqlOrmOptions,
-  cacheTtl: number,
-  selections: any,
-  aliasMap: any,
-  onfulfilled?: any,
-  onrejected?: any,
-): Promise<any> {
+async function handleCachedQuery(config: CachedQueryConfig): Promise<any> {
+  const { target, options, cacheTtl, selections, aliasMap, onfulfilled, onrejected } = config;
   try {
     const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
@@ -500,25 +513,26 @@ async function handleCachedQuery(
   }
 }
 
+/**
+ * Configuration for non-cached query handling.
+ */
+interface NonCachedQueryConfig {
+  target: any;
+  options: any;
+  selections: any;
+  aliasMap: any;
+  onfulfilled?: any;
+  onrejected?: any;
+}
+
 /**
  * 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
- * @param onrejected - Error callback
+ * @param config - Configuration for non-cached query handling
  * @returns Promise with transformed result
  */
-async function handleNonCachedQuery(
-  target: any,
-  options: any,
-  selections: any,
-  aliasMap: any,
-  onfulfilled?: any,
-  onrejected?: any,
-): Promise<any> {
+async function handleNonCachedQuery(config: NonCachedQueryConfig): Promise<any> {
+  const { target, options, selections, aliasMap, onfulfilled, onrejected } = config;
   try {
     const localCached = await getQueryLocalCacheQuery(target, options);
     if (localCached) {
@@ -577,7 +591,15 @@ function createCachedThenHandler(
 ): (onfulfilled?: any, onrejected?: any) => Promise<any> {
   return (onfulfilled?: any, onrejected?: any) => {
     const ttl = cacheTtl ?? options.cacheTTL ?? 120;
-    return handleCachedQuery(target, options, ttl, selections, aliasMap, onfulfilled, onrejected);
+    return handleCachedQuery({
+      target,
+      options,
+      cacheTtl: ttl,
+      selections,
+      aliasMap,
+      onfulfilled,
+      onrejected,
+    });
   };
 }
 
@@ -591,7 +613,14 @@ function createNonCachedThenHandler(
   aliasMap: any,
 ): (onfulfilled?: any, onrejected?: any) => Promise<any> {
   return (onfulfilled?: any, onrejected?: any) => {
-    return handleNonCachedQuery(target, options, selections, aliasMap, onfulfilled, onrejected);
+    return handleNonCachedQuery({
+      target,
+      options,
+      selections,
+      aliasMap,
+      onfulfilled,
+      onrejected,
+    });
   };
 }
 
@@ -637,47 +666,83 @@ function createFunctionCallHandler(
  * @param cacheTtl - Optional cache TTL override
  * @returns Select query builder with aliasing and optional caching
  */
+/**
+ * Configuration for aliased select proxy handler.
+ */
+interface AliasedSelectProxyConfig {
+  selections: any;
+  aliasMap: any;
+  useCache: boolean;
+  options: ForgeSqlOrmOptions;
+  cacheTtl: number | undefined;
+  wrapBuilder: (rawBuilder: any) => any;
+}
+
+/**
+ * Creates a Proxy handler for aliased select builders.
+ */
+function createAliasedSelectProxyHandler(config: AliasedSelectProxyConfig) {
+  const { selections, aliasMap, useCache, options, cacheTtl, wrapBuilder } = config;
+  return {
+    get(target: any, prop: string | symbol, receiver: any) {
+      // Handle 'then' separately to avoid thenable object issues
+      if (prop === "then") {
+        return useCache
+          ? createCachedThenHandler(target, options, cacheTtl, selections, aliasMap)
+          : createNonCachedThenHandler(target, options, selections, aliasMap);
+      }
+
+      // Handle other special properties with a map
+      const specialHandlers: Record<string | symbol, () => any> = {
+        execute: () => createExecuteHandler(target, selections, aliasMap),
+        catch: () => createCatchHandler(receiver),
+        finally: () => createFinallyHandler(receiver),
+      };
+
+      if (prop in specialHandlers) {
+        return specialHandlers[prop]();
+      }
+
+      const value = Reflect.get(target, prop, receiver);
+
+      if (typeof value === "function") {
+        return createFunctionCallHandler(value, target, wrapBuilder);
+      }
+
+      return value;
+    },
+  };
+}
+
+/**
+ * Configuration for creating aliased select builder.
+ */
+interface AliasedSelectBuilderConfig<TSelection extends SelectedFields> {
+  db: MySqlRemoteDatabase<any>;
+  fields: TSelection;
+  selectFn: (selections: any) => MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+  useCache: boolean;
+  options: ForgeSqlOrmOptions;
+  cacheTtl?: number;
+}
+
 function createAliasedSelectBuilder<TSelection extends SelectedFields>(
-  db: MySqlRemoteDatabase<any>,
-  fields: TSelection,
-  selectFn: (selections: any) => MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>,
-  useCache: boolean,
-  options: ForgeSqlOrmOptions,
-  cacheTtl?: number,
+  config: AliasedSelectBuilderConfig<TSelection>,
 ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT> {
+  const { fields, selectFn, useCache, options, cacheTtl } = config;
   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 createExecuteHandler(target, selections, aliasMap);
-        }
-
-        if (prop === "then") {
-          return useCache
-            ? createCachedThenHandler(target, options, cacheTtl, selections, aliasMap)
-            : createNonCachedThenHandler(target, options, selections, aliasMap);
-        }
-
-        if (prop === "catch") {
-          return createCatchHandler(receiver);
-        }
-
-        if (prop === "finally") {
-          return createFinallyHandler(receiver);
-        }
-
-        const value = Reflect.get(target, prop, receiver);
-
-        if (typeof value === "function") {
-          return createFunctionCallHandler(value, target, wrapBuilder);
-        }
-
-        return value;
-      },
+    const handler = createAliasedSelectProxyHandler({
+      selections,
+      aliasMap,
+      useCache,
+      options,
+      cacheTtl,
+      wrapBuilder,
     });
+    return new Proxy(rawBuilder, handler);
   };
 
   return wrapBuilder(builder);
@@ -763,55 +828,25 @@ function createRawQueryExecutor(
 }
 
 // ============================================================================
-// MAIN PATCH FUNCTION
+// HELPER FUNCTIONS FOR PATCHING
 // ============================================================================
 
 /**
- * Patches a Drizzle database instance with additional methods for aliased selects and cache management.
- *
- * This function extends the database instance with:
- * - selectAliased: Select with field aliasing support
- * - selectAliasedDistinct: Select distinct with field aliasing support
- * - selectAliasedCacheable: Select with field aliasing and caching
- * - selectAliasedDistinctCacheable: Select distinct with field aliasing and caching
- * - insertAndEvictCache: Insert operations that automatically evict cache
- * - updateAndEvictCache: Update operations that automatically evict cache
- * - deleteAndEvictCache: Delete operations that automatically evict cache
- *
- * @param db - The Drizzle database instance to patch
- * @param options - Optional ForgeSQL ORM configuration
- * @returns The patched database instance with additional methods
+ * Sets up select methods with field aliasing.
  */
-export function patchDbWithSelectAliased(
+function setupSelectAliasedMethods(
   db: MySqlRemoteDatabase<any>,
-  options?: ForgeSqlOrmOptions,
-): MySqlRemoteDatabase<any> & {
-  selectAliased: SelectAliasedType;
-  selectAliasedDistinct: SelectAliasedDistinctType;
-  selectAliasedCacheable: SelectAliasedCacheableType;
-  selectAliasedDistinctCacheable: SelectAliasedDistinctCacheableType;
-  insertWithCacheContext: InsertAndEvictCacheType;
-  insertAndEvictCache: InsertAndEvictCacheType;
-  updateAndEvictCache: UpdateAndEvictCacheType;
-  updateWithCacheContext: UpdateAndEvictCacheType;
-  deleteAndEvictCache: DeleteAndEvictCacheType;
-  deleteWithCacheContext: DeleteAndEvictCacheType;
-} {
-  const newOptions = { ...DEFAULT_OPTIONS, ...options };
-
-  // ============================================================================
-  // SELECT METHODS WITH FIELD ALIASING
-  // ============================================================================
-
+  newOptions: ForgeSqlOrmOptions,
+): void {
   // Select aliased without cache
   db.selectAliased = function <TSelection extends SelectedFields>(fields: TSelection) {
-    return createAliasedSelectBuilder(
+    return createAliasedSelectBuilder({
       db,
       fields,
-      (selections) => db.select(selections),
-      false,
-      newOptions,
-    );
+      selectFn: (selections) => db.select(selections),
+      useCache: false,
+      options: newOptions,
+    });
   };
 
   // Select aliased with cache
@@ -819,25 +854,25 @@ export function patchDbWithSelectAliased(
     fields: TSelection,
     cacheTtl?: number,
   ) {
-    return createAliasedSelectBuilder(
+    return createAliasedSelectBuilder({
       db,
       fields,
-      (selections) => db.select(selections),
-      true,
-      newOptions,
+      selectFn: (selections) => db.select(selections),
+      useCache: true,
+      options: newOptions,
       cacheTtl,
-    );
+    });
   };
 
   // Select aliased distinct without cache
   db.selectAliasedDistinct = function <TSelection extends SelectedFields>(fields: TSelection) {
-    return createAliasedSelectBuilder(
+    return createAliasedSelectBuilder({
       db,
       fields,
-      (selections) => db.selectDistinct(selections),
-      false,
-      newOptions,
-    );
+      selectFn: (selections) => db.selectDistinct(selections),
+      useCache: false,
+      options: newOptions,
+    });
   };
 
   // Select aliased distinct with cache
@@ -845,20 +880,21 @@ export function patchDbWithSelectAliased(
     fields: TSelection,
     cacheTtl?: number,
   ) {
-    return createAliasedSelectBuilder(
+    return createAliasedSelectBuilder({
       db,
       fields,
-      (selections) => db.selectDistinct(selections),
-      true,
-      newOptions,
+      selectFn: (selections) => db.selectDistinct(selections),
+      useCache: true,
+      options: newOptions,
       cacheTtl,
-    );
+    });
   };
+}
 
-  // ============================================================================
-  // TABLE-BASED SELECT METHODS
-  // ============================================================================
-
+/**
+ * Sets up table-based select methods.
+ */
+function setupTableBasedSelectMethods(db: MySqlRemoteDatabase<any>): void {
   /**
    * Creates a select query builder for all columns from a table with field aliasing support.
    * This is a convenience method that automatically selects all columns from the specified table.
@@ -870,52 +906,10 @@ export function patchDbWithSelectAliased(
    * const users = await db.selectFrom(userTable).where(eq(userTable.id, 1));
    * ```
    */
-  db.selectFrom = function <T extends MySqlTable>(
-    table: T,
-  ): MySqlSelectBase<
-    GetSelectTableName<T>,
-    GetSelectTableSelection<T>,
-    "single",
-    MySqlRemotePreparedQueryHKT,
-    GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
-    false,
-    never,
-    {
-      [K in keyof {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }]: {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }[K];
-    }[],
-    any
-  > {
-    return db.selectAliased(getTableColumns(table)).from(table) as unknown as MySqlSelectBase<
-      GetSelectTableName<T>,
-      GetSelectTableSelection<T>,
-      "single",
-      MySqlRemotePreparedQueryHKT,
-      GetSelectTableName<T> extends string
-        ? Record<string & GetSelectTableName<T>, "not-null">
-        : {},
-      false,
-      never,
-      {
-        [K in keyof {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }]: {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }[K];
-      }[],
-      any
-    >;
+  db.selectFrom = function <T extends MySqlTable>(table: T): SelectFromReturnType<T> {
+    return db
+      .selectAliased(getTableColumns(table))
+      .from(table) as unknown as SelectFromReturnType<T>;
   };
 
   /**
@@ -933,52 +927,10 @@ export function patchDbWithSelectAliased(
   db.selectFromCacheable = function <T extends MySqlTable>(
     table: T,
     cacheTtl?: number,
-  ): MySqlSelectBase<
-    GetSelectTableName<T>,
-    GetSelectTableSelection<T>,
-    "single",
-    MySqlRemotePreparedQueryHKT,
-    GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
-    false,
-    never,
-    {
-      [K in keyof {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }]: {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }[K];
-    }[],
-    any
-  > {
+  ): SelectFromReturnType<T> {
     return db
       .selectAliasedCacheable(getTableColumns(table), cacheTtl)
-      .from(table) as unknown as MySqlSelectBase<
-      GetSelectTableName<T>,
-      GetSelectTableSelection<T>,
-      "single",
-      MySqlRemotePreparedQueryHKT,
-      GetSelectTableName<T> extends string
-        ? Record<string & GetSelectTableName<T>, "not-null">
-        : {},
-      false,
-      never,
-      {
-        [K in keyof {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }]: {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }[K];
-      }[],
-      any
-    >;
+      .from(table) as unknown as SelectFromReturnType<T>;
   };
 
   /**
@@ -992,54 +944,10 @@ export function patchDbWithSelectAliased(
    * const uniqueUsers = await db.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
    * ```
    */
-  db.selectDistinctFrom = function <T extends MySqlTable>(
-    table: T,
-  ): MySqlSelectBase<
-    GetSelectTableName<T>,
-    GetSelectTableSelection<T>,
-    "single",
-    MySqlRemotePreparedQueryHKT,
-    GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
-    false,
-    never,
-    {
-      [K in keyof {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }]: {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }[K];
-    }[],
-    any
-  > {
+  db.selectDistinctFrom = function <T extends MySqlTable>(table: T): SelectFromReturnType<T> {
     return db
       .selectAliasedDistinct(getTableColumns(table))
-      .from(table) as unknown as MySqlSelectBase<
-      GetSelectTableName<T>,
-      GetSelectTableSelection<T>,
-      "single",
-      MySqlRemotePreparedQueryHKT,
-      GetSelectTableName<T> extends string
-        ? Record<string & GetSelectTableName<T>, "not-null">
-        : {},
-      false,
-      never,
-      {
-        [K in keyof {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }]: {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }[K];
-      }[],
-      any
-    >;
+      .from(table) as unknown as SelectFromReturnType<T>;
   };
 
   /**
@@ -1057,92 +965,46 @@ export function patchDbWithSelectAliased(
   db.selectDistinctFromCacheable = function <T extends MySqlTable>(
     table: T,
     cacheTtl?: number,
-  ): MySqlSelectBase<
-    GetSelectTableName<T>,
-    GetSelectTableSelection<T>,
-    "single",
-    MySqlRemotePreparedQueryHKT,
-    GetSelectTableName<T> extends string ? Record<string & GetSelectTableName<T>, "not-null"> : {},
-    false,
-    never,
-    {
-      [K in keyof {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }]: {
-        [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-          GetSelectTableSelection<T>[Key]
-        >;
-      }[K];
-    }[],
-    any
-  > {
+  ): SelectFromReturnType<T> {
     return db
       .selectAliasedDistinctCacheable(getTableColumns(table), cacheTtl)
-      .from(table) as unknown as MySqlSelectBase<
-      GetSelectTableName<T>,
-      GetSelectTableSelection<T>,
-      "single",
-      MySqlRemotePreparedQueryHKT,
-      GetSelectTableName<T> extends string
-        ? Record<string & GetSelectTableName<T>, "not-null">
-        : {},
-      false,
-      never,
-      {
-        [K in keyof {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }]: {
-          [Key in keyof GetSelectTableSelection<T>]: SelectResultField<
-            GetSelectTableSelection<T>[Key]
-          >;
-        }[K];
-      }[],
-      any
-    >;
-  };
-
-  // ============================================================================
-  // CACHE-AWARE MODIFY OPERATIONS
-  // ============================================================================
-
-  // Insert with cache context support (participates in cache clearing when used within cache context)
-  db.insertWithCacheContext = function <TTable extends MySqlTable>(table: TTable) {
-    return insertAndEvictCacheBuilder(db, table, newOptions, false);
-  };
-
-  // Insert with cache eviction
-  db.insertAndEvictCache = function <TTable extends MySqlTable>(table: TTable) {
-    return insertAndEvictCacheBuilder(db, table, newOptions, true);
-  };
-
-  // Update with cache context support (participates in cache clearing when used within cache context)
-  db.updateWithCacheContext = function <TTable extends MySqlTable>(table: TTable) {
-    return updateAndEvictCacheBuilder(db, table, newOptions, false);
-  };
-
-  // Update with cache eviction
-  db.updateAndEvictCache = function <TTable extends MySqlTable>(table: TTable) {
-    return updateAndEvictCacheBuilder(db, table, newOptions, true);
-  };
-
-  // Delete with cache context support (participates in cache clearing when used within cache context)
-  db.deleteWithCacheContext = function <TTable extends MySqlTable>(table: TTable) {
-    return deleteAndEvictCacheBuilder(db, table, newOptions, false);
-  };
-
-  // Delete with cache eviction
-  db.deleteAndEvictCache = function <TTable extends MySqlTable>(table: TTable) {
-    return deleteAndEvictCacheBuilder(db, table, newOptions, true);
+      .from(table) as unknown as SelectFromReturnType<T>;
   };
+}
 
-  // ============================================================================
-  // RAW SQL QUERY EXECUTORS
-  // ============================================================================
+/**
+ * Sets up cache-aware modify operations.
+ */
+function setupCacheAwareModifyMethods(
+  db: MySqlRemoteDatabase<any>,
+  newOptions: ForgeSqlOrmOptions,
+): void {
+  // Insert operations
+  db.insertWithCacheContext = <TTable extends MySqlTable>(table: TTable) =>
+    insertAndEvictCacheBuilder(db, table, newOptions, false);
+  db.insertAndEvictCache = <TTable extends MySqlTable>(table: TTable) =>
+    insertAndEvictCacheBuilder(db, table, newOptions, true);
+
+  // Update operations
+  db.updateWithCacheContext = <TTable extends MySqlTable>(table: TTable) =>
+    updateAndEvictCacheBuilder(db, table, newOptions, false);
+  db.updateAndEvictCache = <TTable extends MySqlTable>(table: TTable) =>
+    updateAndEvictCacheBuilder(db, table, newOptions, true);
+
+  // Delete operations
+  db.deleteWithCacheContext = <TTable extends MySqlTable>(table: TTable) =>
+    deleteAndEvictCacheBuilder(db, table, newOptions, false);
+  db.deleteAndEvictCache = <TTable extends MySqlTable>(table: TTable) =>
+    deleteAndEvictCacheBuilder(db, table, newOptions, true);
+}
 
+/**
+ * Sets up raw SQL query executors.
+ */
+function setupRawQueryExecutors(
+  db: MySqlRemoteDatabase<any>,
+  newOptions: ForgeSqlOrmOptions,
+): void {
   /**
    * Executes a raw SQL query with local cache support.
    * This method provides local caching for raw SQL queries within the current invocation context.
@@ -1180,6 +1042,49 @@ export function patchDbWithSelectAliased(
    * ```
    */
   db.executeQueryCacheable = createRawQueryExecutor(db, newOptions, true);
+}
+
+// ============================================================================
+// MAIN PATCH FUNCTION
+// ============================================================================
+
+/**
+ * Patches a Drizzle database instance with additional methods for aliased selects and cache management.
+ *
+ * This function extends the database instance with:
+ * - selectAliased: Select with field aliasing support
+ * - selectAliasedDistinct: Select distinct with field aliasing support
+ * - selectAliasedCacheable: Select with field aliasing and caching
+ * - selectAliasedDistinctCacheable: Select distinct with field aliasing and caching
+ * - insertAndEvictCache: Insert operations that automatically evict cache
+ * - updateAndEvictCache: Update operations that automatically evict cache
+ * - deleteAndEvictCache: Delete operations that automatically evict cache
+ *
+ * @param db - The Drizzle database instance to patch
+ * @param options - Optional ForgeSQL ORM configuration
+ * @returns The patched database instance with additional methods
+ */
+export function patchDbWithSelectAliased(
+  db: MySqlRemoteDatabase<any>,
+  options?: ForgeSqlOrmOptions,
+): MySqlRemoteDatabase<any> & {
+  selectAliased: SelectAliasedType;
+  selectAliasedDistinct: SelectAliasedDistinctType;
+  selectAliasedCacheable: SelectAliasedCacheableType;
+  selectAliasedDistinctCacheable: SelectAliasedDistinctCacheableType;
+  insertWithCacheContext: InsertAndEvictCacheType;
+  insertAndEvictCache: InsertAndEvictCacheType;
+  updateAndEvictCache: UpdateAndEvictCacheType;
+  updateWithCacheContext: UpdateAndEvictCacheType;
+  deleteAndEvictCache: DeleteAndEvictCacheType;
+  deleteWithCacheContext: DeleteAndEvictCacheType;
+} {
+  const newOptions = { ...DEFAULT_OPTIONS, ...options };
+
+  setupSelectAliasedMethods(db, newOptions);
+  setupTableBasedSelectMethods(db);
+  setupCacheAwareModifyMethods(db, newOptions);
+  setupRawQueryExecutors(db, newOptions);
 
   return db;
 }