singapore_cpf_calculator 1.2.0 → 1.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0d44d25461342a4f59f937164260f9b7f4a80997
-  data.tar.gz: 5ae6f53a86bb4b3765673b5e8c7d94af62efa288
+SHA256:
+  metadata.gz: 2b0d8aa374278f946ccb6f54e778961317d15d455a0f0eeae1eb4bd4af7b251a
+  data.tar.gz: a711ea455d39a43a8d3dc2b598c02db1a35e8e95b15121139a53b4dbb6640255
 SHA512:
-  metadata.gz: 6c2beef08f80b1090938105321b0e7f27d6cc0fb1ae858a9557bae5a140288b27012a7ee2bde9063dd27f3202d115ba15ec19e7ec8672f412b555c5ca843edc1
-  data.tar.gz: 5b0bac0f364682ff322895cfe39534a3bf645f9b422e717a05e4792bd7d83f7362b70303eab34b5564723ec75302d05df347281143bd303b75b761121ee3b084
+  metadata.gz: bb687c0f164156933033b3b2a8a2a00231d62c761e0c10aa8ee4d4569c98addf63d2cf9e6a30fcb8beaa4070a33e7e58defeae7fe1ea5127f11c7efb0f376e29
+  data.tar.gz: 6969152787d83f823a60087d293b9eeea8267ae5e871ea7b3a0d9cb8712a4dc91e74e89a7b2f0d089dad70a41ce9e9abeb4ecdf2a47fba2ea370d1cd2b2346a7

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+dist: trusty
+group: stable
+rvm:
+  - 2.1.8
+  - 2.2.4
+  - 2.3.8
+  - 2.4.9
+  - 2.5.8
+  - 2.6.6
+  - 2.7.1
+
+script:
+  - bundle exec rspec
+

data/README.md

@@ -44,9 +44,10 @@ Or install it yourself as:
 
 ## Usage
 
