deferring 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Appraisals

@@ -0,0 +1,15 @@
+appraise 'rails-30' do
+  gem 'activerecord', '3.0.19'
+end
+
+appraise 'rails-32' do
+  gem 'activerecord', '3.2.17'
+end
+
+appraise 'rails-40' do
+  gem 'activerecord', '4.0.4'
+end
+
+appraise 'rails-41' do
+  gem 'activerecord', '4.1.0'
+end

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Robin Roestenburg
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,236 @@
+# Deferring
+
+Deferring makes it possible to delay saving ActiveRecord associations until the
+parent object has been saved.
+
+Currently supporting Rails 3.0, 3.2, 4.0 and 4.1 on Ruby 1.9.3.
+
+It is important to note that Deferring does not touch the original `has_many`
+and `has_and_belongs_to_many` associations. You can use them, without worrying
+about any changed behaviour or side-effects from using Deferring.
+
+**NOTE: This is currently work in progress.**
+
+## Why use it?
+
+Let's take a look at the following example:
+
+``` ruby
+class Person
+  has_and_belongs_to_many :teams
+  validates :name, presence: true
+end
+
+class Team
+  has_and_belongs_to_many :people
+end
+
+support = Team.create(name: 'Support')
+person = Person.create(name: 'Bob')
+
+person.teams << support
+person.name = nil
+person.save
+# => false, because the name attribute is empty
+
+Person.first.teams
+# => [#<Team id: 4, name: "Support", ... ]
+```
+
+The links to the Teams associated to the Person are stored directly, before the
+(in this case invalid) parent is actually saved. This is how Rails' `has_many`
+and `has_and_belongs_to_many` associations work, but not how (imho) they should
+work in this situation.
+
+The `deferring` gem will delay creating the links between Person and Team until
+the Person has been saved successfully. Let's look at the example again, only
+now using the `deferring` gem:
+
+``` ruby
+class Person
+  deferred_has_and_belongs_to_many :teams
+  validates :name, presence: true
+end
+
+class Team
+  has_and_belongs_to_many :people
+end
+support = Team.create(name: 'Support')
+person = Person.create(name: 'Bob')
+
+person.teams << support
+person.name = nil
+person.save
+# => false, because the name attribute is empty
+
+Person.first.teams
+# => []
+```
+
+
+## Use cases
+
+* Auditing
+* ...
+
+
+## Credits/Rationale
+
+The idea for this gem was originally thought of by Tyler Rick (see [this Ruby
+form thread from 2006](https://www.ruby-forum.com/topic/81095)). The gem created
+by TylerRick is still
+[available](https://github.com/TylerRick/has_and_belongs_to_many_with_deferred_save),
+but unmaintained. This gem has been forked by Martin Koerner, who released his
+fork as a gem called
+[`deferred_associations`](https://rubygems.org/gems/deferred_associations).
+Koerner fixes some issues with Rick's original implementation and added support
+for Rails 3 and 4.
+
+A project I am working on, uses the
+[`autosave_habtm`](https://rubygems.org/gems/autosave_habtm) gem, which kind of
+takes different approach to doing the same thing. This gem only supports Rails
+3.0.
+
+As we are upgrading to Rails 3.2 (and later Rails 4), I needed a gem to provide
+this behaviour. Upgrading either one of the gems would result into rewriting a
+lot of the code (for different reasons, some purely esthetic :)), so that is why
+I wrote a new gem.
+
+
+## Getting started
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'deferring'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install deferring
+
+
+### How do I use it?
+
+Deferring adds a couple of methods to your ActiveRecord models. These are:
+
+- `deferred_has_and_belongs_to_many`
+- `deferred_accepts_nested_attributes_for`
+- `deferred_has_many`
+
+These methods wrap the existing methods. For instance, `deferred_has_many` will
+call `has_many` in order to set up the association.
+
+**TODO:** Describe pending_creates/pending_deletes/links/unlinks/callbacks/
+original_name/checked.
+
+
+### How does it work?
+
+Deferring wraps the original ActiveRecord association and replaces the accessor
+methods to the association by a custom object that will keep track of the
+updates to the association. This wrapper is basically an array with some extras
+to match the ActiveRecord API.
+
+When the parent is saved, this object is assigned to the original association
+(using an `after_save` callback on the parent model) which will automatically
+save the changes to the database.
+
+For the astute reader: Yes, the gem abuses the exact problem it is trying to
+avoid ;-)
+
+### Gotchas
+
+#### Using autosave (or not actually)
+
+TL;DR; Using `autosave: true` (or false) on a deferred association will work,
+but does not do anything.
+
+This is what the Rails documentation says about the AutosaveAssociation:
+
+_AutosaveAssociation is a module that takes care of automatically saving
+associated records when their parent is saved. In addition to saving, it also
+destroys any associated records that were marked for destruction._
+
+_If validations for any of the associations fail, their error messages will be
+applied to the parent._
+
+The `deferring` gem works with `pending_deletes` (or the alias `unlinks`)
+instead of the `marked_for_destruction` flag, so everything related to that in
+AutosaveAssociation does not work as you would expect.
+
+Also, `deferring` adds the associated records present in a deferred
+association to the original (in this case, autosaved) association by assigning
+the array of associated records to original association. This kind of assignment
+bypasses the autosave behaviour, see the _Why use it?_ part on top of this
+README.
+
+#### Using custom callback methods
+
+**TODO**: This is incorrect and has to be rewritten to match code.
+
+You can use custom callback functions. However, the callbacks for defferred
+associations are triggered at a different point in time.
+
+An example to illustrate:
+
+``` ruby
+class Person < ActiveRecord::Base
+  has_and_belongs_to_many :teams, before_add: :before_adding
+  deferred_has_and_belongs_to_many :pets, before_add: :before_adding
+
+  def audit_log
+    @log = []
+  end
+
+  def before_adding(record)
+    audit_log << "Before adding #{record.class} with id #{record.id}"
+  end
+end
+```
+
+This sets up a Person model that has a regular HABTM association with teams and
+that has a deferred HABTM association with pets. Each time a team or pet is
+added to the database a log statement is written to the audit log (using the
+`before_adding` callback function).
+
+The regular HABTM association behaves likes this:
+
+``` ruby
+person = Person.first
+person.teams << Team.find(1)
+person.audit_log # => ['Before adding Team 1']
+```
+
+As records of deferred associations are saved to the database after saving the
+parent the behavior is a bit different:
+
+``` ruby
+person = Person.first
+person.pets << Pet.find(1)
+person.audit_log # => []
+
+person.save
+person.audit_log # => ['Before adding Pet 1']
+```
+
+## TODO
+
+* add support for more Rubies
+* check out what is going on with uniq: true
+* collection(true) (same as reload)
+* collection.replace
+* validations!
+* validate: false does not work
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Run the specs.'
+task default: :spec

data/deferring.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'deferring/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'deferring'
+  spec.version       = Deferring::VERSION
+  spec.authors       = ['Robin Roestenburg']
+  spec.email         = ['robin@roestenburg.io']
+  spec.description   = %q{
+    The Deferring gem makes it possible to defer saving ActiveRecord
+    associations until the parent object is saved.
+  }
+  spec.summary       = %q{Defer saving ActiveRecord associations until parent is saved}
+  spec.homepage      = 'http://github.com/robinroestenburg/delay_many'
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activerecord', '> 3.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'sqlite3'
+  spec.add_development_dependency 'appraisal'
+end

data/gemfiles/rails_30.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "3.0.19"
+
+gemspec :path => "../"

data/gemfiles/rails_30.gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: ..
+  specs:
+    deferring (0.0.1)
+      activerecord (> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.0.19)
+      activesupport (= 3.0.19)
+      builder (~> 2.1.2)
+      i18n (~> 0.5.0)
+    activerecord (3.0.19)
+      activemodel (= 3.0.19)
+      activesupport (= 3.0.19)
+      arel (~> 2.0.10)
+      tzinfo (~> 0.3.23)
+    activesupport (3.0.19)
+    appraisal (1.0.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    arel (2.0.10)
+    builder (2.1.2)
+    diff-lcs (1.2.5)
+    i18n (0.5.2)
+    rake (10.3.1)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+    sqlite3 (1.3.9)
+    thor (0.19.1)
+    tzinfo (0.3.39)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (= 3.0.19)
+  appraisal
+  bundler (~> 1.3)
+  deferring!
+  rake
+  rspec
+  sqlite3

data/gemfiles/rails_32.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activerecord", "3.2.17"
+
+gemspec :path => "../"

data/gemfiles/rails_32.gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: ..
+  specs:
+    deferring (0.0.1)
+      activerecord (> 3.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (3.2.17)
+      activesupport (= 3.2.17)
+      builder (~> 3.0.0)
+    activerecord (3.2.17)
+      activemodel (= 3.2.17)
+      activesupport (= 3.2.17)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activesupport (3.2.17)
+      i18n (~> 0.6, >= 0.6.4)
+      multi_json (~> 1.0)
+    appraisal (1.0.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    arel (3.0.3)
+    builder (3.0.4)
+    diff-lcs (1.2.5)
+    i18n (0.6.9)
+    multi_json (1.9.2)
+    rake (10.3.1)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+    sqlite3 (1.3.9)
+    thor (0.19.1)
+    tzinfo (0.3.39)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (= 3.2.17)
+  appraisal
+  bundler (~> 1.3)
+  deferring!
+  rake
+  rspec
+  sqlite3