superfeature 0.1.7 → 0.1.8

data/lib/superfeature/price.rb

@@ -1,24 +1,42 @@
-module Superfeature
-  # Convenience method for creating Price objects.
-  # Use Superfeature::Price(100) or after `include Superfeature`, just Price(100)
-  def Price(amount, **options)
-    Price.new(amount, **options)
-  end
-  module_function :Price
-  public :Price
+require 'bigdecimal'
 
+module Superfeature
+  # Immutable price object with discount support. Uses BigDecimal internally
+  # to avoid floating-point precision errors.
+  #
+  #   price = Price.new(49.99)
+  #   discounted = price.apply_discount("20%")
+  #   discounted.amount           # => 39.99
+  #   discounted.discount.percent # => 20.0
+  #
   class Price
-    DEFAULT_AMOUNT_PRECISION = 2
-    DEFAULT_PERCENT_PRECISION = 4
+    include Comparable
+
+    attr_reader :amount, :previous, :range
+
+    # Creates a new Price.
+    # - amount: the price value (converted to BigDecimal)
+    # - previous: the previous price in a discount chain
+    # - discount: the applied Discount::Applied object
+    # - range: clamp values to this range (default 0.., use nil for no clamping)
+    def initialize(amount, previous: nil, discount: nil, range: 0..)
+      @amount = clamp_to_range(to_decimal(amount), range)
+      @previous = previous
+      @discount = discount
+      @range = range
+    end
 
-    attr_reader :amount, :original, :discount_source, :amount_precision, :percent_precision
+    def price = self
 
-    def initialize(amount, original: nil, discount_source: nil, amount_precision: DEFAULT_AMOUNT_PRECISION, percent_precision: DEFAULT_PERCENT_PRECISION)
-      @amount = amount.to_f
-      @original = original
-      @discount_source = discount_source
-      @amount_precision = amount_precision
-      @percent_precision = percent_precision
+    def discount
+      @discount || Discount::NONE
+    end
+
+    def savings
+      original_amount = original.amount
+      fixed = original_amount - @amount
+      percent = original_amount.zero? ? BigDecimal("0") : (fixed / original_amount * 100)
+      Discount::Savings.new(fixed:, percent:)
     end
 
     # Apply a discount from various sources:
@@ -27,97 +45,334 @@ module Superfeature
     # - Discount object: Discount::Percent.new(25) → 25% off
     # - Any object responding to to_discount
     # - nil: no discount, returns self
-    def discount(source)
-      return self if source.nil?
-      
-      discount_obj = coerce_discount(source)
-      new_amount = [discount_obj.apply(@amount), 0].max.round(@amount_precision)
+    def apply_discount(*discounts)
+      discount, *remaining = discounts.flatten
+
+      if discount.present?
+        coerced = coerce_discount(discount)
+        discounted = coerced.apply(@amount)
+        original_amount = original.amount
+        fixed = @amount - discounted
+        percent = original_amount.zero? ? BigDecimal("0") : (fixed / original_amount * 100)
 
-      Price.new(new_amount,
-        original: self,
-        discount_source: source,
-        amount_precision: @amount_precision,
-        percent_precision: @percent_precision
-      )
+        applied = Discount::Applied.new(coerced, fixed:, percent:)
+
+        build_price(discounted, previous: self, discount: applied).apply_discount(*remaining)
+      else
+        price
+      end
     end
 
     # Apply a fixed dollar discount
     def discount_fixed(amount)
-      discount(Discount::Fixed.new(amount.to_f))
+      apply_discount Discount::Fixed.new to_decimal(amount)
     end
 
-    # Set the price to a specific amount (calculates discount from current amount)
-    # Price(300).to(200) is equivalent to Price(300).discount_fixed(100)
-    def to(new_amount)
-      discount_fixed([@amount - new_amount.to_f, 0].max)
+    # Set the price to a specific amount
+    # Price(300).discount_to(200) is equivalent to Price(300).discount_fixed(100)
+    def discount_to(new_amount)
+      diff = @amount - to_decimal(new_amount)
+      discount_fixed diff.positive? ? diff : 0
     end
 
-    # Apply a percentage discount (decimal, e.g., 0.25 for 25%)
+    # Apply a percentage discount (e.g., 50 for 50% off)
     def discount_percent(percent)
-      discount(Discount::Percent.new(percent.to_f * 100))
+      apply_discount Discount::Percent.new(percent)
     end
 
