forge-sql-orm 2.0.30 → 2.1.1

package/dist/core/ForgeSQLQueryBuilder.d.ts

@@ -1,30 +1,58 @@
 import { UpdateQueryResponse } from "@forge/sql";
 import { SqlParameters } from "@forge/sql/out/sql-statement";
-import { AnyMySqlSelectQueryBuilder, AnyMySqlTable, MySqlSelectBuilder } from "drizzle-orm/mysql-core";
+import { AnyMySqlSelectQueryBuilder, AnyMySqlTable, MySqlSelectBuilder, MySqlTable } from "drizzle-orm/mysql-core";
 import { MySqlSelectDynamic, type SelectedFields } from "drizzle-orm/mysql-core/query-builders/select.types";
 import { InferInsertModel, Query, SQL } from "drizzle-orm";
-import { MySqlRemoteDatabase, MySqlRemotePreparedQueryHKT } from "drizzle-orm/mysql-proxy/index";
+import { MySqlRemoteDatabase, MySqlRemotePreparedQueryHKT } from "drizzle-orm/mysql-proxy";
 import { SqlHints } from "../utils/sqlHints";
 import { ClusterStatementRowCamelCase, ExplainAnalyzeRow, SlowQueryNormalized } from "./SystemTables";
+import { ForgeSQLCacheOperations } from "./ForgeSQLCacheOperations";
+import { DeleteAndEvictCacheType, ExecuteQuery, ExecuteQueryCacheable, InsertAndEvictCacheType, SelectAliasedCacheableType, SelectAliasedDistinctCacheableType, SelectAliasedDistinctType, SelectAliasedType, SelectAllDistinctFromAliasedType, SelectAllDistinctFromCacheableAliasedType, SelectAllFromAliasedType, SelectAllFromCacheableAliasedType, UpdateAndEvictCacheType } from "..";
+import { MySqlDeleteBase, MySqlInsertBuilder, MySqlSelectBase, MySqlUpdateBuilder } from "drizzle-orm/mysql-core/query-builders";
+import { MySqlRemoteQueryResultHKT } from "drizzle-orm/mysql-proxy";
+import { GetSelectTableName, GetSelectTableSelection } from "drizzle-orm/query-builders/select.types";
+import { SQLWrapper } from "drizzle-orm/sql/sql";
+import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
+import type { WithBuilder } from "drizzle-orm/mysql-core/subquery";
+import { WithSubquery } from "drizzle-orm/subquery";
 /**
  * Core interface for ForgeSQL operations.
  * Provides access to CRUD operations, schema-level SQL operations, and query analysis capabilities.
  *
+ * This is the main interface that developers interact with when using ForgeSQL ORM.
+ * It combines query building capabilities with database operations and caching.
+ *
  * @interface ForgeSqlOperation
  * @extends {QueryBuilderForgeSql}
  */
 export interface ForgeSqlOperation extends QueryBuilderForgeSql {
     /**
-     * Provides CRUD (Create, Update, Delete) operations.
-     * @deprecated Use modify() instead for better type safety and consistency
-     * @returns {CRUDForgeSQL} Interface for performing CRUD operations
+     * Creates a new query builder for the given entity.
+     * @returns {MySqlRemoteDatabase<Record<string, unknown>>} The Drizzle database instance for building queries
      */
-    crud(): CRUDForgeSQL;
+    getDrizzleQueryBuilder(): MySqlRemoteDatabase<Record<string, unknown>> & {
+        selectAliased: SelectAliasedType;
+        selectAliasedDistinct: SelectAliasedDistinctType;
+        executeQuery: ExecuteQuery;
+        selectAliasedCacheable: SelectAliasedCacheableType;
+        selectAliasedDistinctCacheable: SelectAliasedDistinctCacheableType;
+        executeQueryCacheable: ExecuteQueryCacheable;
+        insertWithCacheContext: InsertAndEvictCacheType;
+        insertAndEvictCache: InsertAndEvictCacheType;
+        updateAndEvictCache: UpdateAndEvictCacheType;
+        updateWithCacheContext: UpdateAndEvictCacheType;
+        deleteAndEvictCache: DeleteAndEvictCacheType;
+        deleteWithCacheContext: DeleteAndEvictCacheType;
+        selectFrom: SelectAllFromAliasedType;
+        selectDistinctFrom: SelectAllDistinctFromAliasedType;
+        selectFromCacheable: SelectAllFromCacheableAliasedType;
+        selectDistinctFromCacheable: SelectAllDistinctFromCacheableAliasedType;
+    };
     /**
      * Provides modify (Create, Update, Delete) operations with optimistic locking support.
-     * @returns {CRUDForgeSQL} Interface for performing CRUD operations
+     * @returns {VerioningModificationForgeSQL} Interface for performing CRUD operations
      */
-    modify(): CRUDForgeSQL;
+    modifyWithVersioning(): VerioningModificationForgeSQL;
     /**
      * Provides schema-level SQL fetch operations with type safety.
      * @returns {SchemaSqlForgeSql} Interface for executing schema-bound SQL queries
@@ -35,11 +63,27 @@ export interface ForgeSqlOperation extends QueryBuilderForgeSql {
      * @returns {SchemaAnalyzeForgeSql} Interface for analyzing query performance
      */
     analyze(): SchemaAnalyzeForgeSql;
+    /**
+     * Provides schema-level SQL operations with optimistic locking/versioning and automatic cache eviction.
+     *
+     * This method returns operations that use `modifyWithVersioning()` internally, providing:
+     * - Optimistic locking support
+     * - Automatic version field management
+     * - Cache eviction after successful operations
+     *
+     * @returns {ForgeSQLCacheOperations} Interface for executing versioned SQL operations with cache management
+     */
+    modifyWithVersioningAndEvictCache(): ForgeSQLCacheOperations;
 }
 /**
  * Interface for Query Builder operations.
  * Provides access to the underlying Drizzle ORM query builder with enhanced functionality.
  *
+ * This interface extends Drizzle's query building capabilities with:
+ * - Field aliasing to prevent name collisions in joins
+ * - Caching support for select operations
+ * - Automatic cache eviction for modify operations
+ *
  * @interface QueryBuilderForgeSql
  */
 export interface QueryBuilderForgeSql {
@@ -47,7 +91,20 @@ export interface QueryBuilderForgeSql {
      * Creates a new query builder for the given entity.
      * @returns {MySqlRemoteDatabase<Record<string, unknown>>} The Drizzle database instance for building queries
      */
-    getDrizzleQueryBuilder(): MySqlRemoteDatabase<Record<string, unknown>>;
+    getDrizzleQueryBuilder(): MySqlRemoteDatabase<Record<string, unknown>> & {
+        selectAliased: SelectAliasedType;
+        selectAliasedDistinct: SelectAliasedDistinctType;
+        executeQuery: ExecuteQuery;
+        selectAliasedCacheable: SelectAliasedCacheableType;
+        selectAliasedDistinctCacheable: SelectAliasedDistinctCacheableType;
+        executeQueryCacheable: ExecuteQueryCacheable;
+        insertWithCacheContext: InsertAndEvictCacheType;
+        insertAndEvictCache: InsertAndEvictCacheType;
+        updateAndEvictCache: UpdateAndEvictCacheType;
+        updateWithCacheContext: UpdateAndEvictCacheType;
+        deleteAndEvictCache: DeleteAndEvictCacheType;
+        deleteWithCacheContext: DeleteAndEvictCacheType;
+    };
     /**
      * 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.
@@ -66,30 +123,337 @@ export interface QueryBuilderForgeSql {
      */
     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.
+     * 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.
+     *
+     * @template T - The type of the table
+     * @param table - The table to select from
+     * @returns Select query builder with all table columns and field aliasing support
+     * @example
+     * ```typescript
+     * const users = await forgeSQL.selectFrom(userTable).where(eq(userTable.id, 1));
+     * ```
+     */
+    selectFrom<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>;
+    /**
+   * 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>;
+    /**
+     * Creates a select distinct query builder for all columns from a table with field aliasing support.
+     * This is a convenience method that automatically selects all distinct columns from the specified table.
+     *
+     * @template T - The type of the table
+     * @param table - The table to select from
+     * @returns Select distinct query builder with all table columns and field aliasing support
+     * @example
+     * ```typescript
+     * const uniqueUsers = await forgeSQL.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
+     * ```
+     */
+    selectDistinctFrom<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>;
+    /**
+     * Creates a cacheable 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
+     * @param {number} cacheTTL - cache ttl optional default is 60 sec.
+     * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
      * @throws {Error} If fields parameter is empty
      * @example
      * ```typescript
      * await forgeSQL
-     *   .selectDistinct({user: users, order: orders})
+     *   .selectCacheable({user: users, order: orders},60)
      *   .from(orders)
      *   .innerJoin(users, eq(orders.userId, users.id));
      * ```
      */
-    selectDistinct<TSelection extends SelectedFields>(fields: TSelection): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+    selectCacheable<TSelection extends SelectedFields>(fields: TSelection, cacheTTL?: number): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Creates a cacheable select query builder for all columns from a table with field aliasing and caching support.
+     * This is a convenience method that automatically selects all columns from the specified table with caching enabled.
+     *
+     * @template T - The type of the table
+     * @param table - The table to select from
+     * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+     * @returns Select query builder with all table columns, field aliasing, and caching support
+     * @example
+     * ```typescript
+     * const users = await forgeSQL.selectCacheableFrom(userTable, 300).where(eq(userTable.id, 1));
+     * ```
+     */
+    selectCacheableFrom<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>;
+    /**
+     * Creates a cacheable 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
+     * @param {number} cacheTTL - cache ttl optional default is 60 sec.
+     * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A distinct select query builder with unique field aliases
+     * @throws {Error} If fields parameter is empty
+     * @example
+     * ```typescript
+     * await forgeSQL
+     *   .selectDistinctCacheable({user: users, order: orders}, 60)
+     *   .from(orders)
+     *   .innerJoin(users, eq(orders.userId, users.id));
+     * ```
+     */
+    selectDistinctCacheable<TSelection extends SelectedFields>(fields: TSelection, cacheTTL?: number): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Creates a cacheable select distinct query builder for all columns from a table with field aliasing and caching support.
+     * This is a convenience method that automatically selects all distinct columns from the specified table with caching enabled.
+     *
+     * @template T - The type of the table
+     * @param table - The table to select from
+     * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
+     * @returns Select distinct query builder with all table columns, field aliasing, and caching support
+     * @example
+     * ```typescript
+     * const uniqueUsers = await forgeSQL.selectDistinctCacheableFrom(userTable, 300).where(eq(userTable.status, 'active'));
+     * ```
+     */
+    selectDistinctCacheableFrom<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>;
+    /**
+   * Creates an insert query builder.
+   *
+   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+   * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
+   *
+   * @param table - The table to insert into
+   * @returns Insert query builder (no versioning, no cache management)
+   */
+    insert<TTable extends MySqlTable>(table: TTable): MySqlInsertBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Creates an insert query builder that automatically evicts cache after execution.
+     *
+     * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+     * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
+     *
+     * @param table - The table to insert into
+     * @returns Insert query builder with automatic cache eviction (no versioning)
+     */
+    insertAndEvictCache<TTable extends MySqlTable>(table: TTable): MySqlInsertBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Creates an update query builder.
+     *
+     * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+     * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
+     *
+     * @param table - The table to update
+     * @returns Update query builder (no versioning, no cache management)
+     */
+    update<TTable extends MySqlTable>(table: TTable): MySqlUpdateBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Creates an update query builder that automatically evicts cache after execution.
+     *
+     * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+     * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
+     *
+     * @param table - The table to update
+     * @returns Update query builder with automatic cache eviction (no versioning)
+     */
+    updateAndEvictCache<TTable extends MySqlTable>(table: TTable): MySqlUpdateBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Creates a delete query builder.
+     *
+     * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+     * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
+     *
+     * @param table - The table to delete from
+     * @returns Delete query builder (no versioning, no cache management)
+     */
+    delete<TTable extends MySqlTable>(table: TTable): MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Creates a delete query builder that automatically evicts cache after execution.
+     *
+     * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
+     * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
+     *
+     * @param table - The table to delete from
+     * @returns Delete query builder with automatic cache eviction (no versioning)
+     */
+    deleteAndEvictCache<TTable extends MySqlTable>(table: TTable): MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+    /**
+     * Executes operations within a cache context that collects cache eviction events.
+     * All clearCache calls within the context are collected and executed in batch at the end.
+     * Queries executed within this context will bypass cache for tables that were marked for clearing.
+     *
+     * @param cacheContext - Function containing operations that may trigger cache evictions
+     * @returns Promise that resolves when all operations and cache clearing are complete
+     */
+    executeWithCacheContext(cacheContext: () => Promise<void>): Promise<void>;
+    /**
+     * Executes operations within a cache context and returns a value.
+     * All clearCache calls within the context are collected and executed in batch at the end.
+     * Queries executed within this context will bypass cache for tables that were marked for clearing.
+     *
+     * @param cacheContext - Function containing operations that may trigger cache evictions
+     * @returns Promise that resolves to the return value of the cacheContext function
+     */
+    executeWithCacheContextAndReturnValue<T>(cacheContext: () => Promise<T>): Promise<T>;
+    /**
+     * Executes operations within a local cache context that provides in-memory caching for select queries.
+     * This is useful for optimizing queries within a single resolver or request scope.
+     *
+     * Local cache features:
+     * - Caches select query results in memory for the duration of the context
+     * - Automatically evicts cache when insert/update/delete operations are performed
+     * - Provides faster access to repeated queries within the same context
+     * - Does not persist across different requests or contexts
+     *
+     * @param cacheContext - Function containing operations that will benefit from local caching
+     * @returns Promise that resolves when all operations are complete
+     *
+     * @example
+     * ```typescript
+     * await forgeSQL.executeWithLocalContext(async () => {
+     *   // First call - executes query and caches result
+     *   const users = await forgeSQL.select({ id: users.id, name: users.name })
+     *     .from(users).where(eq(users.active, true));
+     *
+     *   // Second call - gets result from local cache (no database query)
+     *   const cachedUsers = await forgeSQL.select({ id: users.id, name: users.name })
+     *     .from(users).where(eq(users.active, true));
+     *
+     *   // Insert operation - evicts local cache
+     *   await forgeSQL.insert(users).values({ name: 'New User', active: true });
+     * });
+     * ```
+     */
+    executeWithLocalContext(cacheContext: () => Promise<void>): Promise<void>;
+    /**
+     * Executes operations within a local cache context and returns a value.
+     * This is useful for optimizing queries within a single resolver or request scope.
+     *
+     * Local cache features:
+     * - Caches select query results in memory for the duration of the context
+     * - Automatically evicts cache when insert/update/delete operations are performed
+     * - Provides faster access to repeated queries within the same context
+     * - Does not persist across different requests or contexts
+     *
+     * @param cacheContext - Function containing operations that will benefit from local caching
+     * @returns Promise that resolves to the return value of the cacheContext function
+     *
+     * @example
+     * ```typescript
+     * const result = await forgeSQL.executeWithLocalCacheContextAndReturnValue(async () => {
+     *   // First call - executes query and caches result
+     *   const users = await forgeSQL.select({ id: users.id, name: users.name })
+     *     .from(users).where(eq(users.active, true));
+     *
+     *   // Second call - gets result from local cache (no database query)
+     * const cachedUsers = await forgeSQL.select({ id: users.id, name: users.name })
+     *     .from(users).where(eq(users.active, true));
+     *
+     *   return { users, cachedUsers };
+     * });
+     * ```
+     */
+    executeWithLocalCacheContextAndReturnValue<T>(cacheContext: () => Promise<T>): Promise<T>;
+    /**
+     * Executes a raw SQL query with local cache support.
+     * This method provides local caching for raw SQL queries within the current invocation context.
+     * Results are cached locally and will be returned from cache on subsequent identical queries.
+     *
+     * @param query - The SQL query to execute (SQLWrapper or string)
+     * @returns Promise with query results
+     * @example
+     * ```typescript
+     * // Using SQLWrapper
+     * const result = await forgeSQL.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
+     *
+     * // Using string
+     * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
+     * ```
+     */
+    execute(query: SQLWrapper | string): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+    /**
+     * Executes a raw SQL query with both local and global cache support.
+     * This method provides comprehensive caching for raw SQL queries:
+     * - Local cache: Within the current invocation context
+     * - Global cache: Cross-invocation caching using @forge/kvs
+     *
+     * @param query - The SQL query to execute (SQLWrapper or string)
+     * @param cacheTtl - Optional cache TTL override (defaults to global cache TTL)
+     * @returns Promise with query results
+     * @example
+     * ```typescript
+     * // Using SQLWrapper with custom TTL
+     * const result = await forgeSQL.executeCacheable(sql`SELECT * FROM users WHERE id = ${userId}`, 300);
+     *
+     * // Using string with default TTL
+     * const result = await forgeSQL.executeCacheable("SELECT * FROM users WHERE status = 'active'");
+     * ```
+     */
+    executeCacheable(query: SQLWrapper | string, cacheTtl?: number): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, unknown>>;
+    /**
+     * Creates a Common Table Expression (CTE) builder for complex queries.
+     * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+     *
+     * @returns WithBuilder for creating CTEs
+     * @example
+     * ```typescript
+     * const withQuery = forgeSQL.$with('userStats').as(
+     *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+     *     .from(users)
+     *     .groupBy(users.id)
+     * );
+     * ```
+     */
+    $with: WithBuilder;
+    /**
+     * Creates a query builder that uses Common Table Expressions (CTEs).
+     * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
+     *
+     * @param queries - Array of CTE queries created with $with()
+     * @returns Query builder with CTE support
+     * @example
+     * ```typescript
+     * const withQuery = forgeSQL.$with('userStats').as(
+     *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
+     *     .from(users)
+     *     .groupBy(users.id)
+     * );
+     *
+     * const result = await forgeSQL.with(withQuery)
+     *   .select({ userId: withQuery.userId, count: withQuery.count })
+     *   .from(withQuery);
+     * ```
+     */
+    with(...queries: WithSubquery[]): {
+        select: {
+            (): MySqlSelectBuilder<undefined, MySqlRemotePreparedQueryHKT>;
+            <TSelection extends SelectedFields>(fields: TSelection): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+        };
+        selectDistinct: {
+            (): MySqlSelectBuilder<undefined, MySqlRemotePreparedQueryHKT>;
+            <TSelection extends SelectedFields>(fields: TSelection): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+        };
+    };
 }
 /**
  * Interface for Modify (Create, Update, Delete) operations.
  * Provides methods for basic database operations with support for optimistic locking.
  *
- * @interface CRUDForgeSQL
+ * @interface VerioningModificationForgeSQL
  */
-export interface CRUDForgeSQL {
+export interface VerioningModificationForgeSQL {
     /**
      * Inserts multiple records into the database.
      * @template T - The type of the table schema
@@ -139,6 +503,10 @@ export interface CRUDForgeSQL {
      */
     updateFields<T extends AnyMySqlTable>(updateData: Partial<InferInsertModel<T>>, schema: T, where?: SQL<unknown>): Promise<number>;
 }
+export interface CacheForgeSQL extends VerioningModificationForgeSQL {
+    evictCache(tables: string[]): Promise<void>;
+    evictCacheEntities(tables: AnyMySqlTable[]): Promise<void>;
+}
 /**
  * Interface for schema analysis operations.
  * Provides methods for analyzing query performance and execution plans.
@@ -225,10 +593,11 @@ export interface SchemaSqlForgeSql {
     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
+     *
+     * @param query - The raw SQL update query
+     * @param params - Optional SQL parameters
+     * @returns Promise that resolves to the update response containing affected rows
+     * @throws Error if the update operation fails
      */
     executeRawUpdateSQL(query: string, params?: unknown[]): Promise<UpdateQueryResponse>;
 }
@@ -273,6 +642,12 @@ export interface ForgeSqlOrmOptions {
     disableOptimisticLocking?: boolean;
     /** SQL hints to be applied to queries */
     hints?: SqlHints;
+    cacheTTL?: number;
+    cacheEntityName?: string;
+    cacheEntityQueryName?: string;
+    cacheWrapTable?: boolean;
+    cacheEntityExpirationName?: string;
+    cacheEntityDataName?: string;
     /**
      * Additional metadata for table configuration.
      * Allows specifying table-specific settings and behaviors.

package/dist/core/ForgeSQLQueryBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgeSQLQueryBuilder.d.ts","sourceRoot":"","sources":["../../src/core/ForgeSQLQueryBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ForgeSQLQueryBuilder.d.ts","sourceRoot":"","sources":["../../src/core/ForgeSQLQueryBuilder.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export * from "./core/ForgeSQLSelectOperations";
 export * from "./utils/sqlUtils";
 export * from "./utils/forgeDriver";
 export * from "./webtriggers";
-export * from "./lib/drizzle/extensions/selectAliased";
+export * from "./lib/drizzle/extensions/additionalActions";
 export * from "./core/SystemTables";
 export default ForgeSQLORM;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,oBAAoB,CAAC;AAE7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,wCAAwC,CAAC;AACvD,cAAc,qBAAqB,CAAC;AAEpC,eAAe,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,oBAAoB,CAAC;AAE7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,iCAAiC,CAAC;AAChD,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qBAAqB,CAAC;AAEpC,eAAe,WAAW,CAAC"}

package/dist/lib/drizzle/extensions/additionalActions.d.ts

@@ -0,0 +1,90 @@
+import { MySqlRemoteDatabase, MySqlRemotePreparedQueryHKT, MySqlRemoteQueryResultHKT } from "drizzle-orm/mysql-proxy";
+import { SelectedFields } from "drizzle-orm/mysql-core/query-builders/select.types";
+import { ForgeSqlOrmOptions } 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 { SQLWrapper } from "drizzle-orm/sql/sql";
+import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
+import type { GetSelectTableName, GetSelectTableSelection } from "drizzle-orm/query-builders/select.types";
+/**
+ * Type for select queries with field aliasing
+ */
+export type SelectAliasedType = <TSelection extends SelectedFields>(fields: TSelection) => MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+/**
+ * Type for select distinct queries with field aliasing
+ */
+export type SelectAliasedDistinctType = <TSelection extends SelectedFields>(fields: TSelection) => MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+/**
+ * Type for select queries with field aliasing and caching
+ */
+export type SelectAliasedCacheableType = <TSelection extends SelectedFields>(fields: TSelection, cacheTtl?: number) => MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+/**
+ * Type for select distinct queries with field aliasing and caching
+ */
+export type SelectAliasedDistinctCacheableType = <TSelection extends SelectedFields>(fields: TSelection, cacheTtl?: number) => MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>;
+/**
+ * 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>;
+/**
+ * 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>;
+/**
+ * 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>;
+/**
+ * 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>;
+/**
+ * Type for executing raw SQL queries with local cache
+ */
+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>>;
+/**
+ * Type for insert operations with cache eviction
+ */
+export type InsertAndEvictCacheType = <TTable extends MySqlTable>(table: TTable) => MySqlInsertBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+/**
+ * Type for update operations with cache eviction
+ */
+export type UpdateAndEvictCacheType = <TTable extends MySqlTable>(table: TTable) => MySqlUpdateBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+/**
+ * Type for delete operations with cache eviction
+ */
+export type DeleteAndEvictCacheType = <TTable extends MySqlTable>(table: TTable) => MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT>;
+/**
+ * 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 declare 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;
+};
+//# sourceMappingURL=additionalActions.d.ts.map