rom-repository 1.4.0 → 2.0.0.beta1

data/lib/rom/repository/relation_proxy.rb

@@ -1,337 +0,0 @@
-require 'dry/core/deprecations'
-
-require 'rom/initializer'
-require 'rom/relation/materializable'
-
-require 'rom/repository/relation_proxy/combine'
-require 'rom/repository/relation_proxy/wrap'
-
-module ROM
-  class Repository
-    # RelationProxy decorates a relation and automatically generates mappers that
-    # will map raw tuples into rom structs
-    #
-    # Relation proxies are being registered within repositories so typically there's
-    # no need to instantiate them manually.
-    #
-    # @api public
-    class RelationProxy
-      extend Initializer
-      extend Dry::Core::Deprecations[:rom]
-
-      include Relation::Materializable
-
-      (Kernel.private_instance_methods - %i(raise)).each(&method(:undef_method))
-
-      include RelationProxy::Combine
-      include RelationProxy::Wrap
-
-      deprecate :combine_parents
-      deprecate :combine_children
-      deprecate :wrap_parent
-
-      RelationRegistryType = Types.Definition(RelationRegistry).constrained(type: RelationRegistry)
-
-      # @!attribute [r] relation
-      #   @return [Relation, Relation::Composite, Relation::Graph, Relation::Curried] The decorated relation object
-      param :relation
-
-      option :name, type:  Types::Strict::Symbol
-      option :mappers, default: -> { MapperBuilder.new }
-      option :meta, default: -> { EMPTY_HASH }
-      option :registry, type: RelationRegistryType, default: -> { RelationRegistry.new }
-      option :auto_struct, default: -> { true }
-
-      # Relation name
-      #
-      # @return [ROM::Relation::Name]
-      #
-      # @api public
-      def name
-        @name ? relation.name.with(@name) : relation.name
-      end
-
-      # Materializes wrapped relation and sends it through a mapper
-      #
-      # For performance reasons a combined relation will skip mapping since
-      # we only care about extracting key values for combining
-      #
-      # @api public
-      def call(*args)
-        ((combine? || composite?) ? relation : (relation >> mapper)).call(*args)
-      end
-
-      # Maps the wrapped relation with other mappers available in the registry
-      #
-      # @overload map_with(model)
-      #   Map tuples to the provided custom model class
-      #
-      #   @example
-      #     users.as(MyUserModel)
-      #
-      #   @param [Class>] model Your custom model class
-      #
-      # @overload map_with(*mappers)
-      #   Map tuples using registered mappers
-      #
-      #   @example
-      #     users.map_with(:my_mapper, :my_other_mapper)
-      #
-      #   @param [Array<Symbol>] mappers A list of mapper identifiers
-      #
-      # @overload map_with(*mappers, auto_map: true)
-      #   Map tuples using auto-mapping and custom registered mappers
-      #
-      #   If `auto_map` is enabled, your mappers will be applied after performing
-      #   default auto-mapping. This means that you can compose complex relations
-      #   and have them auto-mapped, and use much simpler custom mappers to adjust
-      #   resulting data according to your requirements.
-      #
-      #   @example
-      #     users.map_with(:my_mapper, :my_other_mapper, auto_map: true)
-      #
-      #   @param [Array<Symbol>] mappers A list of mapper identifiers
-      #
-      # @return [RelationProxy] A new relation proxy with pipelined relation
-      #
-      # @api public
-      def map_with(*names, **opts)
-        if names.size == 1 && names[0].is_a?(Class)
-          map_to(names[0])
-        elsif names.size > 1 && names.any? { |name| name.is_a?(Class) }
-          raise ArgumentError, 'using custom mappers and a model is not supported'
-        else
-          if opts[:auto_map] && !meta[:combine_type]
-            mappers = [mapper, *names.map { |name| relation.mappers[name] }]
-            mappers.reduce(self) { |a, e| a >> e }
-          else
-            names.reduce(self) { |a, e| a >> relation.mappers[e] }
-          end
-        end
-      end
-
-      # @api public
-      def as(*names, **opts)
-        if names.size == 1 && names[0].is_a?(Class)
-          msg = <<-STR
-            Relation#as will change behavior in 4.0. Use `map_to` instead
-              => Called at:
-                #{Kernel.caller[0..5].join("\n")}
-            STR
-
-          Dry::Core::Deprecations.warn(msg)
-
-          map_to(names[0])
-        elsif names.size > 1 && names.any? { |name| name.is_a?(Class) }
-          raise ArgumentError, 'using custom mappers and a model is not supported'
-        else
-          if opts[:auto_map] && !meta[:combine_type]
-            mappers = [mapper, *names.map { |name| relation.mappers[name] }]
-            mappers.reduce(self) { |a, e| a >> e }
-          else
-            names.reduce(self) { |a, e| a >> relation.mappers[e] }
-          end
-        end
-      end
-
-      # @api public
-      def map_to(model)
-        with(meta: meta.merge(model: model))
-      end
-
-      # Return a new graph with adjusted node returned from a block
-      #
-      # @example with a node identifier
-      #   aggregate(:tasks).node(:tasks) { |tasks| tasks.prioritized }
-      #
-      # @example with a nested path
-      #   aggregate(tasks: :tags).node(tasks: :tags) { |tags| tags.where(name: 'red') }
-      #
-      # @param [Symbol] name The node relation name
-      #
-      # @yieldparam [RelationProxy] The relation node
-      # @yieldreturn [RelationProxy] The new relation node
-      #
-      # @return [RelationProxy]
-      #
-      # @api public
-      def node(name, &block)
-        if name.is_a?(Symbol) && !nodes.map { |n| n.name.relation }.include?(name)
-          raise ArgumentError, "#{name.inspect} is not a valid aggregate node name"
-        end
-
-        new_nodes = nodes.map { |node|
-          case name
-          when Symbol
-            name == node.name.relation ? yield(node) : node
-          when Hash
-            other, *rest = name.flatten(1)
-            if other == node.name.relation
-              nodes.detect { |n| n.name.relation == other }.node(*rest, &block)
-            else
-              node
-            end
-          else
-            node
-          end
-        }
-
-        with_nodes(new_nodes)
-      end
-
-      # Return a string representation of this relation proxy
-      #
-      # @return [String]
-      #
-      # @api public
-      def inspect
-        %(#<#{relation.class} name=#{name} dataset=#{dataset.inspect}>)
-      end
-
-      # Infers a mapper for the wrapped relation
-      #
-      # @return [ROM::Mapper]
-      #
-      # @api private
-      def mapper
-        mappers[to_ast]
-      end
-
-      # Returns a new instance with new options
-      #
-      # @param new_options [Hash]
-      #
-      # @return [RelationProxy]
-      #
-      # @api private
-      def with(new_options)
-        __new__(relation, options.merge(new_options))
-      end
-
-      # Returns if this relation is combined aka a relation graph
-      #
-      # @return [Boolean]
-      #
-      # @api private
-      def combine?
-        meta[:combine_type]
-      end
-
-      # Return if this relation is a composite
-      #
-      # @return [Boolean]
-      #
-      # @api private
-      def composite?
-        relation.is_a?(Relation::Composite)
-      end
-
-      # @return [Symbol] The wrapped relation's adapter identifier ie :sql or :http
-      #
-      # @api private
-      def adapter
-        relation.class.adapter
-      end
-
-      # Returns AST for the wrapped relation
-      #
-      # @return [Array]
-      #
-      # @api private
-      def to_ast
-        @to_ast ||=
-          begin
-            attr_ast = schema.map { |attr| [:attribute, attr] }
-
-            meta = self.meta.merge(dataset: base_name.dataset)
-            meta.update(model: false) unless meta[:model] || auto_struct
-            meta.delete(:wraps)
-
-            header = attr_ast + nodes_ast + wraps_ast
-
-            [:relation, [base_name.relation, meta, [:header, header]]]
-          end
-      end
-
-      # @api private
-      def respond_to_missing?(meth, _include_private = false)
-        relation.respond_to?(meth) || super
-      end
-
-      private
-
-      # @api private
-      def schema
-        if meta[:wrap]
-          relation.schema.wrap
-        else
-          relation.schema.reject(&:wrapped?)
-        end
-      end
-
-      # @api private
-      def base_name
-        relation.base_name
-      end
-
-      # @api private
-      def nodes_ast
-        @nodes_ast ||= nodes.map(&:to_ast)
-      end
-
-      # @api private
-      def wraps_ast
-        @wraps_ast ||= wraps.map(&:to_ast)
-      end
-
-      # Return a new instance with another relation and options
-      #
-      # @return [RelationProxy]
-      #
-      # @api private
-      def __new__(relation, new_options = EMPTY_HASH)
-        self.class.new(
-          relation, new_options.size > 0 ? options.merge(new_options) : options
-        )
-      end
-
-      # Return all nodes that this relation combines
-      #
-      # @return [Array<RelationProxy>]
-      #
-      # @api private
-      def nodes
-        relation.graph? ? relation.nodes : EMPTY_ARRAY
-      end
-
-      # Return all nodes that this relation wraps
-      #
-      # @return [Array<RelationProxy>]
-      #
-      # @api private
-      def wraps
-        meta.fetch(:wraps, EMPTY_ARRAY)
-      end
-
-      # Forward to relation and wrap it with proxy if response was a relation too
-      #
-      # TODO: this will be simplified once ROM::Relation has lazy-features built-in
-      #       and ROM::Lazy is gone
-      #
-      # @api private
-      def method_missing(meth, *args, &block)
-        if relation.respond_to?(meth)
-          result = relation.__send__(meth, *args, &block)
-
-          if result.kind_of?(Relation::Materializable) && !result.is_a?(Relation::Loaded)
-            __new__(result)
-          else
-            result
-          end
-        else
-          raise NoMethodError, "undefined method `#{meth}' for #{relation.class.name}"
-        end
-      end
-    end
-  end
-end

data/lib/rom/repository/relation_proxy/combine.rb

@@ -1,320 +0,0 @@
-require 'dry/core/inflector'
-
-module ROM
-  class Repository
-    class RelationProxy
-      # Provides convenient methods for composing relations
-      #
-      # @api public
-      module Combine
-        # Returns a combine representation of a loading-proxy relation
-        #
-        # This will carry meta info used to produce a correct AST from a relation
-        # so that correct mapper can be generated
-        #
-        # @return [RelationProxy]
-        #
-        # @api private
-        def combined(name, keys, type)
-          meta = { keys: keys, combine_type: type, combine_name: name }
-          with(name: name, meta: self.meta.merge(meta))
-        end
-
-        # Combine with other relations
-        #
-        # @overload combine(*associations)
-        #   Composes relations using configured associations
-        #   @example
-        #     users.combine(:tasks, :posts)
-        #   @param *associations [Array<Symbol>] A list of association names
-        #
-        # @overload combine(options)
-        #   Composes relations based on options
-        #
-        #   @example
-        #     # users have-many tasks (name and join-keys inferred, which needs associations in schema)
-        #     users.combine(many: tasks)
-        #
-        #     # users have-many tasks with custom name (join-keys inferred, which needs associations in schema)
-        #     users.combine(many: { priority_tasks: tasks.priority })
-        #
-        #     # users have-many tasks with custom view and join keys
-        #     users.combine(many: { tasks: [tasks.for_users, id: :task_id] })
-        #
-        #     # users has-one task
-        #     users.combine(one: { task: tasks })
-        #
-        #   @param options [Hash] Options for combine
-        #     @option :many [Hash] Sets options for "has-many" type of association
-        #     @option :one [Hash] Sets options for "has-one/belongs-to" type of association
-        #
-        # @return [RelationProxy]
-        #
-        # @api public
-        def combine(*args)
-          options = args[0].is_a?(Hash) ? args[0] : args
-
-          combine_opts = Hash.new { |h, k| h[k] = {} }
-
-          options.each do |key, value|
-            if key == :one || key == :many
-              if value.is_a?(Hash)
-                value.each do |name, spec|
-                  if spec.is_a?(Array)
-                    combine_opts[key][name] = spec
-                  else
-                    _, (curried, keys) = combine_opts_from_relations(spec).to_a[0]
-                    combine_opts[key][name] = [curried, keys]
-                  end
-                end
-              else
-                _, (curried, keys) = combine_opts_from_relations(value).to_a[0]
-                combine_opts[key][curried.combine_tuple_key(key)] = [curried, keys]
-              end
-            else
-              if value.is_a?(Array)
-                other =
-                  if registry.key?(key)
-                    registry[key]
-                  else
-                    registry[associations[key].target]
-                  end
-                curried = combine_from_assoc(key, other).combine(*value)
-                result, _, keys = combine_opts_for_assoc(key)
-                combine_opts[result][key] = [curried, keys]
-              else
-                result, curried, keys = combine_opts_for_assoc(key, value)
-                combine_opts[result][key] = [curried, keys]
-              end
-            end
-          end
-
-          nodes = combine_opts.flat_map do |type, relations|
-            relations.map { |name, (relation, keys)|
-              relation.combined(name, keys, type)
-            }
-          end
-
-          __new__(relation.graph(*nodes))
-        end
-
-        # Shortcut for combining with parents which infers the join keys
-        #
-        # @example
-        #   # tasks belong-to users
-        #   tasks.combine_parents(one: users)
-        #
-        #   # tasks belong-to users with custom user view
-        #   tasks.combine_parents(one: users.task_owners)
-        #
-        # @param options [Hash] Combine options hash
-        #
-        # @return [RelationProxy]
-        #
-        # @api public
-        def combine_parents(options)
-          combine_opts = {}
-
-          options.each do |type, parents|
-            combine_opts[type] =
-              case parents
-              when Hash
-                parents.each_with_object({}) { |(name, parent), r|
-                  keys = combine_keys(parent, relation, :parent)
-                  curried = combine_from_assoc_with_fallback(name, parent, keys)
-                  r[name] = [curried, keys]
-                }
-              when Array
-                parents.each_with_object({}) { |parent, r|
-                  keys = combine_keys(parent, relation, :parent)
-                  tuple_key = parent.combine_tuple_key(type)
-                  curried = combine_from_assoc_with_fallback(parent.name, parent, keys)
-                  r[tuple_key] = [curried, keys]
-                }
-              else
-                keys = combine_keys(parents, relation, :parent)
-                tuple_key = parents.combine_tuple_key(type)
-                curried = combine_from_assoc_with_fallback(parents.name, parents, keys)
-                { tuple_key => [curried, keys] }
-              end
-          end
-
-          combine(combine_opts)
-        end
-
-        # Shortcut for combining with children which infers the join keys
-        #
-        # @example
-        #   # users have-many tasks
-        #   users.combine_children(many: tasks)
-        #
-        #   # users have-many tasks with custom mapping (requires associations)
-        #   users.combine_children(many: { priority_tasks: tasks.priority })
-        #
-        # @param [Hash] options
-        #
-        # @return [RelationProxy]
-        #
-        # @api public
-        def combine_children(options)
-          combine_opts = {}
-
-          options.each do |type, children|
-            combine_opts[type] =
-              case children
-              when Hash
-                children.each_with_object({}) { |(name, child), r|
-                  keys = combine_keys(relation, child, :children)
-                  curried = combine_from_assoc_with_fallback(name, child, keys)
-                  r[name] = [curried, keys]
-                }
-              when Array
-                children.each_with_object({}) { |child, r|
-                  keys = combine_keys(relation, child, :children)
-                  tuple_key = child.combine_tuple_key(type)
-                  curried = combine_from_assoc_with_fallback(child.name, child, keys)
-                  r[tuple_key] = [curried, keys]
-                }
-              else
-                keys = combine_keys(relation, children, :children)
-                curried = combine_from_assoc_with_fallback(children.name, children, keys)
-                tuple_key = children.combine_tuple_key(type)
-                { tuple_key => [curried, keys] }
-              end
-          end
-
-          combine(combine_opts)
-        end
-
-        protected
-
-        # Infer join/combine keys for a given relation and association type
-        #
-        # When source has association corresponding to target's name, it'll be
-        # used to get the keys. Otherwise we fall back to using default keys based
-        # on naming conventions.
-        #
-        # @param [Relation::Name] source The source relation name
-        # @param [Relation::Name] target The target relation name
-        # @param [Symbol] type The association type, can be either :parent or :children
-        #
-        # @return [Hash<Symbol=>Symbol>]
-        #
-        # @api private
-        def combine_keys(source, target, type)
-          source.associations.try(target.name) { |assoc|
-            assoc.combine_keys(__registry__)
-          } or infer_combine_keys(source, target, type)
-        end
-
-        # Build combine options from a relation mapping hash passed to `combine`
-        #
-        # This method will infer combine keys either from defined associations
-        # or use the keys provided explicitly for ad-hoc combines
-        #
-        # It returns a mapping like `name => [preloadable_relation, combine_keys]`
-        # and this mapping is used by `combine` to build a full relation graph
-        #
-        # @api private
-        def combine_opts_from_relations(*relations)
-          relations.each_with_object({}) do |spec, h|
-            # We assume it's a child relation
-            keys = combine_keys(relation, spec, :children)
-            rel = combine_from_assoc_with_fallback(spec.name, spec, keys)
-            h[spec.name.relation] = [rel, keys]
-          end
-        end
-
-        # @api private
-        def combine_from_assoc_with_fallback(name, other, keys)
-          combine_from_assoc(name, other) do
-            other.combine_method(relation, keys)
-          end
-        end
-
-        # Try to get a preloadable relation from a defined association
-        #
-        # If association doesn't exist we call the fallback block
-        #
-        # @return [RelationProxy]
-        #
-        # @api private
-        def combine_from_assoc(name, other, &fallback)
-          return other if other.curried?
-          associations.try(name) { |assoc| other.for_combine(assoc) } or fallback.call
-        end
-
-        # Extract result (either :one or :many), preloadable relation and its keys
-        # by using given association name
-        #
-        # This is used when a flat list of association names was passed to `combine`
-        #
-        # @api private
-        def combine_opts_for_assoc(name, opts = nil)
-          assoc = relation.associations[name]
-          curried = registry[assoc.target.relation].for_combine(assoc)
-          curried = curried.combine(opts) unless opts.nil?
-          keys = assoc.combine_keys(__registry__)
-          [assoc.result, curried, keys]
-        end
-
-        # Build a preloadable relation for relation graph
-        #
-        # When a given relation defines `for_other_relation` then it will be used
-        # to preload `other_relation`. ie `users` relation defines `for_tasks`
-        # then when we preload tasks for users, this custom method will be used
-        #
-        # This *defaults* to the built-in `for_combine` with explicitly provided
-        # keys
-        #
-        # @return [RelationProxy]
-        #
-        # @api private
-        def combine_method(other, keys)
-          custom_name = :"for_#{other.name.dataset}"
-
-          if relation.respond_to?(custom_name)
-            __send__(custom_name)
-          else
-            for_combine(keys)
-          end
-        end
-
-        # Infer key under which a combine relation will be loaded
-        #
-        # This is used in cases like ad-hoc combines where relation was passed
-        # in without specifying the key explicitly, ie:
-        #
-        #    tasks.combine_parents(one: users)
-        #
-        #    # ^^^ this will be expanded under-the-hood to:
-        #    tasks.combine(one: { user: users })
-        #
-        # @return [Symbol]
-        #
-        # @api private
-        def combine_tuple_key(result)
-          if result == :one
-            Dry::Core::Inflector.singularize(base_name.relation).to_sym
-          else
-            base_name.relation
-          end
-        end
-
-        # Fallback mechanism for `combine_keys` when there's no association defined
-        #
-        # @api private
-        def infer_combine_keys(source, target, type)
-          primary_key = source.primary_key
-          foreign_key = target.foreign_key(source)
-
-          if type == :parent
-            { foreign_key => primary_key }
-          else
-            { primary_key => foreign_key }
-          end
-        end
-      end
-    end
-  end
-end