vorpal 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83737ac0a684cae35b5e849cba0c7851234dd83644ec04458e2c3c49ae0213f1
-  data.tar.gz: 8ac93c1267e080bc874dc2526d7b9f2c5abc1635c579d0f4be7cbd9af4fd7fc9
+  metadata.gz: c236d5dee0ca27224473d24e59680317a5b30fae7e400a13738298d27e6f1e74
+  data.tar.gz: ffe4922245341adc4ef2e4ed25751dee28a03232c2bb5b19699120f07d7fd3d6
 SHA512:
-  metadata.gz: 959ef178a6479c47053c2d100c323a48134fdcf7c63479c21afff0cc7cb91f2a198962013e5b324c7a8a4b1946e19332b15198c957c3e1b097e7734036b2ab09
-  data.tar.gz: 2783c22ba9362a9285e4e80369565a8be0695feb910325f77233b43060826dfffafd03e74c2c4cdcb554e6246eba1e42441b7b2f94d7ba0748cda140effee044
+  metadata.gz: d6ba4c4ab43cc66a776be399be185130665ea4951a18a34e664b45d851801b37260ce4eee343f81511910e739f7451b3b30ead059c24712e9ee577c579fdeffa
+  data.tar.gz: e134e15a04d0e7037fbbedf83f5e381e281e72f8bae51e43b0f9b488877477d7d6dfb7350c037e9bfb06279ac78d74024b1e592725cd8673348bf6ad4d6f61c7

data/README.md

@@ -182,7 +182,7 @@ end
 
 ## API Documentation
 
-http://rubydoc.info/github/nulogy/vorpal/main/frames
+http://rubydoc.info/github/nulogy/vorpal
 
 ## Caveats
 It also does not do some things that you might expect from other ORMs:
@@ -199,7 +199,8 @@ It also does not do some things that you might expect from other ORMs:
 1. Only supports PostgreSQL.
 
 ## Future Enhancements
-* Support for clients to set UUID-based ids.
+* Support for having foreign keys point to columns other than primary keys.
+* Support for storing entity ids in a column called something other than "id".
 * Nicer DSL for specifying attributes that have different names in the domain model than in the DB.
 * Aggregate updated_at.
 * Better support for value objects.
