Class: SecApi::Period

Inherits:
Dry::Struct
  • Object
show all
Defined in:
lib/sec_api/objects/period.rb

Overview

Immutable value object representing a time period for XBRL facts.

Periods can be either:

  • Duration: has start_date and end_date (for income statement items)

  • Instant: has instant date (for balance sheet items)

Examples:

Duration period (income statement)

period = SecApi::Period.new(
  start_date: Date.new(2022, 9, 25),
  end_date: Date.new(2023, 9, 30)
)
period.duration? # => true

Instant period (balance sheet)

period = SecApi::Period.new(instant: Date.new(2023, 9, 30))
period.instant? # => true

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes) ⇒ Period

Returns a new instance of Period.



44
45
46
47
 
# File 'lib/sec_api/objects/period.rb', line 44

def initialize(attributes)
  super
  freeze
end

Class Method Details

.from_api(data) ⇒ Period

Parses API response data into a Period object.

Examples:

Period.from_api({"startDate" => "2023-01-01", "endDate" => "2023-12-31"})
Period.from_api({"instant" => "2023-09-30"})

Parameters:

  • data (Hash) —

    API response with camelCase or snake_case keys

Returns:

  • (Period) —

    Immutable Period object



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/sec_api/objects/period.rb', line 58

def self.from_api(data)
  # Defensive nil check for direct calls (Fact.from_api validates period presence)
  return nil if data.nil?

  start_date = data[:startDate] || data["startDate"] || data[:start_date] || data["start_date"]
  end_date = data[:endDate] || data["endDate"] || data[:end_date] || data["end_date"]
  instant = data[:instant] || data["instant"]

  validate_structure!(instant, start_date, end_date, data)

  new(
    start_date: start_date,
    end_date: end_date,
    instant: instant
  )
end

Instance Method Details

#duration? ⇒ Boolean

Returns true if this is a duration period (has start/end dates)

Returns:

  • (Boolean) 


33
34
35
 
# File 'lib/sec_api/objects/period.rb', line 33

def duration?
  !start_date.nil? && !end_date.nil?
end

#instant? ⇒ Boolean

Returns true if this is an instant period (point-in-time)

Returns:

  • (Boolean) 


40
41
42
 
# File 'lib/sec_api/objects/period.rb', line 40

def instant?
  !instant.nil?
end