moon_phase_tracker 1.3.2

data/lib/moon_phase_tracker/phase_calculator/phase_interpolator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../phase"
+
+module MoonPhaseTracker
+  class PhaseCalculator
+    class PhaseInterpolator
+      MAX_INTERPOLATION_INTERVAL = 11.07
+      HOURS_PER_DAY = 24
+      SECONDS_PER_HOUR = 3600
+      DEFAULT_HOUR = 12
+      INTERMEDIATE_PHASES = [
+        { name: "Waxing Crescent", offset_ratio: 0.5, between: %i[new_moon first_quarter] },
+        { name: "Waxing Gibbous", offset_ratio: 0.5, between: %i[first_quarter full_moon] },
+        { name: "Waning Gibbous", offset_ratio: 0.5, between: %i[full_moon last_quarter] },
+        { name: "Waning Crescent", offset_ratio: 0.5, between: %i[last_quarter new_moon] }
+      ].freeze
+
+      def calculate_between(phase1, phase2)
+        return nil unless interpolation_possible?(phase1, phase2)
+
+        intermediate_config = find_intermediate_config(phase1.phase_type, phase2.phase_type)
+        return nil unless intermediate_config
+
+        create_intermediate_phase(phase1, phase2, intermediate_config)
+      end
+
+      private
+
+      def interpolation_possible?(phase1, phase2)
+        return false unless valid_phases?(phase1, phase2)
+        return false unless valid_dates?(phase1, phase2)
+
+        interval_within_limits?(phase1, phase2)
+      end
+
+      def valid_phases?(phase1, phase2)
+        phase1 && phase2
+      end
+
+      def valid_dates?(phase1, phase2)
+        phase1.date && phase2.date
+      end
+
+      def interval_within_limits?(phase1, phase2)
+        days_between = calculate_days_between(phase1.date, phase2.date)
+        days_between.positive? && days_between <= MAX_INTERPOLATION_INTERVAL
+      end
+
+      def calculate_days_between(date1, date2)
+        (date2 - date1).to_f
+      end
+
+      def find_intermediate_config(type1, type2)
+        INTERMEDIATE_PHASES.find { |config| config[:between] == [ type1, type2 ] }
+      end
+
+      def create_intermediate_phase(phase1, phase2, config)
+        intermediate_datetime = calculate_intermediate_datetime(phase1, phase2, config)
+        return nil unless intermediate_datetime
+
+        phase_data = build_phase_data(intermediate_datetime, config[:name])
+        Phase.new(phase_data, interpolated: true)
+      rescue Date::Error, ArgumentError => e
+        warn "Failed to create intermediate phase: #{e.class}"
+        nil
+      end
+
+      def calculate_intermediate_datetime(phase1, phase2, config)
+        total_hours = calculate_total_hours_between(phase1, phase2)
+        intermediate_hours = total_hours * config[:offset_ratio]
+
+        base_time = determine_base_time(phase1)
+        base_time + (intermediate_hours * SECONDS_PER_HOUR)
+      end
+
+      def calculate_total_hours_between(phase1, phase2)
+        days_between = calculate_days_between(phase1.date, phase2.date)
+        hours_from_days = days_between * HOURS_PER_DAY
+
+        return hours_from_days unless both_phases_have_time?(phase1, phase2)
+
+        time_difference_hours = calculate_time_difference_hours(phase1.time, phase2.time)
+        hours_from_days + time_difference_hours
+      end
+
+      def both_phases_have_time?(phase1, phase2)
+        phase1.time && phase2.time
+      end
+
+      def calculate_time_difference_hours(time1, time2)
+        (time2 - time1) / SECONDS_PER_HOUR.to_f
+      end
+
+      def determine_base_time(phase)
+        return phase.time if phase.time
+
+        Time.new(phase.date.year, phase.date.month, phase.date.day,
+                 DEFAULT_HOUR, 0, 0, "+00:00")
+      end
+
+      def build_phase_data(datetime, name)
+        {
+          "phase" => name,
+          "year" => datetime.year,
+          "month" => datetime.month,
+          "day" => datetime.day,
+          "time" => datetime.strftime("%H:%M")
+        }
+      end
+    end
+  end
+end

