///|
pub fn bytes_to_hex(data : Bytes) -> String {
  let out = @buffer.new(size_hint=data.length() * 2)
  for b in data {
    let v = b.to_int()
    let hi = (v >> 4) & 0x0f
    let lo = v & 0x0f
    out.write_string(
      if hi < 10 {
        "\{hi}"
      } else {
        "\{('a'.to_int() + hi - 10).to_char()}"
      },
    )
    out.write_string(
      if lo < 10 {
        "\{lo}"
      } else {
        "\{('a'.to_int() + lo - 10).to_char()}"
      },
    )
  }
  out.to_string()
}

///|
pub fn decode_json_column(
  value : Json,
  storage : String,
) -> Json raise ParamDecodeError {
  match storage {
    "bson" =>
      match @bson.json_bytes_to_bytes(value) {
        Some(data) =>
          @bson.from_bytes(data) catch {
            @bson.BsonError(msg) =>
              raise ParamDecodeError("BSON decode error: \{msg}")
          }
        None => value
      }
    _ => value
  }
}

///|
pub(all) enum WhereType {
  Eq
  Ne
  Gt
  Lt
  Gte
  Lte
  Like
} derive(Eq, Show, ToJson, FromJson)

///|
pub(all) struct Where {
  col : String
  value : Param
  ty : WhereType
} derive(Eq, Show, ToJson, FromJson)

///|
pub(all) enum OrderBy {
  Asc(String)
  Desc(String)
} derive(Eq, Show, ToJson, FromJson)

///|
pub(all) struct Set {
  col : String
  value : Param
} derive(Eq, Show, ToJson, FromJson)

///|
pub(open) trait QueryBuilder {
  to_statement(Self) -> Statement
}

///|
pub(open) trait Engine {
  /// Render SQL and params from query builder statement.
  render(Self, stmt : Statement) -> (String, FixedArray[Param])
  ///|
  /// Transaction begin SQL for current engine.
  tx_begin_sql(Self) -> String
  ///|
  /// Transaction commit SQL for current engine.
  tx_commit_sql(Self) -> String
  ///|
  /// Transaction rollback SQL for current engine.
  tx_rollback_sql(Self) -> String
  ///|
  /// Savepoint SQL for current engine.
  tx_savepoint_sql(Self, name : String) -> String
  ///|
  /// Rollback-to-savepoint SQL for current engine.
  tx_rollback_to_savepoint_sql(Self, name : String) -> String
  ///|
  /// Apply table migration from schema JSON generated by morm.Table::to_json().
  async migrate_table(Self, table_schema : Json) -> QueryResult
  ///|
  /// Execute raw SQL statement directly. Keep this for custom SQL in mapper.
  async exec_raw(Self, sql : String, params : FixedArray[Param]) -> QueryResult
  ///|
  /// Execute belongs-to preload and return rows keyed by target key.
  async preload_belongs_to_json(
    Self,
    target_table : String,
    target_key : String,
    key_params : FixedArray[Param],
  ) -> Map[String, Json]
  ///|
  /// Execute has-one preload and return rows keyed by target key.
  async preload_has_one_json(
    Self,
    target_table : String,
    target_key : String,
    key_params : FixedArray[Param],
  ) -> Map[String, Json]
  ///|
  /// Execute has-many preload and return grouped rows keyed by target key.
  async preload_has_many_json(
    Self,
    target_table : String,
    target_key : String,
    key_params : FixedArray[Param],
  ) -> Map[String, Array[Json]]
  ///|
  /// Execute many-to-many preload and return grouped rows keyed by owner key.
  async preload_many_to_many_json(
    Self,
    target_table : String,
    target_key : String,
    join_table : String,
    join_owner_key : String,
    join_target_key : String,
    key_params : FixedArray[Param],
  ) -> Map[String, Array[Json]]
  ///|
  /// Close the database connection.
  close(Self) -> Unit
}