rom 5.4.1 → 6.0.0.alpha1

data/lib/rom/command.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+require "rom/support/configurable"
+require "rom/types"
+require "rom/initializer"
+require "rom/pipeline"
+require "rom/plugins/class_methods"
+
+require "rom/commands/class_interface"
+require "rom/commands/composite"
+require "rom/commands/graph"
+require "rom/commands/lazy"
+
+require_relative "components/provider"
+
+module ROM
+  # Abstract command class
+  #
+  # Provides a constructor accepting relation with options and basic behavior
+  # for calling, currying and composing commands.
+  #
+  # Typically command subclasses should inherit from specialized
+  # Create/Update/Delete, not this one.
+  #
+  # @abstract
+  #
+  # @api public
+  class Command
+    extend ROM::Provider(type: :command)
+    extend Plugins::ClassMethods
+    extend Initializer
+    extend ClassInterface
+
+    include Dry::Equalizer(:relation, :options)
+    include Commands
+    include Pipeline::Operator
+
+    setting :restrictable
+    setting :result
+    setting :input
+    setting :type
+
+    config.input = Hash
+    config.result = :many
+
+    # @!attribute [r] relation
+    #   @return [Relation] Command's relation
+    param :relation
+
+    CommandType = Types::Strict::Symbol.enum(:create, :update, :delete)
+    Result = Types::Strict::Symbol.enum(:one, :many)
+
+    # @!attribute [r] type
+    #   @return [Symbol] The command type, one of :create, :update or :delete
+    option :type, type: CommandType, optional: true
+
+    # @!attribute [r] config
+    #   @return [Dry::Configurable::Config]
+    option :config, default: -> { self.class.config }
+
+    # @!attribute [r] source
+    #   @return [Relation] The source relation
+    option :source, default: -> { relation }
+
+    # @!attribute [r] result
+    #   @return [Symbol] Result type, either :one or :many
+    option :result, type: Result, default: -> { config.result }
+
+    # @!attribute [r] input
+    #   @return [Proc, #call] Tuple processing function, typically uses Relation#input_schema
+    option :input, default: -> { config.input }
+
+    # @!attribute [r] curry_args
+    #   @return [Array] Curried args
+    option :curry_args, default: -> { EMPTY_ARRAY }
+
+    # @!attribute [r] before
+    #   @return [Array<Hash>] An array with before hooks configuration
+    option :before, Types::Coercible::Array, reader: false, default: -> { self.class.before }
+
+    # @!attribute [r] after
+    #   @return [Array<Hash>] An array with after hooks configuration
+    option :after, Types::Coercible::Array, reader: false, default: -> { self.class.after }
+
+    # Return name of this command's relation
+    #
+    # @return [ROM::Relation::Name]
+    #
+    # @api public
+    def name
+      relation.name
+    end
+
+    # Return gateway of this command's relation
+    #
+    # @return [Symbol]
+    #
+    # @api public
+    def gateway
+      relation.gateway
+    end
+
+    # Execute the command
+    #
+    # @abstract
+    #
+    # @return [Array] an array with inserted tuples
+    #
+    # @api private
+    def execute(*)
+      raise(
+        NotImplementedError,
+        "#{self.class}##{__method__} must be implemented"
+      )
+    end
+
+    # Call the command and return one or many tuples
+    #
+    # This method will apply before/after hooks automatically
+    #
+    # @api public
+    def call(*args, &block)
+      tuples =
+        if hooks?
+          prepared =
+            if curried?
+              apply_hooks(before_hooks, *(curry_args + args))
+            else
+              apply_hooks(before_hooks, *args)
+            end
+
+          result = prepared ? execute(prepared, &block) : execute(&block)
+
+          if curried?
+            if !args.empty?
+              apply_hooks(after_hooks, result, *args)
+            elsif curry_args.size > 1
+              apply_hooks(after_hooks, result, curry_args[1])
+            else
+              apply_hooks(after_hooks, result)
+            end
+          else
+            apply_hooks(after_hooks, result, *args[1..args.size - 1])
+          end
+        else
+          execute(*(curry_args + args), &block)
+        end
+
+      if one?
+        tuples.first
+      else
+        tuples
+      end
+    end
+    alias_method :[], :call
+
+    # Curry this command with provided args
+    #
+    # Curried command can be called without args. If argument is a graph input processor,
+    # lazy command will be returned, which is used for handling nested input hashes.
+    #
+    # @return [Command, Lazy]
+    #
+    # @api public
+    def curry(*args)
+      if curry_args.empty? && args.first.is_a?(Graph::InputEvaluator)
+        Lazy[self].new(self, *args)
+      else
+        self.class.build(relation, **options, curry_args: args)
+      end
+    end
+
+    # Compose this command with other commands
+    #
+    # Composed commands can handle nested input
+    #
+    # @return [Command::Graph]
+    #
+    # @api public
+    def combine(*others)
+      Graph.new(self, others)
+    end
+
+    # Check if this command is curried
+    #
+    # @return [TrueClass, FalseClass]
+    #
+    # @api public
+    def curried?
+      !curry_args.empty?
+    end
+
+    # Return a new command with appended before hooks
+    #
+    # @param [Array<Hash>] hooks A list of before hooks configurations
+    #
+    # @return [Command]
+    #
+    # @api public
+    def before(*hooks)
+      self.class.new(relation, **options, before: before_hooks + hooks)
+    end
+
+    # Return a new command with appended after hooks
+    #
+    # @param [Array<Hash>] hooks A list of after hooks configurations
+    #
+    # @return [Command]
+    #
+    # @api public
+    def after(*hooks)
+      self.class.new(relation, **options, after: after_hooks + hooks)
+    end
+
+    # List of before hooks
+    #
+    # @return [Array]
+    #
+    # @api public
+    def before_hooks
+      options[:before]
+    end
+
+    # List of after hooks
+    #
+    # @return [Array]
+    #
+    # @api public
+    def after_hooks
+      options[:after]
+    end
+
+    # Return a new command with other source relation
+    #
+    # This can be used to restrict command with a specific relation
+    #
+    # @return [Command]
+    #
+    # @api public
+    def new(new_relation)
+      self.class.build(new_relation, **options, source: relation)
+    end
+
+    # Check if this command has any hooks
+    #
+    # @api private
+    def hooks?
+      !before_hooks.empty? || !after_hooks.empty?
+    end
+
+    # Check if this command is lazy
+    #
+    # @return [false]
+    #
+    # @api private
+    def lazy?
+      false
+    end
+
+    # Check if this command is a graph
+    #
+    # @return [false]
+    #
+    # @api private
+    def graph?
+      false
+    end
+
+    # Check if this command returns a single tuple
+    #
+    # @return [TrueClass,FalseClass]
+    #
+    # @api private
+    def one?
+      result.equal?(:one)
+    end
+
+    # Check if this command returns many tuples
+    #
+    # @return [TrueClass,FalseClass]
+    #
+    # @api private
+    def many?
+      result.equal?(:many)
+    end
+
+    # Check if this command is restrictible through relation
+    #
+    # @return [TrueClass,FalseClass]
+    #
+    # @api private
+    def restrictible?
+      config.restrictable.equal?(true)
+    end
+
+    # Yields tuples for insertion or return an enumerator
+    #
+    # @api private
+    def map_input_tuples(tuples, &mapper)
+      return enum_for(:with_input_tuples, tuples) unless mapper
+
+      if tuples.respond_to? :merge
+        mapper[tuples]
+      else
+        tuples.map(&mapper)
+      end
+    end
+
+    private
+
+    # Hook called by Pipeline to get composite class for commands
+    #
+    # @return [Class]
+    #
+    # @api private
+    def composite_class
+      Command::Composite
+    end
+
+    # Apply provided hooks
+    #
+    # Used by #call
+    #
+    # @return [Array<Hash>]
+    #
+    # @api private
+    def apply_hooks(hooks, tuples, *args)
+      hooks.reduce(tuples) do |a, e|
+        if e.is_a?(Hash)
+          hook_meth, hook_args = e.to_a.flatten(1)
+          __send__(hook_meth, a, *args, **hook_args)
+        else
+          __send__(e, a, *args)
+        end
+      end
+    end
+
+    # Pipes a dataset through command's relation
+    #
+    # @return [Array]
+    #
+    # @api private
+    def wrap_dataset(dataset)
+      if relation.is_a?(Relation::Composite)
+        relation.new(dataset).to_a
+      else
+        dataset
+      end
+    end
+  end
+end

