minitwin 1.0.0

data/lib/minitwin/sync.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+class Minitwin
+  module Sync
+    # Cache constant reference for JIT optimization
+    MODEL_PREFIX = Minitwin::INTERNAL_MODEL_PREFIX
+
+    #: (untyped, validate: bool) -> bool
+    def sync(model = nil, validate: true)
+      # Resolve target model
+      target_model = model
+      if target_model.nil?
+        ivar = self.class.internal_model_name("model")
+        target_model = instance_variable_defined?(ivar) ? instance_variable_get(ivar) : nil
+        if target_model.nil?
+          any_ivar = instance_variables.find { |v| v.to_s.start_with?(MODEL_PREFIX) }
+          target_model = instance_variable_get(any_ivar) if any_ivar
+        end
+      end
+
+      return false if validate && !valid?
+      return false if target_model.nil?
+
+      attribute_methods.each do |method_name| # rubocop: disable Metrics/BlockLength
+        prop_meta = self.class.properties[method_name] || self.class.collections[method_name]
+        as_name = prop_meta&.[](:as)
+        target_name = as_name.is_a?(Symbol) || as_name.is_a?(String) ? as_name.to_sym : method_name
+
+        writer = :"#{target_name}="
+        next unless target_model.respond_to?(writer) || target_model.respond_to?(target_name)
+
+        value = respond_to?(method_name, true) ? send(method_name) : nil
+
+        # Nested twins
+        if value.is_a?(Minitwin)
+          if target_model.respond_to?(target_name)
+            begin
+              child_model = target_model.public_send(target_name)
+              if child_model
+                value.sync(child_model, validate: false)
+                next
+              end
+            rescue StandardError
+              # fall through to writer
+            end
+          end
+        elsif value.is_a?(Array)
+          if target_model.respond_to?(target_name)
+            begin
+              coll = target_model.public_send(target_name)
+              if coll.respond_to?(:each)
+                deep_synced_any = false
+
+                id_map = build_target_id_lookup(coll)
+
+                value.each_with_index do |elem, idx|
+                  next unless elem.is_a?(Minitwin)
+
+                  target = nil
+
+                  # Try id-based match first
+                  target ||= begin
+                    elem_id = elem.respond_to?(:id, true) ? elem.send(:id) : nil
+                    id_map && elem_id ? id_map[elem_id] : nil
+                  end
+
+                  if target.nil? && coll.respond_to?(:[])
+                    begin
+                      target = coll[idx]
+                    rescue StandardError
+                      target = nil
+                    end
+                  end
+
+                  next unless target
+
+                  elem.sync(target, validate: false)
+                  deep_synced_any = true
+                  next
+
+                  # Unmatched elements are handled later by writer fallback
+                end
+
+                next if deep_synced_any
+              end
+            rescue StandardError
+              # continue to writer fallback
+            end
+          end
+        end
+
+        assignable = case value
+                     when Minitwin
+                       value.to_hash
+                     when Array
+                       value.map { |v| v.is_a?(Minitwin) ? v.to_hash : v }
+                     else
+                       value
+                     end
+
+        begin
+          target_model.public_send(writer, assignable)
+        rescue StandardError
+          # ignore and continue
+        end
+      end
+
+      true
+    end
+
+    private
+
+    # Builds a lookup hash from the provided collection.
+    # The collection may be an array or something convertible to an array.
+    # The result is a hash map with the ids of the models in the collection as
+    # keys and the models itself as values.
+    def build_target_id_lookup(coll)
+      ary = if coll.is_a?(Array)
+              coll
+            elsif coll.respond_to?(:to_a)
+              coll.to_a
+            else
+              return nil
+            end
+
+      ary.each_with_object({}) do |m, h|
+        next unless m.respond_to?(:id)
+
+        key = m.id
+        h[key] = m if key
+      end
+    end
+
+    # No append or match_on helpers
+  end
+end

data/lib/minitwin/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Minitwin
+  VERSION = "1.0.0"
+end

