rom-core 4.0.0.beta1

data/lib/rom/command_compiler.rb

@@ -0,0 +1,239 @@
+require 'dry/core/inflector'
+require 'dry/core/cache'
+
+require 'rom/initializer'
+require 'rom/commands'
+require 'rom/command_proxy'
+
+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 Dry::Core::Cache
+    extend Initializer
+
+    # @api private
+    def self.registry
+      @__registry__ ||= Hash.new { |h, k| h[k] = {} }
+    end
+
+    # @!attribute [r] gateways
+    #   @return [ROM::Registry]
+    param :gateways
+
+    # @!attribute [r] relations
+    #   @return [ROM::RelationRegistry]
+    param :relations
+
+    # @!attribute [r] relations
+    #   @return [ROM::Registry]
+    param :commands
+
+    # @!attribute [r] notifications
+    #   @return [Notifications::EventBus] Configuration notifications event bus
+    param :notifications
+
+    # @!attribute [r] id
+    #   @return [Symbol] The command type registry identifier
+    option :id, optional: true
+
+    # @!attribute [r] adapter
+    #   @return [Symbol] The adapter identifier ie :sql or :http
+    option :adapter, optional: true
+
+    # @!attribute [r] registry
+    #   @return [Hash] local registry where commands will be stored during compilation
+    option :registry, optional: true, default: -> { self.class.registry }
+
+    # @!attribute [r] plugins
+    #   @return [Array<Symbol>] a list of optional plugins that will be enabled for commands
+    option :plugins, optional: true, default: -> { EMPTY_ARRAY }
+
+    # @!attribute [r] meta
+    #   @return [Array<Symbol>] Meta data for a command
+    option :meta, optional: true
+
+    # Return a specific command type 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 [](type, adapter, ast, plugins, meta)
+    #   @param type [Symbol] The type of command
+    #   @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)
+      fetch_or_store(args.hash) do
+        type, adapter, ast, plugins, meta = args
+
+        compiler = with(
+          id: type,
+          adapter: adapter,
+          plugins: Array(plugins),
+          meta: meta
+        )
+
+        graph_opts = compiler.visit(ast)
+        command = ROM::Commands::Graph.build(registry, graph_opts)
+
+        if command.graph?
+          CommandProxy.new(command)
+        elsif command.lazy?
+          command.unwrap
+        else
+          command
+        end
+      end
+    end
+    alias_method :[], :call
+
+    # @api private
+    def type
+      @_type ||= Commands.const_get(Dry::Core::Inflector.classify(id))[adapter]
+    rescue NameError
+      nil
+    end
+
+    # @api private
+    def visit(ast, *args)
+      name, node = ast
+      __send__(:"visit_#{name}", node, *args)
+    end
+
+    private
+
+    # @api private
+    def visit_relation(node, parent_relation = nil)
+      name, header, meta = node
+      other = header.map { |attr| visit(attr, name) }.compact
+
+      if type
+        register_command(name, type, meta, parent_relation)
+
+        default_mapping =
+          if meta[:combine_type] == :many
+            name
+          else
+            { Dry::Core::Inflector.singularize(name).to_sym => name }
+          end
+
+        mapping =
+          if parent_relation
+            associations = relations[parent_relation].associations
+
+            assoc = associations[meta[:combine_name]]
+
+            if assoc
+              { assoc.key => assoc.target.name.to_sym }
+            else
+              default_mapping
+            end
+          else
+            default_mapping
+          end
+
+        if other.size > 0
+          [mapping, [type, other]]
+        else
+          [mapping, type]
+        end
+      else
+        registry[name][id] = commands[name][id]
+        [name, id]
+      end
+    end
+
+    # @api private
+    def visit_attribute(*args)
+      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 [Symbol] type The command type
+    # @param [Hash] meta Meta information from relation AST
+    # @param [Symbol] parent_relation Optional parent relation identifier
+    #
+    # @return [ROM::Command]
+    #
+    # @api private
+    def register_command(rel_name, type, meta, parent_relation = nil)
+      relation = relations[rel_name]
+
+      type.create_class(rel_name, type) do |klass|
+        klass.result(meta.fetch(:combine_type, result))
+
+        if meta[:combine_type]
+          setup_associates(klass, relation, meta, parent_relation)
+        end
+
+        plugins.each do |plugin|
+          klass.use(plugin)
+        end
+
+        gateway = gateways[relation.gateway]
+
+        notifications.trigger(
+          'configuration.commands.class.before_build',
+          command: klass, gateway: gateway, dataset: relation.dataset
+        )
+
+        klass.extend_for_relation(relation) if klass.restrictable
+
+        registry[rel_name][type] = klass.build(relation, input: relation.input_schema)
+      end
+    end
+
+    # Return default result type
+    #
+    # @return [Symbol]
+    #
+    # @api private
+    def result
+      meta.fetch(:result, :one)
+    end
+
+    # Sets up `associates` plugin for a given command class and relation
+    #
+    # @param [Class] klass The command class
+    # @param [Relation] relation The relation for the command
+    #
+    # @api private
+    def setup_associates(klass, relation, meta, parent_relation)
+      assoc_name =
+        if relation.associations.key?(parent_relation)
+          parent_relation
+        else
+          singular_name = Dry::Core::Inflector.singularize(parent_relation).to_sym
+          singular_name if relation.associations.key?(singular_name)
+        end
+
+      if assoc_name
+        klass.associates(assoc_name)
+      else
+        klass.associates(parent_relation)
+      end
+    end
+  end
+end

