amounts 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b83ca37936b92cf689a865d0173dafd36e354f5e058fab07983efa436796b5d6
-  data.tar.gz: 3071b5b4bb06f46511a8dc45ec8d0f888b0863d61cfdbda363b313d806fb2f8a
+  metadata.gz: e8169dc3622ec4944cf900418dac855398a8f1ab1dcf59c07a7d839ace60e205
+  data.tar.gz: 6e2d1b8adcaae026bbe777be07f615ec7f7f2c8902e90c6b59e25a0210417b4b
 SHA512:
-  metadata.gz: 398502b610a4e35059307a3f2e895f119ba8456bdfeb22cf95a0976d37b21fcbbedc8f0ff201b90efa6faf5b9cb1f18e9dae2209cc838f8f6cc3929ea73d4d81
-  data.tar.gz: d26be5a7c85fd002ddc3435880d25bebae7b7a29007295b064efb2bcfe0eacb0d3959044c499db1621e7e8e1b238b311c546dc24c591e8ccfc02b61e4865e281
+  metadata.gz: 8afe516fe8c082748e669faa6db55f780a59b8b51948780fb5c23615ac417c830227a447393f5c33393249bbe4b10b40012ee8e090109cfeaf6ca366b197c87e
+  data.tar.gz: 984d7e60a58d97dd6b3fed6ba40845bcaa66f2e6bc72e3a2bf36e80880886743ae38217f26efd84a048c7b31d2682b11d993620bd97b6c9dd8901f92e5c29c0c

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.0.7 - 2026-05-03
+
+### Fixed
+
+- `Display#to_s` now formats the decimal value using `ui_decimals`, matching
+  `ui(decorated: false)`. Previously `to_s` used raw `BigDecimal#to_s("F")`
+  which dropped trailing zeros (`USDC|1.5` instead of `USDC|1.50`), defeating
+  the purpose of the compact format carrying the display-ready amount.
+- `Amount#as_json` returns the compact string (`to_s`), preventing a
+  `SystemStackError` (stack level too deep) when calling `as_json` or `to_json`
+  on an Amount in Rails. The circular reference between `Display` and `Amount`
+  caused ActiveSupport's default recursive serialization to overflow.
+
+## 0.0.6 - 2026-04-28
+
+### Added
+
+- `trim_zeros` option for `Amount.register` strips trailing zeros from `ui`
+  output. Defaults to `false` so fiat currencies keep fixed decimals (`$1.50`).
+  Set `true` for tokens with high precision to get clean output (`1.5 SOL`
+  instead of `1.5000 SOL`). Display units can override via
+  `display_units: { gram: { ..., trim_zeros: false } }`.
+- `Amount#ui(trim_zeros:)` call-site override. Pass `true` or `false` to
+  override the registry and display-unit settings for a single render.
+  Precedence: call-site > display unit spec > registry default.
+- Railtie `initializer` block that auto-requires `amount/active_record` in
+  Rails apps. `has_amount` and `t.amount` are now available without manual
+  `require` statements — Bundler's auto-require of the `amounts` gem handles
+  everything.
+
 ## 0.0.5 - 2026-04-26
 
 ### Added

data/README.md

@@ -1,9 +1,14 @@
+> **You are reading the gem package readme.** The repository also contains
+> [`site/`](../site) (the docs site) and [`demo/`](../demo) (a Rails
+> case-study app that exercises every feature). See the
+> [root README](../README.md) for the layout overview.
+
 # 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)
