rom-core 4.0.0.beta1

data/lib/rom/relation/graph.rb

@@ -0,0 +1,197 @@
+require 'rom/relation/loaded'
+require 'rom/relation/composite'
+require 'rom/relation/materializable'
+require 'rom/relation/commands'
+require 'rom/pipeline'
+
+module ROM
+  class Relation
+    # Compose relations using join-keys
+    #
+    # @example
+    #   class Users < ROM::Relation[:memory]
+    #   end
+    #
+    #   class Tasks < ROM::Relation[:memory]
+    #     def for_users(users)
+    #       restrict(user: users.map { |user| user[:name] })
+    #     end
+    #   end
+    #
+    #   rom.relations[:users] << { name: 'Jane' }
+    #   rom.relations[:tasks] << { user: 'Jane', title: 'Do something' }
+    #
+    #   rom.relations[:users].combine(rom.relations[:tasks].for_users)
+    #
+    # @api public
+    class Graph
+      include Materializable
+      include Commands
+      include Pipeline
+      include Pipeline::Proxy
+
+      # Root aka parent relation
+      #
+      # @return [Relation::Lazy]
+      #
+      # @api private
+      attr_reader :root
+
+      # Child relation nodes
+      #
+      # @return [Array<Relation::Lazy>]
+      #
+      # @api private
+      attr_reader :nodes
+
+      alias_method :left, :root
+      alias_method :right, :nodes
+
+      # @api private
+      def self.build(root, nodes)
+        if nodes.any? { |node| node.instance_of?(Composite) }
+          raise UnsupportedRelationError,
+            "Combining with composite relations is not supported"
+        else
+          new(root, nodes)
+        end
+      end
+
+      # @api private
+      def initialize(root, nodes)
+        root_ns = root.options[:struct_namespace]
+        @root = root
+        @nodes = nodes.map { |node| node.struct_namespace(root_ns) }
+      end
+
+      # @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
+
+      # Combine this graph with more nodes
+      #
+      # @param [Array<Relation::Lazy>]
+      #
+      # @return [Graph]
+      #
+      # @api public
+      def graph(*others)
+        self.class.new(root, nodes + others)
+      end
+
+      # @api public
+      def combine(*args)
+        self.class.new(root, nodes + root.combine(*args).nodes)
+      end
+
+      # Materialize this relation graph
+      #
+      # @return [Loaded]
+      #
+      # @api public
+      def call(*args)
+        left = root.with(auto_struct: false).call(*args)
+
+        right =
+          if left.empty?
+            nodes.map { |node| Loaded.new(node, EMPTY_ARRAY) }
+          else
+            nodes.map { |node| node.call(left) }
+          end
+
+        if auto_map?
+          Loaded.new(self, mapper.([left, right]))
+        else
+          Loaded.new(self, [left, right])
+        end
+      end
+
+      # @api public
+      def map_with(*args)
+        self.class.new(root.map_with(*args), nodes)
+      end
+
+      # @api public
+      def map_to(klass)
+        self.class.new(root.map_to(klass), nodes)
+      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.key }.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.key ? yield(node) : node
+          when Hash
+            other, *rest = name.flatten(1)
+            if other == node.name.key
+              nodes.detect { |n| n.name.key == other }.node(*rest, &block)
+            else
+              node
+            end
+          else
+            node
+          end
+        }
+
+        with_nodes(new_nodes)
+      end
+
+      # @api public
+      def to_ast
+        [:relation, [name.to_sym, attr_ast + node_ast, meta_ast]]
+      end
+
+      # @api private
+      def node_ast
+        nodes.map(&:to_ast)
+      end
+
+      # @api private
+      def mapper
+        mappers[to_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,127 @@
+module ROM
+  class Relation
+    # Materializes a relation and exposes interface to access the data
+    #
+    # @api public
+    class Loaded
+      include Enumerable
+
+      # 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
+        collection.each { |tuple| yield(tuple) }
+      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]
+      # @raises 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,66 @@
+module ROM
+  class Relation
+    # Interface for objects that can be materialized into a loaded relation
+    #
+    # @api public
+    module Materializable
+      # @abstract
+      #
+      # @api public
+      def call(*)
+        raise NotImplementedError, "#{self.class}#call must be implemented"
+      end
+
+      # 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
+        to_a.each { |tuple| yield(tuple) }
+      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,111 @@
+require 'dry/equalizer'
+require 'concurrent/map'
+
+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)
+
+      # Coerce an object to a Name instance
+      #
+      # @return [ROM::Relation::Name]
+      #
+      # @api private
+      def self.[](*args)
+        cache.fetch_or_store(args.hash) do
+          relation, dataset, aliaz = args
+
+          if relation.is_a?(Name)
+            relation
+          else
+            new(relation, dataset, aliaz)
+          end
+        end
+      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
+      end
+
+      # @api private
+      def as(aliaz)
+        self.class[relation, dataset, aliaz]
+      end
+
+      # @api private
+      def aliased?
+        !aliaz.nil?
+      end
+
+      # Return relation name
+      #
+      # @return [String]
+      #
+      # @api private
+      def to_s
+        if aliaz
+          "#{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}(#{to_s})"
+      end
+    end
+  end
+end