rom 5.4.1 → 6.0.0.alpha1

data/lib/rom/container.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "dry/container"
+
+module ROM
+  # ROM container is an isolated environment with no global state where all
+  # components are registered. Container objects provide access to your
+  # relations, commands and mappers. ROM containers are usually configured and
+  # handled via framework integrations, although it is easy to use them
+  # standalone.
+  #
+  # There are 3 types of container setup:
+  #
+  # * 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
+  # * 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
+  # * 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
+  #
+  # @example in-line setup
+  #   rom = ROM.setup(:sql, 'sqlite::memory') do |config|
+  #     config.default.create_table :users do
+  #       primary_key :id
+  #       column :name, String, null: false
+  #     end
+  #
+  #     config.relation(:users) do
+  #       schema(infer: true)
+  #
+  #       def by_name(name)
+  #         where(name: name)
+  #       end
+  #     end
+  #   end
+  #
+  #   rom.relations[:users].insert(name: "Jane")
+  #
+  #   rom.relations[:users].by_name("Jane").to_a
+  #   # [{:id=>1, :name=>"Jane"}]
+  #
+  # @example multi-step setup with explicit component classes
+  #   config = ROM::Configuration.new(:sql, 'sqlite::memory')
+  #
+  #   config.default.create_table :users do
+  #     primary_key :id
+  #     column :name, String, null: false
+  #   end
+  #
+  #   class Users < ROM::Relation[:sql]
+  #     schema(:users, infer: true)
+  #
+  #     def by_name(name)
+  #       where(name: name)
+  #     end
+  #   end
+  #
+  #   config.register_relation(Users)
+  #
+  #   rom = ROM.setup(config)
+  #
+  #   rom.relations[:users].insert(name: "Jane")
+  #
+  #   rom.relations[:users].by_name("Jane").to_a
+  #   # [{:id=>1, :name=>"Jane"}]
+  #
+  #
+  # @example multi-step setup with auto-registration
+  #   config = ROM::Configuration.new(:sql, 'sqlite::memory')
+  #   config.auto_register('./persistence', namespace: false)
+  #
+  #   config.default.create_table :users do
+  #     primary_key :id
+  #     column :name, String, null: false
+  #   end
+  #
+  #   # ./persistence/relations/users.rb
+  #   class Users < ROM::Relation[:sql]
+  #     schema(infer: true)
+  #
+  #     def by_name(name)
+  #       where(name: name)
+  #     end
+  #   end
+  #
+  #   rom = ROM.setup(config)
+  #
+  #   rom.relations[:users].insert(name: "Jane")
+  #
+  #   rom.relations[:users].by_name("Jane").to_a
+  #   # [{:id=>1, :name=>"Jane"}]
+  #
+  # @api public
+  class Container
+    include Dry::Container::Mixin
+    include Dry::Equalizer(:gateways, :relations, :mappers, :commands)
+
+    # @api private
+    def self.new(configuration)
+      super().tap do |container|
+        container.register(:configuration, memoize: true) do
+          Setup::Configuration.new(
+            configuration: configuration, container: container
+          )
+        end
+      end
+    end
+
+    # Return runtime configuration with component registries
+    #
+    # @return [Setup::Configuration]
+    #
+    # @api public
+    def configuration
+      self[:configuration]
+    end
+
+    # Return registered gateways
+    #
+    # @return [Hash<Symbol=>Gateway>]
+    #
+    # @api public
+    def gateways
+      configuration.gateways
+    end
+
+    # Return relation registry
+    #
+    # @return [RelationRegistry]
+    #
+    # @api public
+    def schemas
+      configuration.schemas
+    end
+
+    # Return relation registry
+    #
+    # @return [RelationRegistry]
+    #
+    # @api public
+    def relations
+      configuration.relations
+    end
+
+    # Return mapper registry for all relations
+    #
+    # @return [Hash<Symbol=>MapperRegistry]
+    #
+    # @api public
+    def mappers
+      configuration.mappers
+    end
+
+    # Return command registry
+    #
+    # @return [Hash<Symbol=>CommandRegistry]
+    #
+    # @api public
+    def commands
+      configuration.commands
+    end
+
+    # Disconnect all gateways
+    #
+    # @example
+    #   rom = ROM.setup(:sql, 'sqlite://my_db.sqlite')
+    #   rom.relations[:users].insert(name: "Jane")
+    #   rom.disconnect
+    #
+    # @return [Hash<Symbol=>Gateway>] a hash with disconnected gateways
+    #
+    # @api public
+    def disconnect
+      gateways.each_value(&:disconnect)
+    end
+  end
+end

