dbee 2.1.0.pre.alpha → 3.1.0

data/lib/dbee/dsl_schema_builder.rb

@@ -0,0 +1,86 @@
+# 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
+  # Builds a Dbee::Schema given a Dbee::Base (DSL) model. Note that this class
+  # does not exist in the "Dsl" module as it is not used for defining the DSL
+  # itself.
+  class DslSchemaBuilder # :nodoc:
+    attr_reader :dsl_model, :key_chain
+
+    def initialize(dsl_model, key_chain)
+      @dsl_model = dsl_model || ArgumentError('dsl_model is required')
+      @key_chain = key_chain || ArgumentError('key_chain is required')
+
+      freeze
+    end
+
+    def to_schema
+      schema_spec = { dsl_model.inflected_class_name => model_config(dsl_model) }
+
+      ancestor_paths(key_chain).each do |key_path|
+        start_model = dsl_model
+
+        key_path.ancestor_names.each do |association_name|
+          start_model = append_model_and_relationship(schema_spec, start_model, association_name)
+        end
+      end
+
+      Schema.new(schema_spec)
+    end
+
+    private
+
+    def model_config(dsl_model) # :nodoc:
+      {
+        name: dsl_model.inflected_class_name,
+        partitioners: dsl_model.inherited_partitioners,
+        table: dsl_model.inherited_table_name,
+        relationships: {}
+      }
+    end
+
+    def append_model_and_relationship(schema_spec, base_model, association_name)
+      association = find_association!(base_model, association_name)
+      target_model = association.model_constant
+
+      schema_spec[target_model.inflected_class_name] ||= model_config(target_model)
+
+      schema_spec[base_model.inflected_class_name][:relationships][association.name] = {
+        constraints: association.constraints,
+        model: relationship_model_name(association, target_model)
+      }
+
+      target_model
+    end
+
+    # Returns a unique list of ancestor paths from a key_chain. Omits any
+    # fields on the base model.
+    def ancestor_paths(key_chain)
+      key_chain.to_unique_ancestors.key_path_set.select do |key_path|
+        key_path.ancestor_names.any?
+      end
+    end
+
+    def find_association!(base_model, association_name)
+      base_model.inherited_associations.find { |assoc| assoc.name == association_name } \
+        ||
+        raise(
+          ArgumentError,
+          "no association #{association_name} exists on model #{base_model.name}"
+        )
+    end
+
+    def relationship_model_name(association, target_model)
+      return nil if association.name == target_model.inflected_class_name
+
+      target_model.inflected_class_name
+    end
+  end
+end

data/lib/dbee/key_chain.rb

@@ -38,5 +38,16 @@ module Dbee
 
       ancestor_path_set.include?(path)
     end
+
+    # Returns a unique set of ancestors by considering all column names to be the same.
+    def to_unique_ancestors # :nodoc:
+      normalized_paths = key_path_set.map do |kp|
+        KeyPath.new((kp.ancestor_names + COLUMN_PLACEHOLDER).join(KeyPath::SPLIT_CHAR))
+      end
+      self.class.new(normalized_paths.uniq)
+    end
+
+    COLUMN_PLACEHOLDER = ['any_column'].freeze
+    private_constant :COLUMN_PLACEHOLDER
   end
 end

data/lib/dbee/model/relationships/basic.rb

@@ -0,0 +1,47 @@
+# 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
+    class Relationships
+      # A relationship from one model to another.
+      class Basic
+        acts_as_hashable
+
+        attr_reader :constraints, :model, :name
+
+        def initialize(name:, constraints: [], model: nil)
+          @name = name
+          raise ArgumentError, 'name is required' if name.to_s.empty?
+
+          @constraints = Constraints.array(constraints || []).uniq
+          @model = model
+
+          freeze
+        end
+
+        def model_name
+          model || name
+        end
+
+        def hash
+          [self.class.hash, name.hash, constraints.hash, model.hash].hash
+        end
+
+        def ==(other)
+          other.instance_of?(self.class) &&
+            other.name == name &&
+            other.constraints == constraints &&
+            other.model == model
+        end
+        alias eql? ==
+      end
+    end
+  end
+end

