minitwin 1.0.0

data/lib/minitwin/class_methods/coercion.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+class Minitwin
+  module ClassMethods
+    module Coercion
+      private
+
+      # Iterate over all attribute sources (properties, collections, and allowed keys)
+      # for a target class, yielding each key to the block
+      def iterate_attribute_sources(target_klass, &block)
+        return unless target_klass
+        return unless target_klass.respond_to?(:allowed_attribute_keys, true)
+
+        target_klass.send(:allowed_attribute_keys).each(&block)
+      end
+
+      def coerce_value_to_twin(value, target_klass)
+        return nil if value.nil?
+        return value unless target_klass
+        return value if value.is_a?(target_klass)
+
+        # Check array pair format before to_h (arrays respond to :to_h in Ruby 3+)
+        return coerce_from_array_pair(value, target_klass) if array_pair_format?(value)
+        # Try standard conversion methods
+        return coerce_from_to_h(value, target_klass) if value.respond_to?(:to_h) && !value.is_a?(Array)
+        return coerce_from_attributes(value, target_klass) if value.respond_to?(:attributes)
+        return target_klass.new(**value) if value.is_a?(Hash)
+
+        # Fallback: reflect by reading known properties or instance variables
+        coerce_by_reflection(value, target_klass)
+      end
+
+      def coerce_from_to_h(value, target_klass)
+        attrs = value.to_h
+        enrich_attrs_from_readers!(attrs, value, target_klass)
+        target_klass.new(**attrs)
+      end
+
+      def coerce_from_attributes(value, target_klass)
+        attrs = value.attributes
+        enrich_attrs_from_readers!(attrs, value, target_klass)
+        target_klass.new(**attrs)
+      end
+
+      def array_pair_format?(value)
+        value.is_a?(Array) && value.size == 2 && value.last.is_a?(Hash)
+      end
+
+      def coerce_from_array_pair(value, target_klass)
+        target_klass.new(**value.last)
+      end
+
+      def coerce_by_reflection(value, target_klass)
+        attrs = extract_attrs_by_reflection(value, target_klass)
+        attrs = extract_instance_variables(value) if attrs.empty?
+        attrs.empty? ? value : target_klass.new(**attrs)
+      end
+
+      def extract_attrs_by_reflection(value, target_klass)
+        attrs = {}
+        begin
+          iterate_attribute_sources(target_klass) do |key|
+            next if attrs.key?(key)
+
+            attrs[key] = value.public_send(key) if value.respond_to?(key)
+          end
+        rescue StandardError
+          # Expected: Reflection may fail if source object raises in attribute readers
+          # or has unexpected behavior. Continue with partial attributes.
+        end
+        attrs
+      end
+
+      def extract_instance_variables(value)
+        return {} unless value.respond_to?(:instance_variables) && value.instance_variables.any?
+
+        value.instance_variables.to_h do |var|
+          [Minitwin::Utils.ivar_to_key(var), value.instance_variable_get(var)]
+        end
+      end
+
+      def enrich_attrs_from_readers!(attrs, source, target_klass)
+        return attrs unless target_klass
+
+        begin
+          # Enrich from properties and allowed attribute keys
+          iterate_attribute_sources(target_klass) do |key|
+            next if attrs.key?(key) && !attrs[key].nil?
+            next unless source.respond_to?(key)
+
+            # Special handling for collections to ensure array coercion
+            attrs[key] = if target_klass.respond_to?(:collections) && target_klass.collections.key?(key)
+                           coerce_collection_array(source.public_send(key))
+                         else
+                           source.public_send(key)
+                         end
+          end
+        rescue StandardError
+          # Expected: Source object may raise in attribute readers or have
+          # unexpected behavior. Be resilient and proceed with partial attributes.
+        end
+
+        attrs
+      end
+
+      def coerce_collection_array(raw)
+        return raw if raw.is_a?(Array)
+        return raw.to_a if raw.respond_to?(:to_a)
+
+        Array(raw)
+      end
+    end
+  end
+end

