forge-sql-orm/dist/core/ForgeSQLCacheOperations.d.ts

Drizzle ORM integration for Atlassian @forge/sql. Provides a custom driver, schema migration, two levels of caching (local and global via @forge/kvs), optimistic locking, and query analysis.

import { MySqlSelectDynamic } from "drizzle-orm/mysql-core/query-builders/select.types";
import { AnyMySqlSelectQueryBuilder, AnyMySqlTable } from "drizzle-orm/mysql-core";
import { CacheForgeSQL, ForgeSqlOperation, ForgeSqlOrmOptions } from "./ForgeSQLQueryBuilder";
import { InferInsertModel, SQL } from "drizzle-orm";
/**
 * Implementation of cache operations for ForgeSQL ORM.
 * Provides methods for cacheable database operations with automatic cache management.
 *
 * ⚠️ **IMPORTANT**: All modification methods in this class use optimistic locking/versioning
 * through `modifyWithVersioning()` internally. This ensures data consistency and prevents
 * concurrent modification conflicts.
 */
export declare class ForgeSQLCacheOperations implements CacheForgeSQL {
    private readonly options;
    private readonly forgeOperations;
    /**
     * Creates a new instance of ForgeSQLCacheOperations.
     *
     * @param options - Configuration options for the ORM
     * @param forgeOperations - The ForgeSQL operations instance
     */
    constructor(options: ForgeSqlOrmOptions, forgeOperations: ForgeSqlOperation);
    /**
     * Evicts cache for multiple tables using Drizzle table objects.
     *
     * @param tables - Array of Drizzle table objects to clear cache for
     * @returns Promise that resolves when cache eviction is complete
     * @throws Error if cacheEntityName is not configured
     */
    evictCacheEntities(tables: AnyMySqlTable[]): Promise<void>;
    /**
     * Evicts cache for multiple tables by their names.
     *
     * @param tables - Array of table names to clear cache for
     * @returns Promise that resolves when cache eviction is complete
     * @throws Error if cacheEntityName is not configured
     */
    evictCache(tables: string[]): Promise<void>;
    /**
     * Inserts records with optimistic locking/versioning and automatically evicts cache.
     *
     * This method uses `modifyWithVersioning().insert()` internally, providing:
     * - Automatic version field initialization
     * - Optimistic locking support
     * - Cache eviction after successful operation
     *
     * @param schema - The table schema
     * @param models - Array of entities to insert
     * @param updateIfExists - Whether to update existing records
     * @returns Promise that resolves to the number of inserted rows
     * @throws Error if cacheEntityName is not configured
     * @throws Error if optimistic locking check fails
     */
    insert<T extends AnyMySqlTable>(schema: T, models: InferInsertModel<T>[], updateIfExists?: boolean): Promise<number>;
    /**
     * Deletes a record by ID with optimistic locking/versioning and automatically evicts cache.
     *
     * This method uses `modifyWithVersioning().deleteById()` internally, providing:
     * - Optimistic locking checks before deletion
     * - Version field validation
     * - Cache eviction after successful operation
     *
     * @param id - The ID of the record to delete
     * @param schema - The table schema
     * @returns Promise that resolves to the number of affected rows
     * @throws Error if cacheEntityName is not configured
     * @throws Error if optimistic locking check fails
     */
    deleteById<T extends AnyMySqlTable>(id: unknown, schema: T): Promise<number>;
    /**
     * Updates a record by ID with optimistic locking/versioning and automatically evicts cache.
     *
     * This method uses `modifyWithVersioning().updateById()` internally, providing:
     * - Optimistic locking checks before update
     * - Version field incrementation
     * - Cache eviction after successful operation
     *
     * @param entity - The entity with updated values (must include primary key)
     * @param schema - The table schema
     * @returns Promise that resolves to the number of affected rows
     * @throws Error if cacheEntityName is not configured
     * @throws Error if optimistic locking check fails
     */
    updateById<T extends AnyMySqlTable>(entity: Partial<InferInsertModel<T>>, schema: T): Promise<number>;
    /**
     * Updates fields based on conditions with optimistic locking/versioning and automatically evicts cache.
     *
     * This method uses `modifyWithVersioning().updateFields()` internally, providing:
     * - Optimistic locking support (if version field is configured)
     * - Version field validation and incrementation
     * - Cache eviction after successful operation
     *
     * @param updateData - The data to update
     * @param schema - The table schema
     * @param where - Optional WHERE conditions
     * @returns Promise that resolves to the number of affected rows
     * @throws Error if cacheEntityName is not configured
     * @throws Error if optimistic locking check fails
     */
    updateFields<T extends AnyMySqlTable>(updateData: Partial<InferInsertModel<T>>, schema: T, where?: SQL<unknown>): Promise<number>;
    /**
     * Executes a query with caching support.
     * First checks cache, if not found executes query and stores result in cache.
     *
     * @param query - The Drizzle query to execute
     * @param cacheTtl - Optional cache TTL override
     * @returns Promise that resolves to the query results
     * @throws Error if cacheEntityName is not configured
     */
    executeQuery<T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>>(query: T, cacheTtl?: number): Promise<Awaited<T>>;
    /**
     * Validates that cache configuration is properly set up.
     *
     * @throws Error if cacheEntityName is not configured
     * @private
     */
    private validateCacheConfiguration;
}
//# sourceMappingURL=ForgeSQLCacheOperations.d.ts.map