model-mapper 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d815217a42e717db82be8fb900d733a5b74447fefb0276afaa6bee4e0a8bc1ca
-  data.tar.gz: 3c46647c66ce79bd951883461c283372f195d95a0addc65208390bb7fad940a3
+  metadata.gz: 775e838aa683bcb13a626497d487253ea1e23c27eef15df92a92d99ffdad19f8
+  data.tar.gz: 39b2177d2a088282f16135540f0cbfd9fef501699981bb358981e96b0f6ebdb8
 SHA512:
-  metadata.gz: 8a2b61232b59e1fc1626a7a68cd1f52e9b14851e8252211af28419eb7b18b0f4e37be2d4150d98f39ecafae66b66a50037dcca24043565295b49ac823a3bad24
-  data.tar.gz: 392885dc229cc27060917c74c1aaeb6aca4f197366477993c60933fc2c05d4f115e91384ff22b17c08ba343c7a1b1bc62b98f8677bca6b8f36213f27bb364229
+  metadata.gz: 0ec1989c92c08271125531e1809a845bae74d85b8d23276fd2ac084ed20db8ebcd80966efd44bc82c6264fbb326a92c26ca68abfa82b851fa73e3de0da54d784
+  data.tar.gz: 7179f959eccb52dee9d34ca3c8be8572b19f49b97b08c05e4366a889a8dd720a17b3d557fa93989b7610bb43e956eee28e8ef49d35cb607360281a413ef8d072

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## [0.2.0](https://github.com/dougyouch/mappable/compare/v0.1.0...v0.2.0) (2026-10-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **mapping:** the internal Mapping instance methods map_data, skip?, get_value, call_method and call_map_method are removed.
+
+### Features
+
+* **mappable:** add map_from_<name> to copy data back from the destination ([2b1503f](https://github.com/dougyouch/mappable/commit/2b1503f5a619b77f1d2e342ecf06d5ff429c1392))
+
+
+### Bug Fixes
+
+* **mappable:** support map_to on anonymous classes and stop modifying options ([a5b3b7f](https://github.com/dougyouch/mappable/commit/a5b3b7f1ea0b2477f2213cd3e9c28fcdecda0934))
+* **utils:** keep capital letters when building mapping class names ([5160516](https://github.com/dougyouch/mappable/commit/5160516a1d10bd9cf8593a34496bf95ee13a3330))
+
+
+### Performance Improvements
+
+* **mapping:** compile mappings into plain ruby methods ([8854abb](https://github.com/dougyouch/mappable/commit/8854abb763f976bbc76a4bd7cc00e9c1dde50908))

data/README.md

@@ -1,5 +1,228 @@
-# mappable
+# Mappable
 
-[![Build Status](https://travis-ci.org/dougyouch/mappable.svg?branch=master)](https://travis-ci.org/dougyouch/mappable)
-[![Maintainability](https://api.codeclimate.com/v1/badges/ac5801c8775694186c58/maintainability)](https://codeclimate.com/github/dougyouch/mappable/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/ac5801c8775694186c58/test_coverage)](https://codeclimate.com/github/dougyouch/mappable/test_coverage)
+Fast, declarative two-way mapping between Ruby objects. Declare once how the fields of one object map to another, and Mappable compiles it into plain Ruby methods that copy the data in either direction at close to hand-written speed.
+
+[![CI](https://github.com/dougyouch/mappable/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/dougyouch/mappable/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/dougyouch/mappable/badges/coverage.svg)](https://github.com/dougyouch/mappable/actions/workflows/ci.yml)
+[![Branch Coverage](https://raw.githubusercontent.com/dougyouch/mappable/badges/branches.svg)](https://github.com/dougyouch/mappable/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/model-mapper.svg)](https://rubygems.org/gems/model-mapper)
+
+[API reference](https://rubydoc.info/gems/model-mapper) · [Changelog](CHANGELOG.md) · [Architecture](ARCHITECTURE.md)
+
+## Installation
+
+Requires Ruby 3.2 or newer. The gem is published as `model-mapper`:
+
+```ruby
+gem 'model-mapper'
+```
+
+```ruby
+require 'model-mapper' # Bundler does this for you
+```
+
+## Quick Start
+
+Map a `User` to a `Contact`, combining `first_name` and `last_name` into `name`, and split `name` back out on the way back:
+
+```ruby
+User = Struct.new(:first_name, :last_name, :email)
+Contact = Struct.new(:name, :email_address)
+
+class User
+  include Mappable
+
+  map_to(:contact) do
+    # user -> contact
+    custom_map(:name) { |user| "#{user.first_name} #{user.last_name}" }
+
+    # contact -> user
+    custom_map_back(:first_name) { |contact| contact.name.split(' ', 2).first }
+    custom_map_back(:last_name) { |contact| contact.name.split(' ', 2).last }
+
+    # both directions: email -> email_address and email_address -> email
+    map :email, :email_address
+  end
+end
+
+user = User.new('Ada', 'Lovelace', 'ada@example.com')
+
+contact = user.map_to_contact(Contact.new)
+contact.name          # => "Ada Lovelace"
+contact.email_address # => "ada@example.com"
+
+copy = User.new.map_from_contact(contact)
+copy.first_name # => "Ada"
+copy.last_name  # => "Lovelace"
+copy.email      # => "ada@example.com"
+```
+
+`map_to(:contact)` creates a mapping class, `User::ContactMapping`, and two instance methods:
+
+| Method | Does | Returns |
+|---|---|---|
+| `map_to_contact(dest)` | copies the user's fields to `dest` | `dest` |
+| `map_from_contact(src)` | copies the fields of `src` back to the user | the user |
+
+Any objects work as long as they have getters for the fields being read and setters (`name=`) for the fields being written: Structs, plain Ruby classes, ActiveRecord or ActiveModel models.
+
+## Declaring Mappings
+
+### `map`: copy a field, both ways
+
+```ruby
+map :email                  # email -> email,         and back
+map :email, :email_address  # email -> email_address, and email_address -> email
+```
+
+### `custom_map`: compute a field
+
+`custom_map` sets a destination field from a block, or from a method on the mapping class. It's one-way; declare the reverse with `custom_map_back`.
+
+```ruby
+map_to(:contact) do
+  custom_map(:name) { |user| "#{user.first_name} #{user.last_name}" }
+
+  custom_map :initials                 # calls initials(user)
+  custom_map :display_name, :full_name # calls full_name(user)
+
+  def initials(user)
+    "#{user.first_name[0]}#{user.last_name[0]}"
+  end
+
+  private
+
+  def full_name(user) # custom methods can be private
+    [user.first_name, user.last_name].compact.join(' ')
+  end
+end
+```
+
+### `custom_map_back`: compute a field on the way back
+
+`custom_map_back` sets a field on the source object from the destination object. It takes the same arguments as `custom_map`.
+
+```ruby
+custom_map_back(:first_name) { |contact| contact.name.split(' ', 2).first }
+custom_map_back :last_name # calls last_name(contact)
+```
+
+## Conditions
+
+Skip a field unless a condition holds. Every mapping method takes these options:
+
+| Option | Checked on |
+|---|---|
+| `if:` / `unless:` | the mapping instance |
+| `if_src:` / `unless_src:` | the object being read from |
+| `if_dest:` / `unless_dest:` | the object being written to |
+
+A condition is a method name, called on that object, or a proc, run with that object as `self` and passed as its argument. A lambda that takes no arguments works too.
+
+```ruby
+map_to(:contact) do
+  map :email, :email_address, if_src: :email_verified?
+  map :phone, unless_dest: :phone_locked?
+  map :notes, if: -> { include_notes }
+  map :status, unless_src: ->(user) { user.status.nil? }
+
+  attr_accessor :include_notes
+end
+```
+
+Each `map` call also declares the reverse mapping, and the reverse swaps `_src` and `_dest` conditions so they still check the same object. In the example above, `if_src: :email_verified?` checks the user in both directions: on the way to the contact the user is the source, and on the way back it's the destination.
+
+When a field has several conditions, all of them must pass.
+
+## Using Mapping Classes Directly
+
+The mapping class is a regular class you can instantiate, which is how you pass it state such as the `include_notes` flag above:
+
+```ruby
+mapping = User::ContactMapping.new
+mapping.include_notes = true
+mapping.map(user, Contact.new)     # => the contact
+mapping.map_back(contact, User.new) # => the user
+```
+
+You can also define mapping classes without `map_to`:
+
+```ruby
+class ContactMapping
+  include Mappable::Mapping
+
+  map :email, :email_address
+end
+
+ContactMapping.new.map(user, Contact.new)
+```
+
+### `map_to` options
+
+```ruby
+# name the mapping class (defaults to ContactMapping, set as a constant of the including class)
+map_to(:contact, class_name: 'PersonMapper') { ... }
+
+# inherit mappings from another mapping class and add to them
+map_to(:admin_contact, base_class: User::ContactMapping) do
+  map :role
+end
+```
+
+A subclass gets the mappings its base class had when the subclass declared its first mapping. Declare a base class's mappings before you subclass it.
+
+### Inspecting mappings
+
+`mappings` and `map_back_mappings` return the options for each field. Any extra options you pass, such as a description, are kept:
+
+```ruby
+map :email, :email_address, description: 'primary email'
+
+User::ContactMapping.mappings[:email_address]
+# => {src: :email, getter: "email", dest: :email_address, setter: "email_address=", description: "primary email"}
+
+User.maps # => {contact: User::ContactMapping}
+```
+
+## Performance
+
+Mappable doesn't interpret the mapping hash at runtime. Each `map`, `custom_map` or `custom_map_back` call regenerates the mapping class's `map` and `map_back` methods as straight-line Ruby, so mapping an object is a list of getter and setter calls:
+
+```ruby
+map :email, :email_address, if_dest: :persisted?
+custom_map(:name) { |user| "#{user.first_name} #{user.last_name}" }
+
+# compiles to
+def map(src_model, dest_model)
+  dest_model.email_address = src_model.email if dest_model.persisted?
+  dest_model.name = MAPPABLE_PROCS[0].call(src_model)
+  dest_model
+end
+```
+
+Mapping 9 fields between Structs (one computed field, one condition), on Ruby 4.0.7 without YJIT:
+
+| | ns per object |
+|---|---|
+| hand-written assignments | 490 |
+| `map_to_contact` (this version) | 636 |
+| `map_to_contact` (model-mapper 0.1.0) | 4560 |
+
+Recompiling happens when mappings are declared, so declare them when your classes load, not per request.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec    # tests, with line and branch coverage in coverage/
+bundle exec rubocop  # lint
+bundle exec yard     # API docs in doc/
+```
+
+CI runs RuboCop, requires every public API to have YARD docs, and runs the specs on Ruby 3.2 and on the Ruby in `.ruby-version`, where it requires 100% line and branch coverage.
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please): [conventional commits](https://www.conventionalcommits.org/) on `master` keep a release PR up to date, and merging it tags the release and publishes the gem to RubyGems.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mappable/class_methods.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Mappable
+  # Class methods added by including {Mappable}
+  module ClassMethods
+    # @return [Hash{Symbol => Class}] mapping classes by name, as declared with {#map_to}
+    def maps
+      {}.freeze
+    end
+
+    # Creates a mapping class, a constant of this class, and two instance methods that use it:
+    #
+    # - `map_to_<name>(dest)` copies this object's fields to `dest` and returns `dest`
+    # - `map_from_<name>(src)` copies the fields of `src` back to this object and returns `self`
+    #
+    # @example
+    #   class User
+    #     include Mappable
+    #
+    #     map_to(:contact) do
+    #       map :email, :email_address
+    #     end
+    #   end
+    #
+    #   user.map_to_contact(Contact.new) # => the contact, with email_address set
+    #   User.new.map_from_contact(contact) # => the user, with email set
+    #
+    # @param name [Symbol, String] names the methods and the mapping class (`:contact` creates `ContactMapping`)
+    # @param options [Hash] see {Mapping.create}
+    # @yield evaluated in the mapping class, to declare its mappings (see {Mapping::ClassMethods})
+    # @return [Class] the mapping class
+    def map_to(name, options = {}, &)
+      mapping = Mapping.create(self, name, options, &)
+      add_value_to_class_method(:maps, name.to_sym => mapping)
+      # referenced by its constant name, resolved from this class, so anonymous classes work too
+      mapping_const = mapping.name.split('::').last
+
+      class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def map_to_#{name}(dest)                   # def map_to_contact(dest)
+          #{mapping_const}.new.map(self, dest)     #   ContactMapping.new.map(self, dest)
+        end                                        # end
+
+        def map_from_#{name}(src)                  # def map_from_contact(src)
+          #{mapping_const}.new.map_back(src, self) #   ContactMapping.new.map_back(src, self)
+        end                                        # end
+      RUBY
+
+      mapping
+    end
+  end
+end

data/lib/mappable/compiler.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Mappable
+  # Turns mapping options into the source of a Ruby method, so running a mapping is a
+  # series of plain method calls instead of hash lookups and `public_send`.
+  #
+  # @example
+  #   # map :email, :email_address, if_dest: :persisted?
+  #   # custom_map(:name) { |user| "#{user.first_name} #{user.last_name}" }
+  #   #
+  #   # compiles to
+  #   def map(src_model, dest_model)
+  #     dest_model.email_address = src_model.email if dest_model.persisted?
+  #     dest_model.name = MAPPABLE_PROCS[0].call(src_model)
+  #     dest_model
+  #   end
+  #
+  # Procs can't be written into source, so they are collected in {#procs} and the
+  # generated code reads them from the {PROCS_CONSTANT} constant on the mapping class.
+  # Names that can't be called with dot syntax are called with `public_send`.
+  #
+  # @api private
+  class Compiler
+    # Name of the constant on the mapping class that holds {#procs}
+    PROCS_CONSTANT = :MAPPABLE_PROCS
+
+    # A method name that can be called with dot syntax
+    METHOD_NAME = /\A[a-zA-Z_]\w*[?!]?\z/
+
+    # A setter name that can be called with assignment syntax
+    SETTER_NAME = /\A[a-zA-Z_]\w*=\z/
+
+    # Condition options in the order they are checked: option, receiver, negated
+    CONDITIONS = [
+      [:if, 'self', false],
+      [:unless, 'self', true],
+      [:if_dest, 'dest_model', false],
+      [:unless_dest, 'dest_model', true],
+      [:if_src, 'src_model', false],
+      [:unless_src, 'src_model', true]
+    ].freeze
+
+    # @return [Array<Proc>] the procs referenced by the generated source, by index
+    attr_reader :procs
+
+    def initialize
+      @procs = []
+    end
+
+    # @param method_name [Symbol] name of the generated method
+    # @param mappings [Hash{Symbol => Hash}] mapping options, as built by {Mapping::ClassMethods}
+    # @return [String] source of a method that takes (src_model, dest_model) and returns dest_model
+    # @raise [ArgumentError] when a condition or map method is not a Symbol, String or Proc
+    def method_source(method_name, mappings)
+      lines = mappings.each_value.map { |options| "  #{assignment(options)}" }
+      ["def #{method_name}(src_model, dest_model)", *lines, '  dest_model', 'end'].join("\n")
+    end
+
+    private
+
+    def assignment(options)
+      line = setter_call(options[:setter].to_s, value(options))
+      condition = condition(options)
+      condition ? "#{line} if #{condition}" : line
+    end
+
+    def value(options)
+      return method_call('src_model', options[:getter].to_s) unless options[:map_method]
+
+      map_method_call(options[:map_method])
+    end
+
+    def map_method_call(map_method)
+      case map_method
+      when Symbol, String
+        method_call('self', map_method.to_s, 'src_model')
+      when Proc
+        "#{proc_ref(map_method)}.call(src_model)"
+      else
+        raise ArgumentError, "map method must be a Symbol, String or Proc, got #{map_method.inspect}"
+      end
+    end
+
+    def condition(options)
+      checks = CONDITIONS.filter_map do |option, receiver, negated|
+        next unless options[option]
+
+        check = condition_call(receiver, options[option])
+        negated ? "!(#{check})" : check
+      end
+      checks.join(' && ') unless checks.empty?
+    end
+
+    # Proc conditions run with the receiver as self and get it as their argument;
+    # lambdas that take no arguments are called without it
+    def condition_call(receiver, condition)
+      case condition
+      when Symbol, String
+        method_call(receiver, condition.to_s)
+      when Proc
+        arg = condition.lambda? && condition.arity.zero? ? '' : "#{receiver}, "
+        "#{receiver}.instance_exec(#{arg}&#{proc_ref(condition)})"
+      else
+        raise ArgumentError, "condition must be a Symbol, String or Proc, got #{condition.inspect}"
+      end
+    end
+
+    # self.name(...) can call the mapping's private methods; other receivers only public ones
+    def method_call(receiver, name, *args)
+      call_args = args.empty? ? '' : "(#{args.join(', ')})"
+      return "#{receiver}.#{name}#{call_args}" if METHOD_NAME.match?(name)
+
+      send_method = receiver == 'self' ? '__send__' : 'public_send'
+      "#{receiver}.#{send_method}(#{[name.to_sym.inspect, *args].join(', ')})"
+    end
+
+    def setter_call(setter, value)
+      return "dest_model.#{setter.delete_suffix('=')} = #{value}" if SETTER_NAME.match?(setter)
+
+      "dest_model.public_send(#{setter.to_sym.inspect}, #{value})"
+    end
+
+    def proc_ref(proc)
+      @procs << proc
+      "#{PROCS_CONSTANT}[#{@procs.size - 1}]"
+    end
+  end
+end

data/lib/mappable/mapping/class_methods.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Mappable
+  module Mapping
+    # The mapping DSL, added to classes that include {Mapping}.
+    #
+    # ## Conditions
+    #
+    # {#map}, {#custom_map} and {#custom_map_back} take conditions that skip the field
+    # when they don't hold:
+    #
+    # - `:if` / `:unless` - checked on the mapping instance
+    # - `:if_src` / `:unless_src` - checked on the object being read from
+    # - `:if_dest` / `:unless_dest` - checked on the object being written to
+    #
+    # A condition is a method name, called on that object, or a proc, run with the
+    # object as `self` and passed as its argument (a lambda may take no arguments).
+    # For {#map}, the reverse mapping swaps the `_src` and `_dest` conditions so they
+    # still check the same object.
+    module ClassMethods
+      # @return [Hash{Symbol => Hash}] options for each field {Mapping#map} sets, by field name
+      def mappings
+        {}.freeze
+      end
+
+      # @return [Hash{Symbol => Hash}] options for each field {Mapping#map_back} sets, by field name
+      def map_back_mappings
+        {}.freeze
+      end
+
+      # Copies the `src` field to the `dest` field, and `dest` back to `src` in {Mapping#map_back}.
+      #
+      # @example
+      #   map :email                  # email -> email
+      #   map :email, :email_address  # email -> email_address
+      #   map :active, if_dest: :new_record?
+      #
+      # @param src [Symbol, String] field read from the source
+      # @param dest [Symbol, String] field written on the destination, defaults to `src`
+      # @param options [Hash] conditions (see {ClassMethods}); other keys are kept in {#mappings}
+      # @return [void]
+      def map(src, dest = nil, options = {})
+        if dest.is_a?(Hash)
+          options = dest
+          dest = nil
+        end
+
+        dest ||= src
+
+        options = ::Mappable::Mapping.default_mapping_options(src, dest).merge(options)
+        add_value_to_class_method(:mappings, dest.to_sym => options)
+        add_value_to_class_method(:map_back_mappings, src.to_sym => ::Mappable::Mapping.map_back_options(options))
+        compile_mappings
+      end
+
+      # Sets the `dest` field from a method of the mapping, or a block, given the source.
+      # Only applies to {Mapping#map}; use {#custom_map_back} for the reverse.
+      #
+      # @example
+      #   custom_map :name                  # calls the mapping's name(src) method
+      #   custom_map :name, :full_name      # calls full_name(src)
+      #   custom_map(:name) { |src| "#{src.first_name} #{src.last_name}" }
+      #
+      # @param dest [Symbol, String] field written on the destination
+      # @param custom_method [Symbol, String, Proc] defaults to the block, then to `dest`
+      # @param options [Hash] conditions (see {ClassMethods}); other keys are kept in {#mappings}
+      # @return [void]
+      def custom_map(dest, custom_method = nil, options = {}, &)
+        add_custom_mapping(:mappings, dest, custom_method, options, &)
+      end
+
+      # Sets the `dest` field on the source object from a method of the mapping, or a block,
+      # given the destination object. Used by {Mapping#map_back}.
+      #
+      # @example
+      #   custom_map_back(:first_name) { |contact| contact.name.split(' ', 2).first }
+      #
+      # @param dest [Symbol, String] field written on the source object
+      # @param custom_method [Symbol, String, Proc] defaults to the block, then to `dest`
+      # @param options [Hash] conditions (see {ClassMethods}); other keys are kept in {#map_back_mappings}
+      # @return [void]
+      def custom_map_back(dest, custom_method = nil, options = {}, &)
+        add_custom_mapping(:map_back_mappings, dest, custom_method, options, &)
+      end
+
+      # Regenerates {Mapping#map} and {Mapping#map_back} from the current mappings.
+      # @api private
+      # @return [void]
+      def compile_mappings
+        compiler = ::Mappable::Compiler.new
+        source = [
+          compiler.method_source(:map, mappings),
+          compiler.method_source(:map_back, map_back_mappings)
+        ].join("\n")
+
+        store_procs(compiler.procs)
+        %i[map map_back].each { |name| remove_method(name) if method_defined?(name, false) }
+        class_eval(source, __FILE__, __LINE__)
+      end
+
+      private
+
+      def add_custom_mapping(method, dest, custom_method, options, &block)
+        if custom_method.is_a?(Hash)
+          options = custom_method
+          custom_method = nil
+        end
+
+        custom_method ||= block || dest
+
+        options = ::Mappable::Mapping.default_custom_mapping_options(dest, custom_method).merge(options)
+        add_value_to_class_method(method, dest.to_sym => options)
+        compile_mappings
+      end
+
+      def store_procs(procs)
+        name = ::Mappable::Compiler::PROCS_CONSTANT
+        remove_const(name) if const_defined?(name, false)
+        const_set(name, procs.freeze)
+        private_constant(name)
+      end
+    end
+  end
+end

data/lib/mappable/mapping.rb

@@ -1,79 +1,113 @@
 # frozen_string_literal: true
 
 module Mappable
-  # Defines what fields to map
+  # Declares which fields are copied from one object to another, and back.
+  #
+  # Mapping classes are usually created by {Mappable::ClassMethods#map_to}, but any
+  # class can include this module and declare mappings with {ClassMethods#map},
+  # {ClassMethods#custom_map} and {ClassMethods#custom_map_back}. Each declaration
+  # regenerates the class's {#map} and {#map_back} methods (see {Compiler}).
+  #
+  # @example
+  #   class ContactMapping
+  #     include Mappable::Mapping
+  #
+  #     map :email, :email_address
+  #     custom_map(:name) { |user| "#{user.first_name} #{user.last_name}" }
+  #     custom_map_back(:first_name) { |contact| contact.name.split(' ', 2).first }
+  #     custom_map_back(:last_name) { |contact| contact.name.split(' ', 2).last }
+  #   end
+  #
+  #   ContactMapping.new.map(user, Contact.new)      # => the contact
+  #   ContactMapping.new.map_back(contact, User.new) # => the user
   module Mapping
+    autoload :ClassMethods, 'mappable/mapping/class_methods'
+
+    # @api private
     def self.included(base)
       base.extend InheritanceHelper::Methods
       base.extend ClassMethods
     end
 
+    # Options for copying the `src` field into the `dest` field
+    # @api private
     def self.default_mapping_options(src, dest)
       {
         src: src.to_sym,
-        src_getter: src.to_s.freeze,
-        src_setter: "#{src}=",
+        getter: src.to_s.freeze,
         dest: dest.to_sym,
-        dest_getter: dest.to_s.freeze,
-        dest_setter: "#{dest}="
+        setter: "#{dest}="
       }
     end
 
-    # no-doc
-    module ClassMethods
-      def mappings
-        {}.freeze
-      end
-
-      def map(src, dest = nil, options = {})
-        if dest.is_a?(Hash)
-          options = dest
-          dest = nil
-        end
-
-        dest ||= src
-
-        options = ::Mappable::Mapping.default_mapping_options(src, dest)
-                                    .merge(options)
-
-        add_value_to_class_method(:mappings, src.to_sym => options)
-      end
+    # Options for setting the `dest` field from a custom method or proc
+    # @api private
+    def self.default_custom_mapping_options(dest, custom_method)
+      {
+        map_method: custom_method,
+        dest: dest.to_sym,
+        setter: "#{dest}="
+      }
     end
 
-    def map(src_model, dest_model)
-      self.class.mappings.each do |_, options|
-        next if skip?(src_model, dest_model, options)
+    # Each condition of a {ClassMethods#map} call and the condition it becomes in the
+    # reverse mapping. The source and destination swap places, so _src and _dest
+    # conditions swap too and still check the same object.
+    # @api private
+    MAP_BACK_CONDITIONS = {
+      if: :if,
+      unless: :unless,
+      if_src: :if_dest,
+      unless_src: :unless_dest,
+      if_dest: :if_src,
+      unless_dest: :unless_src
+    }.freeze
 
-        dest_model.public_send(options[:dest_setter], src_model.public_send(options[:src_getter]))
+    # Reverses the options of a {ClassMethods#map} call (see {MAP_BACK_CONDITIONS})
+    # @api private
+    def self.map_back_options(options)
+      new_options = default_mapping_options(options[:dest], options[:src])
+      MAP_BACK_CONDITIONS.each do |cond, map_back_cond|
+        new_options[map_back_cond] = options[cond] if options[cond]
       end
-      dest_model
+      new_options
     end
 
-    def skip?(src_model, dest_model, options)
-      return true if options[:if] && !call_method(dest_model, options[:if])
-      return true if options[:unless] && call_method(dest_model, options[:unless])
-
-      false
+    # Creates a mapping class and sets it as a constant of `base_module`.
+    #
+    # @param base_module [Module] where the class's constant is set
+    # @param name [String, Symbol] the class is named after it: `:contact` becomes `ContactMapping`
+    # @param options [Hash]
+    # @option options [String] :class_name the class's name instead of one built from `name`
+    # @option options [Class] :base_class superclass, so a mapping can extend another one
+    # @yield evaluated in the class, to declare its mappings
+    # @return [Class]
+    def self.create(base_module, name, options = {}, &block)
+      class_name = options[:class_name] || "#{::Mappable::Utils.classify_name(name)}Mapping"
+      kls = base_module.const_set(class_name, Class.new(options[:base_class] || Object))
+      kls.include(::Mappable::Mapping)
+      kls.class_eval(&block) if block
+      kls
     end
 
-    def call_method(model, method)
-      case method
-      when Symbol
-        model.public_send(method)
-      when Proc
-        model.instance_eval(&method)
-      else
-        raise("wrong type, failed to call method #{method}")
-      end
+    # Copies the mapped fields from `src_model` to `dest_model`. Replaced by a generated
+    # method once the class declares a mapping.
+    #
+    # @param _src_model [Object] not read: there is nothing to copy
+    # @param dest_model [Object]
+    # @return [Object] dest_model
+    def map(_src_model, dest_model)
+      dest_model
     end
 
-    def self.create(base_module, name, options = {}, &block)
-      options[:class_name] ||= ::Mappable::Utils.classify_name(name.to_s) + 'Mapping'
-      kls = Class.new(options[:base_class] || Object)
-      kls = base_module.const_set(options[:class_name], kls)
-      kls.send(:include, ::Mappable::Mapping)
-      kls.class_eval(&block) if block
-      kls
+    # Copies the fields of `dest_model` back to `src_model`, reversing {#map}. Replaced by a
+    # generated method once the class declares a mapping.
+    #
+    # @param _dest_model [Object] the object to read from, not read: there is nothing to copy
+    # @param src_model [Object] the object to write to
+    # @return [Object] src_model
+    def map_back(_dest_model, src_model)
+      src_model
     end
   end
 end

data/lib/mappable/utils.rb

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 module Mappable
-  # General purpouse utility methods
+  # General purpose utility methods
   module Utils
     module_function
 
+    # Converts a mapping name into a class name: drops anything that isn't a letter,
+    # digit, underscore or dash, then camel cases the words split by underscores and dashes.
+    #
+    # @example
+    #   Mappable::Utils.classify_name('user_profile') # => "UserProfile"
+    #   Mappable::Utils.classify_name('UserProfile')  # => "UserProfile"
+    #
+    # @param name [String, Symbol]
+    # @return [String]
     def classify_name(name)
-      name.gsub(/[^\da-z_-]/, '').gsub(/(^.|[_|-].)/) { |m| m[-1].upcase }
+      name.to_s.gsub(/[^\da-zA-Z_-]/, '').gsub(/(?:\A|[_-]+)([\da-zA-Z])/) { ::Regexp.last_match(1).upcase }
     end
   end
 end

data/lib/mappable/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Mappable
+  # The gem's version, bumped by release-please
+  VERSION = '0.2.0'
+end

data/lib/mappable.rb

@@ -2,34 +2,19 @@
 
 require 'inheritance-helper'
 
-# Transfer/Map data from one model to the next
+# Maps data from one object to another and back.
+#
+# Include it in a class and declare mappings with {ClassMethods#map_to}.
 module Mappable
+  autoload :ClassMethods, 'mappable/class_methods'
+  autoload :Compiler, 'mappable/compiler'
   autoload :Mapping, 'mappable/mapping'
   autoload :Utils, 'mappable/utils'
+  autoload :VERSION, 'mappable/version'
 
+  # @api private
   def self.included(base)
     base.extend InheritanceHelper::Methods
     base.extend ClassMethods
   end
-
-  # no-doc
-  module ClassMethods
-    def maps
-      {}.freeze
-    end
-
-    def map_to(name, options = {}, &block)
-      mapping = Mapping.create(self, name, options, &block)
-      add_value_to_class_method(:maps, name => mapping)
-
-      class_eval(
-<<-STR, __FILE__, __LINE__ + 1
-  def map_to_#{name}(dest)
-    ::#{mapping.name}.new.map(self, dest)
-    dest
-  end
-STR
-      )
-    end
-  end
 end

metadata

@@ -1,55 +1,59 @@
 --- !ruby/object:Gem::Specification
 name: model-mapper
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Doug Youch
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inheritance-helper
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: Easy way to configure what data is mapped between models
+        version: '0.2'
+description: 'Declare once how fields map from one object to another, and Mappable
+  compiles it into plain Ruby methods that copy the data both ways at close to hand-written
+  speed. Rename fields, combine several into one (first_name + last_name -> name)
+  and split them back out, and skip fields with conditions on the source, the destination
+  or the mapping itself. Works with any objects that have getters and setters: Structs,
+  ActiveRecord models, plain Ruby classes.'
 email: dougyouch@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rubocop.yml"
-- ".ruby-gemset"
-- ".ruby-version"
-- ".travis.yml"
-- Gemfile
-- Gemfile.lock
+- CHANGELOG.md
 - LICENSE
 - README.md
-- gemfiles/travis.gemfile
 - lib/mappable.rb
+- lib/mappable/class_methods.rb
+- lib/mappable/compiler.rb
 - lib/mappable/mapping.rb
+- lib/mappable/mapping/class_methods.rb
 - lib/mappable/utils.rb
+- lib/mappable/version.rb
 - lib/model-mapper.rb
-- model-mapper.gemspec
 homepage: https://github.com/dougyouch/mappable
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dougyouch/mappable
+  changelog_uri: https://github.com/dougyouch/mappable/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dougyouch/mappable/issues
+  documentation_uri: https://rubydoc.info/gems/model-mapper
 rdoc_options: []
 require_paths:
 - lib
@@ -57,16 +61,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.10
-signing_key: 
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Map data between models
+summary: Fast, declarative two-way mapping between Ruby objects
 test_files: []

data/.gitignore

@@ -1,51 +0,0 @@
-# rcov generated
-coverage
-coverage.data
-
-# rdoc generated
-rdoc
-
-# yard generated
-doc
-.yardoc
-
-# bundler
-.bundle
-
-# jeweler generated
-pkg
-
-# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
-#
-# * Create a file at ~/.gitignore
-# * Include files you want ignored
-# * Run: git config --global core.excludesfile ~/.gitignore
-#
-# After doing this, these files will be ignored in all your git projects,
-# saving you from having to 'pollute' every project you touch with them
-#
-# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
-#
-# For MacOS:
-#
-.DS_Store
-
-# For TextMate
-#*.tmproj
-#tmtags
-
-# For emacs:
-*~
-\#*
-.\#*
-
-# For vim:
-*.swp
-
-# For redcar:
-#.redcar
-
-# For rubinius:
-#*.rbc
-
-*.gem

data/.rubocop.yml

@@ -1,12 +0,0 @@
-Naming/FileName:
-  Enabled: false
-Metrics/LineLength:
-  Max: 120
-Metrics/ModuleLength:
-  Max: 120
-Metrics/MethodLength:
-  Max: 20
-AllCops:
-  Exclude:
-    - 'spec/spec_helper.rb'
-    - 'spec/**/*_spec.rb'

data/.ruby-gemset

@@ -1 +0,0 @@
-mappable

data/.ruby-version

@@ -1 +0,0 @@
-2.6.3

data/.travis.yml

@@ -1,17 +0,0 @@
-env:
-  global:
-    - CC_TEST_REPORTER_ID=f54f3242f54a3040953c9127294fef862cb1851d12333d004619a8b7b7842054
-rvm:
-  - 2.6.3
-  - 2.1.9
-  - 1.9.3
-gemfile: gemfiles/travis.gemfile
-language: ruby
-before_script:
-  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
-  - chmod +x ./cc-test-reporter
-  - ./cc-test-reporter before-build
-script:
-  - bundle exec rspec
-after_script:
-  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/Gemfile

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-source 'http://rubygems.org'
-
-gem 'inheritance-helper'
-
-group :development do
-  gem 'rake'
-  gem 'rubocop'
-end
-
-group :spec do
-  gem 'rspec'
-  gem 'simplecov'
-end

data/Gemfile.lock

@@ -1,54 +0,0 @@
-GEM
-  remote: http://rubygems.org/
-  specs:
-    ast (2.4.0)
-    diff-lcs (1.3)
-    docile (1.3.2)
-    inheritance-helper (0.1.0)
-    jaro_winkler (1.5.3)
-    json (2.2.0)
-    parallel (1.17.0)
-    parser (2.6.4.0)
-      ast (~> 2.4.0)
-    rainbow (3.0.0)
-    rake (12.3.3)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.2)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.4)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.1)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.2)
-    rubocop (0.74.0)
-      jaro_winkler (~> 1.5.1)
-      parallel (~> 1.10)
-      parser (>= 2.6)
-      rainbow (>= 2.2.2, < 4.0)
-      ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
-    ruby-progressbar (1.10.1)
-    simplecov (0.17.0)
-      docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-    unicode-display_width (1.6.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  inheritance-helper
-  rake
-  rspec
-  rubocop
-  simplecov
-
-BUNDLED WITH
-   1.17.3

data/gemfiles/travis.gemfile

@@ -1 +0,0 @@
-gemfiles/../Gemfile

data/model-mapper.gemspec

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-Gem::Specification.new do |s|
-  s.name        = 'model-mapper'
-  s.version     = '0.1.0'
-  s.licenses    = ['MIT']
-  s.summary     = 'Map data between models'
-  s.description = 'Easy way to configure what data is mapped between models'
-  s.authors     = ['Doug Youch']
-  s.email       = 'dougyouch@gmail.com'
-  s.homepage    = 'https://github.com/dougyouch/mappable'
-  s.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|script)/}) }
-
-  s.add_runtime_dependency 'inheritance-helper'
-end