rom 5.4.2 → 6.0.0.alpha1

data/lib/rom/changeset/extensions/relation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "rom/relation/graph"
+
+module ROM
+  class Changeset
+    # Namespace for changeset extensions
+    #
+    # @api public
+    module Extensions
+      # Changeset extenions for combined relations
+      #
+      # @api public
+      class Relation::Graph
+        # Build a changeset for a combined relation
+        #
+        # @raise NotImplementedError
+        #
+        # @api public
+        def changeset(*)
+          raise NotImplementedError, "Changeset doesn't support combined relations yet"
+        end
+      end
+    end
+  end
+end

data/lib/rom/changeset/pipe.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "rom/changeset/pipe_registry"
+
+module ROM
+  class Changeset
+    # Composable data transformation pipe used by default in changesets
+    #
+    # @api private
+    class Pipe < Dry::Transformer[PipeRegistry]
+      extend Initializer
+
+      define!(&:identity)
+
+      param :processor, optional: true
+
+      option :use_for_diff, optional: true, default: -> { true }
+      option :diff_processor, default: -> { self[processor] }
+
+      def self.new(*args, **opts)
+        if args.empty?
+          initialize(**opts)
+        else
+          super
+        end
+      end
+
+      def self.initialize(**opts)
+        transformer = allocate
+        transformer.__send__(:initialize, dsl.(transformer), **opts)
+        transformer
+      end
+
+      def self.[](name_or_proc)
+        container[name_or_proc]
+      end
+
+      def [](*args)
+        self.class[*args]
+      end
+
+      def bind(context)
+        if processor.is_a?(Proc)
+          bound_processor = self[-> *args { context.instance_exec(*args, &processor) }]
+          bound_diff_processor = self[-> *args { context.instance_exec(*args, &diff_processor) }]
+
+          new(bound_processor, diff_processor: bound_diff_processor)
+        else
+          self
+        end
+      end
+
+      def compose(other, for_diff: other.is_a?(self.class) ? other.use_for_diff : false)
+        new_proc = processor >> other
+
+        if for_diff
+          diff_proc = diff_processor >> (
+            other.is_a?(self.class) ? other.diff_processor : other
+          )
+
+          new(new_proc, use_for_diff: true, diff_processor: diff_proc)
+        else
+          new(new_proc)
+        end
+      end
+      alias_method :>>, :compose
+
+      def call(data)
+        processor.call(data)
+      end
+
+      def for_diff(data)
+        use_for_diff ? diff_processor.call(data) : data
+      end
+
+      def new(processor, **opts)
+        self.class.new(processor, **options, **opts)
+      end
+    end
+  end
+end

data/lib/rom/changeset/pipe_registry.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "dry/transformer/all"
+require "dry/transformer/registry"
+
+module ROM
+  class Changeset
+    # Dry::Transformer Registry useful for pipe
+    #
+    # @api private
+    module PipeRegistry
+      extend Dry::Transformer::Registry
+
+      import Dry::Transformer::Coercions
+      import Dry::Transformer::HashTransformations
+
+      def self.add_timestamps(data)
+        now = Time.now
+        Hash(created_at: now, updated_at: now).merge(data)
+      end
+
+      def self.touch(data)
+        Hash(updated_at: Time.now).merge(data)
+      end
+    end
+  end
+end

