clowne 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 616d875656dc9fa7ef815190a4281d5cac5ebd8d6ac471bd6b7292a139f78d8e
-  data.tar.gz: 35fd2f7681c3e13152ad98562737e6bac498c79e569f330a9986eba2e45302a2
+  metadata.gz: f1b3c79ac97f903ed3f2c1f8ae8b894dd7c4f3c4da5ab28350e59482ef08714e
+  data.tar.gz: af3aa849d2ba1dfdc34f8edbb612c384bafefd21d2ef74f2842e659af4690867
 SHA512:
-  metadata.gz: 81734963c899011b5f518d817dddeb4fe761df3326ec2165b99b877212ec8de19100d9cb2cd5beccebab276c42f0c6e806d6385ce2f929982c3509641e6c58b9
-  data.tar.gz: e6fa4181b54efcd3a33e9be9dc5a9f569f324954d9d72d4cb95a253bc8c5b1386e30060c52f9f6434ee3c2f03dd2e9f86c0e21f254fab9725efd927c2d07dda9
+  metadata.gz: bbf985fe91770d1d34ae133492ba58aadc7eeab15b3dcc6f122db94d6e48e42dd8c885c4b145da2325583a98143d28464b128c7f34174a13f4922a72a340cfff
+  data.tar.gz: f47be4fac65591d29754756e2dd59a002d1eec0fcbfd661d2619f113020d97a7f1630d0d738cb3d2c9a7496d4302e2a0e888a3d537c9dcb2fed0053db72ee1db

data/.rubocop.yml

@@ -24,6 +24,12 @@ Naming/ClassAndModuleCamelCase:
   Exclude:
     - 'spec/**/*.rb'
 
+Naming/UncommunicativeMethodParamName:
+  Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
 Style/TrivialAccessors:
   Enabled: false
 

data/.travis.yml

@@ -5,7 +5,8 @@ notifications:
   email: false
 
 before_install:
-  gem update --system
+  - gem update --system
+  - gem install bundler
 
 before_script:
   # Only generate coverage report for the specified job
@@ -22,6 +23,8 @@ matrix:
   include:
     - rvm: ruby-head
       gemfile: gemfiles/railsmaster.gemfile
+    - rvm: jruby-9.2.5.0
+      gemfile: gemfiles/jruby.gemfile
     - rvm: jruby-9.1.15.0
       gemfile: gemfiles/jruby.gemfile
     - rvm: 2.5.0
@@ -35,11 +38,11 @@ matrix:
       gemfile: gemfiles/activerecord42.gemfile
     - rvm: 2.3.1
       gemfile: Gemfile
-    - rvm: 2.2.0
-      gemfile: gemfiles/activerecord42.gemfile
   allow_failures:
     - rvm: ruby-head
       gemfile: gemfiles/railsmaster.gemfile
+    - rvm: jruby-9.2.5.0
+      gemfile: gemfiles/jruby.gemfile
     - rvm: jruby-9.1.15.0
       gemfile: gemfiles/jruby.gemfile
 deploy:

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change log
 