data/lib/rom/core.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Global interface
+require_relative "global"
+
+# Global default settings
+require_relative "settings"
+
+# Core components
+require_relative "components/gateway"
+require_relative "components/dataset"
+require_relative "components/schema"
+require_relative "components/relation"
+require_relative "components/view"
+require_relative "components/association"
+require_relative "components/command"
+require_relative "components/mapper"
+
+# Core plugins
+require_relative "plugins"
+
+# Set up ROM
+#
+# @api public
+def ROM(*args, &block)
+  if block
+    ROM.setup(*args, &block)
+  else
+    ROM::Setup.new(*args)
+  end
+end
+
+# Global ROM interface for core setup
+#
+# @api public
+module ROM
+  extend Global
+
+  module_function
+
+  # Global component setup
+  #
+  # @example
+  #   ROM.components do
+  #     register :cache, handler: MyApp::MyCacheHandler
+  #   end
+  #
+  # @api public
+  def components(&block)
+    if defined?(@_components)
+      @_components.instance_eval(&block) if block
+      @_components
+    else
+      require_relative "components"
+      @_components = Components
+      components(&block)
+    end
+  end
+
+  # Global plugin setup
+  #
+  # @example
+  #   ROM.plugins do
+  #     register :publisher, Plugin::Publisher, type: :command
+  #   end
+  #
+  # @api public
+  def plugins(*args, &block)
+    if defined?(@_plugins)
+      @_plugins.dsl(*args, &block) if block
+      @_plugins
+    else
+      require_relative "plugins"
+      @_plugins = Plugins
+      plugins(*args, &block)
+    end
+  end
+
+  # Register core component handlers
+  components do
+    register :gateway, Components::Gateway
+    register :dataset, Components::Dataset
+    register :schema, Components::Schema
+    register :relation, Components::Relation
+    register :view, Components::View
+    register :association, Components::Association
+    register :command, Components::Command
+    register :mapper, Components::Mapper
+  end
+
+  # TODO: this will be automated eventually
+  require_relative "relation"
+  require_relative "schema"
+  require_relative "command"
+  require_relative "mapper"
+  require_relative "transformer"
+
+  configs = {
+    schema: [ROM::Schema],
+    relation: [ROM::Relation],
+    command: [ROM::Command],
+    mapper: [ROM::Mapper, ROM::Transformer]
+  }
+
+  configs.each do |key, items|
+    items.each do |constant|
+      constant.config.component.inherit!(config.component)
+      config[key].inherit!(constant.config.component)
+    end
+  end
+
+  configs.values.flatten(1).each(&:configure).each(&:finalize!)
+
+  # Register core plugins
+  plugins do
+    register :timestamps, ROM::Plugins::Schema::Timestamps, type: :schema
+    register :registry_reader, ROM::Plugins::Relation::RegistryReader, type: :relation
+    register :instrumentation, ROM::Plugins::Relation::Instrumentation, type: :relation
+    register :changeset, ROM::Plugins::Relation::Changeset, type: :relation
+    register :schema, ROM::Plugins::Command::Schema, type: :command
+    register :timestamps, ROM::Plugins::Command::Timestamps, type: :command
+  end
+
+  finalize!
+end

