dbee 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01e542a4c7d9eb3f9641aa7b54f776f32b88e178129ad0e4af219b3965315090
-  data.tar.gz: a94879eb871f87ed9b9c3f7bccbe3ddfa5a177f558a842572f7632d09feab1fc
+  metadata.gz: ae136319b1de6f828e34e6e0546b7c6663848efecbf8bfb42f8fe6204bebb20c
+  data.tar.gz: 1690b0f58befeade514c2949163d37ada74f673235ab64a49ec18f7ffde58e1d
 SHA512:
-  metadata.gz: af62cb3558f7557e939be6b5b4606c299436f782b40441bad3dac27c18560c9c9e55b1884c3645dcfada969f8d704c0aeb313e9731d0dd1cfcab8d7e634efa9e
-  data.tar.gz: 9f87776b0c84ff7c31c0df4d08d7f0725064adcdec21c8653995d1370426bd7d5a3b13c33946e8c1b72816cf0d9906ea0bc970ba61656876d84b3e0081fb93bc
+  metadata.gz: 82c42cf23dbaed18644da3b2e02bc406833a65ca6429c8d31d824de44cf08fe2b503c4af32c6199646fbe797abe7af9dc434d75acff91b1fb7b502d2f7eb6d35
+  data.tar.gz: '07482747b169ccfde19405381d5128bd07ee269374e75c0f577ee34c26b3a0d877654c70da3a0b1bdd8ce31a1e591a4d0d8c11050390b3a5be18e06f7b312b11'

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 1.2.0 (August 29th, 2019)
+
+Additions:
+
+* Added partitioners to a model specification.  A Partitioner is essentially a way of explicitly specifying that a data model must meet a specific equality for a column.
+
+Changes:
+
+* Model#ancestors renamed to Model#ancestors!
+* Model#ancestor now returns a hash where the key is an array of strings and not just a pre-concatenated string.
+
 # 1.1.0 (August 28th, 2019)
 
 Additions:

data/README.md

@@ -175,6 +175,44 @@ models:
 
 It is up to you to determine which modeling technique to use as both are equivalent.  Technically speaking, the code-first DSL is nothing more than syntactic sugar on top of Dbee::Model.
 
