rom 5.2.6 → 6.0.0.alpha1

data/lib/rom/setup.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+
+require "rom/support/inflector"
+
+require "rom/core"
+require "rom/components/provider"
+
+require "rom/open_struct"
+require "rom/constants"
+require "rom/gateway"
+require "rom/loader"
+
+module ROM
+  # @api public
+  class Setup
+    include ROM::Provider(
+      :gateway,
+      :dataset,
+      :schema,
+      :relation,
+      :association,
+      :mapper,
+      :command,
+      :plugin,
+      type: :component
+    )
+
+    DEFAULT_CLASS_NAMESPACE = "ROM"
+
+    CLASS_NAME_INFERRERS = {
+      relation: -> (name, type:, inflector:, class_namespace:, **) {
+        [
+          class_namespace,
+          inflector.pluralize(inflector.camelize(type)),
+          inflector.camelize(name)
+        ].compact.join("::")
+      },
+      command: -> (name, inflector:, adapter:, command_type:, class_namespace:, **) {
+        [
+          class_namespace,
+          inflector.classify(adapter),
+          "Commands",
+          "#{command_type}[#{inflector.pluralize(inflector.classify(name))}]"
+        ].join("::")
+      }
+    }.freeze
+
+    DEFAULT_CLASS_NAME_INFERRER = -> (name, type:, **opts) {
+      CLASS_NAME_INFERRERS.fetch(type).(name, type: type, **opts)
+    }.freeze
+
+    # Global defaults
+    setting :inflector, default: Inflector, reader: true
+
+    setting :gateways, default: EMPTY_HASH
+
+    setting :class_name_inferrer, default: DEFAULT_CLASS_NAME_INFERRER, reader: true
+
+    setting :class_namespace, default: DEFAULT_CLASS_NAMESPACE, reader: true
+
+    setting :auto_register do
+      setting :root_directory
+      setting :auto_load
+      setting :namespace
+      setting :component_dirs, default: {
+        relations: :relations, mappers: :mappers, commands: :commands
+      }
+      setting :inflector, default: Inflector
+    end
+
+    # Initialize a new configuration
+    #
+    # @return [Configuration]
+    #
+    # @api private
+    def initialize(...)
+      super()
+      configure(...)
+    end
+
+    # @return [Registry::Root] Setup component registry
+    # @api private
+    def registry
+      @registry ||=
+        begin
+          options = registry_options
+          options[:loader] = loader if config.auto_register.auto_load
+
+          super(**options)
+        end
+    end
+
+    # This is called internally when you pass a block to ROM.container
+    #
+    # @api private
+    def configure(*args)
+      # Load config from the arguments passed to the constructor.
+      # This *may* override defaults and it's a feature.
+      infer_config(*args) unless args.empty?
+
+      # Load adapters explicitly here to ensure their plugins are present for later use
+      load_adapters
+
+      # Allow customizations now
+      yield(self, config) if block_given?
+
+      # Register gateway components based on current config
+      register_gateways
+
+      self
+    end
+
+    # Enable auto-registration
+    #
+    # @param [String, Pathname] directory The root path to components
+    # @param [Hash] options
+    # @option options [Boolean,String] :namespace Toggle root namespace
+    # @option options [Boolean] :auto_load Toggle auto-loading via Zeitwerk
+    #
+    # @return [Configuration]
+    #
+    # @api public
+    def auto_register(directory, **options)
+      config.auto_register.update(root_directory: directory, **options)
+      self
+    end
+
+    # @api private
+    def register_constant(type, constant)
+      if config.key?(constant.config.component.type)
+        parent_config = config[constant.config.component.type]
+        const_config = constant.config.component
+
+        const_config.inherit!(parent_config).join!(parent_config)
+
+        # TODO: make this work with all components
+        if const_config.key?(:infer_id_from_class) && const_config.infer_id_from_class
+          const_config.id = const_config.inflector.component_id(constant.name)&.to_sym
+        end
+      end
+
+      components.add(type, constant: constant, config: constant.config.component)
+    end
+
+    # Register relation class(es) explicitly
+    #
+    # @param [Array<Relation>] *klasses One or more relation classes
+    #
+    # @api public
+    def register_relation(*klasses)
+      klasses.each do |klass|
+        register_constant(:relations, klass)
+      end
+
+      components.relations
+    end
+
+    # Register mapper class(es) explicitly
+    #
+    # @param [Array] *klasses One or more mapper classes
+    #
+    # @api public
+    def register_mapper(*klasses)
+      klasses.each do |klass|
+        register_constant(:mappers, klass)
+      end
+
+      components[:mappers]
+    end
+
+    # Register command class(es) explicitly
+    #
+    # @param [Array] *klasses One or more command classes
+    #
+    # @api public
+    def register_command(*klasses)
+      klasses.each do |klass|
+        register_constant(:commands, klass)
+      end
+
+      components.commands
+    end
+
+    # This is called automatically in configure block
+    #
+    # After finalization it is no longer possible to alter the configuration
+    #
+    # @api private
+    def finalize
+      # No more config changes allowed
+      config.freeze
+      yield if block_given?
+      loader.() if config.auto_register.key?(:root_directory)
+      registry
+    end
+
+    # Apply a plugin to the configuration
+    #
+    # @param [Mixed] plugin The plugin identifier, usually a Symbol
+    # @param [Hash] options Plugin options
+    #
+    # @return [Configuration]
+    #
+    # @api public
+    def use(plugin, options = {})
+      case plugin
+      when Array then plugin.each { |p| use(p) }
+      when Hash then plugin.to_a.each { |p| use(*p) }
+      else
+        plugin_registry[:configuration].fetch(plugin).apply_to(self, options)
+      end
+
+      self
+    end
+
+    private
+
+    # @api private
+    def plugin_registry
+      ROM.plugins
+    end
+
+    # This register gateway components based on the configuration
+    #
+    # It is private unlike the rest of register_ methods because
+    # it's called automatically doing configuration phase
+    #
+    # @api private
+    def register_gateways
+      config.gateways.each do |id, gateway_config|
+        base = gateway_config.to_h
+        keys = base.keys - config.gateway.keys
+        args = base[:args] || EMPTY_ARRAY
+        opts = keys.zip(base.values_at(*keys)).to_h
+
+        gateway(id, **base, args: args, opts: opts)
+      end
+    end
+
+    # This infers config using arguments passed to the constructor
+    #
+    # @api private
+    def infer_config(*args)
+      config.gateways = ROM::OpenStruct.new
+
+      gateways_config = args.first.is_a?(Hash) ? args.first : {default: args}
+
+      gateways_config.each do |name, value|
+        args = Array(value)
+
+        adapter, *rest = args
+
+        options =
+          if rest.size > 1 && rest.last.is_a?(Hash)
+            {adapter: adapter, args: rest[0..], **rest.last}
+          else
+            options = rest.first.is_a?(Hash) ? rest.first : {args: rest.flatten(1)}
+            {adapter: adapter, **options}
+          end
+
+        config.gateways[name] = ROM::OpenStruct.new(options)
+      end
+    end
+
+    # @api private
+    def load_adapters
+      config.gateways.map { |key| config.gateways[key] }.map(&:adapter).uniq do |adapter|
+        Gateway.class_from_symbol(adapter)
+      rescue AdapterLoadError
+        # TODO: we probably want to remove this. It's perfectly fine to have an adapter
+        #       defined in another location. Auto-require was done for convenience but
+        #       making it mandatory to have that file seems odd now.
+      end
+    end
+
+    # @api private
+    def plugins
+      config.component.plugins
+    end
+
+    # @api private
+    def loader
+      @loader ||= Loader.new(
+        config.auto_register.root_directory,
+        components: components,
+        **config.auto_register
+      )
+    end
+
+    # @api private
+    def registry_options
+      {config: config}
+    end
+  end
+end

