unread 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in unread.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010,2011 Georg Ledermann
+
+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,133 @@
+Unread
+======
+
+Gem to manage read/unread status of ActiveRecord objects - and it's fast.
+
+
+## Features
+
+* Manages unread records for anything you want your users to read (like messages, documents, comments etc.)
+* Supports "mark as read" to mark a **single** record as read
+* Supports "mark all as read" to mark **all** records as read in a single step
+* Gives you a named_scope to get the unread records for a given user
+* Needs only one additional database table
+* Most important: Great performance
+
+
+## Requirements
+
+* ActiveRecord (tested with SQLite and MySQL)
+* Needs a timestamp field in your models (e.g. created_at) with a database index on it
+
+
+## Installation
+
+Step 1: Add this to your Gemfile:
+  
+    gem 'unread'
+    
+  and run
+  
+    bundle
+  
+    
+Step 2: Add this migration:
+    
+    class CreateReadMarks < ActiveRecord::Migration
+      def self.up
+        create_table :read_marks, :force => true do |t|
+          t.integer  :readable_id
+          t.integer  :user_id,       :null => false
+          t.string   :readable_type, :null => false, :limit => 20
+          t.datetime :timestamp
+        end
+        add_index :read_marks, [:user_id, :readable_type, :readable_id]
+      end
+
+      def self.down
+        drop_table :read_marks
+      end
+    end
+
+  and run the migration:
+    
+    rake db:migrate
+
+
+## Usage
+
+    class User < ActiveRecord::Base
+      acts_as_reader
+    end
+    
+    class Message < ActiveRecord::Base
+      acts_as_readable :on => :created_at
+    end
+
+    message1 = Message.create!
+    message2 = Message.create!
+    
+    Message.unread_by(current_user)
+    # => [ message1, message2 ]
+    
+    message1.mark_as_read! :for => current_user
+    Message.unread_by(current_user)
+    # => [ message2 ]
+    
+    Message.mark_as_read! :all, :for => current_user
+    Message.unread_by(current_user)
+    # => [ ]
+    
+    # Optional: Cleaning up unneeded markers
+    # Do this in a cron job once a day.
+    Message.cleanup_read_marks!
+
+
+## How does it work?
+
+The main idea of this gem is to manage a list of read items for every user **after** a certain timestamp.
+
+The gem defines a named_scope doing a LEFT JOIN to this list, so your app can get the unread items in a performant manner. Of course, other scopes can be combined.
+
+It will be ensured that the list of read items will not grow up too much:
+
+* If a user uses "mark all as read", his list is deleted and the timestamp is set to the current time.
+* If a user never uses "mark all as read", the list will grow and grow with each item he reads. But there is help: Your app can use a cleanup method which removes unnecessary list items.
+
+Overall, this gem can be used for large tables, too. If you are in doubt, look at the generated SQL queries, here is an example:
+
+    # Assuming we have a user who has marked all messages as read on 2010-10-20 08:50
+    current_user = User.find(42) 
+    
+    # Get the unread messages for this user
+    Message.unread_by(current_user)
+    
+    # => 
+    #     SELECT messages.* 
+    #     FROM messages
+    #     LEFT JOIN read_marks ON read_marks.readable_type = 'Message'
+    #                         AND read_marks.readable_id = messages.id
+    #                         AND read_marks.user_id = 42
+    #                         AND read_marks.timestamp >= messages.created_at 
+    #     WHERE read_marks.id IS NULL 
+    #     AND messages.created_at > '2010-10-20 08:50:00'
+
+    Hint: You should add a database index on messages.created_at.
+
+
+## Similar tools
+
+There a two other gems/plugins doing a similar job:
+
+* http://github.com/jhnvz/mark_as_read
+* http://github.com/mbleigh/acts-as-readable
+
+Unfortunately, both of them have a lack of performance, because they calculate the unread records doing a _find(:all)_, which should be avoided for a large amount of records. This gem is based on a timestamp algorithm and therefore it's very fast.
+
+
+## TODO
+
+* Add more documentation
+
+
+Copyright (c) 2010,2011 Georg Ledermann, released under the MIT license

data/Rakefile

@@ -0,0 +1,15 @@
+require 'bundler/gem_tasks'
+
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the unread plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end

data/changelog.md

@@ -0,0 +1,3 @@
+0.0.1 - 2011/06/23
+
+* Released as Gem

data/init.rb

@@ -0,0 +1 @@
+require 'unread' 

data/lib/app/models/read_mark.rb

