rom 3.0.0.rc1 → 3.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3b8faaf70d24fe2d5212f777e8023dfc4b6a2e34
-  data.tar.gz: 4fe312831401a4a99c9837ef1948af386b558762
+  metadata.gz: c09afbd9407f30670628cfcfaebf9d903ca6619c
+  data.tar.gz: a94d330cd2a0ecb12c500042b9659ec5ee48c568
 SHA512:
-  metadata.gz: e46223303dd3c701780526df9184c5c2c03cec5aee5a5cc3d3ba64ebd6e962619c2b04af8c309db4410d19bbf999e41c2ef813a667bccd5d5c8c468d69ff9fef
-  data.tar.gz: 09b1af7a72438045fc804872a8cfa63ac8d9c2c3add1123a71f6e6117d7f61c65e005c241e35757a25b3d2ec19b877f97516ba6bae74b973083e5f013d2bb21f
+  metadata.gz: cf5b188aca3186e6f402f4e246edc6555821fb0d0a24e771715267806a923fd3bd19ec4a0270a572b4fd7c48ee8d9ff380a2aca407202d6d84c1846f884b81e7
+  data.tar.gz: 552d6f7c1436ae873f1926feafd38f218090ec3ba0a109b45fa931eb3578452f4611745426adb2fbeca537c9ed36ba66c4b99b5ac00faf815e0e17a921811039

data/lib/rom/command.rb

@@ -21,7 +21,7 @@ module ROM
   #
   # @abstract
   #
-  # @private
+  # @api public
   class Command
     extend Initializer
     include Dry::Equalizer(:relation, :options)
@@ -31,20 +31,199 @@ module ROM
     extend Dry::Core::ClassAttributes
     extend ClassInterface
 
-    defines :adapter, :relation, :result, :input, :register_as, :restrictable
+    # @!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
 
-    # @attr_reader [Relation] relation The command's relation
+    # @!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
+
+    # @!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
+
+    # @!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
+
+    # @!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
+    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
+
+    # @!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] 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
@@ -84,6 +263,8 @@ 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 =
@@ -98,7 +279,13 @@ module ROM
           result = prepared ? execute(prepared, &block) : execute(&block)
 
           if curried?
-            apply_hooks(after_hooks, result, *args)
+            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
@@ -116,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)
@@ -130,68 +318,130 @@ 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
 
-    # @api private
-    def hooks?
-      before_hooks.size > 0 || after_hooks.size > 0
+    # 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 combine(*others)
-      Graph.new(self, others)
+    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
-
-    # @api public
-    def with_opts(new_opts)
-      self.class.new(relation, options.merge(new_opts))
-    end
-
-    # @api public
-    def before(*hooks)
-      self.class.new(relation, options.merge(before: before_hooks + hooks))
-    end
-
-    # @api public
-    def after(*hooks)
-      self.class.new(relation, options.merge(after: after_hooks + hooks))
-    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|

data/lib/rom/container.rb

@@ -11,14 +11,14 @@ module ROM
   #
   # There are 3 types of container setup:
   #
-  # * in-line setup - a simple block-based configuration which allows configuring
+  # * Setup DSL - a simple block-based configuration which allows configuring
   #   all components and gives you back a container instance. This type is suitable
   #   for small scripts, or in some cases rake tasks
-  # * multi-step setup - this type requires creating a configuration object,
+  # * Explicit setup - this type requires creating a configuration object,
   #   registering component classes (ie relation classes) and passing the config
   #   to container builder function. This type is suitable when your environment
   #   is not typical and you need full control over component registration
-  # * multi-step setup with auto-registration - same as multi-step but allows
+  # * Explicit setup with auto-registration - same as explicit setup but allows
   #   you to configure auto-registration mechanism which will register component
   #   classes for you, based on dir/file naming conventions. This is the most
   #   common type of setup that's used by framework integrations
@@ -99,24 +99,20 @@ module ROM
   class Container
     include Dry::Equalizer(:gateways, :relations, :mappers, :commands)
 
-    # @return [Hash] configured gateways
-    #
-    # @api public
+    # @!attribute [r] gateways
+    #   @return [Hash] A hash with configured gateways
     attr_reader :gateways
 
-    # @return [RelationRegistry] relation registry
-    #
-    # @api public
+    # @!attribute [r] relations
+    #   @return [RelationRegistry] The relation registry
     attr_reader :relations
 
-    # @return [Registry] command registry
-    #
-    # @api public
+    # @!attribute [r] gateways
+    #   @return [CommandRegistry] The command registry
     attr_reader :commands
 
-    # @return [Registry] mapper registry
-    #
-    # @api public
+    # @!attribute [r] mappers
+    #   @return [Hash] A hash with configured custom mappers
     attr_reader :mappers
 
     # @api private

data/lib/rom/gateway.rb

@@ -5,49 +5,61 @@ require 'rom/transaction'
 module ROM
   # Abstract gateway class
   #
