@lightsparkdev/core 1.0.5 → 1.0.6

package/src/utils/currency.ts

@@ -1,32 +1,14 @@
 // Copyright ©, 2023-present, Lightspark Group, Inc. - All Rights Reserved
 
 import LightsparkException from "../LightsparkException.js";
+import { getCurrentLocale } from "./locale.js";
+import { localeToCurrencyCode } from "./localeToCurrencyCodes.js";
+import { isNumber, round } from "./numbers.js";
 
-/** Represents the value and unit for an amount of currency. **/
-type CurrencyAmount = {
-  /** The original numeric value for this CurrencyAmount. **/
-  originalValue: number;
-
-  /** The original unit of currency for this CurrencyAmount. **/
-  originalUnit: CurrencyUnit;
-
-  /** The unit of user's preferred currency. **/
-  preferredCurrencyUnit: CurrencyUnit;
-
-  /**
-   * The rounded numeric value for this CurrencyAmount in the very base level of user's preferred
-   * currency. For example, for USD, the value will be in cents.
-   **/
-  preferredCurrencyValueRounded: number;
-
-  /**
-   * The approximate float value for this CurrencyAmount in the very base level of user's preferred
-   * currency. For example, for USD, the value will be in cents.
-   **/
-  preferredCurrencyValueApprox: number;
-};
+export const defaultCurrencyCode = "USD";
 