data/lib/rom/command_proxy.rb

@@ -0,0 +1,24 @@
+require 'dry/core/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, :root
+
+    def initialize(command)
+      @command = command
+      @root = Dry::Core::Inflector.singularize(command.name.relation).to_sym
+    end
+
+    def call(input)
+      command.call(root => input)
+    end
+
+    def >>(other)
+      self.class.new(command >> other)
+    end
+  end
+end

data/lib/rom/command_registry.rb

@@ -0,0 +1,141 @@
+require 'concurrent/map'
+
+require 'rom/constants'
+require 'rom/registry'
+require 'rom/commands/result'
+
+module ROM
+  # Specialized registry class for commands
+  #
+  # @api public
+  class CommandRegistry < Registry
+    include Commands
+
+    # Internal command registry
+    #
+    # @return [Registry]
+    #
+    # @api private
+    param :elements
+
+    # Name of the relation from which commands are under
+    #
+    # @return [String]
+    #
+    # @api private
+    option :relation_name
+
+    option :mappers, optional: true
+
+    option :mapper, optional: true
+
+    option :compiler, optional: true
+
+    def self.element_not_found_error
+      CommandNotFoundError
+    end
+
+    # Try to execute a command in a block
+    #
+    # @yield [command] Passes command to the block
+    #
+    # @example
+    #
+    #   rom.commands[:users].try { create(name: 'Jane') }
+    #   rom.commands[:users].try { update(:by_id, 1).call(name: 'Jane Doe') }
+    #   rom.commands[:users].try { delete(:by_id, 1) }
+    #
+    # @return [Commands::Result]
+    #
+    # @api public
+    def try(&block)
+      response = block.call
+
+      if response.is_a?(Command) || response.is_a?(Composite)
+        try { response.call }
+      else
+        Result::Success.new(response)
+      end
+    rescue CommandError => e
+      Result::Failure.new(e)
+    end
+
+    # Return a command from the registry
+    #
+    # If mapper is set command will be turned into a composite command with
+    # auto-mapping
+    #
+    # @example
+    #   create_user = rom.commands[:users][:create]
+    #   create_user[name: 'Jane']
+    #
+    #   # with mapping, assuming :entity mapper is registered for :users relation
+    #   create_user = rom.commands[:users].map_with(:entity)[:create]
+    #   create_user[name: 'Jane'] # => result is send through :entity mapper
+    #
+    # @param [Symbol] name The name of a registered command
+    #
+    # @return [Command,Command::Composite]
+    #
+    # @api public
+    def [](*args)
+      if args.size.equal?(1)
+        command = super
+        mapper = options[:mapper]
+
+        if mapper
+          command.curry >> mapper
+        else
+          command
+        end
+      else
+        cache.fetch_or_store(args.hash) { compiler.(*args) }
+      end
+    end
+
+    # Specify a mapper that should be used for commands from this registry
+    #
+    # @example
+    #   entity_commands = rom.commands[:users].map_with(:entity)
+    #
+    #
+    # @param [Symbol] mapper_name The name of a registered mapper
+    #
+    # @return [CommandRegistry]
+    #
+    # @api public
+    def map_with(mapper_name)
+      with(mapper: mappers[mapper_name])
+    end
+
+    # @api private
+    def set_compiler(compiler)
+      options[:compiler] = @compiler = compiler
+    end
+
+    # @api private
+    def set_mappers(mappers)
+      options[:mappers] = @mappers = mappers
+    end
+
+    private
+
+    # Allow checking if a certain command is available using dot-notation
+    #
+    # @api private
+    def respond_to_missing?(name, include_private = false)
+      key?(name) || super
+    end
+
+    # Allow retrieving commands using dot-notation
+    #
+    # @api private
+    def method_missing(name, *)
+      if key?(name)
+        self[name]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/rom/commands.rb

