rom-repository 1.0.0.beta3 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8deef9fc5ae64394c2845f34d1575ff4f55d503d
-  data.tar.gz: 746ac682b439a3ffd603cd79e64b2bf52ead6d8b
+  metadata.gz: a6bc1f6b343814740048fa138304b11012da7116
+  data.tar.gz: f61f8773af19190816e3d372fb44f3c94e6b5cef
 SHA512:
-  metadata.gz: c970db02832c84c5287a4c537bcc851abd07013947fdaeccccf6db117bf5b7817b4b10dbbfa0efc6683be30830e826eeaf5aba504b3e47663348a94291c05b06
-  data.tar.gz: 410546d65acdec9fedb221809ed1e2b098621da1b034eb8580b34c333931fdee16ba5ece929f9ccdfbc9be52150eb7fe89c5531ebea852c2cbd3c090f8a3bc44
+  metadata.gz: 57f9e84fa9ed7296a5d792c4d887777083c01685f63f80fe94f22ee50ed0f12f82b06ebfe8f48930a4a1c42aa7004a85e75fa38c2d330419636a26ce14b17a1a
+  data.tar.gz: cbf38fe68a94152d598025f496061f2d25cfcea5670712e426b47325b12bb9bafeaf6ea34b410931949f41ed56d9aaa4bb5f5c73a478e5c78d4a1525be33f82c

data/.gitignore

