import { UpdateQueryResponse } from "@forge/sql";

import type { EntityName, LoggingOptions, QBFilterQuery } from "..";

import type { EntitySchema } from "@mikro-orm/core/metadata/EntitySchema";

import type { QueryBuilder } from "@mikro-orm/knex/query";

import type { Knex } from "knex";

import {EntityKey, EntityProperty} from "@mikro-orm/core";

import {SqlParameters} from "@forge/sql/out/sql-statement";

import {DynamicEntity} from "./ComplexQuerySchemaBuilder";

/**

* Interface representing the main ForgeSQL operations.

*/

export interface ForgeSqlOperation extends QueryBuilderForgeSql {

/**

* Provides CRUD operations.

*/

crud(): CRUDForgeSQL;

/**

* Provides schema-level SQL fetch operations.

*/

fetch(): SchemaSqlForgeSql;

}

/**

* Options for configuring ForgeSQL ORM behavior.

*/

export interface ForgeSqlOrmOptions {

/**

* Enables logging of raw SQL queries in the Atlassian Forge Developer Console.

*/

logRawSqlQuery?: boolean;

/**

* Disable optimistic locking

*/

disableOptimisticLocking?: boolean

}

/**

* Interface for schema-level SQL operations.

*/

export interface SchemaSqlForgeSql {

/**

* Executes a schema-bound SQL query and maps the result to the specified entity schema.

* @param query - The SQL query to execute.

* @param schema - The entity schema.

* @returns A list of mapped entity objects.

*/

executeSchemaSQL<T extends object>(query: string, schema: EntitySchema<T>): Promise<T[]>;

/**

* Executes a schema-bound SQL query and maps the only one result to the specified entity schema.

* @param query - The SQL query to execute.

* @param schema - The entity schema.

* @returns A list of mapped entity objects.

*/

executeSchemaSQLOnlyOne<T extends object>(query: string, schema: EntitySchema<T>): Promise<T|undefined>;

/**

* Executes a raw SQL query and returns the results.

* @param query - The raw SQL query.

* @returns A list of results as objects.

*/

executeRawSQL<T extends object | unknown>(query: string): Promise<T[]>;

/**

* Executes a raw SQL update query.

* @param query - The raw SQL update query.

* @param params - Sql parameters.

* @returns The update response containing affected rows.

*/

executeRawUpdateSQL(query: string, params?: SqlParameters[]): Promise<UpdateQueryResponse>;

/**

* Creates a builder for constructing complex query schemas dynamically.

* This method is useful when working with dynamic entity structures where fields

* may not be known at compile time.

* @returns An instance of ComplexQuerySchemaBuilder configured for dynamic entities.

*/

createComplexQuerySchema():ComplexQuerySchemaBuilder<DynamicEntity>

}

/**

* Interface for CRUD (Create, Read, Update, Delete) operations.

*/

export interface CRUDForgeSQL {

/**

* Inserts multiple records into the database.

* @param schema - The entity schema.

* @param models - The list of entities to insert.

* @param updateIfExists - Whether to update the row if it already exists.

* @returns The number of inserted rows.

*/

insert<T extends object>(

schema: EntitySchema<T>,

models: T[],

updateIfExists?: boolean,

): Promise<number>;

/**

* Deletes a record by its ID.

* @param id - The ID of the record to delete.

* @param schema - The entity schema.

* @returns The number of rows affected.

*/

deleteById<T extends object>(id: unknown, schema: EntitySchema<T>): Promise<number>;

/**

* Updates a record by its ID.

* * If a version field is defined in the schema, versioning is applied:

* * the current record version is retrieved, checked for concurrent modifications,

* * and then incremented.

* *

* * @param entity - The entity with updated values.

* * @param schema - The entity schema.

* * @throws If the primary key is not included in the update fields.

* */

updateById<T extends object>(entity: Partial<T>, schema: EntitySchema<T>): Promise<void>;

/**

* Updates specified fields of records based on provided conditions.

* If the "where" parameter is not provided, the WHERE clause is built from the entity fields

* that are not included in the list of fields to update.

*

* @param entity - The object containing values to update and potential criteria for filtering.

* @param fields - Array of field names to update.

* @param schema - The entity schema.

* @param where - Optional filtering conditions for the WHERE clause.

* @returns The number of affected rows.

* @throws If no filtering criteria are provided (either via "where" or from the remaining entity fields).

*/

updateFields<T extends object>(

entity: Partial<T>,

fields: EntityKey<T>[],

schema: EntitySchema<T>,

where?: QBFilterQuery<T>,

): Promise<number>

/**

* Updates specific fields of a record identified by its primary key.

*

* If a version field is defined in the schema, versioning is applied:

* the current record version is retrieved, checked for concurrent modifications,

* and then incremented.

*

* @param entity - The entity with updated values.

* @param fields - The list of field names to update.

* @param schema - The entity schema.

* @throws If the primary key is not included in the update fields.

*/

updateFieldById<T extends object>(

entity: T,

fields: EntityKey<T>[],

schema: EntitySchema<T>,

): Promise<void>;

}

/**

* Interface for Query Builder operations.

*/

export interface QueryBuilderForgeSql {

/**

* Creates a new query builder for the given entity.

* @param entityName - The entity name or an existing query builder.

* @param alias - The alias for the entity.

* @param loggerContext - Logging options.

* @returns The query builder instance.

*/

createQueryBuilder<Entity extends object, RootAlias extends string = never>(

entityName: EntityName<Entity> | QueryBuilder<Entity>,

alias?: RootAlias,

loggerContext?: LoggingOptions,

): QueryBuilder<Entity, RootAlias>;

/**

* Provides access to the underlying Knex instance for building complex query parts.

* enabling advanced query customization and performance tuning.

* @returns The Knex instance, which can be used for query building.

*/

getKnex(): Knex<any, any[]>;

}

export interface ComplexQuerySchemaBuilder<T> {

/**

* Adds a field from an entity schema to the builder.

* @param field - The entity property to be added.

* @param alias - (Optional) Alias for the field name.

* @returns The updated instance of the builder.

*/

addField<K>(field: Partial<EntityProperty<K>>, alias?: string): this

/**

* Creates and returns a new entity schema based on the added fields.

* @returns A new EntitySchema<T> instance.

*/

createSchema(): EntitySchema<T>;

}