clowne 0.1.0.pre1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b833f076ba69c9b626d4038e977e4a40d8de8dbb
-  data.tar.gz: 271303497d931c2773c8c4f948baacfa9819cd4a
+SHA256:
+  metadata.gz: '0815485e47677a65023e13711ad70570b79c97057ad8d09bed83f45aa293f939'
+  data.tar.gz: d1f8a39135462f1bca941515d055f19f44cdf92c0152ea0c49d8dd3f39475fb7
 SHA512:
-  metadata.gz: f4df02c8872ecdc0b1f70fd74a12549065aaf85cd6922b2648043905f3eba9d4bf415716a11b5f0a8f458d7c59d11edbe590e2e1c92f3328887ab9da38c7de1b
-  data.tar.gz: '0683a5756b9797ac8c2a9cd60a4adbd29c214b9dbd55ef3fd736e2e05b414a7b0d92493edcde7e9a109434ceb67ca557cc55953ec08f1caad2a2c35e13ac1439'
+  metadata.gz: 809ecabf16dc071eda96f03853baaa42b5736804864e417e2d9a03ee3d37425b7e01c649cee2a2b8728813ffb09a3a4fb61a59e53ebdbf5f3da0b0a435a91807
+  data.tar.gz: 9c186a3f86f85f2a08eaea4612329a86f104328c99aa561f82a9b42f9b69f50b159f15b1426aec68585aca6f24c937b0967876689b84a0d04a64ac041169c175

data/.codeclimate.yml

@@ -0,0 +1,7 @@
+version: "2"
+checks:
+  method-complexity:
+    enabled: false
+exclude_patterns:
+- "docs/"
+- "spec/"

data/.gitattributes

@@ -0,0 +1 @@
+docs/**/* linguist-vendored

data/.gitignore

@@ -13,3 +13,4 @@ rubocop.html
 *.gem
 gemfiles/*.lock
 Gemfile.local
+/docs/web/build/

data/.rubocop.yml

@@ -1,45 +1,28 @@
+require:
+  # add after moving docs to another tool
+  - 'standard/cop/semantic_blocks'
+  - 'rubocop-md'
+
+inherit_gem:
+  standard: config/base.yml
+
 AllCops:
   Exclude:
     - 'bin/**/*'
     - 'tmp/**/*'
     - 'vendor/**/*'
     - 'gemfiles/vendor/**/*'
+    - 'clowne.gemspec'
   DisplayCopNames: true
-  StyleGuideCopsOnly: false
-  TargetRubyVersion: 2.3
-
-Rails:
-  Enabled: false
-
-Naming/AccessorMethodName:
-  Enabled: false
-
-Style/TrivialAccessors:
-  Enabled: false
+  TargetRubyVersion: 2.5
 
-Metrics/LineLength:
-  Max: 100
+Markdown:
+  WarnInvalid: true
 
-Style/Documentation:
-  Exclude:
-    - 'spec/**/*.rb'
-
-Style/SymbolArray:
+Standard/SemanticBlocks:
   Enabled: false
 
-Style/FrozenStringLiteralComment:
-  Exclude:
-    - 'spec/**/*.rb'
-    - 'Gemfile'
-    - 'Rakefile'
-    - '*.gemspec'
-
-Metrics/BlockLength:
+Lint/Void:
   Exclude:
-    - 'spec/**/*.rb'
-
-Bundler/OrderedGems:
-  Enabled: false
-
-Gemspec/OrderedDependencies:
-  Enabled: false
+    - 'docs/README.md'
+    - 'README.md'

data/.travis.yml

@@ -1,9 +1,13 @@
 sudo: false
 language: ruby
+cache: bundler
 
 notifications:
   email: false
 
+before_install:
+  - gem install bundler
+
 before_script:
   # Only generate coverage report for the specified job
   - if [ "$CC_REPORT" == "true" ]; then curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter; fi
@@ -11,7 +15,6 @@ before_script:
   - if [ "$CC_REPORT" == "true" ]; then ./cc-test-reporter before-build; fi
 script:
   - bundle exec rake
