database

type DBTX interface {
	Exec(context.Context, string, ...any) (pgconn.CommandTag, error)
	Query(context.Context, string, ...any) (pgx.Rows, error)
	QueryRow(context.Context, string, ...any) pgx.Row
}

type Database interface {
	// Disconnect closes the database connection pool and sets the teardown flag to true.
	// This method should be called when the application is shutting down to ensure all resources are released properly.
	// It sets the isTeardown flag to true to indicate that the database connection is being torn down.
	// This prevents any further operations on the database connection pool after it has been closed.
	//
	// If `noTeardown` is true, it will not set the teardown flag,
	// allowing the client to be reused later.
	// // If `noTeardown` is false or not provided, it will set the teardown flag
	// and close the client connection, preventing any further operations.
	Disconnect(noTeardown ...bool)
	// WithReadTX executes a function within a read-only database transaction context.
	// If an existing transaction is provided via existingQ, it uses that instead of creating a new transaction.
	// Otherwise, it begins a new read-only transaction, executes the provided function with the transaction-aware dbtx,
	// and commits the transaction on success or rolls back on error.
	// The function automatically handles transaction cleanup through deferred rollback.
	// This method is optimized for read operations and may provide better performance for queries that don't modify data.
	//
	// Parameters:
	// - ctx: Context for the transaction operation
	// - fn: Function to execute within the transaction, receives a transaction interface
	// - existingQ: Optional existing transaction to reuse instead of creating a new transaction
	//
	// Returns:
	// - error: Any error from transaction operations or the executed function
	WithReadTX(ctx context.Context, fn func(tx DBTX) error, existingQ ...DBTX) error
	// WithTX executes a function within a database transaction context.
	// If an existing transaction is provided via existingQ, it uses that instead of creating a new transaction.
	// Otherwise, it begins a new read-write transaction, executes the provided function with the transaction-aware dbtx,
	// and commits the transaction on success or rolls back on error.
	// The function automatically handles transaction cleanup through deferred rollback.
	//
	// Parameters:
	// - ctx: Context for the transaction operation
	// - fn: Function to execute within the transaction, receives a transaction interface
	// - existingQ: Optional existing transaction to reuse instead of creating a new transaction
	//
	// Returns:
	// - error: Any error from transaction operations or the executed function
	WithTX(ctx context.Context, fn func(tx DBTX) error, existingQ ...DBTX) error
}

type Page[T any] struct {
	Content          []T         `json:"content"`
	Pageable         PageRequest `json:"pageable"`
	TotalElements    int64       `json:"totalElements"`
	TotalPages       int         `json:"totalPages"`
	Number           int         `json:"number"`
	Size             int         `json:"size"`
	NumberOfElements int         `json:"numberOfElements"`
	IsLast           bool        `json:"last"`
	IsFirst          bool        `json:"first"`
	IsEmpty          bool        `json:"empty"`
}

type PageRequest struct {
	Page int      `query:"page" json:"page"` // The requested page number (0-indexed)
	Size int      `query:"size" json:"size"` // The number of items per page
	Sort []string `query:"sort" json:"sort"` // A slice of sort commands, e.g., "name,desc"
}