Skip to content

FormatterService

katanakit-js / FormatterService

Defined in: core/services/formatter.service.ts:29

FormatterService — Singleton facade over Intl.NumberFormat, locale-aware casing and JSON.

Applies the Singleton pattern (one shared instance via FormatterService.getInstance) and the Facade pattern: each public method hides the Intl/JSON details behind one call. Everything is pure — no state, no I/O — so the instance is safe to share across environments (Node, Bun, browser, SSR).

Every public method uses the use* prefix per CONTRIBUTING.md; the module level use* functions below are thin wrappers kept for call-site ergonomics.

import { useFormatNumber } from "katanakit-js";
useFormatNumber(1234.5, "en", 2); // "1,234.50"
useCapitalize(text, locale?): string;

Defined in: core/services/formatter.service.ts:132

Pure: capitalizes the first character; leaves the rest unchanged.

Parameter Type Default value Description
text string undefined The string to capitalize.
locale? "en" | "es" | "fr" | "de" | "it" | "pt" | "ja" | "zh" "en" BCP 47 locale tag. Defaults to "en".

string

The string with its first character upper-cased.

import { useCapitalize } from "katanakit-js";
useCapitalize("hello world"); // "Hello world"

IFormatterService.useCapitalize


useFormatCurrency(options): string;

Defined in: core/services/formatter.service.ts:164

Pure: formats an amount as currency.

taxes follows the shared rate convention: percentage (21 → 21%) or decimal fraction (0.21 → 21%). Values > 1 are percentages; values in (0, 1] are fractions.

By default the fraction digits are the currency’s own ("¥100", "$1.00"), exactly as Intl defines them. Pass digits to pin an exact count — digits: 2 prints two decimals even for zero-decimal currencies ("¥100.00").

Parameter Type Description
options { amount: number; currency?: | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR"; digits?: number; locale?: "en" | "es" | "fr" | "de" | "it" | "pt" | "ja" | "zh"; taxes?: number; } Currency formatting options.
options.amount? number -
options.currency? | "USD" | "EUR" | "GBP" | "JPY" | "CHF" | "CAD" | "AUD" | "NZD" | "MXN" | "BRL" | "ARS" | "COP" | "CLP" | "SEK" | "NOK" | "DKK" | "PLN" | "CZK" | "HUF" | "RON" | "TRY" | "ISK" | "CNY" | "HKD" | "SGD" | "INR" | "KRW" | "THB" | "IDR" | "MYR" | "PHP" | "ILS" | "ZAR" -
options.digits? number Exact number of fraction digits in the output. Omit it to keep each currency’s own digits as Intl defines them ("¥100", "$1.00"); pass 2 to pin exactly two decimals ("¥100.00").
options.locale? "en" | "es" | "fr" | "de" | "it" | "pt" | "ja" | "zh" -
options.taxes? number Tax rate: percentage when > 1 (e.g. 21 → 21%), or decimal fraction when in (0, 1] (e.g. 0.21 → 21%). Prefer a fraction for rates ≤ 1%.

string

The formatted currency string.

import { useFormatCurrency } from "katanakit-js";
useFormatCurrency({ amount: 100, currency: "USD" }); // "$100.00"
useFormatCurrency({ amount: 100, taxes: 21 }); // "$121.00"
useFormatCurrency({ amount: 100, taxes: 0.21, locale: "es" }); // "121,00 €"
useFormatCurrency({ amount: 100, currency: "JPY" }); // "¥100"
useFormatCurrency({ amount: 100, currency: "JPY", digits: 2 }); // "¥100.00"

IFormatterService.useFormatCurrency


useFormatNumber(
value,
locale?,
digits?
): string;

Defined in: core/services/formatter.service.ts:74

Pure number formatter over Intl.NumberFormat.

Parameter Type Default value Description
value number undefined The number to format.
locale? "en" | "es" | "fr" | "de" | "it" | "pt" | "ja" | "zh" "en" BCP 47 locale tag. Defaults to "en".
digits? number 2 Maximum and minimum fraction digits. Defaults to 2.

string

The formatted number string.

import { useFormatNumber } from "katanakit-js";
useFormatNumber(1234.5, "en", 2); // "1,234.50"
useFormatNumber(1234.5, "de", 2); // "1.234,50"

IFormatterService.useFormatNumber


useJsonParse<T>(json): T;

Defined in: core/services/formatter.service.ts:246

Pure: parse JSON (throws on invalid input — same as JSON.parse).

Type Parameter Default type Description
T unknown Expected parsed shape.
Parameter Type Description
json string The JSON string to parse.

T

The parsed value typed as T.

import { useJsonParse } from "katanakit-js";
const obj = useJsonParse<{ a: number }>('{"a":1}');
// { a: 1 }

IFormatterService.useJsonParse


useJsonStringify(data): string;

Defined in: core/services/formatter.service.ts:227

Pure: pretty-print JSON (3-space indent).

Parameter Type Description
data unknown The value to serialize.

string

The indented JSON string.

import { useJsonStringify } from "katanakit-js";
useJsonStringify({ a: 1 });
// '{\n "a": 1\n}'

IFormatterService.useJsonStringify


useLowerCase(text, locale?): string;

Defined in: core/services/formatter.service.ts:114

Pure: locale-aware lower case (trims whitespace).

Parameter Type Default value Description
text string undefined The string to transform.
locale? "en" | "es" | "fr" | "de" | "it" | "pt" | "ja" | "zh" "en" BCP 47 locale tag. Defaults to "en".

string

The lower-cased, trimmed string.

import { useLowerCase } from "katanakit-js";
useLowerCase("HELLO"); // "hello"

IFormatterService.useLowerCase


useSalePrice(options): SalePrice;

Defined in: core/services/formatter.service.ts:203

Pure: applies a discount to a price and reports what was taken off.

discount follows the same rate convention as taxes in FormatterService.useFormatCurrency: percentage (40 → 40%) or decimal fraction (0.4 → 40%).

The returned salePrice is unrounded, so it survives markup chains (10% + 20% of the same base) without accumulating error; pass it straight to FormatterService.useFormatCurrency to get the digits the currency demands. Only percentOff is rounded, because it exists to be displayed.

Parameter Type Description
options { discount: number; price: number; } Price and discount rate.
options.discount? number Discount rate: percentage when > 1 (e.g. 40 → 40%), or decimal fraction when in (0, 1] (e.g. 0.4 → 40%). Same convention as taxes.
options.price? number Regular price, before the discount.

SalePrice

The regular price, the discounted price and the rounded percentage.

import { useFormatCurrency, useSalePrice } from "katanakit-js";
const sale = useSalePrice({ price: 29.99, discount: 40 });
// { price: 29.99, salePrice: 17.994, percentOff: 40 }
useFormatCurrency({ amount: sale.salePrice, currency: "EUR", locale: "es" }); // "17,99 €"

IFormatterService.useSalePrice


useUpperCase(text, locale?): string;

Defined in: core/services/formatter.service.ts:96

Pure: locale-aware upper case (trims whitespace).

Parameter Type Default value Description
text string undefined The string to transform.
locale? "en" | "es" | "fr" | "de" | "it" | "pt" | "ja" | "zh" "en" BCP 47 locale tag. Defaults to "en".

string

The upper-cased, trimmed string.

import { useUpperCase } from "katanakit-js";
useUpperCase("hello"); // "HELLO"
useUpperCase("straße", "de"); // "STRASSE"

IFormatterService.useUpperCase


static getInstance(): FormatterService;

Defined in: core/services/formatter.service.ts:36

Returns the shared instance (Singleton).

FormatterService