+  # Every adapter needs to inherit from this class and implement
+  # required interface
+  #
+  # @abstract
+  #
   # @api public
   class Gateway
     extend Dry::Core::ClassAttributes
 
     defines :adapter
 
-    # Return connection object
-    #
-    # @return [Object] type varies depending on the gateway
-    #
-    # @api public
+    # @!attribute [r] connection
+    #   @return [Object] The gateway's connection object (type varies across adapters)
     attr_reader :connection
 
-    # Setup a gateway
+    # Set up 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
+    #   @example
+    #     module SuperDB
+    #       class Gateway < ROM::Gateway
+    #         def initialize(options)
+    #         end
+    #       end
+    #     end
     #
-    # @overload setup(gateway)
-    #   @param [Gateway] gateway
+    #     ROM.register_adapter(:super_db, SuperDB)
     #
-    # @return [Gateway] a specific gateway subclass
+    #     Gateway.setup(:super_db, some: 'options')
+    #     # SuperDB::Gateway.new(some: 'options') is called
+    #
+    #   @param [Symbol] type Registered gateway identifier
+    #   @param [Array] args Additional gateway options
     #
-    # @example
-    #   module SuperDB
-    #     class Gateway < ROM::Gateway
-    #       def initialize(options)
+    # @overload setup(gateway)
+    #   Set up a gateway instance
+    #
+    #   @example
+    #     module SuperDB
+    #       class Gateway < ROM::Gateway
+    #         def initialize(options)
+    #         end
     #       end
     #     end
-    #   end
     #
-    #   ROM.register_adapter(:super_db, SuperDB)
+    #     ROM.register_adapter(:super_db, SuperDB)
+    #
+    #     Gateway.setup(SuperDB::Gateway.new(some: 'options'))
     #
-    #   Gateway.setup(:super_db, some: 'options')
-    #   # SuperDB::Gateway.new(some: 'options') is called
+    #   @param [Gateway] gateway
     #
-    #   # or alternatively
-    #   super_db = Gateway.setup(SuperDB::Gateway.new(some: 'options'))
-    #   Gateway.setup(super_db)
+    # @return [Gateway] a specific gateway subclass
     #
     # @api public
     def self.setup(gateway_or_scheme, *args)
@@ -76,7 +88,7 @@ module ROM
 
     # Get gateway subclass for a specific adapter
     #
-    # @param [Symbol] type adapter identifier
+    # @param [Symbol] type Adapter identifier
     #
     # @return [Class]
     #
@@ -109,6 +121,10 @@ module ROM
 
     # A generic interface for setting up a logger
     #
+    # This is not a required interface, it's a no-op by default
+    #
+    # @abstract
+    #
     # @api public
     def use_logger(*)
       # noop
@@ -116,6 +132,11 @@ module ROM
 
     # A generic interface for returning default logger
     #
+    # Adapters should implement this method as handling loggers is different
+    # across adapters. This is a no-op by default and returns nil.
+    #
+    # @return [NilClass]
+    #
     # @api public
     def logger
       # noop
@@ -123,8 +144,10 @@ module ROM
 
     # 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
+    # This simply returns back the class by default
+    #
+    # @param [Class] klass The command class
+    # @param [Object] _dataset The dataset that will be used with this command class
     #
     # @return [Class]
     #
@@ -137,7 +160,7 @@ module ROM
     #
     # Every gateway that supports schema inference should implement this method
     #
-    # @return [Array] array with datasets and their names
+    # @return [Array] An array with dataset names
     #
     # @api private
     def schema
@@ -163,6 +186,8 @@ module ROM
       transaction_runner(opts).run(opts, &block)
     end
 
+    private
+
     # @api private
     def transaction_runner(_)
       Transaction::NoOp

data/lib/rom/relation.rb

@@ -18,18 +18,23 @@ module ROM
   # Base relation class
   #
   # Relation is a proxy for the dataset object provided by the gateway. It
-  # forwards every method to the dataset, which is why the "native" interface of
+  # can forward methods to the dataset, which is why the "native" interface of
   # the underlying gateway is available in the relation. This interface,
   # however, is considered private and should not be used outside of the
   # relation instance.
   #
-  # ROM builds sub-classes of this class for every relation defined in the
-  # environment for easy inspection and extensibility - every gateway can
-  # provide extensions for those sub-classes but there is always a vanilla
-  # relation instance stored in the schema registry.
+  # Individual adapters sets up their relation classes and provide different APIs
+  # depending on their persistence backend.
+  #
+  # Vanilla Relation class doesn't have APIs that are specific to ROM container setup.
+  # When adapter Relation class inherits from this class, these APIs are added automatically,
+  # so that they can be registered within a container.
+  #
+  # @see ROM::Relation::ClassInterface
   #
   # @api public
   class Relation
+    # Default no-op output schema which is called in `Relation#each`
     NOOP_OUTPUT_SCHEMA = -> tuple { tuple }.freeze
 
     extend Initializer
@@ -71,6 +76,15 @@ module ROM
 
     # Return schema attribute
     #