data/lib/minitwin.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "json"
+require "zeitwerk"
+begin
+  require "dry-types"
+rescue LoadError
+  # dry-types is an optional dependency
+end
+require_relative "minitwin/version"
+
+begin
+  require "active_model"
+rescue LoadError
+  # active_model is an optional dependency
+end
+
+# Setup Zeitwerk loader for the gem to support Rails autoloading
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+class Minitwin
+  # Constants for internal variable naming
+  INTERNAL_MODEL_PREFIX = "@internal_model__"
+  NESTED_READER_PREFIX = "__nested_read__"
+  DYNAMIC_ALIASES_VAR = "@__dynamic_aliases__"
+  DYNAMIC_ALIASES_REV_VAR = "@__dynamic_aliases_rev__"
+
+  # Shared utility methods
+  module Utils
+    module_function
+
+    # Normalize property name to instance variable name (handles ? suffix)
+    def ivar_name(name)
+      "@#{name}".delete_suffix("?")
+    end
+
+    # Convert instance variable to attribute key symbol
+    def ivar_to_key(ivar)
+      ivar.to_s.delete_prefix("@").to_sym
+    end
+
+    # Traverse a nested path on an object
+    def traverse_path(obj, path)
+      path.each { |seg| obj = obj.public_send(seg) }
+      obj
+    end
+  end
+
+  include ActiveModel::Model if defined?(ActiveModel::Model)
+  include Minitwin::Initialization
+  include Minitwin::Assignment
+  include Minitwin::Serialization
+  include Minitwin::Sync
+  extend  Minitwin::ClassMethods
+
+  # Lazy-memoized lookups for late-loaded optional deps (Dry::Types,
+  # ActiveSupport's HashWithIndifferentAccess). Resolved on first call so
+  # boot-order between minitwin and the deps does not matter.
+  class << self
+    def hash_klass
+      @hash_klass ||= defined?(HashWithIndifferentAccess) ? HashWithIndifferentAccess : Hash
+    end
+
+    private
+
+    def coercion_error_classes
+      @coercion_error_classes ||= begin
+        arr = [TypeError, ArgumentError]
+        arr.unshift(::Dry::Types::CoercionError) if defined?(::Dry::Types::CoercionError)
+        arr.freeze
+      end
+    end
+
+    def active_model_initialized?(klass)
+      return false unless defined?(ActiveModel::API) || defined?(ActiveModel::Model)
+
+      ancestors = klass.ancestors
+      (defined?(ActiveModel::API) && ancestors.include?(ActiveModel::API)) ||
+        (defined?(ActiveModel::Model) && ancestors.include?(ActiveModel::Model))
+    end
+  end
+
+  # Track descendants via WeakMap so anonymous subclasses can be GC'd.
+  # The map lives only on Minitwin itself; subclasses' inherited hooks
+  # delegate up so that deep hierarchies still register on the root.
+  @__descendants_map__ = ObjectSpace::WeakMap.new
+  class << self
+    def __descendants__
+      Minitwin.instance_variable_get(:@__descendants_map__).keys
+    end
+
+    def inherited(sub)
+      Minitwin.instance_variable_get(:@__descendants_map__)[sub] = true
+      super
+    end
+  end
+end
+
+# Optional: Generate RBS on exit when configured via ENV.
+if ENV["MINITWIN_RBS_OUT"] && !ENV["MINITWIN_RBS_OUT"].empty?
+  at_exit do
+    require "fileutils"
+    path = ENV["MINITWIN_RBS_OUT"]
+    begin
+      twins = Minitwin.__descendants__.select(&:name)
+      content = +""
+      content << "# This file is generated by minitwin. DO NOT EDIT.\n"
+      content << "# Generated at: #{Time.now}\n\n"
+      twins.sort_by!(&:name)
+      twins.each do |k|
+        content << k.to_rbs
+        content << "\n\n"
+      end
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, content)
+    rescue StandardError => exception
+      warn "[minitwin] Failed to generate RBS: #{exception.class}: #{exception.message}"
+    end
+  end
+end
+
+require "minitwin/railtie" if defined?(Rails::Railtie)
+# Minitwin
+# --------
+# Entry point that wires together the core modules and conditionally enables
+# ActiveModel integration when it is available. The goal is to keep runtime
+# dependencies minimal while providing a clean DSL for twin/presenter objects.
+# See docs/ARCHITECTURE.md for an overview.

