types

type Columns interface {
	// Col retrieves the vendor-quoted column name for the given struct field name.
	// If aliased via As(), returns qualified column (e.g., "u.id").
	// Panics if the field name is not found (fail-fast for development-time typos).
	//
	// Example (unaliased):
	//   cols.Col("ID")    // Returns: "id" (PostgreSQL) or "ID" (Oracle)
	//   cols.Col("Level") // Returns: "level" (PostgreSQL) or "LEVEL" (Oracle, quoted)
	//
	// Example (aliased):
	//   u := cols.As("u")
	//   u.Col("ID")       // Returns: "u.id" (PostgreSQL) or "u.\"ID\"" (Oracle)
	Col(fieldName string) string

	// As returns a new Columns instance bound to the specified table alias.
	// The returned instance shares the underlying column metadata (zero-copy).
	// This method is immutable - the original Columns instance remains unchanged.
	//
	// Example:
	//   cols := qb.Columns(&User{})
	//   u := cols.As("u")
	//   p := cols.As("p")
	//   u.Col("ID")  // "u.id"
	//   p.Col("ID")  // "p.id"
	//   cols.Col("ID") // "id" (original unaffected)
	As(alias string) Columns

	// Alias returns the current table alias, or empty string if unaliased.
	//
	// Example:
	//   cols.Alias()        // ""
	//   cols.As("u").Alias() // "u"
	Alias() string

	// Cols retrieves vendor-quoted column names for multiple struct field names.
	// If aliased, returns qualified columns.
	// Panics if any field name is not found.
	//
	// Example:
	//   cols.Cols("ID", "Name", "Email") // ["id", "name", "email"]
	//   cols.As("u").Cols("ID", "Name")  // ["u.id", "u.name"]
	Cols(fieldNames ...string) []string

	// All returns vendor-quoted column names for all columns in the struct,
	// in the order they were declared in the struct definition.
	//
	// Example:
	//   cols.All()        // ["id", "name", "email"] (unaliased)
	//   cols.As("u").All() // ["u.id", "u.name", "u.email"] (aliased)
	All() []string

	// FieldMap extracts field values from a struct instance into a map.
	// The map keys are vendor-quoted column names (respecting alias if set).
	// Only fields with `db` tags are included. Zero values are included.
	//
	// Example:
	//   user := User{ID: 123, Name: "Alice", Email: "alice@example.com"}
	//   cols.FieldMap(&user)
	//   // Returns: {"id": 123, "name": "Alice", "email": "alice@example.com"}
	//
	//   cols.As("u").FieldMap(&user)
	//   // Returns: {"u.id": 123, "u.name": "Alice", "u.email": "alice@example.com"}
	//
	// Panics if instance is not a struct or pointer to struct.
	FieldMap(instance any) map[string]any

	// AllFields extracts all field values from a struct instance as separate slices.
	// Returns (columns, values) suitable for bulk INSERT/UPDATE operations.
	// Only fields with `db` tags are included. Zero values are included.
	//
	// Example:
	//   user := User{ID: 123, Name: "Alice", Email: "alice@example.com"}
	//   cols, vals := cols.AllFields(&user)
	//   // cols: ["id", "name", "email"]
	//   // vals: [123, "Alice", "alice@example.com"]
	//
	// Panics if instance is not a struct or pointer to struct.
	AllFields(instance any) ([]string, []any)
}

type DeleteQueryBuilder interface {
	// Filtering
	Where(filter Filter) DeleteQueryBuilder

	// Batch operations
	Limit(limit uint64) DeleteQueryBuilder
	OrderBy(orderBys ...string) DeleteQueryBuilder

	// SQL generation
	ToSQL() (sql string, args []any, err error)
}

type Filter interface {
	squirrel.Sqlizer

	// ToSQL is a convenience method with idiomatic Go naming.
	// It should delegate to ToSql() in implementations.
	ToSQL() (sql string, args []any, err error)
}

type FilterFactory interface {
	// Comparison operators
	Eq(column string, value any) Filter
	NotEq(column string, value any) Filter
	Lt(column string, value any) Filter
	Lte(column string, value any) Filter
	Gt(column string, value any) Filter
	Gte(column string, value any) Filter
	In(column string, values any) Filter
	NotIn(column string, values any) Filter
	Like(column, pattern string) Filter
	Null(column string) Filter
	NotNull(column string) Filter
	Between(column string, lowerBound, upperBound any) Filter

	// Logical operators
	And(filters ...Filter) Filter
	Or(filters ...Filter) Filter
	Not(filter Filter) Filter

	// Raw escape hatch
	Raw(condition string, args ...any) Filter

	// Subquery support (v2.1+)
	Exists(subquery SelectQueryBuilder) Filter
	NotExists(subquery SelectQueryBuilder) Filter
	InSubquery(column string, subquery SelectQueryBuilder) Filter
}

type Interface interface {
	// Querier provides core query execution operations
	Querier

	// Transactor provides transaction management operations
	Transactor

	// Prepared statements
	Prepare(ctx context.Context, query string) (Statement, error)

	// Health and diagnostics
	Health(ctx context.Context) error
	Stats() (map[string]any, error)

	// Connection management
	Close() error

	// Migration support
	MigrationTable() string
	CreateMigrationTable(ctx context.Context) error
}

