splittable 0.0.7 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1ce195bb6bf78672483d4823042006672922a3de448b313c3229c765e6acc54
-  data.tar.gz: 4d7dbcb92fc8345afcf92637741e68dc8a9cd349cc97e63f80fb66eb916c40da
+  metadata.gz: 11114efe2ce13eb5f799082f87b27b9031d61c88dc4bbf15429bbb96c5038a62
+  data.tar.gz: 214bcc97eb502853d46db7e0b2678570269b6226658cf3c11df921607372fc75
 SHA512:
-  metadata.gz: 33eb4933330ff1020bfc37e8a971273ec825bc6f17c64dbdf8d6825c056db25faeab0683aea256022887fabc524b07df19fe850d79e820df194dee3d37c61281
-  data.tar.gz: ec8f776bc35bb3c5abe8e887ccc6edd07da873d2f0eabbf9925bdbcf6732eba1188dcb5060f5912c6faedbea934879b4691d990338c3e7d22b38807acbf16a2a
+  metadata.gz: 3b47c45ce0f0078632eef4fd3ca2914c17398d75c1e5691d344db08bc9b81a165abe6165763861819e090ffdf264ac0aaf6d5cee9415649d28fbd7f67e7e02e7
+  data.tar.gz: 7d4722cc082db9dcb8d450f7fdd876f71842ee61ea8f3ec7716a695cef935ec15b08c09c6473c2f95894f467e14902045069ff5549b5ccd1d8a19352e628cee5

data/.github/workflows/publish_release.yml

@@ -15,14 +15,6 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Set up Ruby version specified in `.ruby-version`
-        with:
-          ruby-version: .ruby-version
-        uses: ruby/setup-ruby@v1
-
-      - name: Install dependencies
-        run: bundle install --jobs 4 --retry 3
-
       - name: Release Gem
         uses: m4rcelotoledo/publish-rubygems-action@master
         env:

data/CHANGELOG.md

