rom 5.4.1 → 6.0.0.alpha1

data/lib/rom/commands/class_interface.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "dry/core/class_builder"
+
+module ROM
+  # Base command class with factory class-level interface and setup-related logic
+  #
+  # @private
+  class Command
+    module ClassInterface
+      # This hook sets up default class state
+      #
+      # @api private
+      def inherited(klass)
+        super
+        klass.instance_variable_set(:@before, before.dup)
+        klass.instance_variable_set(:@after, after.dup)
+      end
+
+      # Sets up the base class
+      #
+      # @api private
+      def self.extended(klass)
+        super
+        klass.set_hooks(:before, [])
+        klass.set_hooks(:after, [])
+      end
+
+      # Return adapter specific sub-class based on the adapter identifier
+      #
+      # This is a syntax sugar to make things consistent
+      #
+      # @example
+      #   ROM::Commands::Create[:memory]
+      #   # => ROM::Memory::Commands::Create
+      #
+      # @param [Symbol] adapter identifier
+      #
+      # @return [Class]
+      #
+      # @api public
+      def [](adapter)
+        adapter_namespace(adapter).const_get(Inflector.demodulize(name))
+      end
+
+      # Return namespaces that contains command subclasses of a specific adapter
+      #
+      # @param [Symbol] adapter identifier
+      #
+      # @return [Module]
+      #
+      # @api private
+      def adapter_namespace(adapter)
+        ROM.adapters.fetch(adapter).const_get(:Commands)
+      rescue KeyError
+        raise AdapterNotPresentError.new(adapter, :relation)
+      end
+
+      # Build a command class for a specific relation with options
+      #
+      # @example
+      #   class CreateUser < ROM::Commands::Create[:memory]
+      #   end
+      #
+      #   command = CreateUser.build(rom.relations[:users])
+      #
+      # @param [Relation] relation
+      # @param [Hash] options
+      #
+      # @return [Command]
+      #
+      # @api public
+      def build(relation, **options)
+        new(relation, **options)
+      end
+
+      # Create a command class with a specific type
+      #
+      # @param [Symbol] name Command name
+      # @param [Class] type Command class
+      #
+      # @yield [Class]
+      #
+      # @return [Class, Object]
+      #
+      # @api public
+      def create_class(type: self, meta: {}, rel_meta: {}, plugins: {}, **, &block)
+        klass = Dry::Core::ClassBuilder.new(name: type.name, parent: type).call
+
+        result = meta.fetch(:result, :one)
+        klass.config.result = rel_meta.fetch(:combine_type, result)
+
+        meta.each do |name, value|
+          if klass.respond_to?(name)
+            klass.public_send(name, value)
+          else
+            klass.config[name] = value
+          end
+        end
+
+        plugins.each do |plugin, options|
+          klass.use(plugin, **options)
+        end
+
+        if block
+          yield(klass)
+        else
+          klass
+        end
+      end
+
+      # Return configured adapter identifier
+      #
+      # @return [Symbol]
+      #
+      # @api public
+      def adapter
+        config.component.adapter
+      end
+
+      # Set before-execute hooks
+      #
+      # @overload before(hook)
+      #   Set an before hook as a method name
+      #
+      #   @example
+      #     class CreateUser < ROM::Commands::Create[:sql]
+      #       relation :users
+      #       register_as :create
+      #
+      #       before :my_hook
+      #
+      #       def my_hook(tuple, *)
+      #         puts "hook called#
+      #       end
+      #     end
+      #
+      # @overload before(hook_opts)
+      #   Set an before hook as a method name with arguments
+      #
+      #   @example
+      #     class CreateUser < ROM::Commands::Create[:sql]
+      #       relation :users
+      #       register_as :create
+      #
+      #       before my_hook: { arg1: 1, arg2: 2 }
+      #
+      #       def my_hook(tuple, arg1:, arg2:)
+      #         puts "hook called with args: #{arg1} and #{arg2}"
+      #       end
+      #     end
+      #
+      #   @param [Hash<Symbol=>Hash>] hook Options with method name and pre-set args
+      #
+      # @return [Array<Hash, Symbol>] A list of all configured before hooks
+      #
+      # @api public
+      def before(*hooks)
+        if hooks.empty?
+          @before
+        else
+          set_hooks(:before, hooks)
+        end
+      end
+
+      # Set after-execute hooks
+      #
+      # @overload after(hook)
+      #   Set an after hook as a method name
+      #
+      #   @example
+      #     class CreateUser < ROM::Commands::Create[:sql]
+      #       relation :users
+      #       register_as :create
+      #
+      #       after :my_hook
+      #
+      #       def my_hook(tuple, *)
+      #         puts "hook called#
+      #       end
+      #     end
+      #
+      # @overload after(hook_opts)
+      #   Set an after hook as a method name with arguments
+      #
+      #   @example
+      #     class CreateUser < ROM::Commands::Create[:sql]
+      #       relation :users
+      #       register_as :create
+      #
+      #       after my_hook: { arg1: 1, arg1: 2 }
+      #
+      #       def my_hook(tuple, arg1:, arg2:)
+      #         puts "hook called with args: #{arg1} and #{arg2}"
+      #       end
+      #     end
+      #
+      #   @param [Hash<Symbol=>Hash>] hook Options with method name and pre-set args
+      #
+      # @return [Array<Hash, Symbol>] A list of all configured after hooks
+      #
+      # @api public
+      def after(*hooks)
+        if hooks.empty?
+          @after
+        else
+          set_hooks(:after, hooks)
+        end
+      end
+
+      # Set new or more hooks
+      #
+      # @api private
+      def set_hooks(type, hooks)
+        ivar = :"@#{type}"
+
+        if instance_variable_defined?(ivar)
+          instance_variable_get(ivar).concat(hooks)
+        else
+          instance_variable_set(ivar, hooks)
+        end
+      end
+
+      # Return default name of the command class based on its name
+      #
+      # During setup phase this is used by defalut as `register_as` option
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def default_name
+        Inflector.underscore(Inflector.demodulize(name)).to_sym
+      end
+    end
+  end
+end

