clowne 1.0.0 → 1.4.0

data/docs/customization.md

@@ -1,7 +1,4 @@
----
-id: customization
-title: Customization
----
+# Customization
 
 Clowne is built with extensibility in mind. You can create your own DSL commands and resolvers.
 

data/docs/exclude_association.md

@@ -1,7 +1,4 @@
----
-id: exclude_association
-title: Exclude Association
----
+# Exclude Association
 
 Clowne doesn't include any association by default and doesn't provide _magic_ `include_all` declaration (although you can [add one by yourself](customization.md)).
 

data/docs/finalize.md

@@ -1,19 +1,15 @@
----
-id: finalize
-title: Finalization
-sidebar_label: Finalize
----
+# Finalization
 
 To apply custom transformations to the cloned record, you can use the `finalize` declaration:
 
 ```ruby
 class UserCloner < Clowne::Cloner
-  finalize do |_source, record, _params|
-    record.name = 'This is copy!'
+  finalize do |_source, record, **_params|
+    record.name = "This is copy!"
   end
 
   trait :change_email do
-    finalize do |_source, record, params|
+    finalize do |_source, record, **params|
       record.email = params[:email]
     end
   end
@@ -22,7 +18,7 @@ end
 cloned = UserCloner.call(user).to_record
 cloned.name
 # => 'This is copy!'
-cloned.email == 'clone@example.com'
+cloned.email == "clone@example.com"
 # => false
 
 cloned2 = UserCloner.call(user, traits: :change_email).to_record
@@ -32,4 +28,4 @@ cloned2.email
 # => 'clone@example.com'
 ```
 
-Finalization blocks are called at the end of the [cloning process](execution_order.md).
+Finalization blocks are called at the end of the [cloning process](getting_started?id=execution-order).

data/docs/from_v02_to_v1.md

@@ -1,7 +1,4 @@
----
-id: from_v02_to_v10
-title: From v0.2.x to v1.0.0
----
+# 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.
 
@@ -37,9 +34,8 @@ clone.persisted?
 
 ### 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._
+*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)
@@ -56,8 +52,6 @@ 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`
@@ -78,7 +72,6 @@ clone.new?
 
 ### 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)
@@ -88,4 +81,3 @@ clone.save
 # After
 clone = UserCloner.call(user).tap(&:persist).to_record
 ```
-<span style="display:none;"># rubocop:enable all</span>

data/docs/getting_started.md

@@ -0,0 +1,171 @@
+# Getting Started
+
+## Installation
+
+To install Clowne with RubyGems:
+
+```ruby
+gem install clowne
+```
+
+Or add this line to your application's Gemfile:
+
+```ruby
+gem "clowne"
+```
+
+## Configuration
+
+Basic cloner implementation looks like:
+
+```ruby
+class SomeCloner < Clowne::Cloner
+  adapter :active_record # or adapter Clowne::Adapters::ActiveRecord
+  # some implementation ...
+end
+```
+
+You can configure the default adapter for cloners:
+
+```ruby
+# put to initializer
+# e.g. config/initializers/clowne.rb
+Clowne.default_adapter = :active_record
+```
+
+and skip explicit adapter declaration
+
+```ruby
+class SomeCloner < Clowne::Cloner
+  # some implementation ...
+end
+```
+See the list of [available adapters](supported_adapters.md).
+
+## Basic Example
+
+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
+```
+
+## Overview
+
+In [the basic example](#basic-example), you can see that Clowne consists of flexible DSL which is used in a class inherited of `Clowne::Cloner`.
+
+You can combinate this DSL via [`traits`](traits.md) and make a cloning plan which exactly you want.
+
+**We strongly recommend [`write tests`](testing.md) to cover resulting cloner logic**
+
+Cloner class returns [`Operation`](operation.md) instance as a result of cloning. The operation provides methods to save cloned record. You can wrap this call to a transaction if it is necessary.
+
+### Execution Order
+
+The order of cloning actions depends on the adapter (i.e., could be customized).
+
+All built-in adapters have the same order and what happens when you call `Operation#persist`:
+- init clone (see [`init_as`](init_as.md)) (empty by default)
+- [`clone associations`](include_association.md)
+- [`nullify`](nullify.md) attributes
+- run [`finalize`](finalize.md) blocks. _The order of [`finalize`](finalize.md) blocks is the order they've been written._
+- run [`after_clone`](after_clone.md) callbacks
+- __SAVE CLONED RECORD__
+- run [`after_persist`](after_persist.md) callbacks
+
+## Motivation & Alternatives
+
+### Why did we decide to build our own cloning gem instead of using the existing solutions?
+
+First, the existing solutions turned out not to be stable and flexible enough for us.
+
+Secondly, they are Rails-only (or, more precisely, ActiveRecord-only).
+
+Nevertheless, thanks to [amoeba](https://github.com/amoeba-rb/amoeba) and [deep_cloneable](https://github.com/moiristo/deep_cloneable) for inspiration.
+
+For ActiveRecord we support amoeba-like [in-model configuration](active_record.md) and you can add missing DSL declarations yourself [easily](customization.md).
+
+We also provide an ability to specify cloning [configuration in-place](inline_configuration.md) like `deep_clonable` does.
+
+So, we took the best of these too and brought to the outside-of-Rails world.
+
+### Why build a gem to clone models at all?
+
+That's a good question. Of course, you can write plain old Ruby services do handle the cloning logic. But for complex models hierarchies, this approach has major disadvantages: high code complexity and lack of re-usability.
+
+The things become even worse when you deal with STI models and different cloning contexts.
+
+That's why we decided to build a specific cloning tool.

data/docs/implicit_cloner.md

@@ -1,7 +1,4 @@
----
-id: implicit_cloner
-title: Implicit Cloner
----
+# Implicit Cloner
 
 When [cloning associations](include_association.md) Clowne tries to infer an appropriate cloner class for the records (unless `clone_with` specified).
 

data/docs/include_association.md

@@ -1,7 +1,4 @@
----
-id: include_association
-title: Include Association
----
+# Include Association
 
 Use this declaration to clone model's associations:
 
@@ -23,6 +20,13 @@ The declaration supports additional arguments:
 include_association name, scope, options
 ```
 
+### Supported Associations
+
+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     |
+
 ## Scope
 
 Scope can be a:
@@ -121,3 +125,9 @@ end
 ```
 
 **NOTE:** in that case, it's not possible to provide custom scopes and options.
+
+### Belongs To association
+
+You can include belongs_to association, but will do it carefully.
+If you have loop by relations in your models, when you clone it will raise SystemStackError.
+Check this [test](https://github.com/palkan/clowne/blob/master/spec/clowne/integrations/active_record_belongs_to_spec.rb) for instance.

data/docs/index.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="assets/vue.css">
+  <link rel="stylesheet" href="assets/styles.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'Clowne',
+      repo: 'https://github.com/clowne-rb/clowne',
+      loadSidebar: true,
+      subMaxLevel: 2,
+      auto2top: true,
+      search: {
+        namespace: 'clowne'
+      }
+    }
+  </script>
+  <script src="assets/docsify.min.js"></script>
+  <script src="assets/prism-ruby.min.js"></script>
+</body>
+</html>

data/docs/init_as.md

@@ -1,8 +1,4 @@
----
-id: init_as
-title: Initialize Cloning Target
-sidebar_label: Init As
----
+# Initialize Cloning Target
 
 You can override the default Clowne method which generates a _plain_ copy of a source object.
 By default, Clowne initiates the cloned record using a `#dup` method.
@@ -27,12 +23,12 @@ class UserCloner < Clowne::Cloner
   end
 end
 
-jack = User.find_by(email: 'jack@evl.ms')
+jack = User.find_by(email: "jack@evl.ms")
 # => <#User id: 1, ...>
-jack.create_profile(name: 'Jack')
+jack.create_profile(name: "Jack")
 # => <#Profile id: 1, name: 'Jack', ...>
 
-john = User.find_by(email: 'john@evl.ms')
+john = User.find_by(email: "john@evl.ms")
 # => <#User id: 2, ...>
 
 # we want to clone Jack's profile to John's user,

data/docs/inline_configuration.md

@@ -1,7 +1,4 @@
----
-id: inline_configuration
-title: Inline Configuration
----
+# Inline Configuration
 
 You can also enhance the cloner configuration inline (i.e., add declarations dynamically):
 

data/docs/nullify.md

@@ -1,8 +1,4 @@
----
-id: nullify
-title: Nullify Attributes
-sidebar_label: Nullify
----
+# Nullify Attributes
 
 To set a bunch of attributes to `nil` you can use the `nullify` declaration:
 

data/docs/operation.md

@@ -1,7 +1,4 @@
----
-id: operation
-title: Operation
----
+# Operation
 
 Since version 1.0 Clowne has been returning specific result object instead of a raw cloned object. It has allowed unifying interface between adapters and has opened an opportunity to implement new features. We call this object `Operation`.
 
@@ -14,11 +11,11 @@ class UserCloner < Clowne::Cloner
   nullify :email
 
   after_persist do |_origin, cloned, **|
-    cloned.update_attributes(email: "evl-#{cloned.id}.ms")
+    cloned.update(email: "evl-#{cloned.id}.ms")
   end
 end
 
-user = User.create(email: 'evl.ms')
+user = User.create(email: "evl.ms")
 # => <#User id: 1, email: 'evl.ms', ...>
 
 operation = UserCloner.call(user)
@@ -37,7 +34,7 @@ operation.to_record
 # Call only after_persist callbacks:
 user2 = operation.to_record
 # => <#User id: 2, email: 'evl-2.ms', ...>
-user2.update_attributes(email: 'admin@example.com')
+user2.update(email: "admin@example.com")
 # => <#User id: 2, email: 'admin@example.com' ...>
 operation.run_after_persist
 # => <#User id: 2, email: 'evl-2.ms', ...>

data/docs/parameters.md

@@ -1,7 +1,4 @@
----
-id: parameters
-title: Parameters
----
+# Parameters
 
 Clowne provides parameters for make your cloning logic more flexible. You can see their using in [`include_association`](include_association.md#scope) and [`finalize`](finalize.md) documentation pages.
 
@@ -11,12 +8,12 @@ Example:
 class UserCloner < Clowne::Cloner
   include_association :posts, ->(params) { where(state: params[:state]) }
 
-  finalize do |_source, record, params|
+  finalize do |_source, record, **params|
     record.email = params[:email]
   end
 end
 
-operation = UserCloner.call(user, state: :draft, email: 'cloned@example.com')
+operation = UserCloner.call(user, state: :draft, email: "cloned@example.com")
 cloned = operation.to_record
 cloned.email
 # => 'cloned@example.com'
@@ -30,7 +27,7 @@ As result we strongly recommend to use ruby keyword arguments instead of params
 
 ```ruby
 # Bad
-finalize do |_source, record, params|
+finalize do |_source, record, **params|
   record.email = params[:email]
 end
 
@@ -42,7 +39,7 @@ end
 
 ## Nested Parameters
 
-Also we implemented control over the parameters for cloning associations (you can read more [here](https://github.com/palkan/clowne/issues/15)).
+Also we implemented control over the parameters for cloning associations (you can read more [here](https://github.com/clowne-rb/clowne/issues/15)).
 
 Let's explain what the difference:
 
@@ -85,7 +82,7 @@ class UserCloner < Clowne::Cloner
 end
 
 class ProfileCloner < Clowne::Cloner
-  finalize do |_source, record, params|
+  finalize do |_source, record, **params|
     record.jsonb_field = params
   end
 end
@@ -93,7 +90,7 @@ end
 # Execute:
 
 def get_profile_jsonb(user, trait)
-  params = { profile: { name: 'John', surname: 'Cena' } }
+  params = {profile: {name: "John", surname: "Cena"}}
   cloned = UserCloner.call(user, traits: trait, **params).to_record
   cloned.profile.jsonb_field
 end

data/docs/sequel.md

@@ -1,7 +1,4 @@
----
-id: sequel
-title: Sequel
----
+# Sequel
 
 Under the hood, Clowne uses Sequel [`NestedAttributes` plugin](http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/NestedAttributes.html) for cloning source's associations, and you need to configure it.
 

data/docs/supported_adapters.md

@@ -1,13 +1,10 @@
----
-id: supported_adapters
-title: Supported Adapters
----
+# Supported Adapters
 
 Clowne supports the following ORM adapters (and associations):
 
 Adapter                                            |1:1         | 1:M         | M:M                     |
 ---------------------------------------------------|------------|-------------|-------------------------|
-[:active_record](/docs/active_record.html)         | has_one    | has_many    | has_and_belongs_to_many |
-[:sequel](/docs/sequel.html)                       | one_to_one | one_to_many | many_to_many            |
+[:active_record](active_record)         | has_one    | has_many    | has_and_belongs_to_many |
+[:sequel](sequel)                       | one_to_one | one_to_many | many_to_many            |
 
 For more information see the corresponding adapter documentation.

data/docs/testing.md

@@ -1,7 +1,4 @@
----
-id: testing
-title: Testing
----
+# Testing
 
 Clowne provides specific tools to help you test your cloners.
 
@@ -52,7 +49,7 @@ class UserCloner < Clowne::Cloner
 
   trait :with_popular_posts do
     include_association :posts, (lambda do |params|
-      where('rating > ?', params[:min_rating])
+      where("rating > ?", params[:min_rating])
     end)
   end
 end
@@ -62,7 +59,7 @@ class PostCloner < Clowne::Cloner
   include_association :comments
 
   trait :mark_as_copy do |_, record|
-    record.title += ' (copy)'
+    record.title += " (copy)"
   end
 end
 ```
@@ -74,7 +71,7 @@ Currently, only [RSpec](http://rspec.info/) is supported.
 Add this line to your `spec_helper.rb` (or `rails_helper.rb`):
 
 ```ruby
-require 'clowne/rspec'
+require "clowne/rspec"
 ```
 
 ## Configuration matchers
@@ -151,47 +148,47 @@ Most of the time these actions don't depend on each other, thus we can test them
 ```ruby
 # spec/cloners/user_cloner_spec.rb
 RSpec.describe UserCloner, type: :cloner do
-  subject(:user) { create :user, name: 'Bombon' }
+  subject(:user) { create :user, name: "Bombon" }
 
-  specify 'simple case' do
+  specify "simple case" do
     # apply only the specified part of the plan
     cloned_user = described_class.partial_apply(:nullify, user).to_record
     expect(cloned_user.email).to be_nil
     # finalize wasn't applied
-    expect(cloned_user.name).to eq 'Bombon'
+    expect(cloned_user.name).to eq "Bombon"
   end
 
-  specify 'with params' do
-    cloned_user = described_class.partial_apply(:finalize, user, name: 'new name').to_record
+  specify "with params" do
+    cloned_user = described_class.partial_apply(:finalize, user, name: "new name").to_record
     # nullify actions were not applied!
     expect(cloned_user.email).to eq user.email
     # finalize was applied
-    expect(cloned_user.name).to eq 'new name'
+    expect(cloned_user.name).to eq "new name"
   end
 
-  specify 'with traits' do
-    a_user = create(:user, name: 'Dindon')
+  specify "with traits" do
+    a_user = create(:user, name: "Dindon")
     cloned_user = described_class.partial_apply(
       :init_as, user, traits: :copy, target: a_user
     ).to_record
     # returned user is the same as target
     expect(cloned_user).to be_eql(a_user)
-    expect(cloned_user.name).to eq 'Bombon'
+    expect(cloned_user.name).to eq "Bombon"
   end
 
-  specify 'associations' do
-    create(:post, user: user, rating: 1, text: 'Boom Boom')
-    create(:post, user: user, rating: 2, text: 'Flying Dumplings')
+  specify "associations" do
+    create(:post, user: user, rating: 1, text: "Boom Boom")
+    create(:post, user: user, rating: 2, text: "Flying Dumplings")
 
     # you can specify which associations to include (you can use array)
     # to apply all associations write:
     #   plan.apply(:association)
     cloned_user = described_class.partial_apply(
-      'association.posts', user, traits: :with_popular_posts, min_rating: 1
+      "association.posts", user, traits: :with_popular_posts, min_rating: 1
     ).to_record
 
     expect(cloned_user.posts.size).to eq 1
-    expect(cloned_user.posts.first.text).to eq 'Flying Dumplings'
+    expect(cloned_user.posts.first.text).to eq "Flying Dumplings"
   end
 end
 ```

data/docs/traits.md

@@ -1,7 +1,4 @@
----
-id: traits
-title: Traits
----
+# Traits
 
 Traits allow you to group cloner declarations together and then apply them (like in [`factory_bot`](https://github.com/thoughtbot/factory_bot)):
 

data/gemfiles/activerecord42.gemfile

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
-gem 'activerecord', '~> 4.2'
-gem 'sequel', '>= 5.0'
-gem 'sqlite3', '~> 1.3.6'
+gem "activerecord", "~> 4.2"
+gem "sequel", ">= 5.0"
+gem "sqlite3", "~> 1.3.13"
 
-gemspec path: '..'
+gemspec path: ".."

data/gemfiles/jruby.gemfile

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
-gem 'activerecord-jdbcsqlite3-adapter', '~> 50.0'
-gem 'jdbc-sqlite3'
-gem 'activerecord', '~> 5.0.0'
-gem 'sequel', '>= 5.0'
+gem "activerecord-jdbcsqlite3-adapter", "~> 50.0"
+gem "jdbc-sqlite3"
+gem "activerecord", "~> 5.0.0"
+gem "sequel", ">= 5.0"
 
-gemspec path: '..'
+gemspec path: ".."

data/gemfiles/railsmaster.gemfile

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
-gem 'arel', github: 'rails/arel'
-gem 'rails', github: 'rails/rails'
-gem 'sequel', github: 'jeremyevans/sequel'
-gem 'sqlite3'
+gem "arel", github: "rails/arel"
+gem "rails", github: "rails/rails"
+gem "sequel", github: "jeremyevans/sequel"
+gem "sqlite3"
 
-gemspec path: '..'
+gemspec path: ".."

data/lib/clowne/adapters/active_record/associations/base.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'clowne/adapters/base/association'
+require "clowne/adapters/base/association"
 
 module Clowne
   module Adapters # :nodoc: all