timeprice 0.1.2 → 0.3.0

data/lib/timeprice/inflation.rb

@@ -2,6 +2,7 @@
 
 require_relative "errors"
 require_relative "data_loader"
+require_relative "cpi_lookup"
 
 module Timeprice
   # Value object returned by Inflation.adjust.
@@ -14,85 +15,60 @@ module Timeprice
   InflationResult = Data.define(
     :amount, :original_amount, :from, :to, :country,
     :from_index, :to_index, :granularity
-  )
+  ) do
+    # The country's primary currency (e.g. "USD" for "US"). Falls back to the
+    # uppercased country code if the country isn't in the supported map —
+    # callers can still render *some* unit rather than crashing.
+    def country_currency_label
+      require_relative "supported"
+      Supported.currency_for_country(country) || country.to_s.upcase
+    end
+  end
 
+  # CPI-based inflation adjustment for the {Supported::COUNTRIES} list.
   module Inflation
     module_function
 
     # Adjust `amount` from date `from` to date `to` using country CPI.
     #
     # Dates accept "YYYY" or "YYYY-MM".
+    #
+    # @param amount  [Numeric]
+    # @param from    [String] source date ("YYYY" or "YYYY-MM")
+    # @param to      [String] target date ("YYYY" or "YYYY-MM")
+    # @param country [String] country code (see {Supported::COUNTRIES})
+    # @return [InflationResult]
+    # @raise [UnsupportedCountry] if `country` is not supported
+    # @raise [DataNotFound]       if no CPI data covers the requested period
     def adjust(amount:, from:, to:, country:)
-      data = DataLoader.load_cpi(country)
-      from_index, from_gran = lookup_index(data, from)
-      to_index,   to_gran   = lookup_index(data, to)
+      lookup = CpiLookup.new(DataLoader.load_cpi(country))
+      from_point = lookup.at(from)
+      to_point   = lookup.at(to)
 
-      ratio = to_index.to_f / from_index
+      ratio = to_point.value.to_f / from_point.value
       InflationResult.new(
         amount: amount.to_f * ratio,
         original_amount: amount.to_f,
         from: from,
         to: to,
         country: country.to_s.upcase,
-        from_index: from_index,
-        to_index: to_index,
-        granularity: merge_granularity(from_gran, to_gran)
+        from_index: from_point.value,
+        to_index: to_point.value,
+        granularity: merge_granularity(from_point.granularity, to_point.granularity)
       )
     end
 
     # Inflation rate as decimal (e.g. 0.42 = 42%).
+    #
+    # @param from    [String]
+    # @param to      [String]
+    # @param country [String]
+    # @return [Float] decimal rate (positive means inflation, negative deflation)
     def rate(from:, to:, country:)
       result = adjust(amount: 1.0, from: from, to: to, country: country)
       result.amount - 1.0
     end
 
-    # Returns [index_value, granularity_symbol]
-    def lookup_index(data, key)
-      key = key.to_s
-      monthly = data["monthly"] || {}
-      annual  = data["annual"]  || {}
-
-      case key
-      when /\A\d{4}-\d{2}\z/
-        if monthly.key?(key)
-          [monthly[key], :monthly]
-        else
-          year = key[0, 4]
-          raise DataNotFound, missing_cpi_message(key, data, monthly, annual) unless annual.key?(year)
-
-          [annual[year], :annual]
-
-        end
-      when /\A\d{4}\z/
-        if annual.key?(key)
-          [annual[key], :annual]
-        else
-          months = monthly.select { |k, _| k.start_with?("#{key}-") }
-          raise DataNotFound, missing_cpi_message(key, data, monthly, annual) if months.empty?
-
-          avg = months.values.sum.to_f / months.size
-          [avg, :annual_from_monthly_avg]
-        end
-      else
-        raise ArgumentError, "Invalid date format: #{key.inspect} (use YYYY or YYYY-MM)"
-      end
-    end
-
-    def missing_cpi_message(key, data, monthly, annual)
-      country = data["country"]
-      ranges = []
-      if monthly.any?
-        ks = monthly.keys.sort
-        ranges << "monthly #{ks.first}..#{ks.last}"
-      end
-      if annual.any?
-        ks = annual.keys.sort
-        ranges << "annual #{ks.first}..#{ks.last}"
-      end
-      hint = ranges.empty? ? "" : " (supported: #{ranges.join(", ")})"
-      "No CPI data for #{key.inspect} in #{country}#{hint}"
-    end
-
     # If either end fell back to annual_from_monthly_avg, propagate that label;
     # else if either is annual, propagate :annual; else :monthly.
     def merge_granularity(a, b)