type JoinFilter interface {
	squirrel.Sqlizer

	// ToSQL is a convenience method with idiomatic Go naming.
	// It should delegate to ToSql() in implementations.
	ToSQL() (sql string, args []any, err error)
}

type JoinFilterFactory interface {
	// Column-to-column comparison operators
	EqColumn(leftColumn, rightColumn string) JoinFilter
	NotEqColumn(leftColumn, rightColumn string) JoinFilter
	LtColumn(leftColumn, rightColumn string) JoinFilter
	LteColumn(leftColumn, rightColumn string) JoinFilter
	GtColumn(leftColumn, rightColumn string) JoinFilter
	GteColumn(leftColumn, rightColumn string) JoinFilter

	// Column-to-value comparison operators (v2.2+)
	// These methods accept any value type, including RawExpression for complex SQL.
	// Regular values generate placeholders; RawExpression values are inserted verbatim.
	Eq(column string, value any) JoinFilter
	NotEq(column string, value any) JoinFilter
	Lt(column string, value any) JoinFilter
	Lte(column string, value any) JoinFilter
	Gt(column string, value any) JoinFilter
	Gte(column string, value any) JoinFilter
	In(column string, values any) JoinFilter
	NotIn(column string, values any) JoinFilter
	Like(column, pattern string) JoinFilter
	Null(column string) JoinFilter
	NotNull(column string) JoinFilter
	Between(column string, lowerBound, upperBound any) JoinFilter

	// Logical operators for complex JOIN conditions
	And(filters ...JoinFilter) JoinFilter
	Or(filters ...JoinFilter) JoinFilter

	// Raw escape hatch for complex JOIN conditions
	Raw(condition string, args ...any) JoinFilter
}

type Querier interface {
	// Query executes a SQL query that returns rows, typically a SELECT statement.
	// The caller is responsible for closing the returned rows.
	//
	// The query should use vendor-specific placeholders:
	//   - PostgreSQL: $1, $2, $3
	//   - Oracle: :1, :2, :3
	//   - MongoDB: N/A (query builder handles translation)
	//
	// For vendor-agnostic query construction, use the QueryBuilder.
	Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)

	// QueryRow executes a SQL query that is expected to return at most one row.
	// QueryRow always returns a non-nil value. Errors are deferred until Row's Scan method is called.
	//
	// For vendor-agnostic query construction, use the QueryBuilder.
	QueryRow(ctx context.Context, query string, args ...any) Row

	// Exec executes a SQL statement that doesn't return rows, typically INSERT, UPDATE, or DELETE.
	// The returned sql.Result provides RowsAffected and LastInsertId (if supported by the vendor).
	//
	// For vendor-agnostic query construction, use the QueryBuilder.
	Exec(ctx context.Context, query string, args ...any) (sql.Result, error)

	// DatabaseType returns the vendor identifier for this database connection.
	// Valid values are defined as constants: PostgreSQL, Oracle, MongoDB.
	//
	// This is included in Querier (despite being metadata) because the query builder
	// requires vendor information for placeholder generation and identifier quoting.
	// Including it here prevents forcing all test mocks to implement additional interfaces.
	DatabaseType() string
}

type QueryBuilderInterface interface {
	// Vendor information
	Vendor() string

	// Filter factories
	Filter() FilterFactory
	JoinFilter() JoinFilterFactory

	// Expression builder (v2.1+)
	// Returns error if SQL is empty, too many aliases provided, or alias contains dangerous characters.
	Expr(sql string, alias ...string) (RawExpression, error)

	// MustExpr is like Expr but panics on error.
	// Use this only in static initialization or tests where errors indicate programming bugs.
	MustExpr(sql string, alias ...string) RawExpression

	// Column metadata extraction (v2.4+)
	// Extracts column metadata from structs with `db:"column_name"` tags.
	// Lazily parses struct on first use, caches forever.
	// Returns vendor-specific quoted column names (e.g., Oracle reserved words).
	//
	// Example:
	//   type User struct {
	//       ID    int64  `db:"id"`
	//       Level string `db:"level"` // Oracle reserved word
	//   }
	//   cols := qb.Columns(&User{})
	//   qb.Select(cols.Col("ID"), cols.Col("Level")).From("users")
	//
	//   // With aliasing:
	//   u := cols.As("u")
	//   qb.Select(u.Col("ID"), u.Col("Level")).From(Table("users").As("u"))
	//
	// Panics if structPtr is not a pointer to a struct with db tags.
	Columns(structPtr any) Columns

	// Query builders
	Select(columns ...any) SelectQueryBuilder
	Insert(table string) squirrel.InsertBuilder
	InsertWithColumns(table string, columns ...string) squirrel.InsertBuilder

	// Struct-based INSERT (v2.4+)
	// InsertStruct extracts all fields from a struct instance and creates an INSERT query.
	// Zero-value ID fields (int64/string) are automatically excluded to support auto-increment.
	InsertStruct(table string, instance any) squirrel.InsertBuilder

	// InsertFields extracts only specified fields from a struct instance for INSERT.
	// Useful for partial inserts or when you need explicit control over included fields.
	InsertFields(table string, instance any, fields ...string) squirrel.InsertBuilder

	Update(table string) UpdateQueryBuilder
	Delete(table string) DeleteQueryBuilder

	// Vendor-specific helpers
	BuildCaseInsensitiveLike(column, value string) squirrel.Sqlizer
	BuildUpsert(table string, conflictColumns []string, insertColumns, updateColumns map[string]any) (query string, args []any, err error)

	// Database function builders
	BuildCurrentTimestamp() string
	BuildUUIDGeneration() string
	BuildBooleanValue(value bool) any

	// Identifier escaping
	EscapeIdentifier(identifier string) string
}

