vorpal 1.0.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6567d89919ba2836790c9d13fa729c43c21723fbcfa12ef8f77be2552e3f5df5
-  data.tar.gz: 3b5ebeea70138f7cf6e4e68c0e21d4024e3732c1cf6cbe1f04054a03fab815d0
+  metadata.gz: c236d5dee0ca27224473d24e59680317a5b30fae7e400a13738298d27e6f1e74
+  data.tar.gz: ffe4922245341adc4ef2e4ed25751dee28a03232c2bb5b19699120f07d7fd3d6
 SHA512:
-  metadata.gz: 7f991b2d7a25ebf9d85bc7a2af59c02e7105ff981724372167e13e6a30ffcd4a9bfdcd7db5a886b22bbbd9c86e52065a69a9e8c072e805420d16b1cdb4ed0151
-  data.tar.gz: 5bdcb19c91b9ce1de724caa2231d86903e472d65ebd6a47a7fe39c705b31437b6b797e9a0df70c841251581ea882a5d0a33c1fdc236030fe951fc9bb1cf3c723
+  metadata.gz: d6ba4c4ab43cc66a776be399be185130665ea4951a18a34e664b45d851801b37260ce4eee343f81511910e739f7451b3b30ead059c24712e9ee577c579fdeffa
+  data.tar.gz: e134e15a04d0e7037fbbedf83f5e381e281e72f8bae51e43b0f9b488877477d7d6dfb7350c037e9bfb06279ac78d74024b1e592725cd8673348bf6ad4d6f61c7

data/README.md

@@ -1,4 +1,4 @@
-# Vorpal [![Build Status](https://travis-ci.org/nulogy/vorpal.svg?branch=master)](https://travis-ci.org/nulogy/vorpal) [![Code Climate](https://codeclimate.com/github/nulogy/vorpal/badges/gpa.svg)](https://codeclimate.com/github/nulogy/vorpal) [![Code Coverage](https://codecov.io/gh/nulogy/vorpal/branch/master/graph/badge.svg)](https://codecov.io/gh/nulogy/vorpal/branch/master/graph/badge.svg)
+# Vorpal [![Build Status](https://travis-ci.com/nulogy/vorpal.svg?branch=main)](https://travis-ci.com/nulogy/vorpal) [![Code Climate](https://codeclimate.com/github/nulogy/vorpal/badges/gpa.svg)](https://codeclimate.com/github/nulogy/vorpal) [![Code Coverage](https://codecov.io/gh/nulogy/vorpal/branch/main/graph/badge.svg)](https://codecov.io/gh/nulogy/vorpal/branch/main)
 
 Separate your domain model from your persistence mechanism. Some problems call for a really sharp tool.
 
@@ -45,27 +45,21 @@ Or install it yourself as:
 Start with a domain model of POROs and AR::Base objects that form an aggregate:
 
 ```ruby
-class Tree; end
-
 class Branch
-  include Virtus.model
-
-  attribute :id, Integer
-  attribute :length, Decimal
-  attribute :diameter, Decimal
-  attribute :tree, Tree
+  attr_accessor :id
+  attr_accessor :length
+  attr_accessor :diameter
+  attr_accessor :tree
 end
 
-class Gardener < ActiveRecord::Base
+class Gardener
 end
 
 class Tree
-  include Virtus.model
-
-  attribute :id, Integer
-  attribute :name, String
-  attribute :gardener, Gardener
-  attribute :branches, Array[Branch]
+  attr_accessor :id
+  attr_accessor :name
+  attr_accessor :gardener
+  attr_accessor :branches
 end
 ```
 
@@ -162,9 +156,33 @@ TreeRepository.destroy(dead_tree)
 TreeRepository.destroy_by_id(dead_tree_id)
 ```
 
+### Ids
+
+Vorpal by default will use auto-incrementing Integers from a DB sequence for ids. However, UUID v4 ids are also 
+supported:
+
+```ruby
+Vorpal.define do
+  # UUID v4 id!
+  map Tree, primary_key_type: :uuid do
+    # ..
+  end
+
+  # Also a UUID v4 id, the Rails Way!
+  map Trunk, id: :uuid do
+    # ..
+  end
+
+  # If you feel the need to specify an auto-incrementing integer id.
+  map Branch, primary_key_type: :serial do
+    # ..
+  end
+end
+```
+
 ## API Documentation
 
-http://rubydoc.info/github/nulogy/vorpal/master/frames
+http://rubydoc.info/github/nulogy/vorpal
 
 ## Caveats
 It also does not do some things that you might expect from other ORMs:
@@ -181,13 +199,11 @@ It also does not do some things that you might expect from other ORMs:
 1. Only supports PostgreSQL.
 
 ## Future Enhancements
-* Aggregate updated_at.
-* Support for other DBMSs (no MySQL support until ids can be generated without inserting into a table!)
-* Support for other ORMs.
-* Value objects.
-* Remove dependency on ActiveRecord (optimistic locking? updated_at, created_at support? Data type conversions? TimeZone support?)
-* More efficient updates (use fewer queries.)
+* 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.
 
 ## FAQ
 
@@ -203,11 +219,12 @@ It also does not do some things that you might expect from other ORMs:
 
 **A.** Create a method on a [Repository](http://martinfowler.com/eaaCatalog/repository.html)! They have full access to the DB/ORM so you can use [Arel](https://github.com/rails/arel) and go [crazy](http://asciicasts.com/episodes/239-activerecord-relation-walkthrough) or use direct SQL if you want. 
 
-For example:
+For example, use the [#query](https://rubydoc.info/github/nulogy/vorpal/main/Vorpal/AggregateMapper#query-instance_method) method on the [AggregateMapper](https://rubydoc.info/github/nulogy/vorpal/main/Vorpal/AggregateMapper) to access the underyling [ActiveRecordRelation](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html):
 
 ```ruby