-after_script:
   - if [ "$CC_REPORT" == "true" ]; then ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT; fi
 
 matrix:
@@ -19,21 +22,22 @@ matrix:
   include:
     - rvm: ruby-head
       gemfile: gemfiles/railsmaster.gemfile
-    - rvm: jruby-9.1.0.0
+    - rvm: jruby-9.2.8.0
       gemfile: gemfiles/jruby.gemfile
-    - rvm: 2.5.0
+    - rvm: 2.7
       gemfile: Gemfile
-    - rvm: 2.4.3
+    - rvm: 2.6.5
       gemfile: Gemfile
-      env: CC_REPORT=true
-    - rvm: 2.4.1
-      gemfile: gemfiles/activerecord42.gemfile
-    - rvm: 2.3.1
+    - rvm: 2.5.7
       gemfile: Gemfile
-    - rvm: 2.2.0
+    - rvm: 2.4.9
       gemfile: gemfiles/activerecord42.gemfile
+    - rvm: truffleruby-head
+      gemfile: Gemfile
   allow_failures:
     - rvm: ruby-head
       gemfile: gemfiles/railsmaster.gemfile
-    - rvm: jruby-9.1.0.0
+    - rvm: jruby-9.2.8.0
       gemfile: gemfiles/jruby.gemfile
+    - rvm: truffleruby-head
+      gemfile: Gemfile

data/CHANGELOG.md

@@ -1,9 +1,46 @@
 # Change log
 
