rom-core 4.0.0.beta3 → 4.0.0.rc1

data/lib/rom/plugins/command/schema.rb

@@ -1,6 +1,8 @@
 module ROM
   module Plugins
     module Command
+      # Command plugin which sets input processing function via relation schema
+      #
       # @api private
       module Schema
         def self.included(klass)
@@ -10,7 +12,12 @@ module ROM
 
         # @api private
         module ClassInterface
+          # Build a command and set it input to relation's input_schema
+          #
           # @see Command.build
+          #
+          # @return [Command]
+          #
           # @api public
           def build(relation, options = {})
             if options.key?(:input) || !relation.schema?

data/lib/rom/plugins/relation/instrumentation.rb

@@ -24,7 +24,15 @@ module ROM
         defines :mixin
         mixin Module.new
 
+        # Instrumentation extension for relation classes
+        #
+        # @api private
         module ClassInterface
+          # Configure provided methods for instrumentation
+          #
+          # @param [Array<Symbol>] methods A list of method names
+          #
+          # @api public
           def instrument(*methods)
             (methods - Instrumentation.mixin.instance_methods).each do |meth|
               Instrumentation.mixin.send(:define_method, meth) do
@@ -34,6 +42,8 @@ module ROM
           end
         end
 
+        # Execute a block using instrumentation
+        #
         # @api public
         def instrument(&block)
           notifications.instrument(self.class.adapter, name: name.relation, **notification_payload(self), &block)

data/lib/rom/plugins/relation/registry_reader.rb

@@ -1,4 +1,3 @@
-require 'dry/core/cache'
 require 'rom/constants'
 
 module ROM
@@ -10,8 +9,6 @@ module ROM
       #
       # @api public
       class RegistryReader < Module
-        extend Dry::Core::Cache
-
         EMPTY_REGISTRY = RelationRegistry.new(EMPTY_HASH).freeze
 
         # @api private

data/lib/rom/registry.rb

@@ -12,10 +12,15 @@ module ROM
     include Enumerable
     include Dry::Equalizer(:elements)
 
+    # @!attribute [r] elements
+    #   @return [Hash] Internal hash for storing registry objects
     param :elements
 
-    option :cache, reader: true, default: -> { Cache.new }
+    # @!attribute [r] cache
+    #   @return [Cache] local cache instance
+    option :cache, default: -> { Cache.new }
 
+    # @api private
     def self.new(*args)
       case args.size
       when 0
@@ -27,10 +32,12 @@ module ROM
       end
     end
 
+    # @api private
     def self.element_not_found_error
       ElementNotFoundError
     end
 
+    # @api private
     def map(&block)
       new_elements = elements.each_with_object({}) do |(name, element), h|
         h[name] = yield(element)
@@ -38,15 +45,18 @@ module ROM
       self.class.new(new_elements, options)
     end
 
-    def each(&block)
-      return to_enum unless block
+    # @api private
+    def each
+      return to_enum unless block_given?
       elements.each { |element| yield(element) }
     end
 
+    # @api private
     def key?(name)
       !name.nil? && elements.key?(name.to_sym)
     end
 
+    # @api private
     def fetch(key)
       raise ArgumentError.new('key cannot be nil') if key.nil?
 
@@ -58,12 +68,14 @@ module ROM
     end
     alias_method :[], :fetch
 
+    # @api private
     def respond_to_missing?(name, include_private = false)
       elements.key?(name) || super
     end
 
     private
 
+    # @api private
     def method_missing(name, *)
       elements.fetch(name) { super }
     end

data/lib/rom/relation.rb

@@ -30,19 +30,11 @@ module ROM
   #
   # Relation is a proxy for the dataset object provided by the gateway. It
   # 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.
+  # the underlying gateway is available in the relation
   #
   # 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`
@@ -223,8 +215,8 @@ module ROM
     # @return [Enumerator] if block is not provided
     #
     # @api public
-    def each(&block)
-      return to_enum unless block
+    def each
+      return to_enum unless block_given?
 
       if auto_struct?
         mapper.(dataset.map { |tuple| output_schema[tuple] }).each { |struct| yield(struct) }
@@ -267,15 +259,19 @@ module ROM
         when Symbol
           acc << node(arg)
         when Hash
-          acc << arg.reduce(self) do |root, (name, *opts)|
-            root.node(name).combine(*opts)
-          end
+          acc.concat(arg.map { |name, opts| node(name).combine(opts) })
         when Array
           acc.concat(arg.map { |opts| nodes(opts) }.reduce(:concat))
         end
       end
     end
 
+    # Create a graph node for a given association identifier
+    #
+    # @param [Symbol, Relation::Name]
+    #
+    # @return [Relation]
+    #
     # @api public
     def node(name)
       assoc = associations[name]
@@ -283,6 +279,12 @@ module ROM
       other.eager_load(assoc)
     end
 
+    # Return a graph node prepared by the given association
+    #
+    # @param [Association] An association object
+    #
+    # @return [Relation]
+    #
     # @api public
     def eager_load(assoc)
       relation = assoc.prepare(self)
@@ -294,6 +296,12 @@ module ROM
       end
     end
 
+    # Preload other relation via association
+    #
+    # This is used internally when relations are composed
+    #
+    # @return [Relation::Curried]
+    #
     # @api private
     def preload_assoc(assoc, other)
       assoc.preload(self, other)
@@ -304,9 +312,9 @@ module ROM
     # @example
     #   tasks.wrap(:owner)
     #
-    # @param [Hash] options
+    # @param [Array<Symbol>] names A list with association identifiers
     #
-    # @return [Relation]
+    # @return [Wrap]
     #
     # @api public
     def wrap(*names)
@@ -315,6 +323,8 @@ module ROM
 
     # Wrap around other relations
     #
+    # @param [Array<Relation>] others Other relations
+    #
     # @return [Relation::Wrap]
     #
     # @api public
@@ -322,7 +332,7 @@ module ROM
       wrap_class.new(self, others)
     end
 
-    # Loads relation
+    # Loads a relation
     #
     # @return [Relation::Loaded]
     #
@@ -408,16 +418,17 @@ module ROM
     end
 
     undef_method :with
+
     # Returns a new instance with the same dataset but new options
     #
     # @example
     #   users.with(output_schema: -> tuple { .. })
     #
-    # @param new_options [Hash]
+    # @param [Hash] opts New options
     #
     # @return [Relation]
     #
-    # @api private
+    # @api public
     def with(opts)
       new_options =
         if opts.key?(:meta)
@@ -523,7 +534,7 @@ module ROM
     #
     # @api public
     def map_to(klass, **opts)
-      with(opts.merge(meta: { model: klass }))
+      with(opts.merge(auto_struct: true, meta: { model: klass }))
     end
 
     # Return a new relation with an aliased name
@@ -531,9 +542,9 @@ module ROM
     # @example
     #   users.as(:people)
     #
-    # @param [Class] klass Your custom model class
+    # @param [Symbol] aliaz Aliased name
     #
-    # @return [Relation::Composite]
+    # @return [Relation]
     #
     # @api public
     def as(aliaz)
@@ -586,7 +597,7 @@ module ROM
 
     # Return a new relation configured with the provided struct namespace
     #
-    # @param [Module] namespace
+    # @param [Module] ns Custom namespace module for auto-structs
     #
     # @return [Relation]
     #
@@ -614,6 +625,10 @@ module ROM
       Relation::Composite
     end
 
+    # Return configured "wrap" relation class used in Relation#wrap
+    #
+    # @return [Class]
+    #
     # @api private
     def wrap_class
       self.class.wrap_class

data/lib/rom/relation/class_interface.rb

@@ -10,6 +10,8 @@ require 'rom/support/notifications'
 
 module ROM
   class Relation
+    # Global class-level API for relation classes
+    #
     # @api public
     module ClassInterface
       extend Notifications::Listener
@@ -78,8 +80,8 @@ module ROM
       #     end
       #   end
       #
-      #   # access schema
-      #   Users.schema
+      #   # access schema from a finalized relation
+      #   users.schema
       #
       # @return [Schema]
       #
@@ -112,6 +114,12 @@ module ROM
         end
       end
 
+      # Assign a schema to a relation class
+      #
+      # @param [Schema] schema
+      #
+      # @return [Schema]
+      #
       # @api private
       def set_schema!(schema)
         @schema = schema
@@ -129,10 +137,10 @@ module ROM
 
       # Define a relation view with a specific schema
       #
-      # Explicit relation views allow relation composition with auto-mapping
-      # in repositories. It's useful for cases like defining custom views
-      # for associations where relations (even from different databases) can
-      # be composed together and automatically mapped in memory to structs.
+      # This method should only be used in cases where a given adapter doesn't
+      # support automatic schema projection at run-time.
+      #
+      # **It's not needed in rom-sql**
       #
       # @overload view(name, schema, &block)
       #   @example View with the canonical schema
@@ -279,6 +287,7 @@ module ROM
           end
       end
 
+      # @api private
       def name
         super || superclass.name
       end

data/lib/rom/relation/combined.rb

@@ -25,7 +25,7 @@ module ROM
 
       # Combine this graph with more nodes
       #
-      # @param [Array<Relation::Lazy>]
+      # @param [Array<Relation>] others A list of relations
       #
       # @return [Graph]
       #
@@ -34,8 +34,13 @@ module ROM
         self.class.new(root, nodes + others)
       end
 
-      # @api public
+      # Combine with other relations
+      #
       # @see Relation#combine
+      #
+      # @return [Combined]
+      #
+      # @api public
       def combine(*args)
         self.class.new(root, nodes + root.combine(*args).nodes)
       end

data/lib/rom/relation/curried.rb

@@ -8,6 +8,14 @@ require 'rom/relation/materializable'
 
 module ROM
   class Relation
+    # Curried relation is a special relation proxy used by auto-curry mechanism.
+    #
+    # When a relation view method is called without all arguments, a curried proxy
+    # is returned that can be fully applied later on.
+    #
+    # Curried relations are typically used for relation composition
+    #
+    # @api public
     class Curried
       extend Initializer
 
@@ -17,10 +25,20 @@ module ROM
 
       undef :map_with
 
+      # @!attribute [r] relation
+      #   @return [Relation] The source relation that is curried
       param :relation
 
+      # @!attribute [r] view
+      #   @return [Symbol] The name of relation's view method
       option :view, type: Types::Strict::Symbol
+
+      # @!attribute [r] arity
+      #   @return [Integer] View's arity
       option :arity, type: Types::Strict::Int
+
+      # @!attribute [r] curry_args
+      #   @return [Array] Arguments that will be passed to curried view
       option :curry_args, default: -> { EMPTY_ARRAY }
 
       # Load relation if args match the arity
@@ -45,6 +63,11 @@ module ROM
       end
       alias_method :[], :call
 
+      # Relations are coercible to an array but a curried relation cannot be coerced
+      # When something tries to do this, an exception will be raised
+      #
+      # @raise ArgumentError
+      #
       # @api public
       def to_a
         raise(

data/lib/rom/relation/graph.rb

@@ -18,8 +18,12 @@ module ROM
 
       include Memoizable
 
+      # @!attribute [r] root
+      #   @return [Relation] The root relation
       param :root
 
+      # @!attribute [r] nodes
+      #   @return [Array<Relation>] An array with relation nodes
       param :nodes
 
       include Dry::Equalizer(:root, :nodes)
@@ -27,23 +31,16 @@ module ROM
       include Pipeline
       include Pipeline::Proxy
 
-      # Root aka parent relation
-      #
-      # @return [Relation]
-      #
-      # @api private
-      attr_reader :root
-
-      # Child relation nodes
-      #
-      # @return [Array<Relation>]
-      #
-      # @api private
-      attr_reader :nodes
-
+      # for compatibility with the pipeline
       alias_method :left, :root
       alias_method :right, :nodes
 
+      # Rebuild a graph with new nodes
+      #
+      # @param [Array<Relation>] nodes
+      #
+      # @return [Graph]
+      #
       # @api public
       def with_nodes(nodes)
         self.class.new(root, nodes)
@@ -58,16 +55,30 @@ module ROM
         true
       end
 
+      # Map graph tuples via custom mappers
+      #
+      # @see Relation#map_with
+      #
+      # @return [Graph]
+      #
       # @api public
       def map_with(*args)
         self.class.new(root.map_with(*args), nodes)
       end
 
+      # Map graph tuples to custom objects
+      #
+      # @see Relation#map_to
+      #
+      # @return [Graph]
+      #
       # @api public
       def map_to(klass)
         self.class.new(root.map_to(klass), nodes)
       end
 
+      # @see Relation#mapper
+      #
       # @api private
       def mapper
         mappers[to_ast]