data/lib/rom/struct.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+
+module ROM
+  # Simple data-struct class
+  #
+  # ROM structs are plain data structures loaded by repositories.
+  # They implement Hash protocol which means that they can be used
+  # in places where Hash-like objects are supported.
+  #
+  # Repositories define subclasses of ROM::Struct automatically, they are
+  # defined in the ROM::Struct namespace by default, but you set it up
+  # to use your namespace/module as well.
+  #
+  # Structs are based on dry-struct gem, they include `schema` with detailed information
+  # about attribute types returned from relations, thus can be introspected to build
+  # additional functionality when desired.
+  #
+  # There is a caveat you should know about when working with structs. Struct classes
+  # have names but at the same time they're anonymous, i.e. you can't get the User struct class
+  # with ROM::Struct::User. ROM will create as many struct classes for User as needed,
+  # they all will have the same name and ROM::Struct::User will be the common parent class for
+  # them. Combined with the ability to provide your own namespace for structs this enables to
+  # pre-define the parent class.
+  #
+  # @example accessing relation struct model
+  #   rom = ROM.setup(:sql, 'sqlite::memory') do |conf|
+  #     conf.default.create_table(:users) do
+  #       primary_key :id
+  #       column :name, String
+  #     end
+  #   end
+  #
+  #   class UserRepo < ROM::Repository[:users]
+  #   end
+  #
+  #   user_repo = UserRepo.new(rom)
+  #
+  #   # get auto-generated User struct
+  #   model = user_repo.users.mapper.model
+  #   # => ROM::Struct::User
+  #
+  #   # see struct's schema attributes
+  #
+  #   # model.schema.key(:id)
+  #   # => #<Dry::Types[id: Nominal<Integer meta={primary_key: true, source: :users}>]>
+  #
+  #   model.schema[:name]
+  #   # => #<Dry::Types[name: Sum<Nominal<NilClass> | Nominal<String> meta={source: :users}>]>
+  #
+  # @example passing a namespace with an existing parent class
+  #   module Entities
+  #     class User < ROM::Struct
+  #       def upcased_name
+  #         name.upcase
+  #       end
+  #     end
+  #   end
+  #
+  #   class UserRepo < ROM::Repository[:users]
+  #     struct_namespace Entities
+  #   end
+  #
+  #   user_repo = UserRepo.new(rom)
+  #   user = user_repo.users.by_pk(1).one!
+  #   user.name # => "Jane"
+  #   user.upcased_name # => "JANE"
+  #
+  # @see http://dry-rb.org/gems/dry-struct dry-struct
+  # @see http://dry-rb.org/gems/dry-types dry-types
+  #
+  # @api public
+  class Struct < Dry::Struct
+    MissingAttribute = Class.new(NameError)
+
+    # Return attribute value
+    #
+    # @param [Symbol] name The attribute name
+    #
+    # @api public
+    def fetch(name)
+      __send__(name)
+    end
+
+    # @api private
+    def respond_to_missing?(*)
+      super
+    end
+
+    private
+
+    def method_missing(*)
+      super
+    rescue NameError => e
+      raise MissingAttribute, "#{e.message} (attribute not loaded?)"
+    end
+  end
+end

