fiscal_year 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0917960fc403b45d283863bad77ac8e35fc8b5a3c216a13f1ca2cdb68c95410a'
-  data.tar.gz: 68506d80a59973356f41d5bd1c55af3164542378ec8d9bea7d31be14bd90e302
+  metadata.gz: a66a9750908c6de12be50a3ddac4da7070d3e7b43898151ada109d586e26d983
+  data.tar.gz: 407e156b9e5e8f154c68059a652b62cb0016c8aa901b69686c6d8046aa599a6b
 SHA512:
-  metadata.gz: 74e0c8c7ddff795d9c64754dde60b462073f45afd04892dcad3e1595970d1bc2a7ac4ebf3bc464ccc112f10bfe33393023bf008cf08b349c27839994a00c4199
-  data.tar.gz: 50c1f1e00478c28ee72bc301ab8ab5fe42c1d142e822cc2d8747ff25f631ff62aff2e3e457e8bb852cde09676b38c0826057f8dedd503e5ad8ad2c3ad37a7e90
+  metadata.gz: 89fe574b9f0e5cd38a7b2add1caf81d1fdfec9fcf4a321da81aa11ffba72e25df925a343ba20703b66cece55407e40da6b30b101baa9e4e9e543836d71db6ab1
+  data.tar.gz: 4a67105553886931e1868e47b724b5dc983f507961625a7fb498d45697342ba1fe91aa951320faabf6e1c10c8a0bc47dd856b89675b0f06804077553b1f4f4e8

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [1.0.0] - 2024-07-24
+celebrate 1.0.0 release!! 🎉
+No Breaking Changes, Some futures.
+
+- add `passed_month_count_by` and `passed_month_count_by_month` to each FiscalYear, Half, Quarter.
+- fix wrong example comment on `FiscalYear::YearToDate.quarter_range_by`.
+- robust `Config.start_month`. you can no longer pass invalid month. now only pass number 1-12, or short symbol like `:jan`, `:dec`.
+
+Thank you for gave me courage to release, ruby-jp!
+
+## [0.7.0] - 2024-07-11
+- add YARD comment.
+- fix `FiscalYear::YearToDate.quarter_range_by` logic.
+
 ## [0.6.0] - 2024-05-15
 - [BREAK] Ruby 3.0.x, 2.7.x and 2.6.x has no longer support.
 - add `FiscalYear.range_by` method

data/lib/fiscal_year/config.rb

@@ -1,11 +1,52 @@
 # frozen_string_literal: true
 
+require "fiscal_year/invalid_start_month_error"
+
 module FiscalYear
   class Config
-    attr_accessor :start_month
+    attr_reader :start_month
+
+    VALID_START_MONTHS = {
+      jan: 1,
+      feb: 2,
+      mar: 3,
+      apr: 4,
+      may: 5,
+      jun: 6,
+      jul: 7,
+      aug: 8,
+      sep: 9,
+      oct: 10,
+      nov: 11,
+      dec: 12
+    }.freeze
 
     def initialize
       @start_month = 4
     end
+
+    def start_month=(month)
+      valid_start_month?(month)
+
+      @start_month = fetch_start_month(month)
+    end
+
+    private
+
+    def valid_start_month?(month)
+      if month.is_a? Integer
+        VALID_START_MONTHS.values.include?(month)
+      else
+        VALID_START_MONTHS.keys.include?(month)
+      end || raise(InvalidStartMonthError)
+    end
+
+    def fetch_start_month(month)
+      if month.is_a? Integer
+        VALID_START_MONTHS.rassoc(month)&.last
+      else
+        VALID_START_MONTHS.assoc(month)&.last
+      end || raise(StandardError)
+    end
   end
 end

data/lib/fiscal_year/half.rb

@@ -3,47 +3,55 @@
 module FiscalYear
   class Half
     class << self
+      # @return [Array<Integer>] the first half of the fiscal year.
       def first
-        first = FiscalYear.halfs.first
-        return first if first.is_a? Array
-
-        []
+        FiscalYear.halfs.first || raise(StandardError)
       end
 
+      # @return [Array<Integer>] the second half of the fiscal year.
       def second
-        second = FiscalYear.halfs.second
-        return second if second.is_a? Array
-
-        []
+        FiscalYear.halfs.second || raise(StandardError)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the first half of the fiscal year.
       def first?(month)
         FiscalYear.halfs.first.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the second half of the fiscal year.
       def second?(month)
         !first?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Array<Integer>] the half months by the month.