data/lib/dbee/model/relationships.rb

@@ -0,0 +1,24 @@
+# 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.
+#
+
+require_relative 'relationships/basic'
+require_relative '../util/make_keyed_by'
+
+module Dbee
+  class Model
+    # Top-level class that allows for the making of relationships.
+    class Relationships
+      acts_as_hashable_factory
+      extend Dbee::Util::MakeKeyedBy
+
+      register 'basic', Basic
+      register '',      Basic # When type is not present this will be the default
+    end
+  end
+end

data/lib/dbee/model.rb

@@ -9,65 +9,53 @@
 
 require_relative 'model/constraints'
 require_relative 'model/partitioner'
+require_relative 'model/relationships'
+require_relative 'util/make_keyed_by'
 
 module Dbee
   # In DB terms, a Model is usually a table, but it does not have to be.  You can also re-model
   # your DB schema using Dbee::Models.
   class Model
-    extend Forwardable
     acts_as_hashable
+    extend Dbee::Util::MakeKeyedBy
+    extend Forwardable
 
     class ModelNotFoundError < StandardError; end
 
-    attr_reader :constraints, :filters, :name, :partitioners, :table
+    attr_reader :constraints, :filters, :name, :partitioners, :relationships, :table
 
     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 initialize(name:, constraints: [], models: [], partitioners: [], table: '')
-      raise ArgumentError, 'name is required' if name.to_s.empty?
-
-      @name           = name.to_s
-      @constraints    = Constraints.array(constraints).uniq
+    def initialize(
+      name:,
+      constraints: [], # Exists here for tree based model backward compatibility.
+      relationships: [],
+      models: [],      # Exists here for tree based model backward compatibility.
+      partitioners: [],
+      table: ''
+    )
+      @name           = name
+      @constraints    = Constraints.array(constraints || []).uniq
+      @relationships  = Relationships.make_keyed_by(:name, relationships)
       @models_by_name = name_hash(Model.array(models))
       @partitioners   = Partitioner.array(partitioners).uniq
       @table          = table.to_s.empty? ? @name : table.to_s
 
+      ensure_input_is_valid
+
       freeze
     end
 
-    # 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?
-
-      # Take the first entry in parts
-      model_name = parts.first.to_s
-
-      # Ensure we have it registered as a child, or raise error
-      model = assert_model(model_name, visited_parts)
-
-      # Push onto visited list
-      visited_parts += [model_name]
-
-      # Add found model to flattened structure
-      found[visited_parts] = model
-
-      # Recursively call for next parts in the chain
-      model.ancestors!(parts[1..-1], visited_parts, found)
+    def relationship_for_name(relationship_name)
+      relationships[relationship_name]
     end
 
     def ==(other)
       other.instance_of?(self.class) &&
-        other.name == name &&
-        other.table == table &&
-        other.sorted_constraints == sorted_constraints &&
-        other.sorted_partitioners == sorted_partitioners &&
-        other.sorted_models == sorted_models
+        other.name == name && other.table == table && children_are_equal(other)
     end
     alias eql? ==
 
@@ -75,17 +63,41 @@ module Dbee
       name <=> other.name
     end
 
+    def hash
+      [
+        name.hash,
+        table.hash,
+        relationships.hash,
+        sorted_constraints.hash,
+        sorted_partitioners.hash,
+        sorted_models.hash
+      ].hash
+    end
+
+    def to_s
+      name
+    end
+
     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
+
+    def children_are_equal(other)
+      other.relationships == relationships &&
+        other.sorted_constraints == sorted_constraints &&
+        other.sorted_partitioners == sorted_partitioners &&
+        other.sorted_models == sorted_models
+    end
+
+    def ensure_input_is_valid
+      raise ArgumentError, 'name is required' if name.to_s.empty?
+
+      constraints&.any? && relationships&.any? && \
+        raise(ArgumentError, 'constraints and relationships are mutually exclusive')
+    end
   end
 end

