rom-repository 1.0.0.beta3 → 1.0.0.rc1

data/lib/rom/repository.rb

@@ -12,23 +12,15 @@ 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
+  # A repository provides access to composable relations, commands and changesets.
+  # 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 are configured to
-  # use a single relation as its root, and compose aggregates and use commands
+  # 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
-  #   class MyRepo < ROM::Repository[:users]
-  #     relations :users, :tasks
-  #
-  #     def users_with_tasks
-  #       users.combine_children(tasks: tasks).to_a
-  #     end
-  #   end
-  #
   #   rom = ROM.container(:sql, 'sqlite::memory') do |conf|
   #     conf.default.create_table(:users) do
   #       primary_key :id
@@ -40,15 +32,36 @@ module ROM
   #       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]
+  #     relations :tasks
+  #
+  #     def users_with_tasks
+  #       aggregate(:tasks).to_a
+  #     end
   #   end
   #
-  #   my_repo = MyRepo.new(rom)
-  #   my_repo.users_with_tasks
+  #   user_repo = UserRepo.new(rom)
+  #   user_repo.users_with_tasks
   #
   # @see Repository::Root
   #
   # @api public
   class Repository
+    # Mapping for supported changeset classes used in #changeset(type => relation) method
+    CHANGESET_TYPES = {
+      create: Changeset::Create,
+      update: Changeset::Update,
+      delete: Changeset::Delete
+    }.freeze
+
     extend ClassInterface
 
     # @!attribute [r] container
@@ -63,7 +76,8 @@ module ROM
     #   @return [MapperBuilder] The auto-generated mappers for repo relations
     attr_reader :mappers
 
-    # @api private
+    # @!attribute [r] commmand_compiler
+    #   @return [Method] Function for compiling commands bound to a repo instance
     attr_reader :command_compiler
 
     # Initializes a new repo by establishing configured relation proxies from
@@ -91,6 +105,8 @@ module ROM
       @command_compiler = method(:command)
     end
 
+    # Return a command for a relation
+    #
     # @overload command(type, relation)
     #   Returns a command for a relation
     #
@@ -138,6 +154,8 @@ module ROM
       end
     end
 
+    # Return a changeset for a relation
+    #
     # @overload changeset(name, attributes)
     #   Return a create changeset for a given relation identifier
     #
@@ -170,6 +188,16 @@ module ROM
     #
     #   @return [Changeset]
     #
+    # @overload changeset(opts)
+    #   Return a changeset object using provided changeset type and relation
+    #
+    #   @example
+    #     repo.changeset(delete: repo.users.where { id > 10 })
+    #
+    #   @param [Hash<Symbol=>Relation] opts Command type => Relation config
+    #
+    #   @return [Changeset]
+    #
     # @api public
     def changeset(*args)
       opts = { command_compiler: command_compiler }
@@ -179,10 +207,14 @@ module ROM
       elsif args.size == 3
         name, pk, data = args
       elsif args.size == 1
-        type = args[0]
+        if args[0].is_a?(Class)
+          klass = args[0]
 
-        if type.is_a?(Class) && type < Changeset
-          return type.new(relations[type.relation], opts)
+          if klass < Changeset
+            return klass.new(relations[klass.relation], opts)
+          else
+            raise ArgumentError, "+#{klass.name}+ is not a Changeset subclass"
+          end
         else
           type, relation = args[0].to_a[0]
         end
@@ -191,41 +223,69 @@ module ROM
       end
 
       if type
-        if type.equal?(:delete)
-          Changeset::Delete.new(relation, opts)
-        end
+        klass = CHANGESET_TYPES.fetch(type) {
+          raise ArgumentError, "+#{type.inspect}+ is not a valid changeset type. Must be one of: #{CHANGESET_TYPES.keys.inspect}"
+        }
+
+        klass.new(relation, opts)
       else
         relation = relations[name]
 
         if pk
-          Changeset::Update.new(relation, opts.merge(__data__: data, primary_key: pk))
+          Changeset::Update.new(relation.by_pk(pk), opts.update(__data__: data))
         else
-          Changeset::Create.new(relation, opts.merge(__data__: data))
+          Changeset::Create.new(relation, opts.update(__data__: data))
         end
       end
     end
 
-    # TODO: document me, please
+    # Open a database transaction
     #
-    # @api public
-    def session(&block)
-      session = Session.new(self)
-      yield(session)
-      transaction { session.commit! }
-    end
-
-    # TODO: document me, please
+    # @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
     #
     # @api public
     def transaction(&block)
       container.gateways[:default].transaction(&block)
     end
 