@@ -1,3 +1,55 @@
+# splittable 0.0.9 (Oct 15, 2025)
+
+* **Bug Fixes**
+  * Fixed incorrect examples in README.md with mathematically accurate values
+  * Corrected division examples to show proper cent adjustment behavior
+  * Fixed normalize examples to demonstrate actual gem behavior
+
+* **Error Handling Improvements**
+  * Added proper validation for empty installments array in normalize method
+  * Added validation for nil installments parameter
+  * Improved error messages with clear ArgumentError exceptions
+  * Enhanced error handling documentation with accurate examples
+
+* **Test Coverage**
+  * Added comprehensive tests for error handling scenarios
+  * Added tests for empty and nil installments arrays
+  * Maintained 100% test coverage (38 examples, 0 failures)
+  * Improved test readability with better formatting
+
+* **Code Quality**
+  * Enhanced input validation in Splittable::Normalize class
+  * Improved error messages for better developer experience
+  * All existing functionality preserved and thoroughly tested
+
+  *Marcelo Toledo*
+
+## splittable 0.0.8 (Oct 14, 2025)
+
+* **Documentation Improvements**
+  * Complete README.md rewrite with better examples and real-world use cases
+  * Added comprehensive problem explanation with before/after examples
+  * Included e-commerce, invoice distribution, and subscription billing examples
+  * Added error handling documentation and development setup instructions
+  * Improved project structure documentation
+
+* **Gemspec Enhancements**
+  * Updated summary and description for better clarity and professionalism
+  * Added explicit BigDecimal dependency declaration
+  * Enhanced metadata with bug tracker URI
+  * Fixed RubyGems metadata warnings
+
+* **CI/CD Improvements**
+  * Fixed publish workflow to use correct Ruby version (3.4.6)
+  * Added proper dependency installation steps in release workflow
+  * Resolved Ruby version compatibility issues
+
+* **Code Quality**
+  * Maintained 100% test coverage
+  * All existing functionality preserved and tested
+
+  *Marcelo Toledo*
+
 ## splittable 0.0.7 (Oct 14, 2025)
 
 * Update repository

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    splittable (0.0.7)
+    splittable (0.0.9)
+      bigdecimal (~> 3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -2,12 +2,28 @@
 
 [![Gem Version](https://badge.fury.io/rb/splittable.svg)](https://badge.fury.io/rb/splittable)
 [![Ruby](https://github.com/m4rcelotoledo/splittable/workflows/Ruby/badge.svg?branch=master)](https://github.com/m4rcelotoledo/splittable/actions?query=workflow%3ARuby)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.4.6-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-## Goal
+## 🎯 Problem Solved
 
-This gem solves the problem of several decimal places in divisions where the result must be presented in cents, that is converting the division result to only two decimal places and the difference is attributed to the first plot.
+When dividing monetary values, you often get results with many decimal places that need to be rounded to cents (2 decimal places). This creates a common problem: **the sum of rounded installments doesn't equal the original total**.
 
-## Installation
+**Example of the problem:**
+```ruby
+# Dividing $100.00 into 3 equal parts
+100.00 / 3 = 33.333333...
+
+# If we round each installment to 2 decimal places:
+[33.33, 33.33, 33.33].sum = 99.99  # ❌ Missing $0.01!
+```
+
+**Splittable solves this by:**
+- Truncating values to the specified precision
+- Adding the difference to the first installment
+- Ensuring the sum always equals the original value
+
+## 🚀 Installation
 
 Add this line to your application's Gemfile:
 
@@ -17,77 +33,167 @@ gem 'splittable'
 
 And then execute:
 
-    $ bundle install
+```bash
+$ bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install splittable
+```bash
+$ gem install splittable
+```
+
+## 📖 Usage
 
-## Usage
+### Division Method
 
-Using `division` method:
+Split a total value into equal installments:
 
-``` ruby
-Splittable.division(value: 0.1188888, quantity: 3)
+```ruby
+# Basic usage - split $0.12 into 3 equal parts
+Splittable.division(value: 0.12, quantity: 3)
+# => [0.04, 0.04, 0.04]  # Sum: 0.12
+
+# Custom precision - 3 decimal places
+Splittable.division(value: 10, quantity: 3, precision: 3)
+# => [3.334, 3.333, 3.333]  # Sum: 10.000
 ```
 
-Result: the total truncated value was divided by the number of plots informed and attributed the difference in the first installment:
+### Normalize Method
+
+Normalize existing installments to match a total value:
 
 ```ruby
-=> [0.5e-1, 0.3e-1, 0.3e-1] # => [0.05, 0.03, 0.03]
-```
-Default precision is 2 decimal places, but, you can customize this with precision parameter:
+# Normalize installments to sum exactly $100.00
+Splittable.normalize(value: 100.00, installments: [33.33, 33.33, 33.33])
+# => [33.34, 33.33, 33.33]  # Sum: 100.00
 
-``` ruby
-Splittable.division(value: 10, quantity: 3, precision: 3)
+# With custom precision
+Splittable.normalize(value: 100, installments: [33.333, 33.333, 33.333], precision: 3)
+# => [33.334, 33.333, 33.333]  # Sum: 100.000
 ```
 
-Result:
+## 💡 Real-World Examples
+
+### E-commerce Payment Splitting
 ```ruby
-=> [0.3334e1, 0.3333e1, 0.3333e1] # => [0.334, 0.333, 0.333]
+# Split a $99.99 order into 3 monthly payments
+payments = Splittable.division(value: 99.99, quantity: 3)
+# => [33.33, 33.33, 33.33]
+# Total: $99.99 ✅
 ```
 
+### Invoice Distribution
+```ruby
+# Distribute a $1,000.00 invoice across departments
+departments = ['Sales', 'Marketing', 'Support']
+amounts = [400.00, 350.00, 250.00]
 
-Using `normalize` method:
+normalized = Splittable.normalize(value: 1000.01, installments: amounts)
+# => [400.01, 350.00, 250.00]
+# Total: $1,000.01 ✅
+```
 
+### Subscription Billing
 ```ruby
-Splittable.normalize(value: 100.003, installments: [33.33, 21.433, 43.33333])
+# Annual subscription split into monthly payments
+monthly_payment = Splittable.division(value: 120.01, quantity: 12)
+# => [10.01, 10.00, 10.00, 10.00, 10.00, 10.00, 10.00, 10.00, 10.00, 10.00, 10.00, 10.00]
+# Total: $120.01 ✅
 ```
 
-Result: all values are truncated and them the difference is attributed in the first installment:
+## ⚠️ Error Handling
 
 ```ruby
-=> [0.3524e2, 0.2143e2, 0.4333e2] # => [35.24, 21.43, 43.33]
+# Invalid quantity (must be positive)
+Splittable.division(value: 100, quantity: 0)
+# => ArgumentError: quantity should be positive
+
+# Empty installments array
+Splittable.normalize(value: 100, installments: [])
+# => ArgumentError: installments should be a non-empty array
+
+# Nil installments
+Splittable.normalize(value: 100, installments: nil)
+# => ArgumentError: installments should be a non-empty array
 ```
 
-In this method, you have the same optional precision parameter:
-```ruby
-Splittable.normalize(value: 100, installments: [33.33333333, 33.33333333, 33.33333333], precision: 3)
+## 🛠️ Development
+
+### Setup
+```bash
+git clone https://github.com/m4rcelotoledo/splittable.git
+cd splittable
+bundle install
 ```
 
-Result:
-```ruby
-=> [0.33334e2, 0.33333e2, 0.33333e2] # => [33.334, 33.333, 33.333]
+### Running Tests
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage
+bundle exec rspec --format documentation
+
+# Run specific test file
+bundle exec rspec spec/splittable_spec.rb
 ```
 
-## Development
+### Code Quality
+```bash
+# Run RuboCop
+bundle exec rubocop
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+# Auto-fix RuboCop issues
+bundle exec rubocop -a
+```
+
+### Interactive Console
+```bash
+bundle exec bin/console
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`.
+### Project Structure
+```
+lib/
+├── splittable.rb           # Main module with public methods
+├── splittable/
+│   ├── version.rb         # Gem version
+│   ├── division.rb        # Division logic
+│   └── normalize.rb       # Normalization logic
+spec/
+├── spec_helper.rb         # Test configuration
+└── splittable_spec.rb     # Test cases
+```
 
-## To Release
+## 📦 Release Process
 
-Fill the `CHANGELOG.md` with relevants update.
+### Automatic Release
+1. Update version in `lib/splittable/version.rb`
+2. Update `CHANGELOG.md` with relevant changes
+3. Merge to `master` branch
+4. GitHub Actions will automatically publish to RubyGems
 
-To automatic release a new version, update the version number in `lib/splittable/version.rb` and merge it to `master` branch.
+### Manual Release
+```bash
+# Update version and changelog first
+bundle exec rake release
+```
 
-To manual release update the version and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## 🤝 Contributing
 
-## Contributing
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/m4rcelotoledo/splittable/blob/master/CONTRIBUTING.md.
 
-## Code of Conduct
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 📚 Code of Conduct
 
-Welcome on GitHub at https://github.com/m4rcelotoledo/splittable/blob/master/CODE_OF_CONDUCT.md.
+This project follows the [Contributor Covenant](https://github.com/m4rcelotoledo/splittable/blob/master/CODE_OF_CONDUCT.md) code of conduct.

data/lib/splittable/normalize.rb

@@ -2,6 +2,7 @@
 
 class Splittable::Normalize
   def initialize(value:, installments:, precision: 2)
+    check_installments_validity!(installments)
     @value = BigDecimal(value, 15).truncate(precision)
     @installments = installments.map { |installment| BigDecimal(installment.round(precision), 15) }
   end
@@ -17,4 +18,10 @@ class Splittable::Normalize
 
   attr_reader :value
   attr_accessor :installments
+
+  def check_installments_validity!(installments)
+    return if installments.is_a?(Array) && !installments.empty?
+
+    raise ArgumentError, 'installments should be a non-empty array'
+  end
 end

data/lib/splittable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Splittable
-  VERSION = '0.0.7'
+  VERSION = '0.0.9'
 end

data/splittable.gemspec

@@ -10,17 +10,19 @@ Gem::Specification.new do |spec|
 
   spec.license       = 'MIT'
 
-  spec.summary       = 'Calculate division and normalize parcels to use just cents.'
-  spec.description   = 'This gem solves the problem of several decimal places in divisions
-                        where the result must be presented in cents, that is converting the
-                        division result to only two decimal places and the difference is
-                        attributed to the first plot.'
+  spec.summary       = 'Split monetary values into equal installments with precise cent rounding.'
+  spec.description   = 'Splittable solves the common problem of dividing monetary values where ' \
+                       'the sum of rounded installments doesn\'t equal the original total. ' \
+                       'It ensures precise financial calculations by truncating values to the ' \
+                       'specified precision and attributing any difference to the first installment. ' \
+                       'Perfect for e-commerce payments, invoice distribution, and subscription billing.'
   spec.homepage      = 'https://github.com/m4rcelotoledo/splittable'
   spec.required_ruby_version = Gem::Requirement.new('>= 3.4.6')
 
   spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/m4rcelotoledo/splittable'
+  spec.metadata['source_code_uri'] = 'https://github.com/m4rcelotoledo/splittable/tree/master'
   spec.metadata['changelog_uri'] = 'https://github.com/m4rcelotoledo/splittable/blob/master/CHANGELOG.md'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/m4rcelotoledo/splittable/issues'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
@@ -30,4 +32,7 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'bigdecimal', '~> 3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: splittable
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.9
 platform: ruby
 authors:
 - Arthur Brandão
@@ -9,12 +9,26 @@ authors:
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: |-
-  This gem solves the problem of several decimal places in divisions
-                          where the result must be presented in cents, that is converting the
-                          division result to only two decimal places and the difference is
-                          attributed to the first plot.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Splittable solves the common problem of dividing monetary values where
+  the sum of rounded installments doesn't equal the original total. It ensures precise
+  financial calculations by truncating values to the specified precision and attributing
+  any difference to the first installment. Perfect for e-commerce payments, invoice
+  distribution, and subscription billing.
 email:
 - arthur_aebc@hotmail.com
 - marcelotoledo5000@gmail.com
@@ -52,8 +66,9 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/m4rcelotoledo/splittable
-  source_code_uri: https://github.com/m4rcelotoledo/splittable
+  source_code_uri: https://github.com/m4rcelotoledo/splittable/tree/master
   changelog_uri: https://github.com/m4rcelotoledo/splittable/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/m4rcelotoledo/splittable/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -71,5 +86,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Calculate division and normalize parcels to use just cents.
+summary: Split monetary values into equal installments with precise cent rounding.
 test_files: []