procrastinator 1.0.0.pre.rc3 → 1.0.0

data/lib/procrastinator/task_store/simple_comma_store.rb

@@ -4,25 +4,33 @@ require 'csv'
 require 'pathname'
 
 module Procrastinator
+   # Task storage strategies.
+   #
+   # All task stores must implement the API #read, #create, #update, #delete.
    module TaskStore
       # Simple Task I/O adapter that writes task information (ie. TaskMetaData attributes) to a CSV file.
       #
-      # SimpleCommaStore is not designed for efficiency or large loads (10,000+ tasks).
-      #
-      # For critical production environments, it is strongly recommended to use a more robust storage mechanism like a
-      # proper database.
+      # SimpleCommaStore is not designed for efficiency or large loads (10,000+ tasks). For critical production
+      # environments, it is strongly recommended to use a more robust storage mechanism like a proper database.
       #
       # @author Robin Miller
       class SimpleCommaStore
-         # ordered
+         # Ordered list of CSV column headers
          HEADERS = [:id, :queue, :run_at, :initial_run_at, :expire_at,
                     :attempts, :last_fail_at, :last_error, :data].freeze
 
-         EXT          = 'csv'
-         DEFAULT_FILE = Pathname.new("procrastinator-tasks.#{ EXT }").freeze
-
+         # Columns that store time information
          TIME_FIELDS = [:run_at, :initial_run_at, :expire_at, :last_fail_at].freeze
 
+         # CSV file extension
+         EXT = 'csv'
+
+         # Default filename
+         DEFAULT_FILE = Pathname.new("procrastinator-tasks.#{ EXT }").freeze
+
+         # CSV Converter lambda
+         #
+         # @see CSV
          READ_CONVERTER = proc do |value, field_info|
             if field_info.header == :data
                value
@@ -53,6 +61,10 @@ module Procrastinator
             freeze
          end
 
+         # Parses the CSV file for data matching the given filter, or all if no filter provided.
+         #
+         # @param filter [Hash] Specified attributes to match.
+         # @return [Array<Hash>]
          def read(filter = {})
             CSVFileTransaction.new(@path).read do |existing_data|
                existing_data.select do |row|
@@ -69,7 +81,7 @@ module Procrastinator
          # @param run_at [Time, nil] time to run the task at
          # @param initial_run_at [Time, nil] first time to run the task at. Defaults to run_at.
          # @param expire_at [Time, nil] time to expire the task
-         def create(queue:, run_at:, expire_at:, data: '', initial_run_at: nil)
+         def create(queue:, run_at:, expire_at: nil, data: '', initial_run_at: nil)
             CSVFileTransaction.new(@path).write do |tasks|
                max_id = tasks.collect { |task| task[:id] }.max || 0
 
@@ -87,6 +99,10 @@ module Procrastinator
             end
          end
 
+         # Updates an existing task in the CSV file.
+         #
+         # @param id [Integer] task ID number
+         # @param data [Hash] new data to save
          def update(id, data)
             CSVFileTransaction.new(@path).write do |tasks|
                task_data = tasks.find do |task|
@@ -99,12 +115,19 @@ module Procrastinator
             end
          end
 
+         # Removes an existing task from the CSV file.
+         #
+         # @param id [Integer] task ID number
          def delete(id)
             CSVFileTransaction.new(@path).write do |existing_data|
                generate(existing_data.reject { |task| task[:id] == id })
             end
          end
 
+         # Generates a CSV string from the given data.
+         #
+         # @param data [Array] list of data to convert into CSV
+         # @return [String] Generated CSV string
          def generate(data)
             lines = data.collect do |d|
                TIME_FIELDS.each do |field|
@@ -120,6 +143,7 @@ module Procrastinator
 
          # Adds CSV parsing to the file reading
          class CSVFileTransaction < FileTransaction
+            # (see FileTransaction#transact)
             def transact(writable: nil)
                super(writable: writable) do |file_str|
                   yield(parse(file_str))

data/lib/procrastinator/test/mocks.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module Procrastinator
+   # Reusable Test classes for mocking out object queues.
+   #
+   #    require 'procrastinator/test/mocks'
+   #
+   #    Procrastinator.setup do |config|
+   #       config.define_queue :test_queue, Procrastinator::Test::Mock
+   #    end
    module Test
       # Testing mock Task class
       #
@@ -16,10 +23,12 @@ module Procrastinator
       class MockTask
          attr_accessor :container, :logger, :scheduler
 
+         # Records that the mock task was run.
          def run
             @run = true
          end
 
+         # @return [Boolean] Whether the task was run
          def run?
             @run
          end

data/lib/procrastinator/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Procrastinator
-   VERSION = '1.0.0-rc3'
+   # Version number of this release
+   VERSION = '1.0.0'
 end

data/procrastinator.gemspec

@@ -33,4 +33,5 @@ Gem::Specification.new do |spec|
    spec.add_development_dependency 'rubocop-performance', '~> 1.10'
    spec.add_development_dependency 'simplecov', '~> 0.18.0'
    spec.add_development_dependency 'timecop', '~> 0.9'
+   spec.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: procrastinator
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc3
+  version: 1.0.0
 platform: ruby
 authors:
 - Robin Miller
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-09-17 00:00:00.000000000 Z
+date: 2022-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: A flexible pure Ruby job queue. Tasks are reschedulable after failures.
 email:
 - robin@tenjin.ca
@@ -149,6 +163,7 @@ files:
 - lib/procrastinator/queue_worker.rb
 - lib/procrastinator/rake/daemon_tasks.rb
 - lib/procrastinator/rake/tasks.rb
+- lib/procrastinator/rspec/matchers.rb
 - lib/procrastinator/scheduler.rb
 - lib/procrastinator/task.rb
 - lib/procrastinator/task_meta_data.rb
@@ -173,9 +188,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.2
 signing_key: