active_job_tracker 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3102a3e7bcb824b3db71003baa5f401f0598178c503b1f5b4b49f7c3e580d835
-  data.tar.gz: e043943a466eb2d514a906acd8ae2b72c9fe0a294f0b080f0ddceb6e561affef
+  metadata.gz: 2b8342cf50be46737b9d191b7d631008c6cecad77fc81d1e0fcfca23c4ff6007
+  data.tar.gz: 02a1d61e46c41f6241b8be9d25ba311c42f882b1db71e94afc7d19062bbe3e31
 SHA512:
-  metadata.gz: f030c69148089178e8d0dd8693835af4407bb9d62ea789f08b3875fff399d282603eae68411e1eb10acff0f0d707c0e6470f53114df0534f369816c49ca3d460
-  data.tar.gz: 0146a953fee7b01f7e203eff001e974799f8e8ba364dcc79fa54a5a6b81eb6d13670354bd1fbb1dc59cf95b62d8b7b9c4b1bdb3f35103ba29be6414eae3cb7dc
+  metadata.gz: 1b46f5815fd0809154e222e50e388f6aa49bde11cb904d12bb8ff12fe9ecf1ccf2f41b0e250620b09accf18f0755e3e275b997380ee9284d9b1e290f6b2ead6b
+  data.tar.gz: f60e1e47250e60af0693f3a9f81cfcc8777289b2640e1a0b8f96b2b29bd3d61f9e42624148169fc2ba3b32ef186ee2e9c3c75f43784368020c36444b35d1f0e9

data/README.md

@@ -1,8 +1,12 @@
+❤️ I'm looking for a full-time position. Please consider hiring me.
+
 # ActiveJobTracker
 
 ActiveJobTracker provides persisted, real-time tracking and monitoring of ActiveJob jobs in Ruby on Rails applications. It allows you to track job status, progress, and errors with a simple API and real-time UI updates via ActionCable.
 
-<img width="796" alt="Screenshot 2025-03-04 at 1 09 38 PM" src="https://github.com/user-attachments/assets/d34e6fb8-bb3c-4d71-a737-2f7597a23c43" />
+<div align="center">
+<img width="500" alt="Screenshot 2025-03-04 at 1 09 38 PM" src="https://github.com/user-attachments/assets/d34e6fb8-bb3c-4d71-a737-2f7597a23c43" />
+</div>
 
 ## Features
 
@@ -10,7 +14,7 @@ ActiveJobTracker provides persisted, real-time tracking and monitoring of Active
 - Monitor job progress with percentage completion
 - Real-time UI updates via ActionCable
 - Error tracking and reporting
-- Efficient progress caching to minimize database updates
+- Efficient progress write-behind caching to minimize database updates
 - Configurable options
 
 ## Installation
@@ -59,6 +63,9 @@ ActiveJobTracker.configure do |config|
   # When true, job updates are automatically broadcast via ActionCable
   config.auto_broadcast = true
 
+  # Whether to raise an error when progress increments the current value beyond the target value (default: false)
+  config.raise_error_when_target_exceeded = false
+
   # Default partial path for rendering job trackers
   # (default: 'active_job_tracker/active_job_tracker')
   config.default_partial = 'active_job_tracker/active_job_tracker'
@@ -66,6 +73,10 @@ ActiveJobTracker.configure do |config|
   # Whether to include the style in the job tracker (default: true)
   # When true, the gem's CSS styles are automatically included
   config.include_style = true
+
+  # Custom Turbo Stream channel name (default: 'active_job_tracker')
+  # Use this to customize the ActionCable channel name for real-time updates
+  config.turbo_stream_channel = 'Turbo::StreamsChannel'
 end
 ```
 
@@ -80,9 +91,9 @@ class CsvUpload < ApplicationRecord
   # Sets up polymorphic association to tie this record to the ActiveJobTracker
   has_one :job, as: :active_job_trackable, class_name: 'ActiveJobTrackerRecord'
 
-  after_create :create_jobs
+  after_create :process_import
 
-  def create_jobs
+  def process_import
     # The tracked record must be passed into the job as the first argument
     ProcessImportJob.perform_later(self)
   end
@@ -122,13 +133,27 @@ class ProcessImportJob < ApplicationJob
     records.each do |record|
       # Process item
 
-      # Update progress (increments by 1)
+      # Update progress (increments by 1 by default)
       active_job_tracker_progress
     end
   end
 end
 ```
 
+Optionally, you can use a custom value to increment your progress by:
+
+```ruby
+def perform
+  # Default target is 100
+
+  10.times do
+    # Process item
+
+    active_job_tracker_progress(increment_by: 10)
+  end
+end
+```
+
 For more efficient progress tracking with many updates, use threadsafe progress caching:
 
 ```ruby
@@ -167,6 +192,7 @@ This will render a default tracker UI with progress bar, status badge, and job i
 #### Custom Rendering
 
 You can customize the tracker UI by creating your own partials and using the ActiveJobTrackerRecord model attributes:
+
 - Make sure to set the `config.default_partial` to the new partial path
 - Each job block needs to be wrapped with `id="active_job_tracker_<%= tracker.id %>"` for turbo to update your frontend
 
@@ -260,7 +286,7 @@ end
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rails test` to run the tests.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/app/models/active_job_tracker_record.rb

@@ -43,14 +43,15 @@ class ActiveJobTrackerRecord < ApplicationRecord
     [ current.to_f / target.to_f, 1.0 ].min
   end
 
-  def progress(use_cache = true)
+  def progress(use_cache: true, increment_by: 1)
     if use_cache
       key = progress_cache_key
       should_flush = false
 
       @@mutex.synchronize do
         current_value = Rails.cache.fetch(key, expires_in: 1.week) { 0 }.to_i
-        new_value = current_value + 1
+        new_value = incremented_value(current_value: current_value, increment_by: increment_by)
+
         Rails.cache.write(key, new_value, expires_in: 1.week)
 
         should_flush = new_value >= self.cache_threshold
@@ -60,7 +61,7 @@ class ActiveJobTrackerRecord < ApplicationRecord
       flush_progress_cache if should_flush
     else
       with_lock do
-        self.current += 1
+        self.current = incremented_value(current_value: current, increment_by: increment_by)
         save!
       end
     end
@@ -86,8 +87,24 @@ class ActiveJobTrackerRecord < ApplicationRecord
 
   private
 
+  def incremented_value(current_value:, increment_by:)
+    new_value = current_value + increment_by
+
+    if new_value > target
+      if ActiveJobTracker.configuration.raise_error_when_target_exceeded
+        raise ActiveJobTracker::Error::TargetExceeded.new(
+          "The current value of #{new_value} exceeds the target value of #{target}"
+        )
+      end
+
+      target
+    else
+      new_value
+    end
+  end
+
   def broadcast_changes