-    # Dollars saved from original price
-    def fixed_discount
-      return 0.0 unless @original
-      (@original.amount - @amount).round(@amount_precision)
+    # Round price to a specified ending.
+    # Defaults to nearest. Use round_up or round_down for explicit direction.
+    #
+    #   Price(50).round(9)       # => Price(49) - nearest ending in 9
+    #   Price(50).round_up(9)    # => Price(59) - round up to ending 9
+    #   Price(50).round_down(9)  # => Price(49) - round down to ending 9
+    #   Price(50).round(0.99)    # => Price(49.99) - nearest ending in .99
+    #
+    def round(ending)
+      apply_discount Discount::Round::Nearest.new(ending)
     end
 
-    # Percent saved as decimal (e.g., 0.25 for 25%)
-    def percent_discount
-      return 0.0 unless @original
-      return 0.0 if @original.amount.zero?
-      ((@original.amount - @amount) / @original.amount).round(@percent_precision)
+    def round_up(ending)
+      apply_discount Discount::Round::Up.new(ending)
+    end
+
+    def round_down(ending)
+      apply_discount Discount::Round::Down.new(ending)
     end
 
     def discounted?
-      !@original.nil?
+      !@previous.nil?
     end
 
-    def full_price
-      @original ? @original.amount : @amount
+    # Returns the original price (walks all the way back in the discount chain)
+    def original
+      current = self
+      current = current.previous while current.previous
+      current
     end
 
-    # Format amount as string with configured precision
-    def to_formatted_s
-      "%.#{@amount_precision}f" % @amount
+    # Returns an Itemization enumerable for walking the discount chain.
+    def itemization
+      Itemization.new(self)
     end
 
-    def to_f
-      @amount
+    # Returns an Inspector for formatting the price breakdown as text.
+    def inspector
+      Inspector.new(itemization)
+    end
+
+    # Returns the undiscounted price amount (walks up the discount chain)
+    def full_price
+      original.amount
     end
 
+    def to_formatted_s(decimals: 2)
+      "%.#{decimals}f" % @amount.to_f
+    end
+
+    def to_f = @amount.to_f
+    def to_d = @amount
+    def to_i = @amount.to_i
+    # Returns display-friendly string: whole numbers without decimals ("19"),
+    # cents with 2 decimals ("19.50"). Use to_formatted_s(decimals: 2) for
+    # consistent decimal places.
     def to_s
-      @amount.to_s
+      if @amount % 1 == 0
+        @amount.to_i.to_s
+      else
+        "%.2f" % @amount.to_f
+      end
+    end
+
+    def <=>(other)
+      case other
+      when Price then @amount <=> other.amount
+      when Numeric then @amount <=> to_decimal(other)
+      else nil
+      end
+    end
+
+    def +(other) = build_price(@amount + to_amount(other))
+    def -(other) = build_price(@amount - to_amount(other))
+    def *(other) = build_price(@amount * to_amount(other))
+    def /(other) = build_price(@amount / to_amount(other))
+    def -@ = build_price(-@amount)
+    def abs = build_price(@amount.abs)
+
+    def zero? = @amount.zero?
+    alias free? zero?
+
+    def positive? = @amount.positive?
+    alias paid? positive?
+
+    def negative? = @amount.negative?
+
+    
+    def clamp(min, max) = build_price(@amount.clamp(to_amount(min), to_amount(max)))
+
+    # Enables `10 + Price(5)` by converting the numeric to a Price
+    def coerce(other)
+      case other
+      when Numeric then [build_price(other), self]
+      else raise TypeError, "#{other.class} can't be coerced into Price"
+      end
     end
 
     def inspect
       if discounted?
-        "#<Price #{to_formatted_s} (was #{@original.to_formatted_s}, #{(percent_discount * 100).round(1)}% off)>"
+        "#<#{self.class.name} #{to_formatted_s} (was #{@previous.to_formatted_s}, #{discount.percent.to_f.round(1)}% off)>"
       else
-        "#<Price #{to_formatted_s}>"
+        "#<#{self.class.name} #{to_formatted_s}>"
       end
     end
 
+    def pretty_inspect
+      receipt = inspector.to_s.lines.map { |line| "# #{line}" }.join
+      "#{inspect}\n#\n#{receipt}\n"
+    end
+
+    def pretty_print(pp)
+      pp.text(pretty_inspect)
+    end
+
     private
 
+    def build_price(*, **)
+      Price.new(*, range: @range, **)
+    end
+
+    def clamp_to_range(value, range)
+      return value unless range
+
+      min = range.begin || -Float::INFINITY
+      max = range.end || Float::INFINITY
+      value.clamp(min, max)
+    end
+
+    def to_decimal(value)
+      case value
+      when BigDecimal then value
+      when Float then BigDecimal(value, 15)
+      else BigDecimal(value.to_s)
+      end
+    end
+
+    def to_amount(other)
+      case other
+      when Price then other.amount
+      when Numeric then to_decimal(other)
+      else raise ArgumentError, "Cannot convert #{other.class} to amount"
+      end
+    end
+
     def coerce_discount(source)
       case source
       when String then parse_discount_string(source)
