xdb

type CustomQuery[R any] struct {
	SQL     string
	Args    []any
	Scanner RowScanner[R]
}

type DBConfig struct {
	Driver                string        `json:"driver"`
	DSN                   string        `json:"dsn"`
	MigrationsDirPath     string        `json:"migrationsDirPath"`
	MaxOpenConnections    int           `json:"maxOpenConnections"`
	MaxIdleConnections    int           `json:"maxIdleConnections"`
	ConnectionMaxLifetime time.Duration `json:"connectionMaxLifetime"`
	SQLite                SQLiteConfig  `json:"sqlite"`

	DB *sql.DB
}

type DBGeneric[T any, PT interface {
	*T
	Entity
}] struct {
	// contains filtered or unexported fields
}

type Entity interface {
	// Normalize cleanses and standardizes internal field values before processing (e.g., trimming whitespace or altering casing).
	Normalize()

	// Validate performs fail-fast domain business rules checking, returning false and a distinct status code upon failure.
	Validate() (bool, xerrors.ErrorCode)

	// TableName returns the exact database table identifier linked to this entity.
	TableName() string

	// Columns yields the sequence of table columns targeted for INSERT/UPDATE actions, strictly excluding database-managed values.
	Columns() []string

	// Values yields the field records mapped in the exact corresponding sequence order specified by Columns().
	Values() []any

	// TablePK returns the physical database primary key column identifier (e.g., "id" or "key").
	TablePK() string

	// BindPK allows the repository engine to inject database-generated or application-generated identifiers back into the instance memory pointer.
	BindPK(id any)

	// PKValue returns the current snapshot value of the primary key field (e.g., an int64 ID or a string UUID).
	PKValue() any

	// ScanRow hydrats the entire entity fields from an active database query cursor row result, mapping all table columns sequentially.
	ScanRow(rows *sql.Rows) error

	// GeneratePK creates an application-side unique identifier, returning nil if the key lifecycle is delegated to the database engine.
	GeneratePK() any

	// IsNaturalPK indicates whether the entity primary key is a natural identifier supplied from an external context outside the system.
	IsNaturalPK() bool
}

type RowScanner[R any] func(rows *sql.Rows) (R, error)

type SQLExecutor interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

type SQLiteConfig struct {
	Mode        string            `json:"mode"`
	Dir         string            `json:"dir"`
	FileName    string            `json:"fileName"`
	QueryString string            `json:"querystring"`
	Pragma      map[string]string `json:"pragma"`
}