@@ -0,0 +1,3 @@
+require 'rom/commands/create'
+require 'rom/commands/update'
+require 'rom/commands/delete'

data/lib/rom/commands/class_interface.rb

@@ -0,0 +1,270 @@
+require 'dry/core/class_builder'
+require 'dry/core/inflector'
+
+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(Dry::Core::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 = EMPTY_HASH)
+        new(relation, self.options.merge(options))
+      end
+
+      # Create a command class with a specific type
+      #
+      # @param [Symbol] command name
+      # @param [Class] parent class
+      #
+      # @yield [Class] create class
+      #
+      # @return [Class, Object] return result of the block if it was provided
+      #
+      # @api public
+      def create_class(name, type, &block)
+        klass = Dry::Core::ClassBuilder
+          .new(name: "#{Dry::Core::Inflector.classify(type)}[:#{name}]", parent: type)
+          .call
+
+        if block
+          yield(klass)
+        else
+          klass
+        end
+      end
+
+      # Use a configured plugin in this relation
+      #
+      # @example
+      #   class CreateUser < ROM::Commands::Create[:memory]
+      #     use :pagintion
+      #
+      #     per_page 30
+      #   end
+      #
+      # @param [Symbol] plugin
+      # @param [Hash] options
+      # @option options [Symbol] :adapter (:default) first adapter to check for plugin
+      #
+      # @api public
+      def use(plugin, _options = EMPTY_HASH)
+        ROM.plugin_registry.commands.fetch(plugin, adapter).apply_to(self)
+      end
+
+      # Extend a command class with relation view methods
+      #
+      # @param [Relation]
+      #
+      # @return [Class]
+      #
+      # @api public
+      def extend_for_relation(relation)
+        include(relation_methods_mod(relation.class))
+      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, 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 before hooks
+      #
+      # @api public
+      def before(*hooks)
+        if hooks.size > 0
+          set_hooks(:before, hooks)
+        else
+          @before
+        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.size > 0
+          set_hooks(:after, hooks)
+        else
+          @after
+        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
+        Dry::Core::Inflector.underscore(Dry::Core::Inflector.demodulize(name)).to_sym
+      end
+
+      # Return default options based on class macros
+      #
+      # @return [Hash]
+      #
+      # @api private
+      def options
+        { input: input, result: result, before: before, after: after }
+      end
+
+      # @api private
+      def relation_methods_mod(relation_class)
+        Module.new do
+          relation_class.view_methods.each do |meth|
+            module_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{meth}(*args)
+                response = relation.public_send(:#{meth}, *args)
+
+                if response.is_a?(relation.class)
+                  new(response)
+                else
+                  response
+                end
+              end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end