data/lib/timeprice/point.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Timeprice
+  # A (currency, date) pair used as input to {Timeprice.compare}.
+  #
+  # The library accepts either a Point or a 2-element array. Arrays may be
+  # ordered either way (`["USD", "2010"]` or `["2010", "USD"]`) — the year
+  # and currency are detected by shape. This mirrors what the CLI already
+  # tolerates and removes the only "which slot is which?" footgun.
+  #
+  # @example
+  #   Timeprice::Point.new(currency: "USD", date: "2010")
+  #   Timeprice::Point.coerce(["USD", "2010"])
+  #   Timeprice::Point.coerce(["2010", "USD"])
+  Point = Data.define(:currency, :date) do
+    # Coerce input into a Point. Accepts:
+    #   - {Point} (returned as-is)
+    #   - 2-element Array of [currency, date] in either order
+    #
+    # @param input [Point, Array]
+    # @return [Point]
+    # @raise [ArgumentError] if shape can't be recognised
+    def self.coerce(input)
+      case input
+      in Point
+        input
+      in [_, _]
+        a, b = input.map(&:to_s)
+        currency = [a, b].find { |s| s.match?(/\A[A-Za-z]{3}\z/) }
+        date     = [a, b].find { |s| s.match?(/\A\d{4}(-\d{2}(-\d{2})?)?\z/) }
+        raise ArgumentError, malformed_pair_message(input) if currency.nil? || date.nil?
+
+        new(currency: currency.upcase, date: date)
+      else
+        raise ArgumentError, "Expected Timeprice::Point or [currency, date] tuple, got #{input.inspect}"
+      end
+    end
+
+    def self.malformed_pair_message(input)
+      "Could not detect currency + date in #{input.inspect} " \
+        "(expected a 3-letter currency and a YYYY[-MM[-DD]] date)"
+    end
+
+    # Resolve `date` to a full YYYY-MM-DD for FX lookup.
+    #
+    # Coarser grains anchor to a representative day:
+    #   - "YYYY"    → mid-year (YYYY-06-30)
+    #   - "YYYY-MM" → mid-month (YYYY-MM-15)
+    #   - "YYYY-MM-DD" → passes through
+    #
+    # @return [String]
+    # @raise [ArgumentError] if `date` doesn't match any supported shape
+    def fx_anchor_date
+      case date.to_s
+      when /\A\d{4}\z/         then "#{date}-06-30"
+      when /\A\d{4}-\d{2}\z/   then "#{date}-15"
+      when /\A\d{4}-\d{2}-\d{2}\z/ then date.to_s
+      else raise ArgumentError, "Invalid date for Point: #{date.inspect}"
+      end
+    end
+  end
+end

data/lib/timeprice/sources/coverage.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../data_loader"
+
+module Timeprice
+  module Sources
+    # Computes coverage strings for bundled data sources at runtime. All
+    # filesystem reads happen here so the Sources attribution registry stays
+    # a pure data table.
+    module Coverage
+      module_function
+
+      # @param src [Hash] one entry from Sources::ATTRIBUTIONS
+      # @return [String]
+      def for(src)
+        case src[:kind]
+        when "cpi" then cpi(src[:country])
+        when "fx"  then fx(src[:id])
+        else "n/a"
+        end
+      rescue StandardError => e
+        "(coverage unavailable: #{e.message})"
+      end
+
+      def cpi(country)
+        data = DataLoader.load_cpi(country)
+        monthly = (data["monthly"] || {}).keys.sort
+        annual  = (data["annual"]  || {}).keys.sort
+        parts = []
+        parts << "monthly #{monthly.first}..#{monthly.last} (#{monthly.size})" unless monthly.empty?
+        parts << "annual #{annual.first}..#{annual.last} (#{annual.size})" unless annual.empty?
+        parts.join(", ")
+      end
+
+      def fx(id)
+        years = fx_years
+        return "no data" if years.empty?
+
+        id == "fx_vnd" ? vnd_summary(years) : ecb_summary(years)
+      end
+
+      def fx_years
+        Dir[File.join(fx_root, "*.json")].map { |f| File.basename(f, ".json").to_i }.sort
+      end
+
+      def vnd_summary(years)
+        with_vnd = years.select { |y| year_has_currency?(y, %w[VND]) }
+        return "no VND data" if with_vnd.empty?
+
+        "USD↔VND #{with_vnd.first}..#{with_vnd.last}"
+      end
+
+      def ecb_summary(years)
+        ecb_years = years.select { |y| year_has_currency?(y, %w[EUR GBP JPY]) }
+        return "no ECB data" if ecb_years.empty?
+
+        "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
+      end
+
+      def year_has_currency?(year, codes)
+        rates = JSON.parse(File.read(File.join(fx_root, "#{year}.json")))["rates"]
+        rates.any? { |_, v| v.keys.intersect?(codes) }
+      end
+
+      def fx_root
+        File.join(DataLoader.data_root, "fx", "usd")
+      end
+    end
+  end
+end

