vorpal 0.1.0.rc3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 824912a10087771cda48b9ad66dac75861e80bb1
-  data.tar.gz: 67ff5e87b3e45c8308866036e79cfb83ae5959d8
+SHA256:
+  metadata.gz: c866f3e83daac73f28e5c9a53875b73d7f8db95cbf437200f0b0c69cce81d317
+  data.tar.gz: e1e91f848552e1f3710849370978d4a1e322e65b12c65bebcd995b76960ba44e
 SHA512:
-  metadata.gz: 3db514381c185a0dc4b9b4a408ca35b34a244bb1fe97e899ff1b89ebb84d14cd20d5159c2a459316d77c1e3b4d81e4529e0ff110d02dfdece3f06817531653b1
-  data.tar.gz: 5437e2611a1ae1e75b1143cd1f9732429fa9acb0fb5e11fc105e60bb7d0330fe4e23021ca7c63b676758977fedeafaed2b39f26be24f83b1f431fc5c7ab1a0b2
+  metadata.gz: 5bcd5518f56b4c43f4180d3f63c75c6186c1bd89bee939b8410e656f3df411920238eaf51da4a590367f929507c3bdb1ada98cf972d6ebf6785432417018b9a2
+  data.tar.gz: 85e53e6946ea0d0f06e14d8913ac3eba45668b3d08bfc0036a789620ea05af587cb5a97991467eadfea1f76d5dd3fccaf71c96aeec2345327d9538e714e0e720

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=master)](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/master/graph/badge.svg)](https://codecov.io/gh/nulogy/vorpal/branch/master)
 
 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).
@@ -45,8 +42,6 @@ Or install it yourself as:
 
 ## Usage
 
-**Warning! API still in flux! Expect it to change with every release until 0.1.0. After this point, semantic versioning will be used.**
-
 Start with a domain model of POROs and AR::Base objects that form an aggregate:
 
 ```ruby
@@ -145,7 +140,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:
 
@@ -176,7 +172,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.
 
@@ -185,13 +181,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 UUID primary keys.
 * Nicer DSL for specifying attributes that have different names in the domain model than in the DB.
+* Show how to implement POROs without using Virtus (it is unsupported and can be crazy slow)
+* Aggregate updated_at.
+* Better support for value objects.
 
 ## FAQ
 
@@ -207,11 +201,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/master/Vorpal/AggregateMapper#query-instance_method) method on the [AggregateMapper](https://rubydoc.info/github/nulogy/vorpal/master/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
 ```
 
@@ -233,19 +228,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
-
-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
+**Q.** Are `updated_at` and `created_at` supported?
 
