rom 2.0.2 → 3.0.0

data/lib/rom/command.rb

@@ -1,5 +1,8 @@
-require 'rom/support/deprecations'
-require 'rom/support/options'
+require 'dry/core/deprecations'
+require 'dry/core/class_attributes'
+
+require 'rom/types'
+require 'rom/initializer'
 require 'rom/pipeline'
 
 require 'rom/commands/class_interface'
@@ -18,58 +21,213 @@ module ROM
   #
   # @abstract
   #
-  # @private
+  # @api public
   class Command
-    DEFAULT_VALIDATOR = proc {}
-
+    extend Initializer
     include Dry::Equalizer(:relation, :options)
     include Commands
     include Pipeline::Operator
 
-    extend ClassMacros
+    extend Dry::Core::ClassAttributes
     extend ClassInterface
 
-    include Options
+    # @!method self.adapter
+    #   Get or set adapter identifier
+    #
+    #   @overload adapter
+    #     Get adapter identifier
+    #
+    #     @example
+    #       ROM::Memory::Commands::Create.adapter
+    #       # => :memory
+    #
+    #     @return [Symbol]
+    #
+    #   @overload adapter(identifier)
+    #     Set adapter identifier. This must always match actual adapter identifier
+    #     that was used to register an adapter.
+    #
+    #     @example
+    #       module MyAdapter
+    #         class CreateCommand < ROM::Commands::Memory::Create
+    #           adapter :my_adapter
+    #         end
+    #       end
+    #
+    # @api public
+    defines :adapter
 
-    defines :adapter, :relation, :result, :input, :validator, :register_as, :restrictable
+    # @!method self.relation
+    #   Get or set relation identifier
+    #
+    #   @overload relation
+    #     Get relation identifier
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         relation :users
+    #       end
+    #
+    #       CreateUser.relation
+    #       # => :users
+    #
+    #     @return [Symbol]
+    #
+    #   @overload relation(identifier)
+    #     Set relation identifier.
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         relation :users
+    #       end
+    #
+    # @api public
+    defines :relation
 
-    option :type, allow: [:create, :update, :delete]
-    option :source, reader: true
-    option :result, reader: true, allow: [:one, :many]
-    option :validator, reader: true
-    option :input, reader: true
-    option :curry_args, type: Array, reader: true, default: EMPTY_ARRAY
+    # @!method self.relation
+    #   Get or set result type
+    #
+    #   @overload result
+    #     Get result type
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         result :one
+    #       end
+    #
+    #       CreateUser.result
+    #       # => :one
+    #
+    #     @return [Symbol]
+    #
+    #   @overload relation(identifier)
+    #     Set result type
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         result :one
+    #       end
+    #
+    # @api public
+    defines :result
 
-    input Hash
-    validator DEFAULT_VALIDATOR
-    result :many
+    # @!method self.relation
+    #   Get or set input processing function. This is typically set during setup
+    #   to relation's input_schema
+    #
+    #   @overload input
+    #     Get input processing function
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         input -> tuple { .. }
+    #       end
+    #
+    #       CreateUser.input
+    #       # Your custom function
+    #
+    #     @return [Proc,#call]
+    #
+    #   @overload input(identifier)
+    #     Set input processing function
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         input -> tuple { .. }
+    #       end
+    #
+    # @api public
+    defines :input
 
-    # @deprecated
+    # @!method self.register_as
+    #   Get or set identifier that should be used to register a command in a container
+    #
+    #   @overload register_as
+    #     Get registration identifier
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         register_as :create_user
+    #       end
+    #
+    #       CreateUser.register_as
+    #       # => :create_user
+    #
+    #     @return [Symbol]
+    #
+    #   @overload register_as(identifier)
+    #     Set registration identifier
+    #
+    #     @example
+    #       module CreateUser < ROM::Commands::Create[:memory]
+    #         register_as :create_user
+    #       end
     #
     # @api public
-    def self.validator(vp = nil)
-      if defined?(@validator) && vp.nil?
-        @validator
-      else
-        unless vp.equal?(DEFAULT_VALIDATOR)
-          Deprecations.announce(
-            "#{name}.validator",
-            'Please handle validation before calling commands'
-          )
-        end
-        super
-      end
-    end
+    defines :register_as
+
+    # @!method self.restrictable
+    #   @overload restrictable
+    #     Check if a command class is restrictable
+    #
+    #     @example
+    #       module UpdateUser < ROM::Commands::Update[:memory]
+    #         restrictable true
+    #       end
+    #
+    #       CreateUser.restrictable
+    #       # => true
+    #
+    #     @return [FalseClass, TrueClass]
+    #
+    #   @overload restrictable(value)
+    #     Set if a command is restrictable
+    #
+    #     @example
+    #       module UpdateUser < ROM::Commands::Update[:memory]
+    #         restrictable true
+    #       end
+    #
+    # @api public
+    defines :restrictable
 
-    # @attr_reader [Relation] relation The command's relation
-    attr_reader :relation
+    # @!attribute [r] relation
+    #   @return [Relation] Command's relation
+    param :relation
 