+    # Return a string representation of a repository object
+    #
+    # @return [String]
+    #
     # @api public
     def inspect
       %(#<#{self.class} relations=[#{self.class.relations.map(&:inspect).join(' ')}]>)
     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(&block)
+      session = Session.new(self)
+      yield(session)
+      transaction { session.commit! }
+    end
+
     private
 
     # Local command cache

data/lib/rom/struct.rb

@@ -1,9 +1,47 @@
 require 'dry/struct'
 
 module ROM
-  # Simple data-struct
+  # Simple data-struct class
   #
-  # By default mappers use this as the model
+  # 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 not
+  # defined as constants in any module, instead, generated mappers are configured
+  # to use anonymous struct classes as models.
+  #
+  # 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.
+  #
+  # @example accessing relation struct model
+  #   rom = ROM.container(: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[:id]
+  #   # => #<Dry::Types::Constrained type=#<Dry::Types::Definition primitive=Integer options={}> options={:rule=>#<Dry::Logic::Rule::Predicate predicate=#<Method: Module(Dry::Logic::Predicates::Methods)#gt?> options={:args=>[0]}>, :meta=>{:primary_key=>true, :name=>:id, :source=>ROM::Relation::Name(users)}} rule=#<Dry::Logic::Rule::Predicate predicate=#<Method: Module(Dry::Logic::Predicates::Methods)#gt?> options={:args=>[0]}>>
+  #
+  #   model.schema[:name]
+  #   # => #<Dry::Types::Sum left=#<Dry::Types::Constrained type=#<Dry::Types::Definition primitive=NilClass options={}> options={:rule=>#<Dry::Logic::Rule::Predicate predicate=#<Method: Module(Dry::Logic::Predicates::Methods)#type?> options={:args=>[NilClass]}>} rule=#<Dry::Logic::Rule::Predicate predicate=#<Method: Module(Dry::Logic::Predicates::Methods)#type?> options={:args=>[NilClass]}>> right=#<Dry::Types::Definition primitive=String options={}> options={:meta=>{:name=>:name, :source=>ROM::Relation::Name(users)}}>
+  #
+  # @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

data/rom-repository.gemspec

@@ -15,8 +15,8 @@ Gem::Specification.new do |gem|
   gem.test_files    = `git ls-files -- {spec}/*`.split("\n")
   gem.license       = 'MIT'
 
-  gem.add_runtime_dependency 'rom', '~> 3.0.0.beta'
-  gem.add_runtime_dependency 'rom-mapper', '~> 0.5.0.beta'
+  gem.add_runtime_dependency 'rom', '~> 3.0.0.rc'
+  gem.add_runtime_dependency 'rom-mapper', '~> 0.5.0.rc'
   gem.add_runtime_dependency 'dry-core', '~> 0.2', '>= 0.2.1'
   gem.add_runtime_dependency 'dry-struct', '~> 0.1'
 

data/spec/integration/changeset_spec.rb

@@ -43,6 +43,33 @@ RSpec.describe 'Using changesets' do
       expect(result.created_at).to be_instance_of(Time)
       expect(result.updated_at).to be_instance_of(Time)
     end
+
+    it 'preprocesses data using custom block' do
+      changeset = repo.
+                    changeset(:books, title: "rom-rb is awesome").
+                    map { |tuple| tuple.merge(created_at: Time.now) }
+
+      command = repo.command(:create, repo.books)
+      result = command.(changeset)
+
+      expect(result.id).to_not be(nil)
+      expect(result.title).to eql("rom-rb is awesome")
+      expect(result.created_at).to be_instance_of(Time)
+    end
+
+    it 'preprocesses data using built-in steps and custom block' do
+      changeset = repo.
+                    changeset(:books, title: "rom-rb is awesome").
+                    map(:touch) { |tuple| tuple.merge(created_at: Time.now) }
+
+      command = repo.command(:create, repo.books)
+      result = command.(changeset)
+
+      expect(result.id).to_not be(nil)
+      expect(result.title).to eql("rom-rb is awesome")
+      expect(result.created_at).to be_instance_of(Time)
+      expect(result.updated_at).to be_instance_of(Time)
+    end
   end
 
   describe 'Update' do

data/spec/unit/changeset_spec.rb

@@ -1,6 +1,6 @@
 RSpec.describe ROM::Changeset do
   let(:jane) { { id: 2, name: "Jane" } }
-  let(:relation) { double(ROM::Relation, primary_key: :id) }
+  let(:relation) { double(ROM::Relation, name: :users) }
 
   describe '.[]' do
     it 'returns a changeset preconfigured for a specific relation' do
@@ -24,9 +24,9 @@ RSpec.describe ROM::Changeset do
 
   describe '#diff' do
     it 'returns a hash with changes' do
-      expect(relation).to receive(:fetch).with(2).and_return(jane)
+      expect(relation).to receive(:one).and_return(jane)
 
-      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane Doe" }, primary_key: 2)
+      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane Doe" })
 
       expect(changeset.diff).to eql(name: "Jane Doe")
     end
@@ -34,22 +34,40 @@ RSpec.describe ROM::Changeset do
 
   describe '#diff?' do
     it 'returns true when data differs from the original tuple' do
-      expect(relation).to receive(:fetch).with(2).and_return(jane)
+      expect(relation).to receive(:one).and_return(jane)
 
-      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane Doe" }, primary_key: 2)
+      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane Doe" })
 
       expect(changeset).to be_diff
     end
 
     it 'returns false when data are equal to the original tuple' do
-      expect(relation).to receive(:fetch).with(2).and_return(jane)
+      expect(relation).to receive(:one).and_return(jane)
 
-      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane" }, primary_key: 2)
+      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane" })
 
       expect(changeset).to_not be_diff
     end
   end
 
+  describe '#clean?' do
+    it 'returns true when data are equal to the original tuple' do
+      expect(relation).to receive(:one).and_return(jane)
+
+      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane" })
+
+      expect(changeset).to be_clean
+    end
+
+    it 'returns false when data differs from the original tuple' do
+      expect(relation).to receive(:one).and_return(jane)
+
+      changeset = ROM::Changeset::Update.new(relation, __data__: { name: "Jane Doe" })
+
+      expect(changeset).to_not be_clean
+    end
+  end
+
   describe 'quacks like a hash' do
     subject(:changeset) { ROM::Changeset::Create.new(relation, __data__: data) }
 
@@ -101,4 +119,24 @@ RSpec.describe ROM::Changeset do
       expect { changeset.not_here }.to raise_error(NoMethodError, /not_here/)
     end
   end
+
+  describe '#inspect' do
+    context 'with a stateful changeset' do
+      subject(:changeset) { ROM::Changeset::Create.new(relation).data(name: 'Jane') }
+
+      specify do
+        expect(changeset.inspect).
+          to eql('#<ROM::Changeset::Create relation=:users data={:name=>"Jane"}>')
+      end
+    end
+
+    context 'with a data-less changeset' do
+      subject(:changeset) { ROM::Changeset::Delete.new(relation) }
+
+      specify do
+        expect(changeset.inspect).
+          to eql('#<ROM::Changeset::Delete relation=:users>')
+      end
+    end
+  end
 end

data/spec/unit/repository/changeset_spec.rb

@@ -20,8 +20,8 @@ RSpec.describe ROM::Repository, '#changeset' do
         expect(changeset.relation).to be(repo.users)
       end
 
-      it 'can return a dedicated command' do
-        expect(changeset.command.call).to eql(id: 1, name: 'Jane')
+      it 'can be commited' do
+        expect(changeset.commit).to eql(id: 1, name: 'Jane')
       end
     end
 
@@ -42,35 +42,53 @@ RSpec.describe ROM::Repository, '#changeset' do
         expect(changeset.relation).to be(repo.users)
       end
 
-      it 'can return a dedicated command' do
-        expect(changeset.command.call).to eql([{ id: 1, name: 'Jane' }, { id: 2, name: 'Joe' }])
+      it 'can be commited' do
+        expect(changeset.commit).to eql([{ id: 1, name: 'Jane' }, { id: 2, name: 'Joe' }])
       end
     end
   end
 
   describe ROM::Changeset::Update do
-    let(:changeset) do
-      repo.changeset(:users, user[:id], name: 'Jane Doe')
+    let(:data) do
+      { name: 'Jane Doe' }
     end
 
-    let(:user) do
-      repo.command(:create, repo.users).call(name: 'Jane')
-    end
+    shared_context 'a valid update changeset' do
+      let(:user) do
+        repo.command(:create, repo.users).call(name: 'Jane')
+      end
 
-    it 'has data' do
-      expect(changeset.to_h).to eql(name: 'Jane Doe')
-    end
+      it 'has data' do
+        expect(changeset.to_h).to eql(name: 'Jane Doe')
+      end
+
+      it 'has diff' do
+        expect(changeset.diff).to eql(name: 'Jane Doe')
+      end
 
-    it 'has diff' do
-      expect(changeset.diff).to eql(name: 'Jane Doe')
+      it 'has relation' do
+        expect(changeset.relation.one).to eql(repo.users.by_pk(user[:id]).one)
+      end
+
+      it 'can return be commited' do
+        expect(changeset.commit).to eql(id: 1, name: 'Jane Doe')
+      end
     end
 
-    it 'has relation' do
-      expect(changeset.relation).to be(repo.users)
+    context 'using PK to restrict a relation' do
+      let(:changeset) do
+        repo.changeset(:users, user[:id], data)
+      end
+
+      include_context 'a valid update changeset'
     end
 
-    it 'can return a dedicated command' do
-      expect(changeset.command.call).to eql(id: 1, name: 'Jane Doe')
+    context 'using custom relation' do
+      let(:changeset) do
+        repo.changeset(update: repo.users.by_pk(user[:id])).data(data)
+      end
+
+      include_context 'a valid update changeset'
     end
   end
 
@@ -91,8 +109,8 @@ RSpec.describe ROM::Repository, '#changeset' do
       expect(changeset.relation).to eql(relation)
     end
 
-    it 'can return a dedicated command' do
-      expect(changeset.command.call.to_h).to eql(id: 1, name: 'Jane')
+    it 'can be commited' do
+      expect(changeset.commit.to_h).to eql(id: 1, name: 'Jane')
       expect(relation.one).to be(nil)
     end
   end
@@ -118,8 +136,27 @@ RSpec.describe ROM::Repository, '#changeset' do
       expect(changeset.relation).to be(repo.users)
     end
 
-    it 'can return a dedicated command' do
-      expect(changeset.command.call).to eql(id: 1, name: 'Jane')
+    it 'can be commited' do
+      expect(changeset.commit).to eql(id: 1, name: 'Jane')
     end
   end
+
+  it 'raises ArgumentError when unknown type was used' do
+    expect { repo.changeset(not_here: repo.users) }.
+      to raise_error(
+           ArgumentError,
+           '+:not_here+ is not a valid changeset type. Must be one of: [:create, :update, :delete]'
+         )
+  end
+
+  it 'raises ArgumentError when unknown class was used' do
+    klass = Class.new {
+      def self.name
+        'SomeClass'
+      end
+    }
+
+    expect { repo.changeset(klass) }.
+      to raise_error(ArgumentError, /SomeClass/)
+  end
 end

data/spec/unit/repository/transaction_spec.rb

@@ -4,7 +4,7 @@ RSpec.describe ROM::Repository, '#transaction' do
   end
 
   let(:task_repo) do
-    Class.new(ROM::Repository[:tasks]) { commands :create }.new(rom)
+    Class.new(ROM::Repository[:tasks]) { commands :create, :update }.new(rom)
   end
 
   include_context 'database'
@@ -25,4 +25,18 @@ RSpec.describe ROM::Repository, '#transaction' do
     expect(task.user_id).to be(user.id)
     expect(task.title).to eql('Task One')
   end
+
+  it 'updating tasks user' do
+    jane = user_repo.create(name: 'Jane')
+    john = user_repo.create(name: 'John')
+    task = task_repo.create(title: 'Jane Task', user_id: jane.id)
+
+    task = task_repo.transaction do
+      task_changeset = task_repo.changeset(task.id, title: 'John Task').associate(john, :user).commit
+      task_repo.update(task_changeset)
+    end
+
+    expect(task.user_id).to be(john.id)
+    expect(task.title).to eql('John Task')
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rom-repository
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta3
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Piotr Solnica
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-21 00:00:00.000000000 Z
+date: 2017-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rom
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0.beta
+        version: 3.0.0.rc
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0.beta
+        version: 3.0.0.rc
 - !ruby/object:Gem::Dependency
   name: rom-mapper
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0.beta
+        version: 0.5.0.rc
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0.beta
+        version: 0.5.0.rc
 - !ruby/object:Gem::Dependency
   name: dry-core
   requirement: !ruby/object:Gem::Requirement
@@ -119,9 +119,11 @@ files:
 - lib/rom-repository.rb
 - lib/rom/repository.rb
 - lib/rom/repository/changeset.rb
+- lib/rom/repository/changeset/associated.rb
 - lib/rom/repository/changeset/create.rb
 - lib/rom/repository/changeset/delete.rb
 - lib/rom/repository/changeset/pipe.rb
+- lib/rom/repository/changeset/stateful.rb
 - lib/rom/repository/changeset/update.rb
 - lib/rom/repository/class_interface.rb
 - lib/rom/repository/command_compiler.rb