clowne 1.3.0 → 1.5.0

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.

data/docs/testing.md

@@ -1,194 +0,0 @@
-# Testing
-
-Clowne provides specific tools to help you test your cloners.
-
-The main goal is to make it possible to test different cloning phases separately and avoid _heavy_ tests setup phases.
-
-Let's consider the following models and cloners:
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  has_one :profile
-  has_many :posts
-end
-
-# app/models/post.rb
-class Post < ApplicationRecord
-  has_many :comments
-  has_many :votes
-
-  scope :draft, -> { where(draft: true) }
-end
-
-# app/cloners/user_cloner.rb
-class UserCloner < Clowne::Cloner
-  class ProfileCloner
-    nullify :rating
-  end
-
-  include_association :profile, clone_with: ProfileCloner
-
-  nullify :email
-
-  finalize do |_, record, name: nil, **|
-    record.name = name unless name.nil?
-  end
-
-  trait :copy do
-    init_as do |user, target:, **|
-      # copy name
-      target.name = user.name
-      target
-    end
-  end
-
-  trait :with_posts do
-    include_association :posts, :draft, traits: :mark_as_copy
-  end
-
-  trait :with_popular_posts do
-    include_association :posts, (lambda do |params|
-      where("rating > ?", params[:min_rating])
-    end)
-  end
-end
-
-# app/cloners/post_cloner.rb
-class PostCloner < Clowne::Cloner
-  include_association :comments
-
-  trait :mark_as_copy do |_, record|
-    record.title += " (copy)"
-  end
-end
-```
-
-## Getting started
-
-Currently, only [RSpec](http://rspec.info/) is supported.
-
-Add this line to your `spec_helper.rb` (or `rails_helper.rb`):
-
-```ruby
-require "clowne/rspec"
-```
-
-## Configuration matchers
-
-There are several matchers that allow you to verify the cloner configuration.
-
-### `clone_associations`
-
-This matcher vefifies that your cloner includes the specified associations:
-
-```ruby
-# spec/cloners/user_cloner_spec.rb
-RSpec.describe UserCloner, type: :cloner do
-  subject { described_class }
-
-  specify do
-    # checks that only the specified associations is included
-    is_expected.to clone_associations(:profile)
-
-    # with traits
-    is_expected.to clone_associations(:profile, :posts)
-      .with_traits(:with_posts)
-
-    # raises when there are some unspecified associations
-    is_expected.to clone_associations(:profile)
-      .with_traits(:with_posts)
-    #=> raises RSpec::Expectations::ExpectationNotMetError
-  end
-end
-```
-
-### `clone_association`
-
-This matcher allows to verify the specified association options:
-
-```ruby
-# spec/cloners/user_cloner_spec.rb
-RSpec.describe UserCloner, type: :cloner do
-  subject { described_class }
-
-  specify do
-    # simply check that association is included
-    is_expected.to clone_association(:profile)
-
-    # check options
-    is_expected.to clone_association(
-      :profile,
-      clone_with: described_class::ProfileCloner
-    )
-
-    # with traits, scope and activated trait
-    is_expected.to clone_association(
-      :posts,
-      traits: :mark_as_copy,
-      scope: :draft
-    ).with_traits(:with_posts)
-  end
-end
-```
-
-**NOTE:** `clone_associations`/`clone_association` matchers are only available in groups marked with `type: :cloner` tag.
-
-Clowne automaticaly marks all specs in `spec/cloners` folder with `type: :cloner`. Otherwise you have to add this tag you.
-
-
-## Using partial cloning
-
-Under the hood, Clowne builds a [compilation plan](architecture.md) which is used to clone the record.
-
-Plan is a set of _actions_ (such as `nullify`, `finalize`, `association`, `init_as`) which are applied to the record.
-
-Most of the time these actions don't depend on each other, thus we can test them separately:
-
-```ruby
-# spec/cloners/user_cloner_spec.rb
-RSpec.describe UserCloner, type: :cloner do
-  subject(:user) { create :user, name: "Bombon" }
-
-  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"
-  end
-
-  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"
-  end
-
-  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"
-  end
-
-  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
-    ).to_record
-
-    expect(cloned_user.posts.size).to eq 1
-    expect(cloned_user.posts.first.text).to eq "Flying Dumplings"
-  end
-end
-```

data/docs/traits.md

@@ -1,25 +0,0 @@
-# Traits
-
-Traits allow you to group cloner declarations together and then apply them (like in [`factory_bot`](https://github.com/thoughtbot/factory_bot)):
-
-```ruby
-class UserCloner < Clowne::Cloner
-  trait :with_posts do
-    include_association :posts
-  end
-
-  trait :with_profile do
-    include_association :profile
-  end
-
-  trait :nullify_name do
-    nullify :name
-  end
-end
-
-UserCloner.call(user, traits: %i[with_posts with_profile nullify_name])
-# or
-UserCloner.call(user, traits: :nullify_name)
-# or
-# ...
-```

data/gemfiles/activerecord42.gemfile

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

data/gemfiles/jruby.gemfile

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

data/gemfiles/railsmaster.gemfile

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

data/lib/clowne/ext/yield_self_then.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Clowne
-  module Ext # :nodoc: all
-    # Add yield_self and then if missing
-    module YieldSelfThen
-      module Ext
-        unless nil.respond_to?(:yield_self)
-          def yield_self
-            yield self
-          end
-        end
-
-        alias then yield_self
-      end
-
-      # See https://github.com/jruby/jruby/issues/5220
-      ::Object.include(Ext) if RUBY_PLATFORM.match?(/java/i)
-
-      refine Object do
-        include Ext
-      end
-    end
-  end
-end