batch_processor 0.2.6 → 0.3.0

data/lib/batch_processor/batch/controller.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# The controller performs updates on and tracks details of a batch.
+# Batches have a status which is driven by the jobs it is processing. Callbacks are fired in response to status changes.
 module BatchProcessor
   module Batch
     module Controller

data/lib/batch_processor/batch/core.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# A batch has an ID, details, and is recoverable as an STI.
+# Batches accept a unique identifier and input representing the arguments and options which define it's collection.
 module BatchProcessor
   module Batch
     module Core

data/lib/batch_processor/batch/job.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# A batch job is what process each item in the collection.
+# Unless otherwise specified a `Batch` assumes its **Job** class shares a common name.
 module BatchProcessor
   module Batch
     module Job

data/lib/batch_processor/batch/job_controller.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# The job controller performs updates on and tracks details related to the jobs in a batch.
+# A BatchJob calls into the Batch to report on it's lifecycle from start to finish, including on success and failure.
 module BatchProcessor
   module Batch
     module JobController

data/lib/batch_processor/batch/predicates.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Predicates allow inspection of the status of a batch.
+# The **Status** of a batch is manifested by a collection of predicates which track certain lifecycle events.
 module BatchProcessor
   module Batch
     module Predicates
@@ -10,6 +10,8 @@ module BatchProcessor
         date_predicate :started, :enqueued, :aborted, :cleared, :finished
 
         job_count_predicate :enqueued, :pending, :running, :failed, :canceled, :unfinished, :finished
+
+        delegate :valid?, to: :collection, prefix: true
       end
 
       def processing?

data/lib/batch_processor/batch/processor.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-# When processed, the batch performs a job for each item in its collection.
+# Unless otherwise specified a `Batch` uses the **default** `Parallel` Processor.
 module BatchProcessor
   module Batch
     module Processor
       extend ActiveSupport::Concern
 
