clowne 0.1.0.pre1 → 1.2.0

data/Rakefile

@@ -1,6 +1,6 @@
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new

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'
 
@@ -8,21 +8,29 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Vladimir Dementyev', 'Sverchkov Nikolay']
   spec.email         = ['palkan@evilmartians.com', 'ssnikolay@gmail.com']
 
-  spec.summary       = 'A flexible gem for cloning your models.'
+  spec.summary       = 'A flexible gem for cloning your models'
   spec.description   = 'A flexible gem for cloning your models.'
-  spec.homepage      = 'https://github.com/palkan/clowne'
+  spec.homepage      = 'https://github.com/clowne-rb/clowne'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.metadata = {
+    "bug_tracker_uri" => "http://github.com/clowne-rb/clowne/issues",
+    "changelog_uri" => "https://github.com/clowne-rb/clowne/blob/master/CHANGELOG.md",
+    "documentation_uri" => "https://clowne.evilmartians.io/",
+    "homepage_uri" => "https://clowne.evilmartians.io/",
+    "source_code_uri" => "http://github.com/clowne-rb/clowne"
+  }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.14'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 12.3', '>= 12.3.3'
   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.75.0'
+  spec.add_development_dependency 'rubocop-md', '~> 0.3.0'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.36.0'
+  spec.add_development_dependency 'standard', '~> 0.1.5'
 end

data/docs/.rubocop.yml

@@ -0,0 +1,18 @@
+inherit_gem:
+  standard: config/base.yml
+
+Lint/Void:
+  Exclude:
+    - '*.md'
+
+Metrics/AbcSize:
+  Enabled: false
+
+Standard/SemanticBlocks:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false

data/docs/CNAME

@@ -0,0 +1 @@
+clowne.evilmartians.io

data/docs/README.md