data/lib/tasks/minitwin.rake

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "../minitwin"
+require "fileutils"
+
+namespace :minitwin do
+  desc "Generate RBS signatures for all loaded Minitwin subclasses into sig/generated/ " \
+    "(override output dir with OUTPUT_DIR env var or task argument)"
+
+  task :generate_rbs, [:output_dir] do |_t, args|
+    # In Rails, invoke :environment to ensure the app is fully initialized
+    # before eager loading. We invoke it here rather than declaring it as a
+    # prerequisite because Rails defines :environment *after* running railtie
+    # rake_tasks blocks, so Rake::Task.task_defined?(:environment) is always
+    # false at rake file load time.
+    Rake::Task[:environment].invoke if Rake::Task.task_defined?(:environment)
+
+    # Eager load the rails app if the task runs in Rails context
+    Rails.application.eager_load! if defined?(Rails)
+
+    # Require files "manually" in non-rails projects.
+    # Provide pattern for file paths as ENV var:
+    #
+    # MINITWIN_REQUIRE_GLOB="lib/**/*.rb" rake minitwin:generate_rbs
+    #
+    if (glob = ENV.fetch("MINITWIN_REQUIRE_GLOB", nil))
+      Dir[glob].each { |f| require File.expand_path(f) }
+    end
+
+    output_dir = args[:output_dir] || ENV.fetch("MINITWIN_RBS_DIR", "sig/generated")
+
+    twins = Minitwin.__descendants__.select(&:name).sort_by(&:name)
+
+    if twins.empty?
+      warn "[minitwin] No Minitwin subclasses found. " \
+        "Ensure your classes are loaded before running this task."
+      next
+    end
+
+    twins.each do |klass|
+      file_path = klass.name.
+                    gsub("::", "/").
+                    gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+                    gsub(/([a-z\d])([A-Z])/, '\1_\2').
+                    downcase.
+                    concat(".rbs")
+
+      output_path = File.join(output_dir, file_path)
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, "# Generated by minitwin. DO NOT EDIT.\n\n#{klass.to_rbs}\n")
+      puts "  [minitwin] #{output_path}"
+    end
+  end
+
+  desc "Check that generated RBS signatures are up to date"
+  task :check_rbs do
+    FileUtils.rm_rf(Dir["sig/generated/**/*.rbs"])
+    sh "bundle exec rbs-inline --output lib"
+
+    diff = `git diff --name-only sig/generated`
+    untracked = `git ls-files --others --exclude-standard sig/generated`
+
+    unless diff.empty? && untracked.empty?
+      warn "[minitwin] RBS signatures are out of date. Run: bundle exec rbs-inline --output lib"
+      warn diff unless diff.empty?
+      warn untracked unless untracked.empty?
+      exit 1
+    end
+  end
+end

data/sig/generated/minitwin/assignment.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/minitwin/assignment.rb with RBS::Inline
+
+class Minitwin
+  # Assign/update helpers to merge incoming data into an existing twin.
+  # - assign_object: copy readable attributes from an object and remember it
+  # - assign_hash / assign_params: update only known attributes, recursing into
+  #   nested twins and collection items when possible
+  module Assignment
+    # Mirror values from a model's getters into this twin's setters
+    # : (untyped) -> instance
+    def to_object: (untyped) -> instance
+
+    # : (untyped) -> instance
+    def assign_object: (untyped) -> instance
+
+    # : (Hash[ String | Symbol, untyped ] hash) -> instance
+    def assign_hash: (Hash[String | Symbol, untyped] hash) -> instance
+
+    # 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 assign_params: (untyped params) -> instance
+
+    # Gets the non-readonly methods, which can be assigned with new values.
+    # : () -> Array[Symbol]
+    def assignable_attribute_methods: () -> Array[Symbol]
+  end
+end

data/sig/generated/minitwin/class_methods/caches.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/minitwin/class_methods/caches.rb with RBS::Inline
+
+class Minitwin
+  module ClassMethods
+    module Caches
+      # : () -> bool
+      def dynamic_aliases?: () -> bool
+
+      private
+
+      def invalidate_caches: () -> untyped
+
+      def serializable_getters: () -> untyped
+
+      # Methods defined directly on the twin class hierarchy: this class and any
+      # intermediate Minitwin subclasses, but not Minitwin itself. Methods mixed
+      # in via modules (e.g. ActionView helpers, which include arg-taking methods
+      # like #link_to) are excluded because instance_methods(false) reports only
+      # methods owned by the class, not by included modules.
+      def serializable_method_candidates: () -> untyped
+
+      # Base names of every declared property and collection across the twin
+      # class hierarchy. Only methods whose declaration name is one of these
+      # serialize, so plain getters hand-defined on a twin are excluded. `as:`
+      # aliases pass because #original_name maps them back to the original
+      # property (the aliased reader is made protected and rejected separately).
+      def declared_property_keys: () -> untyped
+
+      # This class and any intermediate Minitwin subclasses, but not Minitwin
+      # itself or mixed-in modules.
+      def twin_class_hierarchy: () -> untyped
+
+      def allowed_attribute_keys: () -> untyped
+
+      def allowed_attribute_keys_array: () -> untyped
+
+      def setter_methods: () -> untyped
+    end
+  end
+end

data/sig/generated/minitwin/class_methods/constructors.rbs

@@ -0,0 +1,41 @@
+# Generated from lib/minitwin/class_methods/constructors.rb with RBS::Inline
+
+class Minitwin
+  module ClassMethods
+    module Constructors
+      # : () -> Hash[untyped, untyped]
+      def properties: () -> Hash[untyped, untyped]
+
+      # : () -> Hash[untyped, untyped]
+      def collections: () -> Hash[untyped, untyped]
+
+      # : (Hash[untyped, untyped] args) -> instance
+      def from_hash: (Hash[untyped, untyped] args) -> instance
+
+      # : (String body) -> instance
+      def from_json: (String body) -> instance
+
+      # 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: (untyped params) -> instance
+
+      # : (untyped model) -> instance
+      def from_object: (untyped model) -> instance
+
+      # : (Hash[Symbol, untyped] **models) -> instance
+      def from_objects: (**untyped models) -> untyped
+
+      # : (Array[untyped] models) -> Array[instance]
+      def from_collection: (Array[untyped] models) -> Array[instance]
+
+      # : (Symbol name) -> String | nil
+      def internal_model_name: (Symbol name) -> String
+
+      def enrich_attributes_from_models!: (untyped attributes, untyped models) -> untyped
+
+      def enrich_attribute_from_models: (untyped attributes, untyped models, untyped key, is_collection: untyped) -> untyped
+    end
+  end
+end

data/sig/generated/minitwin/class_methods/dsl.rbs

@@ -0,0 +1,79 @@
+# Generated from lib/minitwin/class_methods/dsl.rb with RBS::Inline
+
+class Minitwin
+  module ClassMethods
+    module Dsl
+      # : () -> Array[Symbol]
+      def block_properties: () -> Array[Symbol]
+
+      # : () -> Array[Symbol]
+      def collection_properties: () -> Array[Symbol]
+
+      # : () -> Array[Symbol]
+      def unexposed_properties: () -> Array[Symbol]
+
+      # : () -> Array[Symbol]
+      def property_order: () -> Array[Symbol]
+
+      # : () -> Array[Hash]
+      def dynamic_nested_aliases: () -> Array[Hash]
+
+      # @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: (Symbol name, ?validates: Hash[Symbol, untyped], ?default: untyped, ?as: untyped, ?getter: Proc, ?twin: untyped, ?on: Symbol, **untyped _opts) ?{ (?) -> untyped } -> void
+
+      # @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: (Symbol name, ?validates: Hash[Symbol, untyped], ?default: untyped, ?as: untyped, ?expose: bool, ?readonly: bool, ?type: untyped, ?getter: Proc, ?setter: Proc, ?twin: untyped, ?on: Symbol, **untyped _opts) ?{ (?) -> untyped } -> void
+
+      # @rbs name: Symbol
+      # @rbs as: Symbol | Proc
+      # @rbs return: void
+      def nested: (Symbol name, ?as: untyped) ?{ (?) -> untyped } -> void
+
+      private
+
+      def constantize_name: (untyped name) -> untyped
+
+      def create_nested_class: (name: untyped) ?{ (?) -> untyped } -> untyped
+
+      def define_getter_method: (name: untyped, as: untyped, on: untyped, default: untyped, getter: untyped, ?type: untyped) -> untyped
+
+      def build_getter_proc: (name: untyped, on: untyped, default: untyped, getter: untyped, type: untyped) -> untyped
+
+      def build_composition_getter: (name: untyped, on: untyped, default: untyped, type: untyped) -> untyped
+
+      def build_regular_getter: (name: untyped, default: untyped, type: untyped) -> untyped
+
+      def apply_alias_to_getter: (name: untyped, as: untyped) -> untyped
+
+      def add_validation: (name: untyped, validates: untyped) -> untyped
+
+      def add_unexposed_property: (name: untyped, expose: untyped) -> untyped
+
+      def add_block_property: (name: untyped) -> untyped
+
+      def add_collection_property: (name: untyped) -> untyped
+
+      def add_to_property_order: (untyped name) -> untyped
+
+      def resolve_default_value: (untyped default, untyped type) -> untyped
+    end
+  end
+end

data/sig/generated/minitwin/class_methods/rbs.rbs

@@ -0,0 +1,20 @@
+# Generated from lib/minitwin/class_methods/rbs.rb with RBS::Inline
+
+class Minitwin
+  module ClassMethods
+    module Rbs
+      # : () -> String
+      def to_rbs: () -> String
+
+      private
+
+      def rbs_type_for: (untyped meta) -> untyped
+
+      def rbs_elem_type_for: (untyped meta) -> untyped
+
+      def rbs_class_name: (untyped klass) -> untyped
+
+      def dry_type_to_rbs: (untyped dry_type) -> untyped
+    end
+  end
+end

data/sig/generated/minitwin/initialization.rbs

@@ -0,0 +1,45 @@
+# Generated from lib/minitwin/initialization.rb with RBS::Inline
+
+class Minitwin
+  # Instance construction and low-level helpers used by the DSL-generated
+  # accessors. Filters unknown keys on initialize and seeds nested block
+  # properties so that validations on nested twins can run.
+  module Initialization
+    # Cache constant references for JIT optimization
+    ALIASES_VAR: untyped
+
+    ALIASES_REV_VAR: untyped
+
+    # Forbidden method names that should never be aliased for security reasons
+    FORBIDDEN_ALIAS_NAMES: untyped
+
+    # : (**untyped) -> instance
+    def initialize: (**untyped) -> instance
+
+    private
+
+    def assign_attribute: (method: untyped, value: untyped) -> untyped
+
+    def attribute_methods: () -> untyped
+
+    def define_instance_variable: (name: untyped, value: untyped) -> untyped
+
+    # Define or update per-instance alias methods for properties/collections
+    # where `as:` was provided as a Proc. The Proc is executed in the context
+    # of the instance to compute the alias name.
+    def __recompute_dynamic_aliases__: () -> untyped
+
+    def __recompute_aliases_for_collection__: (untyped collection_method) -> untyped
+
+    def __recompute_nested_aliases__: () -> untyped
+
+    def __compute_alias_name__: (untyped as_proc) -> untyped
+
+    def __compute_nested_alias_name__: (untyped entry) -> untyped
+
+    def __apply_dynamic_alias__: (untyped target_method, untyped alias_name) -> untyped
+
+    # Public: expose current dynamic aliases as a Hash of alias_name => target_method
+    def dynamic_aliases: () -> untyped
+  end
+end

data/sig/generated/minitwin/serialization.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/minitwin/serialization.rb with RBS::Inline
+
+class Minitwin
+  # Serialization to Hash/JSON and ActiveModel validation aggregation.
+  # Converts nested twins recursively and preserves array items (dropping only
+  # nil). When ActiveModel validations are available, nested errors are
+  # surfaced on the parent using dot/bracket notation.
+  module Serialization
+    # Cache constant references for JIT optimization
+    ALIASES_VAR: untyped
+
+    NESTED_PREFIX: untyped
+
+    # : (render_nil: bool) -> Hash[Symbol, untyped]
+    def to_hash: (render_nil: bool) -> Hash[Symbol, untyped]
+
+    alias to_h to_hash
+
+    # : (**untyped) -> String
+    def to_json: (**untyped) -> String
+
+    # : () -> Hash[Symbol, untyped]
+    def attributes: () -> Hash[Symbol, untyped]
+
+    # : () -> bool
+    def valid?: () -> bool
+
+    # : () -> String
+    def inspect: () -> String
+
+    # Internal helper for PrettyPrint. Do not call this on your own.
+    # : (PP) -> void
+    def pretty_print: (PP) -> void
+
+    private
+
+    def transform_value_for_serialization: (untyped value) -> untyped
+
+    def ordered_attributes_for_pp: () -> untyped
+
+    def ordered_methods_for_pp: () -> untyped
+
+    def display_name_for: (untyped method) -> untyped
+
+    def dynamic_aliases_for_pp: () -> untyped
+  end
+end

data/sig/generated/minitwin/sync.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/minitwin/sync.rb with RBS::Inline
+
+class Minitwin
+  module Sync
+    # Cache constant reference for JIT optimization
+    MODEL_PREFIX: untyped
+
+    # : (untyped, validate: bool) -> bool
+    def sync: (untyped, validate: bool) -> bool
+
+    private
+
+    # Builds a lookup hash from the provided collection.
+    # The collection may be an array or something convertible to an array.
+    # The result is a hash map with the ids of the models in the collection as
+    # keys and the models itself as values.
+    def build_target_id_lookup: (untyped coll) -> untyped
+  end
+end

data/sig/module.rbs

@@ -0,0 +1,19 @@
+# This should come from Dry Types, but they do not ship rbs signatures.
+
+module Types
+  module Params
+    String: untyped
+    Nil: untyped
+    Date: untyped
+    DateTime: untyped
+    Time: untyped
+    True: untyped
+    False: untyped
+    Bool: untyped
+    Integer: untyped
+    Float: untyped
+    Decimal: untyped
+    Array: untyped
+    Hash: untyped
+  end
+end