data/lib/moon_phase_tracker/phase_calculator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "phase_calculator/phase_interpolator"
+require_relative "phase_calculator/cycle_estimator"
+
+module MoonPhaseTracker
+  class PhaseCalculator
+    def initialize(major_phases)
+      @major_phases = major_phases.sort
+      @interpolator = PhaseInterpolator.new
+      @cycle_estimator = CycleEstimator.new
+    end
+
+    def calculate_all_phases
+      all_phases = @major_phases.dup
+
+      add_consecutive_intermediate_phases(all_phases)
+      add_cycle_transition_phases(all_phases)
+
+      all_phases.sort
+    end
+
+    private
+
+    def add_consecutive_intermediate_phases(all_phases)
+      @major_phases.each_cons(2) do |phase1, phase2|
+        intermediate_phase = @interpolator.calculate_between(phase1, phase2)
+        all_phases << intermediate_phase if intermediate_phase
+      end
+    end
+
+    def add_cycle_transition_phases(all_phases)
+      return unless @major_phases.size >= 2
+
+      last_phase = @major_phases.last
+      next_cycle_phase = @cycle_estimator.estimate_next_cycle_phase(last_phase)
+
+      return unless next_cycle_phase
+
+      intermediate_phase = @interpolator.calculate_between(last_phase, next_cycle_phase)
+      all_phases << intermediate_phase if intermediate_phase
+    end
+  end
+end

data/lib/moon_phase_tracker/rate_limiter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module MoonPhaseTracker
+  class RateLimiter
+    DEFAULT_REQUESTS_PER_SECOND = 1.0
+    DEFAULT_BURST_SIZE = 1
+
+    def initialize(requests_per_second: nil, burst_size: nil)
+      @requests_per_second = parse_rate_limit(requests_per_second)
+      @burst_size = parse_burst_size(burst_size)
+      @tokens = @burst_size.to_f
+      @last_refill = current_time
+      @mutex = Mutex.new
+    end
+
+    def throttle
+      @mutex.synchronize do
+        refill_tokens
+
+        if @tokens >= 1.0
+          consume_token
+          return
+        end
+
+        wait_time = calculate_wait_time
+        sleep(wait_time) if wait_time > 0
+
+        refill_tokens
+        consume_token
+      end
+    end
+
+    def can_proceed?
+      @mutex.synchronize do
+        refill_tokens
+        @tokens >= 1.0
+      end
+    end
+
+    def configuration
+      {
+        requests_per_second: @requests_per_second,
+        burst_size: @burst_size,
+        available_tokens: @tokens.floor
+      }
+    end
+
+    private
+
+    def parse_rate_limit(rate)
+      rate = rate || ENV.fetch("MOON_PHASE_RATE_LIMIT", DEFAULT_REQUESTS_PER_SECOND)
+
+      case rate
+      when String
+        Float(rate)
+      when Numeric
+        rate.to_f
+      else
+        raise ArgumentError, "Rate limit must be a number"
+      end
+    end
+
+    def parse_burst_size(size)
+      size = size || ENV.fetch("MOON_PHASE_BURST_SIZE", DEFAULT_BURST_SIZE)
+
+      case size
+      when String
+        Integer(size)
+      when Numeric
+        size.to_i
+      else
+        raise ArgumentError, "Burst size must be an integer"
+      end
+    end
+
+    def refill_tokens
+      now = current_time
+      elapsed = now - @last_refill
+      tokens_to_add = elapsed * @requests_per_second
+
+      @tokens = [ @tokens + tokens_to_add, @burst_size ].min
+      @last_refill = now
+    end
+
+    def calculate_wait_time
+      return 0 if @tokens >= 1.0
+
+      tokens_needed = 1.0 - @tokens
+      tokens_needed / @requests_per_second
+    end
+
+    def consume_token
+      @tokens = [ @tokens - 1.0, 0.0 ].max
+    end
+
+    def current_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/moon_phase_tracker/tracker/date_parser.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "date"
+
+module MoonPhaseTracker
+  class DateParser
+    def parse(date)
+      return parse_by_type(date) if valid_date_type?(date)
+
+      raise InvalidDateError, "Invalid date format: #{date.class}"
+    rescue Date::Error => e
+      raise InvalidDateError, "Invalid date: #{date} (#{e.message})"
+    end
+
+    private
+
+    def valid_date_type?(date)
+      [ String, Date, Time ].any? { |klass| date.is_a?(klass) }
+    end
+
+    def parse_by_type(date)
+      case date
+      when String
+        Date.parse(date)
+      when Date
+        date
+      when Time
+        date.to_date
+      end
+    end
+  end
+end

