ree_lib 1.3.9 → 1.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 237cf0a00005f59af6c0741f79302159d84433b60b63e401baa4ae95ab0dd2ae
-  data.tar.gz: f9c00515a41e9d78fc2c3ac1785d5a8a21d1f4142461537299e4c1678d4a6b61
+  metadata.gz: 9602630839840f13c5b0be8226aea07ddabc2846b22ee90be4d2a2ba64e43aba
+  data.tar.gz: 3bb721b4ccecb67d709d850ca7e56357fe52350a96a1b817d33654a2eed6e759
 SHA512:
-  metadata.gz: c712530b729aa1e48d53de393ee737b7605c233108940e78f09f4561c36b69c413136880f8b72f73f694d4a6ac5ee7e4010d2d46ff2dcdb30450ad1fd2bb9a56
-  data.tar.gz: e148d3f589e0c2863a9b1958d903458407c1646f0fca6ca79c5fb0839893c0bc00059b4a80a9c0b45cf6710e4e9b6802f6a94ee9b8958fa485701164cd99a240
+  metadata.gz: 8afde36de03a451291b092d3449438de32ccd1f3bd5ea1356d1b487e0a91373e3ce9f7a1bd149913c26953274009244ca343c7e1a508aaab2f219b3391a3f190
+  data.tar.gz: b97d9425262c5c99d56c7d23c7069901676594060c40d93c57a9e07a846486bff0cf176c0d39fcff6f77edbdfa239af46261800a7eff74ccb964d2363bc2262d

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../ree
   specs:
-    ree (1.3.3)
+    ree (1.3.5)
       base64
       commander
       logger
@@ -9,7 +9,7 @@ PATH
 PATH
   remote: .
   specs:
-    ree_lib (1.3.9)
+    ree_lib (1.3.10)
       bigdecimal
       binding_of_caller
       i18n

data/lib/ree_lib/packages/ree_dao/package/ree_dao/dataset_extensions.rb

@@ -183,21 +183,23 @@ module ReeDao
       end
 
       def with_mapper(mapper)
-        clone(
-          schema_mapper: mapper || opts[:schema_mapper],
-        ).with_row_proc(
+        m = mapper || opts[:schema_mapper]
+
+        row_proc = if m.nil?
+          Proc.new { |hash| hash }
+        elsif (dto = m.find_strategy(:db_load)&.dto) && dto.include?(ReeDto::DSL)
+          # ree_dto entities skip set_persistence_state anyway; avoid the
+          # per-row ancestor walk entirely
+          Proc.new { |hash| m.db_load(hash) }
+        else
           Proc.new { |hash|
-            m = mapper || opts[:schema_mapper]
-
-            if m
-              entity = m.db_load(hash)
-              self.set_persistence_state(entity, hash)
-              entity
-            else
-              hash
-            end
+            entity = m.db_load(hash)
+            self.set_persistence_state(entity, hash)
+            entity
           }
-        )
+        end
+
+        clone(schema_mapper: m).with_row_proc(row_proc)
       end
 
       private

data/lib/ree_lib/packages/ree_dao/spec/ree_dao/db_load_performance_mode_spec.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+package_require('ree_dao')
+package_require('ree_dto/entity_dsl')
+package_require('ree_dto/dsl')
+
+RSpec.describe "db_load performance mode (dao integration)" do
+  link :build_sqlite_connection, from: :ree_dao
+
+  after do
+    Ree.disable_irb_mode
+    Ree.disable_db_load_performance_mode
+  end
+
+  before :all do
+    connection = build_sqlite_connection({database: 'sqlite_db'})
+
+    if connection.table_exists?(:perf_mode_users)
+      connection.drop_table(:perf_mode_users)
+    end
+
+    connection.create_table :perf_mode_users do
+      primary_key :id
+
+      column :name, 'varchar(256)'
+      column :age, :integer
+    end
+
+    connection.disconnect
+  end
+
+  Ree.enable_irb_mode
+
+  module ReeDaoPerfModeTest
+    include Ree::PackageDSL
+
+    package do
+      depends_on :ree_dao
+    end
+  end
+
+  class ReeDaoPerfModeTest::Db
+    include Ree::BeanDSL
+
+    bean :db do
+      singleton
+      factory :build
+
+      link :build_sqlite_connection, from: :ree_dao
+    end
+
+    def build
+      build_sqlite_connection({database: 'sqlite_db'})
+    end
+  end
+
+  class ReeDaoPerfModeTest::User
+    include ReeDto::EntityDSL
+
+    properties(
+      id: Nilor[Integer],
+      name: String,
+      age: Integer,
+    )
+
+    attr_accessor :name
+  end
+
+  class ReeDaoPerfModeTest::UserDto
+    include ReeDto::DSL
+
+    build_dto do
+      field :id, Nilor[Integer]
+      field :name, String
+      field :age, Integer
+    end
+  end
+
+  # mappers are built at class definition time, so the flag state around each
+  # class body decides which db_load implementation the dao gets
+  Ree.enable_db_load_performance_mode
+
+  class ReeDaoPerfModeTest::CompiledUsersDao
+    include ReeDao::DSL
+
+    dao :compiled_users_dao do
+      link :db
+    end
+
+    table :perf_mode_users
+
+    schema ReeDaoPerfModeTest::User do
+      integer :id, null: true
+      string :name
+      integer :age
+    end
+  end
+
+  class ReeDaoPerfModeTest::CompiledDtoDao
+    include ReeDao::DSL
+
+    dao :compiled_dto_dao do
+      link :db
+    end
+
+    table :perf_mode_users
+
+    schema ReeDaoPerfModeTest::UserDto do
+      integer :id, null: true
+      string :name
+      integer :age
+    end
+  end
+
+  Ree.disable_db_load_performance_mode
+
+  class ReeDaoPerfModeTest::GenericUsersDao
+    include ReeDao::DSL
+
+    dao :generic_users_dao do
+      link :db
+    end
+
+    table :perf_mode_users
+
+    schema ReeDaoPerfModeTest::User do
+      integer :id, null: true
+      string :name
+      integer :age
+    end
+  end
+
+  let(:compiled_dao) { ReeDaoPerfModeTest::CompiledUsersDao.new }
+  let(:compiled_dto_dao) { ReeDaoPerfModeTest::CompiledDtoDao.new }
+  let(:generic_dao) { ReeDaoPerfModeTest::GenericUsersDao.new }
+
+  it "compiles the schema mapper of daos defined with the mode on" do
+    compiled_mapper = ReeDaoPerfModeTest::CompiledUsersDao.instance_variable_get(:@schema_mapper)
+    generic_mapper = ReeDaoPerfModeTest::GenericUsersDao.instance_variable_get(:@schema_mapper)
+
+    expect(compiled_mapper.class.method_defined?(:__generic_db_load, false)).to be true
+    expect(generic_mapper.class.method_defined?(:__generic_db_load, false)).to be false
+  end
+
+  it "reads identical entities through compiled and generic daos" do
+    generic_dao.delete_all
+
+    user = ReeDaoPerfModeTest::User.new(name: 'John', age: 30)
+    generic_dao.put(user)
+
+    from_generic = generic_dao.find(user.id)
+    from_compiled = compiled_dao.find(user.id)
+
+    expect(from_compiled.id).to eq(from_generic.id)
+    expect(from_compiled.name).to eq(from_generic.name)
+    expect(from_compiled.age).to eq(from_generic.age)
+
+    expect(compiled_dao.all.map(&:id)).to eq(generic_dao.all.map(&:id))
+  end
+
+  it "keeps the update round-trip working for entity_dsl entities" do
+    generic_dao.delete_all
+
+    user = ReeDaoPerfModeTest::User.new(name: 'John', age: 30)
+    compiled_dao.put(user)
+
+    loaded = compiled_dao.find(user.id)
+    loaded.name = 'Doe'
+    compiled_dao.update(loaded)
+
+    expect(generic_dao.find(user.id).name).to eq('Doe')
+  end
+
+  it "loads and updates ree_dto entities through the compiled dao" do
+    compiled_dto_dao.delete_all
+
+    dto = ReeDaoPerfModeTest::UserDto.build(id: nil, name: 'Jane', age: 25)
+    compiled_dto_dao.put(dto)
+
+    loaded = compiled_dto_dao.find(dto.id)
+    expect(loaded).to be_a(ReeDaoPerfModeTest::UserDto)
+    expect(loaded.name).to eq('Jane')
+
+    loaded.name = 'Janet'
+    expect(loaded.changed_fields).to eq([:name])
+    compiled_dto_dao.update(loaded)
+
+    expect(compiled_dto_dao.find(dto.id).name).to eq('Janet')
+  end
+end