data/lib/minitwin/class_methods/constructors.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Minitwin
+  module ClassMethods
+    module Constructors
+
+      #: () -> Hash[untyped, untyped]
+      def properties
+        @properties ||= {}
+      end
+
+      #: () -> Hash[untyped, untyped]
+      def collections
+        @collections ||= {}
+      end
+
+      #: (Hash[untyped, untyped] args) -> instance
+      def from_hash(args)
+        new(**args)
+      end
+
+      #: (String body) -> instance
+      def from_json(body)
+        hash = JSON.parse(body, symbolize_names: true)
+        from_hash(hash)
+      end
+
+      # Actually, this is expected to be an `ActionController::Parameters`
+      # object. The type will be unknown when used without rails. So for RBS
+      # the argument is typed `untyped`.
+      #: (untyped params) -> instance
+      def from_params(params)
+        return from_hash(params) unless params.respond_to?(:to_unsafe_h)
+
+        from_hash params.to_unsafe_h
+      end
+
+      #: (untyped model) -> instance
+      def from_object(model)
+        if model.is_a?(Hash)
+          raise(
+            "Input is not an object. If you want to instantiate a Minitwin with multiple " \
+              "objects, then use the pluralized 'from_objects'-method."
+          )
+        end
+
+        from_objects(model:)
+      end
+
+      #: (Hash[Symbol, untyped] **models) -> instance
+      def from_objects(**models)
+        attributes =
+          models.values.map do |model|
+            if model.respond_to?(:attributes) && model.respond_to?(:attribute_aliases)
+              combined_attributes = model.attributes.dup
+              model.attribute_aliases.each do |alias_name, real_attr|
+                combined_attributes[alias_name] = model.send(real_attr)
+              end
+              combined_attributes
+            elsif model.respond_to?(:to_h)
+              model.to_h
+            elsif model.respond_to?(:attributes)
+              model.attributes
+            else
+              extract_instance_variables(model)
+            end
+          end.reduce({}, :merge)
+
+        # Enrich attributes with relation-style readers (e.g., has_one/has_many)
+        # when they are not present in the model's attributes hash. This allows
+        # nested block/twin properties and collections to be populated from
+        # object readers commonly used by ORMs like ActiveRecord.
+        enrich_attributes_from_models!(attributes, models)
+
+        obj = new(**attributes)
+        models.each { |name, model| obj.instance_variable_set(internal_model_name(name), model) }
+        obj
+      end
+
+      #: (Array[untyped] models) -> Array[instance]
+      def from_collection(models)
+        models.map { |item| from_objects(model: item) }
+      end
+
+      #: (Symbol name) -> String | nil
+      def internal_model_name(name)
+        "#{Minitwin::INTERNAL_MODEL_PREFIX}#{name}" unless name.nil?
+      end
+
+      def enrich_attributes_from_models!(attributes, models)
+        properties.each_key do |key|
+          enrich_attribute_from_models(attributes, models, key, is_collection: false)
+        end
+
+        collections.each_key do |key|
+          enrich_attribute_from_models(attributes, models, key, is_collection: true)
+        end
+      rescue StandardError
+        # Expected: Model objects may raise in attribute readers or have unexpected
+        # behavior. Be resilient and proceed with best-effort enrichment.
+      end
+
+      def enrich_attribute_from_models(attributes, models, key, is_collection:)
+        # Only enrich when attribute is missing or nil
+        return if attributes.key?(key) && !attributes[key].nil?
+
+        models.each_value do |model|
+          next unless model.respond_to?(key)
+
+          val = model.public_send(key)
+          next if val.nil?
+
+          attributes[key] = is_collection ? coerce_collection_array(val) : val
+          break
+        end
+      end
+    end
+  end
+end

