clowne 0.1.0.pre1 → 1.2.0

data/docs/exclude_association.md

@@ -0,0 +1,61 @@
+# 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)).
+
+Nevertheless, sometimes you might want to exclude already added associations (when inheriting a cloner or using [traits](traits.md)).
+
+Consider an example:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  include_association :posts
+
+  trait :without_posts do
+    exclude_association :posts
+  end
+end
+
+# copy user and posts
+clone = UserCloner.call(user).to_record
+clone.posts.count == user.posts.count
+# => true
+
+# copy only user
+clone2 = UserCloner.call(user, traits: :without_posts).to_record
+clone2.posts
+# => []
+```
+
+**NOTE**: once excluded association cannot be re-included, e.g. the following cloner:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  exclude_association :comments
+
+  trait :with_comments do
+    # That wouldn't work
+    include_association :comments
+  end
+end
+
+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
+(or inheriting cloners).
+
+## Exclude multiple associations
+
+It's possible to exclude multiple associations at once the same way as [`include_associations`](include_association.md):
+
+```ruby
+class UserCloner < Clowne::Cloner
+  include_associations :accounts, :posts, :comments
+
+  trait :without_posts do
+    exclude_associations :posts, :comments
+  end
+end
+```

data/docs/finalize.md

@@ -0,0 +1,31 @@
+# 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!"
+  end
+
+  trait :change_email do
+    finalize do |_source, record, params|
+      record.email = params[:email]
+    end
+  end
+end
+
+cloned = UserCloner.call(user).to_record
+cloned.name
+# => 'This is copy!'
+cloned.email == "clone@example.com"
+# => false
+
+cloned2 = UserCloner.call(user, traits: :change_email).to_record
+cloned2.name
+# => 'This is copy!'
+cloned2.email
+# => 'clone@example.com'
+```
+
+Finalization blocks are called at the end of the [cloning process](getting_started?id=execution-order).

data/docs/from_v02_to_v1.md

@@ -0,0 +1,83 @@
+# 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.*
+
+```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
+```
+## 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`
+
+```ruby
+# Before
+record_wrapper = UserCloner.call(user)
+clone = record_wrapper.to_model
+clone.save
+
+# After
+clone = UserCloner.call(user).tap(&:persist).to_record
+```

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

@@ -0,0 +1,33 @@
+# Implicit Cloner
+
+When [cloning associations](include_association.md) Clowne tries to infer an appropriate cloner class for the records (unless `clone_with` specified).
+
+It relies on the naming convention: `MyModel` -> `MyModelCloner`.
+
+Consider an example:
+
+```ruby
+class User < ActiveRecord::Base
+  has_one :profile
+end
+
+class UserCloner < Clowne::Cloner
+  include_association :profile
+end
+
+class ProfileCloner < Clowne::Cloner
+  finalize do |source, record|
+    record.name = "Clone of #{source.name}"
+  end
+end
+
+user = User.last
+user.profile.name
+#=> "Bimbo"
+
+cloned = UserCloner.call(user).to_record
+cloned.profile.name
+# => "Clone of Bimbo"
+```
+
+**NOTE:** when using [in-model cloner](active_record.md) for ActiveRecord it is used by default.

data/docs/include_association.md

@@ -0,0 +1,133 @@
+# Include Association
+
+Use this declaration to clone model's associations:
+
+```ruby
+class User < ActiveRecord::Base
+  has_one :profile
+end
+
+class UserCloner < Clowne::Cloner
+  include_association :profile
+end
+```
+
+Looks pretty simple, right? But that's not all we may offer you! :)
+
+The declaration supports additional arguments:
+
+```ruby
+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:
+- `Symbol` - named scope.
+- `Proc` - custom scope (supports parameters).
+
+Example:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :accounts
+  has_many :posts
+end
+
+class Account < ActiveRecord::Base
+  scope :active, -> { where(active: true) }
+end
+
+class Post < ActiveRecord::Base
+  # t.string :status
+end
+
+class UserCloner < Clowne::Cloner
+  include_association :accounts, :active
+  include_association :posts, ->(params) { where(state: params[:state]) }
+end
+
+# Clone only draft posts
+UserCloner.call(user, state: :draft).to_record
+# => <#User id: nil, ... >
+```
+
+## Options
+
+The following options are available:
+- `:clone_with` - use custom cloner\*
+- `:traits` - define special traits.
+
+\* **NOTE:** the same cloner class would be used for **all children**
+
+Example:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  # t.string :title
+  has_many :tags
+end
+```
+
+```ruby
+class PostSpecialCloner < Clowne::Cloner
+  nullify :title
+
+  trait :with_tags do
+    include_association :tags
+  end
+end
+
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_association :posts, clone_with: PostSpecialCloner
+  # or clone user's posts with tags!
+  # include_association :posts, clone_with: PostSpecialCloner, traits: :with_tags
+end
+
+UserCloner.call(user).to_record
+# => <#User id: nil, ... >
+```
+
+**NOTE**: if custom cloner is not defined, Clowne tries to infer the [implicit cloner](implicit_cloner.md).
+
+## Nested parameters
+
+Follow to [documentation page](parameters.md).
+
+## Include multiple associations
+
+You can include multiple associations at once too:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :accounts
+  has_many :posts
+end
+
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_associations :accounts, :posts
+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.