timeful 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8f3483ad41973a14436a441189dc9ae9f6ad6a40
+  data.tar.gz: 008af65f6a63f6dd6e8ffead55c67330e0d303b8
+SHA512:
+  metadata.gz: f2044cb33f76b7e6db9fb08cc25a62eff75c48d54eb4aece32a2abb9d3c720a924316659ee76021639999d4723478b039715a0caae8905794e179f55e5d2b201
+  data.tar.gz: 7fd5b9e367d372efb26d57f568579e16ff6457473a1d28b0fb158f9354f68bb0b50aff0dec3eb7b35edb22d0612d864698bae9e7396e66baf3923a9fc1668f52

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Alessandro Desantis
+
+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,112 @@
+# Timeful
+
+[![Gem Version](https://img.shields.io/gem/v/timeful.svg?maxAge=3600&style=flat-square)](https://rubygems.org/gems/timeful)
+[![Dependency Status](https://img.shields.io/gemnasium/alessandro1997/timeful.svg?maxAge=3600&style=flat-square)](https://gemnasium.com/github.com/alessandro1997/timeful)
+[![Code Climate](https://img.shields.io/codeclimate/github/alessandro1997/timeful.svg?maxAge=3600&style=flat-square)](https://codeclimate.com/github/alessandro1997/timeful)
+
+Timeful is a Ruby on Rails engine for building timelines (aka "activity streams").
+
+## Why another gem?
+
+There are battle-tested activity stream builders out there already (the most known being
+[PublicActivity][public_activity], [TimelineFu][timeline_fu] and [Social Stream][social_stream].
+However, these gems do not really create a feed for each user, but simply record a list of global
+activities and leave you to deal with the retrieval.
+
+Timeful is different: it takes a simple approach at building user feeds and allows you to obtain
+an ordered list of feed items for each user.
+
+Also, Timeful does not handle presentation: you will have to build your own views and controllers to
+expose feeds. This keeps the codebase smaller and allows you to easily integrate Timeful in JSON
+APIs.
+
+[public_activity]: https://github.com/chaps-io/public_activity
+[timeline_fu]: https://github.com/jamesgolick/timeline_fu
+[social_stream]: https://github.com/ging/social_stream
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'timeful'
+```
+
+And then execute:
+
+```console
+$ bundle
+```
+
+Or install it yourself as:
+
+```console
+$ gem install timeful
+```
+
+Then, run the installer generator:
+
+```console
+$ rails g timeful:install
+$ rake db:migrate
+```
+
+Finally, add the following to the model that will have a feed and publish activities (this is
+usually your `User` model, but you can use two different models):
+
+```ruby
+class User < ActiveRecord::Base
+  include Timeful::Model::Actor
+  include Timeful::Model::Subscriber
+end
+```
+
+## Usage
+
+Timeful revolves around three core concepts:
+
+- **Activity**: An _action_ taken by an _actor_ on an _object_. _Metadata_ can also be attached to
+  activities. An example would be "John Doe (actor) wrote (action) a comment (object)."
+- **Feed**: A collection of activities that should be accessible by a specific user.
+- **Feed item**: The instance of an activity in a user's feed.
+
+Each activity action (or "type") has its own class. This is required because Timeful has to know
+which feeds the activity should be added to.
+
+To avoid polluting `app/models`, it is recommended to put your activities in the `app/activities`
+directory.
+
+Here's an example activity:
+
+```ruby
+class CommentActivity < Timeful::Activity
+  def subscribers
+    [object.post.author]
+  end
+end
+```
+
+Now, you can publish the `comment` activity:
+
+```ruby
+user.publish_activity :comment, object: comment
+```
+
+This will create an `Activity` and link it to the author's feed through a `FeedItem`:
+
+```ruby
+author = comment.post.author
+author.feed_items.count # => 1
+```
+
+## Performance
+
+TODO: Write performance considerations
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alessandro1997/timeful.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,31 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+require 'rake/testtask'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Timeful'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+load 'rails/tasks/statistics.rake'
+
+Bundler::GemHelper.install_tasks
+
+Rake::TestTask.new(:spec) do |t|
+  t.libs << 'lib'
+  t.libs << 'spec'
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = false
+end
+
+task default: :spec

data/app/jobs/timeful/deliver_activity_to_subscribers_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module Timeful
+  # Creates a feed item for each subscriber of the activity.
+  #
+  # @author Alessandro Desantis
+  class DeliverActivityToSubscribersJob < ActiveJob::Base
+    queue_as { Timeful.jobs_queue }
+
+    def perform(activity)
+      RelationProxy.new(activity.subscribers).find_each do |subscriber|
+        subscriber.feed_items.create!(activity: activity)
+      end
+    end
+  end
+end

data/app/models/timeful/activity.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+module Timeful
+  # An activity is something that happens in your application. It's comprised of an actor, an
+  # action and an object.
+  #
+  # An example activity might be: "John Doe (actor) published (action) a new post (object)."
+  #
+  # @author Alessandro Desantis
+  #
+  # @abstract Subclass and override {#subscribers} to implement your own activity
+  #
+  # @example
+  #   class CommentCreatedActivity < Timeful::Activity
+  #     def subscribers
+  #       [object.post.author]
+  #     end
+  #   end
+  class Activity < ApplicationRecord
+    belongs_to :actor, polymorphic: true
+    belongs_to :object, polymorphic: true
+
+    # Returns the users that subscribe to this activity. A {FeedItem} linked to the activity will
+    # be created for these users.
+    #
+    # The returned value can be an instance of either +ActiveRecord::Relation+ or +Array+. The
+    # former is preferred when the subscribers list is very long, as we'll automatically use
+    # +find_each+ to reduce memory usage if it's available.
+    #
+    # @raise NotImplementedError
+    def subscribers
+      fail NotImplementedError
+    end
+  end
+end

data/app/models/timeful/application_record.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module Timeful
+  class ApplicationRecord < ActiveRecord::Base # rubocop:disable Style/Documentation
+    self.abstract_class = true
+  end
+end

data/app/models/timeful/feed_item.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Timeful
+  # A feed item is an instance of an activity in a specific user's feed.
+  #
+  # Feed items are automatically created by Timeful when an activity is created for all subscribers
+  # of the activty.
+  #
+  # @author Alessandro Desantis
+  class FeedItem < ApplicationRecord
+    belongs_to :feedable, polymorphic: true
+    belongs_to :activity
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Timeful::Engine.routes.draw do
+end

data/db/migrate/20160927141608_create_timeful_activities.rb

@@ -0,0 +1,16 @@
+class CreateTimefulActivities < ActiveRecord::Migration[5.0]
+  def change
+    create_table :timeful_activities do |t|
+      t.string :type, null: false
+      t.string :object_type, null: false
+      t.integer :object_id, null: false
+      t.string :actor_type, null: false
+      t.integer :actor_id, null: false
+
+      t.timestamps null: false
+
+      t.index [:object_type, :object_id]
+      t.index [:actor_type, :actor_id]
+    end
+  end
+end

data/db/migrate/20160927154912_create_timeful_feed_items.rb

@@ -0,0 +1,15 @@
+class CreateTimefulFeedItems < ActiveRecord::Migration[5.0]
+  def change
+    create_table :timeful_feed_items do |t|
+      t.string :feedable_type, null: false
+      t.integer :feedable_id, null: false
+      t.integer :activity_id, null: false
+
+      t.timestamps null: false
+
+      t.foreign_key :timeful_activities, column: :activity_id, on_delete: :cascade
+
+      t.index [:feedable_type, :feedable_id]
+    end
+  end
+end

data/lib/generators/timeful/install_generator.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+module Timeful
+  class InstallGenerator < Rails::Generators::Base # rubocop:disable Style/Documentation
+    source_root File.expand_path('../templates', __FILE__)
+
+    def copy_initializer_file
+      rake 'timeful:install:migrations'
+    end
+  end
+end

data/lib/timeful.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+require 'timeful/version'
+
+require 'timeful/relation_proxy'
+
+require 'timeful/model/actor'
+require 'timeful/model/subscriber'
+
+require 'timeful/engine'
+
+module Timeful # rubocop:disable Style/Documentation
+  # !@attribute [rw]
+  #   @return [Symbol] the queue to use for background jobs (default is +default+)
+  mattr_accessor :jobs_queue
+  self.jobs_queue = :default
+
+  # Yields the module for configuration.
+  #
+  # @yieldparam config [Timeful] the +Timeful+ module
+  #
+  # @example
+  #   Timeful.configure do |config|
+  #     config.jobs_queue = :timeful
+  #   end
+  def self.configure
+    yield self
+  end
+end

data/lib/timeful/engine.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+module Timeful
+  class Engine < ::Rails::Engine # rubocop:disable Style/Documentation
+    isolate_namespace Timeful
+  end
+end

data/lib/timeful/model/actor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Timeful
+  module Model
+    # An actor can publish activities.
+    #
+    # @author Alessandro Desantis
+    module Actor
+      def self.included(klass)
+        klass.include InstanceMethods
+      end
+
+      module InstanceMethods # rubocop:disable Style/Documentation
+        # Publishes an activity and creates a feed item for each subscriber.
+        #
+        # @param action [Symbol] the action (or activity type) to create
+        # @param object [ActiveRecord::Base] the object the action was taken upon
+        #
+        # @return [Activity] the created activity
+        #
+        # @example
+        #   actor.publish_activity :post_created, object: post # => #<PostCreatedActivity>
+        def publish_activity(action, object:)
+          activity = activity_klass(action).create! object: object, actor: self
+          DeliverActivityToSubscribersJob.perform_later activity
+        end
+
+        private
+
+        def activity_klass(action)
+          "#{action.to_s.camelize}Activity".constantize
+        end
+      end
+    end
+  end
+end

data/lib/timeful/model/subscriber.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module Timeful
+  module Model
+    # A subscriber can subscribe to activities and get a new feed item for each new instance of
+    # that activity.
+    #
+    # @author Alessandro Desantis
+    #
+    # @example
+    #   subscriber.feed_items # => #<ActiveRecord::Associations::CollectionProxy>
+    module Subscriber
+      def self.included(klass)
+        klass.class_eval do
+          has_many :feed_items, -> { order(created_at: :desc) },
+            as: :feedable,
+            class_name: 'Timeful::FeedItem'
+        end
+      end
+    end
+  end
+end

data/lib/timeful/relation_proxy.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+module Timeful
+  # Makes +Array+ behave much like +ActiveRecord::Relation+.
+  #
+  # This proxy class wraps an +Array+ or +ActiveRecord::Relation+ instance and makes the former
+  # behave like the latter by simulating methods like +find_each+.
+  #
+  # @author Alessandro Desantis
+  class RelationProxy < SimpleDelegator
+    # If +find_each+ is defined on the object we're delegating to (i.e. the object is an instance
+    # of +ActiveRecord::Relation+), calls it on the object.
+    #
+    # Otherwise, calls +each+ on the object and yields the values.
+    #
+    # @yieldparam item [Object] the items in the object
+    def find_each(*args, &block)
+      method = if __getobj__.respond_to?(:find_each)
+        :find_each
+      else
+        :each
+      end
+
+      __getobj__.send(method, *args, &block)
+    end
+  end
+end

data/lib/timeful/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module Timeful
+  VERSION = '0.0.1'
+end

data/spec/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.