vorpal 1.0.1 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2bd60707eb3762666ed0ada9c456b5d54fbc73ca5d56eda9febd1c540ffc754
-  data.tar.gz: a17bf33069fe5d44d2a9577da2d7e5457a18ab0703b7dfe14d67fc22f6f7d76c
+  metadata.gz: 83737ac0a684cae35b5e849cba0c7851234dd83644ec04458e2c3c49ae0213f1
+  data.tar.gz: 8ac93c1267e080bc874dc2526d7b9f2c5abc1635c579d0f4be7cbd9af4fd7fc9
 SHA512:
-  metadata.gz: 8a9b2b133c7db7523153b290d3422e84db785856a12d37d863608f017366dd0f06ddad3e4f9b261e28a6c7cd66a72dc54c52b05425715146165d7573118b84bc
-  data.tar.gz: da8970a533f9fce8e3cd3b3bcdd2464abd2b6c8fa0cb06fd8ced941d6c61115cea3df3523679a01722dcd7e641503628b76140bd553b0e167623021bd7e937fe
+  metadata.gz: 959ef178a6479c47053c2d100c323a48134fdcf7c63479c21afff0cc7cb91f2a198962013e5b324c7a8a4b1946e19332b15198c957c3e1b097e7734036b2ab09
+  data.tar.gz: 2783c22ba9362a9285e4e80369565a8be0695feb910325f77233b43060826dfffafd03e74c2c4cdcb554e6246eba1e42441b7b2f94d7ba0748cda140effee044

data/README.md

@@ -1,16 +1,13 @@
-# 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)
+# 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.
 
-
-> One, two! One, two! and through and through
-
-> The vorpal blade went snicker-snack!
-
-> He left it dead, and with its head
-
+> One, two! One, two! and through and through<br/>
+> The vorpal blade went snicker-snack!<br/>
+> He left it dead, and with its head<br/>
 > He went galumphing back.
 