+    # @example accessing canonical attribute
+    #   users[:id]
+    #   # => #<ROM::SQL::Attribute[Integer] primary_key=true name=:id source=ROM::Relation::Name(users)>
+    #
+    # @example accessing joined attribute
+    #   tasks_with_users = tasks.join(users).select_append(tasks[:title])
+    #   tasks_with_users[:title, :tasks]
+    #   # => #<ROM::SQL::Attribute[String] primary_key=false name=:title source=ROM::Relation::Name(tasks)>
+    #
     # @return [Schema::Attribute]
     #
     # @api public
@@ -80,7 +94,10 @@ module ROM
 
     # Yields relation tuples
     #
+    # Every tuple is processed through Relation#output_schema, it's a no-op by default
+    #
     # @yield [Hash]
+    #
     # @return [Enumerator] if block is not provided
     #
     # @api public
@@ -91,7 +108,7 @@ module ROM
 
     # Composes with other relations
     #
-    # @param *others [Array<Relation>] The other relation(s) to compose with
+    # @param [Array<Relation>] others The other relation(s) to compose with
     #
     # @return [Relation::Graph]
     #
@@ -147,6 +164,18 @@ module ROM
 
     # Return a new relation with provided dataset and additional options
     #
+    # Use this method whenever you need to use dataset API to get a new dataset
+    # and you want to return a relation back. Typically relation API should be
+    # enough though. If you find yourself using this method, it might be worth
+    # to consider reporting an issue that some dataset functionality is not available
+    # through relation API.
+    #
+    # @example with a new dataset
+    #   users.new(users.dataset.some_method)
+    #
+    # @example with a new dataset and options
+    #   users.new(users.dataset.some_method, other: 'options')
+    #
     # @param [Object] dataset
     # @param [Hash] new_opts Additional options
     #
@@ -157,6 +186,9 @@ module ROM
 
     # Returns a new instance with the same dataset but new options
     #
+    # @example
+    #   users.with(output_schema: -> tuple { .. })
+    #
     # @param new_options [Hash]
     #
     # @return [Relation]
@@ -168,6 +200,8 @@ module ROM
 
     # Return all registered relation schemas
     #
+    # This holds all schemas defined via `view` DSL
+    #
     # @return [Hash<Symbol=>Schema>]
     #
     # @api public
@@ -186,6 +220,10 @@ module ROM
 
     private
 
+    # Hook used by `Pipeline` to get the class that should be used for composition
+    #
+    # @return [Class]
+    #
     # @api private
     def composite_class
       Relation::Composite

data/lib/rom/version.rb

@@ -1,3 +1,3 @@
 module ROM
-  VERSION = '3.0.0.rc1'.freeze
+  VERSION = '3.0.0.rc2'.freeze
 end

data/spec/unit/rom/commands/pre_and_post_processors_spec.rb

@@ -94,7 +94,7 @@ RSpec.describe ROM::Commands::Create[:memory], 'before/after hooks' do
     end
   end
 
-  context 'with curried args' do
+  context 'with one curried arg' do
     subject(:command) do
       Class.new(ROM::Commands::Create[:memory]) do
         result :many
@@ -142,6 +142,54 @@ RSpec.describe ROM::Commands::Create[:memory], 'before/after hooks' do
     end
   end
 
+  context 'with 2 curried args' do
+    subject(:command) do
+      Class.new(ROM::Commands::Create[:memory]) do
+        result :many
+        before :prepare
+        after :finalize
+
+        def execute(tuples)
+          input = tuples.map.with_index { |tuple, idx| tuple.merge(id: idx + 1) }
+          relation.insert(input)
+          input
+        end
+
+        def prepare(tuples, name)
+          tuples.map.with_index { |tuple, idx| tuple.merge(name: "#{name} #{idx + 1}") }
+        end
+
+        def finalize(tuples, *)
+          tuples.map { |tuple| tuple.merge(finalized: true) }
+        end
+      end.build(relation)
+    end
+
+    let(:tuples) do
+      [{ email: 'user-1@test.com' }, { email: 'user-2@test.com' }]
+    end
+
+    let(:relation) do
+      spy(:relation)
+    end
+
+    it 'applies before/after hooks' do
+      insert_tuples = [
+        { id: 1, email: 'user-1@test.com', name: 'User 1' },
+        { id: 2, email: 'user-2@test.com', name: 'User 2' }
+      ]
+
+      result = [
+        { id: 1, email: 'user-1@test.com', name: 'User 1', finalized: true },
+        { id: 2, email: 'user-2@test.com', name: 'User 2', finalized: true }
+      ]
+
+      expect(command.with(tuples, 'User').call).to eql(result)
+
+      expect(relation).to have_received(:insert).with(insert_tuples)
+    end
+  end
+
   context 'with pre-set opts' do
     subject(:command) do
       Class.new(ROM::Commands::Create[:memory]) do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rom
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc1
+  version: 3.0.0.rc2
 platform: ruby
 authors:
 - Piotr Solnica
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-24 00:00:00.000000000 Z
+date: 2017-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby