auto_alert 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6115b3cc9d444af3c92d33b3ad3c3152040e0912254a36959d46e732dd3e3634
+  data.tar.gz: 2da6fae49f957aeb5be28a00dd9921feb699ad8d63ea7b83d906e073e9ba6079
+SHA512:
+  metadata.gz: 7934f6257a750d9fa24814e3789e2c30f81c84d903d55688c8fd38a11d6c3ee11f46645cef1101fe43f29dbea8227c19538baff07987d5ae6bda92e7105fc8f7
+  data.tar.gz: dbbb8a284baf98324de67846bc216ec48ef9912f74e09b1ef9e5120849cb6970bdf8dbe0f1bc61272532abbec2d672022db01e22ad5eec5800d8dcdee1e5d738

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Brendan Tang
+
+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,175 @@
+# auto_alert
+
+
+[`auto_alert`](https://github.com/brendantang/auto_alert) provides a simple DSL to declare conditions that should raise alerts on your ActiveRecord models.
+Alerts are saved in a database table with a [polymorphic association](https://guides.rubyonrails.org/association_basics.html#polymorphic-associations) to the model which triggered their creation.
+It's possible to define different conditions to raise, resolve, and re-raise an alert.
+
+
+
+## Quick example
+
+
+Imagine a to-do list application where tasks with a due date in the past should be flagged with an alert.
+With `auto_alert`, you can modify your Task model like so:
+
+
+```ruby
+class Task < ApplicationRecord
+  acts_as_alertable
+
+  raises_alert :past_due,
+               on: :past_due_date?,
+               message: "was due"
+               
+  private
+  def past_due_date?
+    due_date < Date.current and !done
+  end
+```
+
+
+Then you can call the `scan_for_alerts!` on any task and, if `past_due_date?` returns `true`, an alert record belonging to that task will be created.
+Instances of `Task` will also have a `past_due_alert` getter method to fetch their associated `past_due` alert, if any.
+
+
+
+## Installation
+
+
+### Install `auto_alert`
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'auto_alert'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+### Create `Alert` model
+
+`auto_alert` assumes there is an `Alert` model to store your alerts in the database.
+
+An appropriate model can be built using the Rails generator by running something like, `rails generate model Alert alertable:references resolved:boolean kind:string message:string`.
+Then edit the resulting migration so that it looks like [this example](test/dummy/db/migrate/20210613222049_create_alerts.rb).
+
+Make sure to edit the alert model file to register it with `auto_alert`:
+
+```ruby
+# app/models/alert.rb
+class Alert < ApplicationRecord
+  acts_as_alert # add this line
+end
+```
+
+(In the future I'd like to add an `install` rake task to automate this process.)
+
+`auto_alert` assumes the alert relation uses the table called `alerts`, but you can specify a different relation:
+
+```ruby
+# app/models/task.rb
+class Task < ApplicationRecord
+  acts_as_alertable # will default to using the Alert model
+end
+
+# app/models/task_list.rb
+class TaskList < ApplicationRecord
+  acts_as_alertable with_table: :special_alerts # will look for a SpecialAlert model
+end
+```
+
+
+
+## Usage
+
+
+Calling `acts_as_alertable` in your model definition:
+  - Allows you to use the `raises_alert` class method to declare the conditions that should raise or resolve an alert
+  - Registers that model instances have alerts
+    - Uses [polymorphic association](https://guides.rubyonrails.org/association_basics.html#polymorphic-associations), so you can use all the instance methods it provides
+    - Also creates convenience getters for each kind of alert that model can raise (i.e. `task.past_due_alert`)
+  - Provides the instance method `scan_for_alerts!`, which creates or updates alert records according to the declared `raises_alert` conditions.
+  
+  
+### Scanning for alerts
+
+`auto_alert` makes no assumptions about when you'd like to check if alerts should be raised or resolved.
+
+For simple use cases, it can make sense to call `scan_for_alerts!` on specific instances from your controller, or to hook into one of the ActiveRecord [callbacks](https://guides.rubyonrails.org/active_record_callbacks.html):
+```ruby
+class MyModel < ApplicationRecord
+  acts_as_alertable
+  # ...
+  after_save :scan_for_alerts!
+```
+
+For more complicated use cases, especially where alert conditions rely on factors external to the model instance itself, it can make sense to use a [job](https://guides.rubyonrails.org/active_job_basics.html) to asynchronously call `scan_for_alerts!` on big batches of records.
+
+
+### Alert records
+
+`auto_alert` assumes there is an ActiveRecord model for the table `alerts`, with at least:
+  - A polymorphic `alertable` reference (pointing to the record which triggered the alert)
+  - A boolean `resolved` attribute (indicating the alert is no longer relevant)
+  - A `kind` attribute (each alertable record has only one alert of each kind—`past_due` in the example above)
+    - Can be a text column or a Rails enumerable using a numeric column ([example](./test/dummy/app/models/special_alert.rb))
+  - A string `message` attribute describing the alert details
+  
+Instructions for creating such a model are in the Installation secion under [Create Alert model](#create-alert-model).
+
+
+### Declaring rules to raise and resolve alerts
+
+The `on` parameter to `raises_alert` can take a method name as [above](#quick-example), or a proc:
+
+```ruby
+raises_alert :past_due, 
+  on: ->(t) { t.due_date < Date.current and !t.done }
+```
+
+You can also pass a `resolve_on` parameter to specify the condition for marking the alert `resolved`. 
+A proc or method name is acceptable.
+
+```ruby
+class Order < ApplicationRecord
+  acts_as_alertable
+
+  raises_alert :week_old,
+    on: ->(order) { order.placed <= Date.current - 1.week },
+    resolve_on: :shipped 
+    # Now changing the order date won't resolve the alert, but marking it `shipped` will.
+```
+
+If no `resolve_on` parameter is passed, the inverse of the `on` condition is used.
+
+
+### Re-raising alerts
+
+By default, an alert which is `resolved` will not be re-raised, even if the `on` condition is met again.
+If you pass the `reraise` option `true`, the alert's `resolved` attribute will be updated to `false` every time the `on` condition is met.
+
+```ruby
+class Temperature < ApplicationRecord
+  acts_as_alertable
+  
+  raises_alert :too_cold,
+    on: ->(temp) { temp.farenheit < 32 },
+    reraise: true
+```
+
+You can also give a proc or method name to the `reraise` option to use a condition other than the initial `on` condition.
+    
+
+### Messages
+
+Alert messages can be built using a string, a proc, or a method name.
+When an alert is re-raised, its message will be built again.
+
+
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/lib/auto_alert.rb

@@ -0,0 +1,9 @@
+require "auto_alert/version"
+require "auto_alert/railtie"
+require "auto_alert/acts_as_alertable"
+require "auto_alert/acts_as_alert"
+require "auto_alert/checker"
+
+module AutoAlert
+  # Your code goes here...
+end

data/lib/auto_alert/acts_as_alert.rb

@@ -0,0 +1,27 @@
+module AutoAlert
+  module ActsAsAlert
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Class method to register a model as alertable
+      def acts_as_alert
+        belongs_to :alertable, polymorphic: true
+        validates :kind,
+          uniqueness: {
+            scope: :alertable,
+            message: ->(record, data) { "This #{record.alertable_type} already has a '#{data[:value]}' alert." },
+          }
+        include AutoAlert::ActsAsAlert::LocalInstanceMethods
+        extend AutoAlert::ActsAsAlert::SingletonMethods
+      end
+    end
+
+    module LocalInstanceMethods
+    end
+
+    module SingletonMethods
+    end
+  end
+end
+
+ActiveRecord::Base.send(:include, AutoAlert::ActsAsAlert)

data/lib/auto_alert/acts_as_alertable.rb

@@ -0,0 +1,50 @@
+module AutoAlert
+  module ActsAsAlertable
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Class method to register a model as alertable
+      def acts_as_alertable(with_table: :alerts)
+        cattr_accessor :alerts_table_name, default: with_table
+        alias_attribute :alerts, with_table unless with_table.to_sym == :alerts
+        cattr_accessor :alert_checkers, default: []
+        has_many with_table.to_sym, as: :alertable, dependent: :destroy
+        include AutoAlert::ActsAsAlertable::LocalInstanceMethods
+        extend AutoAlert::ActsAsAlertable::SingletonMethods
+      end
+    end
+
+    module LocalInstanceMethods
+      def unresolved_alerts
+        alerts.where(resolved: false)
+      end
+
+      def has_unresolved_alerts?
+        unresolved_alerts.size > 0
+      end
+
+      # Check if any alerts should be raised or resolveed
+      def scan_for_alerts!
+        self.class.alert_checkers.each do |checker|
+          checker.check(self)
+        end
+      end
+    end
+
+    module SingletonMethods
+      def raises_alert(kind, on:, resolve_on: nil, message: nil, reraise: false)
+        checker = AutoAlert::Checker.new(kind, on, resolve_on, reraise, message)
+        alert_checkers << checker
+        define_method "#{kind}_alert" do
+          alerts.find_by(kind: kind)
+        end
+      end
+
+      def alert_kinds
+        alert_checkers.map do |checker| checker.kind end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:include, AutoAlert::ActsAsAlertable)

data/lib/auto_alert/checker.rb

@@ -0,0 +1,75 @@
+module AutoAlert
+  class Checker
+    attr_reader :kind
+
+    def initialize(alert_kind, raise_condition, resolve_condition, reraise_condition = false, message_builder)
+      @kind = alert_kind
+      @raise_condition = normalize_check_condition raise_condition
+      @resolve_condition =
+        resolve_condition ?
+          normalize_check_condition(resolve_condition) :
+          ->(a) { not @raise_condition.call(a) }
+      @reraise_condition = if !reraise_condition # If nil or false
+          nil
+        elsif reraise_condition == true
+          @raise_condition
+        else
+          normalize_check_condition reraise_condition
+        end
+      @message_builder = message_builder
+    end
+
+    def check(alertable)
+      existing_alert = alertable.send("#{@kind}_alert")
+
+      case [existing_alert, @reraise_condition, existing_alert&.resolved]
+
+      # Check for alert for the first time
+      in nil, _, _
+        if @raise_condition.call(alertable)
+          alertable.alerts.create(kind: @kind, message: message(alertable), resolved: false)
+        end
+
+      # Check if alert should be resolveed
+      in alert, _, false
+        alert.update(resolved: true) if @resolve_condition.call(alertable)
+
+      # Resolved alert should not be re-raised
+      in alert, nil, true
+        return
+
+      # Check if resolved alert should be re-raised
+      in alert, reraise_condition, true
+        if reraise_condition.call(alertable)
+          alert.update(message: message(alertable), resolved: false)
+        end
+
+      else
+        return
+      end
+    end
+
+    def message(alertable)
+      case @message_builder
+      in Proc => p
+        p.call(alertable)
+      in Symbol => s if alertable.respond_to?(s, true)
+        alertable.send(@message_builder)
+      else
+        @message_builder
+      end
+    end
+
+    private
+
+    def normalize_check_condition(condition)
+      if condition.respond_to?(:call)
+        condition
+      else
+        lambda do |record|
+          record.send(condition)
+        end
+      end
+    end
+  end
+end

data/lib/auto_alert/railtie.rb

@@ -0,0 +1,4 @@
+module AutoAlert
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/auto_alert/version.rb

@@ -0,0 +1,3 @@
+module AutoAlert
+  VERSION = '0.1.0'
+end

data/lib/tasks/auto_alert_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :auto_alert do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: auto_alert
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brendan Tang
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-06-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.3.2
+description: A plugin for Rails which makes it easy to specify conditions to raise
+  or resolve alert records associated with your ActiveRecord models.
+email:
+- b@brendantang.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/auto_alert.rb
+- lib/auto_alert/acts_as_alert.rb
+- lib/auto_alert/acts_as_alertable.rb
+- lib/auto_alert/checker.rb
+- lib/auto_alert/railtie.rb
+- lib/auto_alert/version.rb
+- lib/tasks/auto_alert_tasks.rake
+homepage: https://github.com/brendantang/auto_alert
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/brendantang/auto_alert
+  source_code_uri: https://github.com/brendantang/auto_alert
+  changelog_uri: https://github.com/brendantang/auto_alert
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.16
+signing_key:
+specification_version: 4
+summary: Automatically raise and dismiss alerts on your ActiveRecord models.
+test_files: []