couch_potato 1.6.4 → 1.9.0

data/README.md

@@ -8,7 +8,6 @@
 
 [![Code Climate](https://codeclimate.com/github/langalex/couch_potato.png)](https://codeclimate.com/github/langalex/couch_potato)
 
-
 ### Mission
 
 The goal of Couch Potato is to create a minimal framework in order to store and retrieve Ruby objects to/from CouchDB and create and query views.
@@ -21,17 +20,13 @@ Lastly Couch Potato aims to provide a seamless integration with Ruby on Rails, e
 
 ### Core Features
 
-* persisting objects by including the CouchPotato::Persistence module
-* declarative views with either custom or generated map/reduce functions
-* extensive spec suite
+- persisting objects by including the CouchPotato::Persistence module
+- declarative views with either custom or generated map/reduce functions
+- extensive spec suite
 
 ### Supported Environments
 
-* Ruby 2.0, 2.1, 2.2, Rubinius
-* CouchDB 1.6.0
-* ActiveSupport 4.0, 4.1, 4.2
-
-(Supported means I run the specs against those before releasing a new gem.)
+Check travis.yml for supported Ruby/ActiveSupport versions.
 
 ### Installation
 
@@ -85,6 +80,13 @@ Another switch allows you to store each CouchDB view in its own design document.
 CouchPotato::Config.split_design_documents_per_view = true
 ```
 
+If you are using more than one database from your app, you can create aliases:
+
+```ruby
+CouchPotato::Config.additional_databases = {'db1' => 'db1_production', 'db2' => 'https://db2.example.com/db'}
+db1 = CouchPotato.use 'db1'
+```
+
 #### Using with Rails
 
 Create a `config/couchdb.yml`:
@@ -94,6 +96,7 @@ default: &default
   split_design_documents_per_view: true # optional, default is false
   digest_view_names: true # optional, default is false
   default_language: :erlang # optional, default is javascript
+  database_host: "http://127.0.0.1:5984"
 
 development:
   <<: *default
@@ -104,9 +107,12 @@ test:
 production:
   <<: *default
   database: <%= ENV['DB_NAME'] %>
+  additional_databases:
+    db1: db1_production
+    db2: https://db2.example.com/db
 ```
 
-#### Rails 3.x
+#### Rails
 
 Add to your `Gemfile`:
 
@@ -164,19 +170,18 @@ end
 ```
 
 In this case `Address` also implements `CouchPotato::Persistence` which means its JSON representation will be added to the user document.
-Couch Potato also has support for the basic types (right now `Fixnum`, `Date`, `Time` and `:boolean` are supported):
+Couch Potato also has support for the basic types (right now `Integer`, `Date`, `Time` and `:boolean` are supported):
 
 ```ruby
 class User
   include CouchPotato::Persistence
 
-  property :age, :type => Fixnum
+  property :age, :type => Integer
   property :receive_newsletter, :type => :boolean
 end
 ```
 
-With this in place when you set the user's age as a String (e.g. using an HTML form) it will be converted into a `Fixnum` automatically.
-
+With this in place when you set the user's age as a String (e.g. using an HTML form) it will be converted into a `Integer` automatically.
 
 Properties can have a default value:
 
@@ -214,6 +219,20 @@ end
 
 When a conflict occurs Couch Potato automatically reloads the document, runs the block and tries to save it again. Note that the block is also run before initally saving the document.
 
+#### Caching load reqeusts
+
+You can add a cache to a database instance to enable caching subsequent `#load` calls to the same id.
+Any write operation will completely clear the cache.
+
+```ruby
+db = CouchPotato.database
+db.cache = {}
+db.load '1'
+db.load '1' # goes to the cache instead of to the database
+```
+
+In web apps, the idea is to use a per request cache, i.e. set a new cache for every request.
+
 #### Operations on multiple documents
 
 You can also load a bunch of documents with one request.
@@ -256,7 +275,7 @@ end
 
 #### Dirty tracking
 
-CouchPotato tracks the dirty state of attributes in the same way ActiveRecord does:
+CouchPotato tracks the dirty state of attributes in the same way ActiveRecord does. Models are always saved though to avoid missing updates when multiple processes update the same documents concurrently.
 
 ```ruby
 user = User.create :name => 'joe'
@@ -265,68 +284,6 @@ user.name_changed? # => false
 user.name_was # => nil
 ```
 
-You can also force a dirty state:
-
-```ruby
-user.name = 'jane'
-user.name_changed? # => true
-user.name_not_changed
-user.name_changed? # => false
-CouchPotato.database.save_document user # does nothing as no attributes are dirty
-```
-
-#### Optional Deep Dirty Tracking
-
-In addition to standard dirty tracking, you can opt-in to more advanced dirty tracking for deeply structured documents by including the `CouchPotato::DeepDirtyAttributes` module in your models. This provides two benefits:
-
-1. Dirty checking for array and embedded document properties is more reliable, such that modifying elements in an array (by any means) or changing a property of an embedded document will make the root document be `changed?`. With standard dirty checking, the `#{property}=` method must be called on the root document for it to be `changed?`.
-2. It gives more useful and detailed change tracking for embedded documents, arrays of simple values, and arrays of embedded documents.
-
-The `#{property}_changed?` and `#{property}_was` methods work the same as basic dirty checking, and the `_was` values are always deep clones of the original/previous value. The `#{property}_change` and `changes` methods differ from basic dirty checking for embedded documents and arrays, giving richer details of the changes instead of just the previous and current values. This makes generating detailed, human friendly audit trails of documents easy.
-
-Tracking changes in embedded documents gives easy access to the changes in that document:
-
-```ruby
-book = Book.new(:cover => Cover.new(:color => "red"))
-book.cover.color = "blue"
-book.cover_changed? # => true
-book.cover_was # => <deep clone of original state of book.cover>
-book.cover_change # => [<deep clone of original state of book.cover>, {:color => ["red", "blue"]}]
-```
-
-Tracking changes in arrays of simple properties gives easy access to added and removed items:
-
-```ruby
-book = Book.new(:authors => ["Sarah", "Jane"])
-book.authors.delete "Jane"
-book.authors << "Sue"
-book.authors_changed? # => true
-book.authors_was # => ["Sarah", "Jane"]
-book.authors_change # => [["Sarah", "Jane"], {:added => ["Sue"], :removed => ["Jane"]}]
-```
-
-Tracking changes in an array of embedded documents also gives changed items:
-
-```ruby
-book = Book.new(:pages => [Page.new(:number => 1), Page.new(:number => 2)]
-book.pages[0].title = "New title"
-book.pages.delete_at 1
-book.pages << Page.new(:number => 3)
-book.pages_changed? # => true
-book.pages_was # => <deep clone of original pages array>
-book.pages_change[0] # => <deep clone of original pages array>
-book.pages_change[1] # => {:added => [<page 3>], :removed => [<page 2>], :changed => [[<deep clone of original page 1>, {:title => [nil, "New title"]}]]}
-```
-
-For change tracking in nested documents and document arrays to work, the embedded documents **must** have unique `_id` values. This can be accomplished easily in your embedded CouchPotato models by overriding `initialize`:
-
-```ruby
-def initialize(*args)
-  self._id = SecureRandom.uuid
-  super
-end
-```
-
 #### Object validations
 
 Couch Potato by default uses ActiveModel for validation
@@ -363,6 +320,16 @@ CouchPotato.database.view User.all
 
 This will load all user documents in your database sorted by `created_at`.
 
+For large data sets, use batches:
+
+```ruby
+CouchPotato.database.view_in_batches(User.all, batch_size: 100) do |users|
+  ...
+end
+```
+
+This will query CouchDB with skip/limit until all documents have been yielded.
+
 ```ruby
 CouchPotato.database.view User.all(:key => (Time.now- 10)..(Time.now), :descending => true)
 ```
@@ -455,7 +422,16 @@ end
 When querying this view you will get the raw data returned by CouchDB which looks something like this:
 
 ```json
-{'total_entries': 2, 'rows': [{'value': 'alex', 'key': '2009-01-03 00:02:34 +000', 'id': '75976rgi7546gi02a'}]}
+{
+  "total_entries": 2,
+  "rows": [
+    {
+      "value": "alex",
+      "key": "2009-01-03 00:02:34 +000",
+      "id": "75976rgi7546gi02a"
+    }
+  ]
+}
 ```
 
 To process this raw data you can also pass in a results filter:
@@ -468,11 +444,11 @@ end
 
 In this case querying the view would only return the emitted value for each row.
 
-You can pass in your own view specifications by passing in `:type => MyViewSpecClass`. Take a look at the CouchPotato::View::*ViewSpec classes to get an idea of how this works.
+You can pass in your own view specifications by passing in `:type => MyViewSpecClass`. Take a look at the CouchPotato::View::\*ViewSpec classes to get an idea of how this works.
 
 ##### Digest view names
 
-If turned on, Couch Potato will append an MD5 digest of the map function to each view name. This makes sure (together with split_design_documents_per_view) that no views/design documents are ever updated. Instead, new ones are created. Since reindexing can take a long time once your database is larger, you want to avoid blocking your app while CouchDB is busy. Instead, you create a new view, warm it up, and only then start using it. 
+If turned on, Couch Potato will append an MD5 digest of the map function to each view name. This makes sure (together with split_design_documents_per_view) that no views/design documents are ever updated. Instead, new ones are created. Since reindexing can take a long time once your database is larger, you want to avoid blocking your app while CouchDB is busy. Instead, you create a new view, warm it up, and only then start using it.
 
 ##### Lists
 
@@ -517,7 +493,6 @@ And you can pass parameters to the list:
 CouchPotato.database.view(User.all(list: :add_last_name, list_params: {filter: '*'}))
 ```
 
-
 #### Associations
 
 Not supported. Not sure if they ever will be. You can implement those yourself using views and custom methods on your models.
@@ -602,9 +577,9 @@ describe 'save a user' do
 end
 ```
 
-By creating you own instances of `CouchPotato::Database` and passing them a fake CouchRest database instance you can completely disconnect your unit tests/spec from the database.
+By creating your own instances of `CouchPotato::Database` and passing them a fake CouchRest database instance you can completely disconnect your unit tests/spec from the database.
 
-For stubbing out the database couch potato offers some helpers via the `couch_potato-rspec` gem. Use version 2.x of the gem, you you are on RSpec 2, use 3.x for RSpec 3.
+For stubbing out the database couch potato offers some helpers via the `couch_potato-rspec` gem. Use version 2.x of the gem if you are on RSpec 2, use 3.x for RSpec 3.
 
 ```ruby
 class Comment
@@ -617,7 +592,8 @@ require 'couch_potato/rspec'
 db = stub_db # stubs CouchPotato.database
 db.stub_view(Comment, :by_commenter_id).with('23').and_return([:comment1, :comment2])
 
-CouchPotato.database.view(Comment.by_commenter_id('23)) # => [:comment1, :comment2]
+CouchPotato.database.view(Comment.by_commenter_id('23')) # => [:comment1, :comment2]
+CouchPotato.database.view_in_batches(Comment.by_commenter_id('23'), batch_size: 1) # => yields [:comment1] and [:comment2]
 CouchPotato.database.first(Comment.by_commenter_id('23)) # => :comment1
 ```
 
@@ -630,7 +606,7 @@ class User
   include CouchPotato::Persistence
 
   property :name
-  property :age, :type => Fixnum
+  property :age, :type => Integer
 
   view :by_name, :key => :name
   view :by_age,  :key => :age

data/Rakefile

@@ -19,17 +19,18 @@ RSpec::Core::RakeTask.new(:spec_unit) do |spec|
 end
 
 desc 'Run all specs'
+task :spec_ci do
+  Rake::Task[:spec_unit].execute
+  Rake::Task[:spec_functional].execute
+end
+
+desc 'Run all specs for all gemfiles'
 task :spec do
-  if ENV['TRAVIS'] # travis handles the environments for us
-    Rake::Task[:spec_unit].execute
-    Rake::Task[:spec_functional].execute
-  else
-    %w(4_0 4_1 4_2).each do |version|
-      Bundler.with_clean_env do
-        puts "Running tests with ActiveSupport #{version.sub('_', '.')}"
-        sh "env BUNDLE_GEMFILE=gemfiles/active_support_#{version} bundle install"
-        sh "env BUNDLE_GEMFILE=gemfiles/active_support_#{version} bundle exec rake spec_unit spec_functional"
-      end
+  %w(6_1 6_0 5_2 5_1 5_0).each do |version|
+    Bundler.with_clean_env do
+      puts "Running tests with ActiveSupport #{version.sub('_', '.')}"
+      sh "env BUNDLE_GEMFILE=gemfiles/active_support_#{version} bundle install"
+      sh "env BUNDLE_GEMFILE=gemfiles/active_support_#{version} bundle exec rake spec_unit spec_functional"
     end
   end
 end

data/couch_potato-rspec.gemspec

@@ -11,10 +11,11 @@ Gem::Specification.new do |s|
   s.version     = CouchPotato::RSPEC_VERSION
   s.platform    = Gem::Platform::RUBY
 
-  s.add_dependency 'rspec', '~>3.0'
+  s.add_dependency 'rspec', '~>3.4'
   s.add_development_dependency 'rake'
+  s.add_dependency 'execjs', '~>2.7.0'
 
-  s.files         = `git ls-files | grep "lib/couch_potato/rspec"`.split("\n")
+  s.files         = `git ls-files | grep "lib/couch_potato/rspec\|vendor/pouchdb-collate"`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/* | grep rspec_matchers`.split("\n")
   s.require_paths = ['lib']
 end

data/couch_potato.gemspec

@@ -1,4 +1,6 @@
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'couch_potato/version'
 
 Gem::Specification.new do |s|
@@ -11,17 +13,17 @@ Gem::Specification.new do |s|
   s.version     = CouchPotato::VERSION
   s.platform    = Gem::Platform::RUBY
 
-  s.add_dependency 'json', '~> 1.6'
-  s.add_dependency 'couchrest', '~>2.0.0.rc3'
-  s.add_dependency 'activemodel', '~> 4.0'
+  s.add_dependency 'activemodel', ['>= 5.0', '< 7.0']
+  s.add_dependency 'couchrest', '~>2.0.0'
+  s.add_dependency 'json', '~> 2.3'
 
-  s.add_development_dependency 'rspec', '~>3.2.0'
+  s.add_development_dependency 'rake', '~>12.0'
+  s.add_development_dependency 'rspec', '~>3.5.0'
   s.add_development_dependency 'timecop'
   s.add_development_dependency 'tzinfo'
-  s.add_development_dependency 'rake'
 
   s.files         = `git ls-files | grep -v "lib/couch_potato/rspec"`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/* | grep -v rspec_matchers`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map {|f| File.basename(f) }
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   s.require_paths = ['lib']
 end

data/gemfiles/active_support_5_0

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'activemodel', '~>5.0.0'
+gem 'rails', '~>5.0.0'
+gem 'execjs'
+
+gemspec name: 'couch_potato', path: '..'

data/gemfiles/active_support_5_1

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'activemodel', '~>5.1.7'
+gem 'rails', '~>5.1.7'
+gem 'execjs'
+
+gemspec name: 'couch_potato', path: '..'

data/gemfiles/active_support_5_2

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'activemodel', '~>5.2.3'
+gem 'rails', '~>5.2.3'
+gem 'execjs'
+
+gemspec name: 'couch_potato', path: '..'

data/gemfiles/active_support_6_0

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'activemodel', '~>6.0.2.2'
+gem 'rails', '~>6.0.2.2'
+gem 'execjs'
+
+gemspec name: 'couch_potato', path: '..'

data/gemfiles/active_support_6_1

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem 'activemodel', '~>6.1'
+gem 'rails', '~>6.1'
+gem 'execjs'
+
+gemspec name: 'couch_potato', path: '..'