+\- [Jabberwocky](https://www.poetryfoundation.org/poems/42916/jabberwocky) by Lewis Carroll
 
 ## Overview
 Vorpal is a [Data Mapper](http://martinfowler.com/eaaCatalog/dataMapper.html)-style ORM (object relational mapper) framelet that persists POROs (plain old Ruby objects) to a relational DB. It has been heavily influenced by concepts from [Domain Driven Design](http://www.infoq.com/minibooks/domain-driven-design-quickly).
@@ -48,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
 ```
 
@@ -143,7 +134,8 @@ module TreeRepository
 end
 ```
 
-Here we've used the `owned` flag on the `belongs_to` from the Tree to the Gardener to show that the Gardener is on the aggregate boundary.
+Here we've used the `owned: false` flag on the `belongs_to` from the Tree to the Gardener to show
+that the Gardener is on the aggregate boundary.
 
 And use it:
 
@@ -164,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/main/frames
 
 ## Caveats
 It also does not do some things that you might expect from other ORMs:
@@ -174,7 +190,7 @@ It also does not do some things that you might expect from other ORMs:
 1. No lazy loading of associations. This might sound like a big deal, but with [correctly designed aggregates](http://dddcommunity.org/library/vernon_2011/) it turns out not to be.
 1. No managing of transactions. It is the strong opinion of the authors that managing transactions is an application-level concern.
 1. No support for validations. Validations are not a persistence concern.
-1. No AR-style callbacks. Use Infrastructure, Application, or Domain [services](http://martinfowler.com/bliki/EvansClassification.html) instead.
+1. No AR-style callbacks. Use [Infrastructure, Application, or Domain services](http://martinfowler.com/bliki/EvansClassification.html) instead.
 1. No has-many-through associations. Use two has-many associations to a join entity instead.
 1. The `id` attribute is reserved for database primary keys. If you have a natural key/id on your domain model, name it something that makes sense for your domain. It is the strong opinion of the authors that using natural keys as foreign keys is a bad idea. This mixes domain and persistence concerns.
 
@@ -183,13 +199,10 @@ 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 clients to set UUID-based ids.
 * 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
 
@@ -205,11 +218,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
 ```
 
@@ -231,6 +245,10 @@ 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.
+
 ## Contributing
 
 1. Fork it ( https://github.com/nulogy/vorpal/fork )
@@ -239,33 +257,31 @@ For example:
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
 
-### Setup DirEnv
-
-Using this gem's bin stubs (contained in the `bin` dir) is much easier if [DirEnv](https://github.com/direnv/direnv) is installed.
-
-On OSX using ZSH DirEnv can be installed like so:
-
-1. `brew install direnv`
-2. `echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc`
+## OSX Environment setup
 
-Please see the [DirEnv docs](https://direnv.net/) if your environment is different.
+1. Install [Homebrew](https://brew.sh/)
+2. Install [rbenv](https://github.com/rbenv/rbenv#installation) ([RVM](https://rvm.io/) can work too)
+3. Install [DirEnv](https://direnv.net/docs/installation.html) (`brew install direnv`)
+4. Install Docker Desktop Community Edition (`brew cask install docker`)
+5. Start Docker Desktop Community Edition (`CMD+space docker ENTER`)
+6. Install Ruby (`rbenv install 2.7.0`)
+7. Install PostgreSQL (`brew install postgresql`)
+8. Clone the repo (`git clone git@github.com:nulogy/vorpal.git`) and `cd` to the project root.
+8. Copy the contents of `gemfiles/rails_<version>.gemfile.lock` into a `Gemfile.lock` file
+  at the root of the project. (`cp gemfiles/rails_6_0.gemfile.lock gemfile.lock`)
+9. `bundle`
 
 ### Running Tests
 
-1. Start a PostgreSQL server.
-2. Either:
-  * Create a DB user called `vorpal` with password `pass`. OR:
-  * Modify `spec/helpers/db_helpers.rb`.
-3. Run `rake` from the terminal.
+1. Start a PostgreSQL server using `docker-compose up`
+3. Run `rake` from the terminal to run all specs or `rspec <path to spec file>` to
+  run a single spec.
 
-### Running Tests for the non-default versions of Rails
+### Running Tests for a specific version of Rails
 
-1. Start a PostgreSQL server.
-2. Either:
-  * Create a DB user called `vorpal` with password `pass`. OR:
-  * Modify `spec/helpers/db_helpers.rb`.
-3. Run `appraisal <rails version> rake` from the terminal.
-  * Where `<rails version>` is one of the options defined in the `./Appraisal` file.
+1. Start a PostgreSQL server using `docker-compose up`
+2. Run `appraisal rails-5-2 rake` from the terminal to run all specs or
+  `appraisal rails-5-2 rspec <path to spec file>` to run a single spec.
 
 Please see the [Appraisal gem docs](https://github.com/thoughtbot/appraisal) for more information.
 

data/lib/vorpal/aggregate_mapper.rb

@@ -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/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/configs.rb

@@ -1,13 +1,13 @@
 require 'vorpal/util/hash_initialization'
 require 'vorpal/exceptions'
+require 'vorpal/config/class_config'
 require 'equalizer'
 
 module Vorpal
   # @private
-  class MasterConfig
-    def initialize(class_configs)
-      @class_configs = class_configs
-      initialize_association_configs
+  class MainConfig
+    def initialize
+      @class_configs = []
     end
 
     def config_for(clazz)
@@ -20,7 +20,9 @@ module Vorpal
       @class_configs.detect { |conf| conf.db_class == db_object.class }
     end
 
-    private
+    def add_class_config(class_config)
+      @class_configs << class_config
+    end
 
     def initialize_association_configs
       association_configs = {}
@@ -50,6 +52,8 @@ module Vorpal
       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]
@@ -126,67 +130,6 @@ module Vorpal
     end
   end
 
-  # @private
-  class ClassConfig
-    include Equalizer.new(:domain_class, :db_class)
-    attr_reader :serializer, :deserializer, :domain_class, :db_class, :local_association_configs
-    attr_accessor :has_manys, :belongs_tos, :has_ones
-
-    def initialize(attrs)
-      @has_manys = []
-      @belongs_tos = []
-      @has_ones = []
-      @local_association_configs = []
-
-      attrs.each do |k,v|
-        instance_variable_set("@#{k}", v)
-      end
-    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
-
   # @private
   class ForeignKeyInfo
     include Equalizer.new(:fk_column, :fk_type_column, :fk_type)

data/lib/vorpal/driver/postgresql.rb

@@ -9,7 +9,12 @@ module Vorpal
       end
 
       def insert(db_class, db_objects)
-        if defined? ActiveRecord::Import
+        if ActiveRecord::VERSION::MAJOR >= 6
+          return if db_objects.empty?
+
+          update_timestamps_on_create(db_class, db_objects)
+          db_class.insert_all!(db_objects.map(&:attributes))
+        elsif defined? ActiveRecord::Import
           db_class.import(db_objects, validate: false)
         else
           db_objects.each do |db_object|
@@ -19,8 +24,15 @@ module Vorpal
       end
 
       def update(db_class, db_objects)
-        db_objects.each do |db_object|
-          db_object.save!(validate: false)
+        if ActiveRecord::VERSION::MAJOR >= 6
+          return if db_objects.empty?
+
+          update_timestamps_on_update(db_class, db_objects)
+          db_class.upsert_all(db_objects.map(&:attributes))
+        else
+          db_objects.each do |db_object|
+            db_object.save!(validate: false)
+          end
         end
       end
 
@@ -100,6 +112,30 @@ module Vorpal
 
       private
 
+      # Adapted from https://github.com/rails/rails/blob/614580270d7789e5275defc3da020ce27b3b2302/activerecord/lib/active_record/timestamp.rb#L99
+      def update_timestamps_on_create(db_class, db_objects)
+        return unless db_class.record_timestamps
+
+        current_time = db_class.current_time_from_proper_timezone
+        db_objects.each do |db_object|
+          db_class.all_timestamp_attributes_in_model.each do |column|
+            db_object.write_attribute(column, current_time) unless db_object.read_attribute(column)
+          end
+        end
+      end
+
+      #Adapted from https://github.com/rails/rails/blob/614580270d7789e5275defc3da020ce27b3b2302/activerecord/lib/active_record/timestamp.rb#L111
+      def update_timestamps_on_update(db_class, db_objects)
+        return unless db_class.record_timestamps
+
+        current_time = db_class.current_time_from_proper_timezone
+        db_objects.each do |db_object|
+          db_class.timestamp_attributes_for_update_in_model.each do |column|
+            db_object.write_attribute(column, current_time)
+          end
+        end
+      end
+
       def sequence_name(db_class)
         @sequence_names[db_class] ||= execute(
           "SELECT substring(column_default from '''(.*)''') FROM INFORMATION_SCHEMA.COLUMNS WHERE table_name = $1 AND column_name = 'id' LIMIT 1",