vorpal 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fdca5b34f5a1ac2b9b228849c53b8322e542ab9bc75a5c15a0c8003f1f1fd94
-  data.tar.gz: aebdb05efdfd853644afa49bf101d845082a7d627e47c50bf609830be46901f0
+  metadata.gz: cf920ae279d48b7b9db84a79c77eeb521602a885c8fe88e8f2121e47a5a46e41
+  data.tar.gz: 9e97596434cf65e598279005a0bb325cadde5d7a6d3f2180ea5a828432f89760
 SHA512:
-  metadata.gz: 1416691727efd279769865a4725949ff41965d120d6431a3737880936838e6760d857c3a5546b5b73774a1ea24cb1ef742d6f7cce6dfa0497de34739ba67b22a
-  data.tar.gz: 117da60ac019fa9b373d7f45ad6893b24de5611533d348034ef4f4d978adc81468d3228d55adf8107482084b219c47509cb8fef69516ae0ccdea31f73e3a0390
+  metadata.gz: d7c07c613b24c7d342be0361e33bda6db6cff0270222db1b7ca8018cf141fb623b2583e49a0d39db51d53389225e527d6a5fd74f133edc6f7653309e86644be4
+  data.tar.gz: 492d62d23506de0e26ffdc8e525169dcb78d6c1060dc9309c9828e9865f2341e8f01cc84fe95a059d01d89462c62292a67ebcfc4148ce4ace770884a56e5e04c

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,35 @@ 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
+```
+
+CAVEAT: Vorpal currently does NOT SUPPORT anyone but Vorpal setting the id of an entity!
+
 ## 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 +192,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 +201,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 +220,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,19 +247,9 @@ 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.
 
-## Running Tests
+**Q.** Are `updated_at` and `created_at` supported?
 
-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.
-
-## Contributors
-
-* [Sean Kirby](https://github.com/sskirby)
-* [Paul Sobocinski](https://github.com/psobocinski)
-* [Jason Cheong-Kee-You](https://github.com/jchunky)
+**A.** Yes. If they exist on your database tables, they will behave exactly as if you were using vanilla ActiveRecord.
 
 ## Contributing
 
@@ -252,3 +258,35 @@ For example:
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+## OSX Environment setup
+
+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 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 a specific version of Rails
+
+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.
+
+## Contributors
+
+See who's [contributed](https://github.com/nulogy/vorpal/graphs/contributors)!

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,13 +24,20 @@ 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
 
       def destroy(db_class, ids)
-        db_class.delete_all(id: ids)
+        db_class.where(id: ids).delete_all
       end
 
       # Loads instances of the given class by primary key.
@@ -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",