+## 1.0.0 (2019-02-26)
+
+- Return `Operation` instance as a rusult of cloning. ([@ssnickolay][])
+
+See [migration guide](https://clowne.evilmartians.io/docs/from_v02_to_v10.html)
+
+- Add `after_persist` declaration. ([@ssnickolay][], [@palkan][])
+
+- Unify interface between adapters. ([@ssnickolay][])
+
+- Deprecate `Operation#save` and `Operation#save!` methods. ([@ssnickolay][])
+
+- Improve Docs ([@ssnickolay][], [@palkan][])
+
 ## 0.2.0 (2018-02-21)
 
 - Add `Cloner#partial_apply` method. ([@palkan][])

data/Gemfile

@@ -5,7 +5,7 @@ gemspec
 
 gem 'pry-byebug', platform: :mri
 
-gem 'sqlite3', platform: :mri
+gem 'sqlite3', '~> 1.3.6', platform: :mri
 gem 'activerecord-jdbcsqlite3-adapter', '~> 50.0', platform: :jruby
 gem 'jdbc-sqlite3', platform: :jruby
 

data/README.md

@@ -1,12 +1,16 @@
 [![Gem Version](https://badge.fury.io/rb/clowne.svg)](https://badge.fury.io/rb/clowne)
 [![Build Status](https://travis-ci.org/palkan/clowne.svg?branch=master)](https://travis-ci.org/palkan/clowne)
 [![Test Coverage](https://codeclimate.com/github/palkan/clowne/badges/coverage.svg)](https://codeclimate.com/github/palkan/clowne/coverage)
-[![Docs](https://img.shields.io/readthedocs/pip.svg)](https://palkan.github.io/clowne)
+[![Docs](https://img.shields.io/badge/docs-link-brightgreen.svg)](https://clowne.evilmartians.io)
 
 # Clowne
 
 A flexible gem for cloning your models. Clowne focuses on ease of use and provides the ability to connect various ORM adapters.
 
+📖 Read [Evil Martians Chronicles](https://evilmartians.com/chronicles/clowne-clone-ruby-models-with-a-smile) to learn about possible use cases.
+
+📑 [Documentation](https://clowne.evilmartians.io)
+
 <a href="https://evilmartians.com/">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
@@ -40,6 +44,16 @@ class User < ActiveRecord::Base
   has_one :profile
   has_many :posts
 end
+
+class Profile < ActiveRecord::Base
+  # create_table :profiles do |t|
+  #   t.string :name
+  # end
+end
+
+class Post < ActiveRecord::Base
+  # create_table :posts
+end
 ```
 
 Let's declare our cloners first:
@@ -70,13 +84,20 @@ Now you can use `UserCloner` to clone existing records:
 
 ```ruby
 user = User.last
-#=> <#User(login: 'clown', email: 'clown@circus.example.com')>
+# => <#User id: 1, login: 'clown', email: 'clown@circus.example.com'>
+
+operation = UserCloner.call(user, email: 'fake@example.com')
+# => <#Clowne::Utils::Operation...>
+
+operation.to_record
+# => <#User id: nil, login: nil, email: 'fake@example.com'>
+
+operation.persist!
+# => true
 
-cloned = UserCloner.call(user, email: 'fake@example.com')
-cloned.persisted?
-# => false
+cloned = operation.to_record
+# => <#User id: 2, login: nil, email: 'fake@example.com'>
 
-cloned.save!
 cloned.login
 # => nil
 cloned.email
@@ -89,14 +110,14 @@ cloned.profile.name
 # => nil
 ```
 
-Take a look at our [documentation](https://palkan.github.io/clowne) for more information!
+Take a look at our [documentation](https://clowne.evilmartians.io) for more info!
 
 ### Supported ORM adapters
 
 Adapter                                   |1:1         | 1:M         | M:M                     |
 ------------------------------------------|------------|-------------|-------------------------|
-[Active Record](https://palkan.github.io/clowne/docs/active_record.html)  | has_one    | has_many    | has_and_belongs_to_many |
-[Sequel](https://palkan.github.io/clowne/docs/sequel.html)           | one_to_one | one_to_many | many_to_many            |
+[Active Record](https://clowne.evilmartians.io/clowne/docs/active_record.html)  | has_one    | has_many    | has_and_belongs_to|
+[Sequel](https://clowne.evilmartians.io/clowne/docs/sequel.html)                | one_to_one | one_to_many | many_to_many     |
 
 ## Maintainers
 

data/clowne.gemspec

@@ -1,4 +1,4 @@
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'clowne/version'
 
@@ -20,10 +20,11 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.14'
+  spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'factory_bot', '~> 4.8'
-  spec.add_development_dependency 'rubocop', '~> 0.51'
+  spec.add_development_dependency 'rubocop', '~> 0.61'
   spec.add_development_dependency 'rubocop-md', '~> 0.2'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.31'
 end

data/docs/active_record.md

@@ -31,6 +31,6 @@ end
 And then you can clone objects like this:
 
 ```ruby
-user.clowne(traits: my_traits, **params)
-# => <#User...
+user.clowne(traits: my_traits, **params).to_record
+# => <#User id: nil...>
 ```

data/docs/after_persist.md

@@ -0,0 +1,80 @@
+---
+id: after_persist
+title: After Persist
+---
+
+_Notice: `after_persist` supported only with [`active_record`](active_record.md) adapter._
+
+The special mechanism for transformation of cloned record. In contradistinction to [`finalize`](finalize.md) executes with a saved record. This type of callbacks provides a default `mapper:` parameter which contains a relation between origin and cloned objects.
+
+`after_persist` helps to restore broken _relationships_ while cloning associations and implement some logic with already persisted clone record. (_Inspired by [issues#19](https://github.com/palkan/clowne/issues/19)_)
+
+Examples:
+
+```ruby
+class User < ActiveRecord::Base
+  # create_table :users do |t|
+  #   t.string :login
+  #   t.integer :bio_id
+  # end
+
+  has_many :posts # all user's posts including BIO
+  belongs_to :bio, class_name: 'Post'
+end
+
+class Post < ActiveRecord::Base
+  # create_table :posts do |t|
+  #   t.integer :user_id
+  # end
+end
+
+class UserCloner < Clowne::Cloner
+  include_association :posts, params: true
+
+  after_persist do |origin, clone, mapper:, **|
+    cloned_bio = mapper.clone_of(origin.bio)
+    clone.update_attributes(bio_id: cloned_bio.id)
+  end
+end
+
+class PostCloner < Clowne::Cloner
+  after_persist do |_, clone, run_job:, **|
+    PostBackgroundJob.perform_async(clone.id) if run_job
+  end
+end
+```
+
+_Notice: See more about `mapper:` [`here`](clone_mapper.md)._
+
+`after_persist` runs when you call [`Operation#persist`]('operation.md) (or `Operation#persist!`)
+
+```ruby
+# prepare data
+user = User.create
+posts = Array.new(3) { Post.create(user: user) }
+bio = posts.sample
+user.update_attributes(bio_id: bio.id)
+
+operation = UserCloner.call(user, run_job: true)
+# => <#Clowne::Utils::Operation ...>
+
+clone = operation.to_record
+# => <#User id: nil, ...>
+
+# we copy all user attributes including bio_id
+# but this is wrong because bio refers to the source user's bio
+# and we can fix it using after_persist when posts already saved
+clone.bio_id == bio.id
+# => true
+
+# save clone and run after_persist callbacks
+operation.persit
+
+clone.bio_id == bio.id
+# => false
+
+clone.posts.pluck(:id).include?(clone.bio_id)
+# => true
+```
+
+_Notice: be careful while using after_persist feature! If you clone a fat record (with a lot of associations) and will implement complex logic inside `after_persist` callback, it may affect your system._

data/docs/basic_example.md

@@ -16,6 +16,16 @@ class User < ActiveRecord::Base
   has_one :profile
   has_many :posts
 end
+
+class Profile < ActiveRecord::Base
+  # create_table :profiles do |t|
+  #   t.string :name
+  # end
+end
+
+class Post < ActiveRecord::Base
+  # create_table :posts
+end
 ```
 
 Let's declare our cloners first:
@@ -46,13 +56,20 @@ Now you can use `UserCloner` to clone existing records:
 
 ```ruby
 user = User.last
-#=> <#User(login: 'clown', email: 'clown@circus.example.com')>
+# => <#User id: 1, login: 'clown', email: 'clown@circus.example.com'>
+
+operation = UserCloner.call(user, email: 'fake@example.com')
+# => <#Clowne::Utils::Operation...>
+
+operation.to_record
+# => <#User id: nil, login: nil, email: 'fake@example.com'>
+
+operation.persist!
+# => true
 
-cloned = UserCloner.call(user, email: 'fake@example.com')
-cloned.persisted?
-# => false
+cloned = operation.to_record
+# => <#User id: 2, login: nil, email: 'fake@example.com'>
 
-cloned.save!
 cloned.login
 # => nil
 cloned.email

data/docs/clone_mapper.md

@@ -0,0 +1,62 @@
+---
+id: clone_mapper
+title: Clone mapper
+---
+
+_Notice: `after_persist` supported only with [`active_record`](active_record.md) adapter._
+
+In [`after_persist`](after_persist.md) documenation you can find interisting code:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  # ...
+  after_persist do |origin, clone, mapper:, **|
+    cloned_bio = mapper.clone_of(origin.bio)
+    clone.update_attributes(bio_id: cloned_bio.id)
+  end
+end
+```
+
+What is it `mapper:` and how it works?
+
+`mapper:` is an instance of `Clowne::Utils::CloneMapper`. Active Record pattern gives us an opportunity to build our cloning tool on objects, so while cloning, we remember origin records and their clones and can use these relations after saving with `Clowne::Utils::CloneMapper`.
+
+It perfectly works, and we can use the mapper to fix broken associations.
+There is only one small nuance - we can get `#clone_of` only for the record that participated in a cloning process, and this limits the functionality of the `after_persist` callbacks.
+
+But `Clowne is built with extensibility in mind™` and Clowne provides the ability to use your custom mapper:
+
+```ruby
+class CustomMapper < Clowne::Utils::CloneMapper
+  def initialize(dependencies)
+    super()
+    # inject dependencies if need
+    # or fetch it from other place (e.g. from DB)
+    @default_bios = dependencies.index_by(&:title)
+  end
+
+  def clone_of(record)
+    super(record) || fallback(record)
+  end
+
+  private
+
+  def fallback(record)
+    # put some mapping logic here
+    return if record.is_a?(Post)
+
+    @default_bios[record.title]
+  end
+end
+
+# now we can use it:
+
+class Post < ActiveRecord::Base
+  # add simple scope
+  # scope :default_bios, -> {...}
+end
+
+user = User.last
+operation = UserCloner.call(user, mapper: CustomMapper.new(Post.default_bios))
+operation.persist
+```

data/docs/customization.md

@@ -21,7 +21,7 @@ class IncludeAll < Clowne::Declarations::Base # :nodoc: all
 end
 
 # Register our declrations, i.e. extend DSL
-Clowne::Declarations.add :include_all, Clowne::Declarations::IncludeAll
+Clowne::Declarations.add :include_all, IncludeAll
 ```
 
 See more on `plan` in [architecture overview](architecture.md).
@@ -40,6 +40,7 @@ class AllAssociations
     source.class.reflections.each_value do |_name, reflection|
       # Exclude belongs_to associations
       next if reflection.macro == :belongs_to
+
       # Resolve and apply association cloner
       cloner_class = Clowne::Adapters::ActiveRecord::Associations.cloner_for(reflection)
       cloner_class.new(reflection, source, declaration, params).call(record)

data/docs/exclude_association.md

@@ -19,12 +19,12 @@ class UserCloner < Clowne::Cloner
 end
 
 # copy user and posts
-clone = UserCloner.call(user)
+clone = UserCloner.call(user).to_record
 clone.posts.count == user.posts.count
 # => true
 
 # copy only user
-clone2 = UserCloner.call(user, traits: :without_posts)
+clone2 = UserCloner.call(user, traits: :without_posts).to_record
 clone2.posts
 # => []
 ```
@@ -41,8 +41,9 @@ class UserCloner < Clowne::Cloner
   end
 end
 
-clone = UserCloner.call(user, traits: :with_comments)
-clone.comments.empty? #=> true
+clone = UserCloner.call(user, traits: :with_comments).to_record
+clone.comments.empty?
+# => true
 ```
 
 Why so? That allows us to have a deterministic cloning plan when combining multiple traits

data/docs/finalize.md

@@ -19,13 +19,13 @@ class UserCloner < Clowne::Cloner
   end
 end
 
-cloned = UserCloner.call(user)
+cloned = UserCloner.call(user).to_record
 cloned.name
 # => 'This is copy!'
 cloned.email == 'clone@example.com'
 # => false
 
-cloned2 = UserCloner.call(user, traits: :change_email)
+cloned2 = UserCloner.call(user, traits: :change_email).to_record
 cloned2.name
 # => 'This is copy!'
 cloned2.email

data/docs/from_v02_to_v1.md

@@ -0,0 +1,91 @@
+---
+id: from_v02_to_v10
+title: From v0.2.x to v1.0.0
+---
+
+The breaking change of v1.0 is the return of a unified [`result object`](operation.md) for all adapters.
+
+## ActiveRecord
+
+### Update code to work with [`Operation`](operation.md)
+
+```ruby
+# Before
+clone = UserCloner.call(user)
+# => <#User id: nil, ...>
+clone.save!
+# => true
+
+# After
+clone = UserCloner.call(user)
+# => <#Clowne::Utils::Operation ...>
+clone = clone.to_record
+# => <#User id: 2, ...>
+clone.save!
+# => true
+
+# After (even better because of using full functionality)
+operation = UserCloner.call(user)
+# => <#Clowne::Utils::Operation ...>
+operation.persist!
+# => true
+clone = operation.to_record
+# => <#User id: 2, ...>
+clone.persisted?
+# => true
+```
+
+### Move post-processing cloning logic into [`after_persist`](after_persist.md) callback (if you have it)
+
+_Notice: `after_persist` supported only with [`active_record`](active_record.md) adapter._
+
+<span style="display:none;"># rubocop:disable all</span>
+```ruby
+# Before
+clone = UserCloner.call(user)
+clone.save!
+# do something with persisted clone
+
+# After
+class UserCloner < Clowne::Cloner
+  # ...
+  after_persist do |origin, clone, **|
+    # do something with persisted clone
+  end
+end
+
+clone = UserCloner.call(user).tap(&:persist).to_record
+```
+<span style="display:none;"># rubocop:enable all</span>
+
+## Sequel
+
+### Use `to_record` instead of `to_model`
+
+```ruby
+# Before
+record_wrapper = UserCloner.call(user)
+clone = record_wrapper.to_model
+clone.new?
+# => true
+
+# After
+operation = UserCloner.call(user)
+clone = operation.to_record
+clone.new?
+# => true
+```
+
+### Use `operation#persist` instead of converting to model and calling `#save`
+
+<span style="display:none;"># rubocop:disable all</span>
+```ruby
+# Before
+record_wrapper = UserCloner.call(user)
+clone = record_wrapper.to_model
+clone.save
+
+# After
+clone = UserCloner.call(user).tap(&:persist).to_record
+```
+<span style="display:none;"># rubocop:enable all</span>