rom 0.7.1 → 0.8.0

data/lib/rom/commands/graph/class_interface.rb

@@ -0,0 +1,69 @@
+module ROM
+  module Commands
+    class Graph
+      # Class methods for command Graph
+      #
+      # @api private
+      module ClassInterface
+        # Build a command graph recursively
+        #
+        # This is used by `Env#command` when array with options is passed in
+        #
+        # @param [Registry] registry The command registry from env
+        # @param [Array] options The options array
+        # @param [Array] path The path for input evaluator proc
+        #
+        # @return [Graph]
+        #
+        # @api private
+        def build(registry, options, path = EMPTY_ARRAY)
+          options.reduce { |spec, other| build_command(registry, spec, other, path) }
+        end
+
+        # @api private
+        def build_command(registry, spec, other, path)
+          name, nodes = other
+
+          key, relation =
+            if spec.is_a?(Hash)
+              spec.to_a.first
+            else
+              [spec, spec]
+            end
+
+          command = registry[relation][name]
+
+          tuple_path = Array[*path] << key
+
+          input_proc = -> *args do
+            input, index = args
+
+            begin
+              if index
+                tuple_path[0..tuple_path.size-2]
+                  .reduce(input) { |a,e| a.fetch(e) }
+                  .at(index)[tuple_path.last]
+              else
+                tuple_path.reduce(input) { |a,e| a.fetch(e) }
+              end
+            rescue KeyError => err
+              raise CommandFailure.new(command, err)
+            end
+          end
+
+          command = command.with(input_proc)
+
+          if nodes
+            if nodes.all? { |node| node.is_a?(Array) }
+              command.combine(*nodes.map { |node| build(registry, node, tuple_path) })
+            else
+              command.combine(build(registry, nodes, tuple_path))
+            end
+          else
+            command
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/commands/lazy.rb

@@ -0,0 +1,87 @@
+require 'rom/commands/composite'
+require 'rom/commands/graph'
+
+module ROM
+  module Commands
+    # Lazy command wraps another command and evaluates its input when called
+    #
+    # @api private
+    class Lazy
+      # @attr_reader [Command] command The wrapped command
+      attr_reader :command
+
+      # @attr_reader [Proc] evaluator The proc that will evaluate the input
+      attr_reader :evaluator
+
+      # @api private
+      def initialize(command, evaluator)
+        @command = command
+        @evaluator = evaluator
+      end
+
+      # Evaluate command's input using the input proc and pass to command
+      #
+      # @return [Array,Hash]
+      #
+      # @api public
+      def call(*args)
+        first = args.first
+        last = args.last
+        size = args.size
+
+        if size > 1 && last.is_a?(Array)
+          last.map.with_index do |item, index|
+            command.call(evaluator[first, index], item)
+          end.reduce(:concat)
+        else
+          command.call(evaluator[first], *args[1..size-1])
+        end
+      end
+
+      # Compose a lazy command with another one
+      #
+      # @see Commands::Abstract#>>
+      #
+      # @return [Composite]
+      #
+      # @api public
+      def >>(other)
+        Composite.new(self, other)
+      end
+
+      # @see Abstract#combine
+      #
+      # @api public
+      def combine(*others)
+        Graph.new(self, others)
+      end
+
+      # @api private
+      def lazy?
+        true
+      end
+
+      # @api private
+      def respond_to_missing?(name, include_private = false)
+        super || command.respond_to?(name)
+      end
+
+      private
+
+      # @api private
+      def method_missing(name, *args, &block)
+        if command.respond_to?(name)
+          response = command.public_send(name, *args, &block)
+
+          if response.instance_of?(command.class)
+            self.class.new(response, evaluator)
+          else
+            response
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rom/constants.rb

@@ -4,17 +4,39 @@ module ROM
 
   AdapterLoadError = Class.new(StandardError)
 