data/lib/minitwin/class_methods/dsl.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Minitwin
+  module ClassMethods
+    module Dsl
+
+      #: () -> Array[Symbol]
+      def block_properties
+        @block_properties ||= []
+      end
+
+      #: () -> Array[Symbol]
+      def collection_properties
+        @collection_properties ||= []
+      end
+
+      #: () -> Array[Symbol]
+      def unexposed_properties
+        @unexposed_properties ||= []
+      end
+
+      #: () -> Array[Symbol]
+      def property_order
+        @property_order ||= []
+      end
+
+      #: () -> Array[Hash]
+      def dynamic_nested_aliases
+        @dynamic_nested_aliases ||= []
+      end
+
+      # @rbs name: Symbol
+      # @rbs validates: Hash[Symbol, untyped]
+      # @rbs default: untyped
+      # @rbs as: Symbol | Proc
+      # @rbs getter: Proc
+      # @rbs twin: untyped
+      # @rbs on: Symbol
+      # @rbs return: void
+      def collection(name, validates: {}, default: [], as: nil, getter: nil, twin: nil, on: nil, **_opts, &block)
+        nested_class = block ? create_nested_class(name:, &block) : nil
+        element_klass = twin || nested_class
+
+        define_method("#{name}=") do |values|
+          arr = self.class.send(:coerce_collection_array, values)
+          coerced_values = arr.map { |v| self.class.send(:coerce_value_to_twin, v, element_klass) }
+          define_instance_variable(name:, value: coerced_values)
+          # :nocov:
+          if !@__skip_alias_recompute__ && self.class.dynamic_aliases?
+            __recompute_dynamic_aliases__
+          end
+          # :nocov:
+        end
+        alias_method "#{name}_attributes=", "#{name}="
+
+        define_getter_method(name:, on:, as:, default:, getter:, type: nil)
+        alias_method "#{name}_attributes", name
+        add_validation(name:, validates:)
+        add_collection_property(name:)
+        invalidate_caches
+
+        collections[name.to_sym] = { element_twin: element_klass, as: as }
+        add_to_property_order(name)
+      end
+
+      # @rbs name: Symbol
+      # @rbs validates: Hash[Symbol, untyped]
+      # @rbs default: untyped
+      # @rbs as: Symbol | Proc
+      # @rbs expose: bool
+      # @rbs readonly: bool
+      # @rbs type: untyped
+      # @rbs getter: Proc
+      # @rbs setter: Proc
+      # @rbs twin: untyped
+      # @rbs on: Symbol
+      # @rbs return: void
+      def property(
+        name, validates: {}, default: nil, as: nil, expose: true, readonly: false, type: nil, getter: nil, setter: nil,
+        twin: nil, on: nil, **_opts, &block
+      )
+        nested_class = nil
+
+        if block_given?
+          raise "setters are not possible in blocks" if setter
+
+          nested_class = create_nested_class(name:, &block)
+
+          define_method("#{name}=") do |value|
+            coerced = self.class.send(:coerce_value_to_twin, value, nested_class)
+            raise "Unprocessable input for property '#{name}'." unless coerced.nil? || coerced.is_a?(nested_class)
+
+            define_instance_variable(name:, value: coerced)
+            if !@__skip_alias_recompute__ && self.class.dynamic_aliases?
+              __recompute_dynamic_aliases__
+            end
+          end
+
+          add_block_property(name:)
+        else
+          define_method("#{name}=") do |value|
+            coerced_value =
+              if twin
+                self.class.send(:coerce_value_to_twin, value, twin)
+              elsif setter
+                setter.call(value)
+              elsif type && !value.nil?
+                self.class.send(:coerce_with_type, value, type)
+              else
+                value
+              end
+            define_instance_variable(name:, value: coerced_value)
+            if !@__skip_alias_recompute__ && self.class.dynamic_aliases?
+              __recompute_dynamic_aliases__
+            end
+          end
+        end
+
+        define_getter_method(name:, as:, on:, default:, getter:, type: type)
+        add_validation(name:, validates:)
+        add_unexposed_property(name:, expose:)
+        invalidate_caches
+
+        properties[name.to_sym] = {
+          type: type,
+          as: as,
+          expose: expose,
+          readonly: readonly
+        }
+        properties[name.to_sym][:twin] = twin if twin
+        properties[name.to_sym][:nested_class] = nested_class if nested_class
+        add_to_property_order(name)
+      end
+
+      # @rbs name: Symbol
+      # @rbs as: Symbol | Proc
+      # @rbs return: void
+      def nested(name, as: nil, &block)
+        raise ArgumentError, "nested requires a block" unless block_given?
+
+        property(name, as: as, &block)
+
+        # Pull the nested class directly from the registration `property`
+        # just performed instead of round-tripping through `const_get`.
+        nested_klass = properties[name.to_sym]&.[](:nested_class)
+
+        # Registry for dynamic nested aliases (as: -> { ... }) on leafs.
+        # Reader defined once in the module body above.
+        leafs = []
+        if nested_klass.respond_to?(:properties)
+          extract_leaf_properties = ->(klass, path) do
+            klass.properties.each do |prop, meta|
+              if meta[:nested_class]
+                extract_leaf_properties.call(meta[:nested_class], path + [prop])
+              else
+                leafs << { path: (path + [prop]), as: (meta[:as] if meta[:as] && meta[:as] != prop) }
+              end
+            end
+          end
+          extract_leaf_properties.call(nested_klass, [])
+        end
+
+        leafs.each do |leaf| # rubocop: disable Metrics/BlockLength
+          path = leaf[:path]
+          prop = path.last
+          as_meta = leaf[:as]
+
+          # Define a stable internal reader for this leaf to support dynamic aliasing
+          target_reader = "#{Minitwin::NESTED_READER_PREFIX}#{([name] + path).join("__")}"
+          define_method(target_reader) do
+            obj = send(name)
+            obj = Minitwin::Utils.traverse_path(obj, path[0..-2])
+            if as_meta.is_a?(Proc)
+              # When inner property has a dynamic alias, original reader may be protected.
+              obj.send(prop)
+            else
+              inner_read = as_meta || prop
+              # Use send to allow accessing protected original readers
+              obj.send(inner_read)
+            end
+          end
+
+          # Setter uses original base name to call the nested twin's writer.
+          define_method("#{prop}=") do |value|
+            obj = send(name)
+            obj = Minitwin::Utils.traverse_path(obj, path[0..-2])
+            obj.public_send("#{prop}=", value)
+            if !@__skip_alias_recompute__ && self.class.dynamic_aliases?
+              __recompute_dynamic_aliases__
+            end
+          end
+
+          # Static alias: define a public getter method with the alias name
+          if as_meta && !as_meta.is_a?(Proc)
+            alias_name = as_meta
+            define_method(alias_name) do
+              send(target_reader)
+            end
+            unexposed_properties << alias_name
+
+            # Define protected getter with original name so sync can read the value,
+            # and register in properties so sync resolves the as: alias.
+            define_method(prop) { send(target_reader) }
+            protected prop
+            properties[prop.to_sym] = { type: nil, as: as_meta, expose: true, nested_proxy: true }
+          else
+            # Dynamic alias: register for instance-level aliasing and rely on
+            # __recompute_dynamic_aliases__ to create the per-instance method.
+            dynamic_nested_aliases << { target: target_reader.to_sym, as: as_meta || prop, group: name, path: path }
+          end
+
+          # Always hide the internal reader from serialization
+          unexposed_properties << target_reader.to_sym
+        end
+
+        invalidate_caches
+      end
+
+      private
+
+      def constantize_name(name)
+        name.to_s.split("_").map(&:capitalize).join
+      end
+
+      def create_nested_class(name:, &block)
+        Class.new(Minitwin).tap do |klass|
+          if defined?(ActiveModel::Name)
+            klass.define_singleton_method(:model_name) do
+              ActiveModel::Name.new(self, nil, name.to_s)
+            end
+          end
+
+          klass.class_eval(&block) if block
+
+          const_name = constantize_name(name)
+          begin
+            const_set(const_name, klass) unless const_defined?(const_name, false)
+          rescue NameError
+            # Expected: Constant name may be invalid or already defined in complex scenarios.
+            # The nested class is still accessible via the klass variable.
+          end
+        end
+      end
+
+      def define_getter_method(name:, as:, on:, default:, getter:, type: nil)
+        getter_proc = build_getter_proc(name:, on:, default:, getter:, type:)
+        define_method(name, &getter_proc)
+        apply_alias_to_getter(name:, as:)
+      end
+
+      def build_getter_proc(name:, on:, default:, getter:, type:)
+        if getter
+          ivar = Minitwin::Utils.ivar_name(name)
+          if getter.is_a?(Symbol)
+            return -> {
+              if self.class.instance_method(getter).arity.zero?
+                send(getter)
+              else
+                send(getter, instance_variable_get(ivar))
+              end
+            }
+          elsif getter.arity.zero?
+            return -> { instance_exec(&getter) }
+          else
+            return -> { instance_exec(instance_variable_get(ivar), &getter) }
+          end
+        end
+
+        if on
+          build_composition_getter(name:, on:, default:, type:)
+        else
+          build_regular_getter(name:, default:, type:)
+        end
+      end
+
+      def build_composition_getter(name:, on:, default:, type:)
+        # Resolve model ivar name at definition time when on is a symbol
+        model_ivar = on.is_a?(Proc) ? nil : internal_model_name(on)
+        # Collection metadata will be resolved after property registration
+        # via a lazy lookup on first access, then cached in the closure.
+        col_meta = nil
+        col_meta_resolved = false
+
+        -> { # rubocop: disable Metrics/BlockLength
+          # Get composition model - handle both symbol and proc cases
+          model = if on.is_a?(Proc)
+                    instance_exec(&on)
+                  else
+                    instance_variable_get(model_ivar) || begin
+                      send(on)
+                    rescue NoMethodError
+                      nil
+                    end
+                  end
+
+          # Validate model
+          if model.nil?
+            raise(
+              "Property '#{name}' refers to unknown composition source '#{on}' in #{self.class}. " \
+                "Ensure the model is provided via from_objects or a reader exists."
+            )
+          end
+          unless model.respond_to?(name)
+            raise "The instance of '#{model.class}' does not respond to '#{name}'."
+          end
+
+          raw = model.send(name)
+
+          # Return default if raw is nil
+          return self.class.send(:resolve_default_value, default, type) if raw.nil?
+
+          # Resolve collection metadata once and cache in closure
+          unless col_meta_resolved
+            col_meta = begin
+              self.class.collections[name.to_sym]
+            rescue StandardError
+              nil
+            end
+            col_meta_resolved = true
+          end
+
+          if col_meta && (raw.is_a?(Array) || raw.respond_to?(:to_a))
+            elem_klass = col_meta[:element_twin]
+            arr = self.class.send(:coerce_collection_array, raw)
+            arr.map { |v| self.class.send(:coerce_value_to_twin, v, elem_klass) }
+          else
+            type ? self.class.send(:coerce_with_type, raw, type) : raw
+          end
+        }
+      end
+
+      def build_regular_getter(name:, default:, type:)
+        # Compute ivar_name at definition time for JIT optimization.
+        # Type coercion happens on assignment (setter) so the getter just reads.
+        ivar = Minitwin::Utils.ivar_name(name)
+        -> {
+          if instance_variable_defined?(ivar)
+            val = instance_variable_get(ivar)
+            return self.class.send(:resolve_default_value, default, type) if val.nil?
+
+            val
+          else
+            self.class.send(:resolve_default_value, default, type)
+          end
+        }
+      end
+
+      def apply_alias_to_getter(name:, as:)
+        return if as.nil?
+
+        if as.is_a?(Proc)
+          # Dynamic alias: protect original reader and let instances
+          # compute and define the alias method at runtime.
+          protected name
+        elsif name != as
+          alias_method as, name
+          protected name
+        end
+      end
+
+      def add_validation(name:, validates:)
+        return if validates.nil?
+        return if validates.respond_to?(:empty?) && validates.empty?
+
+        raise "Validation is not possible, because activemodel is not available" unless respond_to?(:validates)
+
+        if validates.is_a?(Proc)
+          validate do
+            value = send(name)
+            errors.add(name, "is invalid") unless validates.call(value)
+          end
+        else
+          validates(name, **validates)
+        end
+      end
+
+      def add_unexposed_property(name:, expose:)
+        unexposed_properties << name unless expose
+      end
+
+      def add_block_property(name:)
+        block_properties << name.to_sym
+      end
+
+      def add_collection_property(name:)
+        collection_properties << name.to_sym
+      end
+
+      def add_to_property_order(name)
+        key = name.to_sym
+        property_order << key unless property_order.include?(key)
+      end
+
+      def resolve_default_value(default, type)
+        unless default.nil?
+          return default.respond_to?(:call) ? default.call : default
+        end
+
+        type ? type_default_value(type) : nil
+      end
+    end
+  end
+end