rom 5.4.1 → 6.0.0.alpha1

data/lib/rom/repository/class_interface.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "dry/core/cache"
+
+require "rom/repository/relation_reader"
+
+module ROM
+  class Repository
+    # Class-level APIs for repositories
+    #
+    # @api public
+    module ClassInterface
+      # Create a root-repository class and set its root relation
+      #
+      # @example
+      #   # where :users is the relation name in your rom container
+      #   class UserRepo < ROM::Repository[:users]
+      #   end
+      #
+      # @param name [Symbol] The relation `register_as` value
+      #
+      # @return [Class] descendant of ROM::Repository::Root
+      #
+      # @api public
+      def [](name)
+        fetch_or_store(name) do
+          klass = Class.new(self < Repository::Root ? self : Repository::Root)
+          klass.root(name)
+          klass
+        end
+      end
+
+      # Initialize a new repository object, establishing configured relation proxies from
+      # the passed container
+      #
+      # @overload new(container, **options)
+      #   Initialize with container as leading parameter
+      #
+      #   @param [ROM::Container] container Finalized rom container
+      #
+      #   @param [Hash] options Repository options
+      #   @option options [Module] :struct_namespace Custom struct namespace
+      #   @option options [Boolean] :auto_struct Enable/Disable auto-struct mapping
+      #
+      # @overload new(**options)
+      #   Inititalize with container as option
+      #
+      #   @param [Hash] options Repository options
+      #   @option options [ROM::Container] :container Finalized rom container
+      #   @option options [Module] :struct_namespace Custom struct namespace
+      #   @option options [Boolean] :auto_struct Enable/Disable auto-struct mapping
+      #
+      # @api public
+      def new(container = nil, **options)
+        container ||= options.fetch(:container)
+
+        unless relation_reader
+          relation_reader(RelationReader.new(self, container.relation_ids))
+          include(relation_reader)
+        end
+
+        super(**options, container: container)
+      end
+
+      # Inherits configured relations and commands
+      #
+      # @api private
+      def inherited(klass)
+        super
+
+        return if equal?(Repository)
+
+        klass.extend(::Dry::Core::Cache)
+        klass.commands(*commands)
+      end
+
+      # Defines command methods on a root repository
+      #
+      # @example
+      #   class UserRepo < ROM::Repository[:users]
+      #     commands :create, update: :by_pk, delete: :by_pk
+      #   end
+      #
+      #   # with custom command plugin
+      #   class UserRepo < ROM::Repository[:users]
+      #     commands :create, use: :my_command_plugin
+      #   end
+      #
+      #   # with custom mapper
+      #   class UserRepo < ROM::Repository[:users]
+      #     commands :create, mapper: :my_custom_mapper
+      #   end
+      #
+      # @param [Array<Symbol>] names A list of command names
+      # @option :mapper [Symbol] An optional mapper identifier
+      # @option :use [Symbol] An optional command plugin identifier
+      #
+      # @return [Array<Symbol>] A list of defined command names
+      #
+      # @api public
+      def commands(*names, mapper: nil, use: nil, plugins_options: EMPTY_HASH, **opts)
+        if names.any? || opts.any?
+          @commands = names + opts.to_a
+
+          @commands.each do |spec|
+            type, *view = Array(spec).flatten
+
+            if view.empty?
+              define_command_method(type, mapper: mapper, use: use,
+                                          plugins_options: plugins_options)
+            else
+              define_restricted_command_method(type, view, mapper: mapper, use: use,
+                                                           plugins_options: plugins_options)
+            end
+          end
+        else
+          @commands ||= []
+        end
+      end
+
+      # @api public
+      def use(plugin, **options)
+        ROM.plugins[:repository].fetch(plugin).apply_to(self, **options)
+      end
+
+      private
+
+      # @api private
+      def define_command_method(type, **opts)
+        define_method(type) do |*input|
+          if input.size == 1 && input[0].respond_to?(:commit)
+            input[0].commit
+          else
+            root.command(type, **opts).call(*input)
+          end
+        end
+      end
+
+      # @api private
+      def define_restricted_command_method(type, views, **opts)
+        views.each do |view_name|
+          meth_name = views.size > 1 ? :"#{type}_#{view_name}" : type
+
+          define_method(meth_name) do |*args|
+            arity = root.__send__(view_name).arity
+
+            view_args = args[0..arity - 1]
+            input = args[arity..args.size - 1]
+
+            changeset = input.first
+
+            if changeset.respond_to?(:commit)
+              changeset.commit
+            else
+              root.public_send(view_name, *view_args).command(type, **opts).(*input)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/repository/relation_reader.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ROM
+  class Repository
+    # @api private
+    class RelationReader < Module
+      # @api private
+      attr_reader :klass
+
+      # @api private
+      attr_reader :relations
+
+      module InstanceMethods
+        # @api private
+        def set_relation(name)
+          container
+            .relations[name]
+            .with(auto_struct: auto_struct)
+            .struct_namespace(struct_namespace)
+        end
+      end
+
+      # @api private
+      def initialize(klass, relations)
+        @klass = klass
+        @relations = relations
+        define_readers!
+      end
+
+      # @api private
+      def included(klass)
+        super
+        klass.include(InstanceMethods)
+      end
+
+      private
+
+      # @api private
+      def define_readers!
+        relations.each do |name|
+          define_method(name) do
+            @relations[name] ||= set_relation(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/repository/root.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "dry/core/class_attributes"
+
+module ROM
+  class Repository
+    # A specialized repository type dedicated to work with a root relation
+    #
+    # This repository type builds commands and aggregates for its root relation
+    #
+    # @example
+    #   class UserRepo < ROM::Repository[:users]
+    #     commands :create, update: :by_pk, delete: :by_pk
+    #   end
+    #
+    #   rom = ROM.setup(:sql, 'sqlite::memory') do |conf|
+    #     conf.default.create_table(:users) do
+    #       primary_key :id
+    #       column :name, String
+    #     end
+    #   end
+    #
+    #   user_repo = UserRepo.new(rom)
+    #
+    #   user = user_repo.create(name: "Jane")
+    #
+    #   user_repo.update(user.id, name: "Jane Doe")
+    #
+    #   user_repo.delete(user.id)
+    #
+    # @api public
+    class Root < Repository
+      # @!method self.root
+      #   Get or set repository root relation identifier
+      #
+      #   This method is automatically used when you define a class using
+      #   MyRepo[:rel_identifier] shortcut
+      #
+      #   @overload root
+      #     Return root relation identifier
+      #     @return [Symbol]
+      #
+      #   @overload root(identifier)
+      #     Set root relation identifier
+      #     @return [Symbol]
+      defines :root
+
+      # @!attribute [r] root
+      #   @return [Relation] The root relation
+      attr_reader :root
+
+      # Sets descendant root relation
+      #
+      # @api private
+      def self.inherited(klass)
+        super
+        klass.root(root)
+      end
+
+      # @see Repository#initialize
+      def initialize(*)
+        super
+        @root = set_relation(self.class.root)
+      end
+      ruby2_keywords(:initialize) if respond_to?(:ruby2_keywords, true)
+
+      # @see ROM::Repository#transaction
+      #
+      # @api public
+      def transaction(gateway: root.gateway, **opts, &block)
+        super
+      end
+    end
+  end
+end

data/lib/rom/repository/session.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "dry/core/equalizer"
+
+module ROM
+  # TODO: finish this in 1.1.0
+  #
+  # @api private
+  class Session
+    include Dry::Equalizer(:queue, :status)
+
+    attr_reader :repo
+
+    attr_reader :queue
+
+    attr_reader :status
+
+    def initialize(repo)
+      @repo = repo
+      @status = :pending
+      initialize_queue!
+    end
+
+    def add(changeset)
+      queue << changeset
+      self
+    end
+
+    def commit!
+      queue.each(&:commit)
+
+      @status = :success
+
+      self
+    rescue StandardError => e
+      @status = :failure
+      raise e
+    ensure
+      initialize_queue!
+    end
+
+    def pending?
+      status.equal?(:pending)
+    end
+
+    def success?
+      status.equal?(:success)
+    end
+
+    def failure?
+      status.equal?(:failure)
+    end
+
+    private
+
+    def initialize_queue!
+      @queue = []
+    end
+  end
+end

data/lib/rom/repository.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "dry/core/cache"
+require "dry/core/class_attributes"
+
+require "rom/initializer"
+require "rom/plugins"
+require "rom/struct"
+require "rom/container"
+require "rom/repository/class_interface"
+require "rom/repository/session"
+
+module ROM
+  # Abstract repository class to inherit from
+  #
+  # A repository provides access to composable relations and commands.
+  # Its job is to provide application-specific data that is already materialized, so that
+  # relations don't leak into your application layer.
+  #
+  # Typically, you're going to work with Repository::Root that is configured to
+  # use a single relation as its root, and compose aggregates and use changesets and commands
+  # against the root relation.
+  #
+  # @example
+  #   rom = ROM.setup(:sql, 'sqlite::memory') do |conf|
+  #     conf.default.create_table(:users) do
+  #       primary_key :id
+  #       column :name, String
+  #     end
+  #
+  #     conf.default.create_table(:tasks) do
+  #       primary_key :id
+  #       column :user_id, Integer
+  #       column :title, String
+  #     end
+  #
+  #     conf.relation(:users) do
+  #       associations do
+  #         has_many :tasks
+  #       end
+  #     end
+  #   end
+  #
+  #   class UserRepo < ROM::Repository[:users]
+  #     def users_with_tasks
+  #       aggregate(:tasks).to_a
+  #     end
+  #   end
+  #
+  #   user_repo = UserRepo.new(rom)
+  #   user_repo.users_with_tasks
+  #
+  # @see Repository::Root
+  #
+  # @api public
+  class Repository
+    extend Dry::Core::Cache
+    extend Dry::Core::ClassAttributes
+
+    extend ClassInterface
+    extend Initializer
+
+    # @!method self.auto_struct
+    #   Get or set auto_struct setting
+    #
+    #   When disabled, rom structs won't be created
+    #
+    #   @overload auto_struct
+    #     Return auto_struct setting value
+    #     @return [TrueClass,FalseClass]
+    #
+    #   @overload auto_struct(value)
+    #     Set auto_struct value
+    #     @return [Class]
+    defines :auto_struct
+
+    auto_struct true
+
+    # @!method self.auto_struct
+    #   Get or set struct namespace
+    defines :struct_namespace
+
+    # @!method self.relation_reader
+    #   Get or set relation reader module
+    #   @return [RelationReader]
+    defines :relation_reader
+
+    struct_namespace ROM::Struct
+
+    # @!attribute [r] container
+    #   @return [ROM::Container] The container used to set up a repo
+    option :container, allow: ROM::Container
+
+    # @!attribute [r] struct_namespace
+    #   @return [Module,Class] The namespace for auto-generated structs
+    option :struct_namespace, default: -> { self.class.struct_namespace }
+
+    # @!attribute [r] auto_struct
+    #   @return [Boolean] The container used to set up a repo
+    option :auto_struct, default: -> { self.class.auto_struct }
+
+    # @!attribute [r] relations
+    #   @return [RelationRegistry] The relation proxy registry used by a repo
+    attr_reader :relations
+
+    # Initializes a new repository object
+    #
+    # @api private
+    def initialize(*)
+      super
+      @relations = {}
+    end
+    ruby2_keywords(:initialize) if respond_to?(:ruby2_keywords, true)
+
+    # Open a database transaction
+    # @option gateway [Symbol] gateway key. For Repository::Root descendants
+    #                                       it's taken from the root relation
+    #
+    # @example commited transaction
+    #   user = transaction do |t|
+    #     create(changeset(name: 'Jane'))
+    #   end
+    #
+    #   user
+    #   # => #<ROM::Struct::User id=1 name="Jane">
+    #
+    # @example with a rollback
+    #   user = transaction do |t|
+    #     changeset(name: 'Jane').commit
+    #     t.rollback!
+    #   end
+    #
+    #   user
+    #   # nil
+    #
+    # @example with automatic savepoints
+    #   user = transaction(auto_savepoint: true) do
+    #     create(changeset(name: 'Jane'))
+    #
+    #     transaction do |t|
+    #       update(changeset(name: 'John'))
+    #       t.rollback!
+    #     end
+    #   end
+    #
+    #   user
+    #   # => #<ROM::Struct::User id=1 name="Jane">
+    #
+    # @api public
+    def transaction(gateway: :default, **opts, &block)
+      container.gateways[gateway].transaction(**opts, &block)
+    end
+
+    # Return a string representation of a repository object
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      %(#<#{self.class} struct_namespace=#{struct_namespace} auto_struct=#{auto_struct}>)
+    end
+
+    # Start a session for multiple changesets
+    #
+    # TODO: this is partly done, needs tweaks in changesets so that we can gather
+    #       command results and return them in a nice way
+    #
+    # @!visibility private
+    #
+    # @api public
+    def session
+      session = Session.new(self)
+      yield(session)
+      transaction { session.commit! }
+    end
+  end
+end
+
+require "rom/repository/root"