+      def months(month)
+        first?(month) ? first : second
+      end
+
+      # @param year [Integer] the calendar year
+      # @return [Range<Date>] the range of the first half of the fiscal year.
       def first_range_by(year)
         # care Date#parse 2 digit year auto complete.
         # 99 + 1 = 100, but expect 2000 this context.
         year = 1999 if year == 99
-        end_month = first.last
-        raise StandardError if end_month.nil?
+        end_month = first.last || raise(StandardError)
 
         end_year = FiscalYear.increase_year_by_month(year, end_month)
 
         Date.parse("#{year}/#{first.first}/01")..Date.parse("#{end_year}/#{end_month}/01").end_of_month
       end
 
+      # @param year [Integer] the calendar year
+      # @return [Range<Date>] the range of the second half of the fiscal year.
       def second_range_by(year)
         # care Date#parse 2 digit year auto complete.
         # 99 + 1 = 100, but expect 2000 this context.
         year = 1999 if year == 99
-        first_month = second.first
-        end_month = second.last
-        raise StandardError if first_month.nil? || end_month.nil?
+        first_month = second.first || raise(StandardError)
+        end_month = second.last || raise(StandardError)
 
         start_year = FiscalYear.increase_year_by_month(year, first_month)
         end_year = FiscalYear.increase_year_by_month(year, end_month)
@@ -51,6 +59,8 @@ module FiscalYear
         Date.parse("#{start_year}/#{first_month}/01")..Date.parse("#{end_year}/#{end_month}/01").end_of_month
       end
 
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the half of the fiscal year by the date.
       def range_by(date)
         month = date.month
         year = date.year
@@ -60,9 +70,29 @@ module FiscalYear
         first?(month) ? first_range_by(year) : second_range_by(year)
       end
 
+      # @param half [Array<Integer>] the half of the fiscal year
+      # @return [Boolean] true if the any month of half are crossed calendar year.
       def cross_year_in_half?(half)
         FiscalYear.cross_year? && half.any? { |month| month == 12 }
       end
+
+      # start by 0.
+      #
+      # @see passed_month_count_by_month
+      # @param date [Date] the date
+      # @return [Integer] the passed month count from the beginning of the half.
+      def passed_month_count_by(date)
+        passed_month_count_by_month(date.month)
+      end
+
+      # start by 0.
+      #
+      # @see passed_month_count_by_month
+      # @param date [Date] the date
+      # @return [Integer] the passed month count from the beginning of the half.
+      def passed_month_count_by_month(month)
+        months(month).find_index(month) || raise(StandardError)
+      end
     end
   end
 end

data/lib/fiscal_year/invalid_start_month_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FiscalYear
+  class InvalidStartMonthError < StandardError
+    def message
+      "Invalid start month. please set 1-12 or :jan, :feb, :mar, :apr, :may, :jun, :jul, :aug, :sep, :oct, :nov, :dec."
+    end
+  end
+end

data/lib/fiscal_year/quarter.rb

@@ -3,35 +3,55 @@
 module FiscalYear
   class Quarter
     class << self
+      # @!method first
+      # @return [Array<Integer>] the first quarter of the fiscal year.
+
+      # @!method second
+      # @return [Array<Integer>] the second quarter of the fiscal year.
+
+      # @!method third
+      # @return [Array<Integer>] the third quarter of the fiscal year.
+
+      # @!method fourth
+      # @return [Array<Integer>] the fourth quarter of the fiscal year.
       %i[first second third fourth].each do |method_name|
         define_method(method_name) do
           FiscalYear.quarters.public_send(method_name)
         end
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the first quarter of the fiscal year.
       def first?(month)
         FiscalYear.quarters.first.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the second quarter of the fiscal year.
       def second?(month)
         FiscalYear.quarters.second.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the third quarter of the fiscal year.
       def third?(month)
         FiscalYear.quarters.third.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Boolean] true if the month is in the fourth quarter of the fiscal year.
       def fourth?(month)
         FiscalYear.quarters.fourth.include?(month)
       end
 
+      # @param month [Integer] the month
+      # @return [Array<Integer>] the quarter months by the month.
       def months(month)
-        months = FiscalYear.quarters.find { |a| a.include?(month) }
-        raise ::StandardError if months.nil?
-
-        months
+        FiscalYear.quarters.find { |a| a.include?(month) } || raise(StandardError)
       end
 
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the quarter by the date.
       def range_by(date)
         year = date.year
         this_quarter = months(date.month)
