timeprice 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f350843e8e12653e2f798d8f9afec193001e911e0f36910d0473724f33d79f8
-  data.tar.gz: 3d1107eb101dd95ec6c2203fe6f1843f9249cf5046cf838577094c67a0fe63c0
+  metadata.gz: a991e47e7ddcc1b8a88a2be8e8a3850406f1a17bb9f6e0c69164bb25dcdb3fb8
+  data.tar.gz: b5d95ebc9b318b9165e32712142906539e230939e8a0e4bdbd2157ad89c247b9
 SHA512:
-  metadata.gz: a7efbb6d151b4fd4c9c6d4697fc9c755c9a0d2e6b8e1e32d828a1416737dbfbd00d9143c64edde191eaea3f7f758b96ac1d4b93c9f765fbc5d0993bf68b0be7a
-  data.tar.gz: 3a5b598b62cf93b992ed4ba5d069f84475c91a0be636600451fb3247caaa5c494c44b39268ed5e6107c34f923606521d42374d3300de42ad5a7449f53ae37e39
+  metadata.gz: f740a51b83681979a0b1a4b505bae66a4e266df69ba7064df53f50b783e5fd5d3ebfe3b4aea30452c4e216987f0248eb39c4f1e357c5df9ac7b439dc630593b5
+  data.tar.gz: 3f5e18ad1ef50e16636f63a7bc96e9bb2fda2ca8b7b7235b2c6534365d82ab0ca53bc24fc5e0d8188a86b5a1d36b5c80522c6f62a37d79d06c4b42f3da71f449

data/CHANGELOG.md

@@ -5,6 +5,52 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Breaking changes (planned for 1.0.0)
+- Public API methods (`inflation`, `exchange`, `compare`) now accept
+  `Timeprice::Date` in addition to strings. The accepted string formats
+  (`YYYY`, `YYYY-MM`, `YYYY-Qn`, `YYYY-MM-DD`) are unchanged. Unparseable
+  input now raises `Timeprice::InvalidDate` instead of a generic
+  `ArgumentError` at the boundary.
+- `Timeprice.metadata` returns a `MetadataSnapshot` value object. Hash
+  access (`meta[:countries]`), `to_h`, and `JSON.generate(meta)` keep
+  working — the wire shape is byte-identical. New code should treat the
+  result as a frozen `Data` instance.
+- `Timeprice::Point` gains `Point.parse(currency, date)` as the
+  canonical constructor; it routes the date through `Timeprice::Date`.
+- Implementation modules (`Timeprice::Inflation`, `::Exchange`,
+  `::Compare`, `::Metadata`) are marked `@api private`. They will be
+  relocated to `Timeprice::Internal::` in a future major release; depend
+  on the `Timeprice.<method>` facade.
+
+## [0.7.0] - 2026-05-15
+
+### Fixed
+- `Exchange.resolve_rate` no longer raises `DataNotFound` when one
+  triangulation leg falls back to the annual rate and the other resolves
+  on a daily date. Annual rates are year-wide, so they now adopt the
+  daily leg's effective date. Daily-vs-daily mismatches still raise.
+- `Compare.run` short-circuits CPI with `cpi_ratio: 1.0` when both
+  points share a date — there's no time-elapsed inflation to apply, and
+  the daily `YYYY-MM-DD` grain that this path produces would otherwise
+  blow up CPI's monthly-max lookup.
+- Web UI: `humaniseError` now recognises `DataNotFound`, FX
+  triangulation, and "No FX rate" patterns so a Ruby backtrace can no
+  longer surface in the result block.
+
+### Refactor (internal)
+- `Timeprice::Schema` owns the on-disk format definition; both the
+  reader (DataLoader) and the writer (data pipeline) reference it.
+- Data pipeline moved from `scripts/` to `tools/data_pipeline/`. Run via
+  `bundle exec rake data:refresh` and `bundle exec rake data:check_schema`.
+- Provider self-registration replaces the hand-written orchestration
+  list. Seven World Bank CPI subclasses collapsed into a factory call.
+- `Tools::DataPipeline::Series` value object replaces positional
+  `[monthly, annual]` / `[monthly, quarterly, annual]` returns.
+- Typed `Tools::DataPipeline::Error` hierarchy (HttpError, ShapeError,
+  ValidationError, SchemaError) replaces bare string raises.
+- Adopted the Weirich convention: `fail` for new exceptions, `raise` for
+  re-throws inside rescue blocks.
+
 ## [0.6.0] - 2026-05-12
 
 ### Added