-    broadcast_replace_to(
+    ActiveJobTracker.configuration.turbo_stream_channel.constantize.broadcast_replace_to(
      "active_job_trackers",
      target: "active_job_tracker_#{self.id}",
      partial: ActiveJobTracker.configuration.default_partial,

data/app/views/active_job_tracker/_active_job_tracker_wrapper.html.erb

@@ -6,7 +6,7 @@
   html_options ||= {}
   css_class = html_options[:class] || "active_job_tracker-container"
 %>
-<%= turbo_stream_from "active_job_trackers" %>
+<%= turbo_stream_from "active_job_trackers", channel: ActiveJobTracker.configuration.turbo_stream_channel %>
 <div class="<%= css_class %>" data-controller="active_job_tracker-container">
   <%= content %>
 </div>

data/app/views/active_job_tracker/_radial_progress.html.erb

@@ -0,0 +1,41 @@
+<%
+  percentage = active_job_tracker_record.progress_percentage
+  status = active_job_tracker_record.status
+  
+  # Calculate the stroke-dasharray and stroke-dashoffset for the circle
+  circumference = 2 * Math::PI * 45 # 45 is the radius of the circle
+  stroke_dashoffset = circumference * (1 - percentage / 100.0)
+%>
+
+<div class="active_job_tracker-radial-progress">
+  <svg width="100" height="100" viewBox="0 0 100 100">
+    <circle 
+      class="active_job_tracker-radial-progress-bg" 
+      cx="50" 
+      cy="50" 
+      r="45" 
+      fill="none" 
+      stroke-width="8"
+    />
+    <circle 
+      class="active_job_tracker-radial-progress-fill active_job_tracker-radial-progress-<%= status %>" 
+      cx="50" 
+      cy="50" 
+      r="45" 
+      fill="none" 
+      stroke-width="8"
+      stroke-dasharray="<%= circumference %>"
+      stroke-dashoffset="<%= stroke_dashoffset %>"
+      transform="rotate(-90 50 50)"
+    />
+    <text 
+      class="active_job_tracker-radial-progress-text" 
+      x="50" 
+      y="50" 
+      text-anchor="middle" 
+      dominant-baseline="middle"
+    >
+      <%= percentage %>%
+    </text>
+  </svg>
+</div> 

data/lib/active_job_tracker/configuration.rb

@@ -19,17 +19,27 @@ module ActiveJobTracker
     # @return [String]
     attr_accessor :default_partial
 
+    # Whether to raise an error when progress increments the current value beyond the target value
+    # @return [Boolean]
+    attr_accessor :raise_error_when_target_exceeded
+
     # Whether to include the style in the job tracker
     # @return [Boolean]
     attr_accessor :include_style
 
+    # The turbo stream channel to use for broadcasting job tracker updates
+    # @return [String]
+    attr_accessor :turbo_stream_channel
+
     # Initialize with default values
     def initialize
       @default_target = 100
       @cache_threshold = 10
       @auto_broadcast = true
+      @raise_error_when_target_exceeded = false
       @default_partial = "active_job_tracker/active_job_tracker"
       @include_style = true
+      @turbo_stream_channel = "Turbo::StreamsChannel"
     end
   end
 end

data/lib/active_job_tracker/version.rb

@@ -1,3 +1,3 @@
 module ActiveJobTracker
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/active_job_tracker.rb

@@ -6,6 +6,7 @@ module ActiveJobTracker
   extend ActiveSupport::Concern
 
   class Error < StandardError
+    class TargetExceeded < Error; end
   end
 
   def self.configuration
@@ -35,8 +36,8 @@ module ActiveJobTracker
     active_job_tracker.update(target: target)
   end
 
-  def active_job_tracker_progress(cache: false)
-    active_job_tracker.progress(cache)
+  def active_job_tracker_progress(cache: false, increment_by: 1)
+    active_job_tracker.progress(use_cache: cache, increment_by: increment_by)
   end
 
   def active_job_tracker

data/lib/generators/active_job_tracker/templates/config/initializers/active_job_tracker.rb

@@ -15,6 +15,9 @@ ActiveJobTracker.configure do |config|
   # When true, job updates are automatically broadcast via ActionCable
   config.auto_broadcast = true
 
+  # Whether to raise an error when progress increments the current value beyond the target value
+  config.raise_error_when_target_exceeded = false
+
   # Default partial path for rendering job trackers
   # (default: 'active_job_tracker/shared/active_job_tracker')
   config.default_partial = "active_job_tracker/active_job_tracker"
@@ -22,4 +25,8 @@ ActiveJobTracker.configure do |config|
   # Whether to include the style in the job tracker (default: true)
   # When true, the gem's CSS styles are automatically included
   config.include_style = true
+
+  # The turbo stream channel to use for broadcasting job tracker updates
+  # (default: 'Turbo::StreamsChannel')
+  config.turbo_stream_channel = "Turbo::StreamsChannel"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: active_job_tracker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Seena Sabti
 bindir: bin
 cert_chain: []
-date: 2025-03-06 00:00:00.000000000 Z
+date: 2025-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.0.1
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.11
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
@@ -120,6 +134,7 @@ files:
 - app/models/active_job_tracker_record.rb
 - app/views/active_job_tracker/_active_job_tracker.html.erb
 - app/views/active_job_tracker/_active_job_tracker_wrapper.html.erb
+- app/views/active_job_tracker/_radial_progress.html.erb
 - lib/active_job_tracker.rb
 - lib/active_job_tracker/configuration.rb
 - lib/active_job_tracker/engine.rb