rom 5.4.1 → 6.0.0.alpha1

data/lib/rom/relation/curried.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+
+require "rom/types"
+require "rom/initializer"
+require "rom/pipeline"
+require "rom/relation/name"
+require "rom/relation/materializable"
+
+module ROM
+  class Relation
+    # Curried relation is a special relation proxy used by auto-curry mechanism.
+    #
+    # When a relation view method is called without all arguments, a curried proxy
+    # is returned that can be fully applied later on.
+    #
+    # Curried relations are typically used for relation composition
+    #
+    # @api public
+    class Curried
+      extend Initializer
+
+      include Dry::Equalizer(:relation, :options)
+      include Materializable
+      include Pipeline
+
+      undef :map_with
+
+      # @!attribute [r] relation
+      #   @return [Relation] The source relation that is curried
+      param :relation
+
+      # @!attribute [r] view
+      #   @return [Symbol] The name of relation's view method
+      option :view, type: Types::Strict::Symbol
+
+      # @!attribute [r] arity
+      #   @return [Integer] View's arity
+      option :arity, type: Types::Strict::Integer
+
+      # @!attribute [r] curry_args
+      #   @return [Array] Arguments that will be passed to curried view
+      option :curry_args, default: -> { EMPTY_ARRAY }
+
+      # Load relation if args match the arity
+      #
+      # @return [Loaded,Curried]
+      #
+      # @api public
+      def call(*args)
+        all_args = curry_args + args
+
+        if all_args.empty?
+          raise ArgumentError,
+                "curried #{relation.class}##{view} relation was called without any arguments"
+        end
+
+        if args.empty?
+          self
+        elsif arity == all_args.size
+          Loaded.new(relation.__send__(view, *all_args))
+        else
+          __new__(relation, curry_args: all_args)
+        end
+      end
+      alias_method :[], :call
+
+      # Relations are coercible to an array but a curried relation cannot be coerced
+      # When something tries to do this, an exception will be raised
+      #
+      # @raise ArgumentError
+      #
+      # @api public
+      def to_a
+        raise(
+          ArgumentError,
+          "#{relation.class}##{view} arity is #{arity} " \
+          "(#{curry_args.size} args given)"
+        )
+      end
+      alias_method :to_ary, :to_a
+
+      # Return if this lazy relation is curried
+      #
+      # @return [true]
+      #
+      # @api private
+      def curried?
+        true
+      end
+
+      # @api private
+      def respond_to_missing?(name, include_private = false)
+        super || relation.respond_to?(name, include_private)
+      end
+
+      private
+
+      # @api private
+      def __new__(relation, **new_opts)
+        self.class.new(relation, **options, **new_opts)
+      end
+
+      # @api private
+      def composite_class
+        Relation::Composite
+      end
+
+      # @api private
+      def method_missing(meth, *args, &block)
+        if relation.respond_to?(meth)
+          response = relation.__send__(meth, *args, &block)
+
+          super if response.is_a?(self.class)
+
+          if response.is_a?(Relation) || response.is_a?(Graph) || response.is_a?(Wrap) || response.is_a?(Composite)
+            __new__(response)
+          else
+            response
+          end
+        else
+          super
+        end
+      end
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+    end
+  end
+end

data/lib/rom/relation/graph.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+
+require "rom/initializer"
+
+require "rom/relation/loaded"
+require "rom/relation/composite"
+require "rom/relation/materializable"
+require "rom/pipeline"
+require "rom/support/memoizable"
+
+module ROM
+  class Relation
+    # Abstract relation graph class
+    #
+    # @api public
+    class Graph
+      extend Initializer
+
+      include Memoizable
+
+      # @!attribute [r] root
+      #   @return [Relation] The root relation
+      param :root
+
+      # @!attribute [r] nodes
+      #   @return [Array<Relation>] An array with relation nodes
+      param :nodes
+
+      include Dry::Equalizer(:root, :nodes)
+      include Materializable
+      include Pipeline
+      include Pipeline::Proxy
+
+      # for compatibility with the pipeline
+      alias_method :left, :root
+      alias_method :right, :nodes
+
+      # Rebuild a graph with new nodes
+      #
+      # @param [Array<Relation>] nodes
+      #
+      # @return [Graph]
+      #
+      # @api public
+      def with_nodes(nodes)
+        self.class.new(root, nodes)
+      end
+
+      # Return if this is a graph relation
+      #
+      # @return [true]
+      #
+      # @api private
+      def graph?
+        true
+      end
+
+      # Map graph tuples via custom mappers
+      #
+      # @see Relation#map_with
+      #
+      # @return [Relation::Composite]
+      #
+      # @api public
+      def map_with(*names, **opts)
+        names.reduce(self.class.new(root.with(opts), nodes)) { |a, e| a >> mappers[e] }
+      end
+
+      # Map graph tuples to custom objects
+      #
+      # @see Relation#map_to
+      #
+      # @return [Graph]
+      #
+      # @api public
+      def map_to(klass)
+        self.class.new(root.map_to(klass), nodes)
+      end
+
+      # @see Relation#mapper
+      #
+      # @api private
+      def mapper
+        mappers[to_ast]
+      end
+
+      # @api private
+      memoize def to_ast
+        [:relation, [name.relation, attr_ast + nodes.map(&:to_ast), meta_ast]]
+      end
+
+      private
+
+      # @api private
+      def decorate?(other)
+        super || other.is_a?(Composite) || other.is_a?(Curried)
+      end
+
+      # @api private
+      def composite_class
+        Relation::Composite
+      end
+    end
+  end
+end

