philiprehberger-cron_parser 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eeb369c781ff5bf8c316b443bf97ee4786ed74e11842f7f5de81a9071418bdb2
-  data.tar.gz: ee7c9d64bae3aee0f9a7b617197e32c6af9816d09ad372c80031d748082f9ab2
+  metadata.gz: 3be8924f48f35f97ea4d356f5368d7907cf23bda63af8af43c4b3776f1a47a69
+  data.tar.gz: 0d0284d3e84fe3b93db4911a30149333bf0faaba73f2857ec28ae95f83455509
 SHA512:
-  metadata.gz: c95125f661ce1799d954dc8766c494b784db4fcc7ccd1ad37ca638b4cd3a6a807560fa9640868d2a9eb91e89e8323604868a3f27fecf797324571f7d6d341b48
-  data.tar.gz: c1464aa92d9df184418b6e211864f2ea30c7444822c955c5772482e2c7e24d10c5dc395de909c4baf7e17436cee4aba87c20a7ff72fd3241ab3c5049a3781ba2
+  metadata.gz: 4cf277261fcf00a553dc1defe27a24b74ace4d34f7760e5033d5b52dbbb2fa87bacb0a36b32e8847bd3af4e2d93381caf3fa17b8f5e6fa0953fc32a3105f2b01
+  data.tar.gz: 6e5f421543e3a2871f1b8e068f12dab5ebec5586ff18ee297dcbca94261cca57e931c72e00af468a783170462edd333939b1e1370d715a5770b32fb3f457f4fc

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-30
+
+### Added
+- `Expression#count_in(from:, to:)` returns the number of times the expression matches within an inclusive time window — useful for capacity planning and alert tuning
+
+## [0.3.0] - 2026-04-09
+
+### Added
+- Named cron aliases (`@hourly`, `@daily`, `@midnight`, `@weekly`, `@monthly`, `@yearly`, `@annually`) with case-insensitive matching
+- `valid?` and `validate` now accept alias expressions
+
 ## [0.2.0] - 2026-04-03
 
 ### Added

data/README.md

@@ -49,6 +49,15 @@ cron.matches?(Time.new(2026, 3, 22, 9, 0, 0))  # => true
 cron.matches?(Time.new(2026, 3, 22, 10, 0, 0)) # => false
 ```
 
+### Counting Occurrences in a Window
+
+```ruby
+cron = Philiprehberger::CronParser.new('*/15 * * * *')
+from = Time.new(2026, 4, 30, 9, 0, 0)
+to   = Time.new(2026, 4, 30, 10, 0, 0)
+cron.count_in(from: from, to: to)  # => 5
+```
+
 ### Human-Readable Description
 
 ```ruby
@@ -69,6 +78,20 @@ Philiprehberger::CronParser.new('0 0 * * MON,WED,FRI') # specific days
 Philiprehberger::CronParser.new('0 0 * * 1,WED,5')     # mixed numeric and named
 ```
 
+### Named Aliases
+
+Standard crontab aliases are supported (case-insensitive):
+
+```ruby
+Philiprehberger::CronParser.new('@hourly')    # => 0 * * * *
+Philiprehberger::CronParser.new('@daily')     # => 0 0 * * *
+Philiprehberger::CronParser.new('@midnight')  # alias for @daily
+Philiprehberger::CronParser.new('@weekly')    # => 0 0 * * 0
+Philiprehberger::CronParser.new('@monthly')   # => 0 0 1 * *
+Philiprehberger::CronParser.new('@yearly')    # => 0 0 1 1 *
+Philiprehberger::CronParser.new('@annually')  # alias for @yearly
+```
+
 ### Validation
 
 ```ruby
@@ -104,6 +127,7 @@ Philiprehberger::CronParser.new('0 9 * * MON-FRI') # named weekdays
 | `Expression#next(from:)` | Calculate the next matching time |
 | `Expression#prev(from:)` | Calculate the previous matching time |
 | `Expression#next_n(n, from:)` | Calculate the next N matching times |
+| `Expression#count_in(from:, to:)` | Count occurrences within an inclusive `[from, to]` window |
 | `Expression#matches?(time)` | Check if a time matches the expression |
 | `Expression#human_readable` | Human-readable description of the expression |
 | `Expression#description` | Alias for `human_readable` |

data/lib/philiprehberger/cron_parser/expression.rb

@@ -30,13 +30,27 @@ module Philiprehberger
         weekday: 'day of week'
       }.freeze
 
-      # @return [String] the original expression
+      ALIASES = {
+        '@yearly' => '0 0 1 1 *',
+        '@annually' => '0 0 1 1 *',
+        '@monthly' => '0 0 1 * *',
+        '@weekly' => '0 0 * * 0',
+        '@daily' => '0 0 * * *',
+        '@midnight' => '0 0 * * *',
+        '@hourly' => '0 * * * *'
+      }.freeze
+
+      # @return [String] the original (post-alias expansion) expression
       attr_reader :expression
 
-      # @param expr [String] a 5-field cron expression
+      # @param expr [String] a 5-field cron expression or named alias (e.g. "@daily")
       # @raise [Error] if the expression is invalid
       def initialize(expr)
-        @expression = expr.strip
+        stripped = expr.strip
+        stripped = ALIASES[stripped.downcase] if stripped.start_with?('@')
+        raise Error, "Unknown cron alias: #{expr.strip}" if stripped.nil?
+
+        @expression = stripped
         parts = @expression.split(/\s+/)
         raise Error, "Expected 5 fields, got #{parts.size}: #{@expression}" unless parts.size == 5
 
@@ -92,6 +106,30 @@ module Philiprehberger
         results
       end
 
+      # Count occurrences within a time window [from, to].
+      #
+      # The window is inclusive on both ends; `from` is treated as the cursor's
+      # starting point so an exact match at `from` counts only if it lies on a
+      # minute boundary that the schedule fires on.
+      #
+      # @param from [Time] start of the window
+      # @param to [Time] end of the window
+      # @return [Integer] the count of occurrences in the window
+      # @raise [Error] if `to` is earlier than `from`
+      def count_in(from:, to:)
+        raise Error, '`to` must be greater than or equal to `from`' if to < from
+
+        count = 0
+        cursor = round_to_minute(from) - 60
+        loop do
+          cursor = self.next(from: cursor)
+          break if cursor > to
+
+          count += 1
+        end
+        count
+      end
+
       # Return a human-readable description of the expression
       #
       # @return [String]

data/lib/philiprehberger/cron_parser/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CronParser
-    VERSION = '0.2.0'
+    VERSION = '0.4.0'
   end
 end

data/lib/philiprehberger/cron_parser.rb

@@ -37,6 +37,12 @@ module Philiprehberger
     def self.validate(expr)
       errors = []
       stripped = expr.strip
+      if stripped.start_with?('@')
+        alias_expanded = Expression::ALIASES[stripped.downcase]
+        return { valid: false, errors: ["Unknown cron alias: #{stripped}"] } if alias_expanded.nil?
+
+        stripped = alias_expanded
+      end
       parts = stripped.split(/\s+/)
 
       unless parts.size == 5

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-cron_parser
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-03 00:00:00.000000000 Z
+date: 2026-05-01 00:00:00.000000000 Z
 dependencies: []
 description: Parse standard 5-field cron expressions and calculate next/previous occurrences,
   match times against patterns, and generate human-readable descriptions.