data/lib/rom/changeset/stateful.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "rom/changeset/pipe"
+
+module ROM
+  class Changeset
+    # Stateful changesets carry data and can transform it into
+    # a different structure compatible with a persistence backend
+    #
+    # @abstract
+    class Stateful < Changeset
+      # Default no-op pipe
+      EMPTY_PIPE = Pipe.new(use_for_diff: false).freeze
+
+      # @!attribute [r] __data__
+      #   @return [Hash] The relation data
+      #   @api private
+      option :__data__, optional: true
+
+      # @!attribute [r] pipe
+      #   @return [Changeset::Pipe] data transformation pipe
+      #   @api private
+      option :pipe, reader: false, optional: true
+
+      # Define a changeset mapping
+      #
+      # Subsequent mapping definitions will be composed together
+      # and applied in the order they way defined
+      #
+      # @example Transformation DSL
+      #   class NewUser < ROM::Changeset::Create
+      #     map do
+      #       unwrap :address, prefix: true
+      #     end
+      #   end
+      #
+      # @example Using custom block
+      #   class NewUser < ROM::Changeset::Create
+      #     map do |tuple|
+      #       tuple.merge(created_at: Time.now)
+      #     end
+      #   end
+      #
+      # @example Multiple mappings (executed in the order of definition)
+      #   class NewUser < ROM::Changeset::Create
+      #     map do
+      #       unwrap :address, prefix: true
+      #     end
+      #
+      #     map do |tuple|
+      #       tuple.merge(created_at: Time.now)
+      #     end
+      #   end
+      #
+      # @return [Array<Pipe>, Dry::Transformer::Function>]
+      #
+      # @see https://github.com/dry-rb/dry-transformer
+      #
+      # @api public
+      def self.map(**options, &block)
+        if block.parameters.empty?
+          pipes << Class.new(Pipe).define!(&block).new(**options)
+        else
+          pipes << Pipe.new(block, **options)
+        end
+      end
+
+      # Define a changeset mapping excluded from diffs
+      #
+      # @see Changeset::Stateful.map
+      # @see Changeset::Stateful#extend
+      #
+      # @return [Array<Pipe>, Dry::Transformer::Function>]
+      #
+      # @api public
+      def self.extend(*, &block)
+        if block
+          map(use_for_diff: false, &block)
+        else
+          super
+        end
+      end
+
+      # Build default pipe object
+      #
+      # This can be overridden in a custom changeset subclass
+      #
+      # @return [Pipe]
+      def self.default_pipe(context)
+        pipes.empty? ? EMPTY_PIPE : pipes.map { |p| p.bind(context) }.reduce(:>>)
+      end
+
+      # @api private
+      def self.inherited(klass)
+        return if klass == ROM::Changeset
+
+        super
+        klass.instance_variable_set(:@__pipes__, pipes.dup)
+      end
+
+      # @api private
+      def self.pipes
+        @__pipes__
+      end
+      @__pipes__ = EMPTY_ARRAY
+
+      # Pipe changeset's data using custom steps define on the pipe
+      #
+      # @overload map(*steps)
+      #   Apply mapping using built-in transformations
+      #
+      #   @example
+      #     changeset.map(:add_timestamps)
+      #
+      #   @param [Array<Symbol>] steps A list of mapping steps
+      #
+      # @overload map(&block)
+      #   Apply mapping using a custom block
+      #
+      #   @example
+      #     changeset.map { |tuple| tuple.merge(created_at: Time.now) }
+      #
+      # @overload map(*steps, &block)
+      #   Apply mapping using built-in transformations and a custom block
+      #
+      #   @example
+      #     changeset.map(:add_timestamps) { |tuple| tuple.merge(status: 'published') }
+      #
+      #   @param [Array<Symbol>] steps A list of mapping steps
+      #
+      # @return [Changeset]
+      #
+      # @api public
+      def map(*steps, &block)
+        extend(*steps, for_diff: true, &block)
+      end
+
+      # Pipe changeset's data using custom steps define on the pipe.
+      # You should use #map instead except updating timestamp fields.
+      # Calling changeset.extend builds a pipe that excludes certain
+      # steps for generating the diff. Currently the only place where
+      # it is used is update changesets with the `:touch` step, i.e.
+      # `changeset.extend(:touch).diff` will exclude `:updated_at`
+      # from the diff.
+      #
+      # @see Changeset::Stateful#map
+      #
+      # @return [Changeset]
+      #
+      # @api public
+      def extend(*steps, **options, &block)
+        if block
+          if steps.empty?
+            with(pipe: pipe.compose(Pipe.new(block).bind(self), **options))
+          else
+            extend(*steps, **options).extend(**options, &block)
+          end
+        else
+          with(pipe: steps.reduce(pipe.with(**options)) { |a, e| a.compose(pipe[e], **options) })
+        end
+      end
+
+      # Return changeset with data
+      #
+      # @param [Hash] data
+      #
+      # @return [Changeset]
+      #
+      # @api public
+      def data(data)
+        with(__data__: data)
+      end
+
+      # Coerce changeset to a hash
+      #
+      # This will send the data through the pipe
+      #
+      # @return [Hash]
+      #
+      # @api public
+      def to_h
+        pipe.call(__data__)
+      end
+      alias_method :to_hash, :to_h
+
+      # Coerce changeset to an array
+      #
+      # This will send the data through the pipe
+      #
+      # @return [Array]
+      #
+      # @api public
+      def to_a
+        result == :one ? [to_h] : __data__.map { |element| pipe.call(element) }
+      end
+      alias_method :to_ary, :to_a
+
+      # Commit stateful changeset
+      #
+      # @see Changeset#commit
+      #
+      # @api public
+      def commit
+        command.call(self)
+      end
+
+      # Associate a changeset with another changeset or hash-like object
+      #
+      # @example with another changeset
+      #   new_user = users.changeset(name: 'Jane')
+      #   new_task = users.changeset(:tasks, title: 'A task')
+      #
+      #   new_task.associate(new_user, :users)
+      #
+      # @example with a hash-like object
+      #   user = users.users.by_pk(1).one
+      #   new_task = users.changeset(:tasks, title: 'A task')
+      #
+      #   new_task.associate(user, :users)
+      #
+      # @param [#to_hash, Changeset] other Other changeset or hash-like object
+      # @param [Symbol] name The association identifier from schema
+      #
+      # @api public
+      def associate(other, name = Associated.infer_assoc_name(other))
+        Associated.new(self, associations: {name => other})
+      end
+
+      # Return command result type
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def result
+        __data__.is_a?(Array) ? :many : :one
+      end
+
+      # Return string representation of the changeset
+      #
+      # @return [String]
+      #
+      # @api public
+      def inspect
+        %(#<#{self.class} relation=#{relation.name.inspect} data=#{__data__}>)
+      end
+
+      # @api private
+      def command_compiler_options
+        super.merge(result: result)
+      end
+
+      # Data transformation pipe
+      #
+      # @return [Changeset::Pipe]
+      #
+      # @api private
+      def pipe
+        @pipe ||= self.class.default_pipe(self)
+      end
+
+      private
+
+      # @api private
+      def respond_to_missing?(meth, include_private = false)
+        super || __data__.respond_to?(meth)
+      end
+
+      # @api private
+      def method_missing(meth, *args, &block)
+        if __data__.respond_to?(meth)
+          response = __data__.__send__(meth, *args, &block)
+
+          if response.is_a?(__data__.class)
+            with(__data__: response)
+          else
+            response
+          end
+        else
+          super
+        end
+      end
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+    end
+  end
+end

data/lib/rom/changeset/update.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ROM
+  class Changeset
+    # Changeset specialization for update commands
+    #
+    # Update changesets will only execute their commands when
+    # the data is different from the original tuple. Original tuple
+    # is fetched from changeset's relation using `one` method.
+    #
+    # @example
+    #   users.by_pk(1).changeset(:update, name: "Jane Doe").commit
+    #
+    # @see Changeset::Stateful
+    #
+    # @api public
+    class Update < Stateful
+      command_type :update
+
+      # Commit update changeset if there's a diff
+      #
+      # This returns original tuple if there's no diff
+      #
+      # @return [Hash]
+      #
+      # @see Changeset#commit
+      #
+      # @api public
+      def commit
+        diff? ? super : original
+      end
+
+      # Return original tuple that this changeset may update
+      #
+      # @return [Hash]
+      #
+      # @api public
+      def original
+        @original ||= relation.one
+      end
+
+      # Return true if there's a diff between original and changeset data
+      #
+      # @return [TrueClass, FalseClass]
+      #
+      # @api public
+      def diff?
+        !diff.empty?
+      end
+
+      # Return if there's no diff between the original and changeset data
+      #
+      # @return [TrueClass, FalseClass]
+      #
+      # @api public
+      def clean?
+        diff.empty?
+      end
+
+      # Calculate the diff between the original and changeset data
+      #
+      # @return [Hash]
+      #
+      # @api public
+      def diff
+        @diff ||=
+          begin
+            source = original.to_h
+            data = pipe.for_diff(__data__)
+            data_tuple = data.to_a
+            data_keys = data.keys & source.keys
+
+            new_tuple = data_tuple.to_a.select { |k, _| data_keys.include?(k) }
+            ori_tuple = source.to_a.select { |k, _| data_keys.include?(k) }
+
+            (new_tuple - (new_tuple & ori_tuple)).to_h
+          end
+      end
+    end
+  end
+end

data/lib/rom/changeset.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "dry/core/class_attributes"
+require "dry/core/cache"
+
+require "rom/constants"
+require "rom/initializer"
+
+module ROM
+  # Abstract Changeset class
+  #
+  # If you inherit from this class you need to configure additional settings
+  #
+  # @example define a custom changeset using :upsert command
+  #   class NewTag < ROM::Changeset[:tags]
+  #     command_type :upsert
+  #   end
+  #
+  # @abstract
+  class Changeset
+    extend Initializer
+    extend Dry::Core::Cache
+    extend Dry::Core::ClassAttributes
+
+    # @!method self.command_type
+    #   Get or set changeset command type
+    #
+    #   @overload command_type
+    #     Return configured command_type
+    #     @return [Symbol]
+    #
+    #   @overload command_type(identifier)
+    #     Set relation identifier for this changeset
+    #     @param [Symbol] identifier The command type identifier
+    #     @return [Symbol]
+    defines :command_type
+
+    # @!method self.command_options
+    #   Get or set command options
+    #
+    #   @overload command_options
+    #     Return configured command_options
+    #     @return [Hash,nil]
+    #
+    #   @overload command_options(**options)
+    #     Set command options
+    #     @param options [Hash] The command options
+    #     @return [Hash]
+    defines :command_options
+
+    # @!method self.command_plugins
+    #   Get or set command plugins options
+    #
+    #   @overload command_plugins
+    #     Return configured command_plugins
+    #     @return [Hash,nil]
+    #
+    #   @overload command_plugins(**options)
+    #     Set command plugin options
+    #     @param options [Hash] The command plugin options
+    #     @return [Hash]
+    defines :command_plugins
+
+    # @!method self.relation
+    #   Get or set changeset relation identifier
+    #
+    #   @overload relation
+    #     Return configured relation identifier for this changeset
+    #     @return [Symbol]
+    #
+    #   @overload relation(identifier)
+    #     Set relation identifier for this changeset
+    #     @param [Symbol] identifier The relation identifier from the ROM container
+    #     @return [Symbol]
+    defines :relation
+
+    # @!attribute [r] relation
+    #   @return [Relation] The changeset relation
+    param :relation
+
+    # @!attribute [r] command_type
+    #   @return [Symbol] a custom command identifier
+    option :command_type, default: -> { self.class.command_type }
+
+    # @!attribute [r] command_options
+    #   @return [Hash] Configured options for the command
+    option :command_options, default: -> { self.class.command_options }
+
+    # @!attribute [r] command_plugins
+    #   @return [Hash] Configured plugin options for the command
+    option :command_plugins, default: -> { self.class.command_plugins }
+
+    # Set the default command options
+    command_options(mapper: false)
+
+    # Set the default command plugin options
+    command_plugins(EMPTY_HASH)
+
+    # Create a changeset class preconfigured for a specific relation
+    #
+    # @example
+    #   class NewUserChangeset < ROM::Changeset::Create[:users]
+    #   end
+    #
+    #   users.changeset(NewUserChangeset).data(name: 'Jane')
+    #
+    # @api public
+    def self.[](relation_name)
+      fetch_or_store([relation_name, self]) {
+        Class.new(self) { relation(relation_name) }
+      }
+    end
+
+    # Enable a plugin for the changeset
+    #
+    # @api public
+    def self.use(plugin, **options)
+      ROM.plugins[:changeset].fetch(plugin).enable(self).apply(**options)
+    end
+
+    # Return a new changeset with provided relation
+    #
+    # New options can be provided too
+    #
+    # @param [Relation] relation
+    # @param [Hash] new_options
+    #
+    # @return [Changeset]
+    #
+    # @api public
+    def new(relation, **new_options)
+      self.class.new(relation, **options, **new_options)
+    end
+
+    # Persist changeset
+    #
+    # @example
+    #   changeset = users.changeset(name: 'Jane')
+    #   changeset.commit
+    #   # => { id: 1, name: 'Jane' }
+    #
+    # @return [Hash, Array]
+    #
+    # @api public
+    def commit
+      command.call
+    end
+
+    # Return string representation of the changeset
+    #
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      %(#<#{self.class} relation=#{relation.name.inspect}>)
+    end
+
+    # Return a command for this changeset
+    #
+    # @return [ROM::Command]
+    #
+    # @api private
+    def command
+      relation.command(command_type, **command_compiler_options)
+    end
+
+    # Return configured command compiler options
+    #
+    # @return [Hash]
+    #
+    # @api private
+    def command_compiler_options
+      command_options.merge(use: command_plugins.keys, plugins_options: command_plugins)
+    end
+  end
+end
+
+require "rom/changeset/stateful"
+require "rom/changeset/associated"
+
+require "rom/changeset/create"
+require "rom/changeset/update"
+require "rom/changeset/delete"
+
+require "rom/plugins"