-    # @api private
-    def initialize(relation, options = EMPTY_HASH)
-      super
-      @relation = relation
-      @source = options[:source] || relation
-    end
+    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] source
+    #   @return [Relation] The source relation
+    option :source, reader: true, optional: true, default: -> c { c.relation }
+
+    # @!attribute [r] type
+    #   @return [Symbol] Result type, either :one or :many
+    option :result, reader: true, type: Result
+
+    # @!attribute [r] input
+    #   @return [Proc, #call] Tuple processing function, typically uses Relation#input_schema
+    option :input, reader: true
+
+    # @!attribute [r] curry_args
+    #   @return [Array] Curried args
+    option :curry_args, reader: true, default: -> _ { EMPTY_ARRAY }
+
+    # @!attribute [r] before
+    #   @return [Array<Hash>] An array with before hooks configuration
+    option :before, Types::Coercible::Array, reader: true, as: :before_hooks, default: proc { EMPTY_ARRAY }
+
+    # @!attribute [r] before
+    #   @return [Array<Hash>] An array with after hooks configuration
+    option :after, Types::Coercible::Array, reader: true, as: :after_hooks, default: proc { EMPTY_ARRAY }
+
+    input Hash
+    result :many
 
     # Return name of this command's relation
     #
@@ -105,9 +263,35 @@ module ROM
 
     # Call the command and return one or many tuples
     #
+    # This method will apply before/after hooks automatically
+    #
     # @api public
     def call(*args, &block)
-      tuples = execute(*(curry_args + 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.size > 0
+              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
@@ -119,9 +303,10 @@ module ROM
 
     # Curry this command with provided args
     #
-    # Curried command can be called without 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]
+    # @return [Command, Lazy]
     #
     # @api public
     def curry(*args)
@@ -133,41 +318,140 @@ module ROM
     end
     alias_method :with, :curry
 
+    # 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.size > 0
+    end
+
+    # Return a new command with new options
+    #
+    # @param [Hash] new_opts A hash with new options
+    #
+    # @return [Command]
+    #
+    # @api public
+    def with_opts(new_opts)
+      self.class.new(relation, options.merge(new_opts))
+    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.merge(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.merge(after: after_hooks + hooks))
+    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.merge(source: relation))
+    end
+
+    # Check if this command has any hooks
+    #
+    # @api private
+    def hooks?
+      before_hooks.size > 0 || after_hooks.size > 0
+    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
 
-    # @api private
-    def new(new_relation)
-      self.class.build(new_relation, options.merge(source: relation))
-    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
   end
 end

data/lib/rom/command_registry.rb

@@ -1,3 +1,4 @@
+require 'rom/types'
 require 'rom/commands/result'
 
 module ROM
@@ -5,40 +6,28 @@ module ROM
   #
   # @api public
   class CommandRegistry
+    extend Initializer
     include Commands
-    include Options
 
     CommandNotFoundError = Class.new(KeyError)
+    RegistryType = Types.Definition(Registry) | Types.Constructor(Registry) { |r| Registry.new(r, self.class.name) }
 
     # Name of the relation from which commands are under
     #
     # @return [String]
     #
     # @api private
-    attr_reader :relation_name
+    param :relation_name
 
     # Internal command registry
     #
     # @return [Registry]
     #
     # @api private
-    attr_reader :registry
+    param :registry, type: RegistryType
 
-    option :mappers, reader: true
-    option :mapper, reader: true
-
-    # @api private
-    def initialize(relation_name, elements, options = EMPTY_HASH)
-      super
-
-      @relation_name = relation_name
-      @registry =
-        if elements.is_a?(Registry)
-          elements
-        else
-          Registry.new(elements, self.class.name)
-        end
-    end
+    option :mappers, reader: true, optional: true
+    option :mapper, reader: true, optional: true
 
     # Try to execute a command in a block
     #

data/lib/rom/commands/class_interface.rb

@@ -1,4 +1,5 @@
-require 'rom/support/class_builder'
+require 'dry/core/class_builder'
+require 'dry/core/inflector'
 
 module ROM
   # Base command class with factory class-level interface and setup-related logic
@@ -6,6 +7,15 @@ module ROM
   # @private
   class Command
     module ClassInterface
+      # This hook sets up default class state
+      #
+      # @api private
+      def inherited(klass)
+        super
+        klass.instance_variable_set(:'@before', before ? before.dup : [])
+        klass.instance_variable_set(:'@after', before ? after.dup : [])
+      end
+
       # Return adapter specific sub-class based on the adapter identifier
       #
       # This is a syntax sugar to make things consistent
@@ -20,7 +30,7 @@ module ROM
       #
       # @api public
       def [](adapter)
-        adapter_namespace(adapter).const_get(Inflector.demodulize(name))
+        adapter_namespace(adapter).const_get(Dry::Core::Inflector.demodulize(name))
       end
 
       # Return namespaces that contains command subclasses of a specific adapter
@@ -65,8 +75,8 @@ module ROM
       #
       # @api public
       def create_class(name, type, &block)
-        klass = ClassBuilder
-          .new(name: "#{Inflector.classify(type)}[:#{name}]", parent: type)
+        klass = Dry::Core::ClassBuilder
+          .new(name: "#{Dry::Core::Inflector.classify(type)}[:#{name}]", parent: type)
           .call
 
         if block
@@ -105,6 +115,110 @@ module ROM
         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}"
+        value = instance_variable_get(ivar)
+
+        if value.empty?
+          instance_variable_set(ivar, hooks)
+        else
+          value.concat(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
@@ -113,7 +227,7 @@ module ROM
       #
       # @api private
       def default_name
-        Inflector.underscore(Inflector.demodulize(name)).to_sym
+        Dry::Core::Inflector.underscore(Dry::Core::Inflector.demodulize(name)).to_sym
       end
 
       # Return default options based on class macros
@@ -122,7 +236,7 @@ module ROM
       #
       # @api private
       def options
-        { input: input, validator: validator, result: result }
+        { input: input, result: result, before: before, after: after }
       end
 
       # @api private

data/lib/rom/commands/composite.rb

@@ -1,5 +1,4 @@
 require 'rom/pipeline'
-require 'rom/support/constants'
 
 module ROM
   module Commands