-  def find_all
-    @mapper.query.load_all # use the mapper to load all the aggregates
+  def find_special_ones
+    # use `load_all` or `load_one` to convert from ActiveRecord objects to domain POROs.
+    @mapper.query.where(special: true).load_all 
   end
 ```
 
@@ -229,6 +246,28 @@ For example:
 
 **A.** You can use [ActiveModel::Serialization](http://api.rubyonrails.org/classes/ActiveModel/Serialization.html) or [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers) but they are not heartily recommended. The former is too coupled to the model and the latter is too coupled to Rails controllers. Vorpal uses [SimpleSerializer](https://github.com/nulogy/simple_serializer) for this purpose.
 
+**Q.** Are `updated_at` and `created_at` supported?
+
+**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 )
@@ -265,6 +304,14 @@ For example:
 
 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
@@ -84,6 +84,17 @@ module Vorpal
       @engine
     end
 
+    # Returns a 'Vorpal-aware' [ActiveRecord::Relation](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html)
+    # for the ActiveRecord object underlying the domain entity mapped by this mapper.
+    #
+    # This method allows you to easily access the power of ActiveRecord::Relation to do more complex
+    # queries in your repositories.
+    #
+    # The ActiveRecord::Relation is 'Vorpal-aware' because it has the {#load_one} and {#load_many} methods
+    # mixed in so that you can get the POROs from your domain model instead of the ActiveRecord
+    # objects normally returned by ActiveRecord::Relation.
+    #
+    # @return [ActiveRecord::Relation]
     def query
       @engine.query(@domain_class)
     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/class_config.rb

@@ -0,0 +1,71 @@
+require 'equalizer'
+
+module Vorpal
+  module Config
+    # @private
+    class ClassConfig
+      include Equalizer.new(:domain_class, :db_class)
+      attr_reader :serializer, :deserializer, :domain_class, :db_class, :primary_key_type, :local_association_configs
+      attr_accessor :has_manys, :belongs_tos, :has_ones
+
+      ALLOWED_PRIMARY_KEY_TYPE_OPTIONS = [:serial, :uuid]
+
+      def initialize(attrs)
+        @has_manys = []
+        @belongs_tos = []
+        @has_ones = []
+        @local_association_configs = []
+
+        @serializer = attrs[:serializer]
+        @deserializer = attrs[:deserializer]
+        @domain_class = attrs[:domain_class]
+        @db_class = attrs[:db_class]
+        @primary_key_type = attrs[:primary_key_type]
+        raise "Invalid primary_key_type: '#{@primary_key_type}'" unless ALLOWED_PRIMARY_KEY_TYPE_OPTIONS.include?(@primary_key_type)
+      end
+
+      def build_db_object(attributes)
+        db_class.new(attributes)
+      end
+
+      def set_db_object_attributes(db_object, attributes)
+        db_object.attributes = attributes
+      end
+
+      def get_db_object_attributes(db_object)
+        symbolize_keys(db_object.attributes)
+      end
+
+      def serialization_required?
+        domain_class.superclass.name != 'ActiveRecord::Base'
+      end
+
+      def serialize(object)
+        serializer.serialize(object)
+      end
+
+      def deserialize(db_object)
+        attributes = get_db_object_attributes(db_object)
+        serialization_required? ? deserializer.deserialize(domain_class.new, attributes) : db_object
+      end
+
+      def set_attribute(db_object, attribute, value)
+        db_object.send("#{attribute}=", value)
+      end
+
+      def get_attribute(db_object, attribute)
+        db_object.send(attribute)
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        result = {}
+        hash.each_key do |key|
+          result[key.to_sym] = hash[key]
+        end
+        result
+      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