+#### Table Partitioning
+
+You can leverage the model partitioners for hard-coding partitioning by column=value.  The initial use-case for this was to mirror how ActiveRecord deals with (Single Table Inheritance)[https://api.rubyonrails.org/v6.0.0/classes/ActiveRecord/Base.html#class-ActiveRecord::Base-label-Single+table+inheritance].  Here is a basic example of how to partition an `animals` table for different subclasses:
+
+##### Code-first:
+
+````ruby
+class Dogs < Dbee::Base
+  table 'animals'
+
+  partitioner :type, 'Dog'
+end
+
+class Cats < Dbee::Base
+  table 'animals'
+
+  partitioner :type, 'Cat'
+end
+````
+
+##### Configuration-first:
+
+````yaml
+Dogs:
+  name: dogs
+  table: animals
+  partitioners:
+    - name: type
+      value: Dog
+
+Cats:
+  name: cats
+  table: animals
+  partitioners:
+    - name: type
+      value: Cat
+````
+
 ### The Query API
 
 The Query API (Dbee::Query) is a simplified and abstract way to model an SQL query.  A Query has the following components:

data/lib/dbee/base.rb

@@ -12,6 +12,10 @@ module Dbee
   # Model declaration.
   class Base
     class << self
+      def partitioner(name, value)
+        partitioners << { name: name, value: value }
+      end
+
       def table(name)
         @table_name = name.to_s
 
@@ -51,6 +55,10 @@ module Dbee
         @associations_by_name ||= {}
       end
 
+      def partitioners
+        @partitioners ||= []
+      end
+
       def table_name?
         !table_name.empty?
       end
@@ -65,6 +73,12 @@ module Dbee
         end
       end
 
+      def inherited_partitioners
+        reversed_subclasses.inject([]) do |memo, subclass|
+          memo + subclass.partitioners
+        end
+      end
+
       private
 
       def subclasses
@@ -78,6 +92,7 @@ module Dbee
       def model_config(key_chain, name, constraints, path_parts)
         {
           constraints: constraints,
+          partitioners: inherited_partitioners,
           models: associations(key_chain, path_parts),
           name: name,
           table: derive_table

data/lib/dbee/model/partitioner.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+#
+# Copyright (c) 2019-present, Blue Marble Payroll, LLC
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+#
+
+module Dbee
+  class Model
+    # An Partitioner is a way to explicitly define constraints on a model.  For example, say we
+    # want to create a data model, but restrict the returned data to a subset based on a 'type'
+    # column like ActiveRecord does for Single Table Inheritance. We could use a partition
+    # to define this constraint.
+    class Partitioner
+      acts_as_hashable
+
+      attr_reader :name, :value
+
+      def initialize(name: '', value: nil)
+        raise ArgumentError, 'name is required' if name.to_s.empty?
+
+        @name   = name.to_s
+        @value  = value
+      end
+
+      def <=>(other)
+        "#{name}#{value}" <=> "#{other.name}#{other.value}"
+      end
+
+      def hash
+        "#{name}#{value}".hash
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) &&
+          other.name == name &&
+          other.value == value
+      end
+      alias eql? ==
+    end
+  end
+end

data/lib/dbee/model.rb

@@ -8,6 +8,7 @@
 #
 
 require_relative 'model/constraints'
+require_relative 'model/partitioner'
 
 module Dbee
   # In DB terms, a Model is usually a table, but it does not have to be.  You can also re-model
@@ -16,53 +17,48 @@ module Dbee
     extend Forwardable
     acts_as_hashable
 
-    JOIN_CHAR = '.'
-
-    private_constant :JOIN_CHAR
-
     class ModelNotFoundError < StandardError; end
 
-    attr_reader :constraints, :name, :table
-
-    def_delegator :models_by_name, :values, :models
+    attr_reader :constraints, :filters, :name, :partitioners, :table
 
-    def_delegator :models, :sort, :sorted_models
+    def_delegator :models_by_name,  :values,  :models
+    def_delegator :models,          :sort,    :sorted_models
+    def_delegator :constraints,     :sort,    :sorted_constraints
+    def_delegator :partitioners,    :sort,    :sorted_partitioners
 
-    def_delegator :constraints, :sort, :sorted_constraints
-
-    def initialize(name:, constraints: [], models: [], table: '')
+    def initialize(name:, constraints: [], models: [], partitioners: [], table: '')
       raise ArgumentError, 'name is required' if name.to_s.empty?
 
       @name           = name.to_s
-      @constraints    = Constraints.array(constraints)
+      @constraints    = Constraints.array(constraints).uniq
       @models_by_name = name_hash(Model.array(models))
+      @partitioners   = Partitioner.array(partitioners).uniq
       @table          = table.to_s.empty? ? @name : table.to_s
 
       freeze
     end
 
-    def name_hash(array)
-      array.map { |a| [a.name, a] }.to_h
-    end
-
-    def ancestors(parts = [], alias_chain = [], found = {})
+    # This recursive method will walk a path of model names (parts) and return back a
+    # flattened hash instead of a nested object structure.
+    # The hash key will be an array of strings (model names) and the value will be the
+    # identified model.
+    def ancestors!(parts = [], visited_parts = [], found = {})
       return found if Array(parts).empty?
 
-      alias_chain = [] if Array(alias_chain).empty?
-
-      model_name = parts.first
+      # Take the first entry in parts
+      model_name = parts.first.to_s
 
-      model = models_by_name[model_name.to_s]
+      # Ensure we have it registered as a child, or raise error
+      model = assert_model(model_name, visited_parts)
 
-      raise ModelNotFoundError, "Cannot traverse: #{model_name}" unless model
+      # Push onto visited list
+      visited_parts += [model_name]
 
-      new_alias_chain = alias_chain + [model_name]
+      # Add found model to flattened structure
+      found[visited_parts] = model
 
-      new_alias = new_alias_chain.join(JOIN_CHAR)
-
-      found[new_alias] = model
-
-      model.ancestors(parts[1..-1], new_alias_chain, found)
+      # Recursively call for next parts in the chain
+      model.ancestors!(parts[1..-1], visited_parts, found)
     end
 
     def ==(other)
@@ -70,6 +66,7 @@ module Dbee
         other.name == name &&
         other.table == table &&
         other.sorted_constraints == sorted_constraints &&
+        other.sorted_partitioners == sorted_partitioners &&
         other.sorted_models == sorted_models
     end
     alias eql? ==
@@ -81,5 +78,14 @@ module Dbee
     private
 
     attr_reader :models_by_name
+
+    def assert_model(model_name, visited_parts)
+      models_by_name[model_name] ||
+        raise(ModelNotFoundError, "Missing: #{model_name}, after: #{visited_parts}")
+    end
+
+    def name_hash(array)
+      array.map { |a| [a.name, a] }.to_h
+    end
   end
 end

data/lib/dbee/query/filters.rb

@@ -21,7 +21,7 @@ require_relative 'filters/starts_with'
 module Dbee
   class Query
     # Top-level class that allows for the making of filters.  For example, you can call this as:
-    # - Filters.make(type: :contains, value: 'something')
+    # - Filters.make(key_path: :field, type: :contains, value: 'something')
     class Filters
       acts_as_hashable_factory
 

data/lib/dbee/version.rb

@@ -8,5 +8,5 @@
 #
 
 module Dbee
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/spec/dbee/base_spec.rb

@@ -72,4 +72,32 @@ describe Dbee::Base do
       expect(Models::E.inherited_table_name).to eq('table_set_to_e')
     end
   end
+
+  describe 'partitioners' do
+    it 'honors partitioners on a root model' do
+      model_name      = 'Partitioner Example 1'
+      expected_config = yaml_fixture('models.yaml')[model_name]
+      expected_model = Dbee::Model.make(expected_config)
+
+      key_paths = %w[id]
+      key_chain = Dbee::KeyChain.new(key_paths)
+
+      actual_model = PartitionerExamples::Dogs.to_model(key_chain)
+
+      expect(actual_model).to eq(expected_model)
+    end
+
+    it 'honors partitioners on a child model' do
+      model_name      = 'Partitioner Example 2'
+      expected_config = yaml_fixture('models.yaml')[model_name]
+      expected_model = Dbee::Model.make(expected_config)
+
+      key_paths = %w[id dogs.id]
+      key_chain = Dbee::KeyChain.new(key_paths)
+
+      actual_model = PartitionerExamples::Owners.to_model(key_chain)
+
+      expect(actual_model).to eq(expected_model)
+    end
+  end
 end

data/spec/dbee/model_spec.rb

@@ -66,10 +66,10 @@ describe Dbee::Model do
       members = subject.models.first
 
       expected_plan = {
-        'members' => members
+        %w[members] => members
       }
 
-      plan = subject.ancestors(%w[members])
+      plan = subject.ancestors!(%w[members])
 
       expect(plan).to eq(expected_plan)
     end
@@ -80,12 +80,12 @@ describe Dbee::Model do
       phone_numbers = demos.models.first
 
       expected_plan = {
-        'members' => members,
-        'members.demos' => demos,
-        'members.demos.phone_numbers' => phone_numbers
+        %w[members] => members,
+        %w[members demos] => demos,
+        %w[members demos phone_numbers] => phone_numbers
       }
 
-      plan = subject.ancestors(%w[members demos phone_numbers])
+      plan = subject.ancestors!(%w[members demos phone_numbers])
 
       expect(plan).to eq(expected_plan)
     end

data/spec/fixtures/models.rb

@@ -139,3 +139,20 @@ module Cycles
     association :a, model: 'Cycles::A'
   end
 end
+
+# Examples of Rails Single Table Inheritance.
+module PartitionerExamples
+  class Owners < Dbee::Base
+    association :dogs, model: 'PartitionerExamples::Dogs', constraints: {
+      name: :owner_id, parent: :id
+    }
+  end
+
+  class Dogs < Dbee::Base
+    table 'animals'
+
+    partitioner :type, 'Dog'
+
+    partitioner :deleted, false
+  end
+end

data/spec/fixtures/models.yaml

@@ -186,3 +186,26 @@ Cycle Example:
                   table: b
                   models:
                     - name: c
+
+Partitioner Example 1:
+  name: dogs
+  table: animals
+  partitioners:
+    - name: type
+      value: Dog
+    - name: deleted
+      value: false
+
+Partitioner Example 2:
+  name: owners
+  models:
+    - name: dogs
+      table: animals
+      constraints:
+        - name: owner_id
+          parent: id
+      partitioners:
+        - name: type
+          value: Dog
+        - name: deleted
+          value: false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dbee
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Matthew Ruggio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-28 00:00:00.000000000 Z
+date: 2019-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: acts_as_hashable
@@ -162,6 +162,7 @@ files:
 - lib/dbee/model/constraints/base.rb
 - lib/dbee/model/constraints/reference.rb
 - lib/dbee/model/constraints/static.rb
+- lib/dbee/model/partitioner.rb
 - lib/dbee/providers.rb
 - lib/dbee/providers/null_provider.rb
 - lib/dbee/query.rb