-## master branch
+## 1.1.0 (2019-03-20)
+
+
+- Add `after_clone` declaration. ([@elardo][])
+- Add opporotunity to include belongs_to association for active_record adapter. ([@madding][])
+
+## 1.0.0 (2019-02-26)
+
+- Return `Operation` instance as a rusult of cloning. ([@ssnickolay][])
+
+See [migration guide](https://clowne.evilmartians.io/docs/from_v02_to_v10.html)
+
+- Add `after_persist` declaration. ([@ssnickolay][], [@palkan][])
+
+- Unify interface between adapters. ([@ssnickolay][])
+
+- Deprecate `Operation#save` and `Operation#save!` methods. ([@ssnickolay][])
+
+- Improve Docs ([@ssnickolay][], [@palkan][])
+
+## 0.2.0 (2018-02-21)
+
+- Add `Cloner#partial_apply` method. ([@palkan][])
+
+- Add RSpec matchers `clone_association` / `clone_associations`. ([@palkan][])
+
+- [[#15](https://github.com/palkan/clowne/issues/15)] Add control over nested params. ([@ssnickolay][])
+
+## 0.1.0 (2018-02-01)
+
+- Add `init_as` declaration. ([@palkan][])
+
+- Support [Sequel](https://github.com/jeremyevans/sequel). ([@ssnickolay][])
+
+- Support passing a block to `#clowne` for inline configuration. ([@palkan][])
+
+## 0.1.0.beta1 (2018-01-08)
 
 - Initial version. ([@ssnickolay][], [@palkan][])
 
 [@palkan]: https://github.com/palkan
 [@ssnickolay]: https://github.com/ssnickolay
-
+[@elardo]: https://github.com/elardo
+[@madding]: https://github.com/madding

data/Gemfile

@@ -1,14 +1,19 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in clowne.gemspec
 gemspec
 
-gem 'pry-byebug'
-gem 'sqlite3'
-gem 'activerecord', '>= 5.0'
-gem 'simplecov'
+gem "pry-byebug", platform: :mri
 
-local_gemfile = 'Gemfile.local'
+gem "sqlite3", "~> 1.4.1", platform: :ruby
+gem "activerecord-jdbcsqlite3-adapter", "~> 50.0", platform: :jruby
+gem "jdbc-sqlite3", platform: :jruby
+
+gem "activerecord", "~> 5.2"
+gem "sequel", ">= 5.0"
+gem "simplecov"
+
+local_gemfile = "Gemfile.local"
 
 if File.exist?(local_gemfile)
   eval(File.read(local_gemfile)) # rubocop:disable Security/Eval

data/README.md

@@ -1,26 +1,20 @@
 [![Gem Version](https://badge.fury.io/rb/clowne.svg)](https://badge.fury.io/rb/clowne)
-[![Build Status](https://travis-ci.org/palkan/clowne.svg?branch=master)](https://travis-ci.org/palkan/clowne)
-[![Code Climate](https://codeclimate.com/github/palkan/clowne.svg)](https://codeclimate.com/github/palkan/clowne)
-[![Test Coverage](https://codeclimate.com/github/palkan/clowne/badges/coverage.svg)](https://codeclimate.com/github/palkan/clowne/coverage)
+[![Build Status](https://travis-ci.org/clowne-rb/clowne.svg?branch=master)](https://travis-ci.org/clowne-rb/clowne)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/9143c4f91e9d1d2a4bd1/test_coverage)](https://codeclimate.com/github/clowne-rb/clowne/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/9143c4f91e9d1d2a4bd1/maintainability)](https://codeclimate.com/github/clowne-rb/clowne/maintainability)
+[![Docs](https://img.shields.io/badge/docs-link-brightgreen.svg)](https://clowne.evilmartians.io)
 
 # Clowne
 
-**NOTICE**: gem is currently under heavy development, we plan to release the first version 'till the end of the year. 
+A flexible gem for cloning your models. Clowne focuses on ease of use and provides the ability to connect various ORM adapters.
 
-A flexible gem for cloning your models. Clowne focuses on ease of use and provides the ability to connect various ORM adapters (currently only ActiveRecord is supported).
+📖 Read [Evil Martians Chronicles](https://evilmartians.com/chronicles/clowne-clone-ruby-models-with-a-smile) to learn about possible use cases.
+
+📑 [Documentation](https://clowne.evilmartians.io)
 
 <a href="https://evilmartians.com/">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
-### Alternatives
-
-Why did we decide to build our own cloning gem?
-
-First, existing solutions turned out not stable and flexible enough for us.
-
-Secondly, they are Rails-only. And we are not.
-
-Nevertheless, thanks to [amoeba](https://github.com/amoeba-rb/amoeba) and [deep_cloneable](https://github.com/moiristo/deep_cloneable) for inspiration.
 
 ## Installation
 
@@ -33,14 +27,12 @@ gem install clowne
 Or add this line to your application's Gemfile:
 
 ```ruby
-gem 'clowne'
+gem "clowne"
 ```
 
 ## Quick Start
 
-This is a basic example that demonstrates how to clone your ActiveRecord model. For detailed documentation see [Features](#features).
-
-At first, define your cloneable model
+Assume that you have the following model:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -53,9 +45,19 @@ class User < ActiveRecord::Base
   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
 ```
 
-The next step is to declare cloner
+Let's declare our cloners first:
 
 ```ruby
 class UserCloner < Clowne::Cloner
@@ -65,8 +67,8 @@ class UserCloner < Clowne::Cloner
   include_association :posts
 
   nullify :login
-  
-  # params here is an arbitrary hash passed into cloner
+
+  # params here is an arbitrary Hash passed into cloner
   finalize do |_source, record, params|
     record.email = params[:email]
   end
@@ -79,388 +81,50 @@ class SpecialProfileCloner < Clowne::Cloner
 end
 ```
 
-and call it
-
-```ruby
-clone = UserCloner.call(User.last, { email: "fake@example.com" })
-clone.persisted?
-# => false
-clone.save!
-clone.login
-# => nil
-clone.email
-# => "fake@example.com"
-
-# associations:
-clone.posts.count == User.last.posts.count
-# => true
-clone.profile.name
-# => nil
-```
-
-## <a name="features">Features
-
-- [Configuration](#configuration)
-- [Include one association](#include_association)
-- - [Scope](#include_association_scope)
-- - [Options](#include_association_options)
-- [Exclude association](#exclude_association)
-- [Nullify attribute(s)](#nullify)
-- [Execute finalize block](#finalize)
-- [Traits](#traits)
-- [Execution order](#execution_order)
-- [Customization](#customization)
-
-### <a name="configuration"></a>Configuration
-
-You can configure the default adapter for cloners:
-
-```ruby
-# somewhere in initializers
-Clowne.default_adapter = :active_record
-```
-
-### <a name="include_association"></a>Include one association
-
-Powerful declaration for including model's association.
-
-```ruby
-class User < ActiveRecord::Base
-  has_one :profile
-end
-
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  include_association :profile
-end
-```
-
-But it's not all! :) The DSL looks like
-
-```ruby
-include_association name, scope, options
-```
-
-#### <a name="include_association_scope"></a>Include one association: Scope
-Scope can be a:
-
-`Symbol` - named scope.
-
-`Proc` - custom scope (supports parameter passing).
-
-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
-  adapter Clowne::ActiveRecord::Adapter
-
-  include_association :accounts, :active
-  include_association :posts, ->(params) { where(state: params[:post_status] }
-end
-
-# posts will be cloned only with draft status
-UserCloner.call(user, { post_status: :draft })
-# => <#User...
-```
-
-#### <a name="include_association_options"></a>Include one association: Options
-
-Options keys can be a:
-
-`:clone_with` - use custom cloner for all children.
-
-`:traits` - define special traits.
-
-Example:
-
-```ruby
-class User < ActiveRecord::Base
-  has_many :posts
-end
-
-class Post < ActiveRecord::Base
-  # t.string :title
-  has_many :tags
-end
-```
+Now you can use `UserCloner` to clone existing records:
 
 ```ruby
-class PostSpecialCloner < Clowne::Cloner
-  adapter :active_record
-
-  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)
-# => <#User...
-```
-
-**Notice: if custom cloner is not defined, clowne tries to find default cloner and use it. (PostCloner for previous example)**
+user = User.last
+# => <#User id: 1, login: 'clown', email: 'clown@circus.example.com'>
 
-### <a name="exclude_association"></a>Exclude association
+operation = UserCloner.call(user, email: "fake@example.com")
+# => <#Clowne::Utils::Operation...>
 
-Exclude association from copying
+operation.to_record
+# => <#User id: nil, login: nil, email: 'fake@example.com'>
 
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  include_association :posts
-
-  trait :without_posts do
-    exclude_association :posts
-  end
-end
-
-# copy user and posts
-clone = UserCloner.call(user)
-clone.posts.count == user.posts.count
+operation.persist!
 # => true
 
-# copy only user
-clone2 = UserCloner.call(user, traits: :without_posts)
-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)
-clone.comments.empty? #=> true
-```
-
-Why so? That allows to have deterministic cloning plans when combining multiple traits
-(or inheriting cloners).
-
-### <a name="nullify"></a>Nullify attribute(s)
-
-Nullify attributes:
-
-```ruby
-class User < ActiveRecord::Base
-  # t.string :name
-  # t.string :surename
-  # t.string :email
-end
-
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  nullify :name, :email
-
-  trait :nullify_surename do
-    nullify :surename
-  end
-end
+cloned = operation.to_record
+# => <#User id: 2, login: nil, email: 'fake@example.com'>
 
-# nullify only name
-clone = UserCloner.call(user)
-clone.name.nil?
-# => true
-clone.email.nil?
-# => true
-clone.surename.nil?
-# => false
+cloned.login
+# => nil
+cloned.email
+# => "fake@example.com"
 
-# nullify name and surename
-clone2 = UserCloner.call(user, traits: :nullify_surename)
-clone.name.nil?
-# => true
-clone.surename.nil?
+# associations:
+cloned.posts.count == user.posts.count
 # => true
+cloned.profile.name
+# => nil
 ```
 
-### <a name="finalize"></a>Execute finalize block
-
-Simple callback for changing record manually.
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  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
-
-# execute first finalize
-clone = UserCloner.call(user)
-clone.name
-# => 'This is copy!'
-clone.email == 'clone@example.com'
-# => false
-
-# execute both finalizes
-clone2 = UserCloner.call(user, traits: :change_email)
-clone.name
-# => 'This is copy!'
-clone.email
-# => 'clone@example.com'
-```
-
-### <a name="traits"></a>Traits
-
-Traits allow you to group cloner declarations together and then apply them (like in factory_bot).
-
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter Clowne::ActiveRecord::Adapter
-
-  trait :with_posts do
-    include_association :posts
-  end
-
-  trait :with_profile do
-    include_association :profile
-  end
-
-  trait :nullify_name do
-    nullify :name
-  end
-end
-
-# execute first finalize
-UserCloner.call(user, traits: [:with_posts, :with_profile, :nullify_name])
-# or
-UserCloner.call(user, traits: :nullify_name)
-# or
-# ...
-```
-
-### <a name="execution_order"></a>Execution order
-
-The order of cloning actions depends on the adapter.
-
-For ActiveRecord:
-- clone associations
-- nullify attributes
-- run `finalize` blocks
-The order of `finalize` blocks is the order they've been written.
-
-### <a name="customization"></a>Customization
-
-Clowne is built with extensibility in mind. You can create your own DSL commands and resolvers.
-
-Let's consider an example.
-
-Suppose that you want to add `include_all` declaration to automagically include all associations (for ActiveRecord).
-
-First, you should add a custom declaration:
-
-```ruby
-class IncludeAll # :nodoc: all
-  def compile(plan)
-    # Just add all_associations object to plan
-    plan.set(:all_associations, self)
-    # Plan supports 3 types of registers:
-    #
-    # 1) Scalar
-    #
-    # plan.set(key, value)
-    # plan.remove(key)
-    #
-    # 2) Append-only lists
-    #
-    # plan.add(key, value)
-    #
-    # 3) Two-phase set (2P-Set) (see below)
-    #
-    # plan.add_to(type, key, value)
-    # plan.remove_from(type, key)
-  end
-end
-
-# Register our declrations, i.e. extend DSL
-Clowne::Declarations.add :include_all, Clowne::Declarations::IncludeAll
-```
-
-\* Operations over [2P-Set](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type#2P-Set_(Two-Phase_Set)) (adding/removing) do not depend on the order of execution; we use "remove-wins" semantics, i.e. when a key has been removed, it cannot be re-added.
-
-Secondly, register a resolver:
-
-```ruby
-class AllAssociations
-  # This method is called when all_associations command is applied.
-  #
-  #   source – source record
-  #   record – target record (our clone)
-  #   declaration – declaration object
-  #   params – custom params passed to cloner
-  def call(source, record, declaration, params:)
-    source.class.reflections.each do |name, reflection|
-      # Exclude belongs_to associations
-      next if reflection.macro == :belongs_to
-      # Resolve and apply association cloner
-      cloner_class = Clowne::Adapters::ActiveRecord::Associations.cloner_for(reflection)
-      cloner_class.new(reflection, source, declaration, params).call(record)
-    end
-    record
-  end
-end
-
-# Finally, register the resolver
-Clowne::Adapters::ActiveRecord.register_resolver(
-  :all_associations, AllAssociations
-)
-```
-
-Now you can use it likes this:
+Take a look at our [documentation](https://clowne.evilmartians.io) for more info!
 
-```ruby
-class UserCloner < Clowne::Cloner
-  adapter :active_record
+### Supported ORM adapters
 
-  include_all
-end
-```
+Adapter                                   |1:1         |*:1         | 1:M         | M:M                     |
+------------------------------------------|------------|------------|-------------|-------------------------|
+[Active Record](https://clowne.evilmartians.io/#/active_record)  | has_one    | belongs_to | has_many    | has_and_belongs_to|
+[Sequel](https://clowne.evilmartians.io/#/sequel)                | one_to_one | -          | one_to_many | many_to_many     |
 
 ## Maintainers
 
 - [Vladimir Dementyev](https://github.com/palkan)
 
-- [Sverchkov Nikolay](https://github.com/ssnickolay)
+- [Nikolay Sverchkov](https://github.com/ssnickolay)
 
 ## License