data/lib/timeprice/sources.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "data_loader"
+require_relative "sources/coverage"
 
 module Timeprice
   # Enumerate bundled data sources with license/attribution and the actual
@@ -77,55 +77,9 @@ module Timeprice
 
     # Returns an array of hashes with :id, :kind, :name, :license, :license_url,
     # :attribution, :coverage (string like "1990-01 to 2026-03 (monthly+annual)").
+    # @return [Array<Hash>]
     def list
-      ATTRIBUTIONS.map { |s| s.merge(coverage: coverage_for(s)) }
-    end
-
-    def coverage_for(src)
-      case src[:kind]
-      when "cpi" then cpi_coverage(src[:country])
-      when "fx"  then fx_coverage(src[:id])
-      else "n/a"
-      end
-    rescue StandardError => e
-      "(coverage unavailable: #{e.message})"
-    end
-
-    def cpi_coverage(country)
-      data = DataLoader.load_cpi(country)
-      monthly = (data["monthly"] || {}).keys.sort
-      annual  = (data["annual"]  || {}).keys.sort
-      parts = []
-      parts << "monthly #{monthly.first}..#{monthly.last} (#{monthly.size})" unless monthly.empty?
-      parts << "annual #{annual.first}..#{annual.last} (#{annual.size})" unless annual.empty?
-      parts.join(", ")
-    end
-
-    def fx_coverage(id)
-      root = File.join(DataLoader.data_root, "fx", "usd")
-      years = Dir[File.join(root, "*.json")].map { |f| File.basename(f, ".json").to_i }.sort
-      return "no data" if years.empty?
-
-      case id
-      when "fx_vnd"
-        # VND broadcast-from-annual covers earlier years too.
-        with_vnd = years.select do |y|
-          d = JSON.parse(File.read(File.join(root, "#{y}.json")))
-          d["rates"].any? { |_, v| v.key?("VND") }
-        end
-        return "no VND data" if with_vnd.empty?
-
-        "USD↔VND #{with_vnd.first}..#{with_vnd.last}"
-      else
-        # ECB pairs (EUR/GBP/JPY) start 1999
-        ecb_years = years.select do |y|
-          d = JSON.parse(File.read(File.join(root, "#{y}.json")))
-          d["rates"].any? { |_, v| v.keys.intersect?(%w[EUR GBP JPY]) }
-        end
-        return "no ECB data" if ecb_years.empty?
-
-        "USD↔EUR/GBP/JPY daily #{ecb_years.first}..#{ecb_years.last}"
-      end
+      ATTRIBUTIONS.map { |s| s.merge(coverage: Coverage.for(s)) }
     end
   end
 end

data/lib/timeprice/supported.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Timeprice
+  # Canonical lists of supported country and currency codes, plus the
+  # bidirectional currency↔country map used by `Compare` and CLI output.
+  #
+  # Everything that needs to know "which currency pairs with which CPI series"
+  # must read it from here — duplicating the map elsewhere has bitten us before
+  # when a new country was added in one place and forgotten in the other.
+  module Supported
+    COUNTRIES  = %w[US UK EU JP VN].freeze
+    CURRENCIES = %w[USD GBP EUR JPY VND].freeze
+
+    COUNTRY_TO_CURRENCY = {
+      "US" => "USD",
+      "UK" => "GBP",
+      "EU" => "EUR",
+      "JP" => "JPY",
+      "VN" => "VND",
+    }.freeze
+
+    CURRENCY_TO_COUNTRY = COUNTRY_TO_CURRENCY.invert.freeze
+
+    # Currencies with no minor unit — formatted as whole numbers.
+    ZERO_DECIMAL_CURRENCIES = %w[JPY VND].freeze
+
+    module_function
+
+    # ISO 4217 minor-unit count for a currency. Falls back to 2 for unknown
+    # codes so callers can still render *some* value rather than crashing.
+    #
+    # @param currency [String]
+    # @return [Integer]
+    def decimals_for(currency)
+      ZERO_DECIMAL_CURRENCIES.include?(currency.to_s.upcase) ? 0 : 2
+    end
+
+    # @param country [String]
+    # @return [Boolean]
+    def country?(country)
+      COUNTRIES.include?(country.to_s.upcase)
+    end
+
+    # @param currency [String]
+    # @return [Boolean]
+    def currency?(currency)
+      CURRENCIES.include?(currency.to_s.upcase)
+    end
+
+    # @param currency [String] ISO 4217 code (e.g. "USD")
+    # @return [String, nil] country code, or nil if unsupported
+    def country_for_currency(currency)
+      CURRENCY_TO_COUNTRY[currency.to_s.upcase]
+    end
+
+    # @param country [String] country code (e.g. "US")
+    # @return [String, nil] currency code, or nil if unsupported
+    def currency_for_country(country)
+      COUNTRY_TO_CURRENCY[country.to_s.upcase]
+    end
+  end
+end