data/lib/rom/struct_compiler.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "rom/support/inflector"
+require "dry/core/class_builder"
+require "dry/types/compiler"
+
+require "rom/initializer"
+require "rom/types"
+require "rom/cache"
+require "rom/struct"
+require "rom/open_struct"
+require "rom/attribute"
+
+module ROM
+  # @api private
+  class StructCompiler < Dry::Types::Compiler
+    extend Initializer
+
+    param :registry, default: -> { Dry::Types }
+
+    option :cache, default: -> { Cache.new }
+
+    option :inflector, reader: true, default: -> { Inflector }
+
+    # @api private
+    def initialize(*)
+      super
+      @cache = cache.namespaced(:structs)
+    end
+    ruby2_keywords(:initialize) if respond_to?(:ruby2_keywords, true)
+
+    # Build a struct class based on relation header ast
+    #
+    # @api private
+    def call(*args)
+      cache.fetch_or_store(args) do
+        name, header, ns = args
+        attributes = header.map(&method(:visit)).compact
+
+        if attributes.empty?
+          ROM::OpenStruct
+        else
+          build_class(name, ROM::Struct, ns) do |klass|
+            klass.attributes(attributes.to_h)
+          end
+        end
+      end
+    end
+    alias_method :[], :call
+
+    private
+
+    # @api private
+    def visit_relation(node)
+      _, header, meta = node
+      name = meta[:combine_name] || meta[:alias]
+      namespace = meta.fetch(:struct_namespace)
+
+      model = meta[:model] || call(name, header, namespace)
+
+      member =
+        if model < Dry::Struct
+          model
+        else
+          Dry::Types::Nominal.new(model).constructor(&model.method(:new))
+        end
+
+      if meta[:combine_type] == :many
+        [name, Types::Array.of(member)]
+      else
+        [name, member.optional]
+      end
+    end
+
+    # @api private
+    def visit_attribute(node)
+      name, type, meta = node
+
+      [meta[:alias] && !meta[:wrapped] ? meta[:alias] : name, visit(type).meta(meta)]
+    end
+
+    # @api private
+    def visit_constructor(node)
+      definition, * = node
+
+      visit(definition)
+    end
+
+    # @api private
+    def visit_constrained(node)
+      definition, = node
+
+      visit(definition)
+    end
+
+    # @api private
+    def visit_enum(node)
+      type_node, * = node
+      visit(type_node)
+    end
+
+    # @api private
+    def build_class(name, parent, ns, &block)
+      Dry::Core::ClassBuilder
+        .new(name: class_name(name), parent: parent, namespace: ns)
+        .call(&block)
+    end
+
+    # @api private
+    def class_name(name)
+      inflector.classify(name)
+    end
+  end
+end

