clowne 1.4.0 → 1.5.0

data/docs/getting_started.md

@@ -1,171 +0,0 @@
-# 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,33 +0,0 @@
-# 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

@@ -1,133 +0,0 @@
-# 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.

data/docs/index.html

@@ -1,29 +0,0 @@
-<!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,40 +0,0 @@
-# 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.
-
-For example, Cloners could be used not only to generate _fresh_ new models but to apply some transformations to the existing record:
-
-
-```ruby
-class User < ApplicationRecord
-  has_one :profile
-  has_many :posts
-end
-
-class UserCloner < Clowne::Cloner
-  adapter :active_record
-
-  include_association :profile
-
-  trait :copy_settings do
-    # Use a `target` for all the actions
-    init_as { |_source, target:| target }
-  end
-end
-
-jack = User.find_by(email: "jack@evl.ms")
-# => <#User id: 1, ...>
-jack.create_profile(name: "Jack")
-# => <#Profile id: 1, name: 'Jack', ...>
-
-john = User.find_by(email: "john@evl.ms")
-# => <#User id: 2, ...>
-
-# we want to clone Jack's profile to John's user,
-# without creating a new one
-john_with_profile = UserCloner.call(jack, traits: :copy_settings, target: john).to_record
-# => <#User id: 2, ...>
-john_with_profile.profile
-#=> <#Profile id: nil, name: 'Jack',...>
-```

data/docs/inline_configuration.md

@@ -1,37 +0,0 @@
-# Inline Configuration
-
-You can also enhance the cloner configuration inline (i.e., add declarations dynamically):
-
-```ruby
-operation = UserCloner.call(User.last) do
-  exclude_association :profile
-
-  finalize do |source, record|
-    record.email = "clone_of_#{source.email}"
-  end
-end
-
-cloned = operation.to_record
-
-cloned.email
-# => "clone_of_john@example.com"
-
-# associations:
-cloned.posts.size == User.last.posts.size
-# => true
-cloned.profile
-# => nil
-```
-
-Inline enhancement doesn't affect the _global_ configuration so that you can use it without any fear.
-
-Thus it's also possible to clone objects without any cloner classes at all by using `Clowne::Cloner`:
-
-```ruby
-cloned = Clowne::Cloner.call(user) do
-  # anything you want!
-end.to_record
-
-cloned
-# => <#User..
-```

data/docs/nullify.md

@@ -1,33 +0,0 @@
-# Nullify Attributes
-
-To set a bunch of attributes to `nil` you can use the `nullify` declaration:
-
-```ruby
-class User < ActiveRecord::Base
-  # t.string :name
-  # t.string :surname
-  # t.string :email
-end
-
-class UserCloner < Clowne::Cloner
-  nullify :name, :email
-
-  trait :nullify_surname do
-    nullify :surname
-  end
-end
-
-clone = UserCloner.call(user).to_record
-clone.name.nil?
-# => true
-clone.email.nil?
-# => true
-clone.surname.nil?
-# => false
-
-clone2 = UserCloner.call(user, traits: :nullify_surname).to_record
-clone2.name.nil?
-# => true
-clone2.surname.nil?
-# => true
-```

data/docs/operation.md

@@ -1,55 +0,0 @@
-# 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`.
-
-An instance of `Operation` has a very clear interface:
-
-```ruby
-class User < ActiveRecord::Base; end
-
-class UserCloner < Clowne::Cloner
-  nullify :email
-
-  after_persist do |_origin, cloned, **|
-    cloned.update(email: "evl-#{cloned.id}.ms")
-  end
-end
-
-user = User.create(email: "evl.ms")
-# => <#User id: 1, email: 'evl.ms', ...>
-
-operation = UserCloner.call(user)
-
-# Return resulted (non saved) object:
-operation.to_record
-# => <#User id: nil, email: nil, ...>
-
-# Save cloned object and call after_persist callbacks:
-operation.persist # or operation.persist!
-# => true
-
-operation.to_record
-# => <#User id: 2, email: 'evl-2.ms', ...>
-
-# Call only after_persist callbacks:
-user2 = operation.to_record
-# => <#User id: 2, email: 'evl-2.ms', ...>
-user2.update(email: "admin@example.com")
-# => <#User id: 2, email: 'admin@example.com' ...>
-operation.run_after_persist
-# => <#User id: 2, email: 'evl-2.ms', ...>
-```
-
-The last example is weird, but it can be helpful when you need to execute `save` (or `save!`) separately from `after_persist` callbacks:
-
-```ruby
-operation = UserClone.call(user)
-
-# Wrap main cloning into the transaction
-ActiveRecord::Base.transaction do
-  operation.to_record.save!
-end
-
-# And after that execute after_persist without transaction
-operation.run_after_persist
-```

