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 {
	// TableName returns the exact database table identifier linked to this entity.
	TableName() string

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

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

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

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

	// PKExternal indicates whether the entity's primary key comes from
	// an external identifier provided by the system context, rather
	// than from the database itself (This value is commonly 'false').
	PKExternal() bool

	// 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

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

	// 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)
}

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"`
}