data/lib/rom/commands/composite.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rom/pipeline"
+
+module ROM
+  module Commands
+    # Composite command that consists of left and right commands
+    #
+    # @api public
+    class Composite < Pipeline::Composite
+      # Calls the composite command
+      #
+      # Right command is called with a result from the left one
+      #
+      # @return [Object]
+      #
+      # @api public
+      def call(*args)
+        response = left.call(*args)
+
+        if response.nil? || (many? && response.empty?)
+          return one? ? nil : EMPTY_ARRAY
+        end
+
+        if one? && !graph?
+          if right.is_a?(Command) || right.is_a?(Commands::Composite)
+            right.call([response].first)
+          else
+            right.call([response]).first
+          end
+        elsif one? && graph?
+          right.call(response).first
+        else
+          right.call(response)
+        end
+      end
+      alias_method :[], :call
+
+      # @api private
+      def graph?
+        left.is_a?(Graph)
+      end
+
+      # @api private
+      def result
+        left.result
+      end
+
+      # @api private
+      def decorate?(response)
+        super || response.is_a?(Graph)
+      end
+    end
+  end
+end

data/lib/rom/commands/create.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "rom/command"
+
+module ROM
+  module Commands
+    # Create command
+    #
+    # This command inserts a new tuple into a relation
+    #
+    # @abstract
+    class Create < Command
+    end
+  end
+end

