Module: A2A::Utils::TimeHelpers

Defined in:
lib/a2a/utils/time_helpers.rb

Class Method Summary collapse

Class Method Details

.current_time ⇒ Time

Get current time with Rails compatibility

Uses Time.current if available (Rails), otherwise falls back to Time.now

Returns:

  • (Time) —

    Current time



19
20
21
22
23
24
25
 
# File 'lib/a2a/utils/time_helpers.rb', line 19

def current_time
  if defined?(Time.current)
    Time.current
  else
    Time.now
  end
end

.current_time_i ⇒ Integer

Get current time as integer (Unix timestamp)

Returns:

  • (Integer) —

    Unix timestamp



47
48
49
 
# File 'lib/a2a/utils/time_helpers.rb', line 47

def current_time_i
  current_time.to_i
end

.current_timestamp ⇒ String

Get current timestamp in ISO8601 format

Returns:

  • (String) —

    ISO8601 formatted timestamp



31
32
33
 
# File 'lib/a2a/utils/time_helpers.rb', line 31

def current_timestamp
  current_time.utc.iso8601
end

.duration_between(start_time, end_time = nil) ⇒ Float

Calculate duration between two timestamps

Parameters:

  • start_time (String, Time) —

    Start timestamp

  • end_time (String, Time) (defaults to: nil) —

    End timestamp (defaults to current time)

Returns:

  • (Float) —

    Duration in seconds



115
116
117
118
119
120
121
122
123
124
 
# File 'lib/a2a/utils/time_helpers.rb', line 115

def duration_between(start_time, end_time = nil)
  start_t = start_time.is_a?(String) ? parse_timestamp(start_time) : start_time
  end_t = if end_time
            end_time.is_a?(String) ? parse_timestamp(end_time) : end_time
          else
            current_time
          end

  end_t - start_t
end

.format_duration(duration) ⇒ String

Format duration in human-readable format

Parameters:

  • duration (Numeric) —

    Duration in seconds

Returns:

  • (String) —

    Human-readable duration



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/a2a/utils/time_helpers.rb', line 131

def format_duration(duration)
  return "0s" if duration.zero?

  parts = []

  if duration >= 86_400 # days
    days = (duration / 86_400).floor
    parts << "#{days}d"
    duration %= 86_400
  end

  if duration >= 3600 # hours
    hours = (duration / 3600).floor
    parts << "#{hours}h"
    duration %= 3600
  end

  if duration >= 60 # minutes
    minutes = (duration / 60).floor
    parts << "#{minutes}m"
    duration %= 60
  end

  if duration.positive? || parts.empty?
    parts << if duration == duration.to_i
               "#{duration.to_i}s"
             else
               "#{duration.round(2)}s"
             end
  end

  parts.join(" ")
end

.format_timestamp(time) ⇒ String

Format time as ISO8601 string

Parameters:

  • time (Time) —

    Time object to format

Returns:

  • (String) —

    ISO8601 formatted string



67
68
69
 
# File 'lib/a2a/utils/time_helpers.rb', line 67

def format_timestamp(time)
  time.utc.iso8601
end

.future?(timestamp) ⇒ Boolean

Check if timestamp is in the future

Parameters:

  • timestamp (String, Time) —

    Timestamp to check

Returns:

  • (Boolean) —

    True if timestamp is in the future



104
105
106
107
 
# File 'lib/a2a/utils/time_helpers.rb', line 104

def future?(timestamp)
  time = timestamp.is_a?(String) ? parse_timestamp(timestamp) : timestamp
  time > current_time
end

.parse_timestamp(timestamp) ⇒ Time

Parse ISO8601 timestamp string

Parameters:

  • timestamp (String) —

    ISO8601 timestamp string

Returns:

  • (Time) —

    Parsed time object



56
57
58
59
60
 
# File 'lib/a2a/utils/time_helpers.rb', line 56

def parse_timestamp(timestamp)
  Time.parse(timestamp)
rescue ArgumentError => e
  raise A2A::Errors::InvalidTimestamp, "Invalid timestamp format: #{timestamp} - #{e.message}"
end

.past?(timestamp) ⇒ Boolean

Check if timestamp is in the past

Parameters:

  • timestamp (String, Time) —

    Timestamp to check

Returns:

  • (Boolean) —

    True if timestamp is in the past



94
95
96
97
 
# File 'lib/a2a/utils/time_helpers.rb', line 94

def past?(timestamp)
  time = timestamp.is_a?(String) ? parse_timestamp(timestamp) : timestamp
  time < current_time
end

.test_timestamp ⇒ String

Get current timestamp for tests (always uses Time.now for consistency)

Returns:

  • (String) —

    ISO8601 formatted timestamp



39
40
41
 
# File 'lib/a2a/utils/time_helpers.rb', line 39

def test_timestamp
  Time.now.utc.iso8601
end

.time_from_now(duration) ⇒ Time

Add time duration to current time

Parameters:

  • duration (Numeric) —

    Duration in seconds

Returns:

  • (Time) —

    Future time



76
77
78
 
# File 'lib/a2a/utils/time_helpers.rb', line 76

def time_from_now(duration)
  current_time + duration
end

.timestamp_from_now(duration) ⇒ String

Add time duration to current time and format as ISO8601

Parameters:

  • duration (Numeric) —

    Duration in seconds

Returns:

  • (String) —

    ISO8601 formatted future timestamp



85
86
87
 
# File 'lib/a2a/utils/time_helpers.rb', line 85

def timestamp_from_now(duration)
  format_timestamp(time_from_now(duration))
end