-Use {SingaporeCPFCalculator.calculate} to calculate for CPF contribution. The method return a
+Use {SingaporeCPFCalculator.calculate} to calculate for CPF contribution. The method returns a
 {SingaporeCPFCalculator::CPFContribution} object responding to {SingaporeCPFCalculator::CPFContribution#employee},
-{SingaporeCPFCalculator::CPFContribution#employer} and {SingaporeCPFCalculator::CPFContribution#total}.
+{SingaporeCPFCalculator::CPFContribution#employer}, {SingaporeCPFCalculator::CPFContribution#total},
+{SingaporeCPFCalculator::CPFContribution#ow_subject_to_cpf} and {SingaporeCPFCalculator::CPFContribution#aw_subject_to_cpf}.
 
 ```ruby
   require "singapore_cpf_calculator"
@@ -58,12 +59,16 @@ Use {SingaporeCPFCalculator.calculate} to calculate for CPF contribution. The me
                                             ordinary_wages: 700.00,
                                             additional_wages: 252.00,
                                             employee_contribution_type: "full",
-                                            employer_contribution_type: "full"
+                                            employer_contribution_type: "full",
+                                            ytd_additional_wages: 20_000,
+                                            ytd_ow_subject_to_cpf: 80_000
 
   result # => #<SingaporeCPFCalculator::CPFContribution ...>
   result.employee # => 190.00
   result.employer # => 153.00
   result.total # => 343.00
+  result.ow_subject_to_cpf # => 700.0 (the ordinary wages which were under the wage cap)
+  result.aw_subject_to_cpf # => 252.0 (the additional wages which were under the additional wage ceiling)
 ```
 
 The following parameters needs to be specified:
@@ -87,6 +92,12 @@ The following parameters needs to be specified:
   * **employer\_contribution\_type** : type of rates to use
     * accepted values : `"full"`, `"graduated"` type of rates to use for the employer's contribution
     * note: *graduated* rates is not supported if the employee's contribution type is *full*
+  * **ytd_additional_wages : Year to Date Additional Wages which were subject to CPF
+    * notes:
+      * this is for calculating the additional wage ceiling.
+  * **ytd_ow_subject_to_cpf: Year to Date Ordinary Wages which were subject to CPF
+    * notes:
+      * this is for calculating the additional wage ceiling.
 
 ## Contributing
 

data/lib/singapore_cpf_calculator.rb

@@ -12,7 +12,9 @@ module SingaporeCPFCalculator
     #                                             ordinary_wages: 700.00,
     #                                             additional_wages: 252.00,
     #                                             employee_contribution_type: "full",
-    #                                             employer_contribution_type: "full"
+    #                                             employer_contribution_type: "full",
+    #                                             ytd_additional_wages: 20_000,
+    #                                             ytd_ow_subject_to_cpf: 60_000
     #
     #   result # => #<SingaporeCPFCalculator::CPFContribution ...>
     #   result.employee # => 190.00
@@ -34,23 +36,27 @@ module SingaporeCPFCalculator
     #   Additional wages are wage supplements which are not granted wholly and exclusively for the
     #   month, such as annual bonus and leave pay. These and other incentive payments may be made at
     #   intervals of more than a month.
-    #
+    # @param [BigDecimal] ytd_additional_wages:
+    #   Cumulative Additional Wages for the year (YTD)
+    # @param [BigDecimal] ytd_ow_subject_to_cpf:
+    #   The Year to Date Ordinary Wages which have been subject to CPF.
     # @return [CPFContribution]
-    def calculate(
-      date:,
-      birthdate:,
-      residency_status:,
-      spr_start_date: nil,
-      ordinary_wages:,
-      additional_wages:,
-      employee_contribution_type: nil,
-      employer_contribution_type: nil
-    )
-      validate_params date: date,
+    def calculate(date:,
+                  birthdate:,
+                  residency_status:,
+                  spr_start_date: nil,
+                  ordinary_wages:,
+                  additional_wages:,
+                  employee_contribution_type: nil,
+                  employer_contribution_type: nil,
+                  ytd_additional_wages: 0.0,
+                  ytd_ow_subject_to_cpf: 0.0,
+                  estimated_yearly_ow: 0.0)
+      validate_params(date: date,
                       employee_contribution_type: employee_contribution_type,
                       employer_contribution_type: employer_contribution_type,
                       residency_status: residency_status,
-                      spr_start_date: spr_start_date
+                      spr_start_date: spr_start_date)
 
       module_for_date(date).
         module_for_residency(
@@ -60,7 +66,11 @@ module SingaporeCPFCalculator
           employee_contribution_type: employee_contribution_type,
           employer_contribution_type: employer_contribution_type
         ).calculator_for(date, birthdate: birthdate).
-        calculate ordinary_wages: ordinary_wages, additional_wages: additional_wages
+        calculate ordinary_wages: ordinary_wages,
+                  additional_wages: additional_wages,
+                  ytd_additional_wages: ytd_additional_wages,
+                  ytd_ow_subject_to_cpf: ytd_ow_subject_to_cpf,
+                  estimated_yearly_ow: estimated_yearly_ow
     end
 
     private
@@ -122,6 +132,7 @@ require_relative "singapore_cpf_calculator/spr_1_fg_common"
 require_relative "singapore_cpf_calculator/spr_1_gg_common"
 require_relative "singapore_cpf_calculator/spr_2_fg_common"
 require_relative "singapore_cpf_calculator/spr_2_gg_common"
+require_relative 'singapore_cpf_calculator/year_2012_to_2015_aw_ceiling_module'
 require_relative "singapore_cpf_calculator/year_2014"
 require_relative "singapore_cpf_calculator/year_2015"
 require_relative "singapore_cpf_calculator/year_2016"

data/lib/singapore_cpf_calculator/base_calculator.rb

@@ -18,9 +18,14 @@ module SingaporeCPFCalculator
       #   month, such as annual bonus and leave pay. These and other incentive payments may be made at
       #   intervals of more than a month.
       #
+      # @param [BigDecimal] ytd_additional_wages The year to date additional wages
+      # @param [BigDecimal] ytd_ow_subject_to_cpf The year to date ordinary wages
       # @return [Hash] returns the total, employee, employer amounts for the CPF contribution
-      def calculate(ordinary_wages:, additional_wages:)
-        new(ordinary_wages: ordinary_wages, additional_wages: additional_wages).calculate
+      def calculate(ordinary_wages:, additional_wages:, ytd_additional_wages: 0.0, ytd_ow_subject_to_cpf: 0.0,
+                    estimated_yearly_ow: 0.0)
+        new(ordinary_wages: ordinary_wages, additional_wages: additional_wages,
+            ytd_ow_subject_to_cpf: ytd_ow_subject_to_cpf, ytd_additional_wages: ytd_additional_wages,
+            estimated_yearly_ow: estimated_yearly_ow).calculate
       end
 
       private
@@ -30,25 +35,38 @@ module SingaporeCPFCalculator
       end
     end
 
-    def initialize(ordinary_wages:, additional_wages:)
+    def initialize(ordinary_wages:, additional_wages:, ytd_additional_wages: 0.0, ytd_ow_subject_to_cpf: 0.0,
+                   estimated_yearly_ow: 0.0)
       @ordinary_wages = ordinary_wages
+      @ytd_ow_subject_to_cpf = ytd_ow_subject_to_cpf
+      @ytd_additional_wages = ytd_additional_wages
+      @estimated_yearly_ow = estimated_yearly_ow
       @additional_wages = additional_wages
+      clip_additional_wages_based_on_ceiling()
     end
 
     # @return [Hash] returns the total, employee, employer amounts for the CPF contribution
     def calculate
       CPFContribution.new total: total_contribution,
-                          employee: employee_contribution
+                          employee: employee_contribution,
+                          aw_subject_to_cpf: additional_wages,
+                          ow_subject_to_cpf: capped_ordinary_wages
     end
 
     private
 
-    attr_reader :ordinary_wages, :additional_wages
+    attr_reader :ordinary_wages, :additional_wages, :ytd_additional_wages, :ytd_ow_subject_to_cpf,
+                :estimated_yearly_ow
 
     def total_contribution
       @total_contribution ||= calculated_total_contribution.round(0, :half_up)
     end
 
+    # Steps to compute CPF contribution:
+    #   a. Compute the total CPF contribution (rounded to the nearest dollar). An amount of 50 cents
+    #      should be regarded as an additional dollar.
+    #   b. Compute the employee’s share of CPF contribution (cents should be dropped)
+    #   c. Employer’s share = Total contribution – Employee’s share
     def employee_contribution
       @employee_contribution ||= calculated_employee_contribution.round(0, :truncate)
     end
@@ -61,6 +79,22 @@ module SingaporeCPFCalculator
       ordinary_wages + additional_wages
     end
 
+    def clip_additional_wages_based_on_ceiling
+      unless additional_wage_ceiling.blank?
+        @additional_wages = [additional_wages, calculated_remaining_wage_ceiling, estimated_remaining_wage_ceiling].min
+      end
+    end
+
+    def calculated_remaining_wage_ceiling
+      max_remaining = additional_wage_ceiling - ytd_ow_subject_to_cpf - capped_ordinary_wages - ytd_additional_wages
+      [max_remaining, d('0.0')].max
+    end
+
+    def estimated_remaining_wage_ceiling
+      estimated_remaining = additional_wage_ceiling - estimated_yearly_ow - ytd_additional_wages
+      [estimated_remaining, d('0.0')].max
+    end
+
     def calculated_total_contribution
       case
       when total_wages <= d("50.00")
@@ -85,6 +119,11 @@ module SingaporeCPFCalculator
       end
     end
 
+    # generally applies only to spr3 and citizens
+    def additional_wage_ceiling
+      nil
+    end
+
     # TC Rate 1 is
     def tc_rate_1
       raise NotImplementedError, "sub classes needs to implement #tc_rate_1"
@@ -108,7 +147,7 @@ module SingaporeCPFCalculator
 
     # precision helper
     def d(val)
-      BigDecimal.new val
+      BigDecimal(val)
     end
 
   end

data/lib/singapore_cpf_calculator/cpf_contribution.rb

@@ -4,13 +4,17 @@ module SingaporeCPFCalculator
   class CPFContribution
 
     # @return [BigDecimal]
-    attr_reader :total, :employee
+    attr_reader :total, :employee, :ow_subject_to_cpf, :aw_subject_to_cpf
 
     # @param [BigDecimal] total the total contribution amount
     # @param [BigDecimal] employee the employee contribution amount
-    def initialize(total:, employee:)
+    # @param [BigDecimal] ow_subject_to_cpf Ordinary Wages which were subject to CPF
+    # @param [BigDecimal] aw_subject_to_cpf Additional Wages which were subject to CPF
+    def initialize(total:, employee:, ow_subject_to_cpf:, aw_subject_to_cpf:)
       @total = total
       @employee = employee
+      @ow_subject_to_cpf = ow_subject_to_cpf
+      @aw_subject_to_cpf = aw_subject_to_cpf
     end
 
     # @return [BigDecimal] difference between the total and employee contributions
@@ -21,7 +25,14 @@ module SingaporeCPFCalculator
     # @param [CPFContribution] other
     # @return [TrueClass, FalseClass]
     def ==(other)
-      total == other.total && employee == other.employee
+      other.kind_of?(CPFContribution) && total == other.total && employee == other.employee &&
+        (ow_subject_to_cpf == other.ow_subject_to_cpf) &&
+        (aw_subject_to_cpf == other.aw_subject_to_cpf)
+    end
+
+    def inspect
+      {total: total.to_s, employee: employee.to_s,
+       ow_subject_to_cpf: ow_subject_to_cpf.to_s, aw_subject_to_cpf: aw_subject_to_cpf.to_s}.to_json
     end
 
   end

data/lib/singapore_cpf_calculator/null_contribution_calculator.rb

@@ -7,8 +7,10 @@ module SingaporeCPFCalculator
 
       # returns zero value
       def calculate(*)
-        CPFContribution.new total: BigDecimal.new("0.0"),
-                            employee: BigDecimal.new("0.0")
+        CPFContribution.new total: BigDecimal("0.0"),
+                            employee: BigDecimal("0.0"),
+                            ow_subject_to_cpf: BigDecimal('0.0'),
+                            aw_subject_to_cpf: BigDecimal('0.0')
       end
 
     end

data/lib/singapore_cpf_calculator/version.rb

@@ -1,3 +1,3 @@
 module SingaporeCPFCalculator
-  VERSION = "1.2.0"
+  VERSION = "1.3.4"
 end

data/lib/singapore_cpf_calculator/year_2012_to_2015_aw_ceiling_module.rb

@@ -0,0 +1,7 @@
+module SingaporeCPFCalculator
+  module Year2012To2015AwCeilingModule
+    def additional_wage_ceiling
+      d('85_000')
+    end
+  end
+end

data/lib/singapore_cpf_calculator/year_2014/base.rb

@@ -3,6 +3,7 @@ module SingaporeCPFCalculator
 
     # Base class for 2014 CPF calculators.
     class Base < BaseCalculator
+      include SingaporeCPFCalculator::Year2012To2015AwCeilingModule
 
       private
 

data/lib/singapore_cpf_calculator/year_2014/citizen_or_spr_3/citzen_or_spr3_base.rb

@@ -0,0 +1,8 @@
+module SingaporeCPFCalculator
+  module Year2014
+    module CitizenOrSPR3
+      class CitizenOrSpr3Base < Year2014::Base
+      end
+    end
+  end
+end

data/lib/singapore_cpf_calculator/year_2015/base.rb

@@ -3,6 +3,7 @@ module SingaporeCPFCalculator
 
     # Base class for 2014 CPF calculators.
     class Base < BaseCalculator
+      include SingaporeCPFCalculator::Year2012To2015AwCeilingModule
 
       private
 

data/lib/singapore_cpf_calculator/year_2015/citizen_or_spr_3.rb

@@ -1,3 +1,4 @@
+require_relative 'citizen_or_spr_3/citizen_or_spr3_base'
 require_relative "citizen_or_spr_3/age_50_below_contribution_calculator"
 require_relative "citizen_or_spr_3/age_50_to_55_contribution_calculator"
 require_relative "citizen_or_spr_3/age_55_to_60_contribution_calculator"

data/lib/singapore_cpf_calculator/year_2015/citizen_or_spr_3/age_50_below_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 50 and below.
-      class Age50BelowContributionCalculator < Year2015::Base
+      class Age50BelowContributionCalculator < CitizenOrSpr3Base
 
         extend Requirements::Group50YearsAndBelow
 

data/lib/singapore_cpf_calculator/year_2015/citizen_or_spr_3/age_50_to_55_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 50 to 55.
-      class Age50To55ContributionCalculator < Year2015::Base
+      class Age50To55ContributionCalculator < CitizenOrSpr3Base
 
         extend Requirements::GroupAbove50To55Years
 

data/lib/singapore_cpf_calculator/year_2015/citizen_or_spr_3/age_55_to_60_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 55 to 60.
-      class Age55To60ContributionCalculator < Year2015::Base
+      class Age55To60ContributionCalculator < CitizenOrSpr3Base
 
         extend Requirements::GroupAbove55To60Years
 

data/lib/singapore_cpf_calculator/year_2015/citizen_or_spr_3/age_60_to_65_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 60 to 65.
-      class Age60To65ContributionCalculator < Year2015::Base
+      class Age60To65ContributionCalculator < CitizenOrSpr3Base
 
         extend Requirements::GroupAbove60To65Years
 

data/lib/singapore_cpf_calculator/year_2015/citizen_or_spr_3/age_65_up_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 65 and above.
-      class Age65UpContributionCalculator < Year2015::Base
+      class Age65UpContributionCalculator < CitizenOrSpr3Base
 
         extend Requirements::GroupAbove65Years
 

data/lib/singapore_cpf_calculator/year_2015/citizen_or_spr_3/citizen_or_spr3_base.rb

@@ -0,0 +1,9 @@
+module SingaporeCPFCalculator
+  module Year2015
+    module CitizenOrSPR3
+      # Base calculator for citizen or spr3 in year 2015
+      class CitizenOrSpr3Base < Year2015::Base
+      end
+    end
+  end
+end

data/lib/singapore_cpf_calculator/year_2016/base.rb

@@ -6,6 +6,10 @@ module SingaporeCPFCalculator
 
       private
 
+      def additional_wage_ceiling
+        d('102_000')
+      end
+
       def capped_ordinary_wages
         [d("6_000"), ordinary_wages].min
       end

data/lib/singapore_cpf_calculator/year_2016/citizen_or_spr_3.rb

@@ -1,3 +1,4 @@
+require_relative 'citizen_or_spr_3/citizen_or_spr3_base'
 require_relative "citizen_or_spr_3/age_55_below_contribution_calculator"
 require_relative "citizen_or_spr_3/age_55_to_60_contribution_calculator"
 require_relative "citizen_or_spr_3/age_60_to_65_contribution_calculator"

data/lib/singapore_cpf_calculator/year_2016/citizen_or_spr_3/age_55_below_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 50 and below.
-      class Age55BelowContributionCalculator < Year2016::Base
+      class Age55BelowContributionCalculator < CitizenOrSpr3Base
 
         extend Requirements::Group55YearsAndBelow
 

data/lib/singapore_cpf_calculator/year_2016/citizen_or_spr_3/age_55_to_60_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 55 to 60.
-      class Age55To60ContributionCalculator < Year2016::Base
+      class Age55To60ContributionCalculator  < CitizenOrSpr3Base
 
         extend Requirements::GroupAbove55To60Years
 

data/lib/singapore_cpf_calculator/year_2016/citizen_or_spr_3/age_60_to_65_contribution_calculator.rb

@@ -3,7 +3,7 @@ module SingaporeCPFCalculator
     module CitizenOrSPR3
 
       # Payment calculator for Singapore's Central Provident Fund for employee's age 60 to 65.
-      class Age60To65ContributionCalculator < Year2016::Base
+      class Age60To65ContributionCalculator < CitizenOrSpr3Base
 
         extend Requirements::GroupAbove60To65Years