vorpal 1.0.3 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9833373892cb8a97f3b37ba1ec0fe9d06fe0b39dc6caaf9f7b333b28f20c2a47
-  data.tar.gz: 47df18148ce8412236a13032055da0ca6d3c1c21c9839e99c329a2df88982a55
+  metadata.gz: a6010044c0c80fa3020a1e7a0cd362977b363df6e03bbcc8508028b9bf4e3a2f
+  data.tar.gz: '07708e14f8dc2af434718350a18935ead37232b3a9907338cade26cfd9080b41'
 SHA512:
-  metadata.gz: 24c5cd71c9d56d8b882bb6691808c22749317d81ca1b104c90ddcf846c35ee0d8b36809cf1558f5a973f3696a48dc2aa9e80a6c0d6f7ea80dac275ef7b1d8597
-  data.tar.gz: c1012c585122a6259137e9de766247222b7c1a20606b27aca7fb219d947914a860016c1ec1c7ba8387d223d9bbde53c416065f52b837680b0bcff2fc6d177d40
+  metadata.gz: dc45b50d694ea28489e2125e8ecae7065a24ba91773771536e01dcb5cbfc4bad93c8e9fabc1be635213b072ca6c9068b0851c37763814ff3cbcebe5037ba8686
+  data.tar.gz: 4b8dc8c8ce5a567a7f563df9d3c478d24f61afd66ab110852cb3fab028089ec6f307d74d9ff5157c478f5f60a349930cce6a8f837f282f56b5d1502af30710cd

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)
+# 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