-      when Numeric then Discount::Fixed.new(source)
+      when Numeric then Discount::Fixed.new to_decimal(source)
       else source.to_discount
       end
     end
 
     def parse_discount_string(str)
       case str
-      when /\A(\d+(?:\.\d+)?)\s*%\z/
-        Discount::Percent.new($1.to_f)
-      when /\A\$?\s*(\d+(?:\.\d+)?)\z/
-        Discount::Fixed.new($1.to_f)
+      when nil then Discount::NONE
+      when Discount::Percent::PATTERN then Discount::Percent.parse(str)
+      when Discount::Fixed::PATTERN then Discount::Fixed.parse(str)
+      else raise ArgumentError, "Invalid discount format: #{str.inspect}"
+      end
+    end
+  end
+
+  # Enumerates prices in a discount chain from original to final.
+  #
+  #   final = Price(100).apply_discount("20%").apply_discount("$10")
+  #   itemization = Itemization.new(final)
+  #
+  #   itemization.original # => Price(100)
+  #   itemization.final    # => Price(70)
+  #   itemization.count    # => 3
+  #   itemization.each { |p| puts p }
+  #
+  class Itemization
+    include Enumerable
+
+    def initialize(price)
+      @final = price
+    end
+
+    def each(&block)
+      return to_enum(:each) unless block_given?
+
+      to_a.each(&block)
+    end
+
+    def to_a
+      @prices ||= build_chain
+    end
+
+    def original
+      to_a.first
+    end
+    alias first original
+
+    def final
+      @final
+    end
+    alias last final
+
+    def size
+      to_a.size
+    end
+    alias count size
+    alias length size
+
+    private
+
+    def build_chain
+      prices = []
+      current = @final
+
+      while current
+        prices.unshift(current)
+        current = current.previous
+      end
+
+      prices
+    end
+  end
+
+  # Formats a price itemization as a receipt-style text breakdown.
+  #
+  #   final = Price(100).apply_discount("20%").apply_discount("$10")
+  #   puts Inspector.new(final.itemization)
+  #
+  #   # Output:
+  #   #   Original              100.00
+  #   #   20% off               -20.00
+  #   #                       --------
+  #   #   Subtotal               80.00
+  #   #   $10 off               -10.00
+  #   #                       --------
+  #   #   FINAL                  70.00
+  #
+  class Inspector
+    def initialize(itemization, label_width: 20, max_label_width: 30)
+      @itemization = itemization
+      @label_width = label_width
+      @max_label_width = max_label_width
+    end
+
+    def to_s
+      items = @itemization.to_a
+      amount_width = calculate_amount_width(items)
+      separator_line = " " * @label_width + "-" * amount_width
+
+      output = []
+      output << format_line("Original", items.first.to_formatted_s, amount_width)
+
+      original_amount = items.first.amount
+      items.drop(1).each_with_index do |price, index|
+        cumulative_fixed = original_amount - price.amount
+        sign = cumulative_fixed.negative? ? "+" : "-"
+        discount_amount = "#{sign}%.2f" % cumulative_fixed.abs.to_f
+        label = price.discount.to_receipt_s
+        output << format_line(label, discount_amount, amount_width)
+        output << separator_line
+
+        is_last = index == items.length - 2
+        if is_last
+          output << format_line("FINAL", price.to_formatted_s, amount_width)
+        else
+          output << format_line("Subtotal", price.to_formatted_s, amount_width)
+        end
+      end
+
+      # Handle case with no discounts
+      if items.length == 1
+        output << separator_line
+        output << format_line("FINAL", items.first.to_formatted_s, amount_width)
+      end
+
+      output.join("\n")
+    end
+
+    private
+
+    def calculate_amount_width(items)
+      widths = items.map { |p| p.to_formatted_s.length }
+      items.drop(1).each do |p|
+        widths << "-#{p.discount.to_fixed_s}".length
+      end
+      widths.max + 2
+    end
+
+    def format_line(label, amount, amount_width)
+      if label.length > @max_label_width
+        "#{label}\n#{' ' * @label_width}%#{amount_width}s" % [amount]
       else
-        raise ArgumentError, "Invalid discount format: #{str.inspect}"
+        "%-#{@label_width}s%#{amount_width}s" % [label, amount]
       end
     end
   end
+
 end

data/lib/superfeature/round.rb