@@ -0,0 +1,20 @@
+class ReadMark < ActiveRecord::Base
+  belongs_to :user
+  belongs_to :readable, :polymorphic => true
+  
+  validates_presence_of :user_id, :readable_type
+  
+  scope_method = respond_to?(:scope) ? :scope : :named_scope
+  
+  send scope_method, :global, :conditions => { :readable_id => nil }
+  send scope_method, :single, :conditions => 'readable_id IS NOT NULL'
+  send scope_method, :readable_type, lambda { |readable_type | { :conditions => { :readable_type => readable_type }}}
+  send scope_method, :user,          lambda { |user|           { :conditions => { :user_id => user.id }}}
+  send scope_method, :older_than,    lambda { |timestamp|      { :conditions => [ 'timestamp < ?', timestamp] }}
+  
+  if respond_to?(:class_attribute)
+    class_attribute :reader_class, :readable_classes
+  else
+    class_inheritable_accessor :reader_class, :readable_classes
+  end
+end

data/lib/unread/acts_as_readable.rb

@@ -0,0 +1,183 @@
+module Unread
+  def self.included(base)
+    base.extend ActsAsReadable
+  end
+  
+  module ActsAsReadable
+    def acts_as_reader
+      ReadMark.reader_class = self
+      
+      has_many :read_marks, :dependent => :delete_all
+      
+      after_create do |user|
+        (ReadMark.readable_classes || []).each do |klass|
+          klass.mark_as_read! :all, :for => user
+        end
+      end
+    end
+    
+    def acts_as_readable(options={})
+      options.reverse_merge!({ :on => :updated_at })
+      if respond_to?(:class_attribute)
+        class_attribute :readable_options
+      else
+        class_inheritable_accessor :readable_options
+      end
+      self.readable_options = options
+      
+      self.has_many :read_marks, :as => :readable, :dependent => :delete_all
+      
+      classes = ReadMark.readable_classes || []
+      classes << self
+      ReadMark.readable_classes = classes
+      
+      scope_method = respond_to?(:scope) ? :scope : :named_scope
+      
+      send scope_method, :unread_by, lambda { |user| 
+        check_reader
+        raise ArgumentError unless user.is_a?(ReadMark.reader_class)
+
+        result = { :joins => "LEFT JOIN read_marks ON read_marks.readable_type  = '#{self.base_class.name}'
+                                                  AND read_marks.readable_id    = #{self.table_name}.id
+                                                  AND read_marks.user_id        = #{user.id}
+                                                  AND read_marks.timestamp     >= #{self.table_name}.#{readable_options[:on]}",
+                   :conditions => 'read_marks.id IS NULL' }
+        if last = read_timestamp(user)
+          result[:conditions] += " AND #{self.table_name}.#{readable_options[:on]} > '#{last.to_s(:db)}'"
+        end
+        result
+      }
+      
+      extend ClassMethods
+      include InstanceMethods
+    end
+  end
+  
+  module ClassMethods
+    def mark_as_read!(target, options)
+      check_reader
+      raise ArgumentError unless target == :all || target.is_a?(Array)
+      
+      user = options[:for]
+      raise ArgumentError unless user.is_a?(ReadMark.reader_class)
+      
+      if target == :all
+        reset_read_marks!(user)
+      elsif target.is_a?(Array)  
+        ReadMark.transaction do
+          last = read_timestamp(user)
+      
+          target.each do |obj|
+            raise ArgumentError unless obj.is_a?(self)
+        
+            rm = ReadMark.user(user).readable_type(self.base_class.name).find_by_readable_id(obj.id) ||
+                 user.read_marks.build(:readable_id => obj.id, :readable_type => self.base_class.name)
+            rm.timestamp = obj.send(readable_options[:on])
+            rm.save!
+          end
+        end
+      end
+    end
+    
+    def read_mark(user)
+      check_reader
+      raise ArgumentError unless user.is_a?(ReadMark.reader_class)
+      
+      user.read_marks.readable_type(self.base_class.name).global.first
+    end
+    
+    def read_timestamp(user)
+      read_mark(user).try(:timestamp)
+    end
+
+    def set_read_mark(user, timestamp)
+      rm = read_mark(user) || user.read_marks.build(:readable_type => self.base_class.name)
+      rm.timestamp = timestamp
+      rm.save!
+    end    
+
+    # A scope with all items accessable for the given user
+    # It's used in cleanup_read_marks! to support a filtered cleanup
+    # Should be overriden if a user doesn't have access to all items
+    # Default: User has access to all items and should read them all
+    #
+    # Example:
+    #   def Message.read_scope(user)
+    #     user.visible_messages
+    #   end
+    def read_scope(user)
+      self
+    end
+
+    def cleanup_read_marks!
+      check_reader
+      
+      ReadMark.reader_class.find_each do |user|
+        ReadMark.transaction do
+          # Get the timestamp of the oldest unread item the user has access to
+          oldest_timestamp = read_scope(user).unread_by(user).minimum(readable_options[:on])
+
+          if oldest_timestamp
+            # Delete markers OLDER than this timestamp and move the global timestamp for this user
+            user.read_marks.readable_type(self.base_class.name).single.older_than(oldest_timestamp).delete_all
+            set_read_mark(user, oldest_timestamp - 1.second)
+          else
+            # There is no unread item, so mark all as read (which deletes all markers)
+            mark_as_read!(:all, :for => user)
+          end
+        end
+      end
+    end
+    
+    def reset_read_marks!(user = :all)
+      check_reader
+
+      ReadMark.transaction do
+        if user == :all
+          ReadMark.delete_all :readable_type => self.base_class.name
+      
+          ReadMark.connection.execute("
+            INSERT INTO read_marks (user_id, readable_type, timestamp)
+            SELECT id, '#{self.base_class.name}', '#{Time.now.to_s(:db)}'
+            FROM #{ReadMark.reader_class.table_name}
+          ")
+        else
+          ReadMark.delete_all :readable_type => self.base_class.name, :user_id => user.id
+          ReadMark.create!    :readable_type => self.base_class.name, :user_id => user.id, :timestamp => Time.now
+        end
+      end
+      true
+    end
+    
+    def check_reader
+      raise RuntimeError, 'Plugin "unread": No reader defined!' unless ReadMark.reader_class
+    end
+  end
+  
+  module InstanceMethods 
+    def unread?(user)
+      self.class.unread_by(user).exists?(self)
+    end
+    
+    def mark_as_read!(options)
+      self.class.check_reader
+      
+      user = options[:for]
+      raise ArgumentError unless user.is_a?(ReadMark.reader_class)
+      
+      ReadMark.transaction do
+        if unread?(user)
+          rm = read_mark(user) || read_marks.build(:user => user)
+          rm.timestamp = self.send(readable_options[:on])
+          rm.save!
+        end
+      end
+    end
+
+    def read_mark(user)
+      read_marks.user(user).first
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Unread

data/lib/unread/version.rb

@@ -0,0 +1,3 @@
+module Unread
+  VERSION = "0.0.1"
+end

data/lib/unread.rb

@@ -0,0 +1,3 @@
+require 'unread/version'
+require 'app/models/read_mark'
+require 'unread/acts_as_readable'

data/test/database.yml

@@ -0,0 +1,3 @@
+sqlite3mem:
+  adapter: sqlite3
+  database: ":memory:"

data/test/schema.rb

@@ -0,0 +1,20 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :users, :force => true do |t|
+    t.string :name
+  end
+  
+  create_table :emails, :force => true do |t|
+    t.string :subject
+    t.text :content
+    t.datetime :created_at
+    t.datetime :updated_at
+  end
+  
+  create_table :read_marks, :force => true do |t|
+    t.integer  :readable_id
+    t.integer  :user_id,       :null => false
+    t.string   :readable_type, :null => false
+    t.datetime :timestamp
+  end
+  add_index :read_marks, [:user_id, :readable_type, :readable_id]
+end

data/test/test_helper.rb

@@ -0,0 +1,24 @@
+require 'rubygems'
+
+gem 'activerecord'
+gem 'mocha'
+
+require 'test/unit'
+require 'active_record'
+require 'active_support'
+require 'active_support/test_case'
+
+require File.dirname(__FILE__) + '/../init.rb'
+
+config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+ActiveRecord::Base.establish_connection(config['sqlite3mem'])
+ActiveRecord::Migration.verbose = false
+load(File.dirname(__FILE__) + "/schema.rb")
+
+class User < ActiveRecord::Base
+  acts_as_reader
+end
+
+class Email < ActiveRecord::Base
+  acts_as_readable :on => :updated_at
+end

data/test/unread_test.rb

@@ -0,0 +1,132 @@
+require 'test_helper'
+
+class UnreadTest < ActiveSupport::TestCase
+  def setup
+    @user = User.create! :name => 'David'
+    @other_user = User.create :name => 'Matz'
+    wait
+    @email1 = Email.create!
+    wait
+    @email2 = Email.create!
+  end
+  
+  def teardown
+    User.delete_all
+    Email.delete_all
+    ReadMark.delete_all
+  end
+  
+  def test_schema_has_loaded_correctly
+    assert_equal [@email1, @email2], Email.all
+  end
+
+  def test_scope
+    assert_equal [@email1, @email2], Email.unread_by(@user)
+    assert_equal [@email1, @email2], Email.unread_by(@other_user)
+    
+    assert_equal 2, Email.unread_by(@user).count
+    assert_equal 2, Email.unread_by(@other_user).count
+  end
+  
+  def test_scope_after_reset
+    @email1.mark_as_read! :for => @user
+    
+    assert_equal [@email2], Email.unread_by(@user)
+    assert_equal 1, Email.unread_by(@user).count
+  end
+
+  def test_unread_by
+    assert_equal true, @email1.unread?(@user)
+    assert_equal true, @email1.unread?(@other_user)
+  end
+  
+  def test_unread_after_update
+    @email1.mark_as_read! :for => @user
+    wait
+    @email1.update_attributes! :subject => 'changed'
+
+    assert_equal true, @email1.unread?(@user)
+  end
+  
+  def test_mark_as_read
+    @email1.mark_as_read! :for => @user
+    
+    assert_equal false, @email1.unread?(@user)
+    assert_equal [@email2], Email.unread_by(@user)
+    
+    assert_equal true, @email1.unread?(@other_user)
+    assert_equal [@email1, @email2], Email.unread_by(@other_user)
+    
+    assert_equal 1, @user.read_marks.single.count
+    assert_equal @email1, @user.read_marks.single.first.readable
+  end
+  
+  def test_mark_as_read_multiple
+    assert_equal true, @email1.unread?(@user)
+    assert_equal true, @email2.unread?(@user)
+    
+    Email.mark_as_read! [ @email1, @email2 ], :for => @user
+    
+    assert_equal false, @email1.unread?(@user)
+    assert_equal false, @email2.unread?(@user)
+  end
+  
+  def test_mark_as_read_with_marked_all
+    wait
+    
+    Email.mark_as_read! :all, :for => @user
+    @email1.mark_as_read! :for => @user
+    
+    assert_equal [], @user.read_marks.single
+  end
+  
+  def test_mark_as_read_twice
+    @email1.mark_as_read! :for => @user
+    @email1.mark_as_read! :for => @user
+    
+    assert_equal 1, @user.read_marks.single.count
+  end
+  
+  def test_mark_all_as_read
+    Email.mark_as_read! :all, :for => @user
+    assert_equal Time.now.to_s, Email.read_mark(@user).timestamp.to_s
+    
+    assert_equal [], @user.read_marks.single
+    assert_equal 0, ReadMark.single.count
+    assert_equal 2, ReadMark.global.count
+  end
+  
+  def test_cleanup_read_marks
+    assert_equal 0, @user.read_marks.single.count
+    
+    @email1.mark_as_read! :for => @user
+    
+    assert_equal [@email2], Email.unread_by(@user)
+    assert_equal 1, @user.read_marks.single.count
+    
+    Email.cleanup_read_marks!    
+    
+    @user.reload
+    assert_equal 0, @user.read_marks.single.count
+  end
+  
+  def test_cleanup_read_marks_not_delete_from_other_readables
+    other_read_mark = @user.read_marks.create! :readable_type => 'Foo', :readable_id => 42, :timestamp => 5.years.ago
+    Email.cleanup_read_marks!
+    assert_equal true, ReadMark.exists?(other_read_mark.id)
+  end
+  
+  def test_reset_read_marks_for_all
+    Email.reset_read_marks!
+    
+    assert_equal 0, ReadMark.single.count
+    assert_equal 2, ReadMark.global.count
+  end
+  
+private
+  def wait
+    # Skip one second
+    now = Time.now + 1.second
+    Time.stubs(:now).returns(now)
+  end
+end

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

data/unread.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "unread/version"
+
+Gem::Specification.new do |s|
+  s.name        = "unread"
+  s.version     = Unread::VERSION
+  s.authors     = ["Georg Ledermann"]
+  s.email       = ["mail@georg-ledermann.de"]
+  s.homepage    = ""
+  s.summary     = %q{Manages read/unread status of ActiveRecord objects}
+  s.description = %q{This gem creates a scope for unread objects and adds methods to mark objects as read }
+
+  s.rubyforge_project = "unread"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_dependency 'activerecord', '>= 2.3'
+  s.add_dependency 'activesupport', '>= 2.3'
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification 
+name: unread
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Georg Ledermann
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-23 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 2
+        - 3
+        version: "2.3"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 2
+        - 3
+        version: "2.3"
+  type: :runtime
+  version_requirements: *id002
+description: "This gem creates a scope for unread objects and adds methods to mark objects as read "
+email: 
+- mail@georg-ledermann.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README.md
+- Rakefile
+- changelog.md
+- init.rb
+- lib/app/models/read_mark.rb
+- lib/unread.rb
+- lib/unread/acts_as_readable.rb
+- lib/unread/version.rb
+- test/database.yml
+- test/schema.rb
+- test/test_helper.rb
+- test/unread_test.rb
+- uninstall.rb
+- unread.gemspec
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: unread
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Manages read/unread status of ActiveRecord objects
+test_files: 
+- test/database.yml
+- test/schema.rb
+- test/test_helper.rb
+- test/unread_test.rb