data/lib/rom/data_proxy.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module ROM
+  # Helper module for dataset classes
+  #
+  # It provides a constructor accepting data, header and an optional row_proc.
+  # This module is used internally by EnumerableDataset and ArrayDataset.
+  #
+  # @private
+  module DataProxy
+    NON_FORWARDABLE = %i[
+      each to_a to_ary kind_of? instance_of? is_a?
+    ].freeze
+
+    # Wrapped data array
+    #
+    # @return [Object] Data object for the iterator
+    #
+    # @api private
+    attr_reader :data
+
+    # @return [Proc] tuple processing proc
+    #
+    # @api private
+    attr_reader :row_proc
+
+    # Extends the class with `forward` DSL and Equalizer using `data` attribute
+    #
+    # @see ClassMethods#forward
+    #
+    # @api private
+    def self.included(klass)
+      klass.class_eval do
+        extend ClassMethods
+
+        include Dry::Equalizer(:data)
+
+        option :row_proc, default: -> { self.class.row_proc }
+      end
+    end
+
+    # Iterate over data using row_proc
+    #
+    # @return [Enumerator] if block is not given
+    #
+    # @api private
+    def each
+      return to_enum unless block_given?
+
+      data.each { |tuple| yield(row_proc[tuple]) }
+    end
+
+    module ClassMethods
+      # Default no-op tuple proc
+      #
+      # @return [Proc]
+      #
+      # @api private
+      def row_proc
+        -> tuple { tuple }
+      end
+
+      # Forward provided methods to the underlaying data object
+      #
+      # @example
+      #
+      #   class MyDataset
+      #     include DataProxy
+      #
+      #     forward(:find_all, :map)
+      #   end
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def forward(*methods)
+        # FIXME: we should probably raise if one of the non-forwardable methods
+        #       was provided
+        (methods - NON_FORWARDABLE).each do |method_name|
+          class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{method_name}(*args, &block)
+              response = data.public_send(#{method_name.inspect}, *args, &block)
+
+              if response.equal?(data)
+                self
+              elsif response.is_a?(data.class)
+                self.class.new(response)
+              else
+                response
+              end
+            end
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/rom/enumerable_dataset.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "rom/initializer"
+require "rom/data_proxy"
+
+module ROM
+  # A helper module that adds data-proxy behavior to an enumerable object
+  #
+  # This module is intended to be used by gateways
+  #
+  # Class that includes this module can define `row_proc` class method which
+  # must return a proc-like object which will be used to process each element
+  # in the enumerable
+  #
+  # @example
+  #   class MyDataset
+  #     include ROM::EnumerableDataset
+  #
+  #     def self.row_proc
+  #       -> tuple { tuple.each_with_object({}) { |(k,v), h| h[k.to_sym] = v } }
+  #     end
+  #   end
+  #
+  #   ds = MyDataset.new([{ 'name' => 'Jane' }, [:name])
+  #   ds.to_a # => { :name => 'Jane' }
+  #
+  # @api public
+  module EnumerableDataset
+    extend DataProxy::ClassMethods
+    include Enumerable
+
+    # Coerce a dataset to an array
+    #
+    # @return [Array]
+    #
+    # @api public
+    alias_method :to_ary, :to_a
+
+    # Included hook which extends a class with DataProxy behavior
+    #
+    # This module can also be included into other modules so we apply the
+    # extension only for classes
+    #
+    # @api private
+    def self.included(klass)
+      return unless klass.is_a?(Class)
+
+      klass.class_eval do
+        extend Initializer
+        include DataProxy
+
+        param :data
+      end
+    end
+
+    forward :take
+
+    %i[
+      chunk collect collect_concat drop_while find_all flat_map
+      grep map reject select sort sort_by take_while
+    ].each do |method|
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method}(*args, &block)
+          return to_enum unless block
+          self.class.new(super(*args, &block), **options)
+        end
+      RUBY
+    end
+  end
+end