data/lib/rom/relation/loaded.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+
+module ROM
+  class Relation
+    # Materializes a relation and exposes interface to access the data.
+    #
+    # This relation type is returned when a lazy relation is called
+    #
+    # @api public
+    class Loaded
+      include Enumerable
+      include Dry::Equalizer(:source, :collection)
+
+      # Coerce loaded relation to an array
+      #
+      # @return [Array]
+      #
+      # @api public
+      alias_method :to_ary, :to_a
+
+      # Source relation
+      #
+      # @return [Relation]
+      #
+      # @api private
+      attr_reader :source
+
+      # Materialized relation
+      #
+      # @return [Object]
+      #
+      # @api private
+      attr_reader :collection
+
+      # @api private
+      def initialize(source, collection = source.to_a)
+        @source = source
+        @collection = collection
+      end
+
+      # Yield relation tuples
+      #
+      # @yield [Hash]
+      #
+      # @api public
+      def each(&block)
+        return to_enum unless block_given?
+
+        collection.each(&block)
+      end
+
+      # Returns a single tuple from the relation if there is one.
+      #
+      # @raise [ROM::TupleCountMismatchError] if the relation contains more than
+      #   one tuple
+      #
+      # @api public
+      def one
+        if collection.count > 1
+          raise(
+            TupleCountMismatchError,
+            "The relation consists of more than one tuple"
+          )
+        else
+          collection.first
+        end
+      end
+
+      # Like [one], but additionally raises an error if the relation is empty.
+      #
+      # @raise [ROM::TupleCountMismatchError] if the relation does not contain
+      #   exactly one tuple
+      #
+      # @api public
+      def one!
+        one || raise(
+          TupleCountMismatchError,
+          "The relation does not contain any tuples"
+        )
+      end
+
+      # Return a list of values under provided key
+      #
+      # @example
+      #   all_users = rom.relations[:users].call
+      #   all_users.pluck(:name)
+      #   # ["Jane", "Joe"]
+      #
+      # @param [Symbol] key The key name
+      #
+      # @return [Array]
+      #
+      # @raise KeyError when provided key doesn't exist in any of the tuples
+      #
+      # @api public
+      def pluck(key)
+        map { |tuple| tuple.fetch(key) }
+      end
+
+      # Pluck primary key values
+      #
+      # This method *may not work* with adapters that don't provide relations
+      # that have primary key configured
+      #
+      # @example
+      #   users = rom.relations[:users].call
+      #   users.primary_keys
+      #   # [1, 2, 3]
+      #
+      # @return [Array]
+      #
+      # @api public
+      def primary_keys
+        pluck(source.primary_key)
+      end
+
+      # Return if loaded relation is empty
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api public
+      def empty?
+        collection.empty?
+      end
+
+      # Return a loaded relation with a new collection
+      #
+      # @api public
+      def new(collection)
+        self.class.new(source, collection)
+      end
+    end
+  end
+end