-* [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
 
@@ -254,3 +239,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/db_loader.rb

@@ -1,6 +1,5 @@
 require 'vorpal/loaded_objects'
 require 'vorpal/util/array_hash'
-require 'vorpal/db_driver'
 
 module Vorpal
   # Handles loading of objects from the database.
@@ -13,7 +12,7 @@ module Vorpal
     end
 
     def load_from_db(ids, config)
-      db_roots = @db_driver.load_by_id(config, ids)
+      db_roots = @db_driver.load_by_id(config.db_class, ids)
       load_from_db_objects(db_roots, config)
     end
 
@@ -123,7 +122,7 @@ module Vorpal
 
     def load_all(db_driver)
       return [] if @ids.empty?
-      db_driver.load_by_id(@config, @ids)
+      db_driver.load_by_id(@config.db_class, @ids)
     end
   end
 
@@ -138,7 +137,7 @@ module Vorpal
 
     def load_all(db_driver)
       return [] if @fk_values.empty?
-      db_driver.load_by_foreign_key(@config, @fk_values, @fk_info)
+      db_driver.load_by_foreign_key(@config.db_class, @fk_values, @fk_info)
     end
   end
 end

data/lib/vorpal/driver/postgresql.rb

@@ -0,0 +1,181 @@
+require 'vorpal/util/string_utils.rb'
+
+module Vorpal
+  module Driver
+    # Interface between the database and Vorpal for PostgreSQL using ActiveRecord.
+    class Postgresql
+      def initialize
+        @sequence_names = {}
+      end
+
+      def insert(db_class, db_objects)
+        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|
+            db_object.save!(validate: false)
+          end
+        end
+      end
+
+      def update(db_class, db_objects)
+        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.where(id: ids).delete_all
+      end
+
+      # Loads instances of the given class by primary 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
+      end
+
+      # Loads instances of the given class whose foreign key has the given value.
+      #
+      # @param db_class [Class] A subclass of ActiveRecord::Base
+      # @param id [Integer] The value of the foreign key to find by. (Can also be an array of ids.)
+      # @param foreign_key_info [ForeignKeyInfo] Meta data for the foreign key.
+      # @return [[Object]] An array of entities.
+      def load_by_foreign_key(db_class, id, foreign_key_info)
+        arel = db_class.where(foreign_key_info.fk_column => id)
+        arel = arel.where(foreign_key_info.fk_type_column => foreign_key_info.fk_type) if foreign_key_info.polymorphic?
+        arel.to_a
+      end
+
+      # Fetches primary key values to be used for new entities.
+      #
+      # @param db_class [Class] A subclass of ActiveRecord::Base
+      # @return [[Integer]] An array of unused primary keys.
+      def get_primary_keys(db_class, count)
+        result = execute("select nextval($1) from generate_series(1,$2);", [sequence_name(db_class), count])
+        result.rows.map(&:first).map(&:to_i)
+      end
+
+      # Builds an ORM Class for accessing data in the given DB table.
+      #
+      # @param model_class [Class] The PORO class that we are creating a DB interface class for.
+      # @param table_name [String] Name of the DB table the DB class should interface with.
+      # @return [Class] ActiveRecord::Base Class
+      def build_db_class(model_class, table_name)
+        db_class = Class.new(ActiveRecord::Base) do
+          class << self
+            # This is overridden for two reasons:
+            # 1) For anonymous classes, #name normally returns nil. Class names in Ruby come from the
+            #   name of the constant they are assigned to.
+            # 2) Because the default implementation for Class#name for anonymous classes is very, very
+            #   slow. https://bugs.ruby-lang.org/issues/11119
+            # Remove this override once #2 has been fixed!
+            def name
+              @name ||= "Vorpal_generated_ActiveRecord__Base_class_for_#{vorpal_model_class_name}"
+            end
+
+            # Overridden because, like #name, the default implementation for anonymous classes is very,
+            # very slow.
+            def to_s
+              name
+            end
+
+            attr_accessor :vorpal_model_class_name
+          end
+        end
+
+        db_class.vorpal_model_class_name = Util::StringUtils.escape_class_name(model_class.name)
+        db_class.table_name = table_name
+        db_class
+      end
+
+      # Builds a composable query object (e.g. ActiveRecord::Relation) with Vorpal methods mixed in
+      # for querying for instances of the given AR::Base class.
+      #
+      # @param db_class [Class] A subclass of ActiveRecord::Base
+      def query(db_class, aggregate_mapper)
+        db_class.unscoped.extending(ArelQueryMethods.new(aggregate_mapper))
+      end
+
+      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",
+          [db_class.table_name]
+        ).rows.first.first
+      end
+
+      def execute(sql, binds)
+        binds = binds.map { |row| [nil, row] }
+        ActiveRecord::Base.connection.exec_query(sql, 'SQL', binds)
+      end
+    end
+
+    class ArelQueryMethods < Module
+      def initialize(mapper)
+        @mapper = mapper
+      end
+
+      def extended(descendant)
+        super
+        descendant.extend(Methods)
+        descendant.vorpal_aggregate_mapper = @mapper
+      end
+
+      # Methods in this module will appear on any composable
+      module Methods
+        attr_writer :vorpal_aggregate_mapper
+
+        # See {AggregateMapper#load_many}.
+        def load_many
+          db_roots = self.to_a
+          @vorpal_aggregate_mapper.load_many(db_roots)
+        end
+
+        # See {AggregateMapper#load_one}.
+        def load_one
+          db_root = self.first
+          @vorpal_aggregate_mapper.load_one(db_root)
+        end
+      end
+    end
+  end
+end

data/lib/vorpal/dsl/config_builder.rb

@@ -22,43 +22,58 @@ module Vorpal
       @attributes.concat(attributes)
     end
 
-    # Defines a one-to-many association with a list of objects of the same type.
+    # Defines a one-to-many association to another type where the foreign key is stored on the child.
     #
-    # @param name [String] Name of the attribute that will refer to the other object.
+    # 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'.
+    #
+    # @param name [String] Name of the association getter.
     # @param options [Hash]
-    # @option options [Boolean] :owned
-    # @option options [String] :fk
-    # @option options [String] :fk_type
-    # @option options [Class] :child_class
+    # @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.
     def has_many(name, options={})
       @has_manys << {name: name}.merge(options)
     end
 
-    # Defines a one-to-one association with another object where the foreign key
-    # is stored on the other object.
+    # Defines a one-to-one association to another type where the foreign key
+    # is stored on the child.
+    #
+    # 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'.
     #
-    # @param name [String] Name of the attribute that will refer to the other object.
+    # @param name [String] Name of the association getter.
     # @param options [Hash]
-    # @option options [Boolean] :owned
-    # @option options [String] :fk
-    # @option options [String] :fk_type
-    # @option options [Class] :child_class
+    # @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.
     def has_one(name, options={})
       @has_ones << {name: name}.merge(options)
     end
 
-    # Defines a one-to-one association with another object where the foreign key
-    # is stored on this object.
+    # Defines a one-to-one association with another type where the foreign key
+    # is stored on the parent.
+    #
+    # This association can be polymorphic. I.E. children can be of different types.
     #
-    # This association can be polymorphic. i.e.
+    # 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'.
     #
-    # @param name [String] Name of the attribute that will refer to the other object.
+    # @param name [String] Name of the association getter.
     # @param options [Hash]
-    # @option options [Boolean] :owned
-    # @option options [String] :fk
-    # @option options [String] :fk_type
-    # @option options [Class] :child_class
-    # @option options [[Class]] :child_classes
+    # @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`.
     def belongs_to(name, options={})
       @belongs_tos << {name: name}.merge(options)
     end