clowne 0.0.1 → 0.1.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1ee04593c36f9b86a93581e16fb7ef42d65b387c
-  data.tar.gz: 9bbe81f26c453f960c3a27f05a8c297e7a207ada
+  metadata.gz: 2d56daf439132f64870a49326ff8afe5465691b7
+  data.tar.gz: b273e7e236eee799de5a5ea7386c05d26a173b04
 SHA512:
-  metadata.gz: 45ae06ab333657628e0ca429b05bc9214e46c619e56dcf89428cf1a57c2a74ef48c7c768f22c8c9c0a552e11605e1dbe9810428134627fba8cc4ce0c5f9dd627
-  data.tar.gz: c583843f2b87e86ea54468ff6b9047596848c07c87a0da3a19bf12decb4f22cf04ded9bf33399854e21f181b4dc96d412e0225ae275a92cc4a8842739bb9d119
+  metadata.gz: d55650b452063d8eeadbcc3c4a2c1c648c3b5d7c18905ac2d0f7dee05e734358dd19798f7382b284676b693628dcde4fb237e937ce0fafd68f4b2ba860c183fd
+  data.tar.gz: 35463db710e77b7320ff114d1b1fd011ccf9d7405216565420b885ee9b989be8ce734b17ec7c3dbd07017326a1921b0fe4632afff141603f2b41520cce60d238

data/.gitignore

@@ -1,3 +1,6 @@
+.rspec_status
+rubocop.html
+/coverage/
 /.bundle/
 /.yardoc
 /Gemfile.lock
@@ -7,3 +10,6 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem
+gemfiles/*.lock
+Gemfile.local

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,49 @@
+AllCops:
+  Exclude:
+    - 'bin/**/*'
+    - 'tmp/**/*'
+    - 'vendor/**/*'
+    - 'gemfiles/vendor/**/*'
+  DisplayCopNames: true
+  StyleGuideCopsOnly: false
+  TargetRubyVersion: 2.3
+
+Rails:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/ClassAndModuleCamelCase:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Style/TrivialAccessors:
+  Enabled: false
+
+Metrics/LineLength:
+  Max: 100
+
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - 'spec/**/*.rb'
+    - 'Gemfile'
+    - 'Rakefile'
+    - '*.gemspec'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Bundler/OrderedGems:
+  Enabled: false
+
+Gemspec/OrderedDependencies:
+  Enabled: false

data/.rufo

@@ -0,0 +1,3 @@
+trailing_commas :never
+spaces_inside_hash_brace :always
+spaces_after_comma :one

data/.travis.yml

@@ -1,5 +1,39 @@
 sudo: false
 language: ruby
-rvm:
-  - 2.4.2
-before_install: gem install bundler -v 1.15.4
+
+notifications:
+  email: false
+
+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
+  - if [ "$CC_REPORT" == "true" ]; then chmod +x ./cc-test-reporter; fi
+  - 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:
+  fast_finish: true
+  include:
+    - rvm: ruby-head
+      gemfile: gemfiles/railsmaster.gemfile
+    - rvm: jruby-9.1.0.0
+      gemfile: gemfiles/jruby.gemfile
+    - rvm: 2.5.0
+      gemfile: Gemfile
+    - rvm: 2.4.3
+      gemfile: Gemfile
+      env: CC_REPORT=true
+    - rvm: 2.4.1
+      gemfile: gemfiles/activerecord42.gemfile
+    - rvm: 2.3.1
+      gemfile: Gemfile
+    - rvm: 2.2.0
+      gemfile: gemfiles/activerecord42.gemfile
+  allow_failures:
+    - rvm: ruby-head
+      gemfile: gemfiles/railsmaster.gemfile
+    - rvm: jruby-9.1.0.0
+      gemfile: gemfiles/jruby.gemfile

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change log
+
+## master
+
+## 0.1.0.beta1 (2018-01-08)
+
+- Initial version. ([@ssnickolay][], [@palkan][])
+
+[@palkan]: https://github.com/palkan
+[@ssnickolay]: https://github.com/ssnickolay
+

data/Gemfile

@@ -1,6 +1,15 @@
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in clowne.gemspec
 gemspec