type RawExpression struct {
	SQL   string // The raw SQL expression
	Alias string // Optional alias (AS clause)
}

type Row interface {
	Scan(dest ...any) error
	Err() error
}

type SelectQueryBuilder interface {
	// Core SELECT builder methods
	// From accepts either string table names or *TableRef instances with optional aliases
	From(from ...any) SelectQueryBuilder

	// Type-safe JOIN methods with JoinFilter (v2.0+)
	// Each accepts either string table name or *TableRef instance with optional alias
	JoinOn(table any, filter JoinFilter) SelectQueryBuilder
	LeftJoinOn(table any, filter JoinFilter) SelectQueryBuilder
	RightJoinOn(table any, filter JoinFilter) SelectQueryBuilder
	InnerJoinOn(table any, filter JoinFilter) SelectQueryBuilder
	CrossJoinOn(table any) SelectQueryBuilder

	GroupBy(groupBys ...any) SelectQueryBuilder
	Having(pred any, rest ...any) SelectQueryBuilder
	OrderBy(orderBys ...any) SelectQueryBuilder
	Limit(limit uint64) SelectQueryBuilder
	Offset(offset uint64) SelectQueryBuilder
	Paginate(limit, offset uint64) SelectQueryBuilder

	// Composable WHERE clause
	Where(filter Filter) SelectQueryBuilder

	// SQL generation
	ToSQL() (sql string, args []any, err error)
}

type Statement interface {
	// Query execution
	Query(ctx context.Context, args ...any) (*sql.Rows, error)
	QueryRow(ctx context.Context, args ...any) Row
	Exec(ctx context.Context, args ...any) (sql.Result, error)

	// Statement management
	Close() error
}

type TableRef struct {
	// contains filtered or unexported fields
}

type Transactor interface {
	// Begin starts a new transaction with default isolation level.
	// The returned Tx must be committed or rolled back to release resources.
	//
	// Common usage pattern:
	//   tx, err := db.Begin(ctx)
	//   if err != nil { return err }
	//   defer tx.Rollback(ctx)  // No-op if already committed
	//   // ... execute operations on tx ...
	//   return tx.Commit(ctx)
	Begin(ctx context.Context) (Tx, error)

	// BeginTx starts a new transaction with explicit isolation level and read-only settings.
	// Use this when you need precise control over transaction behavior.
	//
	// Common isolation levels (from database/sql):
	//   - sql.LevelDefault: Use database's default isolation
	//   - sql.LevelReadUncommitted: Lowest isolation, allows dirty reads
	//   - sql.LevelReadCommitted: Prevents dirty reads (PostgreSQL default)
	//   - sql.LevelRepeatableRead: Prevents dirty and non-repeatable reads
	//   - sql.LevelSerializable: Highest isolation, full transaction isolation
	//
	// Example (read-only transaction for complex reporting):
	//   tx, err := db.BeginTx(ctx, &sql.TxOptions{
	//       Isolation: sql.LevelRepeatableRead,
	//       ReadOnly:  true,
	//   })
	//
	// Note: Not all databases support all isolation levels. Consult vendor documentation.
	BeginTx(ctx context.Context, opts *sql.TxOptions) (Tx, error)
}

type Tx interface {
	// Query execution within transaction
	Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRow(ctx context.Context, query string, args ...any) Row
	Exec(ctx context.Context, query string, args ...any) (sql.Result, error)

	// Prepared statements within transaction
	Prepare(ctx context.Context, query string) (Statement, error)

	// Transaction control
	// Note: Context is passed to support proper cancellation and tracing.
	// The context should be the same one used to begin the transaction.
	Commit(ctx context.Context) error
	Rollback(ctx context.Context) error
}

type UpdateQueryBuilder interface {
	// Data modification
	Set(column string, value any) UpdateQueryBuilder
	SetMap(clauses map[string]any) UpdateQueryBuilder

	// Struct-based UPDATE (v2.4+)
	// SetStruct extracts field values from a struct instance for UPDATE.
	// If fields are specified, only those fields are updated.
	// If no fields specified, all struct fields are updated.
	SetStruct(instance any, fields ...string) UpdateQueryBuilder

	// Filtering
	Where(filter Filter) UpdateQueryBuilder

	// SQL generation
	ToSQL() (sql string, args []any, err error)
}

type Vendor = string