+[![License](https://img.shields.io/github/license/zarpay/amounts)](https://github.com/zarpay/amounts/blob/main/gem/LICENSE.txt)
 [![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.1-red)](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.
@@ -32,6 +37,10 @@ Load the Rails adapter only when needed:
 require "amount/active_record"
 ```
 
+If the gem is bundled into a Rails app, the Rails-only generator hooks are
+loaded through the adapter railtie. You do not need a separate top-level
+generator require.
+
 ## Quickstart
 
 ```ruby
@@ -235,6 +244,22 @@ Load the adapter explicitly:
 require "amount/active_record"
 ```
 
+### Preset registry generator
+
+In a Rails app, you can generate a starter initializer with curated baskets of
+registered symbols:
+
+```bash
+bin/rails generate amounts:registry fiat
+bin/rails generate amounts:registry metals
+bin/rails generate amounts:registry crypto
+bin/rails generate amounts:registry all
+```
+
+The generator writes `config/initializers/amounts.rb` with registration
+metadata only. It intentionally does not register default conversion rates,
+because those are directional and application-specific.
+
 ### Migration DSL
 
 ```ruby

data/lib/amount/active_record/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class Amount
+  module ActiveRecord
+    class Railtie < ::Rails::Railtie
+      initializer "amount.active_record" do
+        require "amount/active_record"
+      end
+
+      generators do
+        require_relative "../../../generators/amount/active_record/registry_generator"
+      end
+    end
+  end
+end

data/lib/amount/display.rb

@@ -21,23 +21,29 @@ class Amount
     # @param decorated [Boolean] when `false`, omit the display symbol and
     #   return just the rounded number. Useful when the caller renders the
     #   currency label separately (e.g. in a column header or a chip).
+    # @param trim_zeros [Boolean, nil] strip trailing zeros from the formatted
+    #   number. When `nil` (the default), falls back to the display unit's
+    #   setting, then the registry entry's setting. An explicit `true` or
+    #   `false` overrides both.
     # @return [String]
     # @example
     #   Amount.usdc("1.50").ui                       # => "$1.50"
     #   Amount.usdc("1.50").ui(decorated: false)     # => "1.50"
     #   Amount.gold("1").ui(unit: :gram)             # => "31.10 g"
     #   Amount.gold("1").ui(unit: :gram, decorated: false)  # => "31.10"
-    def ui(unit: nil, direction: :floor, decorated: true)
+    #   Amount.sol("2.5").ui(trim_zeros: true)       # => "2.5 SOL"
+    def ui(unit: nil, direction: :floor, decorated: true, trim_zeros: nil)
       if unit
-        render_display_unit(unit, direction, decorated:)
+        render_display_unit(unit, direction, decorated:, trim_zeros:)
       else
-        render_default(direction, decorated:)
+        render_default(direction, decorated:, trim_zeros:)
       end
     end
 
     # @return [String]
     def to_s
-      "#{@entry.symbol}|#{@amount.decimal.to_s("F")}"
+      rounded = round(@amount.decimal, @entry.ui_decimals, :floor)
+      "#{@entry.symbol}|#{format_number(rounded, @entry.ui_decimals, false)}"
     end
 
     # @param unit [Symbol]
@@ -49,20 +55,20 @@ class Amount
 
     private
 
-    def render_default(direction, decorated:)
+    def render_default(direction, decorated:, trim_zeros:)
       rounded = round(@amount.decimal, @entry.ui_decimals, direction)
-      formatted = format("%.#{@entry.ui_decimals}f", rounded)
+      formatted = format_number(rounded, @entry.ui_decimals, resolve_trim(trim_zeros))
       return formatted unless decorated
 
       apply_symbol(formatted, @entry.display_symbol, @entry.display_position)
     end
 
-    def render_display_unit(unit, direction, decorated:)
+    def render_display_unit(unit, direction, decorated:, trim_zeros:)
       spec = fetch_display_unit(unit)
       scaled = @amount.decimal * Amount.coerce_decimal(spec[:scale])
       decimals = spec[:ui_decimals] || @entry.ui_decimals
       rounded = round(scaled, decimals, direction)
-      formatted = format("%.#{decimals}f", rounded)
+      formatted = format_number(rounded, decimals, resolve_trim(trim_zeros, spec))
       return formatted unless decorated
 
       apply_symbol(
@@ -90,6 +96,18 @@ class Amount
       truncated / factor
     end
 
+    def format_number(value, decimals, trim)
+      str = format("%.#{decimals}f", value)
+      trim ? str.sub(/(\.\d*?)0+\z/, '\1').chomp('.') : str
+    end
+
+    def resolve_trim(call_site, spec = nil)
+      return call_site unless call_site.nil?
+      return spec[:trim_zeros] if spec&.key?(:trim_zeros)
+
+      @entry.trim_zeros
+    end
+
     def apply_symbol(str, symbol, position)
       return str if symbol.nil? || symbol.empty?
 

data/lib/amount/registry.rb

@@ -35,6 +35,7 @@ class Amount
       :display_units,
       :default_display,
       :amount_class,
+      :trim_zeros,
       keyword_init: true
     )
 
@@ -60,6 +61,7 @@ class Amount
     # @param ui_decimals [Integer] decimals displayed by default UI formatting
     # @param display_units [Hash, nil] optional display-only scaling definitions
     # @param default_display [Symbol, nil] optional default display unit key
+    # @param trim_zeros [Boolean] strip trailing zeros from UI output
     # @param class [Class, nil] optional custom `Amount` subclass
     # @return [void]
     # @raise [AlreadyRegistered] if the symbol is already registered or the
@@ -73,7 +75,7 @@ class Amount
     #     ui_decimals: 2
     def register(symbol, decimals:, display_symbol: symbol.to_s, display_position: :suffix,
                  ui_decimals: decimals, display_units: nil, default_display: nil,
-                 class: nil)
+                 trim_zeros: false, class: nil)
       raise ArgumentError, "symbol must not be blank" if symbol.nil? || symbol.to_s.empty?
 
       symbol = symbol.to_sym
@@ -92,7 +94,8 @@ class Amount
           ui_decimals:,
           display_units:,
           default_display:,
-          amount_class: binding.local_variable_get(:class) || Amount
+          amount_class: binding.local_variable_get(:class) || Amount,
+          trim_zeros:
         )
 
         @entries[symbol] = entry

data/lib/amount/serialization.rb

@@ -50,5 +50,10 @@ class Amount
         symbol: @symbol.to_s
       }
     end
+
+    # @return [String]
+    def as_json(*)
+      to_s
+    end
   end
 end

data/lib/amount/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Amount
-  VERSION = "0.0.5"
+  VERSION = "0.0.7"
 end

data/lib/amounts.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Thin gem-name entrypoint for Bundler auto-require.
+# Core users should still require "amount" directly.
+require_relative "amount"
+
+begin
+  require "rails/railtie"
+  require_relative "amount/active_record/railtie"
+rescue LoadError
+  nil
+end

data/lib/generators/amount/active_record/registry_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+class Amount
+  module ActiveRecord
+    class RegistryGenerator < ::Rails::Generators::Base
+      namespace "amounts:registry"
+
+      source_root File.expand_path("templates", __dir__)
+      VALID_PRESETS = %i[fiat metals crypto all].freeze
+
+      argument :preset, type: :string, banner: "fiat|metals|crypto|all"
+
+      def create_initializer
+        template "registry.rb.tt", "config/initializers/amounts.rb"
+      end
+
+      private
+
+      def preset_key
+        @preset_key ||= begin
+          key = preset.to_s.downcase.to_sym
+          if VALID_PRESETS.include?(key)
+            key
+          else
+            raise ::Thor::Error,
+                  "unknown preset #{preset.inspect}; choose one of: fiat, metals, crypto, all"
+          end
+        end
+      end
+
+      def preset_categories
+        preset_key == :all ? %i[fiat metals crypto] : [preset_key]
+      end
+
+      def preset_name
+        preset_key.to_s
+      end
+
+      def registered_symbols
+        @registered_symbols ||= preset_body.scan(/Amount\.register :([A-Z0-9_]+),/).flatten
+      end
+
+      def registry_guard_symbol
+        registered_symbols.first
+      end
+
+      def preset_body
+        @preset_body ||= File.read(
+          File.join(self.class.source_root, "presets", "#{preset_name}.fragment")
+        ).chomp
+      end
+
+      def preset_source_label
+        preset_name
+      end
+    end
+  end
+end