data/lib/rom/gateway.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "dry/core/class_attributes"
+
+require_relative "support/notifications"
+require_relative "transaction"
+require_relative "components/provider"
+
+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
+    extend Notifications::Listener
+
+    extend ROM::Provider(:plugin, type: :gateway)
+
+    # @!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
+    #        config.component.adapter = :my_adapter
+    #      end
+    #
+    #    @param [Symbol] adapter The adapter identifier
+    defines :adapter
+
+    # @!attribute [r] config
+    #   @return [Configurable::Config] Gateway's configuration identifier
+    attr_reader :config
+
+    # @!attribute [r] connection
+    #   @return [Object] The gateway's connection object (type varies across adapters)
+    attr_reader :connection
+
+    # 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.
+    #
+    #   @example
+    #     module SuperDB
+    #       class Gateway < ROM::Gateway
+    #         def initialize(options)
+    #         end
+    #       end
+    #     end
+    #
+    #     ROM.register_adapter(:super_db, SuperDB)
+    #
+    #     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
+    #
+    # @overload setup(gateway)
+    #   Set up a gateway instance
+    #
+    #   @example
+    #     module SuperDB
+    #       class Gateway < ROM::Gateway
+    #         def initialize(options)
+    #         end
+    #       end
+    #     end
+    #
+    #     ROM.register_adapter(:super_db, SuperDB)
+    #
+    #     Gateway.setup(SuperDB::Gateway.new(some: 'options'))
+    #
+    #   @param [Gateway] gateway
+    #
+    # @return [Gateway] a specific gateway subclass
+    #
+    # @api public
+    #
+    # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
+    def self.setup(gateway_or_scheme, *args)
+      case gateway_or_scheme
+      when Gateway
+        unless args.empty?
+          raise ArgumentError, "Can't accept arguments when passing an instance"
+        end
+
+        gateway_or_scheme
+      when String
+        raise ArgumentError, <<-STRING.gsub(/^ {10}/, "")
+          URIs without an explicit scheme are not supported anymore.
+          See https://github.com/rom-rb/rom/blob/main/CHANGELOG.md
+        STRING
+      when Symbol
+        klass = class_from_symbol(gateway_or_scheme)
+
+        if klass.instance_method(:initialize).arity.zero?
+          klass.new
+        elsif args.size.equal?(1) && args.first.respond_to?(:args)
+          if args.first.respond_to?(:args)
+            setup(gateway_or_scheme, *args.first.args)
+          else
+            klass.new(**config)
+          end
+        elsif args.last.is_a?(Hash)
+          klass.new(*args[0..-2], **args.last)
+        else
+          klass.new(*args)
+        end
+      else
+        gateway_or_scheme
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/PerceivedComplexity
+
+    class << self
+      ruby2_keywords(:setup) if respond_to?(:ruby2_keywords, true)
+    end
+
+    # Get gateway subclass for a specific adapter
+    #
+    # @param [Symbol] type Adapter identifier
+    #
+    # @return [Class]
+    #
+    # @api private
+    def self.class_from_symbol(type)
+      adapter = ROM.adapters.fetch(type) do
+        begin
+          require "rom/#{type}"
+        rescue LoadError
+          raise AdapterLoadError, "Failed to load adapter rom/#{type}"
+        end
+
+        ROM.adapters.fetch(type)
+      end
+
+      adapter.const_get(:Gateway)
+    end
+
+    # Configured gateway name used in the registry
+    #
+    # @return [Symbol]
+    #
+    # @api public
+    def name
+      config.id
+    end
+
+    # Returns the adapter, defined for the class
+    #
+    # @return [Symbol]
+    #
+    # @api public
+    def adapter
+      self.class.adapter || raise(
+        MissingAdapterIdentifierError,
+        "gateway class +#{self}+ is missing the adapter identifier"
+      )
+    end
+
+    # 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
+    end
+
+    # 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
+    end
+
+    # Disconnect is optional and it's a no-op by default
+    #
+    # @api public
+    def disconnect
+      # noop
+    end
+
+    # Runs a block inside a transaction. The underlying transaction engine
+    # is adapter-specific
+    #
+    # @param [Hash] opts Transaction options
+    #
+    # @return The result of yielding the block or +nil+ if
+    #         the transaction was rolled back
+    #
+    # @api public
+    def transaction(**opts, &block)
+      transaction_runner(**opts).run(**opts, &block)
+    end
+
+    # Build a command instance
+    #
+    # @return [Command]
+    #
+    # @api public
+    def command(klass, relation:, **opts)
+      klass.build(relation, **opts)
+    end
+
+    private
+
+    # @api private
+    def transaction_runner(**)
+      Transaction::NoOp
+    end
+  end
+end