rom 0.5.0 → 0.6.0.beta1

data/lib/rom/relation.rb

@@ -1,50 +1,163 @@
+require 'set'
+require 'rom/relation/registry_reader'
+require 'rom/relation/lazy'
+require 'rom/relation/curried'
+
 module ROM
   # Base relation class
   #
-  # Relation is a proxy for the dataset object provided by the adapter, it
-  # forwards every method to the dataset that's why "native" interface of the
-  # underlying adapter is available in the relation. This interface, however, is
-  # considered private and should not be used outside of the relation instance.
+  # Relation is a proxy for the dataset object provided by the repository. It
+  # forwards every method to the dataset, which is why the "native" interface of
+  # the underlying repository is available in the relation. This interface,
+  # however, is considered private and should not be used outside of the
+  # relation instance.
   #
   # ROM builds sub-classes of this class for every relation defined in the env
-  # for easy inspection and extensibility - every adapter can provide extensions
+  # for easy inspection and extensibility - every repository can provide extensions
   # for those sub-classes but there is always a vanilla relation instance stored
   # in the schema registry.
   #
-  # Relation instances also have access to the experimental ROM::RA interface
-  # giving in-memory relational operations that are very handy, especially when
-  # dealing with joined relations or data coming from different sources.
-  #
   # @api public
   class Relation
-    include Charlatan.new(:dataset)
-    include Equalizer.new(:header, :dataset)
+    extend ClassMacros
+
+    include Options
+    include Equalizer.new(:dataset)
+
+    defines :repository, :dataset, :register_as, :exposed_relations
+
+    repository :default
+
+    attr_reader :name, :dataset, :exposed_relations
+
+    # Register adapter relation subclasses during setup phase
+    #
+    # In adition those subclasses are extended with an interface for accessing
+    # relation registry and to define `register_as` setting
+    #
+    # @api private
+    def self.inherited(klass)
+      super
+
+      return if self == ROM::Relation
+
+      klass.class_eval do
+        include ROM::Relation::RegistryReader
+
+        dataset(default_name)
+        exposed_relations Set.new
+
+        def self.register_as(value = Undefined)
+          if value == Undefined
+            @register_as || dataset
+          else
+            super
+          end
+        end
 
-    class << self
-      # Relation methods that were defined inside setup.relation DSL
-      #
-      # @return [Array<Symbol>]
-      #
-      # @api private
-      attr_accessor :relation_methods
+        def self.method_added(name)
+          super
+          exposed_relations << name if public_instance_methods.include?(name)
+        end
+      end
+
+      ROM.register_relation(klass)
+    end
+
+    # Return adapter-specific relation subclass
+    #
+    # @example
+    #   ROM::Relation[:memory]
+    #   # => ROM::Memory::Relation
+    #
+    # @return [Class]
+    #
+    # @api public
+    def self.[](type)
+      ROM.adapters.fetch(type).const_get(:Relation)
     end
 