-enum CurrencyUnit {
+/** This enum identifies the unit of currency associated with a CurrencyAmount. **/
+export enum CurrencyUnit {
   /**
    * This is an enum value that represents values that could be added in the future.
    * Clients should support unknown values as more of them could be added without notice.
@@ -48,6 +30,26 @@ enum CurrencyUnit {
   MILLIBITCOIN = "MILLIBITCOIN",
 }
 
+/** This object represents the value and unit for an amount of currency. **/
+export type CurrencyAmountType = {
+  /** The original numeric value for this CurrencyAmount. **/
+  originalValue: number;
+  /** The original unit of currency for this CurrencyAmount. **/
+  originalUnit: CurrencyUnit;
+  /** The unit of user's preferred currency. **/
+  preferredCurrencyUnit: CurrencyUnit;
+  /**
+   * The rounded numeric value for this CurrencyAmount in the very base level of user's preferred
+   * currency. For example, for USD, the value will be in cents.
+   **/
+  preferredCurrencyValueRounded: number;
+  /**
+   * The approximate float value for this CurrencyAmount in the very base level of user's preferred
+   * currency. For example, for USD, the value will be in cents.
+   **/
+  preferredCurrencyValueApprox: number;
+};
+
 const CONVERSION_MAP = {
   [CurrencyUnit.BITCOIN]: {
     [CurrencyUnit.BITCOIN]: (v: number) => v,
@@ -56,73 +58,414 @@ const CONVERSION_MAP = {
     [CurrencyUnit.MILLISATOSHI]: (v: number) => v * 100_000_000_000,
     [CurrencyUnit.NANOBITCOIN]: (v: number) => v * 1_000_000_000,
     [CurrencyUnit.SATOSHI]: (v: number) => v * 100_000_000,
+    [CurrencyUnit.USD]: (v: number, centsPerBtc = 1) =>
+      /* Round without decimals since we're returning cents: */
+      round(v * centsPerBtc, 2),
   },
   [CurrencyUnit.MICROBITCOIN]: {
-    [CurrencyUnit.BITCOIN]: (v: number) => Math.round(v / 1_000_000),
+    [CurrencyUnit.BITCOIN]: (v: number) => v / 1_000_000,
     [CurrencyUnit.MICROBITCOIN]: (v: number) => v,
-    [CurrencyUnit.MILLIBITCOIN]: (v: number) => Math.round(v / 1000),
+    [CurrencyUnit.MILLIBITCOIN]: (v: number) => v / 1000,
     [CurrencyUnit.MILLISATOSHI]: (v: number) => v * 100_000,
     [CurrencyUnit.NANOBITCOIN]: (v: number) => v * 1000,
     [CurrencyUnit.SATOSHI]: (v: number) => v * 100,
+    [CurrencyUnit.USD]: (v: number, centsPerBtc = 1) =>
+      /* Round without decimals since we're returning cents: */
+      round((v / 1_000_000) * centsPerBtc),
   },
   [CurrencyUnit.MILLIBITCOIN]: {
-    [CurrencyUnit.BITCOIN]: (v: number) => Math.round(v / 1_000),
+    [CurrencyUnit.BITCOIN]: (v: number) => v / 1_000,
     [CurrencyUnit.MICROBITCOIN]: (v: number) => v * 1000,
     [CurrencyUnit.MILLIBITCOIN]: (v: number) => v,
     [CurrencyUnit.MILLISATOSHI]: (v: number) => v * 100_000_000,
     [CurrencyUnit.NANOBITCOIN]: (v: number) => v * 1_000_000,
     [CurrencyUnit.SATOSHI]: (v: number) => v * 100_000,
+    [CurrencyUnit.USD]: (v: number, centsPerBtc = 1) =>
+      /* Round without decimals since we're returning cents: */
+      round((v / 1_000) * centsPerBtc),
   },
   [CurrencyUnit.MILLISATOSHI]: {
-    [CurrencyUnit.BITCOIN]: (v: number) => Math.round(v / 100_000_000_000),
-    [CurrencyUnit.MICROBITCOIN]: (v: number) => Math.round(v / 100_000),
-    [CurrencyUnit.MILLIBITCOIN]: (v: number) => Math.round(v / 100_000_000),
+    [CurrencyUnit.BITCOIN]: (v: number) => v / 100_000_000_000,
+    [CurrencyUnit.MICROBITCOIN]: (v: number) => v / 100_000,
+    [CurrencyUnit.MILLIBITCOIN]: (v: number) => v / 100_000_000,
     [CurrencyUnit.MILLISATOSHI]: (v: number) => v,
-    [CurrencyUnit.NANOBITCOIN]: (v: number) => Math.round(v / 100),
-    [CurrencyUnit.SATOSHI]: (v: number) => Math.round(v / 1000),
+    [CurrencyUnit.NANOBITCOIN]: (v: number) => v / 100,
+    [CurrencyUnit.SATOSHI]: (v: number) => v / 1000,
+    [CurrencyUnit.USD]: (v: number, centsPerBtc = 1) =>
+      /* Round without decimals since we're returning cents: */
+      round((v / 100_000_000_000) * centsPerBtc),
   },
   [CurrencyUnit.NANOBITCOIN]: {
-    [CurrencyUnit.BITCOIN]: (v: number) => Math.round(v / 1_000_000_000),
-    [CurrencyUnit.MICROBITCOIN]: (v: number) => Math.round(v / 1000),
-    [CurrencyUnit.MILLIBITCOIN]: (v: number) => Math.round(v / 1_000_000),
+    [CurrencyUnit.BITCOIN]: (v: number) => v / 1_000_000_000,
+    [CurrencyUnit.MICROBITCOIN]: (v: number) => v / 1000,
+    [CurrencyUnit.MILLIBITCOIN]: (v: number) => v / 1_000_000,
     [CurrencyUnit.MILLISATOSHI]: (v: number) => v * 100,
     [CurrencyUnit.NANOBITCOIN]: (v: number) => v,
-    [CurrencyUnit.SATOSHI]: (v: number) => Math.round(v / 10),
+    [CurrencyUnit.SATOSHI]: (v: number) => v / 10,
+    [CurrencyUnit.USD]: (v: number, centsPerBtc = 1) =>
+      /* Round without decimals since we're returning cents: */
+      round((v / 1_000_000_000) * centsPerBtc),
   },
   [CurrencyUnit.SATOSHI]: {
-    [CurrencyUnit.BITCOIN]: (v: number) => Math.round(v / 100_000_000),
-    [CurrencyUnit.MICROBITCOIN]: (v: number) => Math.round(v / 100),
-    [CurrencyUnit.MILLIBITCOIN]: (v: number) => Math.round(v / 100_000),
+    [CurrencyUnit.BITCOIN]: (v: number) => v / 100_000_000,
+    [CurrencyUnit.MICROBITCOIN]: (v: number) => v / 100,
+    [CurrencyUnit.MILLIBITCOIN]: (v: number) => v / 100_000,
     [CurrencyUnit.MILLISATOSHI]: (v: number) => v * 1000,
     [CurrencyUnit.NANOBITCOIN]: (v: number) => v * 10,
     [CurrencyUnit.SATOSHI]: (v: number) => v,
+    [CurrencyUnit.USD]: (v: number, centsPerBtc = 1) =>
+      /* Round without decimals since we're returning cents: */
+      round((v / 100_000_000) * centsPerBtc),
+  },
+  [CurrencyUnit.USD]: {
+    [CurrencyUnit.BITCOIN]: (v: number, centsPerBtc = 1) => v / centsPerBtc,
+    [CurrencyUnit.MICROBITCOIN]: (v: number, centsPerBtc = 1) =>
+      (v / centsPerBtc) * 1_000_000,
+    [CurrencyUnit.MILLIBITCOIN]: (v: number, centsPerBtc = 1) =>
+      (v / centsPerBtc) * 1_000,
+    [CurrencyUnit.MILLISATOSHI]: (v: number, centsPerBtc = 1) =>
+      (v / centsPerBtc) * 100_000_000_000,
+    [CurrencyUnit.NANOBITCOIN]: (v: number, centsPerBtc = 1) =>
+      (v / centsPerBtc) * 1_000_000_000,
+    [CurrencyUnit.SATOSHI]: (v: number, centsPerBtc = 1) =>
+      (v / centsPerBtc) * 100_000_000,
+    [CurrencyUnit.USD]: (v: number) => v,
   },
 };
 
-export const convertCurrencyAmount = (
-  from: CurrencyAmount,
+export function convertCurrencyAmountValue(
+  fromUnit: CurrencyUnit,
   toUnit: CurrencyUnit,
-): CurrencyAmount => {
+  amount: number,
+  centsPerBtc = 1,
+): number {
   if (
-    from.originalUnit === CurrencyUnit.FUTURE_VALUE ||
-    from.originalUnit === CurrencyUnit.USD ||
-    toUnit === CurrencyUnit.FUTURE_VALUE ||
-    toUnit === CurrencyUnit.USD
+    fromUnit === CurrencyUnit.FUTURE_VALUE ||
+    toUnit === CurrencyUnit.FUTURE_VALUE
   ) {
     throw new LightsparkException("CurrencyError", `Unsupported CurrencyUnit.`);
   }
 
-  const conversionFn = CONVERSION_MAP[from.originalUnit][toUnit];
+  if (fromUnit === toUnit) {
+    return amount;
+  }
+
+  const conversionFn = CONVERSION_MAP[fromUnit][toUnit];
   if (!conversionFn) {
     throw new LightsparkException(
       "CurrencyError",
-      `Cannot convert from ${from.originalUnit} to ${toUnit}`,
+      `Cannot convert from ${fromUnit} to ${toUnit}`,
     );
   }
+
+  return conversionFn(amount, centsPerBtc);
+}
+
+export const convertCurrencyAmount = (
+  from: CurrencyAmountType,
+  toUnit: CurrencyUnit,
+): CurrencyAmountType => {
+  const value = convertCurrencyAmountValue(
+    from.originalUnit,
+    toUnit,
+    from.originalValue,
+  );
   return {
     ...from,
     preferredCurrencyUnit: toUnit,
-    preferredCurrencyValueApprox: conversionFn(from.originalValue),
-    preferredCurrencyValueRounded: conversionFn(from.originalValue),
+    preferredCurrencyValueApprox: value,
+    preferredCurrencyValueRounded: value,
+  };
+};
+
+export type CurrencyMap = {
+  sats: number;
+  msats: number;
+  btc: number;
+  [CurrencyUnit.BITCOIN]: number;
+  [CurrencyUnit.SATOSHI]: number;
+  [CurrencyUnit.MILLISATOSHI]: number;
+  [CurrencyUnit.MICROBITCOIN]: number;
+  [CurrencyUnit.MILLIBITCOIN]: number;
+  [CurrencyUnit.NANOBITCOIN]: number;
+  [CurrencyUnit.USD]: number;
+  [CurrencyUnit.FUTURE_VALUE]: number;
+  formatted: {
+    sats: string;
+    msats: string;
+    btc: string;
+    [CurrencyUnit.BITCOIN]: string;
+    [CurrencyUnit.SATOSHI]: string;
+    [CurrencyUnit.MILLISATOSHI]: string;
+    [CurrencyUnit.MILLIBITCOIN]: string;
+    [CurrencyUnit.MICROBITCOIN]: string;
+    [CurrencyUnit.NANOBITCOIN]: string;
+    [CurrencyUnit.USD]: string;
+    [CurrencyUnit.FUTURE_VALUE]: string;
+  };
+  isZero: boolean;
+  isLessThan: (other: CurrencyMap | CurrencyAmountObj | number) => boolean;
+  isGreaterThan: (other: CurrencyMap | CurrencyAmountObj | number) => boolean;
+  isEqualTo: (other: CurrencyMap | CurrencyAmountObj | number) => boolean;
+  type: "CurrencyMap";
+};
+
+export type CurrencyAmountObj = {
+  /* Technically the generated graphql schema has value as `any` but it's always a number.
+     We are intentionally widening the type here to allow for more forgiving input: */
+  value?: number | string | null;
+  /* assume satoshi if not provided */
+  unit?: CurrencyUnit;
+  __typename?: "CurrencyAmount";
+};
+
+export type CurrencyAmountArg =
+  | CurrencyAmountObj
+  | CurrencyAmountType
+  | undefined
+  | null;
+
+export function isCurrencyAmountObj(arg: unknown): arg is CurrencyAmountObj {
+  return (
+    typeof arg === "object" && arg !== null && "value" in arg && "unit" in arg
+  );
+}
+
+export function isCurrencyAmount(arg: unknown): arg is CurrencyAmountType {
+  return (
+    typeof arg === "object" &&
+    arg !== null &&
+    "originalValue" in arg &&
+    "originalUnit" in arg &&
+    "preferredCurrencyUnit" in arg &&
+    "preferredCurrencyValueRounded" in arg &&
+    "preferredCurrencyValueApprox" in arg
+  );
+}
+
+function asNumber(value: string | number | null | undefined) {
+  if (typeof value === "string") {
+    return Number(value);
+  }
+  return value || 0;
+}
+
+function getCurrencyAmount(currencyAmountArg: CurrencyAmountArg) {
+  let value = 0;
+  let unit = undefined;
+
+  if (isCurrencyAmountObj(currencyAmountArg)) {
+    value = asNumber(currencyAmountArg.value);
+    unit = currencyAmountArg.unit;
+  } else if (isCurrencyAmount(currencyAmountArg)) {
+    value = currencyAmountArg.originalValue;
+    unit = currencyAmountArg.originalUnit;
+  }
+
+  return {
+    value: asNumber(value),
+    unit: unit || CurrencyUnit.SATOSHI,
+  };
+}
+
+export function mapCurrencyAmount(
+  currencyAmountArg: CurrencyAmountArg,
+  centsPerBtc = 1,
+): CurrencyMap {
+  const { value, unit } = getCurrencyAmount(currencyAmountArg);
+
+  const convert = convertCurrencyAmountValue;
+  const sats = convert(unit, CurrencyUnit.SATOSHI, value, centsPerBtc);
+  const btc = convert(unit, CurrencyUnit.BITCOIN, value, centsPerBtc);
+  const msats = convert(unit, CurrencyUnit.MILLISATOSHI, value, centsPerBtc);
+  const usd = convert(unit, CurrencyUnit.USD, value, centsPerBtc);
+  const mibtc = convert(unit, CurrencyUnit.MICROBITCOIN, value, centsPerBtc);
+  const mlbtc = convert(unit, CurrencyUnit.MILLIBITCOIN, value, centsPerBtc);
+  const nbtc = convert(unit, CurrencyUnit.NANOBITCOIN, value, centsPerBtc);
+
+  const mapWithCurrencyUnits = {
+    [CurrencyUnit.BITCOIN]: btc,
+    [CurrencyUnit.SATOSHI]: sats,
+    [CurrencyUnit.MILLISATOSHI]: msats,
+    [CurrencyUnit.USD]: usd,
+    [CurrencyUnit.MICROBITCOIN]: mibtc,
+    [CurrencyUnit.MILLIBITCOIN]: mlbtc,
+    [CurrencyUnit.NANOBITCOIN]: nbtc,
+    [CurrencyUnit.FUTURE_VALUE]: NaN,
+    formatted: {
+      [CurrencyUnit.BITCOIN]: formatCurrencyStr({
+        value: btc,
+        unit: CurrencyUnit.BITCOIN,
+      }),
+      [CurrencyUnit.SATOSHI]: formatCurrencyStr({
+        value: sats,
+        unit: CurrencyUnit.SATOSHI,
+      }),
+      [CurrencyUnit.MILLISATOSHI]: formatCurrencyStr({
+        value: msats,
+        unit: CurrencyUnit.MILLISATOSHI,
+      }),
+      [CurrencyUnit.MICROBITCOIN]: formatCurrencyStr({
+        value: mibtc,
+        unit: CurrencyUnit.MICROBITCOIN,
+      }),
+      [CurrencyUnit.MILLIBITCOIN]: formatCurrencyStr({
+        value: mlbtc,
+        unit: CurrencyUnit.MILLIBITCOIN,
+      }),
+      [CurrencyUnit.NANOBITCOIN]: formatCurrencyStr({
+        value: nbtc,
+        unit: CurrencyUnit.NANOBITCOIN,
+      }),
+      [CurrencyUnit.USD]: formatCurrencyStr({
+        value: usd,
+        unit: CurrencyUnit.USD,
+      }),
+      [CurrencyUnit.FUTURE_VALUE]: "-",
+    },
+  };
+
+  return {
+    ...mapWithCurrencyUnits,
+    btc,
+    sats,
+    msats,
+    isZero: msats === 0,
+    isLessThan: (other: CurrencyMap | CurrencyAmountObj | number) => {
+      if (isNumber(other)) {
+        return msats < other;
+      }
+      if (isCurrencyAmountObj(other)) {
+        other = mapCurrencyAmount(other);
+      }
+      return msats < other.msats;
+    },
+    isGreaterThan: (other: CurrencyMap | CurrencyAmountObj | number) => {
+      if (isNumber(other)) {
+        return msats > other;
+      }
+      if (isCurrencyAmountObj(other)) {
+        other = mapCurrencyAmount(other);
+      }
+      return msats > other.msats;
+    },
+    isEqualTo: (other: CurrencyMap | CurrencyAmountObj | number) => {
+      if (isNumber(other)) {
+        return msats === other;
+      }
+      if (isCurrencyAmountObj(other)) {
+        other = mapCurrencyAmount(other);
+      }
+      return msats === other.msats;
+    },
+    formatted: {
+      ...mapWithCurrencyUnits.formatted,
+      btc: mapWithCurrencyUnits.formatted[CurrencyUnit.BITCOIN],
+      sats: mapWithCurrencyUnits.formatted[CurrencyUnit.SATOSHI],
+      msats: mapWithCurrencyUnits.formatted[CurrencyUnit.MILLISATOSHI],
+    },
+    type: "CurrencyMap" as const,
   };
+}
+
+export const isCurrencyMap = (
+  currencyMap: unknown,
+): currencyMap is CurrencyMap =>
+  typeof currencyMap === "object" &&
+  currencyMap !== null &&
+  "type" in currencyMap &&
+  typeof currencyMap.type === "string" &&
+  currencyMap.type === "CurrencyMap";
+
+export const abbrCurrencyUnit = (unit: CurrencyUnit) => {
+  switch (unit) {
+    case CurrencyUnit.BITCOIN:
+      return "BTC";
+    case CurrencyUnit.SATOSHI:
+      return "SAT";
+    case CurrencyUnit.MILLISATOSHI:
+      return "MSAT";
+    case CurrencyUnit.USD:
+      return "USD";
+  }
+  return "Unsupported CurrencyUnit";
 };
+
+export function formatCurrencyStr(
+  amount: CurrencyAmountArg,
+  maxFractionDigits?: number,
+  compact?: boolean,
+  showBtcSymbol = false,
+  options: Intl.NumberFormatOptions = {},
+) {
+  const currencyAmount = getCurrencyAmount(amount);
+  let { value: num } = currencyAmount;
+  const { unit } = currencyAmount;
+
+  /* Currencies should always be represented in the smallest unit, e.g. cents for USD: */
+  if (unit === CurrencyUnit.USD) {
+    num = num / 100;
+  }
+
+  function getDefaultMaxFractionDigits(defaultDigits: number) {
+    return typeof maxFractionDigits === "undefined"
+      ? compact
+        ? 1
+        : defaultDigits
+      : maxFractionDigits;
+  }
+
+  // Symbol handled by toLocaleString for USD. These rely on the LightsparkIcons font
+  const symbol = !showBtcSymbol
+    ? ""
+    : unit === CurrencyUnit.BITCOIN
+    ? ""
+    : unit === CurrencyUnit.SATOSHI
+    ? ""
+    : "";
+
+  const currentLocale = getCurrentLocale();
+
+  switch (unit) {
+    case CurrencyUnit.BITCOIN:
+      return `${symbol}${num.toLocaleString(currentLocale, {
+        notation: compact ? ("compact" as const) : undefined,
+        maximumFractionDigits: getDefaultMaxFractionDigits(4),
+        ...options,
+      })}`;
+    case CurrencyUnit.MILLISATOSHI:
+    case CurrencyUnit.SATOSHI:
+    case CurrencyUnit.MICROBITCOIN:
+    case CurrencyUnit.MILLIBITCOIN:
+    case CurrencyUnit.NANOBITCOIN:
+    default:
+      return `${symbol}${num.toLocaleString(currentLocale, {
+        notation: compact ? ("compact" as const) : undefined,
+        maximumFractionDigits: getDefaultMaxFractionDigits(0),
+        ...options,
+      })}`;
+    case CurrencyUnit.USD:
+      return num.toLocaleString(currentLocale, {
+        style: "currency",
+        currency: defaultCurrencyCode,
+        notation: compact ? ("compact" as const) : undefined,
+        maximumFractionDigits: getDefaultMaxFractionDigits(2),
+        ...options,
+      });
+  }
+}
+
+export function localeToCurrencySymbol(locale: string) {
+  const currencyCode = localeToCurrencyCode(locale);
+  const formatted = new Intl.NumberFormat(locale, {
+    style: "currency",
+    currency: currencyCode,
+    useGrouping: false, // to avoid thousands separators
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+  }).format(0);
+
+  // Remove numeric and non-breaking space characters to extract the currency symbol
+  const symbol = formatted.replace(/[0-9\s\u00a0]/g, "");
+  return symbol;
+}

package/src/utils/index.ts

@@ -6,6 +6,9 @@ export * from "./currency.js";
 export * from "./environment.js";
 export * from "./errors.js";
 export * from "./hex.js";
+export * from "./locale.js";
+export * from "./localeToCurrencyCodes.js";
+export * from "./numbers.js";
 export * from "./pollUntil.js";
 export * from "./sleep.js";
 export * from "./types.js";

package/src/utils/locale.ts

@@ -0,0 +1,3 @@
+export function getCurrentLocale() {
+  return Intl.NumberFormat().resolvedOptions().locale;
+}