data/lib/timeprice/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Timeprice
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/timeprice.rb

@@ -1,24 +1,64 @@
 # frozen_string_literal: true
 
 require_relative "timeprice/version"
+require_relative "timeprice/supported"
 require_relative "timeprice/errors"
+require_relative "timeprice/point"
 require_relative "timeprice/data_loader"
 require_relative "timeprice/inflation"
 require_relative "timeprice/exchange"
 require_relative "timeprice/compare"
 require_relative "timeprice/sources"
 
+# Offline historical inflation & FX for Ruby.
+#
+# Top-level module functions wrap the three core operations: inflation
+# adjustment, currency exchange, and a combined "compare" that does both
+# in the right order. Each returns an immutable `Data.define` value object.
+#
+# @example Inflation
+#   Timeprice.inflation(amount: 100, from: "1990-01", to: "2024-01", country: "US")
+# @example FX
+#   Timeprice.exchange(amount: 100, from: "USD", to: "JPY", date: "2010-06-15")
+# @example Compare
+#   Timeprice.compare(amount: 100, from: ["USD", "2010"], to: ["VND", "2024"])
 module Timeprice
   module_function
 
+  # Inflation-adjust an amount between two dates using a country's CPI.
+  #
+  # @param amount  [Numeric] the original amount
+  # @param from    [String]  source date as "YYYY" or "YYYY-MM"
+  # @param to      [String]  target date as "YYYY" or "YYYY-MM"
+  # @param country [String]  country code from {Supported::COUNTRIES}
+  # @return [InflationResult]
+  # @raise [UnsupportedCountry] if `country` is not supported
+  # @raise [DataNotFound]       if no CPI point covers `from` or `to`
   def inflation(amount:, from:, to:, country:)
     Inflation.adjust(amount: amount, from: from, to: to, country: country)
   end
 
+  # Convert an amount between currencies on a specific date.
+  #
+  # @param amount [Numeric] the original amount
+  # @param from   [String]  source currency (ISO 4217)
+  # @param to     [String]  destination currency (ISO 4217)
+  # @param date   [String]  date as "YYYY-MM-DD"
+  # @return [ExchangeResult]
+  # @raise [UnsupportedCurrency] if either currency is not supported
+  # @raise [DataNotFound]        if no FX point exists within the fallback window
   def exchange(amount:, from:, to:, date:)
     Exchange.convert(amount: amount, from: from, to: to, date: date)
   end
 
+  # Compare an amount across two (currency, date) points: convert at the
+  # source date, then inflate in the destination currency. See README.md
+  # "Compare semantics" for why this order is correct.
+  #
+  # @param amount [Numeric]
+  # @param from   [Point, Array(String, String)] source point
+  # @param to     [Point, Array(String, String)] destination point
+  # @return [CompareResult]
   def compare(amount:, from:, to:)
     Compare.run(amount: amount, from: from, to: to)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeprice
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Patrick
@@ -157,12 +157,21 @@ files:
 - exe/timeprice
 - lib/timeprice.rb
 - lib/timeprice/cli.rb
+- lib/timeprice/cli/formatting.rb
+- lib/timeprice/cli/presenters/compare.rb
+- lib/timeprice/cli/presenters/exchange.rb
+- lib/timeprice/cli/presenters/inflation.rb
+- lib/timeprice/cli/presenters/sources.rb
 - lib/timeprice/compare.rb
+- lib/timeprice/cpi_lookup.rb
 - lib/timeprice/data_loader.rb
 - lib/timeprice/errors.rb
 - lib/timeprice/exchange.rb
 - lib/timeprice/inflation.rb
+- lib/timeprice/point.rb
 - lib/timeprice/sources.rb
+- lib/timeprice/sources/coverage.rb
+- lib/timeprice/supported.rb
 - lib/timeprice/version.rb
 homepage: https://github.com/patrick204nqh/timeprice
 licenses: