forge-sql-orm/dist/core/ForgeSQLCrudOperations.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 { ForgeSqlOrmOptions } from "..";
import { VerioningModificationForgeSQL, ForgeSqlOperation } from "./ForgeSQLQueryBuilder";
import { AnyMySqlTable } from "drizzle-orm/mysql-core";
import { InferInsertModel, SQL } from "drizzle-orm";
/**
 * Class implementing Modification operations for ForgeSQL ORM.
 * Provides methods for inserting, updating, and deleting records with support for optimistic locking.
 */
export declare class ForgeSQLCrudOperations implements VerioningModificationForgeSQL {
    private readonly forgeOperations;
    private readonly options;
    /**
     * Creates a new instance of ForgeSQLCrudOperations.
     * @param forgeSqlOperations - The ForgeSQL operations instance
     * @param options - Configuration options for the ORM
     */
    constructor(forgeSqlOperations: ForgeSqlOperation, options: ForgeSqlOrmOptions);
    /**
     * Inserts records into the database with optional versioning support.
     * If a version field exists in the schema, versioning is applied.
     *
     * This method automatically handles:
     * - Version field initialization for optimistic locking
     * - Batch insertion for multiple records
     * - Duplicate key handling with optional updates
     *
     * @template T - The type of the table schema
     * @param schema - The entity schema
     * @param models - Array of entities to insert
     * @param updateIfExists - Whether to update existing records (default: false)
     * @returns Promise that resolves to the number of inserted rows
     * @throws Error if the insert operation fails
     */
    insert<T extends AnyMySqlTable>(schema: T, models: InferInsertModel<T>[], updateIfExists?: boolean): Promise<number>;
    /**
     * Deletes a record by its primary key with optional version check.
     * If versioning is enabled, ensures the record hasn't been modified since last read.
     *
     * This method automatically handles:
     * - Single primary key validation
     * - Optimistic locking checks if versioning is enabled
     * - Version field validation before deletion
     *
     * @template T - The type of the table schema
     * @param id - The ID of the record to delete
     * @param schema - The entity schema
     * @returns Promise that resolves to the number of affected rows
     * @throws Error if the delete operation fails
     * @throws Error if multiple primary keys are found
     * @throws Error if optimistic locking check fails
     */
    deleteById<T extends AnyMySqlTable>(id: unknown, schema: T): Promise<number>;
    /**
     * Updates a record by its primary key with optimistic locking support.
     * If versioning is enabled:
     * - Retrieves the current version
     * - Checks for concurrent modifications
     * - Increments the version on successful update
     *
     * This method automatically handles:
     * - Primary key validation
     * - Version field retrieval and validation
     * - Optimistic locking conflict detection
     * - Version field incrementation
     *
     * @template T - The type of the table schema
     * @param entity - The entity with updated values (must include primary key)
     * @param schema - The entity schema
     * @returns Promise that resolves to the number of affected rows
     * @throws Error if the primary key is not provided
     * @throws Error if optimistic locking check fails
     * @throws Error if multiple primary keys are found
     */
    updateById<T extends AnyMySqlTable>(entity: Partial<InferInsertModel<T>>, schema: T): Promise<number>;
    /**
     * Updates specified fields of records based on provided conditions.
     * This method does not support versioning and should be used with caution.
     *
     * @template T - The type of the table schema
     * @param {Partial<InferInsertModel<T>>} updateData - The data to update
     * @param {T} schema - The entity schema
     * @param {SQL<unknown>} where - The WHERE conditions
     * @returns {Promise<number>} Number of affected rows
     * @throws {Error} If WHERE conditions are not provided
     * @throws {Error} If the update operation fails
     */
    updateFields<T extends AnyMySqlTable>(updateData: Partial<InferInsertModel<T>>, schema: T, where?: SQL<unknown>): Promise<number>;
    /**
     * Gets primary keys from the schema.
     * @template T - The type of the table schema
     * @param {T} schema - The table schema
     * @returns {[string, AnyColumn][]} Array of primary key name and column pairs
     * @throws {Error} If no primary keys are found
     */
    private getPrimaryKeys;
    /**
     * Validates and retrieves version field metadata.
     * @param {string} tableName - The name of the table
     * @param {Record<string, AnyColumn>} columns - The table columns
     * @returns {Object | undefined} Version field metadata if valid, undefined otherwise
     */
    private validateVersionField;
    /**
     * Gets the current version of an entity.
     * @template T - The type of the table schema
     * @param {Partial<InferInsertModel<T>>} entity - The entity
     * @param {string} primaryKeyName - The name of the primary key
     * @param {Object | undefined} versionMetadata - Version field metadata
     * @param {Record<string, AnyColumn>} columns - The table columns
     * @param {T} schema - The table schema
     * @returns {Promise<unknown>} The current version value
     */
    private getCurrentVersion;
    /**
     * Prepares a model for insertion with version field.
     * @template T - The type of the table schema
     * @param {Partial<InferInsertModel<T>>} model - The model to prepare
     * @param {Object | undefined} versionMetadata - Version field metadata
     * @param {Record<string, AnyColumn>} columns - The table columns
     * @returns {InferInsertModel<T>} The prepared model
     */
    private prepareModelWithVersion;
    /**
     * Prepares update data with version field.
     * @template T - The type of the table schema
     * @param {Partial<InferInsertModel<T>>} entity - The entity to update
     * @param {Object | undefined} versionMetadata - Version field metadata
     * @param {Record<string, AnyColumn>} columns - The table columns
     * @param {unknown} currentVersion - The current version value
     * @returns {Partial<InferInsertModel<T>>} The prepared update data
     */
    private prepareUpdateData;
    /**
     * Retrieves an existing model by primary key.
     * @template T - The type of the table schema
     * @param {Record<string, unknown>} primaryKeyValues - The primary key values
     * @param {T} schema - The table schema
     * @param {[string, AnyColumn]} versionField - The version field name and column
     * @returns {Promise<Awaited<T> extends Array<any> ? Awaited<T>[number] | undefined : Awaited<T> | undefined>} The existing model
     * @throws {Error} If the record is not found
     */
    private getOldModel;
}
//# sourceMappingURL=ForgeSQLCrudOperations.d.ts.map