amounts 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 92c0c2ebae750b68a79648157559ca2fe6c0c67d5892a83a31beb36e15936648
+  data.tar.gz: c5b8661d2b980a48a655407fdababfe8428bdd978e1fd7a6d52a6d8a554be287
+SHA512:
+  metadata.gz: 2bc8b173facf22c287824621e15f02102cff7cb4e096789e35945a77418815b6027cf9637e0e86bcfc3c427946b1b0aa3f544b01cc338550503aa50b2fa34c7e
+  data.tar.gz: e4cf1297e4c987f8121d6a9f35f76bc9e668a5f22b130531022428ec0443d019f9ad7d637f098c34be26edaa78d1f105479d935765d3353ef9f42cf8199e3936

data/.rubocop.yml

@@ -0,0 +1,89 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 3.1
+  UseCache: false
+  Exclude:
+    - "vendor/**/*"
+    - "site/**/*"
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+  Exclude:
+    - "amounts.gemspec"
+    - "test/**/*"
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  Enabled: false
+
+Lint/RedundantRequireStatement:
+  Enabled: false
+
+Naming/RescuedExceptionsVariableName:
+  Enabled: false
+
+Naming/BinaryOperatorParameterName:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/PredicateName:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/RedundantParentheses:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+Style/SoleNestedConditional:
+  Enabled: false
+
+Style/RedundantConstantBase:
+  Enabled: false
+
+Layout/SpaceAroundKeyword:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.0.1 - 2026-04-25
+
+- Initial release.
+- Added the `Amount` core value object with atomic integer storage.
+- Added directional default-rate conversion for cross-type arithmetic and comparison.
+- Added explicit `[parts, remainder]` semantics for `split` and `allocate`.
+- Added optional ActiveRecord integration via `require "amount/active_record"`.