data/lib/ree_lib/packages/ree_dto/package/ree_dto/dto/dto_class_methods.rb

@@ -32,6 +32,20 @@ module ReeDto::DtoClassMethods
     dto_obj
   end
 
+  # Fast-path constructor used by compiled db_load: takes ownership of attrs
+  # (it becomes @_attrs without copying), so callers must not reuse the hash.
+  # Reads @fields_with_default directly: the contract-wrapped reader would
+  # revalidate the array on every row.
+  def build_from_attrs(attrs)
+    (@fields_with_default || []).each do |field|
+      attrs[field.name] = field.default unless attrs.key?(field.name)
+    end
+
+    dto_obj = allocate
+    dto_obj.instance_variable_set(:@_attrs, attrs)
+    dto_obj
+  end
+
   private
 
   def set_fields(v)

data/lib/ree_lib/packages/ree_dto/spec/ree_dto/build_from_attrs_spec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+package_require("ree_dto/dsl")
+
+RSpec.describe "ReeDto build_from_attrs" do
+  class ReeDto::BuildFromAttrsDto
+    include ReeDto::DSL
+
+    build_dto do
+      field :id, Integer
+      field :name, Nilor[String]
+      field :with_default, Nilor[Integer], default: 7
+    end
+  end
+
+  it "takes ownership of the attrs hash without copying" do
+    attrs = { id: 1, name: "n" }
+    dto = ReeDto::BuildFromAttrsDto.build_from_attrs(attrs)
+
+    expect(dto.attrs).to equal(attrs)
+    expect(dto.id).to eq(1)
+    expect(dto.name).to eq("n")
+  end
+
+  it "fills defaults only for absent keys" do
+    dto = ReeDto::BuildFromAttrsDto.build_from_attrs({ id: 1 })
+    expect(dto.with_default).to eq(7)
+
+    dto = ReeDto::BuildFromAttrsDto.build_from_attrs({ id: 1, with_default: nil })
+    expect(dto.get_value(:with_default)).to eq(nil)
+  end
+
+  it "matches build for identical inputs" do
+    built = ReeDto::BuildFromAttrsDto.build({ id: 1, name: "n" })
+    fast = ReeDto::BuildFromAttrsDto.build_from_attrs({ id: 1, name: "n" })
+
+    expect(fast.attrs).to eq(built.attrs)
+    expect(fast).to eq(built)
+  end
+
+  it "produces a fully functional dto" do
+    dto = ReeDto::BuildFromAttrsDto.build_from_attrs({ id: 1 })
+
+    dto.name = "x"
+    expect(dto.changed_fields).to eq([:name])
+    expect(dto.has_value?(:name)).to be true
+    expect(dto.to_h).to eq({ id: 1, name: "x", with_default: 7 })
+  end
+end

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/db_load_compiler.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# Compiles a specialized :db_load for composite mappers when
+# Ree.db_load_performance_mode? is on at mapper build time.
+#
+# The compiled method handles the hot call shape `db_load(hash)` with no
+# role/filters as straight-line per-field code: values of primitive types
+# skip casting behind a cheap type guard (see AbstractType#db_load_trusted_check),
+# non-trusted types (custom, enums, pg wrappers, nested mappers) are cast as
+# usual, and dto construction goes through a single attrs hash instead of
+# build-then-copy. Every other call shape falls back to the untouched generic
+# method, kept as __generic_db_load.
+#
+# Codegen targets the mapper's anonymous class (each Mapper.build creates
+# one), never the instance: registered mappers are frozen.
+class ReeMapper::DbLoadCompiler
+  class << self
+    def compile(mapper)
+      return if mapper.type # leaf mappers keep their generic delegation
+
+      strategy = mapper.find_strategy(:db_load)
+      return unless strategy
+
+      case (output = strategy.output)
+      when ReeMapper::ReeDtoOutput
+        builder  = "acc = {}"
+        finisher = "DB_LOAD_DTO.build_from_attrs(acc)"
+      when ReeMapper::HashOutput
+        return unless strategy.dto == ::Hash # OpenStruct keeps the generic path
+        builder  = "acc = {}"
+        finisher = "acc"
+      when ReeMapper::ObjectOutput
+        builder  = "acc = DB_LOAD_DTO.allocate"
+        finisher = "acc"
+      else
+        return # StructOutput and unknown outputs keep the generic path
+      end
+
+      klass = mapper.class
+      return if klass.method_defined?(:__generic_db_load, false) # already compiled
+
+      fields = mapper.fields.values
+
+      set_const(klass, :DB_LOAD_FIELDS, fields.freeze)
+      set_const(klass, :DB_LOAD_DTO, strategy.dto)
+      set_const(
+        klass,
+        :DB_LOAD_NESTED_FILTERS,
+        fields.map { _1.fields_filter ? [_1.fields_filter].freeze : nil }.freeze
+      )
+
+      body = fields.each_with_index.filter_map { |field, idx|
+        # the generic loop skips role-scoped fields when role is nil; calls
+        # with an actual role go through the generic fallback
+        next unless field.roles.empty?
+        field_code(field, idx, output, strategy.always_optional)
+      }.join("\n")
+
+      klass.send(:alias_method, :__generic_db_load, :db_load)
+
+      klass.class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def db_load(obj, role: nil, only: nil, except: nil, fields_filters: nil)
+          if role || only || except || fields_filters || !obj.is_a?(::Hash)
+            return __generic_db_load(obj, role: role, only: only, except: except, fields_filters: fields_filters)
+          end
+
+          #{builder}
+          #{body}
+          #{finisher}
+        end
+      RUBY
+
+      # keep the generated source inspectable for debugging
+      klass.instance_variable_set(:@compiled_db_load_source, body)
+
+      nil
+    end
+
+    private
+
+    def field_code(field, idx, output, always_optional)
+      cast_expr = "__dbl_cast(DB_LOAD_FIELDS[#{idx}], v, DB_LOAD_NESTED_FILTERS[#{idx}])"
+      guard = field.type.db_load_trusted_check("v")
+
+      value_expr = if guard == "true"
+        # identity type (any): nil also passes through unchanged, as in the
+        # generic loop where Any#db_load(nil) returns nil
+        "v"
+      elsif guard
+        if field.null
+          "v.nil? ? nil : (#{guard} ? v : #{cast_expr})"
+        else
+          "#{guard} ? v : #{cast_expr}"
+        end
+      else
+        if field.null
+          "v.nil? ? nil : #{cast_expr}"
+        else
+          cast_expr
+        end
+      end
+
+      sym_key = field.from.inspect
+      str_key = field.from_as_str.inspect
+
+      missing_code = if field.optional || always_optional
+        assign(field, output, "DB_LOAD_FIELDS[#{idx}].default") if field.has_default?
+      else
+        <<~RUBY.chomp
+          raise ReeMapper::TypeError.new(
+            "is missing (required field)", DB_LOAD_FIELDS[#{idx}].location, [#{str_key}]
+          )
+        RUBY
+      end
+
+      code = +<<~RUBY
+        if obj.key?(#{sym_key})
+          v = obj[#{sym_key}]
+          #{assign(field, output, value_expr)}
+        elsif obj.key?(#{str_key})
+          v = obj[#{str_key}]
+          #{assign(field, output, value_expr)}
+      RUBY
+
+      if missing_code
+        code << "else\n  #{missing_code}\n"
+      end
+
+      code << "end\n"
+    end
+
+    def assign(field, output, value_expr)
+      if output.is_a?(ReeMapper::ObjectOutput)
+        "acc.instance_variable_set(#{field.name_as_instance_var_name.inspect}, #{value_expr})"
+      else
+        "acc[#{field.name.inspect}] = #{value_expr}"
+      end
+    end
+
+    def set_const(klass, name, value)
+      klass.send(:remove_const, name) if klass.const_defined?(name, false)
+      klass.const_set(name, value)
+    end
+  end
+end

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/mapper.rb

@@ -139,9 +139,34 @@ class ReeMapper::Mapper
   def prepare_dto
     raise ReeMapper::ArgumentError, "mapper should contain at least one field" if fields.empty?
     strategies.each { _1.prepare_dto(fields.keys) }
+
+    if ReeMapper.db_load_performance_mode? && find_strategy(:db_load)
+      ReeMapper::DbLoadCompiler.compile(self)
+    end
+
     nil
   end
 
+  # DbLoadCompiler helpers below are deliberately contract-free: they run
+  # per field per row on the hot path.
+
+  # Guard expression for the wrapped type, or nil when this mapper's db_load
+  # must always be called (composite mappers, wrappers, custom types)
+  def db_load_trusted_check(var)
+    return nil if @type.nil?
+    @type.respond_to?(:db_load_trusted_check) ? @type.db_load_trusted_check(var) : nil
+  end
+
+  # Slow path of compiled db_load: full cast with the same error decoration
+  # as the generic per-field loop
+  def __dbl_cast(field, value, nested_filters)
+    field.type.db_load(value, role: nil, fields_filters: nested_filters)
+  rescue ReeMapper::ErrorWithLocation => e
+    e.prepend_field_name(field.name_as_str)
+    e.location ||= field.location
+    raise e
+  end
+
   contract(Symbol => Nilor[ReeMapper::MapperStrategy])
   def find_strategy(strategy_method)
     strategies.detect { _1.method == strategy_method }

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/mapper_strategy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class ReeMapper::MapperStrategy
-  attr_reader :method, :always_optional
+  attr_reader :method, :always_optional, :output
 
   contract(Symbol, Class, Bool => Any)
   def initialize(method:, dto:, always_optional:)
@@ -61,8 +61,6 @@ class ReeMapper::MapperStrategy
 
   private
 
-  attr_reader :output
-
   def build_output(dto)
     if dto == Hash || (defined?(OpenStruct) && dto == OpenStruct)
       ReeMapper::HashOutput.new(dto)

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/abstract_type.rb

@@ -1,4 +1,13 @@
 class ReeMapper::AbstractType
+  # Ruby expression (as source string) checking that `var` already holds a
+  # correctly-typed DB value, so db_load may return it as-is. Types that
+  # cannot be skipped (custom types, enums, pg wrappers) return nil. The
+  # expression must accept exactly the values for which this type's db_load
+  # is an identity, or db_load semantics change in performance mode.
+  def db_load_trusted_check(var)
+    nil
+  end
+
   private
 
   def truncate(str, limit = 180)

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/any.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 class ReeMapper::Any < ReeMapper::AbstractType
+  def db_load_trusted_check(var)
+    "true"
+  end
+
   contract(Any => Any)
   def serialize(value)
     value

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/bool.rb

@@ -4,6 +4,10 @@ class ReeMapper::Bool < ReeMapper::AbstractType
   TRUE_CAST_VALUES = ['1', 'true', 'on', 1, true].freeze
   FALSE_CAST_VALUES = ['0', 'false', 'off', 0, false].freeze
 
+  def db_load_trusted_check(var)
+    "(true.equal?(#{var}) || false.equal?(#{var}))"
+  end
+
   contract(Any => Bool).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.is_a?(TrueClass) || value.is_a?(FalseClass)

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/date.rb

@@ -3,6 +3,11 @@
 require 'date'
 
 class ReeMapper::Date < ReeMapper::AbstractType
+  # instance_of?, not is_a?: DateTime < Date, and cast converts DateTime
+  def db_load_trusted_check(var)
+    "#{var}.instance_of?(::Date)"
+  end
+
   contract(Any => Date).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.class == Date

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/date_time.rb

@@ -3,6 +3,10 @@
 require 'date'
 
 class ReeMapper::DateTime < ReeMapper::AbstractType
+  def db_load_trusted_check(var)
+    "#{var}.instance_of?(::DateTime)"
+  end
+
   contract(Any => DateTime).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.class == DateTime

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/float.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 class ReeMapper::Float < ReeMapper::AbstractType
+  def db_load_trusted_check(var)
+    "#{var}.is_a?(::Float)"
+  end
+
   contract(Any => Float).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.is_a?(Float)

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/integer.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 class ReeMapper::Integer < ReeMapper::AbstractType
+  def db_load_trusted_check(var)
+    "#{var}.is_a?(::Integer)"
+  end
+
   contract(Any => Integer).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.is_a? Integer

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/rational.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 class ReeMapper::Rational < ReeMapper::AbstractType
+  def db_load_trusted_check(var)
+    "#{var}.is_a?(::Rational)"
+  end
+
   contract(Any => Rational).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.is_a?(Rational)

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/string.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 class ReeMapper::String < ReeMapper::AbstractType
+  def db_load_trusted_check(var)
+    "#{var}.is_a?(::String)"
+  end
+
   contract(Any => String).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.is_a? String

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/time.rb

@@ -3,6 +3,11 @@
 require 'time'
 
 class ReeMapper::Time < ReeMapper::AbstractType
+  # instance_of?: cast accepts subclasses (e.g. Sequel::SQLTime) only via parse paths
+  def db_load_trusted_check(var)
+    "#{var}.instance_of?(::Time)"
+  end
+
   contract(Any => Time).throws(ReeMapper::TypeError)
   def serialize(value)
     if value.class == Time

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper/wrappers/abstract_wrapper.rb

@@ -6,6 +6,11 @@ class ReeMapper::AbstractWrapper
     @subject = field
   end
 
+  # See ReeMapper::AbstractType#db_load_trusted_check. Wrappers always cast.
+  def db_load_trusted_check(var)
+    nil
+  end
+
   private
 
   def truncate(str, limit = 180)

data/lib/ree_lib/packages/ree_mapper/package/ree_mapper.rb

@@ -47,12 +47,18 @@ module ReeMapper
 
   require_relative 'ree_mapper/mapper_strategy'
   require_relative 'ree_mapper/mapper'
+  require_relative 'ree_mapper/db_load_compiler'
   require_relative 'ree_mapper/mapper_factory_proxy'
   require_relative 'ree_mapper/mapper_factory'
 
   require_relative 'ree_mapper/default_factory'
   require_relative 'ree_mapper/dsl'
 
+  # Defensive read: an older ree gem without the flag means the mode is off
+  def self.db_load_performance_mode?
+    Ree.respond_to?(:db_load_performance_mode?) && Ree.db_load_performance_mode?
+  end
+
   def self.get_mapper_factory(mod)
     if !mod.is_a?(Module)
       raise Ree::Error.new("module should be provided", :invalid_dsl_usage)

data/lib/ree_lib/packages/ree_mapper/spec/ree_mapper/benchmarks/db_load_benchmark_spec.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+require 'benchmark'
+
+package_require "ree_mapper"
+package_require "ree_dto/entity_dsl"
+
+# Run with:
+#   REE_BENCHMARK=1 bundle exec rspec ... db_load_benchmark_spec.rb
+# Contracts state is fixed at method definition time, so measure both setups
+# in separate processes: a plain run (contracts on) and NO_CONTRACTS=1.
+RSpec.public_send(ENV["REE_BENCHMARK"] ? :describe : :xdescribe, 'db_load performance mode benchmark') do
+  link :build_mapper_factory, from: :ree_mapper
+  link :build_mapper_strategy, from: :ree_mapper
+
+  after { Ree.disable_db_load_performance_mode }
+
+  ROWS_COUNT = 10_000
+  REPS = 10
+
+  class DbLoadBenchDto
+    include ReeDto::DSL
+
+    build_dto do
+      field :id, Integer
+      field :num2, Integer
+      field :num3, Integer
+      field :num4, Integer
+      field :num5, Integer
+      field :name, String
+      field :s2, String
+      field :s3, String
+      field :s4, String
+      field :s5, String
+      field :active, Bool
+      field :flag2, Bool
+      field :score, Float
+      field :score2, Float
+      field :born_on, Date
+      field :born2, Date
+      field :seen_at, Time
+      field :seen2, Time
+      field :registered_at, DateTime
+      field :payload, Any
+    end
+  end
+
+  class DbLoadBenchEntity
+    include ReeDto::EntityDSL
+
+    properties(
+      id: Nilor[Integer], num2: Nilor[Integer], num3: Nilor[Integer],
+      num4: Nilor[Integer], num5: Nilor[Integer],
+      name: Nilor[String], s2: Nilor[String], s3: Nilor[String],
+      s4: Nilor[String], s5: Nilor[String],
+      active: Nilor[Bool], flag2: Nilor[Bool],
+      score: Nilor[Float], score2: Nilor[Float],
+      born_on: Nilor[Date], born2: Nilor[Date],
+      seen_at: Nilor[Time], seen2: Nilor[Time],
+      registered_at: Nilor[DateTime], payload: Any,
+    )
+  end
+
+  wide_blk = Proc.new do
+    integer :id
+    integer :num2
+    integer :num3
+    integer :num4
+    integer :num5
+    string :name
+    string :s2
+    string :s3
+    string :s4
+    string :s5
+    bool :active
+    bool :flag2
+    float :score
+    float :score2
+    date :born_on
+    date :born2
+    time :seen_at
+    time :seen2
+    date_time :registered_at
+    any :payload
+  end
+
+  mixed_blk = Proc.new do
+    integer :id
+    string :name
+    bool :active
+    date :born_on
+    hash :meta, null: true do
+      date :day
+      integer :num
+    end
+    array :nums, integer, null: true
+  end
+
+  def build_mapper_with_mode(mode_on, dto, blk)
+    mode_on ? Ree.enable_db_load_performance_mode : Ree.disable_db_load_performance_mode
+
+    build_mapper_factory(
+      strategies: [
+        build_mapper_strategy(method: :db_load, dto: dto, always_optional: true)
+      ]
+    ).call.use(:db_load, dto: dto, &blk)
+  ensure
+    Ree.disable_db_load_performance_mode
+  end
+
+  def wide_rows
+    Array.new(ROWS_COUNT) do |i|
+      {
+        id: i, num2: i, num3: i, num4: i, num5: i,
+        name: "name-#{i}", s2: "a", s3: "b", s4: "c", s5: "d",
+        active: true, flag2: false,
+        score: 1.5, score2: 2.5,
+        born_on: Date.new(2020, 1, 1), born2: Date.new(2021, 2, 2),
+        seen_at: Time.at(i).utc, seen2: Time.at(i * 2).utc,
+        registered_at: DateTime.new(2020, 1, 1, 12, 0, 0),
+        payload: { x: i },
+      }
+    end
+  end
+
+  def mixed_rows
+    Array.new(ROWS_COUNT) do |i|
+      {
+        id: i, name: "name-#{i}", active: true, born_on: Date.new(2020, 1, 1),
+        meta: { day: "2020-01-01", num: i }, # string date: the JSONB guard-fallback path
+        nums: [1, 2, 3],
+      }
+    end
+  end
+
+  def report_alloc(label, rows, mapper)
+    GC.start
+    allocated_before = GC.stat(:total_allocated_objects)
+    gc_before = GC.count
+    rows.each { mapper.db_load(_1) }
+    allocated = GC.stat(:total_allocated_objects) - allocated_before
+    gc_runs = GC.count - gc_before
+    puts format("%-28s %10d objects, %3d GC runs per %d rows", label, allocated, gc_runs, rows.size)
+  end
+
+  it 'wide primitive row: generic vs compiled' do
+    rows = wide_rows
+
+    pairs = {
+      "hash dto" => [
+        build_mapper_with_mode(false, Hash, wide_blk),
+        build_mapper_with_mode(true, Hash, wide_blk),
+      ],
+      "ree_dto" => [
+        build_mapper_with_mode(false, DbLoadBenchDto, wide_blk),
+        build_mapper_with_mode(true, DbLoadBenchDto, wide_blk),
+      ],
+      "entity_dsl" => [
+        build_mapper_with_mode(false, DbLoadBenchEntity, wide_blk),
+        build_mapper_with_mode(true, DbLoadBenchEntity, wide_blk),
+      ],
+    }
+
+    puts "\ncontracts: #{Ree::Contracts.no_contracts? ? 'OFF (NO_CONTRACTS)' : 'ON'}"
+
+    Benchmark.bmbm do |x|
+      pairs.each do |name, (generic, compiled)|
+        x.report("generic  #{name}") { REPS.times { rows.each { generic.db_load(_1) } } }
+        x.report("compiled #{name}") { REPS.times { rows.each { compiled.db_load(_1) } } }
+      end
+    end
+
+    puts "\nallocations:"
+    pairs.each do |name, (generic, compiled)|
+      report_alloc("generic  #{name}", rows, generic)
+      report_alloc("compiled #{name}", rows, compiled)
+    end
+  end
+
+  it 'mixed row with nested hash and array: generic vs compiled' do
+    rows = mixed_rows
+    generic = build_mapper_with_mode(false, DbLoadBenchDto, mixed_blk)
+    compiled = build_mapper_with_mode(true, DbLoadBenchDto, mixed_blk)
+
+    Benchmark.bmbm do |x|
+      x.report("generic  mixed") { REPS.times { rows.each { generic.db_load(_1) } } }
+      x.report("compiled mixed") { REPS.times { rows.each { compiled.db_load(_1) } } }
+    end
+
+    puts "\nallocations:"
+    report_alloc("generic  mixed", rows, generic)
+    report_alloc("compiled mixed", rows, compiled)
+  end
+end
+
+# Results (2026-08-16, Ruby 4.0.1, 10_000 rows x 10 reps, real seconds):
+#
+# contracts: ON
+#                            generic    compiled   speedup
+#   wide (20 fields) hash      60.53s      0.41s     ~149x
+#   wide ree_dto               74.76s      0.43s     ~174x
+#   wide entity_dsl            63.78s      0.36s     ~175x
+#   mixed (jsonb-like)         37.23s      5.43s     ~6.9x
+#
+#   allocations per 10_000 rows:
+#   wide hash        15_820_000 -> 10_000      wide ree_dto  18_350_000 -> 20_000
+#   wide entity_dsl  15_820_000 -> 10_000      mixed          8_930_000 -> 1_190_000
+#   GC runs: 40-46 -> 0 (wide), 72 -> 9 (mixed)
+#
+# contracts: OFF (NO_CONTRACTS=1)
+#                            generic    compiled   speedup
+#   wide (20 fields) hash       2.54s      0.42s     ~6.0x
+#   wide ree_dto                2.77s      0.43s     ~6.4x
+#   wide entity_dsl             2.43s      0.39s     ~6.2x
+#   mixed (jsonb-like)          2.52s      1.21s     ~2.1x
+#
+#   allocations per 10_000 rows:
+#   wide hash        220_000 -> 10_000          wide ree_dto  260_000 -> 20_000
+#   wide entity_dsl  220_000 -> 10_000          mixed         360_000 -> 200_000

data/lib/ree_lib/packages/ree_mapper/spec/ree_mapper/db_load_performance_mode_spec.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+package_require "ree_mapper"
+package_require "ree_dto/entity_dsl"
+
+RSpec.describe "db_load performance mode" do
+  link :build_mapper_factory, from: :ree_mapper
+  link :build_mapper_strategy, from: :ree_mapper
+
+  after do
+    Ree.disable_db_load_performance_mode
+  end
+
+  class PerfModeDto
+    include ReeDto::DSL
+
+    build_dto do
+      field :id, Integer
+      field :name, String
+    end
+  end
+
+  class PerfModeEntity
+    include ReeDto::EntityDSL
+
+    properties(
+      id: Nilor[Integer],
+      name: Nilor[String],
+    )
+  end
+
+  def build_factory(dto:, always_optional: true)
+    build_mapper_factory(
+      strategies: [
+        build_mapper_strategy(method: :db_load, dto: dto, always_optional: always_optional)
+      ]
+    )
+  end
+
+  # builds the same mapper twice: with the mode off (generic path) and on
+  # (compiled path), so examples can assert identical behavior
+  def build_pair(dto: Hash, always_optional: true, register_as: nil, &blk)
+    Ree.disable_db_load_performance_mode
+    generic = build_factory(dto: dto, always_optional: always_optional)
+      .call(register_as: register_as).use(:db_load, dto: dto, &blk)
+
+    Ree.enable_db_load_performance_mode
+    compiled = build_factory(dto: dto, always_optional: always_optional)
+      .call(register_as: register_as).use(:db_load, dto: dto, &blk)
+    Ree.disable_db_load_performance_mode
+
+    [generic, compiled]
+  end
+
+  def expect_same_result(generic, compiled, input, **opts)
+    generic_result = begin; generic.db_load(input, **opts); rescue => e; e; end
+    compiled_result = begin; compiled.db_load(input, **opts); rescue => e; e; end
+
+    if generic_result.is_a?(Exception)
+      expect(compiled_result.class).to eq(generic_result.class)
+      expect(compiled_result.message).to eq(generic_result.message)
+    else
+      expect(compiled_result).to eq(generic_result)
+    end
+
+    compiled_result
+  end
+
+  wide_blk = Proc.new do
+    integer :id
+    string :name
+    bool :active
+    float :score, null: true
+    date :born_on, null: true
+    time :seen_at, null: true
+    date_time :registered_at, null: true
+    rational :ratio, null: true
+    any :payload, null: true
+    integer :renamed, from: :src
+    string? :note, default: "-"
+    integer? :maybe
+    integer :admin_count, role: :admin
+    hash :meta, null: true do
+      date :day
+      integer :num
+    end
+    array :nums, integer, null: true
+  end
+
+  def wide_row
+    {
+      id: 1,
+      name: "n",
+      active: true,
+      score: 1.5,
+      born_on: Date.new(2020, 1, 1),
+      seen_at: Time.at(0).utc,
+      registered_at: DateTime.new(2020, 1, 1, 12, 0, 0),
+      ratio: Rational(1, 2),
+      payload: { x: 1 },
+      src: 5,
+      note: "hi",
+      maybe: 2,
+      meta: { day: "2020-01-01", num: 3 },
+      nums: [1, 2],
+    }
+  end
+
+  it "compiles db_load when the mode is on and keeps the generic fallback" do
+    _generic, compiled = build_pair(&wide_blk)
+
+    expect(compiled.class.method_defined?(:__generic_db_load, false)).to be true
+    expect(compiled.class.const_defined?(:DB_LOAD_FIELDS, false)).to be true
+  end
+
+  it "does not compile when the mode is off" do
+    generic, _compiled = build_pair(&wide_blk)
+
+    expect(generic.class.method_defined?(:__generic_db_load, false)).to be false
+  end
+
+  context "parity with the generic path" do
+    it "loads a full row identically" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row)
+
+      expect(result[:id]).to eq(1)
+      expect(result[:renamed]).to eq(5)
+      expect(result[:meta][:day]).to eq(Date.new(2020, 1, 1)) # JSONB-style string is still cast
+      expect(result[:nums]).to eq([1, 2])
+      expect(result.key?(:admin_count)).to be false
+    end
+
+    it "still coerces values that fail the type guard" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row.merge(id: "5", score: 2))
+
+      expect(result[:id]).to eq(5)
+      expect(result[:score]).to eq(2.0)
+      expect(result[:score]).to be_a(Float)
+    end
+
+    it "raises the same error for nil in a null: false field" do
+      generic, compiled = build_pair(&wide_blk)
+      error = expect_same_result(generic, compiled, wide_row.merge(name: nil))
+
+      expect(error).to be_a(ReeMapper::TypeError)
+      expect(error.message).to include("`name`")
+    end
+
+    it "raises the same error for garbage that fails coercion" do
+      generic, compiled = build_pair(&wide_blk)
+      error = expect_same_result(generic, compiled, wide_row.merge(id: "abc"))
+
+      expect(error).to be_a(ReeMapper::CoercionError)
+      expect(error.message).to include("`id`")
+    end
+
+    it "raises the same error from a nested mapper with the field path" do
+      generic, compiled = build_pair(&wide_blk)
+      error = expect_same_result(generic, compiled, wide_row.merge(meta: { day: "not a date", num: 1 }))
+
+      expect(error).to be_a(ReeMapper::CoercionError)
+      expect(error.message).to include("`meta[day]`")
+    end
+
+    it "assigns nil without casting for null: true fields" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(
+        generic, compiled,
+        wide_row.merge(score: nil, born_on: nil, meta: nil, nums: nil, payload: nil)
+      )
+
+      expect(result[:score]).to be_nil
+      expect(result[:meta]).to be_nil
+    end
+
+    it "applies defaults and skips missing optional fields" do
+      generic, compiled = build_pair(&wide_blk)
+      row = wide_row
+      row.delete(:note)
+      row.delete(:maybe)
+      result = expect_same_result(generic, compiled, row)
+
+      expect(result[:note]).to eq("-")
+      expect(result.key?(:maybe)).to be false
+    end
+
+    it "skips missing fields when the strategy is always_optional" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, { id: 1 })
+
+      expect(result).to eq({ id: 1, note: "-" })
+    end
+
+    it "raises for missing required fields when the strategy is not always_optional" do
+      generic, compiled = build_pair(always_optional: false) do
+        integer :id
+        string? :name
+      end
+      error = expect_same_result(generic, compiled, { name: "n" })
+
+      expect(error).to be_a(ReeMapper::TypeError)
+      expect(error.message).to include("`id` is missing (required field)")
+    end
+
+    it "supports string-keyed input" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, { "id" => 1, "name" => "n" })
+
+      expect(result[:id]).to eq(1)
+    end
+
+    it "falls back to the generic path for non-Hash input" do
+      generic, compiled = build_pair(&wide_blk)
+      input = OpenStruct.new(id: 1, name: "n")
+      result = expect_same_result(generic, compiled, input)
+
+      expect(result[:id]).to eq(1)
+    end
+
+    it "falls back to the generic path for role calls" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row.merge(admin_count: 7), role: :admin)
+
+      expect(result[:admin_count]).to eq(7)
+    end
+
+    it "falls back to the generic path for only/except calls" do
+      generic, compiled = build_pair(&wide_blk)
+      result = expect_same_result(generic, compiled, wide_row, only: [:id, :name])
+
+      expect(result.keys).to contain_exactly(:id, :name)
+    end
+
+    it "respects field-level only filters on nested mappers" do
+      generic, compiled = build_pair do
+        integer :id
+        hash :meta, null: true, only: [:num] do
+          date :day, null: true
+          integer :num
+        end
+      end
+      result = expect_same_result(generic, compiled, { id: 1, meta: { day: "2020-01-01", num: 3 } })
+
+      expect(result[:meta]).to eq({ num: 3 })
+    end
+  end
+
+  context "dto outputs" do
+    it "builds ree_dto entities" do
+      generic, compiled = build_pair(dto: PerfModeDto) do
+        integer :id
+        string :name
+      end
+
+      generic_dto = generic.db_load({ id: 1, name: "n" })
+      compiled_dto = compiled.db_load({ id: 1, name: "n" })
+
+      expect(compiled_dto).to be_a(PerfModeDto)
+      expect(compiled_dto.id).to eq(generic_dto.id)
+      expect(compiled_dto.name).to eq(generic_dto.name)
+      expect(compiled_dto.attrs).to eq(generic_dto.attrs)
+    end
+
+    it "builds entity_dsl objects via instance variables" do
+      generic, compiled = build_pair(dto: PerfModeEntity) do
+        integer :id
+        string :name
+      end
+
+      generic_entity = generic.db_load({ id: 1, name: "n" })
+      compiled_entity = compiled.db_load({ id: 1, name: "n" })
+
+      expect(compiled_entity).to be_a(PerfModeEntity)
+      expect(compiled_entity.id).to eq(generic_entity.id)
+      expect(compiled_entity.name).to eq(generic_entity.name)
+    end
+
+    it "keeps the generic path for struct dto" do
+      Ree.enable_db_load_performance_mode
+      mapper = build_factory(dto: Struct).call.use(:db_load, dto: Struct) do
+        integer :id
+      end
+      Ree.disable_db_load_performance_mode
+
+      expect(mapper.class.method_defined?(:__generic_db_load, false)).to be false
+      expect(mapper.db_load({ id: 1 }).id).to eq(1)
+    end
+  end
+
+  context "registered (frozen) mappers" do
+    it "compiles mappers registered via register_as" do
+      generic, compiled = build_pair(register_as: :perf_mode_frozen, &wide_blk)
+
+      expect(compiled.frozen?).to be true
+      expect(compiled.class.method_defined?(:__generic_db_load, false)).to be true
+      expect_same_result(generic, compiled, wide_row)
+    end
+  end
+
+  describe "guard/cast identity invariant" do
+    {
+      ReeMapper::Integer => [1, -5, 10**20],
+      ReeMapper::String => ["s", ""],
+      ReeMapper::Bool => [true, false],
+      ReeMapper::Float => [1.5, -0.0],
+      ReeMapper::Date => [Date.new(2020, 1, 1)],
+      ReeMapper::Time => [Time.at(0).utc],
+      ReeMapper::DateTime => [DateTime.new(2020, 1, 1)],
+      ReeMapper::Rational => [Rational(1, 2)],
+      ReeMapper::Any => [1, "s", nil, [1], { a: 1 }],
+    }.each do |type_class, values|
+      it "#{type_class}: guard implies db_load is identity" do
+        type = type_class.new
+        check = type.db_load_trusted_check("v")
+
+        values.each do |v|
+          expect(eval(check)).to be(true), "guard rejected #{v.inspect} for #{type_class}"
+          expect(type.db_load(v)).to equal(v)
+        end
+      end
+    end
+
+    it "guards reject values that db_load would convert" do
+      {
+        ReeMapper::Integer.new => "5",
+        ReeMapper::Float.new => 2,
+        ReeMapper::Date.new => DateTime.new(2020, 1, 1),
+        ReeMapper::Time.new => DateTime.new(2020, 1, 1),
+        ReeMapper::DateTime.new => Time.at(0).utc,
+        ReeMapper::Rational.new => "1/2",
+        ReeMapper::Bool.new => 1,
+      }.each do |type, v|
+        check = type.db_load_trusted_check("v")
+        expect(eval(check)).to be(false), "guard accepted #{v.inspect} for #{type.class}"
+      end
+    end
+  end
+end

data/lib/ree_lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ReeLib
-  VERSION = "1.3.9"
+  VERSION = "1.3.10"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ree_lib
 version: !ruby/object:Gem::Version
-  version: 1.3.9
+  version: 1.3.10
 platform: ruby
 authors:
 - Ruslan Gatiyatov
@@ -303,6 +303,7 @@ files:
 - lib/ree_lib/packages/ree_dao/package/ree_dao/thread_parents.rb
 - lib/ree_lib/packages/ree_dao/package/ree_dao/wrappers/pg_array.rb
 - lib/ree_lib/packages/ree_dao/package/ree_dao/wrappers/pg_jsonb.rb
+- lib/ree_lib/packages/ree_dao/spec/ree_dao/db_load_performance_mode_spec.rb
 - lib/ree_lib/packages/ree_dao/spec/ree_dao/functions/build_dto_spec.rb
 - lib/ree_lib/packages/ree_dao/spec/ree_dao/functions/build_pg_connection_spec.rb
 - lib/ree_lib/packages/ree_dao/spec/ree_dao/functions/build_sqlite_connection/max_connections_spec.rb
@@ -624,6 +625,7 @@ files:
 - lib/ree_lib/packages/ree_dto/package/ree_dto/entity_dsl.rb
 - lib/ree_lib/packages/ree_dto/package/ree_dto/functions/build_dto.rb
 - lib/ree_lib/packages/ree_dto/package/ree_dto/functions/build_dto_collection_class.rb
