RubyGems - clowne - Versions diffs - 0.1.0.pre1 → 1.2.0 - Mend

clowne 0.1.0.pre1 → 1.2.0

Files changed (108) hide show

checksums.yaml +5 -5
data/.codeclimate.yml +7 -0
data/.gitattributes +1 -0
data/.gitignore +1 -0
data/.rubocop.yml +16 -33
data/.travis.yml +14 -10
data/CHANGELOG.md +39 -2
data/Gemfile +11 -6
data/README.md +48 -384
data/Rakefile +3 -3
data/clowne.gemspec +16 -8
data/docs/.nojekyll +0 -0
data/docs/.rubocop.yml +18 -0
data/docs/CNAME +1 -0
data/docs/README.md +131 -0
data/docs/_sidebar.md +25 -0
data/docs/active_record.md +33 -0
data/docs/after_clone.md +53 -0
data/docs/after_persist.md +77 -0
data/docs/architecture.md +138 -0
data/docs/assets/docsify.min.js +1 -0
data/docs/assets/prism-ruby.min.js +1 -0
data/docs/assets/styles.css +348 -0
data/docs/assets/vue.css +1 -0
data/docs/clone_mapper.md +59 -0
data/docs/customization.md +63 -0
data/docs/exclude_association.md +61 -0
data/docs/finalize.md +31 -0
data/docs/from_v02_to_v1.md +83 -0
data/docs/getting_started.md +171 -0
data/docs/implicit_cloner.md +33 -0
data/docs/include_association.md +133 -0
data/docs/index.html +29 -0
data/docs/init_as.md +40 -0
data/docs/inline_configuration.md +37 -0
data/docs/nullify.md +33 -0
data/docs/operation.md +55 -0
data/docs/parameters.md +112 -0
data/docs/sequel.md +50 -0
data/docs/supported_adapters.md +10 -0
data/docs/testing.md +194 -0
data/docs/traits.md +25 -0
data/gemfiles/activerecord42.gemfile +7 -4
data/gemfiles/jruby.gemfile +8 -4
data/gemfiles/railsmaster.gemfile +8 -5
data/lib/clowne.rb +12 -7
data/lib/clowne/adapters/active_record.rb +6 -16
data/lib/clowne/adapters/active_record/associations.rb +8 -6
data/lib/clowne/adapters/active_record/associations/base.rb +5 -49
data/lib/clowne/adapters/active_record/associations/belongs_to.rb +29 -0
data/lib/clowne/adapters/active_record/associations/has_one.rb +9 -1
data/lib/clowne/adapters/active_record/associations/noop.rb +4 -1
data/lib/clowne/adapters/active_record/dsl.rb +33 -0
data/lib/clowne/adapters/active_record/resolvers/association.rb +38 -0
data/lib/clowne/adapters/base.rb +53 -41
data/lib/clowne/adapters/base/association.rb +78 -0
data/lib/clowne/adapters/registry.rb +54 -11
data/lib/clowne/adapters/sequel.rb +29 -0
data/lib/clowne/adapters/sequel/associations.rb +26 -0
data/lib/clowne/adapters/sequel/associations/base.rb +27 -0
data/lib/clowne/adapters/sequel/associations/many_to_many.rb +23 -0
data/lib/clowne/adapters/sequel/associations/noop.rb +16 -0
data/lib/clowne/adapters/sequel/associations/one_to_many.rb +28 -0
data/lib/clowne/adapters/sequel/associations/one_to_one.rb +28 -0
data/lib/clowne/adapters/sequel/copier.rb +23 -0
data/lib/clowne/adapters/sequel/operation.rb +35 -0
data/lib/clowne/adapters/sequel/record_wrapper.rb +43 -0
data/lib/clowne/adapters/sequel/resolvers/after_persist.rb +22 -0
data/lib/clowne/adapters/sequel/resolvers/association.rb +51 -0
data/lib/clowne/adapters/sequel/specifications/after_persist_does_not_support.rb +15 -0
data/lib/clowne/cloner.rb +50 -20
data/lib/clowne/declarations.rb +15 -11
data/lib/clowne/declarations/after_clone.rb +21 -0
data/lib/clowne/declarations/after_persist.rb +21 -0
data/lib/clowne/declarations/base.rb +13 -0
data/lib/clowne/declarations/exclude_association.rb +1 -6
data/lib/clowne/declarations/finalize.rb +3 -2
data/lib/clowne/declarations/include_association.rb +16 -4
data/lib/clowne/declarations/init_as.rb +21 -0
data/lib/clowne/declarations/nullify.rb +3 -2
data/lib/clowne/declarations/trait.rb +3 -0
data/lib/clowne/dsl.rb +9 -0
data/lib/clowne/ext/lambda_as_proc.rb +17 -0
data/lib/clowne/ext/orm_ext.rb +21 -0
data/lib/clowne/ext/record_key.rb +12 -0
data/lib/clowne/ext/string_constantize.rb +10 -4
data/lib/clowne/ext/yield_self_then.rb +25 -0
data/lib/clowne/planner.rb +27 -7
data/lib/clowne/resolvers/after_clone.rb +17 -0
data/lib/clowne/resolvers/after_persist.rb +18 -0
data/lib/clowne/resolvers/finalize.rb +12 -0
data/lib/clowne/resolvers/init_as.rb +13 -0
data/lib/clowne/resolvers/nullify.rb +15 -0
data/lib/clowne/rspec.rb +5 -0
data/lib/clowne/rspec/clone_association.rb +99 -0
data/lib/clowne/rspec/clone_associations.rb +26 -0
data/lib/clowne/rspec/helpers.rb +35 -0
data/lib/clowne/utils/clone_mapper.rb +26 -0
data/lib/clowne/utils/operation.rb +95 -0
data/lib/clowne/utils/options.rb +39 -0
data/lib/clowne/utils/params.rb +64 -0
data/lib/clowne/utils/plan.rb +90 -0
data/lib/clowne/version.rb +1 -1
metadata +140 -20
data/lib/clowne/adapters/active_record/association.rb +0 -34
data/lib/clowne/adapters/base/finalize.rb +0 -19
data/lib/clowne/adapters/base/nullify.rb +0 -19
data/lib/clowne/plan.rb +0 -81

@@ -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 ADDED

@@ -0,0 +1,40 @@
+# 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 ADDED

@@ -0,0 +1,37 @@
+# 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 ADDED

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

@@ -0,0 +1,55 @@
+# 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_attributes(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_attributes(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 ADDED

@@ -0,0 +1,112 @@
+# 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 ADDED

@@ -0,0 +1,50 @@
+# 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 ADDED

@@ -0,0 +1,10 @@
+# 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 ADDED

@@ -0,0 +1,194 @@
+# 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
+```