data/lib/dbee/query/field.rb

@@ -26,12 +26,7 @@ module Dbee
 
       attr_reader :aggregator, :display, :filters, :key_path
 
-      def initialize(
-        aggregator: nil,
-        display: nil,
-        filters: [],
-        key_path:
-      )
+      def initialize(key_path:, aggregator: nil, display: nil, filters: [])
         raise ArgumentError, 'key_path is required' if key_path.to_s.empty?
 
         @aggregator = aggregator ? Aggregator.const_get(aggregator.to_s.upcase.to_sym) : nil
@@ -71,6 +66,10 @@ module Dbee
       def <=>(other)
         "#{key_path}#{display}" <=> "#{other.key_path}#{other.display}"
       end
+
+      def key_paths
+        [key_path] + filters.map(&:key_path)
+      end
     end
   end
 end

data/lib/dbee/query.rb

@@ -21,35 +21,43 @@ module Dbee
     extend Forwardable
     acts_as_hashable
 
-    class NoFieldsError < StandardError; end
+    attr_reader :fields,
+                :filters,
+                :from,
+                :limit,
+                :offset,
+                :sorters
 
-    attr_reader :fields, :filters, :limit, :sorters
+    def_delegator :fields,   :sort, :sorted_fields
+    def_delegator :filters,  :sort, :sorted_filters
+    def_delegator :sorters,  :sort, :sorted_sorters
 
-    def_delegator :fields,  :sort, :sorted_fields
-    def_delegator :filters, :sort, :sorted_filters
-    def_delegator :sorters, :sort, :sorted_sorters
-
-    def initialize(fields:, filters: [], limit: nil, sorters: [])
-      @fields = Field.array(fields)
-
-      # If no fields were passed into a query then we will have no data to return.
-      # Let's raise a hard error here and let the consumer deal with it since this may
-      # have implications in downstream SQL generators.
-      raise NoFieldsError if @fields.empty?
-
-      @filters  = Filters.array(filters).uniq
-      @limit    = limit.to_s.empty? ? nil : limit.to_i
-      @sorters  = Sorters.array(sorters).uniq
+    def initialize(
+      fields: [],
+      from: nil,
+      filters: [],
+      limit: nil,
+      offset: nil,
+      sorters: []
+    )
+      @fields  = Field.array(fields)
+      @filters = Filters.array(filters).uniq
+      @from    = from.to_s
+      @limit   = limit.to_s.empty? ? nil : limit.to_i
+      @offset  = offset.to_s.empty? ? nil : offset.to_i
+      @sorters = Sorters.array(sorters).uniq
 
       freeze
     end
 
     def ==(other)
       other.instance_of?(self.class) &&
+        other.limit == limit &&
+        other.offset == offset &&
+        other.from == from &&
         other.sorted_fields == sorted_fields &&
         other.sorted_filters == sorted_filters &&
-        other.sorted_sorters == sorted_sorters &&
-        other.limit == limit
+        other.sorted_sorters == sorted_sorters
     end
     alias eql? ==
 
@@ -60,7 +68,11 @@ module Dbee
     private
 
     def key_paths
-      (fields.map(&:key_path) + filters.map(&:key_path) + sorters.map(&:key_path))
+      (
+        fields.flat_map(&:key_paths) +
+        filters.map(&:key_path) +
+        sorters.map(&:key_path)
+      )
     end
   end
 end

data/lib/dbee/schema.rb