@@ -0,0 +1,83 @@
+require 'bigdecimal'
+
+module Superfeature
+  # Rounds values to a specified ending.
+  # For example, round to 9 gives $19, $29, $49, etc.
+  #
+  #   Round.new(9).up(50)      # => 59 (next value ending in 9)
+  #   Round.new(9).down(50)    # => 49 (previous value ending in 9)
+  #   Round.new(9).nearest(50) # => 49 (closer to 49 than 59)
+  #
+  #   Round.new(0.99).up(2.50)   # => 2.99
+  #   Round.new(0.99).down(2.50) # => 1.99
+  #
+  class Round
+    # Convenience methods to create round discounts
+    # Usage: Round::Up(9), Round::Down(9), Round::Nearest(9)
+    def self.Up(ending) = Discount::Round::Up.new(ending)
+    def self.Down(ending) = Discount::Round::Down.new(ending)
+    def self.Nearest(ending) = Discount::Round::Nearest.new(ending)
+
+    attr_reader :ending
+
+    def initialize(ending)
+      @ending = to_decimal(ending)
+    end
+
+    def up(value)
+      val = to_decimal(value)
+      return val if val.zero?
+
+      result = candidate(val)
+      result += interval if result < val
+      result
+    end
+
+    def down(value)
+      val = to_decimal(value)
+      return val if val.zero?
+
+      result = candidate(val)
+      result -= interval if result > val
+      result
+    end
+
+    def nearest(value)
+      val = to_decimal(value)
+      return val if val.zero?
+
+      up_val = up(val)
+      down_val = down(val)
+
+      distance_down = (val - down_val).abs
+      distance_up = (up_val - val).abs
+      distance_down <= distance_up ? down_val : up_val
+    end
+
+    private
+
+    def to_decimal(value)
+      case value
+      when BigDecimal then value
+      when Float then BigDecimal(value, 15)
+      else BigDecimal(value.to_s)
+      end
+    end
+
+    # Determine interval from ending
+    # 0.99 → interval of 1 (0.99, 1.99, 2.99...)
+    # 9 → interval of 10 (9, 19, 29...)
+    # 99 → interval of 100 (99, 199, 299...)
+    def interval
+      return BigDecimal("1") if @ending < 1
+
+      digits = @ending.to_i.to_s.length
+      BigDecimal("10") ** digits
+    end
+
+    def candidate(val)
+      base = (val / interval).floor * interval
+      base + @ending
+    end
+  end
+end

data/lib/superfeature/version.rb

@@ -1,3 +1,3 @@
 module Superfeature
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

data/lib/superfeature.rb

@@ -4,15 +4,28 @@ require "superfeature/limit"
 require "superfeature/feature"
 require "superfeature/plan"
 require "superfeature/plan/collection"
+require "superfeature/round"
 require "superfeature/discount"
 require "superfeature/price"
 
 module Superfeature
-  # Convenience methods for creating Discount objects.
-  # Use Superfeature::Fixed(20) or after `include Superfeature`, just Fixed(20)
-  def Fixed(...) = Discount::Fixed.new(...)
-  def Percent(...) = Discount::Percent.new(...)
-  def Bundle(...) = Discount::Bundle.new(...)
-  module_function :Fixed, :Percent, :Bundle
-  public :Fixed, :Percent, :Bundle
+  # Mix this in to get Price, Fixed, Percent helpers.
+  #
+  #   class Plan
+  #     include Superfeature::Pricing
+  #
+  #     def monthly_price
+  #       Price(29).apply_discount(Percent(20))
+  #     end
+  #   end
+  #
+  module Pricing
+    def Price(...) = Superfeature::Price.new(...)
+    def Fixed(...) = Discount::Fixed.new(...)
+    def Percent(...) = Discount::Percent.new(...)
+    Round = Superfeature::Round
+  end
+
+  include Pricing
+  extend Pricing
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: superfeature
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Brad Gessler
 bindir: bin
 cert_chain: []
-date: 2026-01-09 00:00:00.000000000 Z
+date: 2026-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -53,6 +53,9 @@ files:
 - lib/generators/superfeature/plan/plan_generator.rb
 - lib/generators/superfeature/plan/templates/plan.rb.tt
 - lib/superfeature.rb
+- lib/superfeature/core_ext.rb
+- lib/superfeature/core_ext/numeric.rb
+- lib/superfeature/core_ext/string.rb
 - lib/superfeature/discount.rb
 - lib/superfeature/engine.rb
 - lib/superfeature/feature.rb
@@ -60,6 +63,7 @@ files:
 - lib/superfeature/plan.rb
 - lib/superfeature/plan/collection.rb
 - lib/superfeature/price.rb
+- lib/superfeature/round.rb
 - lib/superfeature/version.rb
 - lib/tasks/superfeature_tasks.rake
 homepage: https://github.com/rubymonolith/superfeature