Keyword arguments before:, after:

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [0.4.0] - 2023-12-22
+
+- Added support for named months and wdays
+- Keyword arguments: before:, after:
+
 ## [0.3.0] - 2023-12-22
 
 - Added support for DOWs

README.md

@@ -22,8 +22,9 @@ Now, you can use one of three methods `#in`, `#next`, `#last` to determine cron
 ### Using `#in`
 
 Calculates cron job occurrences within a given time period.\
-@param period [Range] The time period for which to calculate cron job occurrences.\
-@return [Array<Time>] An array of Time instances representing each occurrence.
+**Parameters:**
+- `period` - a Range object defining the start and end times for the calculation.\
+
 
 ```ruby
     period = Time.new(2024, 1, 1, 0, 0)..Time.new(2024, 1, 4, 0, 0)
@@ -35,10 +36,10 @@ Calculates cron job occurrences within a given time period.\
 ### Using `#next`
 
 Calculates the next 'n' occurrences of the cron job from a given start time.\
-@param count [Integer] The number of occurrences to calculate. Defaults to `1`.\
-@param period_start [Time] The start time from which to calculate occurrences. Defaults to `Time.now`.\
-@param max_years [Integer] The maximum number of years to consider for the period. Defaults to `5`.\
-@return [Array<Time>] An array of the next 'n' occurrences.
+**Parameters:**
+- `count` - (optional, Integer) The number of occurrences to calculate. Defaults to 1.
+- `after:` - (optional, Time, keyword argument) The start time from which to calculate occurrences. If not provided, defaults to the current time (Time.now).
+- `max_years` - (optional, Integer, keyword argument) The maximum number of years to search for future occurrences. Defaults to 5.
 
 ```ruby
     cron_calc.next
@@ -47,23 +48,23 @@ Calculates the next 'n' occurrences of the cron job from a given start time.\
     cron_calc.next(3)
     # => [2023-12-20 05:05:00 +0100, 2023-12-21 05:05:00 +0100, 2023-12-22 05:05:00 +0100]
 
-    cron_calc.next(2, Time.new(2024, 1, 1, 0, 0))
+    cron_calc.next(2, after: Time.new(2024, 1, 1, 0, 0))
     # => [2024-01-01 05:05:00 +0100, 2024-01-02 05:05:00 +0100]
 ```
 
 ### Using `#last`
 
 Calculates the last 'n' occurrences of the cron job until a given end time.\
-@param count [Integer] The number of past occurrences to calculate.\
-@param period_end [Time] The end time until which to calculate occurrences.\
-@param max_years [Integer] The maximum number of years to consider for the period.\
-@return [Array<Time>] An array of the last 'n' occurrences.
+**Parameters:**
+- `count` - (optional, Integer) The number of occurrences to calculate. Defaults to 1.
+- `before:` - (optional, Time, keyword argument) The end time from which to calculate past occurrences. If not provided, defaults to the current time (Time.now).
+- `max_years` - (optional, Integer, keyword argument) The maximum number of years to search backward for past occurrences. Defaults to 5.
 
 ```ruby
     cron_calc.last
     # => [2023-12-19 05:05:00 +0100]
 
-    cron_calc.last(4, Time.new(2024, 1, 1, 0, 0))
+    cron_calc.last(4, before: Time.new(2024, 1, 1, 0, 0))
     # => [2023-12-31 05:05:00 +0100, 2023-12-30 05:05:00 +0100, 2023-12-29 05:05:00 +0100, 2023-12-28 05:05:00 +0100]
 ```
 

lib/cron_calc.rb

@@ -54,24 +54,24 @@ def in(period)
 
     # Calculates the next 'n' occurrences of the cron job from a given start time.
     # @param count [Integer] The number of occurrences to calculate.
-    # @param period_start [Time] The start time from which to calculate occurrences.
+    # @param after [Time] The start time from which to calculate occurrences.
     # @param max_years [Integer] The maximum number of years to consider for the period.
     # @return [Array<Time>] An array of the next 'n' occurrences.
-    def next(count = 1, period_start = Time.now, max_years = 5)
+    def next(count = 1, after: Time.now, max_years: 5)
       occurrences(
-        period_start..(period_start + (60 * 60 * 24 * 365 * max_years)),
+        after..(after + (60 * 60 * 24 * 365 * max_years)),
         count
       )
     end
 
     # Calculates the last 'n' occurrences of the cron job until a given end time.
     # @param count [Integer] The number of past occurrences to calculate.
-    # @param period_end [Time] The end time until which to calculate occurrences.
+    # @param before [Time] The end time until which to calculate occurrences.
     # @param max_years [Integer] The maximum number of years to consider for the period.
     # @return [Array<Time>] An array of the last 'n' occurrences.
-    def last(count = 1, period_end = Time.now, max_years = 5)
+    def last(count = 1, before: Time.now, max_years: 5)
       occurrences(
-        (period_end - (60 * 60 * 24 * 365 * max_years))..period_end,
+        (before - (60 * 60 * 24 * 365 * max_years))..before,
         count,
         reverse: true
       )

lib/cron_calc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CronCalc
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

spec/cron_calc_spec.rb

@@ -173,9 +173,9 @@
   end
 
   describe '#next' do
-    let(:subject) { described_class.new(cron_string).next(n, period_start) }
+    let(:subject) { described_class.new(cron_string).next(n, after:) }
     let(:n) { 3 }
-    let(:period_start) { Time.new(2024, 1, 1, 0, 0) }
+    let(:after) { Time.new(2024, 1, 1, 0, 0) }
 
     context 'when "," is used' do
       let(:cron_string) { '30 22,23 * * *' }
@@ -188,12 +188,23 @@
                               ])
       end
     end
+
+    context 'when count parameter is missing' do
+      let(:subject) { described_class.new(cron_string).next(after:) }
+      let(:cron_string) { '30 22,23 * * *' }
+
+      it do
+        expect(subject).to eq([
+                                Time.new(2024, 1, 1, 22, 30)
+                              ])
+      end
+    end
   end
 
   describe '#last' do
-    let(:subject) { described_class.new(cron_string).last(n, period_end) }
+    let(:subject) { described_class.new(cron_string).last(n, before:) }
     let(:n) { 3 }
-    let(:period_end) { Time.new(2024, 1, 1, 0, 0) }
+    let(:before) { Time.new(2024, 1, 1, 0, 0) }
 
     context 'when "," is used' do
       let(:cron_string) { '30 22,23 * * *' }
@@ -206,5 +217,16 @@
                               ])
       end
     end
+
+    context 'when count parameter is missing' do
+      let(:subject) { described_class.new(cron_string).last(before:) }
+      let(:cron_string) { '30 22,23 * * *' }
+
+      it do
+        expect(subject).to eq([
+                                Time.new(2023, 12, 31, 23, 30)
+                              ])
+      end
+    end
   end
 end