philiprehberger-date_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d98337f647fbd67ead4931f4f95e0553a15076c01fc4a58f0ec5139e1b0bc4a
+  data.tar.gz: a27295be6217b5cfafa6e8b9a9041590324c047fad03e491596598a1e0d30cfa
+SHA512:
+  metadata.gz: 291136dcc83f3445d53d59a91a86c18e75434eca88713be6dce3d0ae23b0990da9dc0993821c5153c2d111333763d2a0aee5f894c908da63344c6fa859e5b9b7
+  data.tar.gz: a6897bcffebfd3dfaf94ff825aabbbe79332bdda5c56333bbedcced1c6f86746651012a549509d7d1016861acb6c3e6d5b2c4796676c3381ef8d035233b207b3

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+
+- Initial release
+- Business day counting between two dates
+- Business day arithmetic with holiday support
+- Quarter boundary calculation (beginning and end)
+- Weekend detection
+- Natural language relative date parsing ("2 weeks ago", "next month", "yesterday")

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,94 @@
+# philiprehberger-date_kit
+
+[![Tests](https://github.com/philiprehberger/rb-date-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-date-kit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-date_kit.svg)](https://rubygems.org/gems/philiprehberger-date_kit)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-date-kit)](LICENSE)
+
+Date utilities for business days, relative expressions, and period calculations
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-date_kit"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-date_kit
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/date_kit"
+
+Philiprehberger::DateKit.business_days_between(Date.new(2026, 3, 16), Date.new(2026, 3, 23))
+# => 4
+```
+
+### Adding Business Days
+
+```ruby
+Philiprehberger::DateKit.add_business_days(Date.new(2026, 3, 20), 3)
+# => 2026-03-25 (skips weekend)
+
+holidays = [Date.new(2026, 3, 23)]
+Philiprehberger::DateKit.add_business_days(Date.new(2026, 3, 20), 1, holidays: holidays)
+# => 2026-03-24 (skips weekend and holiday)
+```
+
+### Quarter Boundaries
+
+```ruby
+Philiprehberger::DateKit.beginning_of_quarter(Date.new(2026, 5, 15))
+# => 2026-04-01
+
+Philiprehberger::DateKit.end_of_quarter(Date.new(2026, 5, 15))
+# => 2026-06-30
+```
+
+### Relative Date Parsing
+
+```ruby
+Philiprehberger::DateKit.parse_relative('2 weeks ago')
+Philiprehberger::DateKit.parse_relative('next month')
+Philiprehberger::DateKit.parse_relative('yesterday')
+Philiprehberger::DateKit.parse_relative('in 3 days')
+```
+
+### Weekend Detection
+
+```ruby
+Philiprehberger::DateKit.weekend?(Date.new(2026, 3, 21)) # => true (Saturday)
+Philiprehberger::DateKit.weekend?(Date.new(2026, 3, 20)) # => false (Friday)
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `.business_days_between(start, finish)` | Count business days between two dates |
+| `.add_business_days(date, n, holidays:)` | Add business days, skipping weekends and holidays |
+| `.beginning_of_quarter(date)` | Return the first day of the quarter |
+| `.end_of_quarter(date)` | Return the last day of the quarter |
+| `.weekend?(date)` | Check if a date falls on a weekend |
+| `.parse_relative(str, relative_to:)` | Parse a relative date expression |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/philiprehberger/date_kit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module DateKit
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/date_kit.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'date'
+require_relative 'date_kit/version'
+
+module Philiprehberger
+  module DateKit
+    class Error < StandardError; end
+
+    # Count business days (Mon-Fri) between two dates, exclusive of both endpoints
+    #
+    # @param start_date [Date] the start date
+    # @param finish_date [Date] the end date
+    # @return [Integer] number of business days between the dates
+    def self.business_days_between(start_date, finish_date)
+      start_date = coerce_date(start_date)
+      finish_date = coerce_date(finish_date)
+
+      return 0 if start_date >= finish_date
+
+      count = 0
+      current = start_date + 1
+      while current < finish_date
+        count += 1 unless weekend?(current)
+        current += 1
+      end
+      count
+    end
+
+    # Add business days to a date, skipping weekends and holidays
+    #
+    # @param date [Date] the starting date
+    # @param days [Integer] number of business days to add
+    # @param holidays [Array<Date>] optional list of holiday dates to skip
+    # @return [Date] the resulting date
+    def self.add_business_days(date, days, holidays: [])
+      date = coerce_date(date)
+      holidays = holidays.map { |h| coerce_date(h) }
+
+      raise Error, 'days must be an integer' unless days.is_a?(Integer)
+
+      direction = days.positive? ? 1 : -1
+      remaining = days.abs
+      current = date
+
+      while remaining.positive?
+        current += direction
+        next if weekend?(current) || holidays.include?(current)
+
+        remaining -= 1
+      end
+
+      current
+    end
+
+    # Return the first day of the quarter containing the given date
+    #
+    # @param date [Date] the input date
+    # @return [Date] the first day of the quarter
+    def self.beginning_of_quarter(date)
+      date = coerce_date(date)
+      quarter_month = ((date.month - 1) / 3) * 3 + 1
+      Date.new(date.year, quarter_month, 1)
+    end
+
+    # Return the last day of the quarter containing the given date
+    #
+    # @param date [Date] the input date
+    # @return [Date] the last day of the quarter
+    def self.end_of_quarter(date)
+      date = coerce_date(date)
+      quarter_month = ((date.month - 1) / 3) * 3 + 3
+      end_month = Date.new(date.year, quarter_month, -1)
+      end_month
+    end
+
+    # Check if a date falls on a weekend (Saturday or Sunday)
+    #
+    # @param date [Date] the date to check
+    # @return [Boolean]
+    def self.weekend?(date)
+      date = coerce_date(date)
+      date.saturday? || date.sunday?
+    end
+
+    # Parse a relative date expression into a Date
+    #
+    # @param str [String] the expression (e.g., "2 weeks ago", "next month", "yesterday")
+    # @param relative_to [Date] the reference date (defaults to today)
+    # @return [Date] the parsed date
+    # @raise [Error] if the expression cannot be parsed
+    def self.parse_relative(str, relative_to: Date.today)
+      relative_to = coerce_date(relative_to)
+      normalized = str.to_s.strip.downcase
+
+      case normalized
+      when 'today'
+        relative_to
+      when 'yesterday'
+        relative_to - 1
+      when 'tomorrow'
+        relative_to + 1
+      when /\A(\d+)\s+days?\s+ago\z/
+        relative_to - ::Regexp.last_match(1).to_i
+      when /\Ain\s+(\d+)\s+days?\z/
+        relative_to + ::Regexp.last_match(1).to_i
+      when /\A(\d+)\s+weeks?\s+ago\z/
+        relative_to - (::Regexp.last_match(1).to_i * 7)
+      when /\Ain\s+(\d+)\s+weeks?\z/
+        relative_to + (::Regexp.last_match(1).to_i * 7)
+      when /\A(\d+)\s+months?\s+ago\z/
+        months_ago(relative_to, ::Regexp.last_match(1).to_i)
+      when /\Ain\s+(\d+)\s+months?\z/
+        months_ahead(relative_to, ::Regexp.last_match(1).to_i)
+      when /\A(\d+)\s+years?\s+ago\z/
+        years_ago(relative_to, ::Regexp.last_match(1).to_i)
+      when /\Ain\s+(\d+)\s+years?\z/
+        years_ahead(relative_to, ::Regexp.last_match(1).to_i)
+      when 'last week'
+        relative_to - 7
+      when 'next week'
+        relative_to + 7
+      when 'last month'
+        months_ago(relative_to, 1)
+      when 'next month'
+        months_ahead(relative_to, 1)
+      when 'last year'
+        years_ago(relative_to, 1)
+      when 'next year'
+        years_ahead(relative_to, 1)
+      else
+        raise Error, "cannot parse relative date: #{str}"
+      end
+    end
+
+    # @api private
+    def self.months_ago(date, n)
+      target_month = date.month - n
+      target_year = date.year
+      while target_month < 1
+        target_month += 12
+        target_year -= 1
+      end
+      day = [date.day, days_in_month(target_year, target_month)].min
+      Date.new(target_year, target_month, day)
+    end
+
+    # @api private
+    def self.months_ahead(date, n)
+      target_month = date.month + n
+      target_year = date.year
+      while target_month > 12
+        target_month -= 12
+        target_year += 1
+      end
+      day = [date.day, days_in_month(target_year, target_month)].min
+      Date.new(target_year, target_month, day)
+    end
+
+    # @api private
+    def self.years_ago(date, n)
+      target_year = date.year - n
+      day = [date.day, days_in_month(target_year, date.month)].min
+      Date.new(target_year, date.month, day)
+    end
+
+    # @api private
+    def self.years_ahead(date, n)
+      target_year = date.year + n
+      day = [date.day, days_in_month(target_year, date.month)].min
+      Date.new(target_year, date.month, day)
+    end
+
+    # @api private
+    def self.days_in_month(year, month)
+      Date.new(year, month, -1).day
+    end
+
+    # @api private
+    def self.coerce_date(value)
+      case value
+      when Date then value
+      when Time then value.to_date
+      when String then Date.parse(value)
+      else
+        raise Error, "cannot coerce #{value.class} to Date"
+      end
+    end
+
+    private_class_method :months_ago, :months_ahead, :years_ago, :years_ahead, :days_in_month, :coerce_date
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-date_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: Date utilities including business day counting and arithmetic, quarter
+  boundaries, weekend detection, and natural language relative date parsing.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/date_kit.rb
+- lib/philiprehberger/date_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-date-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-date-kit
+  source_code_uri: https://github.com/philiprehberger/rb-date-kit
+  changelog_uri: https://github.com/philiprehberger/rb-date-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-date-kit/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Date utilities for business days, relative expressions, and period calculations
+test_files: []