data/docs/parameters.md

@@ -1,112 +0,0 @@
-# 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.
-
-Example:
-
-```ruby
-class UserCloner < Clowne::Cloner
-  include_association :posts, ->(params) { where(state: params[:state]) }
-
-  finalize do |_source, record, **params|
-    record.email = params[:email]
-  end
-end
-
-operation = UserCloner.call(user, state: :draft, email: "cloned@example.com")
-cloned = operation.to_record
-cloned.email
-# => 'cloned@example.com'
-```
-
-## Potential Problems
-
-Clowne is born as a part of our big project and we use it for cloning really deep object relations. When we started to use params and forwarding them between parent-child cloners we got a nasty bugs.
-
-As result we strongly recommend to use ruby keyword arguments instead of params hash:
-
-```ruby
-# Bad
-finalize do |_source, record, **params|
-  record.email = params[:email]
-end
-
-# Good
-finalize do |_source, record, email:, **|
-  record.email = email
-end
-```
-
-## Nested Parameters
-
-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:
-
-```ruby
-class UserCloner < Clowne::Cloner
-  # Don't pass parameters to associations
-  trait :default do
-    include_association :profile
-    # equal to include_association :profile, params: false
-  end
-
-  # Pass all parameters to associations
-  trait :all_params do
-    include_association :profile, params: true
-  end
-
-  # Filter parameters by key.
-  # Notice: value by key must be a Hash.
-
-  trait :by_key do
-    include_association :profile, params: :profile
-  end
-
-  # Execute custom block with params as argument
-  trait :by_block do
-    include_association :profile, params: Proc.new do |params|
-      params[:profile].map { |k, v| [k, v.upcase] }.to_h
-    end
-  end
-
-  # Execute custom block with params and parent record as arguments
-  trait :by_block_with_parent do
-    include_association :profile, params: Proc.new do |params, user|
-      {
-        name: params[:profile][:name],
-        email: user.email
-      }
-    end
-  end
-end
-
-class ProfileCloner < Clowne::Cloner
-  finalize do |_source, record, **params|
-    record.jsonb_field = params
-  end
-end
-
-# Execute:
-
-def get_profile_jsonb(user, trait)
-  params = {profile: {name: "John", surname: "Cena"}}
-  cloned = UserCloner.call(user, traits: trait, **params).to_record
-  cloned.profile.jsonb_field
-end
-
-get_profile_jsonb(user, :default)
-# => {}
-
-get_profile_jsonb(user, :all_params)
-# => { profile: { name: 'John', surname: 'Cena' } }
-
-get_profile_jsonb(user, :by_key)
-# => { name: 'John', surname: 'Cena' }
-
-get_profile_jsonb(user, :by_block)
-# => { name: 'JOHN', surname: 'CENA' }
-
-get_profile_jsonb(user, :by_block_with_parent)
-# => { name: 'JOHN', email: user.email }
-```

data/docs/sequel.md

@@ -1,50 +0,0 @@
-# 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.
-
-Example:
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter :sequel
-
-  include_association :account
-end
-
-class User < Sequel::Model
-  # Configure NestedAttributes plugin
-  plugin :nested_attributes
-
-  one_to_one :account
-  nested_attributes :account
-end
-```
-
-and get cloned user
-
-```ruby
-user = User.last
-operation = UserCloner.call(user)
-# => <#Clowne::Adapters::Sequel::Operation...>
-cloned = operation.to_record
-# => <#User id: nil, ...>
-cloned.new?
-# => true
-```
-
-or you can save it immediately
-
-```ruby
-user = User.last
-# => <#User id: 1, ...>
-operation = UserCloner.call(user)
-# => <#Clowne::Adapters::Sequel::Operation...>
-operation.persist
-# => true
-cloned = operation.to_record
-# => <#User id: 2, ...>
-cloned.new?
-# => false
-```
-
-If you try to clone association without `NestedAttributes` plugin, Clowne will skip this declaration.

data/docs/supported_adapters.md

@@ -1,10 +0,0 @@
-# Supported Adapters
-
-Clowne supports the following ORM adapters (and associations):
-
-Adapter                                            |1:1         | 1:M         | M:M                     |
----------------------------------------------------|------------|-------------|-------------------------|
-[: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.