-      # This is left mutable for extension and customization
+      # The default processors can be redefined and new custom ones can be added as well.
       # rubocop:disable Style/MutableConstant
       PROCESSOR_CLASS_BY_STRATEGY = {
         default: BatchProcessor::Processors::Parallel,
@@ -31,6 +31,10 @@ module BatchProcessor
           new(*arguments).process
         end
 
+        def process!(*arguments)
+          new(*arguments).process!
+        end
+
         def processor_class
           return @processor_class if defined?(@processor_class)
 
@@ -45,13 +49,22 @@ module BatchProcessor
 
         private
 
+        # Certain processors have configurable options; this configuration is specified in the Batch's definition.
         def processor_option(option, value = nil)
           _processor_options[option.to_sym] = value
         end
       end
 
-      def process
+      def process!
         processor_class.execute(batch: self, **_processor_options)
+        self
+      end
+
+      def process
+        process!
+      rescue StandardError => exception
+        error :process_error, exception: exception
+        self
       end
     end
   end

data/lib/batch_processor/batch_base.rb

@@ -7,6 +7,7 @@ require_relative "batch/predicates"
 require_relative "batch/controller"
 require_relative "batch/job_controller"
 
+# A **Batch** defines, controls, and monitors the processing of a collection of items with an `ActiveJob`.
 module BatchProcessor
   class BatchBase < Spicerack::InputObject
     class BatchCollection < BatchProcessor::Collection; end

data/lib/batch_processor/batch_details.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# The details of a batch represent the state of the work to process.
+# The **Details** of a batch are the times of critical lifecycle events and the summary counts of processed jobs.
 module BatchProcessor
   class BatchDetails < Spicerack::RedisModel
     attr_reader :batch_id

data/lib/batch_processor/batch_job.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
-# A batch can only be processed by a batchable job.
+# Only a **BatchJob** can be used to perform work, but it can be run outside of a batch as well.
+# Therefore, the recommendation is to make `ApplicationJob` inherit from `BatchJob`.
 module BatchProcessor
+  # BatchProcessor depends on ActiveJob for handling the processing of individual items in a collection.
   class BatchJob < ActiveJob::Base
     attr_accessor :batch_id, :tracked_batch_running, :tracked_batch_failure
 

data/lib/batch_processor/collection.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# A `Collection` takes input to validate and build a (possibly ordered) list of items to process with the Batch's job.
 module BatchProcessor
   class Collection < Spicerack::InputModel
     def items

data/lib/batch_processor/processor/execute.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# When executed, the processor performs a job for each item in the batch collection.
+# When `.process` is called on a Batch, `.execute` is called on the `Processor` specified in the Batch's definition.
 module BatchProcessor
   module Processor
     module Execute

data/lib/batch_processor/processor/process.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Processing a batch performs a job for each item in the batch collection.
+# Processing a Batch performs a job for each item in its collection if **and only if** it has a valid collection.
 module BatchProcessor
   module Processor
     module Process

data/lib/batch_processor/processor_base.rb

@@ -3,6 +3,7 @@
 require_relative "processor/process"
 require_relative "processor/execute"
 
+# A **Processor** is a service object which determines how to perform a Batch's jobs to properly process its collection.
 module BatchProcessor
   class ProcessorBase < Spicerack::InputObject
     argument :batch, allow_nil: false

data/lib/batch_processor/processors/parallel.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# The Parallel Processor enqueues jobs to be performed later.
 module BatchProcessor
   module Processors
     class Parallel < BatchProcessor::ProcessorBase

data/lib/batch_processor/processors/sequential.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# The Sequential Processor uses `.perform_now` to procedurally process each job within the current thread.
 module BatchProcessor
   module Processors
     class Sequential < BatchProcessor::ProcessorBase

data/lib/batch_processor/rspec/custom_matchers/set_processor_option.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RSpec matcher that tests usages of batches which do not specify a processor
+# RSpec matcher that tests usages of batches specifying processor options.
 #
 #     class ExampleBatch < ApplicationBatch
 #       processor_option :sorted, true

data/lib/batch_processor/rspec/custom_matchers/use_default_job_class.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RSpec matcher to DRY out the similarities between the other batch processor matchers.
+# RSpec matcher that tests usages of batches which do not explicitly specify a job.
 #
 #     class ExampleBatch < ApplicationBatch
 #     end

data/lib/batch_processor/rspec/custom_matchers/use_default_processor.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RSpec matcher that tests usages of batches which do not specify a processor
+# RSpec matcher that tests usages of batches which do not explicitly specify a processor.
 #
 #     class ExampleBatch < ApplicationBatch
 #     end

data/lib/batch_processor/rspec/custom_matchers/use_job_class.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RSpec matcher to DRY out the similarities between the other batch processor matchers.
+# RSpec matcher that tests usages of batches which explicitly specify a job.
 #
 #     class ExampleBatch < ApplicationBatch
 #       def self.job_class

data/lib/batch_processor/rspec/custom_matchers/use_parallel_processor.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RSpec matcher that tests usages of `.with_parallel_processor`
+# RSpec matcher that tests usages of `.with_parallel_processor`.
 #
 #     class ExampleBatch < ApplicationBatch
 #       with_parallel_processor

data/lib/batch_processor/rspec/custom_matchers/use_sequential_processor.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# RSpec matcher that tests usages of `.with_parallel_processor`
+# RSpec matcher that tests usages of `.with_sequential_processor`.
 #
 #     class ExampleBatch < ApplicationBatch
 #       with_sequential_processor

data/lib/batch_processor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BatchProcessor
-  VERSION = "0.2.6"
+  VERSION = "0.3.0"
 end

data/lib/generators/batch_processor/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Stub a Batch with test.
+
+Example:
+    `rails generate batch_processor foo`
+
+    Generates:
+      Batch: app/batches/foo_batch.rb
+       Test: spec/batches/foo_batch_spec.rb

data/lib/generators/batch_processor/application_batch/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Create the ApplicationBatch and test.
+
+Example:
+    `rails generate batch_processor:application_batch`
+
+    Generates:
+       Flow: app/batches/application_batch.rb
+       Test: spec/batches/application_batch_spec.rb

data/lib/generators/batch_processor/application_batch/application_batch_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BatchProcessor
+  module Generators
+    class ApplicationBatchGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      hook_for :test_framework
+
+      def create_application_batch
+        template "application_batch.rb", File.join("app/batches/application_batch.rb")
+      end
+    end
+  end
+end

data/lib/generators/batch_processor/application_batch/templates/application_batch.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+class ApplicationBatch < BatchProcessor::BatchBase; end

data/lib/generators/batch_processor/application_job/application_job_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BatchProcessor
+  module Generators
+    class ApplicationJobGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      hook_for :test_framework
+
+      def create_application_job
+        template "application_job.rb", File.join("app/jobs/application_job.rb")
+      end
+    end
+  end
+end

data/lib/generators/batch_processor/application_job/templates/application_job.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationJob < BatchProcessor::BatchJob
+end

data/lib/generators/batch_processor/batch_processor_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BatchProcessor
+  module Generators
+    class BatchProcessorGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      hook_for :test_framework
+
+      def create_application_flow
+        template "batch.rb.erb", File.join("app/batches/", class_path, "#{file_name}_batch.rb")
+      end
+    end
+  end
+end

data/lib/generators/batch_processor/install/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Creates ApplicationBatch with tests.
+
+Example:
+    `rails generate batch_processor:install`
+
+    Generates:
+      Batch: app/batches/application_batch.rb
+       Test: spec/batches/application_batch_spec.rb

data/lib/generators/batch_processor/install/install_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module BatchProcessor
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      def run_other_generators
+        generate "batch_processor:application_batch"
+        generate "batch_processor:application_job"
+      end
+    end
+  end
+end

data/lib/generators/batch_processor/templates/batch.rb.erb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Batch < ApplicationBatch
+  # with_parallel_processor
+  # with_sequential_processor
+  # processor_option :continue_after_exception, true
+  # processor_option :sorted, true
+
+  # process_with_job OtherJob
+
+  # allow_empty
+
+  class Collection < BatchCollection
+    # argument :arg, allow_nil: false
+    # option :opt, default: 3
+
+    def items
+      # TODO
+    end
+  end
+end

data/lib/generators/rspec/application_batch/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Create ApplicationBatch test.
+
+Example:
+    `rails generate rspec:application_batch`
+
+    Generates:
+      Test: spec/batches/application_batch_spec.rb
+

data/lib/generators/rspec/application_batch/application_batch_generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Generators
+    class ApplicationBatchGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_spec_file
+        template "application_batch_spec.rb", File.join("spec/batches/application_batch_spec.rb")
+      end
+    end
+  end
+end
+

data/lib/generators/rspec/application_batch/templates/application_batch_spec.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe ApplicationBatch, type: :batch do
+  it { is_expected.to inherit_from BatchProcessor::BatchBase }
+end
+

data/lib/generators/rspec/application_job/USAGE

@@ -0,0 +1,9 @@
+Description:
+    Create ApplicationJob test.
+
+Example:
+    `rails generate rspec:application_job`
+
+    Generates:
+      Test: spec/jobs/application_job_spec.rb
+

data/lib/generators/rspec/application_job/application_job_generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Rspec
+  module Generators
+    class ApplicationJobGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_spec_file
+        template "application_job_spec.rb", File.join("spec/jobs/application_job_spec.rb")
+      end
+    end
+  end
+end
+