data/lib/moon_phase_tracker/tracker/phase_formatter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  class PhaseFormatter
+    def format(phases, title = nil)
+      return "No phases found." if phases.empty?
+
+      build_formatted_output(phases, title)
+    end
+
+    private
+
+    def build_formatted_output(phases, title)
+      output_lines = []
+
+      add_title_section(output_lines, title)
+      add_phases_section(output_lines, phases)
+      add_statistics_section(output_lines, phases)
+
+      output_lines.join("\n")
+    end
+
+    def add_title_section(output_lines, title)
+      return unless title
+
+      output_lines << title
+      output_lines << "=" * title.length
+      output_lines << ""
+    end
+
+    def add_phases_section(output_lines, phases)
+      phases.each do |phase|
+        prefix = phase.interpolated ? "~" : " "
+        output_lines << "#{prefix}#{phase}"
+      end
+
+      output_lines << ""
+    end
+
+    def add_statistics_section(output_lines, phases)
+      phase_stats = calculate_phase_statistics(phases)
+
+      if phase_stats[:interpolated_count].positive?
+        add_detailed_statistics(output_lines, phase_stats)
+        output_lines << "~ indicates interpolated phases"
+      else
+        output_lines << "Total: #{phase_stats[:total_count]} phase(s)"
+      end
+    end
+
+    def calculate_phase_statistics(phases)
+      {
+        total_count: phases.size,
+        major_count: phases.count { |phase| !phase.interpolated },
+        interpolated_count: phases.count(&:interpolated)
+      }
+    end
+
+    def add_detailed_statistics(output_lines, stats)
+      output_lines << "Total: #{stats[:total_count]} phase(s) " \
+                      "(#{stats[:major_count]} major, #{stats[:interpolated_count]} interpolated)"
+    end
+  end
+end

data/lib/moon_phase_tracker/tracker/phase_query_service.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  class PhaseQueryService
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    def phases_for_month(year, month)
+      year_phases = phases_for_year(year)
+      filter_phases_by_month(year_phases, year, month)
+    end
+
+    def phases_for_year(year)
+      response = @client.phases_for_year(year)
+      parse_api_response(response)
+    end
+
+    def phases_from_date(date, num_phases)
+      formatted_date = format_date_for_api(date)
+      response = @client.phases_from_date(formatted_date, num_phases)
+      parse_api_response(response)
+    end
+
+    def all_phases_for_month(year, month)
+      major_phases = phases_for_month(year, month)
+      all_phases = calculate_all_phases(major_phases)
+      filter_phases_by_month(all_phases, year, month)
+    end
+
+    def all_phases_for_year(year)
+      major_phases = phases_for_year(year)
+      calculate_all_phases(major_phases)
+    end
+
+    def all_phases_from_date(date, num_cycles)
+      # Calculate enough major phases to cover the requested cycles
+      phases_needed = num_cycles * 4
+      major_phases = phases_from_date(date, phases_needed)
+      calculate_all_phases(major_phases)
+    end
+
+    private
+
+    def parse_api_response(response)
+      return [] unless valid_response?(response)
+
+      phases = response["phasedata"].map { |phase_data| Phase.new(phase_data) }
+      phases.sort
+    end
+
+    def valid_response?(response)
+      response && response["phasedata"]
+    end
+
+    def filter_phases_by_month(phases, year, month)
+      phases.select { |phase| phase.in_month?(year, month) }
+    end
+
+    def format_date_for_api(date)
+      date.strftime("%Y-%m-%d")
+    end
+
+    def calculate_all_phases(major_phases)
+      calculator = PhaseCalculator.new(major_phases)
+      calculator.calculate_all_phases
+    end
+  end
+end

data/lib/moon_phase_tracker/tracker/validators.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  module Validators
+    private
+
+    def validate_year!(year)
+      current_year = Date.today.year
+      valid_range = (1700..current_year + 10)
+
+      return if year.is_a?(Integer) && valid_range.cover?(year)
+
+      raise InvalidDateError, "Year must be between #{valid_range.min} and #{valid_range.max}"
+    end
+
+    def validate_month!(year, month)
+      validate_year!(year)
+
+      return if month.is_a?(Integer) && (1..12).cover?(month)
+
+      raise InvalidDateError, "Month must be between 1 and 12"
+    end
+
+    def validate_num_phases!(num_phases)
+      valid_range = (1..99)
+
+      return if num_phases.is_a?(Integer) && valid_range.cover?(num_phases)
+
+      raise InvalidDateError, "Number of phases must be between #{valid_range.min} and #{valid_range.max}"
+    end
+  end
+end