+
+gem 'pry-byebug'
+gem 'sqlite3'
+gem 'activerecord', '>= 5.0'
+gem 'simplecov'
+
+local_gemfile = 'Gemfile.local'
+
+if File.exist?(local_gemfile)
+  eval(File.read(local_gemfile)) # rubocop:disable Security/Eval
+end

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Vladimir Dementyev
+Copyright (c) 2017 Sverchkov Nikolay, Vladimir Dementyev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,38 +1,556 @@
+[![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)
+[![Test Coverage](https://codeclimate.com/github/palkan/clowne/badges/coverage.svg)](https://codeclimate.com/github/palkan/clowne/coverage)
+
 # Clowne
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/clowne`. To experiment with that code, run `bin/console` for an interactive prompt.
+**NOTE**: this is the documentation for pre-release version **0.1.0.beta1**.
+
+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).
+
+<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.
 
-TODO: Delete this and the text above, and describe your gem
+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
 
-Add this line to your application's Gemfile:
+To install Clowne with RubyGems:
+
+```ruby
+gem install clowne
+```
+
+Or add this line to your application's Gemfile:
 
 ```ruby
 gem 'clowne'
 ```
 
-And then execute:
+## Quick Start
 
-    $ bundle
+This is a basic example that demonstrates how to clone your ActiveRecord model. For detailed documentation see [Features](#features).
 
-Or install it yourself as:
+At first, define your cloneable model
 
-    $ gem install clowne
+```ruby
+class User < ActiveRecord::Base
+  # create_table :users do |t|
+  #  t.string :login
+  #  t.string :email
+  #  t.timestamps null: false
+  # end
 
-## Usage
+  has_one :profile
+  has_many :posts
+end
+```
+
+The next step is to declare cloner
+
+```ruby
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_association :profile, clone_with: SpecialProfileCloner
+  include_association :posts
+
+  nullify :login
 
-TODO: Write usage instructions here
+  # params here is an arbitrary hash passed into cloner
+  finalize do |_source, record, params|
+    record.email = params[:email]
+  end
+end
 
-## Development
+class SpecialProfileCloner < Clowne::Cloner
+  adapter :active_record
+
+  nullify :name
+end
+```
+
+and call it
+
+```ruby
+cloned = UserCloner.call(User.last, { email: "fake@example.com" })
+cloned.persisted?
+# => false
+cloned.save!
+cloned.login
+# => nil
+cloned.email
+# => "fake@example.com"
+
+# associations:
+cloned.posts.count == User.last.posts.count
+# => true
+cloned.profile.name
+# => nil
+```
+
+## <a name="features">Features
+
+- [Configuration](#configuration)
+- [Include association](#include_association)
+- - [Inline configuration](#config-inline)
+- [Include one association](#include_association)
+- - [Scope](#include_association_scope)
+- - [Options](#include_association_options)
+- - [Multiple associations](#include_associations)
+- [Exclude association](#exclude_association)
+- - [Multiple associations](#exclude_associations)
+- [Nullify attribute(s)](#nullify)
+- [Execute finalize block](#finalize)
+- [Traits](#traits)
+- [Execution order](#execution_order)
+- [ActiveRecord DSL](#ar_dsl)
+- [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="config-inline"></a>Inline Configuration
+
+You can also enhance the cloner configuration inline (i.e. add dynamic declarations):
+
+```ruby
+cloned = UserCloner.call(User.last) do
+  exclude_association :profile
+
+  finalize do |source, record|
+    record.email = "clone_of_#{source.email}"
+  end
+end
+
+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 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
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### <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
+```
+
+```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)**
+
+#### <a name="include_associations"></a>Include multiple association
+
+It's possible to include multiple associations at once with default options and scope
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :accounts
+  has_many :posts
+end
+
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_associations :accounts, :posts
+end
+```
+
+### <a name="exclude_association"></a>Exclude association
+
+Exclude association from copying
+
+```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
+# => 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="exclude_associations"></a>Exclude multiple association
+
+It's possible to exclude multiple associations the same way as `include_associations` but with `exclude_associations`
+
+### <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
+
+# nullify only name
+clone = UserCloner.call(user)
+clone.name.nil?
+# => true
+clone.email.nil?
+# => true
+clone.surename.nil?
+# => false
+
+# nullify name and surename
+clone2 = UserCloner.call(user, traits: :nullify_surename)
+clone.name.nil?
+# => true
+clone.surename.nil?
+# => true
+```
+
+### <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="ar_dsl"></a>Active Record DSL
+
+Clowne provides an optional ActiveRecord integration which allows you to configure cloners in your models and adds a shortcut to invoke cloners (`#clowne` method). (Note: that's exactly the way [`amoeba`](https://github.com/amoeba-rb/amoeba) works).
+
+To enable this integration you must require `"clowne/adapters/active_record/dsl"` somewhere in your app, e.g. in initializer:
+
+```ruby
+# config/initializers/clowne.rb
+require "clowne/adapters/active_record/dsl"
+```
+
+Now you can specify cloning configs in your AR models:
+
+```ruby
+class User < ActiveRecord::Base
+  clowne_config do
+    include_associations :profile
+
+    nullify :email
+
+    # whatever available for your cloners,
+    # active_record adapter is set implicitly here
+  end
+end
+```
+
+And then you can clone objects like this:
+
+```ruby
+cloned_user = user.clowne(traits: my_traits, **params)
+```
+
+### <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:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  adapter :active_record
+
+  include_all
+end
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## Maintainers
 
-## Contributing
+- [Vladimir Dementyev](https://github.com/palkan)
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/clowne.
+- [Sverchkov Nikolay](https://github.com/ssnickolay)
 
 ## License