data/lib/rom/commands/delete.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "rom/command"
+
+module ROM
+  module Commands
+    # Delete command
+    #
+    # This command removes tuples from its target relation
+    #
+    # @abstract
+    class Delete < Command
+      config.restrictable = true
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rom/commands/graph/input_evaluator"
+
+module ROM
+  module Commands
+    class Graph
+      # Class methods for command Graph
+      #
+      # @api private
+      module ClassInterface
+        # Build a command graph recursively
+        #
+        # This is used by `Container#command` when array with options is passed in
+        #
+        # @param [Registry] registry The command registry from container
+        # @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)
+          cmd_opts, nodes = other
+
+          key, relation =
+            if spec.is_a?(Hash)
+              spec.to_a.first
+            else
+              [spec, spec]
+            end
+
+          name, opts =
+            if cmd_opts.is_a?(Hash)
+              cmd_opts.to_a.first
+            else
+              [cmd_opts]
+            end
+
+          command = registry[relation][name]
+          tuple_path = Array[*path] << key
+          input_proc = InputEvaluator.build(tuple_path, nodes)
+
+          command = command.curry(input_proc, opts)
+
+          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/graph/input_evaluator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ROM
+  module Commands
+    class Graph
+      # Evaluator for lazy commands which extracts values for commands from nested hashes
+      #
+      # @api private
+      class InputEvaluator
+        include Dry::Equalizer(:tuple_path, :excluded_keys)
+
+        # @!attribute [r] tuple_path
+        #   @return [Array<Symbol>] A list of keys pointing to a value inside a hash
+        attr_reader :tuple_path
+
+        # @!attribute [r] excluded_keys
+        #   @return [Array<Symbol>] A list of keys that should be excluded
+        attr_reader :excluded_keys
+
+        # @!attribute [r] exclude_proc
+        #   @return [Array<Symbol>] A function that should determine which keys should be excluded
+        attr_reader :exclude_proc
+
+        # Build an input evaluator
+        #
+        # @param [Array<Symbol>] tuple_path The tuple path
+        # @param [Array] nodes
+        #
+        # @return [InputEvaluator]
+        #
+        # @api private
+        def self.build(tuple_path, nodes)
+          new(tuple_path, extract_excluded_keys(nodes))
+        end
+
+        # @api private
+        def self.extract_excluded_keys(nodes)
+          return unless nodes
+
+          nodes
+            .map { |item| item.is_a?(Array) && item.size > 1 ? item.first : item }
+            .compact
+            .map { |item| item.is_a?(Hash) ? item.keys.first : item }
+            .reject { |item| item.is_a?(Array) }
+        end
+
+        # Return default exclude_proc
+        #
+        # @api private
+        def self.exclude_proc(excluded_keys)
+          -> input { input.reject { |k, _| excluded_keys.include?(k) } }
+        end
+
+        # Initialize a new input evaluator
+        #
+        # @return [InputEvaluator]
+        #
+        # @api private
+        def initialize(tuple_path, excluded_keys)
+          @tuple_path = tuple_path
+          @excluded_keys = excluded_keys
+          @exclude_proc = self.class.exclude_proc(excluded_keys)
+        end
+
+        # Evaluate input hash
+        #
+        # @param [Hash] input The input hash
+        # @param [Integer] index Optional index
+        #
+        # @return [Hash]
+        def call(input, index = nil)
+          value =
+            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 => e
+              raise KeyMissing, e.message
+            end
+
+          if excluded_keys
+            value.is_a?(Array) ? value.map(&exclude_proc) : exclude_proc[value]
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/commands/graph.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "rom/initializer"
+require "rom/pipeline"
+require "rom/commands/graph/class_interface"
+
+module ROM
+  module Commands
+    # Command graph
+    #
+    # @api private
+    class Graph
+      extend Initializer
+      include Dry::Equalizer(:root, :nodes)
+
+      extend ClassInterface
+
+      include Pipeline
+      include Pipeline::Proxy
+
+      # @attr_reader [Command] root The root command
+      param :root
+
+      # @attr_reader [Array<Command>] nodes The child commands
+      param :nodes
+
+      alias_method :left, :root
+      alias_method :right, :nodes
+
+      # @attr_reader [Symbol] root's relation name
+      option :name, default: -> { root.name }
+
+      # Calls root and all nodes with the result from root
+      #
+      # Graph results are mappable through `combine` operation in mapper DSL
+      #
+      # @example
+      #   create_user = rom.commands[:users][:create]
+      #   create_task = rom.commands[:tasks][:create]
+      #
+      #   command = create_user
+      #     .curry(name: 'Jane')
+      #     .combine(create_task.curry(title: 'Task'))
+      #
+      #   command.call
+      #
+      # @return [Array] nested array with command results
+      #
+      # @api public
+      def call(*args)
+        left = root.call(*args)
+
+        right = nodes.map { |node|
+          response =
+            if node.lazy?
+              node.call(args.first, left)
+            else
+              node.call(left)
+            end
+
+          if node.one? && !node.graph?
+            [response]
+          else
+            response
+          end
+        }
+
+        if one?
+          [[left], right]
+        else
+          [left, right]
+        end
+      end
+
+      # @api private
+      def graph?
+        true
+      end
+
+      private
+
+      # @api public
+      def composite_class
+        Command::Composite
+      end
+    end
+  end
+end

data/lib/rom/commands/lazy/create.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ROM
+  module Commands
+    class Lazy
+      # Lazy command wrapper for create commands
+      #
+      # @api public
+      class Create < Lazy
+        # Execute a command
+        #
+        # @see Command::Create#call
+        #
+        # @return [Hash,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 |parent, index|
+              children = evaluator.call(first, index)
+              command_proc[command, parent, children].call(children, parent)
+            end.reduce(:concat)
+          else
+            input = evaluator.call(first)
+            command.call(input, *args[1..size - 1])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/commands/lazy/delete.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ROM
+  module Commands
+    class Lazy
+      # Lazy command wrapper for delete commands
+      #
+      # @api public
+      class Delete < Lazy
+        # Execute a lazy delete command
+        #
+        # @see Commands::Delete#call
+        #
+        # @return [Hash, Array<Hash>]
+        #
+        # @api public
+        def call(*args)
+          first = args.first
+          last = args.last
+          size = args.size
+
+          if size > 1 && last.is_a?(Array)
+            raise NotImplementedError
+          else
+            input = evaluator.call(first)
+
+            if input.is_a?(Array)
+              input.map do |item|
+                command_proc[command, *(size > 1 ? [last, item] : [input])].call
+              end
+            else
+              command_proc[command, input].call
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/commands/lazy/update.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module ROM
+  module Commands
+    class Lazy
+      # Lazy command wrapper for update commands
+      #
+      # @api public
+      class Update < Lazy
+        # Execute a lazy update command
+        #
+        # @see Commands::Update#call
+        #
+        # @return [Hash, 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 |parent, index|
+              children = evaluator.call(first, index)
+
+              children.map do |child|
+                command_proc[command, parent, child].call(child, parent)
+              end
+            end.reduce(:concat)
+          else
+            input = evaluator.call(first)
+
+            if input.is_a?(Array)
+              input.map.with_index do |item, _index|
+                command_proc[command, last, item].call(item, *args[1..size - 1])
+              end
+            else
+              command_proc[command, *(size > 1 ? [last, input] : [input])]
+                .call(input, *args[1..size - 1])
+            end
+          end
+        end
+      end
+    end
+  end
+end