+  class AdapterNotPresentError < StandardError
+    def initialize(adapter, component)
+      super(
+        "Failed to find #{component} class for #{adapter} adapter. " \
+        "Make sure ROM setup was started and the adapter identifier is correct."
+      )
+    end
+  end
+
   EnvAlreadyFinalizedError = Class.new(StandardError)
   RelationAlreadyDefinedError = Class.new(StandardError)
   NoRelationError = Class.new(StandardError)
   CommandError = Class.new(StandardError)
   TupleCountMismatchError = Class.new(CommandError)
   MapperMissingError = Class.new(StandardError)
+  MapperMisconfiguredError = Class.new(StandardError)
   UnknownPluginError = Class.new(StandardError)
+  UnsupportedRelationError = Class.new(StandardError)
 
   InvalidOptionValueError = Class.new(StandardError)
   InvalidOptionKeyError = Class.new(StandardError)
 
+  class CommandFailure < StandardError
+    attr_reader :command
+    attr_reader :original_error
+
+    def initialize(command, err)
+      super("command: #{command.inspect}; original message: #{err.message}")
+      @command = command
+      @original_error = original_error
+    end
+  end
+
   EMPTY_ARRAY = [].freeze
   EMPTY_HASH = {}.freeze
 end

data/lib/rom/env.rb

@@ -1,27 +1,30 @@
 require 'rom/relation/loaded'
+require 'rom/commands/graph'
 require 'rom/support/deprecations'
 
 module ROM
-  # Exposes defined repositories, relations and mappers
+  # Exposes defined gateways, relations and mappers
   #
   # @api public
   class Env
     extend Deprecations
-    include Equalizer.new(:repositories, :relations, :mappers, :commands)
+    include Equalizer.new(:gateways, :relations, :mappers, :commands)
 
-    # @return [Hash] configured repositories
+    # @return [Hash] configured gateways
     #
     # @api public
-    attr_reader :repositories
+    attr_reader :gateways
+
+    deprecate :repositories, :gateways
 
     # @return [RelationRegistry] relation registry
     #
-    # @api public
+    # @api private
     attr_reader :relations
 
     # @return [Registry] command registry
     #
-    # @api public
+    # @api private
     attr_reader :commands
 
     # @return [Registry] mapper registry
@@ -30,31 +33,34 @@ module ROM
     attr_reader :mappers
 
     # @api private
-    def initialize(repositories, relations, mappers, commands)
-      @repositories = repositories
+    def initialize(gateways, relations, mappers, commands)
+      @gateways = gateways
       @relations = relations
       @mappers = mappers
       @commands = commands
       freeze
     end
 
-    # Load relation by name
+    # Get lazy relation identified by its name
     #
     # @example
-    #
     #   rom.relation(:users)
-    #   rom.relation(:users) { |r| r.by_name('Jane') }
+    #   rom.relation(:users).by_name('Jane')
+    #
+    #   # block syntax allows accessing lower-level query DSLs (usage is discouraged though)
+    #   rom.relation { |r| r.restrict(name: 'Jane') }
     #
     #   # with mapping
     #   rom.relation(:users).map_with(:presenter)
     #
-    #   rom.relation(:users) { |r| r.page(1) }.map_with(:presenter, :json_serializer)
+    #   # using multiple mappers
+    #   rom.relation(:users).page(1).map_with(:presenter, :json_serializer)
     #
     # @param [Symbol] name of the relation to load
     #
     # @yield [Relation]
     #
-    # @return [Relation::Loaded]
+    # @return [Relation::Lazy]
     #
     # @api public
     def relation(name, &block)
@@ -80,15 +86,39 @@ module ROM
     #   # plain command returning tuples
     #   rom.command(:users).create
     #
-    #   # allow auto-mapping using registered mappers
+    #   # allows auto-mapping using registered mappers
     #   rom.command(:users).as(:entity)
     #
+    #   # allows building up a command graph for nested input
+    #   command = rom.command([:users, [:create, [:tasks, [:create]]]])
+    #
+    #   command.call(users: [{ name: 'Jane', tasks: [{ title: 'One' }] }])
+    #
+    # @param [Array,Symbol] options Either graph options or registered command name
+    #
+    # @return [Command, Command::Graph]
+    #
     # @api public
