tessl/npm-medusa-core-utils

Core utilities for Medusa e-commerce platform including error handling, DI container, amount calculations, and configuration parsing

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Amount Utilities

Name: tessl/npm-medusa-core-utils
Author: tessl

Currency-aware financial calculation utilities for converting between human-readable display formats and database storage formats, with proper handling of zero-decimal currencies.

Capabilities

Amount Computerization

Converts human-readable amounts to database storage format (typically cents for most currencies).

/**
 * Converts a display amount to database storage format
 * @param amount - The display amount (e.g., 19.99)
 * @param currency - The currency code (e.g., "USD", "EUR", "JPY")
 * @returns The amount in database format (e.g., 1999 for $19.99)
 */
function computerizeAmount(amount: number, currency: string): number;

Usage Examples:

import { computerizeAmount } from "medusa-core-utils";

// Regular currencies (2 decimal places)
const usdAmount = computerizeAmount(19.99, "USD"); // 1999 (cents)
const eurAmount = computerizeAmount(25.50, "EUR"); // 2550 (cents)

// Zero-decimal currencies
const jpyAmount = computerizeAmount(1000, "JPY"); // 1000 (no conversion)
const krwAmount = computerizeAmount(50000, "KRW"); // 50000 (no conversion)

// Store in database
const product = {
  name: "T-Shirt",
  price: computerizeAmount(29.99, "USD"), // Stored as 2999
  currency: "USD"
};

Amount Humanization

Converts database storage amounts back to human-readable display format.

/**
 * Converts a database amount to display format
 * @param amount - The database amount (e.g., 1999)
 * @param currency - The currency code (e.g., "USD", "EUR", "JPY")
 * @returns The display amount (e.g., 19.99 for 1999 cents)
 */
function humanizeAmount(amount: number, currency: string): number;

Usage Examples:

import { humanizeAmount } from "medusa-core-utils";

// Regular currencies (divide by 100)
const displayUSD = humanizeAmount(1999, "USD"); // 19.99
const displayEUR = humanizeAmount(2550, "EUR"); // 25.50

// Zero-decimal currencies (no conversion)
const displayJPY = humanizeAmount(1000, "JPY"); // 1000
const displayKRW = humanizeAmount(50000, "KRW"); // 50000

// Display in UI
const product = await getProduct(id);
const displayPrice = humanizeAmount(product.price, product.currency);
console.log(`Price: ${displayPrice} ${product.currency}`);

Zero-Decimal Currencies

List of currencies that do not use decimal places in their smallest unit.

/**
 * Array of currency codes that use zero decimal places
 * These currencies are not divided by 100 during conversion
 */
const zeroDecimalCurrencies: string[];

The zero-decimal currencies include:

BIF - Burundian Franc
CLP - Chilean Peso
DJF - Djiboutian Franc
GNF - Guinean Franc
JPY - Japanese Yen
KMF - Comorian Franc
KRW - South Korean Won
MGA - Malagasy Ariary
PYG - Paraguayan Guaraní
RWF - Rwandan Franc
UGX - Ugandan Shilling
VND - Vietnamese Đồng
VUV - Vanuatu Vatu
XAF - Central African CFA Franc
XOF - West African CFA Franc
XPF - CFP Franc

Usage Examples:

import { zeroDecimalCurrencies, computerizeAmount, humanizeAmount } from "medusa-core-utils";

// Check if currency is zero-decimal
function isZeroDecimalCurrency(currency: string): boolean {
  return zeroDecimalCurrencies.includes(currency.toLowerCase());
}

// Comprehensive amount handling
function processAmount(amount: number, currency: string) {
  const isZeroDecimal = isZeroDecimalCurrency(currency);
  
  if (isZeroDecimal) {
    console.log(`${currency} is a zero-decimal currency`);
  }
  
  const dbAmount = computerizeAmount(amount, currency);
  const displayAmount = humanizeAmount(dbAmount, currency);
  
  return {
    original: amount,
    database: dbAmount,
    display: displayAmount,
    isZeroDecimal
  };
}

// Examples
processAmount(100, "JPY");  // { original: 100, database: 100, display: 100, isZeroDecimal: true }
processAmount(100, "USD");  // { original: 100, database: 10000, display: 100, isZeroDecimal: false }

Complete Amount Processing Workflow

Usage Examples:

import { computerizeAmount, humanizeAmount, zeroDecimalCurrencies } from "medusa-core-utils";

// Product creation workflow
async function createProduct(productData: {
  name: string;
  price: number;
  currency: string;
}) {
  // Convert display price to database format
  const dbPrice = computerizeAmount(productData.price, productData.currency);
  
  const product = await database.products.create({
    name: productData.name,
    price: dbPrice,  // Stored in cents (or whole units for zero-decimal)
    currency: productData.currency.toUpperCase()
  });
  
  return product;
}

// Product display workflow  
async function getProductForDisplay(productId: string) {
  const product = await database.products.findById(productId);
  
  // Convert database price to display format
  const displayPrice = humanizeAmount(product.price, product.currency);
  
  return {
    ...product,
    displayPrice,
    formattedPrice: `${displayPrice} ${product.currency}`
  };
}

// Bulk price calculations
function calculateTotals(items: Array<{price: number, currency: string, quantity: number}>) {
  return items.map(item => {
    const unitPrice = humanizeAmount(item.price, item.currency);
    const lineTotal = unitPrice * item.quantity;
    const lineTotalDb = computerizeAmount(lineTotal, item.currency);
    
    return {
      ...item,
      unitPrice,
      lineTotal,
      lineTotalDb
    };
  });
}