clowne 0.1.0.pre1 → 0.1.0

data/clowne.gemspec

@@ -25,4 +25,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'factory_bot', '~> 4.8'
   spec.add_development_dependency 'rubocop', '~> 0.51'
+  spec.add_development_dependency 'rubocop-md', '~> 0.2'
 end

data/docs/.rubocop.yml

@@ -0,0 +1,12 @@
+Metrics/LineLength:
+  Max: 100
+
+Lint/Void:
+  Exclude:
+    - '*.md'
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false

data/docs/active_record.md

@@ -0,0 +1,36 @@
+---
+id: active_record
+title: Active Record
+---
+
+Clowne provides an optional ActiveRecord integration which allows you to configure cloners in your models and adds a shortcut to invoke cloners (`#clowne` method).
+
+To enable this integration, you must require `"clowne/adapters/active_record/dsl"` somewhere in your app, e.g., in the initializer:
+
+```ruby
+# config/initializers/clowne.rb
+require 'clowne/adapters/active_record/dsl'
+Clowne.default_adapter = :active_record
+```
+
+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
+user.clowne(traits: my_traits, **params)
+# => <#User...
+```

data/docs/alternatives.md

@@ -0,0 +1,26 @@
+---
+id: alternatives
+title: 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/architecture.md

@@ -0,0 +1,141 @@
+---
+id: architecture
+title: Architecture
+---
+
+This post aims to help developers and contributors to understand how Clowne works under the hood.
+
+There are two main notions we want to talk about: **declaration set** and **cloning plan**.
+
+## Declaration set
+
+_Declaration set_ is a result of calling Clowne DSL methods in the cloner class. There is (almost) one-to-one correspondence between configuration calls and declarations.
+
+Consider an example:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  include_association :profile
+  include_association :posts
+
+  nullify :external_id, :slug
+
+  trait :with_social_profile do
+    include_association :social_profiles
+  end
+end
+```
+
+This cloner's declaration set contains 3 declarations. You can access it through `.declarations` method:
+
+```ruby
+UserCloner.declarations #=>
+# [
+#   <#Clowne::Declarations::IncludeAssociation...>,
+#   <#Clowne::Declarations::IncludeAssociation...>,
+#   <#Clowne::Declarations::Nullify...>
+# ]
+```
+
+**NOTE:** `include_associations` and `exclude_associations` methods are just syntactic sugar, so they produce multiple declarations.
+
+Traits are not included in the declaration set. Moreover, each trait is just a wrapper over a declaration set. You can access traits through `.traits` method:
+
+```ruby
+UserCloner.traits #=>
+# {
+#   with_social_profiles: <#Clowne::Declarations::Trait...>
+# }
+
+UserCloner.traits[:with_social_profiles].declarations #=>
+# [
+#   <#Clowne::Declarations::IncludeAssociation...>
+# ]
+```
+
+## Cloning plan
+
+Every time you use a cloner the corresponding declaration set (which is the cloner itself declarations combined with all the specified traits declaration sets) is compiled into a _cloning plan_.
+
+The process is straightforward: starting with an empty `Plan`, we're applying every declaration to it.
+Every declaration object must implement `#compile(plan)` method, which populates the plan with _actions_. For example:
+
+```ruby
+class IncludeAssociation
+  def compile(plan)
+    # add a `name` key with the specified value (self)
+    # to :association set
+    plan.add_to(:association, name, self)
+  end
+end
+```
+
+`Plan` supports 3 types of registers:
+
+1) Scalars:
+
+```ruby
+plan.set(key, value)
+plan.remove(key)
+```
+
+Used by [`init_as`](init_as.md) declaration.
+
+2) Append-only lists:
+
+```ruby
+plan.add(key, value)
+```
+
+Used by [`nullify`](nullify.md) and [`finalize`](finalize.md) declarations.
+
+3) Two-phase set (2P-Set\*):
+
+```ruby
+plan.add_to(type, key, value)
+plan.remove_from(type, key)
+```
+
+Used by [`include_association`](include_association.md) and [`exclude_association`](exclude_association.md).
+
+
+\* 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.
+
+Thus, the resulting plan is just a key-value storage.
+
+## Plan resolving
+
+The final step in the cloning process is to apply the compiled plan to a record.
+
+Every adapter registers its own resolvers for each plan _key_ (or _action_). The [order of execution](execution_order.md) is also specified by the adapter.
+
+For example, you can override `:nullify` resolver to handle associations:
+
+```ruby
+module NullifyWithAssociation
+  def self.call(source, record, declaration, _params)
+    reflection = source.class.reflections[declaration.name.to_s]
+
+    # fallback to built-in nullify
+    if reflection.nil?
+      Clowne::Adapters::Base::Nullify.call(source, record, declaration)
+    else
+      association = record.__send__(declaration.name)
+      next record if association.nil?
+
+      association.is_a?(ActiveRecord::Relation) ? association.destroy_all : association.destroy
+      record.association(declaration.name).reset
+
+      # resolver must return cloned record
+      record
+    end
+  end
+end
+
+Clowne::Adapters::ActiveRecord.register_resolver(
+  :nullify,
+  NullifyWithAssociation,
+  # specify the order of execution (available options are `prepend`, `before`, `after`)
+  before: :finalize
+)
+```

