ta_has_event 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 951ce881bec2caac969973595dd1345226ed2213bd35b66223facb8377229bdb
+  data.tar.gz: 655feb6da1c124ef7fb156a91191580b4777eb34562e15338f01da9175648ec7
+SHA512:
+  metadata.gz: ab7f97b14543cec599bc5a4118e97fe8dae1b5c03d53c86b3046c1c37f0d2a76a097b555be01881ac0deb862df263b0a73ec77da2abb7a515be3fbae4bcb232a
+  data.tar.gz: b16fad751df98adab0dffd1448b6b7375299c33dee89a6d709b821e29c2f828e4355f82c7a1f7620e7b2fd2e2b88d276572095d83896ed0f293d695105ef86e3

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 Bartosz Pieńkowski
+
+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,214 @@
+# ActiveRecord::Events [![Gem version](https://img.shields.io/gem/v/active_record-events)](https://rubygems.org/gems/active_record-events) [![Build status](https://img.shields.io/travis/pienkowb/active_record-events/develop)](https://travis-ci.org/pienkowb/active_record-events) [![Coverage status](https://img.shields.io/coveralls/github/pienkowb/active_record-events/develop)](https://coveralls.io/github/pienkowb/active_record-events) [![Maintainability status](https://img.shields.io/codeclimate/maintainability/pienkowb/active_record-events)](https://codeclimate.com/github/pienkowb/active_record-events)
+
+An ActiveRecord extension providing convenience methods for timestamp management.
+
+## Screencast
+
+<a href="https://www.youtube.com/watch?v=TIR7YDF3O-4">
+  <img src="https://img.youtube.com/vi/TIR7YDF3O-4/maxresdefault.jpg" title="ActiveRecord::Events - Awesome Ruby Gems" width="50%">
+</a>
+
+[Watch screencast](https://www.youtube.com/watch?v=TIR7YDF3O-4) (courtesy of [Mike Rogers](https://github.com/MikeRogers0))
+
+## Installation
+
+Add the following line to your application's Gemfile:
+
+```ruby
+gem 'active_record-events'
+```
+
+Install the gem with Bundler:
+
+```
+$ bundle install
+```
+
+Or do it manually by running:
+
+```
+$ gem install active_record-events
+```
+
+## Usage
+
+Recording a timestamp in order to mark that an event occurred to an object is a common practice when dealing with ActiveRecord models.
+A good example of such an approach is how ActiveRecord handles the `created_at` and `updated_at` fields.
+This gem allows you to manage custom timestamp fields in the exact same manner.
+
+### Example
+
+Consider a `Task` model with a `completed_at` field and the following methods:
+
+```ruby
+class Task < ActiveRecord::Base
+  def completed?
+    completed_at.present?
+  end
+
+  def not_completed?
+    !completed?
+  end
+
+  def complete
+    complete! if not_completed?
+  end
+
+  def complete!
+    touch(:completed_at)
+  end
+
+  def self.complete_all
+    touch_all(:completed_at)
+  end
+end
+```
+
+Instead of defining all of these methods by hand, you can use the `has_event` macro provided by the gem.
+
+```ruby
+class Task < ActiveRecord::Base
+  has_event :complete
+end
+```
+
+As a result, the methods will be generated automatically.
+
+*It's important to note that the `completed_at` column has to already exist in the database.*
+*Consider [using the generator](#using-a-rails-generator) to create a necessary migration.*
+
+### Scopes
+
+In addition, the macro defines two scope methods – one for retrieving objects with a recorded timestamp and one for those without it, for example:
+
+```ruby
+scope :not_completed, -> { where(completed_at: nil) }
+scope :completed, -> { where.not(completed_at: nil) }
+```
+
+The inclusion of scope methods can be omitted by passing the `skip_scopes` flag.
+
+```ruby
+has_event :complete, skip_scopes: true
+```
+
+### Multiple events
+
+Using the macro is efficient when more than one field has to be handled that way.
+In such a case, many lines of code can be replaced with an expressive one-liner.
+
+```ruby
+has_events :complete, :archive
+```
+
+### Date fields
+
+In case of date fields, which by convention have names ending with `_on` instead of `_at` (e.g. `completed_on`), the `field_type` option needs to be passed to the macro:
+
+```ruby
+has_event :complete, field_type: :date
+```
+
+### Custom field name
+
+If there's a field with a name that doesn't follow the naming convention (i.e. does not end with `_at` or `_on`), you can pass it as the `field_name` option.
+
+```ruby
+has_event :complete, field_name: :completion_time
+```
+
+Note that the `field_name` option takes precedence over the `field_type` option.
+
+### Specifying an object
+
+There are events which do not relate to a model itself but to one of its attributes – take the `User` model with the `email_confirmed_at` field as an example.
+In order to keep method names grammatically correct, you can specify an object using the `object` option.
+
+```ruby
+class User < ActiveRecord::Base
+  has_event :confirm, object: :email
+end
+```
+
+This will generate the following methods:
+
+- `email_not_confirmed?`
+- `email_confirmed?`
+- `confirm_email`
+- `confirm_email!`
+- `confirm_all_emails` (class method)
+
+As well as these two scopes:
+
+- `email_confirmed`
+- `email_not_confirmed`
+
+### Using a Rails generator
+
+If you want to quickly add a new event, you can make use of a Rails generator provided by the gem:
+
+```
+$ rails generate active_record:event task complete
+```
+
+It will create a necessary migration and insert a `has_event` statement into the model class.
+
+```ruby
+# db/migrate/XXX_add_completed_at_to_tasks.rb
+
+class AddCompletedAtToTasks < ActiveRecord::Migration[6.0]
+  def change
+    add_column :tasks, :completed_at, :datetime
+  end
+end
+```
+
+```ruby
+# app/models/task.rb
+
+class Task < ActiveRecord::Base
+  has_event :complete
+end
+```
+
+All of the macro options are supported by the generator and can be passed via the command line.
+For instance:
+
+```
+$ rails generate active_record:event user confirm --object=email --skip-scopes
+```
+
+For more information, run the generator with the `--help` option.
+
+### Overriding methods
+
+If there's a need to override any of the methods generated by the macro, you can define a new method with the same name in the corresponding model class.
+This applies to instance methods as well as class methods.
+In both cases, the `super` keyword invokes the original method.
+
+```ruby
+class Task < ActiveRecord::Base
+  has_event :complete
+
+  def complete!
+    super
+    logger.info("Task #{id} has been completed")
+  end
+
+  def self.complete_all
+    super
+    logger.info('All tasks have been completed')
+  end
+end
+```
+
+## Contributors
+
+- [Bartosz Pieńkowski](https://github.com/pienkowb)
+- [Tomasz Skupiński](https://github.com/tskupinski)
+- [Oskar Janusz](https://github.com/oskaror)
+- [Mike Rogers](https://github.com/MikeRogers0)
+
+## See also
+
+- [ActiveRecord::Enum](https://api.rubyonrails.org/classes/ActiveRecord/Enum.html)

data/Rakefile

@@ -0,0 +1,60 @@
+#!/usr/bin/env rake
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'ActiveRecord::Events'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'active_record'
+require 'yaml'
+
+include ActiveRecord::Tasks
+
+dummy_root = File.expand_path('spec/dummy', __dir__)
+database_config = YAML.load_file("#{dummy_root}/config/database.yml")
+
+DatabaseTasks.root = dummy_root
+DatabaseTasks.env = ENV['RAILS_ENV'] || 'development'
+DatabaseTasks.db_dir = "#{dummy_root}/db"
+DatabaseTasks.database_configuration = database_config
+DatabaseTasks.migrations_paths = "#{dummy_root}/db/migrate"
+
+task :environment do
+  require "#{dummy_root}/config/environment.rb"
+end
+
+ACTIVE_RECORD_MIGRATION_CLASS =
+  if ActiveRecord::VERSION::MAJOR >= 5
+    ActiveRecord::Migration[4.2]
+  else
+    ActiveRecord::Migration
+  end
+
+load 'active_record/railties/databases.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc 'Run all specs in spec directory (excluding plugin specs)'
+RSpec::Core::RakeTask.new(spec: 'db:test:prepare')
+
+task default: :spec

data/lib/active_record/events/extension.rb

@@ -0,0 +1,23 @@
+require 'active_record/events/method_factory'
+
+module ActiveRecord
+  module Events
+    module Extension
+      def has_events(*names)
+        options = names.extract_options!
+        names.each { |n| has_event(n, options) }
+      end
+
+      def has_event(name, options = {})
+        method_factory = MethodFactory.new(name, options)
+
+        naming = method_factory.naming
+        attribute naming.field, naming.field_database_type, index: true
+        attribute naming.boolean_attribute, :boolean, index: true, default: -> { false }
+
+        include method_factory.instance_methods
+        extend method_factory.class_methods
+      end
+    end
+  end
+end

data/lib/active_record/events/macro.rb

@@ -0,0 +1,36 @@
+module ActiveRecord
+  module Events
+    class Macro
+      def initialize(event_name, options)
+        @event_name = event_name.to_s
+        @options = options
+      end
+
+      def to_s
+        "has_event :#{event_name}#{options_list}"
+      end
+
+      private
+
+      def event_name
+        @event_name.underscore
+      end
+
+      def options_list
+        options.unshift('').join(', ') if options.present?
+      end
+
+      def options
+        @options.map { |k, v| "#{k}: #{convert_value(v)}" }
+      end
+
+      def convert_value(value)
+        symbol_or_string?(value) ? ":#{value}" : value
+      end
+
+      def symbol_or_string?(value)
+        value.is_a?(Symbol) || value.is_a?(String)
+      end
+    end
+  end
+end

data/lib/active_record/events/method_factory.rb

@@ -0,0 +1,121 @@
+require 'active_record/events/naming'
+
+module ActiveRecord
+  module Events
+    class MethodFactory
+      attr_reader :naming
+
+      def initialize(event_name, options)
+        @options = options
+        @naming = Naming.new(event_name, options)
+      end
+
+      def instance_methods
+        Module.new.tap do |module_|
+          field_type = naming.field_database_type
+
+          define_predicate_method(module_, naming)
+          define_inverse_predicate_method(module_, naming)
+
+          define_action_method(module_, naming)
+          define_inverse_action_method(module_, naming)
+          define_safe_action_method(module_, naming)
+          define_inverse_safe_action_method(module_, naming)
+          define_boolean_attribute_method(module_, naming)
+        end
+      end
+
+      def class_methods
+        Module.new.tap do |module_|
+          define_collective_action_method(module_, naming)
+
+          unless options[:skip_scopes]
+            define_scope_method(module_, naming)
+            define_inverse_scope_method(module_, naming)
+          end
+        end
+      end
+
+      private
+
+      attr_reader :options
+
+      def define_predicate_method(module_, naming)
+        module_.send(:define_method, naming.predicate) do
+          self[naming.field].present?
+        end
+      end
+
+      def define_inverse_predicate_method(module_, naming)
+        module_.send(:define_method, naming.inverse_predicate) do
+          !__send__(naming.predicate)
+        end
+      end
+
+      def define_action_method(module_, naming)
+        module_.send(:define_method, naming.action) do
+          __send__("#{naming.boolean_attribute}=", true)
+        end
+      end
+
+      def define_inverse_action_method(module_, naming)
+        module_.send(:define_method, naming.inverse_action) do
+          __send__("#{naming.boolean_attribute}=", false)
+        end
+      end
+
+      def define_safe_action_method(module_, naming)
+        module_.send(:define_method, naming.safe_action) do
+          if __send__(naming.inverse_predicate)
+            __send__(naming.action)
+            save!
+          end
+        end
+      end
+
+      def define_inverse_safe_action_method(module_, naming)
+        module_.send(:define_method, naming.inverse_safe_action) do
+          if __send__(naming.inverse_predicate)
+            __send__(naming.inverse_action)
+            save!
+          end
+        end
+      end
+
+      # naming.boolean_attribute=
+      # is_object_completed=
+      def define_boolean_attribute_method(module_, naming)
+        module_.send(:define_method, "#{naming.boolean_attribute}=") do |val|
+          if val == true && self[naming.field].blank?
+            self[naming.field] = current_time_from_proper_timezone
+          elsif val == false && self[naming.field].present?
+            self[naming.field] = nil
+          end
+          super(val)
+        end
+      end
+
+      def define_collective_action_method(module_, naming)
+        module_.send(:define_method, naming.collective_action) do
+          if respond_to?(:touch_all)
+            touch_all(naming.field)
+          else
+            update_all(naming.field => Time.current)
+          end
+        end
+      end
+
+      def define_scope_method(module_, naming)
+        module_.send(:define_method, naming.scope) do
+          where(arel_table[naming.field].not_eq(nil))
+        end
+      end
+
+      def define_inverse_scope_method(module_, naming)
+        module_.send(:define_method, naming.inverse_scope) do
+          where(arel_table[naming.field].eq(nil))
+        end
+      end
+    end
+  end
+end

data/lib/active_record/events/naming.rb

@@ -0,0 +1,85 @@
+require 'verbs'
+
+module ActiveRecord
+  module Events
+    class Naming
+      def initialize(infinitive, options = {})
+        @infinitive = infinitive
+        @object = options[:object].presence
+        @field_name = options[:field_name].to_s
+        @field_type = options[:field_type].try(:to_sym)
+      end
+
+      def field
+        return field_name if field_name.present?
+
+        suffix = field_type == :date ? 'on' : 'at'
+
+        concatenate(object, past_participle, suffix)
+      end
+
+      def field_database_type
+        field_type || :datetime
+      end
+
+      def boolean_attribute
+        concatenate('is', object, past_participle)
+      end
+
+      def predicate
+        concatenate(object, past_participle) + '?'
+      end
+
+      def inverse_predicate
+        concatenate(object, 'not', past_participle) + '?'
+      end
+
+      def action
+        concatenate(infinitive, object)
+      end
+
+      def inverse_action
+        concatenate('not', infinitive, object)
+      end
+
+      def safe_action
+        concatenate(infinitive, object) + '!'
+      end
+
+      def inverse_safe_action
+        concatenate('not', infinitive, object) + '!'
+      end
+
+      def collective_action
+        concatenate(infinitive, 'all', plural_object)
+      end
+
+      def scope
+        concatenate(object, past_participle)
+      end
+
+      def inverse_scope
+        concatenate(object, 'not', past_participle)
+      end
+
+      private
+
+      attr_reader :infinitive
+      attr_reader :object
+      attr_reader :field_name
+      attr_reader :field_type
+
+      def concatenate(*parts)
+        parts.compact.join('_')
+      end
+
+      def past_participle
+        infinitive.verb.conjugate(tense: :past, aspect: :perfective)
+      end
+
+      def plural_object
+        object.to_s.pluralize if object.present?
+      end
+    end
+  end
+end

data/lib/active_record/events/version.rb

@@ -0,0 +1,5 @@
+module ActiveRecord
+  module Events
+    VERSION = '1.0.0'.freeze
+  end
+end

data/lib/active_record/events.rb

@@ -0,0 +1,13 @@
+require 'active_support'
+
+require 'active_record/events/version'
+
+require 'active_record/events/naming'
+require 'active_record/events/method_factory'
+require 'active_record/events/extension'
+
+require 'active_record/events/macro'
+
+ActiveSupport.on_load(:active_record) do
+  extend ActiveRecord::Events::Extension
+end

data/lib/generators/active_record/event/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Generates a database migration and updates the model file (if it exists).
+    Pass the model name, either CamelCased or under_scored, and the event name
+    as an infinitive.
+
+Examples:
+    `bin/rails generate active_record:event task complete`
+
+        Generates a migration adding a `completed_at` column to the `tasks`
+        table and updates the Task model.
+
+    `bin/rails generate active_record:event user confirm --object=email`
+
+        Generates a migration adding an `email_confirmed_at` column to the
+        `users` table and updates the User model.

data/lib/generators/active_record/event/event_generator.rb

@@ -0,0 +1,60 @@
+require 'rails/generators'
+
+require 'active_record/events/naming'
+require 'active_record/events/macro'
+
+module ActiveRecord
+  module Generators
+    class EventGenerator < Rails::Generators::Base
+      MACRO_OPTIONS = %w[object field_type skip_scopes].freeze
+
+      argument :model_name, type: :string
+      argument :event_name, type: :string
+
+      class_option :skip_scopes, type: :boolean,
+        desc: 'Skip the inclusion of scope methods'
+      class_option :field_type, type: :string,
+        desc: 'The field type (datetime or date)'
+      class_option :object, type: :string,
+        desc: 'The name of the object'
+
+      source_root File.expand_path('templates', __dir__)
+
+      def generate_migration_file
+        naming = ActiveRecord::Events::Naming.new(event_name, options)
+
+        table_name = model_name.tableize
+        field_name = naming.field
+        field_type = options[:field_type] || 'datetime'
+
+        migration_name = "add_#{field_name}_to_#{table_name}"
+        attributes = "#{field_name}:#{field_type}"
+
+        invoke 'active_record:migration', [migration_name, attributes]
+      end
+
+      def update_model_file
+        return unless model_file_exists?
+
+        macro_options = options.slice(*MACRO_OPTIONS)
+        macro = ActiveRecord::Events::Macro.new(event_name, macro_options)
+
+        inject_into_file model_file_path, "\s\s#{macro}\n", after: /class.+\n/
+      end
+
+      private
+
+      def model_file_exists?
+        File.exist?(model_file_path)
+      end
+
+      def model_file_path
+        File.expand_path("app/models/#{model_file_name}", destination_root)
+      end
+
+      def model_file_name
+        "#{model_name.underscore.singularize}.rb"
+      end
+    end
+  end
+end