@@ -40,15 +60,35 @@ module FiscalYear
         Date.parse("#{year}/#{this_quarter.first}/01")..Date.parse("#{last_year}/#{this_quarter.last}/01").end_of_month
       end
 
+      # @param month [Integer] the month
+      # @return [Integer] the quarter number by the month.
       def quarter_num(month)
         rindex = FiscalYear.quarters.rindex(months(month))
 
         rindex.nil? ? 0 : (rindex + 1)
       end
 
+      # @param quarter [Array<Integer>] the quarter
+      # @return [Boolean] true if the quarter is crossed calendar year.
       def cross_year_in_quarter?(quarter)
         FiscalYear.cross_year? && quarter.any? { |month| month == 12 }
       end
+
+      # start by 0.
+      #
+      # @param date [Date] the date
+      # @return [Integer] the passed quarter count by the date.
+      def passed_month_count_by(date)
+        passed_month_count_by_month(date.month)
+      end
+
+      # start by 0.
+      #
+      # @param month [Integer] the month
+      # @return [Integer] the passed quarter count by the month.
+      def passed_month_count_by_month(month)
+        months(month).find_index(month) || raise(StandardError)
+      end
     end
   end
 end

data/lib/fiscal_year/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FiscalYear
-  VERSION = "0.6.0"
+  VERSION = "1.0.0"
 end

data/lib/fiscal_year/year_to_date.rb

@@ -3,6 +3,14 @@
 module FiscalYear
   class YearToDate
     class << self
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the year to date.
+      # @example
+      #  FiscalYear::YearToDate.range_by(Date.parse("2021-08-01"))
+      #  => Thu, 01 Apr 2021..Tue, 31 Aug 2021
+      #
+      #  FiscalYear::YearToDate.range_by(Date.parse("2021-01-01"))
+      #  =>  Wed, 01 Apr 2020..Sun, 31 Jan 2021
       def range_by(date)
         year = date.year
         month = date.month
@@ -14,45 +22,60 @@ module FiscalYear
         end
       end
 
-      # TODO: fit to Abc size
-      def year_month_pairs(date) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # @param date [Date] the date
+      # @return [Array<Array<Integer>, Array<Integer>>] the passed year and month pairs.
+      # @example
+      #  FiscalYear::YearToDate.year_month_pairs(Date.parse("2021-08-01"))
+      #  => [[2021, 4], [2021, 5], [2021, 6], [2021, 7], [2021, 8]]
+      #
+      #  FiscalYear::YearToDate.year_month_pairs(Date.parse("2021-01-01"))
+      #  => [
+      #       [2020, 4], [2020, 5], [2020, 6], [2020, 7], [2020, 8], [2020, 9],
+      #       [2020, 10], [2020, 11], [2020, 12], [2021, 1]
+      #     ]
+      def year_month_pairs(date)
         month = date.month
         month_index = FiscalYear.months.index(month)
         months = FiscalYear.months[(0..month_index)]
         raise StandardError if months.nil?
 
         [date.year].product(months).map do |e|
-          if FiscalYear.cross_year_month?(month)
-            (FiscalYear.cross_year_month?(e.second) ? e : [e.first - 1, e.second])
-          else
-            e
-          end
+          [FiscalYear.decrease_year_by_month(e.first, e.second), e.second]
         end
       end
 
-      # TODO: fit to Abc size
-      def half_range_by(date) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the half year to date.
+      # @example
+      #  FiscalYear::YearToDate.half_range_by(Date.parse("2021-08-01"))
+      #  => Thu, 01 Apr 2021..Tue, 31 Aug 2021
+      #
+      #  FiscalYear::YearToDate.half_range_by(Date.parse("2021-01-01"))
+      #  =>  Thu, 01 Oct 2020..Sun, 31 Jan 2021
+      def half_range_by(date)
         year = date.year
         month = date.month
 
-        if Half.first?(month)
-          return (Date.parse("#{FiscalYear.cross_year_month?(month) ? year - 1 : year}/#{Half.first.first}/01")..
-            date.end_of_month.to_date
-                 )
-        end
+        beginning_year =
+          if Half.first?(month)
+            FiscalYear.cross_year_month?(month) ? year - 1 : year
+          else
+            Half.cross_year_in_half?(Half.second) ? FiscalYear.decrease_year_by_month(year, month) : year
+          end
+
+        half_method = Half.first?(month) ? :first : :second
 
-        Date.parse(
-          "#{
-              if FiscalYear::Half.cross_year_in_half?(Half.second) &&
-              FiscalYear.cross_year_month?(month)
-                year - 1
-              else
-                year
-              end
-            }/#{Half.second.first}"
-        )..date.end_of_month.to_date
+        Date.parse("#{beginning_year}/#{Half.public_send(half_method).first}/01")..date.end_of_month.to_date
       end
 
+      # @param date [Date] the date
+      # @return [Range<Date>] the range of the quarter to date.
+      # @example
+      #  FiscalYear::YearToDate.quarter_range_by(Date.parse("2021-08-01"))
+      #  => Thu, 01 Jul 2021..Tue, 31 Aug 2021
+      #
+      #  FiscalYear::YearToDate.quarter_range_by(Date.parse("2021-01-01"))
+      #  =>  Fri, 01 Jan 2021..Sun, 31 Jan 2021
       def quarter_range_by(date)
         year = date.year
         month = date.month
@@ -63,10 +86,10 @@ module FiscalYear
 
         quarter = Quarter.public_send(quarter_method)
 
-        (
-          Date.parse("#{FiscalYear.cross_year_month?(month) ? year - 1 : year}/#{quarter.first}/01")..
-          date.end_of_month.to_date
-        )
+        beginning_year =
+          Quarter.cross_year_in_quarter?(quarter) ? FiscalYear.decrease_year_by_month(year, month) : year
+
+        Date.parse("#{beginning_year}/#{quarter.first}/01")..date.end_of_month.to_date
       end
     end
   end

data/lib/fiscal_year.rb

@@ -14,45 +14,67 @@ module FiscalYear
   # @type ivar @config: FiscalYear::Config
   @config ||= FiscalYear::Config.new
   class << self
+    # @return [FiscalYear::Config]
     attr_reader :config
 
+    # configure start month of fiscal year.
+    #
+    # @yieldparam config [FiscalYear::Config]
+    # @example
+    #  FiscalYear.configure do |config|
+    #    config.start_month = 6
+    #  end
     def configure
       yield(@config) if block_given?
     end
 
+    # If the fiscal year start from 4, the month 1, 2, 3 are crossed year.
+    #
+    # @param month [Integer] the month to check, 1-12.
+    # @return [Boolean] true if the month is crossed year on calendar year.
+    # Determines if the month passed is beyond the year, By relative to the beginning month of the fiscal year.
     def cross_year_month?(month)
       cross_year_months.include?(month)
     end
 
+    # @return [Boolean] true if the fiscal year is crossed year.
     def cross_year?
       months.rindex(1) != 0
     end
 
+    # @return [Array<Integer>] the months of the fiscal year.
     def months
       (1..12).to_a.tap { |arr| arr.concat(arr.shift(@config.start_month - 1)) }
     end
 
+    # @return [Array<Integer>] the months of the crossed year.
     def cross_year_months
       return [] if @config.start_month == 1
 
       rindex = months.rindex(1).to_i
 
-      m = months.slice(rindex, months.length)
-      raise StandardError if m.nil?
-
-      m
+      months.slice(rindex, months.length) || raise(StandardError)
     end
 
+    # @return [Array(Array<Integer>, Array<Integer>)] the first half and the second half of the fiscal year.
     def halfs
       # @type self: singleton(FiscalYear)
       months.in_groups(2)
     end
 
+    # @return [Array(Array<Integer>, Array<Integer>, Array<Integer>, Array<Integer>)] the quarters of the fiscal year.
     def quarters
       # @type self: singleton(FiscalYear)
       months.in_groups(4)
     end
 
+    # increate the calendar year by month, if the month is crossed year.
+    #
+    # for example, in case of the fiscal year start from 4, you want to obtain calendar year of the month 1, 2, 3.
+    #
+    # @param year [Integer] the calendar year
+    # @param month [Integer] the month
+    # @return [Integer] year
     def increase_year_by_month(year, month)
       if FiscalYear.cross_year_month?(month)
         year + 1
@@ -61,6 +83,13 @@ module FiscalYear
       end
     end
 
+    # decrease the calendar year by month, if the month is crossed year.
+    #
+    # for example, in case of the fiscal year start from 4, you want to obtain fiscal year from the month 1, 2, 3.
+    #
+    # @param year [Integer] the calendar year
+    # @param month [Integer] the month
+    # @return [Integer] year
     def decrease_year_by_month(year, month)
       if FiscalYear.cross_year_month?(month)
         year - 1
@@ -69,6 +98,8 @@ module FiscalYear
       end
     end
 
+    # @param date [Date] the date
+    # @return [Range<Date>] the range of the fiscal year between beginning and end by the date.
     def range_by(date)
       year = date.year
       month = date.month
@@ -76,5 +107,22 @@ module FiscalYear
 
       FiscalYear::Half.first_range_by(normalized_year).first..FiscalYear::Half.second_range_by(normalized_year).last
     end
+
+    # start by 0.
+    #
+    # @see passed_month_count_by_month
+    # @param date [Date] the date
+    # @return [Integer] the passed month count from the beginning of the fiscal year.
+    def passed_month_count_by(date)
+      passed_month_count_by_month(date.month)
+    end
+
+    # start by 0.
+    #
+    # @param month [Integer] the month
+    # @return [Integer] the passed month count from the beginning of the fiscal year.
+    def passed_month_count_by_month(month)
+      months.find_index(month) || raise(StandardError)
+    end
   end
 end

data/sig/fiscal_year/config.rbs

@@ -1,6 +1,10 @@
 module FiscalYear
   class Config
     attr_reader start_month: Integer
+    VALID_START_MONTHS: Hash[Symbol, Integer]
     def initialize: -> Integer
+    def start_month=: (Integer|Symbol) -> bool
+    def valid_start_month?: (Integer|Symbol) -> bool
+    def fetch_start_month: (Integer|Symbol) -> Integer
   end
 end

data/sig/fiscal_year/half.rbs

@@ -4,9 +4,12 @@ module FiscalYear
     def self.second: () -> Array[Integer] | -> Array[untyped]
     def self.first?: (Integer) -> bool
     def self.second?: (Integer) -> bool
+    def self.months: (Integer) -> Array[Integer]
     def self.first_range_by: (Integer) -> Range[Date]
     def self.second_range_by: (Integer) -> Range[Date]
     def self.range_by: (Date) -> Range[Date]
     def self.cross_year_in_half?: (Array[Integer]) -> bool
+    def self.passed_month_count_by: (Date) -> Integer
+    def self.passed_month_count_by_month: (Integer) -> Integer
   end
 end

data/sig/fiscal_year/invalid_start_month_error.rbs

@@ -0,0 +1,5 @@
+module FiscalYear
+  class InvalidStartMonthError < StandardError
+    def message: -> String
+  end
+end

data/sig/fiscal_year/quarter.rbs

@@ -12,5 +12,7 @@ module FiscalYear
     def self.range_by: (Date) -> Range[Date]
     def self.quarter_num: (Integer) -> Integer
     def self. cross_year_in_quarter?: (Array[Integer]) -> bool
+    def self.passed_month_count_by: (Date) -> Integer
+    def self.passed_month_count_by_month: (Integer) -> Integer
   end
-end
+end

data/sig/fiscal_year.rbs

@@ -12,5 +12,7 @@ module FiscalYear
   def self.quarters: () -> [Array[Integer], Array[Integer], Array[Integer], Array[Integer]]
   def self.increase_year_by_month: (Integer, Integer) -> Integer
   def self.decrease_year_by_month: (Integer, Integer) -> Integer
-  def self.range_by: (Date) -> Range
+  def self.range_by: (Date) -> Range[Date]
+  def self.passed_month_count_by: (Date) -> Integer
+  def self.passed_month_count_by_month: (Integer) -> Integer
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fiscal_year
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Tsubasa Kawajiri
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-15 00:00:00.000000000 Z
+date: 2024-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -43,6 +43,7 @@ files:
 - lib/fiscal_year.rb
 - lib/fiscal_year/config.rb
 - lib/fiscal_year/half.rb
+- lib/fiscal_year/invalid_start_month_error.rb
 - lib/fiscal_year/quarter.rb
 - lib/fiscal_year/version.rb
 - lib/fiscal_year/year_to_date.rb
@@ -51,6 +52,7 @@ files:
 - sig/fiscal_year.rbs
 - sig/fiscal_year/config.rbs
 - sig/fiscal_year/half.rbs
+- sig/fiscal_year/invalid_start_month_error.rbs
 - sig/fiscal_year/quarter.rbs
 - sig/fiscal_year/year_to_date.rbs
 homepage: https://github.com/TsubasaKawajiri/fiscal_year