data/lib/rom/support/configurable.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "rom/constants"
+require "rom/types"
+
+module ROM
+  # Component settings API
+  #
+  # @see https://dry-rb.org/gems/dry-configurable
+  #
+  # @api public
+  module Configurable
+    # @api private
+    def self.included(klass)
+      super
+
+      klass.class_eval do
+        include(Dry::Configurable)
+
+        class << self
+          prepend(Methods)
+          prepend(Methods::DSL)
+        end
+      end
+    end
+
+    # @api private
+    def self.extended(klass)
+      super
+
+      klass.class_eval do
+        extend(Dry::Configurable)
+
+        class << self
+          prepend(Methods)
+          prepend(Methods::DSL)
+        end
+      end
+    end
+
+    # @api private
+    module ConfigMethods
+      include Enumerable
+
+      # @api private
+      def each(&block)
+        values.each(&block)
+      end
+
+      # @api private
+      def inherit!(other)
+        update(inherit(other))
+      end
+
+      # @api private
+      def inherit(other)
+        hash = values.merge(other.to_h.slice(*keys)) { |key, left, right|
+          if _constructors[key].is_a?(Constructors::Inherit)
+            _constructors[key].(left, right)
+          else
+            left.nil? ? right : left
+          end
+        }
+        merge(hash)
+      end
+
+      # @api private
+      def join!(other, direction = :left)
+        update(join(other, direction))
+      end
+
+      # @api private
+      def join(other, direction = :left)
+        hash = values.merge(other.to_h.slice(*keys)) { |key, left, right|
+          if _constructors[key].is_a?(Constructors::Join)
+            _constructors[key].(left, right, direction)
+          else
+            direction == :left ? left : right
+          end
+        }
+        merge(hash)
+      end
+
+      # @api private
+      def merge(other)
+        dup.update(values.merge(other))
+      end
+
+      # @api private
+      def empty?
+        values.compact.empty?
+      end
+
+      # @api private
+      def key?(key)
+        _settings.key?(key)
+      end
+
+      # @api private
+      def keys
+        _settings.keys
+      end
+
+      # @api private
+      def fetch(...)
+        values.fetch(...)
+      end
+
+      # @api private
+      def to_h
+        values
+      end
+      alias_method :to_hash, :to_h
+
+      # @api private
+      def freeze
+        _constructors
+        super
+      end
+
+      # @api private
+      def _constructors
+        @_constructors ||= _settings.map { |setting| [setting.name, setting.constructor] }.to_h
+      end
+    end
+
+    module Constructors
+      Default = ::Struct.new(:name) do
+        def call(*args)
+          return if args.compact.empty?
+
+          block_given? ? yield(*args) : args.first
+        end
+        alias_method :[], :call
+      end
+
+      class Inherit < Default
+        def call(*args)
+          super { |left, right|
+            case left
+            when nil then right
+            when Hash then right.merge(left)
+            when Array then (right.map(&:dup) + left.map(&:dup)).uniq
+            else
+              left
+            end
+          }
+        end
+      end
+
+      class Join < Default
+        def call(*args)
+          super { |left, right, direction|
+            case direction
+            when :left then [right, left]
+            when :right then [left, right]
+            else
+              raise ArgumentError, "+#{direction}+ direction is not supported"
+            end.compact.join(".")
+          }
+        end
+      end
+    end
+
+    # @api public
+    module Methods
+      # @api public
+      def configure(namespace = nil, &block)
+        if namespace
+          super(&nil)
+          block.(config[namespace])
+        else
+          super(&block)
+        end
+        self
+      end
+
+      # @api private
+      module DSL
+        # @api private
+        def setting(name, import: nil, inherit: false, join: false, default: Undefined, **options)
+          if import
+            setting_import(name, import, **options)
+          elsif inherit
+            setting(name, default: default, constructor: Constructors::Inherit.new(name), **options)
+          elsif join
+            setting(name, default: default, constructor: Constructors::Join.new(name), **options)
+          else
+            super(name, default: default, **options)
+          end
+        end
+
+        # @api private
+        def setting_import(name, setting)
+          # TODO: it would be great if this could just be import.with(name: name)
+          settings << setting.class.new(
+            name, input: setting.input, default: setting.default, **setting.options
+          )
+        end
+
+        # @api private
+        def settings
+          _settings
+        end
+      end
+    end
+
+    # TODO: either extend functionality of dry-configurable or don't use it here after all
+    Dry::Configurable::DSL.prepend(Methods::DSL)
+    Dry::Configurable::Config.prepend(ConfigMethods)
+  end
+end