activerecord-model_inheritance 1.0.0

data/README.md

@@ -0,0 +1,255 @@
+# Model Inheritance
+
+An attempt at real inheritance for ActiveRecord models.
+
+This gem leverages database views (thanks to [Scenic](https://github.com/scenic-views/scenic)) to compose models
+from other models, kind of like POROs inheritance [with limitations](#limitations). Views are defined using
+[Arel](https://www.rubydoc.info/gems/arel) instead of SQL, which is cleaner and allows for easier integration.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activerecord-model_inheritance', '~> 1.0'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+## Usage
+
+First of all, if you want to make intensive use of this gem, being familiar on how [Scenic](https://github.com/scenic-views/scenic)
+works is highly recommended.
+
+### Quickstart
+
+Assuming you want a new `DerivedModel` that inherits from a preexisting `BaseModel`, follow these steps:
+
+- Generate the new model and its view definition:
+    ```bash
+    rails g active_record:model_inheritance:model DerivedModel BaseModel
+    ```
+
+- Edit the generated model and definition, if needed
+
+- Generate the SQL definition of the view and the initial migration:
+    ```bash
+    rails g active_record:model_inheritance:view DerivedModel
+    ```
+
+- Edit the generated migration if needed
+
+- Finally, run the migration:
+    ```bash
+    rails db:migrate
+    ```
+
+Keep in mind that you need to generate a new version of the SQL definition whenever your view definition changes,
+for example when you want to add some fields to the derived model.
+To do so, just run the same generator as again:
+```bash
+rails g active_record:model_inheritance:view DerivedModel
+```
+This will take care of everything, including generating the migration to update the view.
+It works similarly to Scenic.
+
+### Concepts
+
+A database view is like a _virtual table_ where the schema, as well as the data it contains, are
+defined by a plain old SQL query. Of course, since views are just query results disguised as tables, you can't write into them.
+So, at the end of the day, all this gem does is enabling write operations to Scenic view backed models.
+
+To achieve something _resembling_ real inheritance between models, the **inner model** is introduced,
+which is a third entity between the **base model** (the one you want to inherit from)
+and the **derived model** (the new one you're creating).
+
+The **inner model** holds the additional pieces your **derived model** should have.
+
+When you apply changes to a **derived model**, those changes are mapped to **inner** and **base** models.
+For example, if the **derived model** has the fields `foo` and `bar`, coming respectively from **inner** and **base** models,
+changes to `foo` will be saved to the **inner model**, and changes to `bar` will be saved to the **base model**.
+This way, the database view backing the **derived model** is always accessed in read-only mode.
+
+### Configuration
+
+If you're using Rails, the following is the code you would put inside an initializer
+to configure this gem as it is configured by default. If you're ok with this defaults, then you don't need to
+configure anything.
+```ruby
+# config/initializers/model_inheritance.rb
+
+ActiveRecord::ModelInheritance.configure do |config|
+  ## derived model options
+  
+  # name of the dynamically generated inner model class
+  config.inner_class_name = 'Inner'
+
+  # base class of the dynamically generated inner model
+  config.inner_base_class = ApplicationRecord
+  
+  # name of the belongs_to association from derived model to base model
+  config.base_reference_name = :model_inheritance_base
+
+  # name of the belongs_to association from derived model to its own inner model
+  config.inner_reference_name = :model_inheritance_inner
+
+  # whether to inherit enums from the base model
+  # only enums relevant to inherited fields will be added
+  config.inherit_enums = true
+
+  # whether to delegate missing methods from derived model to base model
+  config.delegate_missing_to_base = true
+
+  ## paths options
+
+  # these are self explanatory
+  config.models_path = Rails.root.join('app/models')
+  config.migrations_path = Rails.root.join('db/migrate')
+
+  # where to save generated SQL definitions (Scenic default)
+  config.views_path = Rails.root.join('db/views')
+
+  # where to save view definitions
+  config.definitions_path = Rails.root.join('db/views/model_inheritance')
+end
+```
+If you're not using Rails, the default configuration stays the same, except:
+```ruby
+config.inner_base_class = ActiveRecord::Base
+
+config.models_path = Pathname('app/models')
+config.migrations_path = Pathname('db/migrate')
+
+config.views_path = Pathname('db/views')
+config.definitions_path = Pathname('db/views/model_inheritance')
+```
+
+You can pass options to `derives_from` if you want to override the global derived models configuration on a per model basis:
+```ruby
+class DerivedModel < ApplicationRecord
+  include ActiveRecord::ModelInheritance::Model
+  
+  derives_from BaseModel,
+               inner_class_name: 'Inner',
+               inner_base_class: ApplicationRecord,
+               base_reference_name: :model_inheritance_base,
+               inner_reference_name: :model_inheritance_inner,
+               inherit_enums: true,
+               delegate_missing_to_base: true
+end
+```
+
+### View definitions
+A view definition is responsible of:
+- providing a convenient way of defining views using Arel
+- keeping a map of which attributes belong respectively to the base and inner model
+
+By default, the derived model will get **all** the fields from base and inner.
+If that's not what you want, you can override the default behaviour like in the following example:
+```ruby
+# db/views/model_inheritance/derived_models.rb
+
+ActiveRecord::ModelInheritance::ViewDefinition.define_derived_view DerivedModel do |inner_table, base_table|
+  inner_table
+    # all fields from inner
+    .project(inner_table[Arel.star])
+    # only some fields from base
+    .project(
+            base_table[:foo],
+            base_table[:bar],
+            base_table[:baz]
+    )
+    .join(base_table)
+    .on(inner_table[:model_inheritance_base_id].eq base_table[:id])
+end
+```
+Here, Arel is used to describe how you want the base and inner table joined.
+The block parameters `inner_table` and `base_table` are both [Arel::SelectTable](https://www.rubydoc.info/gems/arel/Arel/Table)s,
+representing the inner model table and base model table respectively.
+The code inside the block **must** evaluate to [Arel::SelectManager](https://www.rubydoc.info/gems/arel/Arel/SelectManager).
+Note that if you set the option `base_reference_name` to something different to `:model_inheritance_base`, you have to
+change the join condition accordingly.
+
+When you run the `active_record:model_inheritance:view` generator, one of the things that's done is converting that Arel::SelectManager
+(the default one or your custom provided one) to SQL. In the case of the above example, the generated SQL will look something
+like this:
+```sql
+/* db/views/derived_models_v01.sql */
+
+SELECT "derived_model_inners".*,
+       "base_models"."foo",
+       "base_models"."bar",
+       "base_models"."baz"
+FROM "derived_model_inners"
+INNER JOIN "base_models"
+    ON "derived_model_inners"."model_inheritance_base_id" = "base_models"."id"
+```
+This is how the database view backing the derived model will be created.
+
+### Sharing code between derived and inner
+Sometimes it could be useful to have code replicated in both derived and inner models.
+This can be done by passing a block to `derives_from`.
+```ruby
+class DerivedModel < ApplicationRecord
+  include ActiveRecord::ModelInheritance::Model
+
+  derives_from BaseModel do
+    def foo
+      # ...
+    end
+  end
+end
+```
+In the above example, `foo` you will be declared in both derived and inner models.
+
+### Accessing the inner model
+If for some reason you want to directly access the inner model, you can:
+```ruby
+DerivedModel::Inner   # the inner model class
+
+DerivedModel::Foo     # in case you've set inner_class_name to 'Foo'
+
+DerivedModel.first._model_inheritance_inner   # instance of the inner model
+```
+
+### A few words on multiple inheritance
+This gem doesn't strictly prohibit multiple inheritance, and in _in theory_ it should be possible to implement.
+Currently there are no plans on this, but if you find a clean solution you can share your work with us! (see [Contributing](#contributing))
+
+## Limitations
+- A derived model is not a subclass of its base model
+- Query methods called on base models will return only base models
+- Query methods called on derived models will return only derived models
+
+## Future developments
+- Improved and more comprehensive documentation
+- Some ways around current limitations
+- Testing with a dummy Rails application
+
+## Version numbers
+
+Model Inheritance loosely follows [Semantic Versioning](https://semver.org/), with a hard guarantee that breaking changes to the public API will always coincide with an increase to the `MAJOR` number.
+
+Version numbers are in three parts: `MAJOR.MINOR.PATCH`.
+
+- Breaking changes to the public API increment the `MAJOR`. There may also be changes that would otherwise increase the `MINOR` or the `PATCH`.
+- Additions, deprecations, and "big" non breaking changes to the public API increment the `MINOR`. There may also be changes that would otherwise increase the `PATCH`.
+- Bug fixes and "small" non breaking changes to the public API increment the `PATCH`.
+
+Notice that any feature deprecated by a minor release can be expected to be removed by the next major release.
+
+## Changelog
+
+Full list of changes in [CHANGELOG.md](CHANGELOG.md)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/moku-io/activerecord-model_inheritance.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: [:rubocop]

data/lib/active_record/model_inheritance/error.rb

@@ -0,0 +1,5 @@
+module ActiveRecord
+  module ModelInheritance
+    class Error < StandardError; end
+  end
+end

data/lib/active_record/model_inheritance/model.rb

@@ -0,0 +1,169 @@
+require 'active_support'
+require 'active_record'
+require_relative 'error'
+require_relative 'view_definition'
+
+module ActiveRecord
+  module ModelInheritance
+    class InheritanceError < Error; end
+
+    module Model
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :model_inheritance_base_model
+        class_attribute :model_inheritance_inner_model
+        class_attribute :model_inheritance_base_name
+        class_attribute :model_inheritance_inner_name
+        class_attribute :model_inheritance_view_definition
+        class_attribute :model_inheritance_attributes_mapping
+
+        self.primary_key = :id
+        self.record_timestamps = false
+      end
+
+      class_methods do
+        def derives_from(base_model,
+                         base_reference_name: ModelInheritance.base_reference_name,
+                         inner_reference_name: ModelInheritance.inner_reference_name,
+                         inherit_enums: ModelInheritance.inherit_enums,
+                         inner_base_class: ModelInheritance.inner_base_class,
+                         inner_class_name: ModelInheritance.inner_class_name,
+                         delegate_missing_to_base: ModelInheritance.delegate_missing_to_base,
+                         &block)
+          self.model_inheritance_base_name = base_reference_name
+          self.model_inheritance_inner_name = inner_reference_name
+          self.model_inheritance_base_model = base_model
+
+          base_ref_foreign_key = "#{model_inheritance_base_model.model_name.singular}_id"
+          base_ref = proc do
+            belongs_to base_reference_name,
+                       class_name: "::#{base_model.name}",
+                       foreign_key: base_ref_foreign_key
+          end
+
+          inner_model = Class.new inner_base_class do
+            instance_exec(&block) if block.present?
+            instance_exec(&base_ref)
+          end
+          instance_exec(&block) if block.present?
+          instance_exec(&base_ref)
+
+          const_set inner_class_name, inner_model
+          belongs_to inner_reference_name, class_name: inner_class_name, foreign_key: :id
+
+          # the secret ingredient
+          accepts_nested_attributes_for base_reference_name
+          accepts_nested_attributes_for inner_reference_name
+
+          self.model_inheritance_inner_model = inner_model
+          self.model_inheritance_view_definition = ViewDefinition.from_model self
+          self.model_inheritance_attributes_mapping = model_inheritance_view_definition.attributes_mapping
+
+          # prevents attributes from being touched when updating
+          # not strictly necessary, but better safe than sorry
+          attr_readonly attribute_names.map(&:to_sym)
+
+          if inherit_enums
+            base_model.defined_enums.each do |attribute, enum_values|
+              attribute = attribute.to_sym
+              enum attribute, enum_values if model_inheritance_attributes_mapping[:base].include? attribute
+            end
+          end
+
+          delegate_missing_to base_reference_name if delegate_missing_to_base
+        end
+
+        def partition_attributes attributes
+          inner_attributes = attributes.select { |key| model_inheritance_attributes_mapping[:inner].include? key.to_sym }
+          base_attributes = attributes.select { |key| model_inheritance_attributes_mapping[:base].include? key.to_sym }
+
+          [inner_attributes, base_attributes]
+        end
+
+        def create(...)
+          super.reload
+        end
+
+        def create!(...)
+          super.reload
+        end
+
+        # overriding the following methods to prevent ConnectionAdapter from touching the underlying view
+
+        def _insert_record(...)
+          nil
+        end
+
+        def _update_record(...)
+          nil
+        end
+
+        def _delete_record(...)
+          nil
+        end
+      end
+
+      def save(**options, &)
+        prepare_save
+        super && _model_inheritance_base.save
+      end
+
+      def save!(**options, &)
+        prepare_save
+        super
+        _model_inheritance_base.save!
+      end
+
+      def destroy
+        _model_inheritance_inner.destroy
+        super
+      end
+
+      def delete
+        _model_inheritance_inner.delete
+        super
+      end
+
+      def _model_inheritance_base
+        public_send model_inheritance_base_name
+      end
+
+      def _model_inheritance_inner
+        public_send model_inheritance_inner_name
+      end
+
+    private
+
+      def prepare_save
+        inner_attributes, base_attributes = self.class.partition_attributes attributes_for_database
+
+        if new_record?
+          unless _model_inheritance_base.present?
+            raise InheritanceError, "#{model_inheritance_base_name} must be present"
+          end
+
+          # pass updated base attributes to base model
+          # this way it gets automatically updated
+          base_attributes.compact!
+          _model_inheritance_base.assign_attributes base_attributes if base_attributes.present?
+
+          attributes = {
+            model_inheritance_base_name                         => _model_inheritance_base,
+            "#{model_inheritance_inner_name}_attributes".to_sym => inner_attributes
+          }
+        else
+          inner_attributes[:id] = id
+          base_attributes[:id] = _model_inheritance_base.id
+
+          attributes = {
+            "#{model_inheritance_base_name}_attributes".to_sym  => base_attributes,
+            "#{model_inheritance_inner_name}_attributes".to_sym => inner_attributes
+          }
+        end
+
+        assign_attributes attributes
+      end
+    end
+  end
+end

data/lib/active_record/model_inheritance/version.rb

@@ -0,0 +1,5 @@
+module ActiveRecord
+  module ModelInheritance
+    VERSION = '1.0.0'.freeze
+  end
+end

data/lib/active_record/model_inheritance/view_definition.rb

@@ -0,0 +1,112 @@
+require 'arel'
+require_relative 'error'
+
+module ActiveRecord
+  module ModelInheritance
+    class DefinitionError < Error; end
+
+    class ViewDefinition
+      attr_reader :definition
+      attr_reader :model_class
+
+      def initialize model_class, definition
+        @model_class = model_class
+        @definition = definition
+      end
+
+      def to_sql
+        @definition.to_sql
+      end
+
+      def attributes_mapping
+        definition
+          .projections
+          .each_with_object({base: [], inner: []}) do |projection, attributes_mapping|
+            if projection.is_a? Arel::Nodes::As
+              relation = projection.left.relation
+              name = projection.right
+            else
+              relation = projection.relation
+              name = projection.name
+            end
+
+            case relation
+            when model_class.model_inheritance_inner_model.arel_table
+              relation_type = :inner
+              relation_model = model_class.model_inheritance_inner_model
+            when model_class.model_inheritance_base_model.arel_table
+              relation_type = :base
+              relation_model = model_class.model_inheritance_base_model
+            else
+              raise DefinitionError, "Invalid \"#{relation}\" relation"
+            end
+
+            attributes = if name == Arel.star
+                           relation_model.attribute_names.map(&:to_sym)
+                         else
+                           [name.to_sym]
+                         end
+
+            attributes_mapping[relation_type] += attributes
+          end
+      end
+
+      def self.from_model model_class
+        unless model_class.include? Model
+          raise ArgumentError, "#{model_class.name} doesn't include ActiveRecord::ModelInheritance::Model"
+        end
+
+        ViewDefinition.from_name model_class.model_name.plural
+      end
+
+      def self.from_name name
+        definition_filename = Pathname(ModelInheritance.config.definitions_path).join "#{name}.rb"
+        raise ArgumentError, "Definition for \"#{name}\" doesn't exist" unless definition_filename.file?
+
+        eval File.read definition_filename
+      end
+
+      def self.define_derived_view model_class, &block
+        inner_model = model_class.model_inheritance_inner_model
+        base_model = model_class.model_inheritance_base_model
+
+        inner_table = inner_model.arel_table
+        base_table = base_model.arel_table
+
+        definition = if block_given?
+                       block.call(inner_table, base_table).tap do |d|
+                         unless d.is_a? Arel::SelectManager
+                           raise DefinitionError, 'Defined view must evaluate to Arel::SelectManager'
+                         end
+                       end
+                     else
+                       selected_base_columns = if inner_model.primary_key == base_model.primary_key
+                                                 # this is a common naming conflict problem
+                                                 # makes sense to try and solve automatically
+
+                                                 # just delete the base primary key from columns that will be selected
+                                                 base_model
+                                                   .column_names
+                                                   .dup
+                                                   .delete_if { |column_name| column_name == base_model.primary_key }
+                                               else
+                                                 base_model.column_names
+                                               end.map { |column_name| base_table[column_name.to_sym] }
+
+                       base_reference = model_class
+                                          .reflect_on_association(model_class.model_inheritance_base_name)
+                                          .foreign_key
+                                          .to_sym
+
+                       inner_table
+                         .project(inner_table[Arel.star])
+                         .project(*selected_base_columns)
+                         .join(base_table)
+                         .on(inner_table[base_reference].eq base_table[base_model.primary_key])
+                     end
+
+        ViewDefinition.new model_class, definition
+      end
+    end
+  end
+end

data/lib/active_record/model_inheritance.rb

@@ -0,0 +1,57 @@
+require 'scenic'
+require 'active_record'
+require 'active_support'
+require_relative 'model_inheritance/version'
+
+module ActiveRecord
+  module ModelInheritance
+    include ActiveSupport::Configurable
+
+    config.define_singleton_method :define_lazy_property do |key, &block|
+      self[key] = nil
+
+      define_singleton_method key do
+        self[key] || (self[key] = block.call)
+      end
+    end
+
+    config.define_singleton_method :define_lazy_path do |name, *dirs|
+      define_lazy_property name do
+        if defined?(Rails.root) && Rails.root
+          Rails.root.join(*dirs)
+        else
+          Pathname(dirs.join '/')
+        end
+      end
+
+      define_singleton_method "#{name}=".to_sym do |path|
+        self[name] = Pathname(path)
+      end
+    end
+
+    config.base_reference_name = :model_inheritance_base
+    config.inner_reference_name = :model_inheritance_inner
+    config.inner_class_name = 'Inner'
+    config.inherit_enums = true
+    config.delegate_missing_to_base = true
+
+    config.define_lazy_path :views_path, 'db', 'views'
+    config.define_lazy_path :models_path, 'app', 'models'
+    config.define_lazy_path :migrations_path, 'db', 'migrate'
+    config.define_lazy_path :definitions_path, 'db', 'views', 'model_inheritance'
+
+    config.define_lazy_property :inner_base_class do
+      if defined? ApplicationRecord
+        ApplicationRecord
+      else
+        ActiveRecord::Base
+      end
+    end
+
+    singleton_class.delegate(*config.keys, to: :config)
+  end
+end
+
+require_relative 'model_inheritance/error'
+require_relative 'model_inheritance/model'
+require_relative 'model_inheritance/view_definition'

data/lib/activerecord/model_inheritance.rb

@@ -0,0 +1 @@
+require_relative '../active_record/model_inheritance'

data/lib/generators/active_record/model_inheritance/generators.rb

@@ -0,0 +1,6 @@
+module ActiveRecord
+  module ModelInheritance
+    module Generators
+    end
+  end
+end