rom-core 4.0.0.beta3 → 4.0.0.rc1

data/lib/rom/configuration_dsl.rb

@@ -9,7 +9,6 @@ module ROM
     # Relation definition DSL
     #
     # @example
-    #
     #   setup.relation(:users) do
     #     def names
     #       project(:name)
@@ -29,7 +28,6 @@ module ROM
     # Command definition DSL
     #
     # @example
-    #
     #   setup.commands(:users) do
     #     define(:create) do
     #       input NewUserParams

data/lib/rom/constants.rb

@@ -6,7 +6,9 @@ module ROM
 
   AdapterLoadError = Class.new(StandardError)
 
+  # Exception raised when a component is configured with an adapter that's not loaded
   class AdapterNotPresentError < StandardError
+    # @api private
     def initialize(adapter, component)
       super(
         "Failed to find #{component} class for #{adapter} adapter. " \
@@ -28,17 +30,22 @@ module ROM
   MissingAdapterIdentifierError = Class.new(StandardError)
   AttributeAlreadyDefinedError = Class.new(StandardError)
 
+  # Exception raised when a reserved keyword is used as a relation name
   class InvalidRelationName < StandardError
+    # @api private
     def initialize(relation)
       super("Relation name: #{relation} is a protected word, please use another relation name")
     end
   end
 
+  # Exception raised when an element inside a component registry is not found
   class ElementNotFoundError < KeyError
+    # @api private
     def initialize(key, registry)
       super(set_message(key, registry))
     end
 
+    # @api private
     def set_message(key, registry)
       "#{key.inspect} doesn't exist in #{registry.class.name} registry"
     end
@@ -47,18 +54,21 @@ module ROM
   MapperMissingError = Class.new(ElementNotFoundError)
 
   CommandNotFoundError = Class.new(ElementNotFoundError) do
+    # @api private
     def set_message(key, registry)
       "There is no :#{key} command for :#{registry.relation_name} relation"
     end
   end
 
   MissingSchemaClassError = Class.new(StandardError) do
+    # @api private
     def initialize(klass)
       super("#{klass.inspect} relation is missing schema_class")
     end
   end
 
   MissingSchemaError = Class.new(StandardError) do
+    # @api private
     def initialize(klass)
       super("#{klass.inspect} relation is missing schema definition")
     end

data/lib/rom/container.rb

@@ -110,21 +110,37 @@ module ROM
       end
     end
 
+    # Return registered gateways
+    #
+    # @return [Hash<Symbol=>Gateway>]
+    #
     # @api public
     def gateways
       self[:gateways]
     end
 
+    # Return mapper registry for all relations
+    #
+    # @return [Hash<Symbol=>MapperRegistry]
+    #
     # @api public
     def mappers
       self[:mappers]
     end
 
+    # Return relation registry
+    #
+    # @return [RelationRegistry]
+    #
     # @api public
     def relations
       self[:relations]
     end
 
+    # Return command registry
+    #
+    # @return [Hash<Symbol=>CommandRegistry]
+    #
     # @api public
     def commands
       self[:commands]

data/lib/rom/create_container.rb

@@ -4,15 +4,19 @@ require 'rom/setup'
 require 'rom/setup/finalize'
 
 module ROM
+  # @api private
   class CreateContainer
+    # @api private
     attr_reader :container
 
+    # @api private
     def initialize(environment, setup)
       @container = finalize(environment, setup)
     end
 
     private
 
+    # @api private
     def finalize(environment, setup)
       environment.configure do |config|
         environment.gateways.each_key do |key|
@@ -35,7 +39,9 @@ module ROM
     end
   end
 
+  # @api private
   class InlineCreateContainer < CreateContainer
+    # @api private
     def initialize(*args, &block)
       case args.first
       when Configuration
@@ -54,6 +60,7 @@ module ROM
     end
   end
 
+  # @api private
   def self.container(*args, &block)
     InlineCreateContainer.new(*args, &block).container
   end

data/lib/rom/environment.rb

@@ -4,13 +4,13 @@ require 'rom/gateway'
 module ROM
   # Core gateway configuration interface
   #
-  # @api public
+  # @api private
   class Environment
     include Configurable
 
     attr_reader :gateways, :gateways_map
 
-    # @api public
+    # @api private
     def initialize(*args)
       @gateways = {}
       @gateways_map = {}
@@ -20,6 +20,7 @@ module ROM
 
     private
 
+    # @api private
     def configure_gateways(*args)
       normalized_gateway_args = normalize_gateway_args(*args)
       normalized_gateways = normalize_gateways(normalized_gateway_args)

data/lib/rom/gateway.rb

@@ -16,6 +16,20 @@ module ROM
     extend Dry::Core::ClassAttributes
     extend Notifications::Listener
 
+    # @!method self.adapter
+    #  Get or set gateway's adapter identifier
+    #
+    #  @overload adapter
+    #    Return adapter identifier
+    #    @return [Symbol]
+    #
+    #  @overload gateway(adapter)
+    #    @example
+    #      class MyGateway < ROM::Gateway
+    #        adapter :my_adapter
+    #      end
+    #
+    #    @param [Symbol] adapter The adapter identifier
     defines :adapter
 
     # @!attribute [r] connection
@@ -154,7 +168,8 @@ module ROM
     # Runs a block inside a transaction. The underlying transaction engine
     # is adapter-specific
     #
-    # @param [Hash] Transaction options
+    # @param [Hash] opts Transaction options
+    #
     # @return The result of yielding the block or +nil+ if
     #         the transaction was rolled back
     #

data/lib/rom/global.rb

@@ -37,7 +37,7 @@ module ROM
     #     register :publisher, Plugin::Publisher, type: :command
     #   end
     #
-    # @example
+    # @api public
     def plugins(*args, &block)
       PluginDSL.new(plugin_registry, *args, &block)
     end

data/lib/rom/global/plugin_dsl.rb

@@ -38,7 +38,9 @@ module ROM
 
       # Register plugins for a specific adapter
       #
-      # @param [Symbol] adapter type
+      # @param [Symbol] type The adapter identifier
+      #
+      # @api public
       def adapter(type, &block)
         self.class.new(registry, adapter: type, &block)
       end

data/lib/rom/initializer.rb

@@ -1,29 +1,28 @@
 require 'dry-initializer'
 
 module ROM
-
   # @api private
   module Initializer
     # @api private
     module DefineWithHook
+      # @api private
       def param(*)
-        super
-
-        __define_with__
+        super.tap { __define_with__ }
       end
 
+      # @api private
       def option(*)
-        super
-
-        __define_with__ unless method_defined?(:with)
+        super.tap do
+          __define_with__ unless method_defined?(:with)
+        end
       end
 
+      # @api private
       def __define_with__
-        seq_names = __initializer_mixin__.
-                      instance_method(:__initialize__).
-                      parameters.
-                      select { |type, _| type == :req }.
-                      map { |_, name| name }.
+        seq_names = dry_initializer.
+                      definitions.
+                      reject { |_, d| d.option }.
+                      keys.
                       join(', ')
 
         seq_names << ', ' unless seq_names.empty?
@@ -57,7 +56,20 @@ module ROM
       #
       # @api public
       def options
-        @__options__
+        @__options__ ||= self.class.dry_initializer.definitions.values.each_with_object({}) do |item, obj|
+          obj[item.target] = instance_variable_get(item.ivar)
+        end
+      end
+
+      define_method(:class, Kernel.instance_method(:class))
+      define_method(:instance_variable_get, Kernel.instance_method(:instance_variable_get))
+
+      # This makes sure we memoize options before an object becomes frozen
+      #
+      # @api public
+      def freeze
+        options
+        super
       end
     end
   end

data/lib/rom/mapper_registry.rb

@@ -5,11 +5,14 @@ require 'rom/mapper_compiler'
 module ROM
   # @private
   class MapperRegistry < Registry
+    # @api private
     def self.element_not_found_error
       MapperMissingError
     end
 
-    option :compiler, default: -> { MapperCompiler.new }
+    # @!attribute [r] compiler
+    #   @return [MapperCompiler] A mapper compiler instance
+    option :compiler, default: -> { MapperCompiler.new(cache: cache) }
 
     # @see Registry
     # @api public

data/lib/rom/memory/dataset.rb

@@ -4,11 +4,17 @@ module ROM
   module Memory
     # In-memory dataset
     #
+    # This class can be used as a base class for other adapters.
+    #
     # @api public
     class Dataset
       include ArrayDataset
 
-      # Join two datasets
+      # Join with other datasets
+      #
+      # @param [Array<Dataset>] args A list of dataset to join with
+      #
+      # @return [Dataset]
       #
       # @api public
       def join(*args)
@@ -28,9 +34,14 @@ module ROM
 
       # Restrict a dataset
       #
+      # @param [Hash] criteria A hash with conditions
+      #
+      # @return [Dataset]
+      #
       # @api public
       def restrict(criteria = nil)
         return find_all { |tuple| yield(tuple) } unless criteria
+
         find_all do |tuple|
           criteria.all? do |k, v|
             case v
@@ -44,6 +55,10 @@ module ROM
 
       # Project a dataset
       #
+      # @param [Array<Symbol>] names A list of attribute names
+      #
+      # @return [Dataset]
+      #
       # @api public
       def project(*names)
         map { |tuple| tuple.reject { |key| !names.include?(key) } }
@@ -51,12 +66,14 @@ module ROM
 
       # Sort a dataset
       #
-      # @param [Array<Symbol>] names
+      # @param [Array<Symbol>] fields
       #   Names of fields to order tuples by
       #
       # @option [Boolean] :nils_first (false)
       #   Whether `nil` values should be placed before others
       #
+      # @return [Dataset]
+      #
       # @api public
       def order(*fields)
         nils_first = fields.pop[:nils_first] if fields.last.is_a?(Hash)
@@ -70,7 +87,11 @@ module ROM
 
       # Insert tuple into a dataset
       #
+      # @param [Hash] tuple A new tuple for insertion
+      #
       # @api public
+      #
+      # @return [Dataset]
       def insert(tuple)
         data << tuple
         self
@@ -79,6 +100,10 @@ module ROM
 
       # Delete tuples from a dataset
       #
+      # @param [Hash] tuple A new tuple for deletion
+      #
+      # @return [Dataset]
+      #
       # @api public
       def delete(tuple)
         data.delete(tuple)
@@ -88,6 +113,8 @@ module ROM
       private
 
       # Compares two values, that are either comparable, or can be nils
+      #
+      # @api private
       def __compare__(a, b, nils_first)
         return a <=> b unless a.nil? ^ b.nil?
         (nils_first ^ b.nil?) ? -1 : 1

data/lib/rom/memory/schema.rb

@@ -3,6 +3,9 @@ require 'rom/memory/associations'
 
 module ROM
   module Memory
+    # Specialized schema for memory adapter
+    #
+    # @api public
     class Schema < ROM::Schema
       # @see Schema#call
       # @api public
@@ -10,6 +13,10 @@ module ROM
         relation.new(relation.dataset.project(*map(&:name)), schema: self)
       end
 
+      # Internal hook used during setup process
+      #
+      # @see Schema#finalize_associations!
+      #
       # @api private
       def finalize_associations!(relations:)
         super do

data/lib/rom/plugin_base.rb

@@ -35,7 +35,7 @@ module ROM
 
     # Apply this plugin to the provided class
     #
-    # @param [Mixed] base
+    # @param [Mixed] _base
     #
     # @api private
     def apply_to(_base)

data/lib/rom/plugin_registry.rb

@@ -137,7 +137,7 @@ module ROM
     #
     # @param [Symbol] name The name of the environment plugin
     #
-    # @raises [UnknownPluginError] if no plugin is found with the given name
+    # @raise [UnknownPluginError] if no plugin is found with the given name
     #
     # @api public
     def fetch(name)
@@ -184,7 +184,7 @@ module ROM
     # @param [Symbol] name The name of the plugin
     # @param [Symbol] adapter_name (:default) The name of the adapter used
     #
-    # @raises [UnknownPluginError] if no plugin is found with the given name
+    # @raise [UnknownPluginError] if no plugin is found with the given name
     #
     # @api public
     def fetch(name, adapter_name = :default)