data/README.md

@@ -6,6 +6,10 @@ Offline historical inflation & FX for Ruby — bundled data, no API keys, monthl
 [![Gem Version](https://img.shields.io/gem/v/timeprice.svg)](https://rubygems.org/gems/timeprice)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](https://www.ruby-lang.org/)
 
+**Try it without installing anything → [patrick204nqh.github.io/timeprice](https://patrick204nqh.github.io/timeprice/).** The page boots the gem in your browser via ruby.wasm — same code, same numbers, no backend.
+
+[![timeprice calculator screenshot](docs/img/calculator.png)](https://patrick204nqh.github.io/timeprice/)
+
 ## Why this exists
 
 Every other "historical inflation / FX" library wants you to wire up an API key, eat a rate
@@ -88,6 +92,33 @@ r.cpi_ratio  # => 1.897026680414...
 All result objects are `Data.define` value objects — they support `.to_h`, `==`, and
 pattern matching, so you can hand them to JSON, RSpec, or `case/in` without ceremony.
 
+### Introspection: `Timeprice.metadata`
+
+`Timeprice.metadata` returns a frozen, JSON-serialisable snapshot of the bundled
+dataset — version, refresh date, country list with per-granularity CPI ranges, currency
+list, and FX daily coverage. Use it to populate dropdowns or validate date inputs
+without hardcoding what the gem already knows.
+
+```ruby
+Timeprice.metadata
+# => {
+#   version: "0.7.0",
+#   generated_at: "2026-05-12",
+#   countries: [
+#     { code: "US", name: "United States", currency: "USD",
+#       granularities: ["monthly", "annual"],
+#       cpi: { monthly: { min: "1990-01", max: "2026-03" },
+#              annual:  { min: "1990",    max: "2024"    } } },
+#     ...
+#   ],
+#   currencies: [{ code: "USD", name: "US dollar" }, ...],
+#   fx: { base: "USD", daily_min: "1999-01-04", daily_max: "2026-05-11" }
+# }
+```
+
+The browser calculator linked at the top of this README is the canonical consumer —
+it reads metadata at boot so the UI never disagrees with the dataset.
+
 ## Supported countries, currencies, and data ranges
 
 Coverage is derived from the bundled `data/` files. Re-check with `timeprice sources`.
@@ -102,7 +133,7 @@ Coverage is derived from the bundled `data/` files. Re-check with `timeprice sou
 | Australia | AUD | ABS 6401.0 (quarterly) + World Bank `FP.CPI.TOTL` (annual baseline) | Quarterly + annual | 1948-Q3 → present |
 | Canada | CAD | Statistics Canada WDS (table 18-10-0004-01, vector `v41690973`) + World Bank annual baseline | Monthly + annual | 1914-01 → present |
 | Korea (Rep.) | KRW | IMF Data Portal CPI dataflow + World Bank annual baseline | Monthly + annual | 1990-01 → present |
-| China | CNY | World Bank `FP.CPI.TOTL` (annual primary) + IMF Data Portal CPI dataflow (monthly layer) | Monthly + annual | 1990-01 → present |
+| China | CNY | World Bank `FP.CPI.TOTL` (annual primary) + IMF Data Portal CPI dataflow (monthly layer) | Monthly + annual | 1993-01 → present |
 | Russia | RUB | World Bank `FP.CPI.TOTL` (annual primary) + IMF Data Portal CPI dataflow (monthly layer) | Monthly + annual | 1992-01 → present |
 
 **FX (USD base):** ECB reference rates via Frankfurter for **EUR / GBP / JPY / AUD /
@@ -287,7 +318,7 @@ Bundled data lives under `data/` in schema v3 and is self-describing:
   currencies sourced at annual resolution (today only VND). Used as the
   fallback tier when no daily rate covers the requested date.
 
-`scripts/check_schema_stability.rb` enforces the shape in CI.
+`tools/data_pipeline/schema_check.rb` enforces the shape in CI.
 
 ## Author
 

data/data/cpi/au.json

@@ -0,0 +1,419 @@
+{
+  "country": "AU",
+  "index": {
+    "base_period": "2010",
+    "rebased_at": null
+  },
+  "provenance": [
+    {
+      "from": "1948-Q3",
+      "provider": "abs",
+      "series": "quarterly",
+      "to": "2026-Q1"
+    },
+    {
+      "from": "1960",
+      "provider": "world_bank",
+      "series": "annual",
+      "to": "2024"
+    }
+  ],
+  "providers": [
+    {
+      "fetched_at": "2026-05-12",
+      "id": "world_bank",
+      "label": "World Bank FP.CPI.TOTL (annual, AU baseline)",
+      "status": "ok"
+    },
+    {
+      "fetched_at": "2026-05-12",
+      "id": "abs",
+      "label": "ABS 6401.0 Consumer Price Index (quarterly) + World Bank (annual baseline)",
+      "status": "ok"
+    }
+  ],
+  "schema_version": 4,
+  "series": {
+    "annual": {
+      "1960": 7.96045859451027,
+      "1961": 8.14256048564101,
+      "1962": 8.11654592976519,
+      "1963": 8.16857504151683,
+      "1964": 8.40270492027182,
+      "1965": 8.68886615903322,
+      "1966": 8.97502627366723,
+      "1967": 9.28720094417707,
+      "1968": 9.52133194705944,
+      "1969": 9.83350661756927,
+      "1970": 10.1716958439549,
+      "1971": 10.7960455596837,
+      "1972": 11.4464105807065,
+      "1973": 12.4869928157393,
+      "1974": 14.4120721988047,
+      "1975": 16.5972911452823,
+      "1976": 18.8085321418182,
+      "1977": 21.1238298630209,
+      "1978": 22.8147722478579,
+      "1979": 24.8959404650147,
+      "1980": 27.4193553826422,
+      "1981": 30.0208109702242,
+      "1982": 33.4287230358843,
+      "1983": 36.7845992450285,
+      "1984": 38.2414196200022,
+      "1985": 40.8168591528718,
+      "1986": 44.5109290849112,
+      "1987": 48.3090482474348,
+      "1988": 51.7950084772319,
+      "1989": 55.6971918586048,
+      "1990": 59.7814801287815,
+      "1991": 61.6805397100433,
+      "1992": 62.3048875522264,
+      "1993": 63.3975018966839,
+      "1994": 64.6462013281415,
+      "1995": 67.6378752538607,
+      "1996": 69.4068620557434,
+      "1997": 69.5629546369261,
+      "1998": 70.1612864243969,
+      "1999": 71.2018761536123,
+      "2000": 74.3756549681352,
+      "2001": 77.6534867602337,
+      "2002": 79.9687807343452,
+      "2003": 82.1540056761687,
+      "2004": 84.0790850592342,
+      "2005": 86.3423506710122,
+      "2006": 89.4120690137771,
+      "2007": 91.493237230934,
+      "2008": 95.4734650293526,
+      "2009": 97.1644149083721,
+      "2010": 99.9999999999999,
+      "2011": 103.30384784681,
+      "2012": 105.124870505209,
+      "2013": 107.700306290987,
+      "2014": 110.379813789798,
+      "2015": 112.044747614105,
+      "2016": 113.475551934366,
+      "2017": 115.686785436719,
+      "2018": 117.898022686164,
+      "2019": 119.797089761608,
+      "2020": 120.811652194838,
+      "2021": 124.271592622831,
+      "2022": 132.466181470806,
+      "2023": 139.880337389597,
+      "2024": 144.309741509281
+    },
+    "monthly": {},
+    "quarterly": {
+      "1948-Q3": 2.59,
+      "1948-Q4": 2.63,
+      "1949-Q1": 2.71,
+      "1949-Q2": 2.74,
+      "1949-Q3": 2.82,
+      "1949-Q4": 2.86,
+      "1950-Q1": 2.9,
+      "1950-Q2": 3.02,
+      "1950-Q3": 3.05,
+      "1950-Q4": 3.17,
+      "1951-Q1": 3.32,
+      "1951-Q2": 3.52,
+      "1951-Q3": 3.71,
+      "1951-Q4": 3.98,
+      "1952-Q1": 4.1,
+      "1952-Q2": 4.25,
+      "1952-Q3": 4.33,
+      "1952-Q4": 4.37,
+      "1953-Q1": 4.41,
+      "1953-Q2": 4.45,
+      "1953-Q3": 4.48,
+      "1953-Q4": 4.45,
+      "1954-Q1": 4.48,
+      "1954-Q2": 4.48,
+      "1954-Q3": 4.48,
+      "1954-Q4": 4.48,
+      "1955-Q1": 4.52,
+      "1955-Q2": 4.56,
+      "1955-Q3": 4.6,
+      "1955-Q4": 4.64,
+      "1956-Q1": 4.68,
+      "1956-Q2": 4.83,
+      "1956-Q3": 4.95,
+      "1956-Q4": 4.95,
+      "1957-Q1": 4.95,
+      "1957-Q2": 4.99,
+      "1957-Q3": 4.99,
+      "1957-Q4": 4.99,
+      "1958-Q1": 5.03,
+      "1958-Q2": 5.03,
+      "1958-Q3": 5.03,
+      "1958-Q4": 5.06,
+      "1959-Q1": 5.1,
+      "1959-Q2": 5.1,
+      "1959-Q3": 5.14,
+      "1959-Q4": 5.18,
+      "1960-Q1": 5.22,
+      "1960-Q2": 5.3,
+      "1960-Q3": 5.37,
+      "1960-Q4": 5.41,
+      "1961-Q1": 5.45,
+      "1961-Q2": 5.49,
+      "1961-Q3": 5.45,
+      "1961-Q4": 5.45,
+      "1962-Q1": 5.45,
+      "1962-Q2": 5.45,
+      "1962-Q3": 5.45,
+      "1962-Q4": 5.45,
+      "1963-Q1": 5.45,
+      "1963-Q2": 5.45,
+      "1963-Q3": 5.49,
+      "1963-Q4": 5.49,
+      "1964-Q1": 5.53,
+      "1964-Q2": 5.57,
+      "1964-Q3": 5.64,
+      "1964-Q4": 5.68,
+      "1965-Q1": 5.72,
+      "1965-Q2": 5.8,
+      "1965-Q3": 5.84,
+      "1965-Q4": 5.91,
+      "1966-Q1": 5.95,
+      "1966-Q2": 5.99,
+      "1966-Q3": 5.99,
+      "1966-Q4": 6.07,
+      "1967-Q1": 6.11,
+      "1967-Q2": 6.15,
+      "1967-Q3": 6.26,
+      "1967-Q4": 6.26,
+      "1968-Q1": 6.3,
+      "1968-Q2": 6.34,
+      "1968-Q3": 6.38,
+      "1968-Q4": 6.42,
+      "1969-Q1": 6.49,
+      "1969-Q2": 6.53,
+      "1969-Q3": 6.57,
+      "1969-Q4": 6.61,
+      "1970-Q1": 6.69,
+      "1970-Q2": 6.77,
+      "1970-Q3": 6.8,
+      "1970-Q4": 6.92,
+      "1971-Q1": 7.0,
+      "1971-Q2": 7.11,
+      "1971-Q3": 7.27,
+      "1971-Q4": 7.42,
+      "1972-Q1": 7.5,
+      "1972-Q2": 7.58,
+      "1972-Q3": 7.69,
+      "1972-Q4": 7.77,
+      "1973-Q1": 7.93,
+      "1973-Q2": 8.2,
+      "1973-Q3": 8.47,
+      "1973-Q4": 8.78,
+      "1974-Q1": 9.01,
+      "1974-Q2": 9.39,
+      "1974-Q3": 9.86,
+      "1974-Q4": 10.21,
+      "1975-Q1": 10.59,
+      "1975-Q2": 10.98,
+      "1975-Q3": 11.06,
+      "1975-Q4": 11.68,
+      "1976-Q1": 11.98,
+      "1976-Q2": 12.29,
+      "1976-Q3": 12.6,
+      "1976-Q4": 13.34,
+      "1977-Q1": 13.65,
+      "1977-Q2": 13.96,
+      "1977-Q3": 14.23,
+      "1977-Q4": 14.57,
+      "1978-Q1": 14.77,
+      "1978-Q2": 15.08,
+      "1978-Q3": 15.35,
+      "1978-Q4": 15.7,
+      "1979-Q1": 15.97,
+      "1979-Q2": 16.39,
+      "1979-Q3": 16.78,
+      "1979-Q4": 17.28,
+      "1980-Q1": 17.67,
+      "1980-Q2": 18.17,
+      "1980-Q3": 18.48,
+      "1980-Q4": 18.87,
+      "1981-Q1": 19.33,
+      "1981-Q2": 19.76,
+      "1981-Q3": 20.14,
+      "1981-Q4": 20.99,
+      "1982-Q1": 21.38,
+      "1982-Q2": 21.88,
+      "1982-Q3": 22.65,
+      "1982-Q4": 23.31,
+      "1983-Q1": 23.81,
+      "1983-Q2": 24.32,
+      "1983-Q3": 24.74,
+      "1983-Q4": 25.32,
+      "1984-Q1": 25.21,
+      "1984-Q2": 25.28,
+      "1984-Q3": 25.59,
+      "1984-Q4": 25.98,
+      "1985-Q1": 26.33,
+      "1985-Q2": 26.95,
+      "1985-Q3": 27.56,
+      "1985-Q4": 28.11,
+      "1986-Q1": 28.76,
+      "1986-Q2": 29.23,
+      "1986-Q3": 30.0,
+      "1986-Q4": 30.85,
+      "1987-Q1": 31.47,
+      "1987-Q2": 31.93,
+      "1987-Q3": 32.47,
+      "1987-Q4": 33.05,
+      "1988-Q1": 33.63,
+      "1988-Q2": 34.21,
+      "1988-Q3": 34.87,
+      "1988-Q4": 35.57,
+      "1989-Q1": 35.91,
+      "1989-Q2": 36.8,
+      "1989-Q3": 37.65,
+      "1989-Q4": 38.35,
+      "1990-Q1": 39.01,
+      "1990-Q2": 39.63,
+      "1990-Q3": 39.94,
+      "1990-Q4": 40.98,
+      "1991-Q1": 40.9,
+      "1991-Q2": 40.98,
+      "1991-Q3": 41.21,
+      "1991-Q4": 41.6,
+      "1992-Q1": 41.6,
+      "1992-Q2": 41.48,
+      "1992-Q3": 41.52,
+      "1992-Q4": 41.71,
+      "1993-Q1": 42.1,
+      "1993-Q2": 42.25,
+      "1993-Q3": 42.45,
+      "1993-Q4": 42.53,
+      "1994-Q1": 42.68,
+      "1994-Q2": 42.99,
+      "1994-Q3": 43.26,
+      "1994-Q4": 43.61,
+      "1995-Q1": 44.34,
+      "1995-Q2": 44.92,
+      "1995-Q3": 45.46,
+      "1995-Q4": 45.81,
+      "1996-Q1": 46.0,
+      "1996-Q2": 46.31,
+      "1996-Q3": 46.43,
+      "1996-Q4": 46.51,
+      "1997-Q1": 46.58,
+      "1997-Q2": 46.47,
+      "1997-Q3": 46.28,
+      "1997-Q4": 46.39,
+      "1998-Q1": 46.51,
+      "1998-Q2": 46.78,
+      "1998-Q3": 46.91,
+      "1998-Q4": 47.11,
+      "1999-Q1": 47.08,
+      "1999-Q2": 47.29,
+      "1999-Q3": 47.72,
+      "1999-Q4": 47.97,
+      "2000-Q1": 48.4,
+      "2000-Q2": 48.77,
+      "2000-Q3": 50.59,
+      "2000-Q4": 50.76,
+      "2001-Q1": 51.3,
+      "2001-Q2": 51.73,
+      "2001-Q3": 51.87,
+      "2001-Q4": 52.35,
+      "2002-Q1": 52.82,
+      "2002-Q2": 53.2,
+      "2002-Q3": 53.56,
+      "2002-Q4": 53.92,
+      "2003-Q1": 54.62,
+      "2003-Q2": 54.62,
+      "2003-Q3": 54.93,
+      "2003-Q4": 55.22,
+      "2004-Q1": 55.71,
+      "2004-Q2": 55.97,
+      "2004-Q3": 56.2,
+      "2004-Q4": 56.63,
+      "2005-Q1": 57.01,
+      "2005-Q2": 57.35,
+      "2005-Q3": 57.92,
+      "2005-Q4": 58.22,
+      "2006-Q1": 58.72,
+      "2006-Q2": 59.65,
+      "2006-Q3": 60.18,
+      "2006-Q4": 60.11,
+      "2007-Q1": 60.16,
+      "2007-Q2": 60.9,
+      "2007-Q3": 61.32,
+      "2007-Q4": 61.89,
+      "2008-Q1": 62.72,
+      "2008-Q2": 63.63,
+      "2008-Q3": 64.37,
+      "2008-Q4": 64.16,
+      "2009-Q1": 64.23,
+      "2009-Q2": 64.55,
+      "2009-Q3": 65.16,
+      "2009-Q4": 65.51,
+      "2010-Q1": 66.12,
+      "2010-Q2": 66.52,
+      "2010-Q3": 67.0,
+      "2010-Q4": 67.26,
+      "2011-Q1": 68.3,
+      "2011-Q2": 68.93,
+      "2011-Q3": 69.34,
+      "2011-Q4": 69.34,
+      "2012-Q1": 69.38,
+      "2012-Q2": 69.74,
+      "2012-Q3": 70.69,
+      "2012-Q4": 70.87,
+      "2013-Q1": 71.11,
+      "2013-Q2": 71.38,
+      "2013-Q3": 72.25,
+      "2013-Q4": 72.77,
+      "2014-Q1": 73.2,
+      "2014-Q2": 73.57,
+      "2014-Q3": 73.88,
+      "2014-Q4": 74.02,
+      "2015-Q1": 74.16,
+      "2015-Q2": 74.69,
+      "2015-Q3": 74.98,
+      "2015-Q4": 75.27,
+      "2016-Q1": 75.12,
+      "2016-Q2": 75.45,
+      "2016-Q3": 75.98,
+      "2016-Q4": 76.38,
+      "2017-Q1": 76.73,
+      "2017-Q2": 76.88,
+      "2017-Q3": 77.35,
+      "2017-Q4": 77.87,
+      "2018-Q1": 78.21,
+      "2018-Q2": 78.49,
+      "2018-Q3": 78.83,
+      "2018-Q4": 79.24,
+      "2019-Q1": 79.23,
+      "2019-Q2": 79.7,
+      "2019-Q3": 80.15,
+      "2019-Q4": 80.7,
+      "2020-Q1": 81.0,
+      "2020-Q2": 79.44,
+      "2020-Q3": 80.67,
+      "2020-Q4": 81.4,
+      "2021-Q1": 81.87,
+      "2021-Q2": 82.47,
+      "2021-Q3": 83.17,
+      "2021-Q4": 84.23,
+      "2022-Q1": 86.05,
+      "2022-Q2": 87.59,
+      "2022-Q3": 89.2,
+      "2022-Q4": 90.85,
+      "2023-Q1": 92.08,
+      "2023-Q2": 92.87,
+      "2023-Q3": 93.94,
+      "2023-Q4": 94.53,
+      "2024-Q1": 95.41,
+      "2024-Q2": 96.41,
+      "2024-Q3": 96.62,
+      "2024-Q4": 96.81,
+      "2025-Q1": 97.7,
+      "2025-Q2": 98.43,
+      "2025-Q3": 99.73,
+      "2025-Q4": 100.32,
+      "2026-Q1": 101.7
+    }
+  }
+}