data/lib/rom/relation/materializable.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ROM
+  class Relation
+    # Interface for objects that can be materialized into a loaded relation
+    #
+    # @api public
+    module Materializable
+      # Coerce the relation to an array
+      #
+      # @return [Array]
+      #
+      # @api public
+      def to_a
+        call.to_a
+      end
+      alias_method :to_ary, :to_a
+
+      # Yield relation tuples
+      #
+      # @yield [Hash,Object]
+      #
+      # @api public
+      def each(&block)
+        return to_enum unless block_given?
+
+        to_a.each(&block)
+      end
+
+      # Delegate to loaded relation and return one object
+      #
+      # @return [Object]
+      #
+      # @see Loaded#one
+      #
+      # @api public
+      def one
+        call.one
+      end
+
+      # Delegate to loaded relation and return one object
+      #
+      # @return [Object]
+      #
+      # @see Loaded#one
+      #
+      # @api public
+      def one!
+        call.one!
+      end
+
+      # Return first tuple from a relation coerced to an array
+      #
+      # @return [Object]
+      #
+      # @api public
+      def first
+        to_a.first
+      end
+    end
+  end
+end

data/lib/rom/relation/name.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+require "dry/core/equalizer"
+require "rom/support/inflector"
+
+module ROM
+  class Relation
+    # Relation name container
+    #
+    # This is a simple struct with two fields.
+    # It handles both relation registration name (i.e. Symbol) and dataset name.
+    # The reason we need it is a simplification of passing around these two objects.
+    # It is quite common to have a dataset named differently from a relation
+    # built on top if you are dealing with a legacy DB and often you need both
+    # to support things such as associations (rom-sql as an example).
+    #
+    # @api private
+    class Name
+      include Dry::Equalizer(:relation, :dataset, :key)
+
+      # Coerce an object to a Name instance
+      #
+      # @return [ROM::Relation::Name]
+      #
+      # @api private
+      def self.call(*args)
+        cache.fetch_or_store(args.hash) do
+          relation, dataset, aliaz = args
+
+          case relation
+          when self then relation
+          when Symbol then new(relation, dataset, aliaz)
+          when Class, String then new(Inflector.component_id(relation).to_sym)
+          else
+            raise ArgumentError, "+#{relation}+ is not supported"
+          end
+        end
+      end
+
+      class << self
+        # @api private
+        alias_method :[], :call
+      end
+
+      # @api private
+      def self.cache
+        @cache ||= Concurrent::Map.new
+      end
+
+      # Relation registration name
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      attr_reader :relation
+
+      # Underlying dataset name
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      attr_reader :dataset
+
+      attr_reader :aliaz
+
+      attr_reader :key
+
+      # @api private
+      def initialize(relation, dataset = relation, aliaz = nil)
+        @relation = relation
+        @dataset = dataset || relation
+        @key = aliaz || relation
+        @aliaz = aliaz
+        freeze
+      end
+
+      # @api private
+      def as(aliaz)
+        self.class[relation, dataset, aliaz]
+      end
+
+      # @api private
+      def aliased?
+        aliaz && aliaz != relation
+      end
+
+      # Return relation name
+      #
+      # @return [String]
+      #
+      # @api private
+      def to_s
+        if aliased?
+          "#{relation} on #{dataset} as #{aliaz}"
+        elsif relation == dataset
+          relation.to_s
+        else
+          "#{relation} on #{dataset}"
+        end
+      end
+
+      # Alias for registration key implicitly called by ROM::Registry
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def to_sym
+        relation
+      end
+
+      # Return inspected relation
+      #
+      # @return [String]
+      #
+      # @api private
+      def inspect
+        "#{self.class.name}(#{self})"
+      end
+    end
+  end
+end

data/lib/rom/relation/wrap.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rom/relation/graph"
+require "rom/relation/combined"
+
+module ROM
+  class Relation
+    # Relation wrapping other relations
+    #
+    # @api public
+    class Wrap < Graph
+      # Wrap more relations
+      #
+      # @see Relation#wrap
+      #
+      # @return [Wrap]
+      #
+      # @api public
+      def wrap(*args)
+        self.class.new(root, nodes + root.wrap(*args).nodes)
+      end
+
+      # Materialize a wrap
+      #
+      # @see Relation#call
+      #
+      # @return [Loaded]
+      #
+      # @api public
+      def call(*args)
+        if auto_map?
+          Loaded.new(self, mapper.(relation.with(auto_map: false, auto_struct: false)))
+        else
+          Loaded.new(self, relation.(*args))
+        end
+      end
+
+      # Return an adapter-specific relation representing a wrap
+      #
+      # @abstract
+      #
+      # @api private
+      def relation
+        raise NotImplementedError
+      end
+
+      # Return if this is a wrap relation
+      #
+      # @return [true]
+      #
+      # @api private
+      def wrap?
+        true
+      end
+
+      private
+
+      # @api private
+      def decorate?(other)
+        super || other.is_a?(Combined)
+      end
+    end
+  end
+end