Skip to content

moltinginstar/cuppy

Repository files navigation

cuppy logo

cuppy

A lightweight currency display component with automatic inflation adjustment.

License: MIT Contributor Covenant npm Bundle size

Cuppy is a zero-dependency TypeScript library for declaratively formatting monetary values across your webpage. It supports automatic adjustment of historical currency amounts for inflation based on the Consumer Price Index. (“Cuppy” is how “CPI” would be pronounced if economics was any fun.)

Installation

Using a package manager:

npm i @cuppy/core @cuppy/cpi-u

or

yarn add @cuppy/core @cuppy/cpi-u

or

pnpm add @cuppy/core @cuppy/cpi-u

Usage

<span
  data-cuppy
  data-from="1969"
  data-to="2020"
  data-hint="to"
  data-hint-display="inline"
  data-year-display="always"
  data-hint-year-display="ifFallback"
  data-number-style="compactShort"
  data-currency-style="name"
  data-sign-display="always"
  data-use-grouping
  data-precision-mode="decimalPlaces"
  data-min-digits="4"
  data-max-digits="5"
  data-inflation-dataset="cpiU"
  data-locale="en-NZ"
>
  25_400_000_000
</span>
import cuppy from "@cuppy/core";
import cpiU from "@cuppy/cpi-u";

// Set global defaults
cuppy.options.hint = "to";
cuppy.options.currencyStyle = "code";
cuppy.options.numberStyle = "compactShort";
cuppy.options.useGrouping = false;
cuppy.options.maxDigits = 3;
cuppy.options.yearFormatter = (value, year) => `${value} in ${year}`;
cuppy.options.inlineHintFormatter = (value, hint) => `${value} (${hint})`;

// Load inflation dataset
cuppy.dataset(cpiU);

// Format all Cuppies on the page!
cuppy();

Documentation

For more information, see the respective READMEs for each package:

Roadmap

At the moment Cuppy only supports U.S. dollars and the Consumer Price Index for All Urban Consumers (CPI-U) dataset. However, it is flexible enough to accomodate new currencies and inflation datasets via plugins.

There are a few different directions Cuppy could go in the future. One possibility is to retrieve the inflation data from an API instead of bundling it with the library. This would allow automatic updates of the inflation data without requiring end users to update their version of Cuppy.

Another high-impact improvement would be treeshaking support for datasets. Currently, the entire inflation dataset is bundled with the library even if only a subset of the data is used (which I imagine is the case for most users).

However, my main focus for the near future is refining the mobile experience with a more accessible alternative to tooltips, and on the code quality front, improving test coverage and code organization.

Contributing

If you like the idea and want to help make it better, please consider contributing! It can be as simple as opening an issue to report a bug or suggest an improvement, or as involved as implementing a new feature or fixing a bug yourself. For more information, see CONTRIBUTING.md.

License

Cuppy is licensed under the MIT License.