data/lib/rom/command_compiler.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "rom/initializer"
+require "rom/commands/graph"
+require "rom/command_proxy"
+require "rom/registries/root"
+
+module ROM
+  # Builds commands for relations.
+  #
+  # This class is used by repositories to automatically create commands for
+  # their relations. This is used both by `Repository#command` method and
+  # `commands` repository class macros.
+  #
+  # @api private
+  class CommandCompiler
+    extend Initializer
+
+    # @!attribute [r] id
+    #   @return [Symbol] The command registry identifier
+    option :id, optional: true
+
+    # @!attribute [r] command_class
+    #   @return [Symbol] The command command_class
+    option :command_class, optional: true
+
+    # @!attribute [r] registry
+    #   @return [Registry::Root]
+    option :registry, default: -> { Registry::Root.new }
+
+    # @!attribute [r] plugins
+    #   @return [Array<Symbol>] a list of optional plugins that will be enabled for commands
+    option :plugins, optional: true, default: -> { EMPTY_HASH }
+
+    # @!attribute [r] meta
+    #   @return [Array<Symbol>] Meta data for a command
+    option :meta, optional: true
+
+    # @!attribute [r] cache
+    #   @return [Cache] local cache instance
+    option :cache, default: -> { Cache.new }
+
+    # Return a specific command command_class for a given adapter and relation AST
+    #
+    # This class holds its own registry where all generated commands are being
+    # stored
+    #
+    # CommandProxy is returned for complex command graphs as they expect root
+    # relation name to be present in the input, which we don't want to have
+    # in repositories. It might be worth looking into removing this requirement
+    # from rom core Command::Graph API.
+    #
+    # @overload [](id, adapter, ast, plugins, meta)
+    #   @param id [Symbol] The command identifier
+    #   @param adapter [Symbol] The adapter identifier
+    #   @param ast [Array] The AST representation of a relation
+    #   @param plugins [Array<Symbol>] A list of optional command plugins that should be used
+    #   @param meta [Hash] Meta data for a command
+    #
+    #   @return [Command, CommandProxy]
+    #
+    # @api private
+    def call(*args)
+      cache.fetch_or_store(args.hash) do
+        id, adapter, ast, plugins, plugins_options, meta = args
+
+        component = registry.components.get(:commands, id: id)
+
+        command_class =
+          if component
+            component.constant
+          else
+            Command.adapter_namespace(adapter).const_get(Inflector.classify(id))
+          end
+
+        plugins_with_opts = Array(plugins)
+          .map { |plugin| [plugin, plugins_options.fetch(plugin) { EMPTY_HASH }] }
+          .to_h
+
+        compiler = with(
+          id: id,
+          command_class: command_class,
+          adapter: adapter,
+          plugins: plugins_with_opts,
+          meta: meta
+        )
+
+        graph_opts = compiler.visit(ast)
+        command = ROM::Commands::Graph.build(registry.root.commands, graph_opts)
+
+        if command.graph?
+          root = Inflector.singularize(command.name.relation).to_sym
+          CommandProxy.new(command, root)
+        elsif command.lazy?
+          command.unwrap
+        else
+          command
+        end
+      end
+    end
+    alias_method :[], :call
+
+    # @api private
+    def visit(ast, *args)
+      name, node = ast
+      __send__(:"visit_#{name}", node, *args)
+    end
+
+    # @api private
+    def relations
+      registry.root.relations
+    end
+
+    private
+
+    # @api private
+    def visit_relation(node, parent_relation = nil)
+      name, header, rel_meta = node
+      other = header.map { |attr| visit(attr, name) }.compact
+
+      key = register_command(name, rel_meta, parent_relation)
+
+      default_mapping =
+        if rel_meta[:combine_command_class] == :many
+          name
+        else
+          {Inflector.singularize(name).to_sym => name}
+        end
+
+      mapping =
+        if parent_relation
+          associations = relations[parent_relation].associations
+
+          assoc = associations[rel_meta[:combine_name]]
+
+          if assoc
+            {assoc.key => assoc.target.name.to_sym}
+          else
+            default_mapping
+          end
+        else
+          default_mapping
+        end
+
+      if other.empty?
+        [mapping, key]
+      else
+        [mapping, [key, other]]
+      end
+    end
+
+    # @api private
+    def visit_attribute(*)
+      nil
+    end
+
+    # Build a command object for a specific relation
+    #
+    # The command will be prepared for handling associations if it's a combined
+    # relation. Additional plugins will be enabled if they are configured for
+    # this compiler.
+    #
+    # @param [Symbol] rel_name A relation identifier from the container registry
+    # @param [Hash] rel_meta Meta information from relation AST
+    # @param [Symbol] parent_relation Optional parent relation identifier
+    #
+    # @return [ROM::Command]
+    #
+    # @api private
+    def register_command(rel_name, rel_meta, parent_relation = nil)
+      options = {
+        rel_name: rel_name,
+        meta: meta,
+        rel_meta: rel_meta,
+        parent_relation: parent_relation,
+        plugins: plugins
+      }
+
+      key = "commands.#{rel_name}.#{id}-compiled-#{options.hash}"
+
+      registry.fetch(key) do
+        relation = relations[rel_name]
+        klass = command_class.create_class(relation: relation, **options)
+
+        if gateways.key?(relation.gateway)
+          # TODO: add explicit specs covering this case
+          gateways[relation.gateway].command(klass, relation: relation, **options)
+        else
+          klass.build(relation, **options)
+        end
+      end
+
+      key
+    end
+
+    # @api private
+    def gateways
+      registry.root.gateways
+    end
+  end
+end

data/lib/rom/command_proxy.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rom/support/inflector"
+
+module ROM
+  # TODO: look into making command graphs work without the root key in the input
+  #       so that we can get rid of this wrapper
+  #
+  # @api private
+  class CommandProxy
+    attr_reader :command
+
+    attr_reader :root
+
+    # @api private
+    def initialize(command, root)
+      @command = command
+      @root = root
+    end
+
+    # @api private
+    def call(input)
+      command.call(root => input)
+    end
+
+    # @api private
+    def >>(other)
+      self.class.new(command >> other, root)
+    end
+
+    # @api private
+    def restrictible?
+      command.restrictible?
+    end
+  end
+end