@@ -0,0 +1,131 @@
+[![Gem Version](https://badge.fury.io/rb/clowne.svg)](https://badge.fury.io/rb/clowne)
+[![Build Status](https://travis-ci.org/clowne-rb/clowne.svg?branch=master)](https://travis-ci.org/clowne-rb/clowne)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/9143c4f91e9d1d2a4bd1/test_coverage)](https://codeclimate.com/github/clowne-rb/clowne/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/9143c4f91e9d1d2a4bd1/maintainability)](https://codeclimate.com/github/clowne-rb/clowne/maintainability)
+[![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>
+
+
+## Installation
+
+To install Clowne with RubyGems:
+
+```ruby
+gem install clowne
+```
+
+Or add this line to your application's Gemfile:
+
+```ruby
+gem "clowne"
+```
+
+## Quick Start
+
+Assume that you have the following model:
+
+```ruby
+class User < ActiveRecord::Base
+  # create_table :users do |t|
+  #  t.string :login
+  #  t.string :email
+  #  t.timestamps null: false
+  # end
+
+  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:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_association :profile, clone_with: SpecialProfileCloner
+  include_association :posts
+
+  nullify :login
+
+  # params here is an arbitrary Hash passed into cloner
+  finalize do |_source, record, params|
+    record.email = params[:email]
+  end
+end
+
+class SpecialProfileCloner < Clowne::Cloner
+  adapter :active_record
+
+  nullify :name
+end
+```
+
+Now you can use `UserCloner` to clone existing records:
+
+```ruby
+user = User.last
+# => <#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 = operation.to_record
+# => <#User id: 2, login: nil, email: 'fake@example.com'>
+
+cloned.login
+# => nil
+cloned.email
+# => "fake@example.com"
+
+# associations:
+cloned.posts.count == user.posts.count
+# => true
+cloned.profile.name
+# => nil
+```
+
+Take a look at our [documentation](https://clowne.evilmartians.io) for more info!
+
+### Supported ORM adapters
+
+Adapter                                   |1:1         |*:1         | 1:M         | M:M                     |
+------------------------------------------|------------|------------|-------------|-------------------------|
+[Active Record](active_record)  | has_one    | belongs_to | has_many    | has_and_belongs_to|
+[Sequel](sequel)                | one_to_one | -          | one_to_many | many_to_many     |
+
+## Maintainers
+
+- [Vladimir Dementyev](https://github.com/palkan)
+
+- [Nikolay Sverchkov](https://github.com/ssnickolay)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/docs/_sidebar.md

@@ -0,0 +1,25 @@
+* [Getting Started](getting_started.md)
+* DSL
+  * [Operation](operation.md)
+  * [Include Association](include_association.md)
+  * [Exclude Association](exclude_association.md)
+  * [Nullify Attributes](nullify.md)
+  * [Finalization](finalize.md)
+  * [After Clone](after_clone.md)
+  * [After Persist](after_persist.md)
+  * [Initialize Cloning Target](init_as.md)
+  * [Traits](traits.md)
+  * [Parameters](parameters.md)
+* Adapters
+  * [Supported Adapters](supported_adapters.md)
+  * [ActiveRecord](active_record.md)
+  * [Sequel](sequel.md)
+* Advanced Options
+  * [Implicit Cloner](implicit_cloner.md)
+  * [Inline Configuration](inline_configuration.md)
+  * [Clone mapper](clone_mapper.md)
+  * [Architecture](architecture.md)
+  * [Testing](testing.md)
+  * [Customization](customization.md)
+* Upgrade Notes
+  * [From v0.2.x to v1.0.0](from_v02_to_v1.md)

data/docs/active_record.md

@@ -0,0 +1,33 @@
+# Active Record
+
+Clowne provides an optional ActiveRecord integration which allows you to configure cloners in your models and adds a shortcut to invoke cloners (`#clowne` method).
+
+To enable this integration, you must require `"clowne/adapters/active_record/dsl"` somewhere in your app, e.g., in the initializer:
+
+```ruby
+# config/initializers/clowne.rb
+require "clowne/adapters/active_record/dsl"
+Clowne.default_adapter = :active_record
+```
+
+Now you can specify cloning configs in your AR models:
+
+```ruby
+class User < ActiveRecord::Base
+  clowne_config do
+    include_associations :profile
+
+    nullify :email
+
+    # whatever available for your cloners,
+    # active_record adapter is set implicitly here
+  end
+end
+```
+
+And then you can clone objects like this:
+
+```ruby
+user.clowne(traits: my_traits, **params).to_record
+# => <#User id: nil...>
+```

data/docs/after_clone.md

@@ -0,0 +1,53 @@
+# After Clone
+
+The `after_clone` callbacks can help you to make additional operations on cloned record, like checking it with some business logic or actualizing cloned record attributes, before it will be saved to the database. Also it can help to avoid unneeded usage of [`after_persist`](after_persist) callbacks, and additional queries to database.
+
+Examples:
+
+```ruby
+class User < ActiveRecord::Base
+  # create_table :users do |t|
+  #   t.string :login
+  #   t.integer :draft_count
+  # end
+
+  has_many :posts # all user's posts
+end
+
+class Post < ActiveRecord::Base
+  # create_table :posts do |t|
+  #   t.integer :user_id
+  #   t.boolean :is_draft
+  # end
+
+  scope :draft, -> { where is_draft: true }
+end
+
+class UserCloner < Clowne::Cloner
+# clone user and his posts, which is drafts
+  include_association :posts, scope: :draft
+
+  after_clone do |_origin, clone, **|
+    # actualize user attribute
+    clone.draft_count = clone.posts.count
+  end
+end
+```
+
+`after_clone` runs when you call `Operation#to_record` or [`Operation#persist`](operation) (or `Operation#persist!`)
+
+```ruby
+# prepare data
+user = User.create
+3.times { Post.create(user: user, is_draft: false) }
+2.times { Post.create(user: user, is_draft: true) }
+
+operation = UserCloner.call(user)
+# => <#Clowne::Utils::Operation ...>
+
+clone = operation.to_record
+# => <#User id: nil, draft_count: 2 ...>
+
+clone.draft_count == user.posts.draft.count
+# => true
+```

data/docs/after_persist.md

@@ -0,0 +1,77 @@
+# 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) 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) (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/architecture.md

@@ -0,0 +1,138 @@
+# Architecture
+
+This post aims to help developers and contributors to understand how Clowne works under the hood.
+
+There are two main notions we want to talk about: **declaration set** and **cloning plan**.
+
+## Declaration set
+
+_Declaration set_ is a result of calling Clowne DSL methods in the cloner class. There is (almost) one-to-one correspondence between configuration calls and declarations.
+
+Consider an example:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  include_association :profile
+  include_association :posts
+
+  nullify :external_id, :slug
+
+  trait :with_social_profile do
+    include_association :social_profiles
+  end
+end
+```
+
+This cloner's declaration set contains 3 declarations. You can access it through `.declarations` method:
+
+```ruby
+UserCloner.declarations #=>
+# [
+#   <#Clowne::Declarations::IncludeAssociation...>,
+#   <#Clowne::Declarations::IncludeAssociation...>,
+#   <#Clowne::Declarations::Nullify...>
+# ]
+```
+
+**NOTE:** `include_associations` and `exclude_associations` methods are just syntactic sugar, so they produce multiple declarations.
+
+Traits are not included in the declaration set. Moreover, each trait is just a wrapper over a declaration set. You can access traits through `.traits` method:
+
+```ruby
+UserCloner.traits #=>
+# {
+#   with_social_profiles: <#Clowne::Declarations::Trait...>
+# }
+
+UserCloner.traits[:with_social_profiles].declarations #=>
+# [
+#   <#Clowne::Declarations::IncludeAssociation...>
+# ]
+```
+
+## Cloning plan
+
+Every time you use a cloner the corresponding declaration set (which is the cloner itself declarations combined with all the specified traits declaration sets) is compiled into a _cloning plan_.
+
+The process is straightforward: starting with an empty `Plan`, we're applying every declaration to it.
+Every declaration object must implement `#compile(plan)` method, which populates the plan with _actions_. For example:
+
+```ruby
+class IncludeAssociation
+  def compile(plan)
+    # add a `name` key with the specified value (self)
+    # to :association set
+    plan.add_to(:association, name, self)
+  end
+end
+```
+
+`Plan` supports 3 types of registers:
+
+1) Scalars:
+
+```ruby
+plan.set(key, value)
+plan.remove(key)
+```
+
+Used by [`init_as`](init_as.md) declaration.
+
+2) Append-only lists:
+
+```ruby
+plan.add(key, value)
+```
+
+Used by [`nullify`](nullify.md) and [`finalize`](finalize.md) declarations.
+
+3) Two-phase set (2P-Set\*):
+
+```ruby
+plan.add_to(type, key, value)
+plan.remove_from(type, key)
+```
+
+Used by [`include_association`](include_association.md) and [`exclude_association`](exclude_association.md).
+
+
+\* Operations over [2P-Set](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type#2P-Set_(Two-Phase_Set)) (adding/removing) do not depend on the order of execution; we use "remove-wins" semantics, i.e., when a key has been removed, it cannot be re-added.
+
+Thus, the resulting plan is just a key-value storage.
+
+## Plan resolving
+
+The final step in the cloning process is to apply the compiled plan to a record.
+
+Every adapter registers its own resolvers for each plan _key_ (or _action_). The [order of execution](getting_started?id=execution-order) is also specified by the adapter.
+
+For example, you can override `:nullify` resolver to handle associations:
+
+```ruby
+module NullifyWithAssociation
+  def self.call(source, record, declaration, _params)
+    reflection = source.class.reflections[declaration.name.to_s]
+
+    # fallback to built-in nullify
+    if reflection.nil?
+      Clowne::Adapters::Base::Nullify.call(source, record, declaration)
+    else
+      association = record.__send__(declaration.name)
+      next record if association.nil?
+
+      association.is_a?(ActiveRecord::Relation) ? association.destroy_all : association.destroy
+      record.association(declaration.name).reset
+
+      # resolver must return cloned record
+      record
+    end
+  end
+end
+
+Clowne::Adapters::ActiveRecord.register_resolver(
+  :nullify,
+  NullifyWithAssociation,
+  # specify the order of execution (available options are `prepend`, `before`, `after`)
+  before: :finalize
+)
+```