-    # @return [Array] relation base header
+    # Dynamically define a method that will forward to the dataset and wrap
+    # response in the relation itself
+    #
+    # @example
+    #   class SomeAdapterRelation < ROM::Relation
+    #     forward :super_query
+    #   end
+    #
+    # @api public
+    def self.forward(*methods)
+      methods.each do |method|
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{method}(*args, &block)
+            __new__(dataset.__send__(:#{method}, *args, &block))
+          end
+        RUBY
+      end
+    end
+
+    # Return default relation name used for `register_as` setting
+    #
+    # @return [Symbol]
     #
     # @api private
-    attr_reader :header
+    def self.default_name
+      return unless name
+      Inflector.underscore(name).gsub('/', '_').to_sym
+    end
 
-    # Hook to finalize a relation after its instance was created
+    # Build relation registry of specified descendant classes
+    #
+    # This is used by the setup
+    #
+    # @param [Hash] repositories
+    # @param [Array] descendants a list of relation descendants
+    #
+    # @return [Hash]
     #
     # @api private
-    def self.finalize(_env, _relation)
-      # noop
+    def self.registry(repositories, descendants)
+      registry = {}
+
+      descendants.each do |klass|
+        # TODO: raise a meaningful error here and add spec covering the case
+        #       where klass' repository points to non-existant repo
+        repository = repositories.fetch(klass.repository)
+        dataset = repository.dataset(klass.dataset)
+
+        relation = klass.new(dataset, __registry__: registry)
+
+        name = klass.register_as
+
+        if registry.key?(name)
+          raise RelationAlreadyDefinedError,
+            "Relation with `register_as #{name.inspect}` registered more " \
+            "than once"
+        end
+
+        registry[name] = relation
+      end
+
+      registry.each_value do |relation|
+        relation.class.finalize(registry, relation)
+      end
+
+      registry
     end
 
     # @api private
-    def initialize(dataset, header = dataset.header)
+    def initialize(dataset, options = {})
+      @dataset = dataset
+      @name = self.class.dataset
+      @exposed_relations = self.class.exposed_relations
       super
-      @header = header.dup.freeze
+    end
+
+    # Hook to finalize a relation after its instance was created
+    #
+    # @api private
+    def self.finalize(_env, _relation)
+      # noop
     end
 
     # Yield dataset tuples
@@ -54,7 +167,33 @@ module ROM
     # @api private
     def each(&block)
       return to_enum unless block
-      dataset.each(&block)
+      dataset.each { |tuple| yield(tuple) }
+    end
+
+    # Materialize relation into an array
+    #
+    # @return [Array<Hash>]
+    #
+    # @api public
+    def to_a
+      to_enum.to_a
+    end
+
+    # @api private
+    def repository
+      self.class.repository
+    end
+
+    # @api public
+    def to_lazy(*args)
+      Lazy.new(self, *args)
+    end
+
+    private
+
+    # @api private
+    def __new__(dataset, new_opts = {})
+      self.class.new(dataset, options.merge(new_opts))
     end
   end
 end

data/lib/rom/relation/composite.rb

@@ -0,0 +1,132 @@
+require 'rom/relation/loaded'
+
+module ROM
+  class Relation
+    # Left-to-right relation composition used for data-pipelining
+    #
+    # @api public
+    class Composite
+      include Equalizer.new(:left, :right)
+
+      # @return [Lazy,Curried,Composite,#call]
+      #
+      # @api private
+      attr_reader :left
+
+      # @return [Lazy,Curried,Composite,#call]
+      #
+      # @api private
+      attr_reader :right
+
+      # @api private
+      def initialize(left, right)
+        @left = left
+        @right = right
+      end
+
+      # Compose with another callable object
+      #
+      # @param [#call]
+      #
+      # @return [Composite]
+      #
+      # @api public
+      def >>(other)
+        self.class.new(self, other)
+      end
+
+      # Call the pipeline by passing results from left to right
+      #
+      # Optional args are passed to the left object
+      #
+      # @return [Loaded]
+      #
+      # @api public
+      def call(*args)
+        relation = left.call(*args)
+        response = right.call(relation)
+
+        if relation.is_a?(Loaded)
+          relation.new(response)
+        else
+          Loaded.new(relation, response)
+        end
+      end
+      alias_method :[], :call
+
+      # Coerce composite relation to an array
+      #
+      # @return [Array]
+      #
+      # @api public
+      def to_a
+        call.to_a
+      end
+      alias_method :to_ary, :to_a
+
+      # 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
+
+      # Yield composite relation objects
+      #
+      # @yield [Object]
+      #
+      # @api public
+      def each(&block)
+        return to_enum unless block
+        call.each { |object| yield(object) }
+      end
+
+      # Return first object from the called relation
+      #
+      # @return [Object]
+      #
+      # @api public
+      def first
+        call.first
+      end
+
+      # @api private
+      def respond_to_missing?(name, include_private = false)
+        left.respond_to?(name) || super
+      end
+
+      private
+
+      # Allow calling methods on the left side object
+      #
+      # @api private
+      def method_missing(name, *args, &block)
+        if left.respond_to?(name)
+          response = left.__send__(name, *args, &block)
+          if response.is_a?(left.class)
+            self.class.new(response, right)
+          else
+            response
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rom/relation/curried.rb

@@ -0,0 +1,48 @@
+require 'rom/relation/lazy'
+
+module ROM
+  class Relation
+    class Curried < Lazy
+      option :name, type: Symbol, reader: true
+      option :arity, type: Integer, reader: true, default: -1
+      option :curry_args, type: Array, reader: true, default: EMPTY_ARRAY
+
+      # Load relation if args match the arity
+      #
+      # @return [Loaded,Lazy,Curried]
+      # @see Lazy#call
+      #
+      # @api public
+      def call(*args)
+        if arity != -1
+          all_args = curry_args + args
+
+          if arity == all_args.size
+            Loaded.new(relation.__send__(name, *all_args))
+          else
+            __new__(relation, curry_args: all_args)
+          end
+        else
+          super
+        end
+      end
+      alias_method :[], :call
+
+      # Return if this lazy relation is curried
+      #
+      # @return [true]
+      #
+      # @api private
+      def curried?
+        true
+      end
+
+      private
+
+      # @api private
+      def __new__(relation, new_opts = {})
+        Curried.new(relation, options.merge(new_opts))
+      end
+    end
+  end
+end

data/lib/rom/relation/lazy.rb

@@ -0,0 +1,173 @@
+require 'rom/relation/loaded'
+require 'rom/relation/composite'
+
+module ROM
+  class Relation
+    # Lazy relation wraps canonical relation for data-pipelining
+    #
+    # @example
+    #   ROM.setup(:memory)
+    #
+    #   class Users < ROM::Relation[:memory]
+    #     def by_name(name)
+    #       restrict(name: name)
+    #     end
+    #   end
+    #
+    #   rom = ROM.finalize.env
+    #
+    #   rom.relations.users << { name: 'Jane' }
+    #   rom.relations.users << { name: 'Joe' }
+    #
+    #   mapper = proc { |users| users.map { |user| user[:name] } }
+    #   users = rom.relation(:users)
+    #
+    #   (users.by_name >> mapper)['Jane'].inspect # => ["Jane"]
+    #
+    # @api public
+    class Lazy
+      include Equalizer.new(:relation, :options)
+      include Options
+
+      option :mappers, reader: true, default: EMPTY_HASH
+
+      # @return [Relation]
+      #
+      # @api private
+      attr_reader :relation
+
+      # Map of exposed relation methods
+      #
+      # @return [Hash<Symbol=>TrueClass>]
+      #
+      # @api private
+      attr_reader :methods
+
+      # @api private
+      def initialize(relation, options = {})
+        super
+        @relation = relation
+        @methods = @relation.exposed_relations
+      end
+
+      # Compose two relation with a left-to-right composition
+      #
+      # @example
+      #   users.by_name('Jane') >> tasks.for_users
+      #
+      # @param [Relation] other The right relation
+      #
+      # @return [Relation::Composite]
+      #
+      # @api public
+      def >>(other)
+        Composite.new(self, other)
+      end
+
+      # Build a relation pipeline using registered mappers
+      #
+      # @example
+      #   rom.relation(:users).map_with(:json_serializer)
+      #
+      # @return [Relation::Composite]
+      #
+      # @api public
+      def map_with(*names)
+        [self, *names.map { |name| mappers[name] }]
+          .reduce { |a, e| Composite.new(a, e) }
+      end
+      alias_method :as, :map_with
+
+      # Coerce lazy relation to an array
+      #
+      # @return [Array]
+      #
+      # @api public
+      def to_a
+        call.to_a
+      end
+      alias_method :to_ary, :to_a
+
+      # Load relation
+      #
+      # @return [Relation::Loaded]
+      #
+      # @api public
+      def call
+        Loaded.new(relation)
+      end
+      alias_method :[], :call
+
+      # 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
+
+      # @api private
+      def respond_to_missing?(name, include_private = false)
+        methods.include?(name) || super
+      end
+
+      # Return if this lazy relation is curried
+      #
+      # @return [false]
+      #
+      # @api private
+      def curried?
+        false
+      end
+
+      private
+
+      # Forward methods to the underlaying relation
+      #
+      # Auto-curry relations when args size doesn't match arity
+      #
+      # @return [Lazy,Curried]
+      #
+      # @api private
+      def method_missing(meth, *args, &block)
+        if !methods.include?(meth) || (curried? && name != meth)
+          super
+        else
+          arity = relation.method(meth).arity
+
+          if arity == -1 || arity == args.size
+            response = relation.__send__(meth, *args, &block)
+            if response.is_a?(Relation)
+              __new__(response)
+            else
+              response
+            end
+          else
+            Curried.new(relation, name: meth, curry_args: args, arity: arity)
+          end
+        end
+      end
+
+      # Return new lazy relation with updated options
+      #
+      # @api private
+      def __new__(relation, new_opts = {})
+        Lazy.new(relation, options.merge(new_opts))
+      end
+    end
+  end
+end