-    def command(name)
-      if mappers.key?(name)
-        commands[name].with(mappers: mappers[name])
+    def command(options)
+      case options
+      when Symbol
+        name = options
+        if mappers.key?(name)
+          commands[name].with(mappers: mappers[name])
+        else
+          commands[name]
+        end
+      when Array
+        graph = Commands::Graph.build(commands, options)
+        name = graph.name
+
+        if mappers.key?(name)
+          graph.with(mappers: mappers[graph.name])
+        else
+          graph
+        end
       else
-        commands[name]
+        raise ArgumentError, "#{self.class}#command accepts a symbol or an array"
       end
     end
   end

data/lib/rom/gateway.rb

@@ -0,0 +1,132 @@
+module ROM
+  # Abstract gateway class
+  #
+  # @api public
+  class Gateway
+    # Return connection object
+    #
+    # @return [Object] type varies depending on the gateway
+    #
+    # @api public
+    attr_reader :connection
+
+    # Setup a gateway
+    #
+    # @overload setup(type, *args)
+    #   Sets up a single-gateway given a gateway type.
+    #   For custom gateways, create an instance and pass it directly.
+    #
+    #   @param [Symbol] type
+    #   @param [Array] *args
+    #
+    # @overload setup(gateway)
+    #   @param [Gateway] gateway
+    #
+    # @return [Gateway] a specific gateway subclass
+    #
+    # @example
+    #   module SuperDB
+    #     class Gateway < ROM::Gateway
+    #       def initialize(options)
+    #       end
+    #     end
+    #   end
+    #
+    #   ROM.register_adapter(:super_db, SuperDB)
+    #
+    #   Gateway.setup(:super_db, some: 'options')
+    #   # SuperDB::Gateway.new(some: 'options') is called
+    #
+    #   # or alternatively
+    #   super_db = Gateway.setup(SuperDB::Gateway.new(some: 'options'))
+    #   Gateway.setup(super_db)
+    #
+    # @api public
+    def self.setup(gateway_or_scheme, *args)
+      case gateway_or_scheme
+      when String
+        raise ArgumentError, <<-STRING.gsub(/^ {10}/, '')
+          URIs without an explicit scheme are not supported anymore.
+          See https://github.com/rom-rb/rom/blob/master/CHANGELOG.md
+        STRING
+      when Symbol
+        class_from_symbol(gateway_or_scheme).new(*args)
+      else
+        if args.empty?
+          gateway_or_scheme
+        else
+          raise ArgumentError, "Can't accept arguments when passing an instance"
+        end
+      end
+    end
+
+    # Get gateway subclass for a specific adapter
+    #
+    # @param [Symbol] type adapter identifier
+    #
+    # @return [Class]
+    #
+    # @api private
+    def self.class_from_symbol(type)
+      adapter = ROM.adapters.fetch(type) do
+        begin
+          require "rom/#{type}"
+        rescue LoadError
+          raise AdapterLoadError, "Failed to load adapter rom/#{type}"
+        end
+
+        ROM.adapters.fetch(type)
+      end
+
+      if adapter.const_defined?(:Gateway)
+        adapter.const_get(:Gateway)
+      else
+        adapter.const_get(:Repository)
+      end
+    end
+
+    # A generic interface for setting up a logger
+    #
+    # @api public
+    def use_logger(*)
+      # noop
+    end
+
+    # A generic interface for returning default logger
+    #
+    # @api public
+    def logger
+      # noop
+    end
+
+    # Extension hook for adding gateway-specific behavior to a command class
+    #
+    # @param [Class] klass command class
+    # @param [Object] _dataset dataset that will be used with this command class
+    #
+    # @return [Class]
+    #
+    # @api public
+    def extend_command_class(klass, _dataset)
+      klass
+    end
+
+    # Schema inference hook
+    #
+    # Every gateway that supports schema inference should implement this method
+    #
+    # @return [Array] array with datasets and their names
+    #
+    # @api private
+    def schema
+      []
+    end
+
+    # Disconnect is optional and it's a no-op by default
+    #
+    # @api public
+    def disconnect
+      # noop
+    end
+  end
+end