data/lib/moon_phase_tracker/tracker.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "tracker/phase_query_service"
+require_relative "tracker/phase_formatter"
+require_relative "tracker/date_parser"
+require_relative "tracker/validators"
+
+module MoonPhaseTracker
+  class Tracker
+    include Validators
+
+    attr_reader :client, :query_service, :formatter, :date_parser
+
+    def initialize(rate_limiter: nil)
+      @client = Client.new(rate_limiter: rate_limiter)
+      @query_service = PhaseQueryService.new(@client)
+      @formatter = PhaseFormatter.new
+      @date_parser = DateParser.new
+    end
+
+    def rate_limit_info
+      @client.rate_limit_info
+    end
+
+    def phases_for_month(year, month)
+      validate_month!(year, month)
+      @query_service.phases_for_month(year, month)
+    end
+
+    def phases_for_year(year)
+      validate_year!(year)
+      @query_service.phases_for_year(year)
+    end
+
+    def phases_from_date(date, num_phases = 12)
+      parsed_date = @date_parser.parse(date)
+      validate_num_phases!(num_phases)
+      @query_service.phases_from_date(parsed_date, num_phases)
+    end
+
+    def next_phase
+      phases_from_date(Date.today, 1).first
+    end
+
+    def current_month_phases
+      today = Date.today
+      phases_for_month(today.year, today.month)
+    end
+
+    def current_year_phases
+      phases_for_year(Date.today.year)
+    end
+
+    def all_phases_for_month(year, month)
+      validate_month!(year, month)
+      @query_service.all_phases_for_month(year, month)
+    end
+
+    def all_phases_for_year(year)
+      validate_year!(year)
+      @query_service.all_phases_for_year(year)
+    end
+
+    def all_phases_from_date(date, num_cycles = 3)
+      parsed_date = @date_parser.parse(date)
+      @query_service.all_phases_from_date(parsed_date, num_cycles)
+    end
+
+    def format_phases(phases, title = nil)
+      @formatter.format(phases, title)
+    end
+
+    def self.month_name(month)
+      MONTH_NAMES[month - 1]
+    end
+
+    private
+
+    MONTH_NAMES = %w[
+      January February March April May June
+      July August September October November December
+    ].freeze
+  end
+end

data/lib/moon_phase_tracker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  VERSION = "1.3.2"
+end

data/lib/moon_phase_tracker.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "moon_phase_tracker/version"
+require_relative "moon_phase_tracker/rate_limiter"
+require_relative "moon_phase_tracker/client"
+require_relative "moon_phase_tracker/phase"
+require_relative "moon_phase_tracker/phase_calculator"
+require_relative "moon_phase_tracker/tracker"
+
+module MoonPhaseTracker
+  class Error < StandardError; end
+  class APIError < Error; end
+  class NetworkError < Error; end
+  class InvalidDateError < Error; end
+
+  def self.phases_for_month(year, month)
+    Tracker.new.phases_for_month(year, month)
+  end
+
+  def self.phases_for_year(year)
+    Tracker.new.phases_for_year(year)
+  end
+
+  def self.phases_from_date(date, num_phases = 12)
+    Tracker.new.phases_from_date(date, num_phases)
+  end
+
+  # Get all 8 phases (4 major + 4 intermediate) for a month
+  def self.all_phases_for_month(year, month)
+    Tracker.new.all_phases_for_month(year, month)
+  end
+
+  # Get all 8 phases (4 major + 4 intermediate) for a year
+  def self.all_phases_for_year(year)
+    Tracker.new.all_phases_for_year(year)
+  end
+
+  # Get all 8 phases from a specific date
+  def self.all_phases_from_date(date, num_cycles = 3)
+    Tracker.new.all_phases_from_date(date, num_cycles)
+  end
+end

data/sig/moon_phase_tracker.rbs

@@ -0,0 +1,4 @@
+module MoonPhaseTracker
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: moon_phase_tracker
+version: !ruby/object:Gem::Version
+  version: 1.3.2
+platform: ruby
+authors:
+- Daniel K Lima
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+description: A Ruby gem to track moon phases using the US Naval Observatory API. Shows
+  moon phases for specific dates, months, or years for lunar calendar scheduling.
+email:
+- dklima@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/eight_phases_example.rb
+- examples/rate_limiting_example.rb
+- examples/usage_example.rb
+- lib/moon_phase_tracker.rb
+- lib/moon_phase_tracker/client.rb
+- lib/moon_phase_tracker/phase.rb
+- lib/moon_phase_tracker/phase/comparator.rb
+- lib/moon_phase_tracker/phase/formatter.rb
+- lib/moon_phase_tracker/phase/mapper.rb
+- lib/moon_phase_tracker/phase/parser.rb
+- lib/moon_phase_tracker/phase_calculator.rb
+- lib/moon_phase_tracker/phase_calculator/cycle_estimator.rb
+- lib/moon_phase_tracker/phase_calculator/phase_interpolator.rb
+- lib/moon_phase_tracker/rate_limiter.rb
+- lib/moon_phase_tracker/tracker.rb
+- lib/moon_phase_tracker/tracker/date_parser.rb
+- lib/moon_phase_tracker/tracker/phase_formatter.rb
+- lib/moon_phase_tracker/tracker/phase_query_service.rb
+- lib/moon_phase_tracker/tracker/validators.rb
+- lib/moon_phase_tracker/version.rb
+- sig/moon_phase_tracker.rbs
+homepage: https://github.com/dklima/moon_phase_tracker
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/dklima/moon_phase_tracker
+  changelog_uri: https://github.com/dklima/moon_phase_tracker/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/dklima/moon_phase_tracker/blob/main/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Moon phase tracker using USNO Navy API
+test_files: []