@@ -249,6 +250,24 @@ For example, use the [#query](https://rubydoc.info/github/nulogy/vorpal/main/Vor
 
 **A.** Yes. If they exist on your database tables, they will behave exactly as if you were using vanilla ActiveRecord.
 
+**Q.** How do I tell ActiveRecord to ignore certain columns so that I can rename/remove them using zero-downtime deploys?
+
+**A.** You will want to use ActiveRecord's [`ignored_columns=`](https://api.rubyonrails.org/classes/ActiveRecord/ModelSchema/ClassMethods.html#method-i-ignored_columns) method like this:
+
+```ruby
+  engine = Vorpal.define do
+    map Product do
+      attributes(
+        :name,
+        :description,
+        # :column_to_remove
+      )
+    end
+  end
+  product_ar_class = engine.mapper_for(Product).db_class
+  product_ar_class.ignored_columns = [:column_to_remove]
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/nulogy/vorpal/fork )
@@ -285,6 +304,14 @@ For example, use the [#query](https://rubydoc.info/github/nulogy/vorpal/main/Vor
 
 Please see the [Appraisal gem docs](https://github.com/thoughtbot/appraisal) for more information.
 
+### Releasing
+
+1. Update the version number in `lib/vorpal/version.rb`
+2. Update the version of Vorpal in the Appraisal gemfiles (otherwise Travis CI will fail): `appraisal install`
+3. Commit the above changes with the message: `Bump version to <X.Y.Z>`
+4. Release the new version to Rubygems: `rake release`
+5. Profit!
+
 ## Contributors
 
 See who's [contributed](https://github.com/nulogy/vorpal/graphs/contributors)!

data/lib/vorpal/aggregate_mapper.rb

@@ -27,12 +27,12 @@ module Vorpal
     # Loads an aggregate from the DB. Will eagerly load all objects in the
     # aggregate and on the boundary (owned: false).
     #
-    # @param db_root [Object] DB representation of the root of the aggregate to be
+    # @param db_root [Object, nil] DB representation of the root of the aggregate to be
     #   loaded. This can be nil.
     # @param identity_map [IdentityMap] Provide your own IdentityMap instance
     #   if you want entity id -> unique object mapping for a greater scope than one
     #   operation.
-    # @return [Object] Aggregate root corresponding to the given DB representation.
+    # @return [Object, nil] Aggregate root corresponding to the given DB representation.
     def load_one(db_root, identity_map=IdentityMap.new)
       @engine.load_one(db_root, @domain_class, identity_map)
     end

data/lib/vorpal/aggregate_traversal.rb

@@ -19,19 +19,20 @@ module Vorpal
       visitor.visit_object(object, config)
 
       config.belongs_tos.each do |belongs_to_config|
-        child = belongs_to_config.get_child(object)
-        accept(child, visitor, already_visited) if visitor.continue_traversal?(belongs_to_config)
+        associate = belongs_to_config.get_associated(object)
+        accept(associate, visitor, already_visited) if visitor.continue_traversal?(belongs_to_config)
       end
 
       config.has_ones.each do |has_one_config|
-        child = has_one_config.get_child(object)
-        accept(child, visitor, already_visited) if visitor.continue_traversal?(has_one_config)
+        associate = has_one_config.get_associated(object)
+        accept(associate, visitor, already_visited) if visitor.continue_traversal?(has_one_config)
       end
 
       config.has_manys.each do |has_many_config|
-        children = has_many_config.get_children(object)
-        children.each do |child|
-          accept(child, visitor, already_visited) if visitor.continue_traversal?(has_many_config)
+        associates = has_many_config.get_associated(object)
+        raise InvariantViolated.new("#{has_many_config.pretty_name} was set to nil. Use an empty array instead.") if associates.nil?
+        associates.each do |associate|
+          accept(associate, visitor, already_visited) if visitor.continue_traversal?(has_many_config)
         end
       end
     end
@@ -47,4 +48,4 @@ module Vorpal
       true
     end
   end
-end
+end

data/lib/vorpal/config/association_config.rb

@@ -0,0 +1,84 @@
+require 'vorpal/config/foreign_key_info'
+require 'equalizer'
+
+module Vorpal
+  module Config
+    # @private
+    # Object association terminology:
+    # - All object associations are uni-directional
+    # - The end that holds the association is the 'Owner' and the end that
+    #   is referred to is the 'Associate' or 'Associates'
+    #
+    # Relational association terminology:
+    # - Local end: has FK
+    # - Remote end: has no FK
+    #
+    class AssociationConfig
+      include Equalizer.new(:local_class_config, :fk)
+
+      attr_reader :local_class_config, :remote_class_configs, :fk
+
+      # Only one of these two attributes needs to be specified
+      # If one is specified, then the association is uni-directional.
+      # If both are specified, then the association is bi-directional.
+      attr_accessor :local_end_config, :remote_end_config
+
+      def initialize(local_class_config, fk, fk_type)
+        @local_class_config = local_class_config
+        @remote_class_configs = {}
+        @fk = fk
+        @fk_type = fk_type
+      end
+
+      def fk_value(local_db_object)
+        local_db_object.send(fk)
+      end
+
+      def associate(local_object, remote_object)
+        local_end_config.associate(local_object, remote_object) if local_end_config && local_object
+        remote_end_config.associate(remote_object, local_object) if remote_end_config && remote_object
+      end
+
+      def add_remote_class_config(remote_class_configs)
+        Array(remote_class_configs).each do |remote_class_config|
+          @remote_class_configs[remote_class_config.domain_class.name] = remote_class_config
+        end
+      end
+
+      def remote_class_config(local_db_object)
+        if polymorphic?
+          fk_type_value = local_db_object.send(@fk_type)
+          @remote_class_configs[fk_type_value]
+        else
+          @remote_class_configs.values.first
+        end
+      end
+
+      def polymorphic?
+        !@fk_type.nil?
+      end
+
+      def set_foreign_key(local_db_object, remote_object)
+        local_class_config.set_attribute(local_db_object, @fk, remote_object&.send(unique_key_name))
+        local_class_config.set_attribute(local_db_object, @fk_type, remote_object.class.name) if polymorphic?
+      end
+
+      # @return ForeignKeyInfo
+      def foreign_key_info(remote_class_config)
+        ForeignKeyInfo.new(@fk, @fk_type, remote_class_config.domain_class.name, polymorphic?)
+      end
+
+      def unique_key_name
+        (@local_end_config || @remote_end_config).unique_key_name
+      end
+
+      def validate
+        if @local_end_config && @remote_end_config
+          if @local_end_config.unique_key_name != @remote_end_config.unique_key_name
+            raise ConfigurationError.new("#{@local_end_config.pretty_name} and #{@remote_end_config.pretty_name} must have the same unique_key_name/primary_key")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vorpal/config/belongs_to_config.rb

@@ -0,0 +1,35 @@
+require 'vorpal/config/configs'
+
+module Vorpal
+  module Config
+    # @private
+    # Object association terminology:
+    # - All object associations are uni-directional
+    # - The end that holds the association is the 'Owner' and the end that
+    #   is referred to is the 'Associate' or 'Associates'
+    #
+    # Relational association terminology:
+    # - Local end: has FK
+    # - Remote end: has no FK
+    #
+    class BelongsToConfig
+      include Util::HashInitialization
+      include LocalEndConfig
+
+      attr_reader :name, :owned, :fk, :fk_type, :associated_classes, :unique_key_name
+      attr_accessor :association_config
+
+      def get_associated(owner)
+        owner.send(name)
+      end
+
+      def associate(owner, associate)
+        owner.send("#{name}=", associate)
+      end
+
+      def pretty_name
+        "#{association_config.local_class_config.domain_class.name} belongs_to :#{name}"
+      end
+    end
+  end
+end

data/lib/vorpal/config/configs.rb

@@ -0,0 +1,54 @@
+require 'vorpal/util/hash_initialization'
+require 'vorpal/exceptions'
+require 'equalizer'
+
+module Vorpal
+  module Config
+    # @private
+    # Object association terminology:
+    # - All object associations are uni-directional
+    # - The end that holds the association is the 'Owner' and the end that
+    #   is referred to is the 'Associate' or 'Associates'
+    #
+    # Relational association terminology:
+    # - Local end: has FK
+    # - Remote end: has no FK
+    #
+    module RemoteEndConfig
+      def associated_class_config
+        association_config.local_class_config
+      end
+
+      def set_foreign_key(db_associate, owner)
+        association_config.set_foreign_key(db_associate, owner)
+      end
+
+      def set_class_config(class_config)
+        @class_config = class_config
+      end
+
+      def foreign_key_info
+        association_config.foreign_key_info(@class_config)
+      end
+
+      def get_unique_key_value(db_owner)
+        db_owner.send(unique_key_name)
+      end
+    end
+
+    # @private
+    module LocalEndConfig
+      def associated_class_config(db_owner)
+        association_config.remote_class_config(db_owner)
+      end
+
+      def set_foreign_key(db_owner, associate)
+        association_config.set_foreign_key(db_owner, associate)
+      end
+
+      def fk_value(db_owner)
+        db_owner.send(fk)
+      end
+    end
+  end
+end

data/lib/vorpal/config/foreign_key_info.rb

@@ -0,0 +1,23 @@
+require 'equalizer'
+
+module Vorpal
+  module Config
+    # @private
+    class ForeignKeyInfo
+      include Equalizer.new(:fk_column, :fk_type_column, :fk_type)
+
+      attr_reader :fk_column, :fk_type_column, :fk_type, :polymorphic
+
+      def initialize(fk_column, fk_type_column, fk_type, polymorphic)
+        @fk_column = fk_column
+        @fk_type_column = fk_type_column
+        @fk_type = fk_type
+        @polymorphic = polymorphic
+      end
+
+      def polymorphic?
+        @polymorphic
+      end
+    end
+  end
+end

data/lib/vorpal/config/has_many_config.rb

@@ -0,0 +1,38 @@
+require 'vorpal/config/configs'
+
+module Vorpal
+  module Config
+    # @private
+    # Object association terminology:
+    # - All object associations are uni-directional
+    # - The end that holds the association is the 'Owner' and the end that
+    #   is referred to is the 'Associate' or 'Associates'
+    #
+    # Relational association terminology:
+    # - Local end: has FK
+    # - Remote end: has no FK
+    #
+    class HasManyConfig
+      include Util::HashInitialization
+      include RemoteEndConfig
+
+      attr_reader :name, :owned, :fk, :fk_type, :associated_class, :unique_key_name
+      attr_accessor :association_config
+
+      def get_associated(owner)
+        owner.send(name)
+      end
+
+      def associate(owner, associates)
+        if get_associated(owner).nil?
+          owner.send("#{name}=", [])
+        end
+        get_associated(owner) << associates
+      end
+
+      def pretty_name
+        "#{@class_config.domain_class.name} has_many :#{name}"
+      end
+    end
+  end
+end

data/lib/vorpal/config/has_one_config.rb

@@ -0,0 +1,35 @@
+require 'vorpal/config/configs'
+
+module Vorpal
+  module Config
+    # @private
+    # Object association terminology:
+    # - All object associations are uni-directional
+    # - The end that holds the association is the 'Owner' and the end that
+    #   is referred to is the 'Associate' or 'Associates'
+    #
+    # Relational association terminology:
+    # - Local end: has FK
+    # - Remote end: has no FK
+    #
+    class HasOneConfig
+      include Util::HashInitialization
+      include RemoteEndConfig
+
+      attr_reader :name, :owned, :fk, :fk_type, :associated_class, :unique_key_name
+      attr_accessor :association_config
+
+      def get_associated(owner)
+        owner.send(name)
+      end
+
+      def associate(owner, associate)
+        owner.send("#{name}=", associate)
+      end
+
+      def pretty_name
+        "#{@class_config.domain_class.name} has_one :#{name}"
+      end
+    end
+  end
+end

data/lib/vorpal/config/main_config.rb

@@ -0,0 +1,68 @@
+require 'vorpal/exceptions'
+require 'vorpal/config/association_config'
+
+module Vorpal
+  module Config
+    # @private
+    class MainConfig
+      def initialize
+        @class_configs = []
+      end
+
+      def config_for(clazz)
+        config = @class_configs.detect { |conf| conf.domain_class == clazz }
+        raise Vorpal::ConfigurationNotFound.new("No configuration found for #{clazz}") unless config
+        config
+      end
+
+      def config_for_db_object(db_object)
+        @class_configs.detect { |conf| conf.db_class == db_object.class }
+      end
+
+      def add_class_config(class_config)
+        @class_configs << class_config
+      end
+
+      def initialize_association_configs
+        association_configs = {}
+        @class_configs.each do |config|
+          (config.has_ones + config.has_manys).each do |association_end_config|
+            associated_class_config = config_for(association_end_config.associated_class)
+            association_end_config.set_class_config(config)
+
+            association_config = build_association_config(association_configs, associated_class_config, association_end_config.fk, association_end_config.fk_type)
+            association_config.remote_end_config = association_end_config
+            association_config.add_remote_class_config(config)
+            association_end_config.association_config = association_config
+          end
+
+          config.belongs_tos.each do |association_end_config|
+            associated_class_configs = association_end_config.associated_classes.map(&method(:config_for))
+
+            association_config = build_association_config(association_configs, config, association_end_config.fk, association_end_config.fk_type)
+            association_config.local_end_config = association_end_config
+            association_config.add_remote_class_config(associated_class_configs)
+            association_end_config.association_config = association_config
+          end
+        end
+
+        association_configs.values.each do |association_config|
+          association_config.local_class_config.local_association_configs << association_config
+          association_config.validate
+        end
+      end
+
+      private
+
+      def build_association_config(association_configs, local_config, fk, fk_type)
+        association_config = AssociationConfig.new(local_config, fk, fk_type)
+        if association_configs[association_config]
+          association_config = association_configs[association_config]
+        else
+          association_configs[association_config] = association_config
+        end
+        association_config
+      end
+    end
+  end
+end

data/lib/vorpal/db_loader.rb

@@ -12,7 +12,7 @@ module Vorpal
     end
 
     def load_from_db(ids, config)
-      db_roots = @db_driver.load_by_id(config.db_class, ids)
+      db_roots = @db_driver.load_by_unique_key(config.db_class, ids, "id")
       load_from_db_objects(db_roots, config)
     end
 
@@ -24,9 +24,9 @@ module Vorpal
 
       until @lookup_instructions.empty?
         lookup = @lookup_instructions.next_lookup
-        new_objects = lookup.load_all(@db_driver)
-        @loaded_objects.add(lookup.config, new_objects)
-        explore_objects(lookup.config, new_objects)
+        newly_loaded_objects = lookup.load_all(@db_driver)
+        unexplored_objects = @loaded_objects.add(lookup.config, newly_loaded_objects)
+        explore_objects(lookup.config, unexplored_objects)
       end
 
       @loaded_objects
@@ -55,34 +55,34 @@ module Vorpal
     end
 
     def lookup_by_id(db_object, belongs_to_config)
-      child_config = belongs_to_config.child_config(db_object)
-      id = belongs_to_config.fk_value(db_object)
-      return if id.nil? || @loaded_objects.already_loaded?(child_config, id)
-      @lookup_instructions.lookup_by_id(child_config, id)
+      associated_class_config = belongs_to_config.associated_class_config(db_object)
+      unique_key_value = belongs_to_config.fk_value(db_object)
+      unique_key_name = belongs_to_config.unique_key_name
+      return if unique_key_value.nil? || @loaded_objects.already_loaded_by_unique_key?(associated_class_config, unique_key_name, unique_key_value)
+      @lookup_instructions.lookup_by_unique_key(associated_class_config, unique_key_name, unique_key_value)
     end
 
     def lookup_by_fk(db_object, has_some_config)
-      child_config = has_some_config.child_config
+      associated_class_config = has_some_config.associated_class_config
       fk_info = has_some_config.foreign_key_info
-      fk_value = db_object.id
-      @lookup_instructions.lookup_by_fk(child_config, fk_info, fk_value)
+      fk_value = has_some_config.get_unique_key_value(db_object)
+      @lookup_instructions.lookup_by_fk(associated_class_config, fk_info, fk_value)
     end
   end
 
   # @private
   class LookupInstructions
-    include Util::ArrayHash
     def initialize
-      @lookup_by_id = {}
-      @lookup_by_fk = {}
+      @lookup_by_id = Util::ArrayHash.new
+      @lookup_by_fk = Util::ArrayHash.new
     end
 
-    def lookup_by_id(config, ids)
-      add_to_hash(@lookup_by_id, config, Array(ids))
+    def lookup_by_unique_key(config, column_name, values)
+      @lookup_by_id.append([config, column_name], values)
     end
 
     def lookup_by_fk(config, fk_info, fk_value)
-      add_to_hash(@lookup_by_fk, [config, fk_info], fk_value)
+      @lookup_by_fk.append([config, fk_info], fk_value)
     end
 
     def next_lookup
@@ -100,12 +100,14 @@ module Vorpal
     private
 
     def pop_id_lookup
-      config, ids = pop(@lookup_by_id)
-      LookupById.new(config, ids)
+      key, ids = @lookup_by_id.pop
+      config = key.first
+      column_name = key.last
+      LookupById.new(config, column_name, ids)
     end
 
     def pop_fk_lookup
-      key, fk_values = pop(@lookup_by_fk)
+      key, fk_values = @lookup_by_fk.pop
       config = key.first
       fk_info = key.last
       LookupByFk.new(config, fk_info, fk_values)
@@ -115,14 +117,15 @@ module Vorpal
   # @private
   class LookupById
     attr_reader :config
-    def initialize(config, ids)
+    def initialize(config, column_name, ids)
       @config = config
+      @column_name = column_name
       @ids = ids
     end
 
     def load_all(db_driver)
       return [] if @ids.empty?
-      db_driver.load_by_id(@config.db_class, @ids)
+      db_driver.load_by_unique_key(@config.db_class, @ids, @column_name)
     end
   end
 

data/lib/vorpal/driver/postgresql.rb

@@ -40,12 +40,12 @@ module Vorpal
         db_class.where(id: ids).delete_all
       end
 
-      # Loads instances of the given class by primary key.
+      # Loads instances of the given class by a unique key.
       #
       # @param db_class [Class] A subclass of ActiveRecord::Base
       # @return [[Object]] An array of entities.
-      def load_by_id(db_class, ids)
-        db_class.where(id: ids).to_a
+      def load_by_unique_key(db_class, ids, column_name)
+        db_class.where(column_name => ids).to_a
       end
 
       # Loads instances of the given class whose foreign key has the given value.

data/lib/vorpal/dsl/config_builder.rb

@@ -1,4 +1,7 @@
-require 'vorpal/configs'
+require 'vorpal/config/class_config'
+require 'vorpal/config/has_many_config'
+require 'vorpal/config/has_one_config'
+require 'vorpal/config/belongs_to_config'
 require 'vorpal/dsl/defaults_generator'
 
 module Vorpal
@@ -64,25 +67,28 @@ module Vorpal
     end
 
     def build_has_many(options)
-      options[:child_class] ||= @defaults_generator.child_class(options[:name])
+      options[:associated_class] ||= options[:child_class] || @defaults_generator.associated_class(options[:name])
       options[:fk] ||= @defaults_generator.foreign_key(@domain_class.name)
+      options[:unique_key_name] ||= (options[:primary_key] || "id")
       options[:owned] = options.fetch(:owned, true)
-      Vorpal::HasManyConfig.new(options)
+      Vorpal::Config::HasManyConfig.new(options)
     end
 
     def build_has_one(options)
-      options[:child_class] ||= @defaults_generator.child_class(options[:name])
+      options[:associated_class] ||= options[:child_class] || @defaults_generator.associated_class(options[:name])
       options[:fk] ||= @defaults_generator.foreign_key(@domain_class.name)
+      options[:unique_key_name] ||= (options[:primary_key] || "id")
       options[:owned] = options.fetch(:owned, true)
-      Vorpal::HasOneConfig.new(options)
+      Vorpal::Config::HasOneConfig.new(options)
     end
 
     def build_belongs_to(options)
-      child_class = options[:child_classes] || options[:child_class] || @defaults_generator.child_class(options[:name])
-      options[:child_classes] = Array(child_class)
+      associated_classes = options[:associated_classes] || options[:child_classes] || options[:associated_class] || options[:child_class] || @defaults_generator.associated_class(options[:name])
+      options[:associated_classes] = Array(associated_classes)
       options[:fk] ||= @defaults_generator.foreign_key(options[:name])
+      options[:unique_key_name] ||= (options[:primary_key] || "id")
       options[:owned] = options.fetch(:owned, true)
-      Vorpal::BelongsToConfig.new(options)
+      Vorpal::Config::BelongsToConfig.new(options)
     end
   end
   end

data/lib/vorpal/dsl/configuration.rb

@@ -1,6 +1,7 @@
 require 'vorpal/engine'
 require 'vorpal/dsl/config_builder'
 require 'vorpal/driver/postgresql'
+require 'vorpal/config/main_config'
 
 module Vorpal
   module Dsl
@@ -36,7 +37,7 @@ module Vorpal
       #
       # @return [Engine] Instance of the mapping engine.
       def define(options={}, &block)
-        @main_config = MainConfig.new
+        @main_config = Config::MainConfig.new
         instance_exec(&block)
         @main_config.initialize_association_configs
         db_driver = options.fetch(:db_driver, Driver::Postgresql.new)
@@ -86,58 +87,65 @@ module Vorpal
         @builder.attributes(*attributes)
       end
 
-      # Defines a one-to-many association to another type where the foreign key is stored on the child.
+      # Defines a one-to-many association to another type where the foreign key is stored on the associated table.
       #
       # In Object-Oriented programming, associations are *directed*. This means that they can only be
       # traversed in one direction: from the type that defines the association (the one with the
-      # getter) to the type that is associated. They end that defines the association is called the
-      # 'Parent' and the end that is associated is called the 'Child'.
+      # getter) to the type that is associated.
       #
       # @param name [String] Name of the association getter.
       # @param options [Hash]
-      # @option options [Boolean] :owned (True) True if the child type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
-      # @option options [String] :fk (Parent class name converted to snakecase and appended with a '_id') The name of the DB column on the child that contains the foreign key reference to the parent.
-      # @option options [String] :fk_type The name of the DB column on the child that contains the parent class name. Only needed when there is an association from the child side that is polymorphic.
-      # @option options [Class] :child_class (name converted to a Class) The child class.
+      # @option options [Boolean] :owned (True) True if the associated type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
+      # @option options [String] :fk (Association-owning class name converted to snakecase and appended with a '_id') The name of the DB column on the associated table that contains the foreign key reference to the association owner.
+      # @option options [String] :fk_type The name of the DB column on the associated table that contains the association-owning class name. Only needed when the associated end is polymorphic.
+      # @option options [String] :unique_key_name ("id") The name of the column on the owning table that the foreign key points to. Normally the primary key column.
+      # @option options [String] :primary_key Same as :unique_key_name. Exists for compatibility with Rails API.
+      # @option options [Class] :child_class DEPRECATED. Use `associated_class` instead. The associated class.
+      # @option options [Class] :associated_class (Name of the association converted to a Class) The associated class.
       def has_many(name, options={})
         @builder.has_many(name, options)
       end
 
       # Defines a one-to-one association to another type where the foreign key
-      # is stored on the child.
+      # is stored on the associated table.
       #
       # In Object-Oriented programming, associations are *directed*. This means that they can only be
       # traversed in one direction: from the type that defines the association (the one with the
-      # getter) to the type that is associated. They end that defines the association is called the
-      # 'Parent' and the end that is associated is called the 'Child'.
+      # getter) to the type that is associated.
       #
       # @param name [String] Name of the association getter.
       # @param options [Hash]
-      # @option options [Boolean] :owned (True) True if the child type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
-      # @option options [String] :fk (Parent class name converted to snakecase and appended with a '_id') The name of the DB column on the child that contains the foreign key reference to the parent.
-      # @option options [String] :fk_type The name of the DB column on the child that contains the parent class name. Only needed when there is an association from the child side that is polymorphic.
-      # @option options [Class] :child_class (name converted to a Class) The child class.
+      # @option options [Boolean] :owned (True) True if the associated type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
+      # @option options [String] :fk (Association-owning class name converted to snakecase and appended with a '_id') The name of the DB column on the associated table that contains the foreign key reference to the association owner.
+      # @option options [String] :fk_type The name of the DB column on the associated table that contains the association-owning class name. Only needed when the associated end is polymorphic.
+      # @option options [String] :unique_key_name ("id") The name of the column on the owning table that the foreign key points to. Normally the primary key column.
+      # @option options [String] :primary_key Same as :unique_key_name. Exists for compatibility with Rails API.
+      # @option options [Class] :child_class DEPRECATED. Use `associated_class` instead. The associated class.
+      # @option options [Class] :associated_class (Name of the association converted to a Class) The associated class.
       def has_one(name, options={})
         @builder.has_one(name, options)
       end
 
       # Defines a one-to-one association with another type where the foreign key
-      # is stored on the parent.
+      # is stored on the table of the entity declaring the association.
       #
-      # This association can be polymorphic. I.E. children can be of different types.
+      # This association can be polymorphic. I.E. associates can be of different types.
       #
       # In Object-Oriented programming, associations are *directed*. This means that they can only be
       # traversed in one direction: from the type that defines the association (the one with the
-      # getter) to the type that is associated. They end that defines the association is called the
-      # 'Parent' and the end that is associated is called the 'Child'.
+      # getter) to the type that is associated.
       #
       # @param name [String] Name of the association getter.
       # @param options [Hash]
-      # @option options [Boolean] :owned (True) True if the child type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
-      # @option options [String] :fk (Child class name converted to snakecase and appended with a '_id') The name of the DB column on the parent that contains the foreign key reference to the child.
-      # @option options [String] :fk_type The name of the DB column on the parent that contains the child class name. Only needed when the association is polymorphic.
-      # @option options [Class] :child_class (name converted to a Class) The child class.
-      # @option options [[Class]] :child_classes The list of possible classes that can be children. This is for polymorphic associations. Takes precedence over `:child_class`.
+      # @option options [Boolean] :owned (True) True if the associated type belongs to the aggregate. Changes to any object belonging to the aggregate will be persisted when the aggregate is persisted.
+      # @option options [String] :fk (Associated class name converted to snakecase and appended with a '_id') The name of the DB column on the association-owning table that contains the foreign key reference to the associated table.
+      # @option options [String] :fk_type The name of the DB column on the association-owning table that contains the associated class name. Only needed when the association is polymorphic.
+      # @option options [String] :unique_key_name ("id") The name of the column on the associated table that the foreign key points to. Normally the primary key column.
+      # @option options [String] :primary_key Same as :unique_key_name. Exists for compatibility with Rails API.
+      # @option options [Class] :child_class DEPRECATED. Use `associated_class` instead. The associated class.
+      # @option options [Class] :associated_class (Name of the association converted to a Class) The associated class.
+      # @option options [[Class]] :child_classes DEPRECATED. Use `associated_classes` instead. The list of possible classes that can be associated. This is for polymorphic associations. Takes precedence over `:associated_class`.
+      # @option options [[Class]] :associated_classes (Name of the association converted to a Class) The list of possible classes that can be associated. This is for polymorphic associations. Takes precedence over `:associated_class`.
       def belongs_to(name, options={})
         @builder.belongs_to(name, options)
       end

data/lib/vorpal/dsl/defaults_generator.rb

@@ -35,7 +35,7 @@ module Vorpal
       ActiveSupport::Inflector.foreign_key(name.to_s)
     end
 
-    def child_class(association_name)
+    def associated_class(association_name)
       module_parent.const_get(ActiveSupport::Inflector.classify(association_name.to_s))
     end
 

data/lib/vorpal/engine.rb

@@ -137,8 +137,9 @@ module Vorpal
       loaded_db_objects.each do |config, db_objects|
         db_objects.each do |db_object|
           config.local_association_configs.each do |association_config|
-            db_remote = loaded_db_objects.find_by_id(
+            db_remote = loaded_db_objects.find_by_unique_key(
               association_config.remote_class_config(db_object),
+              association_config.unique_key_name,
               association_config.fk_value(db_object)
             )
             association_config.associate(identity_map.get(db_object), identity_map.get(db_remote))
@@ -159,7 +160,7 @@ module Vorpal
     def serialize_object(object, config, loaded_db_objects)
       if config.serialization_required?
         attributes = config.serialize(object)
-        db_object = loaded_db_objects.find_by_id(config, object.id)
+        db_object = loaded_db_objects.find_by_primary_key(config, object)
         if object.id.nil? || db_object.nil? # object doesn't exist in the DB
           config.build_db_object(attributes)
         else
@@ -192,23 +193,23 @@ module Vorpal
         objects.each do |object|
           config.has_manys.each do |has_many_config|
             if has_many_config.owned
-              children = has_many_config.get_children(object)
-              children.each do |child|
-                has_many_config.set_foreign_key(mapping[child], object)
+              associates = has_many_config.get_associated(object)
+              associates.each do |associate|
+                has_many_config.set_foreign_key(mapping[associate], object)
               end
             end
           end
 
           config.has_ones.each do |has_one_config|
             if has_one_config.owned
-              child = has_one_config.get_child(object)
-              has_one_config.set_foreign_key(mapping[child], object)
+              associate = has_one_config.get_associated(object)
+              has_one_config.set_foreign_key(mapping[associate], object) if associate
             end
           end
 
           config.belongs_tos.each do |belongs_to_config|
-            child = belongs_to_config.get_child(object)
-            belongs_to_config.set_foreign_key(mapping[object], child)
+            associate = belongs_to_config.get_associated(object)
+            belongs_to_config.set_foreign_key(mapping[object], associate)
           end
         end
       end

data/lib/vorpal/exceptions.rb

@@ -4,4 +4,8 @@ module Vorpal
   class InvalidAggregateRoot < StandardError; end
 
   class ConfigurationNotFound < StandardError; end
+
+  class ConfigurationError < StandardError; end
+
+  class InvariantViolated < StandardError; end
 end

data/lib/vorpal/identity_map.rb

@@ -28,9 +28,14 @@ module Vorpal
 
     def key(db_row)
       return nil unless db_row
-      raise "Cannot map a DB row without an id '#{db_row.inspect}' to an entity." if db_row.id.nil?
+      primary_key_value = get_primary_key_value(db_row)
+      raise "Cannot map a DB row without an id '#{db_row.inspect}' to an entity." if primary_key_value.nil?
       raise "Cannot map a DB row without a Class with a name '#{db_row.inspect}' to an entity." if db_row.class.name.nil?
-      [db_row.id, db_row.class.name]
+      [primary_key_value, db_row.class.name]
+    end
+
+    def get_primary_key_value(db_row)
+      db_row.send(db_row.class.primary_key)
     end
   end
 end

data/lib/vorpal/loaded_objects.rb

@@ -5,37 +5,80 @@ module Vorpal
 
   # @private
   class LoadedObjects
-    include Util::ArrayHash
     extend Forwardable
     include Enumerable
 
-    attr_reader :objects
-    def_delegators :objects, :each
+    def_delegators :@objects, :each
 
     def initialize
-      @objects = Hash.new([])
-      @objects_by_id = Hash.new
+      @objects = Util::ArrayHash.new
+      @cache = {}
     end
 
     def add(config, objects)
       objects_to_add = objects.map do |object|
-        if !already_loaded?(config, object.id)
-          @objects_by_id[[config.domain_class.name, object.id]] = object
+        if !already_loaded?(config, object)
+          add_to_cache(config, object)
         end
-      end
-      add_to_hash(@objects, config, objects_to_add.compact)
+      end.compact
+      @objects.append(config, objects_to_add)
+      objects_to_add
+    end
+
+    def find_by_primary_key(config, object)
+      find_by_unique_key(config, "id", object.id)
     end
 
-    def find_by_id(config, id)
-      @objects_by_id[[config.domain_class.name, id]]
+    def find_by_unique_key(config, column_name, value)
+      get_from_cache(config, column_name, value)
     end
 
     def all_objects
-      @objects_by_id.values
+      @objects.values
+    end
+
+    def already_loaded_by_unique_key?(config, column_name, id)
+      !find_by_unique_key(config, column_name, id).nil?
+    end
+
+    private
+
+    def already_loaded?(config, object)
+      !find_by_primary_key(config, object).nil?
     end
 
-    def already_loaded?(config, id)
-      !find_by_id(config, id).nil?
+    # TODO: Do we have to worry about symbols vs strings for the column_name?
+    def add_to_cache(config, object)
+      # we take a shortcut here assuming that the cache has already been primed with the primary key column
+      # because this method should always be guarded by #already_loaded?
+      column_cache = @cache[config]
+      column_cache.each do |column_name, unique_key_cache|
+        unique_key_cache[object.send(column_name)] = object
+      end
+      object
+    end
+
+    def get_from_cache(config, column_name, value)
+      lookup_hash(config, column_name)[value]
+    end
+
+    # lazily primes the cache
+    # TODO: Do we have to worry about symbols vs strings for the column_name?
+    def lookup_hash(config, column_name)
+      column_cache = @cache[config]
+      if column_cache.nil?
+        column_cache = {}
+        @cache[config] = column_cache
+      end
+      unique_key_cache = column_cache[column_name]
+      if unique_key_cache.nil?
+        unique_key_cache = {}
+        column_cache[column_name] = unique_key_cache
+        @objects[config].each do |object|
+          unique_key_cache[object.send(column_name)] = object
+        end
+      end
+      unique_key_cache
     end
   end
 end

data/lib/vorpal/util/array_hash.rb

@@ -1,19 +1,33 @@
+require 'forwardable'
+
 module Vorpal
   module Util
     # @private
-    module ArrayHash
-      def add_to_hash(array_hash, key, values)
-        if array_hash[key].nil? || array_hash[key].empty?
-          array_hash[key] = []
+    class ArrayHash
+      extend Forwardable
+
+      def_delegators :@hash, :each, :empty?, :[]
+
+      def initialize
+        @hash = Hash.new([])
+      end
+
+      def append(key, values)
+        if @hash[key].nil? || @hash[key].empty?
+          @hash[key] = []
         end
-        array_hash[key].concat(Array(values))
+        @hash[key].concat(Array(values))
       end
 
-      def pop(array_hash)
-        key = array_hash.first.first
-        values = array_hash.delete(key)
+      def pop
+        key = @hash.first.first
+        values = @hash.delete(key)
         [key, values]
       end
+
+      def values
+        @hash.values.flatten
+      end
     end
   end
 end

data/lib/vorpal/util/hash_initialization.rb

@@ -2,7 +2,7 @@ module Vorpal
   module Util
     # @private
     module HashInitialization
-      def initialize(attrs)
+      def initialize(attrs={})
         attrs.each do |k,v|
           instance_variable_set("@#{k}", v)
         end

data/lib/vorpal/version.rb

@@ -1,3 +1,3 @@
 module Vorpal
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vorpal
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Sean Kirby
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-26 00:00:00.000000000 Z
+date: 2021-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: simple_serializer
@@ -165,8 +165,14 @@ files:
 - lib/vorpal/aggregate_mapper.rb
 - lib/vorpal/aggregate_traversal.rb
 - lib/vorpal/aggregate_utils.rb
+- lib/vorpal/config/association_config.rb
+- lib/vorpal/config/belongs_to_config.rb
 - lib/vorpal/config/class_config.rb
-- lib/vorpal/configs.rb
+- lib/vorpal/config/configs.rb
+- lib/vorpal/config/foreign_key_info.rb
+- lib/vorpal/config/has_many_config.rb
+- lib/vorpal/config/has_one_config.rb
+- lib/vorpal/config/main_config.rb
 - lib/vorpal/db_loader.rb
 - lib/vorpal/driver/postgresql.rb
 - lib/vorpal/dsl/config_builder.rb

data/lib/vorpal/configs.rb

@@ -1,239 +0,0 @@
-require 'vorpal/util/hash_initialization'
-require 'vorpal/exceptions'
-require 'vorpal/config/class_config'
-require 'equalizer'
-
-module Vorpal
-  # @private
-  class MainConfig
-    def initialize
-      @class_configs = []
-    end
-
-    def config_for(clazz)
-      config = @class_configs.detect { |conf| conf.domain_class == clazz }
-      raise Vorpal::ConfigurationNotFound.new("No configuration found for #{clazz}") unless config
-      config
-    end
-
-    def config_for_db_object(db_object)
-      @class_configs.detect { |conf| conf.db_class == db_object.class }
-    end
-
-    def add_class_config(class_config)
-      @class_configs << class_config
-    end
-
-    def initialize_association_configs
-      association_configs = {}
-      @class_configs.each do |config|
-        (config.has_ones + config.has_manys).each do |association_end_config|
-          child_config = config_for(association_end_config.child_class)
-          association_end_config.set_parent_class_config(config)
-
-          association_config = build_association_config(association_configs, child_config, association_end_config.fk, association_end_config.fk_type)
-          association_config.remote_end_config = association_end_config
-          association_config.add_remote_class_config(config)
-          association_end_config.association_config = association_config
-        end
-
-        config.belongs_tos.each do |association_end_config|
-          child_configs = association_end_config.child_classes.map(&method(:config_for))
-
-          association_config = build_association_config(association_configs, config, association_end_config.fk, association_end_config.fk_type)
-          association_config.local_end_config = association_end_config
-          association_config.add_remote_class_config(child_configs)
-          association_end_config.association_config = association_config
-        end
-      end
-
-      association_configs.values.each do |association_config|
-        association_config.local_class_config.local_association_configs << association_config
-      end
-    end
-
-    private
-
-    def build_association_config(association_configs, local_config, fk, fk_type)
-      association_config = AssociationConfig.new(local_config, fk, fk_type)
-      if association_configs[association_config]
-        association_config = association_configs[association_config]
-      else
-        association_configs[association_config] = association_config
-      end
-      association_config
-    end
-  end
-
-  # @private
-  # Object associations:
-  # - All object associations are uni-directional
-  # - The end that holds the association is the 'Parent' and the end that
-  #   is referred to is the 'Child' or 'Children'
-  #
-  # Relational associations:
-  # - Local end: has FK
-  # - Remote end: has no FK
-  #
-  class AssociationConfig
-    include Equalizer.new(:local_class_config, :fk)
-
-    attr_reader :local_class_config, :remote_class_configs, :fk
-
-    # Only one of these two attributes needs to be specified
-    # If one is specified, then the association is uni-directional.
-    # If both are specified, then the association is bi-directional.
-    attr_accessor :local_end_config, :remote_end_config
-
-    def initialize(local_class_config, fk, fk_type)
-      @local_class_config = local_class_config
-      @remote_class_configs = {}
-      @fk = fk
-      @fk_type = fk_type
-    end
-
-    def fk_value(local_db_object)
-      local_db_object.send(fk)
-    end
-
-    def associate(local_object, remote_object)
-      local_end_config.associate(local_object, remote_object) if local_end_config && local_object
-      remote_end_config.associate(remote_object, local_object) if remote_end_config && remote_object
-    end
-
-    def add_remote_class_config(remote_class_configs)
-      Array(remote_class_configs).each do |remote_class_config|
-        @remote_class_configs[remote_class_config.domain_class.name] = remote_class_config
-      end
-    end
-
-    def remote_class_config(local_db_object)
-      if polymorphic?
-        fk_type_value = local_db_object.send(@fk_type)
-        @remote_class_configs[fk_type_value]
-      else
-        @remote_class_configs.values.first
-      end
-    end
-
-    def polymorphic?
-      !@fk_type.nil?
-    end
-
-    def set_foreign_key(local_db_object, remote_object)
-      local_class_config.set_attribute(local_db_object, @fk, remote_object.try(:id))
-      local_class_config.set_attribute(local_db_object, @fk_type, remote_object.class.name) if polymorphic?
-    end
-
-    def foreign_key_info(remote_class_config)
-      ForeignKeyInfo.new(@fk, @fk_type, remote_class_config.domain_class.name, polymorphic?)
-    end
-  end
-
-  # @private
-  class ForeignKeyInfo
-    include Equalizer.new(:fk_column, :fk_type_column, :fk_type)
-
-    attr_reader :fk_column, :fk_type_column, :fk_type, :polymorphic
-
-    def initialize(fk_column, fk_type_column, fk_type, polymorphic)
-      @fk_column = fk_column
-      @fk_type_column = fk_type_column
-      @fk_type = fk_type
-      @polymorphic = polymorphic
-    end
-
-    def polymorphic?
-      @polymorphic
-    end
-  end
-
-  # @private
-  module RemoteEndConfig
-    def child_config
-      association_config.local_class_config
-    end
-
-    def set_foreign_key(db_child, parent)
-      association_config.set_foreign_key(db_child, parent)
-    end
-
-    def set_parent_class_config(parent_config)
-      @parent_config = parent_config
-    end
-
-    def foreign_key_info
-      association_config.foreign_key_info(@parent_config)
-    end
-  end
-
-  # @private
-  module LocalEndConfig
-    def child_config(db_parent)
-      association_config.remote_class_config(db_parent)
-    end
-
-    def set_foreign_key(db_parent, child)
-      association_config.set_foreign_key(db_parent, child)
-    end
-
-    def fk_value(db_parent)
-      db_parent.send(fk)
-    end
-  end
-
-  # @private
-  module ToOneConfig
-    def get_child(parent)
-      parent.send(name)
-    end
-
-    def associate(parent, child)
-      parent.send("#{name}=", child)
-    end
-  end
-
-  # @private
-  module ToManyConfig
-    def get_children(parent)
-      parent.send(name)
-    end
-
-    def associate(parent, child)
-      if get_children(parent).nil?
-        parent.send("#{name}=", [])
-      end
-      get_children(parent) << child
-    end
-  end
-
-  # @private
-  class HasManyConfig
-    include Util::HashInitialization
-    include RemoteEndConfig
-    include ToManyConfig
-
-    attr_reader :name, :owned, :fk, :fk_type, :child_class
-    attr_accessor :association_config
-  end
-
-  # @private
-  class HasOneConfig
-    include Util::HashInitialization
-    include RemoteEndConfig
-    include ToOneConfig
-
-    attr_reader :name, :owned, :fk, :fk_type, :child_class
-    attr_accessor :association_config
-  end
-
-  # @private
-  class BelongsToConfig
-    include Util::HashInitialization
-    include LocalEndConfig
-    include ToOneConfig
-
-    attr_reader :name, :owned, :fk, :fk_type, :child_classes
-    attr_accessor :association_config
-  end
-end