@@ -1,2 +1,3 @@
 Gemfile.lock
 log/*.log
+doc

data/.travis.yml

@@ -10,18 +10,14 @@ after_success:
   - '[ "${TRAVIS_JOB_NUMBER#*.}" = "1" ] && [ "$TRAVIS_BRANCH" = "master" ] && bundle exec codeclimate-test-reporter'
 rvm:
   - 2.4.0
-  - 2.3.3
-  - 2.2.6
+  - 2.3
+  - 2.2
   - rbx-3
-  - jruby-9.1.6.0
+  - jruby
 env:
   global:
     - JRUBY_OPTS='--dev -J-Xmx1024M'
     - COVERAGE='true'
-matrix:
-  allow_failures:
-    - rvm: rbx-3
-    - rvm: jruby-9.1.6.0
 notifications:
   webhooks:
     urls:

data/CHANGELOG.md

@@ -19,6 +19,7 @@
 
 * `ROM::Struct` is now based on `Dry::Struct` (solnic)
 * rom-support dependency was removed (flash-gordon)
+* `update?` and `create?` methods were removed from `Changeset:*` subclasses (solnic)
 
 ### Fixed
 

data/README.md

@@ -13,7 +13,7 @@
 [![Test Coverage](https://codeclimate.com/github/rom-rb/rom-repository/badges/coverage.svg)][codeclimate]
 [![Inline docs](http://inch-ci.org/github/rom-rb/rom-repository.svg?branch=master)][inchpages]
 
-Repository for [rom-rb](https://github.com/rom-rb/rom) with auto-mapping and commands.
+Repositories for [rom-rb](https://github.com/rom-rb/rom) with auto-mapping, changesets and commands.
 
 Resources:
 

data/lib/rom/repository/changeset/associated.rb

@@ -0,0 +1,76 @@
+require 'rom/initializer'
+
+module ROM
+  class Changeset
+    # Associated changesets automatically set up FKs
+    #
+    # @api public
+    class Associated
+      extend Initializer
+
+      # @!attribute [r] left
+      #   @return [Changeset::Create] Child changeset
+      param :left
+
+      # @!attribute [r] right
+      #   @return [Changeset::Create, Hash, #to_hash] Parent changeset or data
+      param :right
+
+      # @!attribute [r] association
+      #   @return [Symbol] Association identifier from relation schema
+      option :association, reader: true
+
+      # Commit changeset's composite command
+      #
+      # @example
+      #   task_changeset = task_repo.
+      #     changeset(title: 'Task One').
+      #     associate(user, :user).
+      #     commit
+      #   # {:id => 1, :user_id => 1, title: 'Task One'}
+      #
+      # @return [Array<Hash>, Hash]
+      #
+      # @api public
+      def commit
+        command.call
+      end
+
+      # Create a composed command
+      #
+      # @example using existing parent data
+      #   user_changeset = user_repo.changeset(name: 'Jane')
+      #   task_changeset = task_repo.changeset(title: 'Task One')
+      #
+      #   user = user_repo.create(user_changeset)
+      #   task = task_repo.create(task_changeset.associate(user, :user))
+      #
+      # @example saving both parent and child in one go
+      #   user_changeset = user_repo.changeset(name: 'Jane')
+      #   task_changeset = task_repo.changeset(title: 'Task One')
+      #
+      #   task = task_repo.create(task_changeset.associate(user, :user))
+      #
+      # This works *only* with parent => child(ren) changeset hierarchy
+      #
+      # @return [ROM::Command::Composite]
+      #
+      # @api public
+      def command
+        case right
+        when Changeset
+          left.command.curry(left) >> right.command.with_association(association).curry(right)
+        when Associated
+          left.command.curry(left) >> right.command.with_association(association)
+        else
+          left.command.with_association(association).curry(left, right)
+        end
+      end
+
+      # @api private
+      def relation
+        left.relation
+      end
+    end
+  end
+end

data/lib/rom/repository/changeset/create.rb

@@ -3,58 +3,8 @@ module ROM
     # Changeset specialization for create commands
     #
     # @api public
-    class Create < Changeset
-      # @!attribute [r] association
-      #   @return [Array] Associated changesets with its association name
-      option :association, reader: true, optional: true
-
-      # @api public
-      def associate(other, assoc)
-        with(association: [other, assoc])
-      end
-
-      # Return false
-      #
-      # @return [FalseClass]
-      #
-      # @api public
-      def update?
-        false
-      end
-
-      # Return true
-      #
-      # @return [TrueClass]
-      #
-      # @api public
-      def create?
-        true
-      end
-
-      # @api private
-      def command
-        if options[:association]
-          other, assoc = options[:association]
-
-          if other.is_a?(Changeset)
-            create_command.curry(self) >> other.command.with_association(assoc)
-          else
-            create_command.with_association(assoc).curry(self, other)
-          end
-        else
-          create_command.curry(self)
-        end
-      end
-
-      # @api private
-      def create_command
-        command_compiler.(command_type, relation, mapper: false, result: result)
-      end
-
-      # @api private
-      def default_command_type
-        :create
-      end
+    class Create < Stateful
+      command_type :create
     end
   end
 end

data/lib/rom/repository/changeset/delete.rb

@@ -1,15 +1,13 @@
 module ROM
   class Changeset
+    # Changeset specialization for delete commands
+    #
+    # Delete changesets will execute delete command for its relation, which
+    # means proper restricted relations should be used with this changeset.
+    #
+    # @api public
     class Delete < Changeset
-      # @api private
-      def command
-        command_compiler.(command_type, relation, mapper: false)
-      end
-
-      # @api private
-      def default_command_type
-        :delete
-      end
+      command_type :delete
     end
   end
 end

data/lib/rom/repository/changeset/pipe.rb

@@ -3,6 +3,9 @@ require 'transproc/transformer'
 
 module ROM
   class Changeset
+    # Composable data transformation pipe used by default in changesets
+    #
+    # @api private
     class Pipe < Transproc::Transformer
       extend Transproc::Registry
 

data/lib/rom/repository/changeset/stateful.rb

@@ -0,0 +1,240 @@
+require 'rom/repository/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.freeze
+
+      # @!attribute [r] __data__
+      #   @return [Hash] The relation data
+      #   @api private
+      option :__data__, reader: true, optional: true, default: proc { nil }
+
+      # @!attribute [r] pipe
+      #   @return [Changeset::Pipe] data transformation pipe
+      #   @api private
+      option :pipe, reader: true, accept: [Proc, Pipe], default: -> changeset {
+        changeset.class.default_pipe(changeset)
+      }
+
+      # 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, Transproc::Function>]
+      #
+      # @api public
+      def self.map(&block)
+        if block.arity.zero?
+          pipes << Class.new(Pipe, &block).new
+        else
+          pipes << Pipe.new(block)
+        end
+      end
+
+      # Build default pipe object
+      #
+      # This can be overridden in a custom changeset subclass
+      #
+      # @return [Pipe]
+      def self.default_pipe(context)
+        pipes.size > 0 ? pipes.map { |p| p.bind(context) }.reduce(:>>) : EMPTY_PIPE
+      end
+
+      # @api private
+      def self.inherited(klass)
+        return if klass == ROM::Changeset
+        super
+        klass.instance_variable_set(:@__pipes__, pipes ? pipes.dup : EMPTY_ARRAY)
+      end
+
+      # @api private
+      def self.pipes
+        @__pipes__
+      end
+
+      # 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) }
+      #
+      #   @param [Array<Symbol>] steps A list of mapping steps
+      #
+      # @overload map(*steps, &block)
+      #   Apply mapping using built-in transformations and a custom block
+      #
+      #   @example
+      #     changeset.map(:touch) { |tuple| tuple.merge(status: 'published') }
+      #
+      #   @param [Array<Symbol>] steps A list of mapping steps
+      #
+      # @return [Changeset]
+      #
+      # @api public
+      def map(*steps, &block)
+        if block
+          if steps.size > 0
+            map(*steps).map(&block)
+          else
+            with(pipe: pipe >> Pipe.new(block).bind(self))
+          end
+        else
+          with(pipe: steps.reduce(pipe) { |a, e| a >> pipe[e] })
+        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 = user_repo.changeset(name: 'Jane')
+      #   new_task = user_repo.changeset(:tasks, title: 'A task')
+      #
+      #   new_task.associate(new_user, :users)
+      #
+      # @example with a hash-like object
+      #   user = user_repo.users.by_pk(1).one
+      #   new_task = user_repo.changeset(:tasks, title: 'A task')
+      #
+      #   new_task.associate(user, :users)
+      #
+      # @param [#to_hash, Changeset] other Other changeset or hash-like object
+      # @param [Symbol] assoc The association identifier from schema
+      #
+      # @api public
+      def associate(other, name)
+        Associated.new(self, other, association: name)
+      end
+
+      # Return command result type
+      #
+      # @return [Symbol]
+      #
+      # @api private
+      def result
+        __data__.is_a?(Hash) ? :one : :many
+      end
+
+      # @api public
+      def command
+        command_compiler.(command_type, relation_identifier, DEFAULT_COMMAND_OPTS.merge(result: result))
+      end
+
+      # Return string representation of the changeset
+      #
+      # @return [String]
+      #
+      # @api public
+      def inspect
+        %(#<#{self.class} relation=#{relation.name.inspect} data=#{__data__}>)
+      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
+    end
+  end
+end

data/lib/rom/repository/changeset/update.rb

@@ -2,11 +2,16 @@ 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 `by_pk` relation view.
+    # This means the underlying adapter must provide this view, or you
+    # you need to implement it yourself in your relations if you want to
+    # use Update changesets.
+    #
     # @api public
-    class Update < Changeset
-      # @!attribute [r] primary_key
-      #   @return [Symbol] The name of the relation's primary key attribute
-      option :primary_key, reader: true
+    class Update < Stateful
+      command_type :update
 
       # Commit update changeset if there's a diff
       #
@@ -21,31 +26,13 @@ module ROM
         diff? ? super : original
       end
 
-      # Return true
-      #
-      # @return [TrueClass]
-      #
-      # @api public
-      def update?
-        true
-      end
-
-      # Return false
-      #
-      # @return [FalseClass]
-      #
-      # @api public
-      def create?
-        false
-      end
-
       # Return original tuple that this changeset may update
       #
       # @return [Hash]
       #
       # @api public
       def original
-        @original ||= relation.fetch(primary_key)
+        @original ||= Hash(relation.one)
       end
 
       # Return diff hash sent through the pipe
@@ -78,7 +65,7 @@ module ROM
 
       # Calculate the diff between the original and changeset data
       #
-      # @return [Hash[
+      # @return [Hash, Array]
       #
       # @api public
       def diff
@@ -90,16 +77,6 @@ module ROM
             Hash[new_tuple - (new_tuple & ori_tuple)]
           end
       end
-
-      # @api private
-      def command
-        command_compiler.(command_type, relation, mapper: false).curry(to_h) if diff?
-      end
-
-      # @api private
-      def default_command_type
-        :update
-      end
     end
   end
 end