data/docs/basic_example.md

@@ -0,0 +1,66 @@
+---
+id: basic_example
+title: 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
+```
+
+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(login: 'clown', email: 'clown@circus.example.com')>
+
+cloned = UserCloner.call(user, email: 'fake@example.com')
+cloned.persisted?
+# => false
+
+cloned.save!
+cloned.login
+# => nil
+cloned.email
+# => "fake@example.com"
+
+# associations:
+cloned.posts.count == user.posts.count
+# => true
+cloned.profile.name
+# => nil
+```

data/docs/configuration.md

@@ -0,0 +1,29 @@
+---
+id: configuration
+title: Configuration
+---
+
+Basic cloner implementation looks like
+
+```ruby
+class SomeCloner < Clowne::Cloner
+  adapter :active_record # or adapter Clowne::ActiveRecord::Adapter
+  # some implementation ...
+end
+```
+
+But you can configure the default adapter for cloners:
+
+```ruby
+# somewhere in initializers
+Clowne.default_adapter = :active_record
+```
+
+and skip adapter declaration
+
+```ruby
+class SomeCloner < Clowne::Cloner
+  # some implementation ...
+end
+```
+See the list of [available adapters](supported_adapters.md).

data/docs/customization.md

@@ -0,0 +1,64 @@
+---
+id: customization
+title: 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 the `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)
+  end
+end
+
+# Register our declrations, i.e. extend DSL
+Clowne::Declarations.add :include_all, Clowne::Declarations::IncludeAll
+```
+
+See more on `plan` in [architecture overview](architecture.md).
+
+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_value 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
+```

data/docs/exclude_association.md

@@ -0,0 +1,63 @@
+---
+id: exclude_association
+title: Exclude Association
+---
+
+Clowne doesn't include any association by default and doesn't provide _magic_ `include_all` declaration (although you can [add one by yourself](customization.md)).
+
+Nevertheless, sometimes you might want to exclude already added associations (when inheriting a cloner or using [traits](traits.md)).
+
+Consider an example:
+
+```ruby
+class UserCloner < Clowne::Cloner
+  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 us to have a deterministic cloning plan when combining multiple traits
+(or inheriting cloners).
+
+## Exclude multiple associations
+
+It's possible to exclude multiple associations at once the same way as [`include_associations`](include_association.md):
+
+```ruby
+class UserCloner < Clowne::Cloner
+  include_associations :accounts, :posts, :comments
+
+  trait :without_posts do
+    exclude_associations :posts, :comments
+  end
+end
+```