@@ -0,0 +1,66 @@
+# 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
+  # A schema represents an entire graph of related models.
+  class Schema
+    attr_reader :models
+
+    extend Forwardable
+    def initialize(schema_config)
+      @models_by_name = Model.make_keyed_by(:name, schema_config)
+
+      freeze
+    end
+
+    # Given a Dbee::Model and Dbee::KeyPath, this returns a list of
+    # Dbee::Relationship and Dbee::Model tuples that lie on the key path.
+    # The returned list is a two dimensional array in
+    # the form of <tt>[[relationship, model], [relationship2, model2]]</tt>,
+    # etc. The relationships and models correspond to each ancestor part of the
+    # key path.
+    #
+    # The key_path argument can be either a Dbee::KeyPath or an array of
+    # string ancestor names.
+    #
+    # An exception is raised of the provided key_path contains relationship
+    # names that do not exist in this schema.
+    def expand_query_path(model, key_path, query_path = [])
+      ancestors = key_path.respond_to?(:ancestor_names) ? key_path.ancestor_names : key_path
+      relationship_name = ancestors.first
+      return query_path unless relationship_name
+
+      relationship = relationship_for_name!(model, relationship_name)
+      join_model = model_for_name!(relationship.model_name)
+      expand_query_path(
+        join_model,
+        ancestors.drop(1),
+        query_path + [[relationship_for_name!(model, relationship_name), join_model]]
+      )
+    end
+
+    def model_for_name!(model_name)
+      models_by_name[model_name.to_s] || raise(Model::ModelNotFoundError, model_name)
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && other.send(:models_by_name) == models_by_name
+    end
+    alias eql? ==
+
+    private
+
+    attr_reader :models_by_name
+
+    def relationship_for_name!(model, rel_name)
+      model.relationship_for_name(rel_name) ||
+        raise("model '#{model.name}' does not have a '#{rel_name}' relationship")
+    end
+  end
+end

data/lib/dbee/schema_creator.rb

@@ -0,0 +1,107 @@
+# 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
+  # This creates a Dbee::Schema from a variety of different inputs:
+  #
+  # 1. The hash representation of a schema.
+  # 2. A Dbee::Base subclass (code based models).
+  #
+  # For backward compatibility, tree based models are also supported in the
+  # following formats:
+  #
+  # 3. The hash representation of a tree based model.
+  # 4. Dbee::Model instances in tree based form (using the deprecated constraints and models
+  #    attributes).
+  class SchemaCreator # :nodoc:
+    attr_reader :schema
+
+    # An ArgumentError is raised if the query "from" attribute differs from the name of the root
+    # model of a tree based model or if the "from" attribute is blank.
+    def initialize(schema_or_model, query)
+      @orig_query = Query.make(query) || raise(ArgumentError, 'query is required')
+      raise ArgumentError, 'a schema or model is required' unless schema_or_model
+
+      @schema = make_schema(schema_or_model)
+
+      # Note that for backward compatibility reasons, this validation does not
+      # exist in the DBee::Query class. This allows continued support for
+      # old callers who depend on the "from" field being inferred from the root
+      # tree model name.
+      raise ArgumentError, 'query requires a from model name' if expected_from_model.empty?
+
+      validate_query_from_model!
+
+      freeze
+    end
+
+    # Returns a Dbee::Query instance with a "from" attribute which is
+    # sometimes derived for tree based models.
+    def query
+      return orig_query if expected_from_model == orig_query.from
+
+      Query.new(
+        from: expected_from_model,
+        fields: orig_query.fields,
+        filters: orig_query.filters,
+        sorters: orig_query.sorters,
+        limit: orig_query.limit
+      )
+    end
+
+    private
+
+    attr_reader :orig_query, :expected_from_model
+
+    def make_schema(input)
+      @expected_from_model = orig_query.from
+
+      return input if input.is_a?(Dbee::Schema)
+
+      if input.respond_to?(:to_schema)
+        @expected_from_model = input.inflected_class_name
+        return input.to_schema(orig_query.key_chain)
+      end
+
+      model_or_schema = to_object(input)
+      if model_or_schema.is_a?(Model)
+        @expected_from_model = model_or_schema.name.to_s
+        SchemaFromTreeBasedModel.convert(model_or_schema)
+      else
+        model_or_schema
+      end
+    end
+
+    def to_object(input)
+      return input unless input.is_a?(Hash)
+
+      if tree_based_hash?(input)
+        Model.make(input)
+      else
+        Schema.new(input)
+      end
+    end
+
+    def validate_query_from_model!
+      !orig_query.from.empty? && expected_from_model.to_s != orig_query.from.to_s && \
+        raise(
+          ArgumentError,
+          "expected from model to be '#{expected_from_model}' but got '#{orig_query.from}'"
+        )
+    end
+
+    def tree_based_hash?(hash)
+      name = hash[:name] || hash['name']
+
+      # In the unlikely event that schema based hash had a model called "name",
+      # its value would either be nil or a hash.
+      name.is_a?(String) || name.is_a?(Symbol)
+    end
+  end
+end