data/Gemfile

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest", ">= 5.0", "< 6.0"
+gem "rake", ">= 13.0"
+gem "rspec", ">= 3.13"
+
+group :development do
+  gem "irb", ">= 1.13"
+end
+
+group :quality do
+  gem "rubocop", "~> 1.63.0"
+end
+
+group :active_record do
+  gem "activerecord", ">= 7.1", "< 8.0"
+  gem "pg", ">= 1.5"
+  gem "railties", ">= 7.1", "< 8.0"
+  gem "sqlite3", ">= 2.0"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seb Scholl
+
+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,402 @@
+# amounts
+
+[![Gem Version](https://img.shields.io/gem/v/amounts)](https://rubygems.org/gems/amounts)
+[![CI](https://github.com/zarpay/amounts/actions/workflows/ci.yml/badge.svg)](https://github.com/zarpay/amounts/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/v/release/zarpay/amounts)](https://github.com/zarpay/amounts/releases)
+[![License](https://img.shields.io/github/license/zarpay/amounts)](https://github.com/zarpay/amounts/blob/main/LICENSE.txt)
+[![Ruby](https://img.shields.io/gem/required-ruby-version/amounts)](https://rubygems.org/gems/amounts)
+
+`amounts` is a Ruby gem for precise quantities of fungible things: money, crypto tokens, commodities, inventory units, points, and similar value-like amounts. It stores every value as an arbitrary-precision atomic `Integer`, keeps type identity in a registry, rejects accidental cross-type math unless an explicit directional rate exists, and offers an optional ActiveRecord adapter without making Rails part of the core runtime.
+
+## Installation
+
+```bash
+bundle add amounts
+```
+
+or:
+
+```bash
+gem install amounts
+```
+
+The library entrypoint is:
+
+```ruby
+require "amount"
+```
+
+Load the Rails adapter only when needed:
+
+```ruby
+require "amount/active_record"
+```
+
+## Quickstart
+
+```ruby
+require "amount"
+
+Amount.register :USDC,
+  decimals: 6,
+  display_symbol: "$",
+  display_position: :prefix,
+  ui_decimals: 2
+
+Amount.register :USD,
+  decimals: 2,
+  display_symbol: "$",
+  display_position: :prefix,
+  ui_decimals: 2
+
+Amount.register_default_rate :USD, :USDC, 1
+
+usdc = Amount.usdc("10.00")
+usd = Amount.new("5.00", :USD)
+
+(usdc + usd).ui
+# => "$15.00"
+```
+
+## Concepts
+
+### Atomic vs. UI values
+
+`Amount` stores values as atomic integers in the smallest registered unit for that type.
+
+```ruby
+Amount.register :USDC, decimals: 6
+
+amount = Amount.new("1.5", :USDC)
+amount.atomic
+# => 1500000
+
+amount.decimal.to_s("F")
+# => "1.5"
+```
+
+Construction rules:
+
+- `Integer` defaults to atomic units
+- `String` defaults to UI decimal values
+- `Float`, `BigDecimal`, and `Rational` are treated as decimal UI values
+- `from: :atomic`, `:ui`, or `:float` overrides inference
+- registering `:USDC` also defines `Amount.usdc(...)` when the symbol is a valid Ruby method name
+
+### Registry
+
+The registry defines the full behavior of each type:
+
+```ruby
+Amount.register :GOLD,
+  decimals: 8,
+  display_symbol: "oz t",
+  display_position: :suffix,
+  ui_decimals: 4,
+  display_units: {
+    oz_t: { scale: 1, symbol: "oz t", ui_decimals: 4 },
+    gram: { scale: "31.1035", symbol: "g", ui_decimals: 2 }
+  },
+  default_display: :oz_t
+```
+
+Boot-time registry configuration can be frozen once setup is complete:
+
+```ruby
+Amount.registry.lock!
+Amount.registry.locked? # => true
+```
+
+### Display units are not conversions
+
+Display units scale presentation only:
+
+```ruby
+gold = Amount.new("1.5", :GOLD)
+gold.ui(unit: :gram)
+# => "46.65 g"
+```
+
+The value is still `:GOLD`.
+
+### Directional conversion rates
+
+Cross-type `+`, `-`, and `<=>` only work when the right-hand side can be converted into the left-hand side using a registered default rate.
+
+```ruby
+Amount.register_default_rate :USD, :USDC, 1
+
+Amount.new("10", :USDC) + Amount.new("5", :USD)
+# => #<Amount USDC|15.0>
+```
+
+Rates are directional. `:USD -> :USDC` does not imply `:USDC -> :USD`.
+
+### Split vs. division
+
+Scalar division returns one scaled amount:
+
+```ruby
+Amount.new("10", :USDC) / 2
+# => #<Amount USDC|5.0>
+```
+
+`split` and `allocate` return explicit remainders:
+
+```ruby
+parts, remainder = Amount.new(10, :LOGS).split(3)
+parts.map(&:atomic)  # => [3, 3, 3]
+remainder.atomic     # => 1
+```
+
+Negative values follow the same rules with rounding toward zero:
+
+```ruby
+parts, remainder = Amount.new(-10, :LOGS).allocate([1, 1, 1])
+parts.map(&:atomic)  # => [-3, -3, -3]
+remainder.atomic     # => -1
+```
+
+## Core API
+
+### Construction
+
+```ruby
+Amount.new(1_500_000, :USDC)
+Amount.new("1.50", :USDC)
+Amount.usdc("1.50")
+Amount.parse("USDC|1.50")
+Amount.load(atomic: 1_500_000, symbol: :USDC)
+```
+
+### Math
+
+```ruby
+a = Amount.new("10", :USDC)
+b = Amount.new("2", :USDC)
+
+a + b
+a - b
+a * 2
+a / 2
+a / b
+```
+
+`Amount * Amount` raises `Amount::TypeMismatch`.
+
+### Comparison
+
+```ruby
+Amount.new("1", :USDC) < Amount.new("2", :USDC)
+```
+
+Cross-type comparison returns `nil` when no directional rate exists.
+
+### Conversion
+
+```ruby
+Amount.new("10", :USDC).to(:USD, rate: "1")
+```
+
+### Display
+
+```ruby
+amount.formatted
+amount.ui
+amount.ui(direction: :ceil)
+amount.ui(unit: :gram)
+amount.in_unit(:gram)
+```
+
+### Serialization
+
+```ruby
+payload = amount.to_h
+Amount.load(payload)
+```
+
+## Registry API
+
+```ruby
+Amount.register(...)
+Amount.register_default_rate(:USD, :USDC, "1")
+Amount.registry.lookup(:USDC)
+Amount.registry.symbols
+Amount.registry.clear!
+Amount.registry.lock!
+Amount.registry.locked?
+```
+
+## ActiveRecord Integration
+
+Load the adapter explicitly:
+
+```ruby
+require "amount/active_record"
+```
+
+### Migration DSL
+
+```ruby
+create_table :holdings do |t|
+  t.amount :amount
+  t.amount :default_amount, default: "USDC|1.25"
+  t.amount :fee, symbol: :SOL
+  t.amount :reserve, precision: 40
+end
+```
+
+This generates:
+
+- `*_atomic` as `numeric(78, 0)` by default
+- `*_symbol` as `string(10)` for multi-symbol amounts
+- `precision:` override support for the atomic column
+
+### Model Macro
+
+```ruby
+class Holding < ApplicationRecord
+  has_amount :amount
+  has_amount :fee, symbol: :SOL
+end
+
+holding = Holding.new
+holding.amount = "USDC|1.50"
+holding.fee = 0.25
+```
+
+Writers accept:
+
+- `Amount`
+- `String` like `"USDC|1.50"`
+- `Hash` payloads
+- raw numeric values for fixed-symbol attributes only
+
+Scopes:
+
+```ruby
+Holding.where_amount("USDC|1.50")
+Holding.where_amount_gt("USDC|1.00")
+Holding.where_amount_gte("USDC|1.00")
+Holding.where_amount_lt("USDC|5.00")
+Holding.where_amount_lte("USDC|5.00")
+Holding.where_amount_between("USDC|1.00", "USDC|5.00")
+Holding.amount_in(:USDC)
+```
+
+Suggested check constraint for multi-symbol amounts:
+
+```sql
+ALTER TABLE holdings ADD CONSTRAINT amount_both_or_neither
+  CHECK ((amount_atomic IS NULL) = (amount_symbol IS NULL));
+```
+
+### SQLite Note
+
+The adapter supports SQLite for general integration tests and development, but SQLite does not preserve `DECIMAL(78,0)` values above 64-bit range exactly under ActiveRecord's default numeric handling. For exact wei-scale persistence, use PostgreSQL or another database with true arbitrary-precision numeric behavior.
+
+### PostgreSQL Dummy App
+
+A minimal Rails dummy app lives under `test/dummy` for PostgreSQL-backed integration testing.
+
+Run the default suite:
+
+```bash
+bundle exec rake
+```
+
+Run the PostgreSQL integration test explicitly:
+
+```bash
+AMOUNTS_POSTGRES_URL=postgresql://localhost/amounts_test \
+  bundle exec ruby -Ilib:test test/postgresql_integration_test.rb
+```
+
+If `AMOUNTS_POSTGRES_URL` is not set, the PostgreSQL test file skips cleanly.
+
+Open a console against the dummy app:
+
+```bash
+AMOUNTS_POSTGRES_URL=postgresql://localhost/amounts_test \
+  test/dummy/bin/rails console
+```
+
+## Testing
+
+The gem ships opt-in RSpec matchers for app-level specs:
+
+```ruby
+# spec/spec_helper.rb
+require "amount/rspec"
+require "amount/active_record/rspec"
+```
+
+Core matcher examples:
+
+```ruby
+expect(holding.amount).to eq_amount("USDC|1.50")
+expect(holding.amount).to be_amount_of(:USDC)
+expect(holding.amount).to be_positive_amount
+expect(converted).to be_approximately_amount(:GOLD, "0.0042", within: "0.0001")
+```
+
+ActiveRecord matcher examples:
+
+```ruby
+expect(holding).to have_amount_column(:amount, "USDC|1.50")
+expect(Holding.group(:amount_symbol).sum(:amount_atomic))
+  .to match_amounts(USDC: "10500.00", SOL: "12.5")
+```
+
+The gem's own test suite runs both Minitest and RSpec:
+
+```bash
+bundle exec rake
+bundle exec rspec
+```
+
+## Releases
+
+RubyGems publishing is intended to run from GitHub Releases using RubyGems trusted publishing.
+
+Workflow:
+
+- create and push a version tag such as `v0.0.1`
+- publish a GitHub Release for that tag
+- GitHub Actions runs `.github/workflows/release.yml`
+- the workflow verifies the test suite and publishes the gem to RubyGems.org
+
+RubyGems setup:
+
+- on RubyGems.org, configure a trusted publisher for the `amounts` gem
+- repository owner: `zarpay`
+- repository name: `amounts`
+- workflow filename: `release.yml`
+- GitHub Actions environment: `release`
+
+This uses OIDC trusted publishing, so no RubyGems API token needs to be stored in GitHub Actions. See the official RubyGems trusted publishing guide:
+
+- https://guides.rubygems.org/trusted-publishing/
+
+## Compared to `money`
+
+`money` is excellent for fiat currency workflows and has a mature ecosystem. `amounts` takes a different tradeoff:
+
+| Concern | `money` | `amounts` |
+| --- | --- | --- |
+| Internal storage | integer subunits | arbitrary-precision atomic integer |
+| Non-fiat tokens | awkward at high decimals | first-class |
+| Cross-type math | money-oriented exchange features | explicit directional rates only |
+| Display units | currency formatting | arbitrary per-type display scaling |
+| Rails dependency | common usage path | optional adapter only |
+
+## Contributing
+
+1. Install dependencies with `bin/setup`
+2. Run `bundle exec rake`
+3. Keep the core gem Rails-agnostic
+4. Add tests for behavioral changes
+
+## License
+
+Released under the MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+Rake::TestTask.new(:test) do |task|
+  task.libs << "lib"
+  task.libs << "test"
+  task.pattern = "test/**/*_test.rb"
+end
+
+RuboCop::RakeTask.new(:rubocop)
+RSpec::Core::RakeTask.new(:spec)
+
+task lint: %i[rubocop]
+
+task default: %i[test spec rubocop]

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "amount"
+require "irb"
+
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bundle install

data/lib/amount/active_record/amount_validator.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    # Validates model-level business rules for `has_amount` attributes.
+    #
+    # Structural integrity is still handled by `has_amount` itself. This
+    # validator adds declarative Rails validations such as symbol checks and
+    # comparison constraints.
+    #
+    # @example Requiring a specific symbol
+    #   class Holding < ApplicationRecord
+    #     has_amount :amount
+    #     validates :amount, amount: { symbol: :USDC }
+    #   end
+    #
+    # @example Applying numeric thresholds to a fixed-symbol amount
+    #   class FeeSchedule < ApplicationRecord
+    #     has_amount :fee, symbol: :SOL
+    #     validates :fee, amount: { greater_than_or_equal_to: 0 }
+    #   end
+    class AmountValidator < ::ActiveModel::EachValidator
+      COMPARATORS = {
+        greater_than: :>,
+        greater_than_or_equal_to: :>=,
+        less_than: :<,
+        less_than_or_equal_to: :<=
+      }.freeze
+
+      def validate_each(record, attribute, value)
+        return if pending_assignment_error?(record, attribute)
+        return if value.nil?
+
+        validate_amount_instance(record, attribute, value)
+        validate_symbol(record, attribute, value)
+        validate_comparators(record, attribute, value)
+      end
+
+      private
+
+      def validate_amount_instance(record, attribute, value)
+        return if value.is_a?(::Amount)
+
+        record.errors.add(attribute, "must be an Amount")
+      end
+
+      def validate_symbol(record, attribute, value)
+        expected_symbol = options[:symbol]&.to_sym
+        return unless expected_symbol
+        return if value.symbol == expected_symbol
+
+        record.errors.add(attribute, "must have symbol #{expected_symbol}")
+      end
+
+      def validate_comparators(record, attribute, value)
+        COMPARATORS.each do |option_name, operator|
+          next unless options.key?(option_name)
+
+          other = coerce_comparison_amount(record, attribute, options.fetch(option_name))
+          next unless other
+
+          compare_amounts(record, attribute, value, operator, other, option_name)
+        rescue ::Amount::Error, ArgumentError => error
+          record.errors.add(attribute, "has invalid #{option_name} constraint: #{error.message}")
+        end
+      end
+
+      def coerce_comparison_amount(record, attribute, candidate)
+        definition = fetch_definition(record, attribute)
+        return candidate if candidate.is_a?(::Amount)
+
+        definition.type.cast(candidate)
+      end
+
+      def compare_amounts(record, attribute, value, operator, other, option_name)
+        comparison = value <=> other
+        if comparison.nil?
+          record.errors.add(attribute, "cannot compare #{value.symbol} to #{other.symbol} for #{option_name}")
+          return
+        end
+
+        return if comparison.public_send(operator, 0)
+
+        record.errors.add(attribute, failure_message(option_name, other))
+      end
+
+      def failure_message(option_name, other)
+        case option_name
+        when :greater_than
+          "must be greater than #{other}"
+        when :greater_than_or_equal_to
+          "must be greater than or equal to #{other}"
+        when :less_than
+          "must be less than #{other}"
+        when :less_than_or_equal_to
+          "must be less than or equal to #{other}"
+        else
+          "is invalid"
+        end
+      end
+
+      def fetch_definition(record, attribute)
+        record.class.amount_attribute_definitions.fetch(attribute.to_sym)
+      rescue KeyError
+        raise ArgumentError, "#{record.class.name}##{attribute} is not declared with has_amount"
+      end
+
+      def pending_assignment_error?(record, attribute)
+        record.send(:pending_amount_assignment_errors).key?(attribute.to_sym)
+      end
+    end
+  end
+end
+
+::AmountValidator = Amount::ActiveRecord::AmountValidator unless defined?(::AmountValidator)