Module: Timeprice::DataLoader

Defined in:
lib/timeprice/data_loader.rb

Overview

Loads and caches the bundled JSON data files. Override the search root by setting ‘TIMEPRICE_DATA_ROOT` in the environment or assigning DataLoader.data_root=.

Constant Summary collapse

SUPPORTED_SCHEMA_VERSION = 
4
SUPPORTED_SCHEMA_VERSIONS =

Files written by older toolchains remain readable: v3 is monthly+annual only; v4 adds an optional ‘series.quarterly` block.

[3, 4].freeze
DEFAULT_DATA_ROOT = 
File.expand_path("../../data", __dir__)

Class Method Summary collapse

Class Method Details

.clear_cache! ⇒ void

This method returns an undefined value.

Drop in-memory caches of parsed data files.



35
36
37
38
39
40
 
# File 'lib/timeprice/data_loader.rb', line 35

def clear_cache!
  @cpi_cache = {}
  @fx_cache = {}
  @manifest_cache = {}
  @annual_fallback_cache = {}
end

.data_root ⇒ String

Returns absolute path to the directory containing ‘cpi/`, `fx/`, `manifest.json`.

Returns:

  • (String) —

    absolute path to the directory containing ‘cpi/`, `fx/`, `manifest.json`.



21
22
23
 
# File 'lib/timeprice/data_loader.rb', line 21

def data_root
  ENV["TIMEPRICE_DATA_ROOT"] || @data_root || DEFAULT_DATA_ROOT
end

.data_root=(path) ⇒ void

This method returns an undefined value.

Override the data root and clear caches. Mostly useful in tests.

Parameters:

  • path (String) 


28
29
30
31
 
# File 'lib/timeprice/data_loader.rb', line 28

def data_root=(path)
  @data_root = path
  clear_cache!
end

.load_cpi(country) ⇒ Hash

Load the CPI series for a supported country.

Parameters:

  • country (String)

Returns:

  • (Hash) —

    parsed JSON with “series” / “index” / “provenance” / “providers”

Raises:



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/timeprice/data_loader.rb', line 63

def load_cpi(country)
  key = country.to_s.downcase
  code = country.to_s.upcase
  cpi_cache[[data_root, key]] ||= begin
    raise UnsupportedCountry, code unless Supported.country?(code)

    path = File.join(data_root, "cpi", "#{key}.json")
    unless File.exist?(path)
      raise DataNotFound, "CPI data file missing for #{code} (looked in #{path}). " \
                          "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
    end

    parse_with_schema(path)
  end
end

.load_fx_annual_fallback ⇒ Hash?

Load the sparse historical FX annual-only fallback file, if present. Returns nil when no fallback file ships with this data root.

Returns:

  • (Hash, nil) 


96
97
98
99
100
101
102
 
# File 'lib/timeprice/data_loader.rb', line 96

def load_fx_annual_fallback
  return @annual_fallback_cache[data_root] if @annual_fallback_cache&.key?(data_root)

  @annual_fallback_cache ||= {}
  path = File.join(data_root, "fx", "usd", "_annual.json")
  @annual_fallback_cache[data_root] = File.exist?(path) ? parse_with_schema(path) : nil
end

.load_fx_year(year) ⇒ Hash

Load the FX rates for a year.

Parameters:

  • year (Integer, String)

Returns:

  • (Hash) —

    parsed JSON with ‘rates` (and optional `annual`) blocks

Raises:



83
84
85
86
87
88
89
90
91
 
# File 'lib/timeprice/data_loader.rb', line 83

def load_fx_year(year)
  key = year.to_i
  fx_cache[[data_root, key]] ||= begin
    path = File.join(data_root, "fx", "usd", "#{key}.json")
    raise DataNotFound, "No FX data for year #{key}" unless File.exist?(path)

    parse_with_schema(path)
  end
end

.load_manifest ⇒ Hash

Load the top-level manifest describing the bundled dataset.

Returns:

  • (Hash)

Raises:



45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/timeprice/data_loader.rb', line 45

def load_manifest
  manifest_cache[data_root] ||= begin
    path = File.join(data_root, "manifest.json")
    unless File.exist?(path)
      raise DataNotFound, "manifest.json missing (looked in #{path}). " \
                          "Check TIMEPRICE_DATA_ROOT or reinstall the gem."
    end

    parse_with_schema(path)
  end
end