data/lib/dbee/schema_from_tree_based_model.rb

@@ -0,0 +1,47 @@
+# 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
+  # Converts a tree based model to a Schema. Note that this results in a
+  # different but compatible schema compared to the result of generating a
+  # Dbee::Schema by calling to_schema on a Dbee::Base class. This is
+  # because converting from a tree based model is a lossy.
+  class SchemaFromTreeBasedModel # :nodoc:
+    class << self
+      def convert(tree_model)
+        Schema.new(to_graph_based_models(tree_model))
+      end
+
+      private
+
+      def to_graph_based_models(tree_model, parent_model = nil, models_attrs_by_name = {})
+        models_attrs_by_name[tree_model.name] = {
+          name: tree_model.name,
+          table: tree_model.table,
+          partitioners: tree_model.partitioners,
+          relationships: {}
+        }
+
+        parent_model && add_relationship_to_parent_model(
+          tree_model, models_attrs_by_name[parent_model.name]
+        )
+
+        tree_model.models.each do |sub_model|
+          to_graph_based_models(sub_model, tree_model, models_attrs_by_name)
+        end
+
+        models_attrs_by_name
+      end
+
+      def add_relationship_to_parent_model(model, graph_model_attrs)
+        graph_model_attrs[:relationships][model.name] = { constraints: model.constraints }
+      end
+    end
+  end
+end

data/lib/dbee/util/make_keyed_by.rb

@@ -0,0 +1,50 @@
+# 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
+  module Util
+    # Provides a "make_keyed_by" method which extends the Hashable gem's
+    # concept of a "make" method.
+    module MakeKeyedBy # :nodoc:
+      # Given a hash of hashes or a hash of values of instances of this class,
+      # a hash is returned where all of the values are instances of this class
+      # and the keys are the string versions of the original hash.
+      #
+      # An ArgumentError is raised if the value's <tt>key_attrib</tt> is not
+      # equal to the top level hash key. This ensures that the
+      # <tt>key_attrib</tt> is the same in the incoming hash and the value.
+      #
+      # This is useful for cases where it makes sense in the configuration
+      # (YAML) specification to represent certain objects in a hash structure
+      # instead of a list.
+      def make_keyed_by(key_attrib, spec_hash)
+        # Once Ruby 2.5 support is dropped, this can just use the block form of
+        # #to_h.
+        spec_hash.map do |key, spec|
+          string_key = key.to_s
+          [string_key, make_value_checking_key_attib!(key_attrib, string_key, spec)]
+        end.to_h
+      end
+
+      private
+
+      def make_value_checking_key_attib!(key_attrib, key, spec)
+        if spec.is_a?(self)
+          if spec.send(key_attrib).to_s != key
+            err_msg = "expected a #{key_attrib} of '#{key}' but got '#{spec.send(key_attrib)}'"
+            raise ArgumentError, err_msg
+          end
+          spec
+        else
+          make((spec || {}).merge(key_attrib => key))
+        end
+      end
+    end
+  end
+end

data/lib/dbee/version.rb

@@ -8,5 +8,5 @@
 #
 
 module Dbee
-  VERSION = '2.1.0-alpha'
+  VERSION = '3.1.0'
 end