+- lib/ree_lib/packages/ree_dto/spec/ree_dto/build_from_attrs_spec.rb
 - lib/ree_lib/packages/ree_dto/spec/ree_dto/dsl_spec.rb
 - lib/ree_lib/packages/ree_dto/spec/ree_dto/entity_dsl_spec.rb
 - lib/ree_lib/packages/ree_dto/spec/spec_helper.rb
@@ -763,6 +765,7 @@ files:
 - lib/ree_lib/packages/ree_mapper/.rspec
 - lib/ree_lib/packages/ree_mapper/bin/console
 - lib/ree_lib/packages/ree_mapper/package/ree_mapper.rb
+- lib/ree_lib/packages/ree_mapper/package/ree_mapper/db_load_compiler.rb
 - lib/ree_lib/packages/ree_mapper/package/ree_mapper/default_factory.rb
 - lib/ree_lib/packages/ree_mapper/package/ree_mapper/dsl.rb
 - lib/ree_lib/packages/ree_mapper/package/ree_mapper/errors/argument_error.rb
@@ -797,7 +800,9 @@ files:
 - lib/ree_lib/packages/ree_mapper/package/ree_mapper/types/time.rb
 - lib/ree_lib/packages/ree_mapper/package/ree_mapper/wrappers/abstract_wrapper.rb
 - lib/ree_lib/packages/ree_mapper/package/ree_mapper/wrappers/array.rb
+- lib/ree_lib/packages/ree_mapper/spec/ree_mapper/benchmarks/db_load_benchmark_spec.rb
 - lib/ree_lib/packages/ree_mapper/spec/ree_mapper/benchmarks/mapper_benchmark_spec.rb
+- lib/ree_lib/packages/ree_mapper/spec/ree_mapper/db_load_performance_mode_spec.rb
 - lib/ree_lib/packages/ree_mapper/spec/ree_mapper/dsl/dsl_spec.rb
 - lib/ree_lib/packages/ree_mapper/spec/ree_mapper/functions/build_mapper_factory_spec.rb
 - lib/ree_lib/packages/ree_mapper/spec/ree_mapper/functions/build_mapper_strategy_spec.rb