@ekaone/rounded

Lightweight, zero-dependency rounding library for finance and payments.

Features

✅ Half Up — standard receipt/POS rounding
✅ Banker's Rounding — round half to even, reduces cumulative bias
✅ Cash Rounding — nearest 0.05 / 0.10 / 0.25 etc.
✅ Currency-aware — correct decimal precision per ISO 4217 code
✅ Null-safe — invalid inputs return null, never throw
✅ Float-safe — guards against 0.1 + 0.2 drift
✅ Zero dependencies
✅ Dual ESM + CJS output with full TypeScript types

Installation

npm install @ekaone/rounded
# or
yarn add @ekaone/rounded
# or
pnpm add @ekaone/rounded

Quick Start

Core rounding

import rounded from "@ekaone/rounded";

rounded(2.345)                         // → 2.35  (halfUp, 2dp default)
rounded(2.345, { precision: 2 })       // → 2.35
rounded(2.345, { method: "bankers" })  // → 2.34
rounded(NaN)                           // → null
rounded(null)                          // → null
rounded(Infinity)                      // → null

Cash rounding

rounded.cash(1.03)                      // → 1.05  (default nearest: 0.05)
rounded.cash(1.02)                      // → 1.00
rounded.cash(1.07, { nearest: 0.10 })  // → 1.10
rounded.cash(1.13, { nearest: 0.25 })  // → 1.25

Currency-aware rounding

rounded.currency(10.1265, "USD")                         // → 10.13
rounded.currency(1500.5,  "JPY")                         // → 1501
rounded.currency(10.1265, "KWD")                         // → 10.127
rounded.currency(10.125,  "USD", { method: "bankers" })  // → 10.12

API

`rounded(value, options?)` — default export

The main entry point. Rounds a number using the specified method and precision.

rounded(value: unknown, options?: RoundedOptions): number | null

Parameter	Type	Default	Description
`value`	`unknown`	—	The number to round
`options.precision`	`number`	`2`	Number of decimal places
`options.method`	`RoundingMethod`	`"halfUp"`	Rounding algorithm to use

Returns null if value is NaN, null, undefined, Infinity, or -Infinity.

rounded(2.345)                                      // → 2.35
rounded(2.345, { precision: 4 })                    // → 2.345
rounded(2.345, { method: "bankers" })               // → 2.34
rounded(2.345, { precision: 2, method: "bankers" }) // → 2.34
rounded(NaN)                                        // → null
rounded(null)                                       // → null

`rounded.cash(value, options?)` — cash rounding

Rounds to the nearest physical denomination. Useful when a currency has no low-denomination coins (e.g. Sweden, Australia, New Zealand).

rounded.cash(value: number, options?: CashOptions): number | null

Parameter	Type	Default	Description
`value`	`number`	—	The amount to round
`options.nearest`	`number`	`0.05`	The denomination increment to round toward

Returns null if value is invalid or if nearest is 0, negative, or invalid.

rounded.cash(1.03)                      // → 1.05
rounded.cash(1.02)                      // → 1.00
rounded.cash(1.07, { nearest: 0.10 })  // → 1.10
rounded.cash(1.12, { nearest: 0.25 })  // → 1.00
rounded.cash(1.13, { nearest: 0.25 })  // → 1.25
rounded.cash(1.49, { nearest: 1 })     // → 1.00
rounded.cash(1.50, { nearest: 1 })     // → 2.00
rounded.cash(NaN)                      // → null

`rounded.currency(value, code, options?)` — currency-aware rounding

Rounds a value to the correct number of decimal places for a given ISO 4217 currency code. Precision is looked up automatically from the built-in currency map.

rounded.currency(value: number, code: string, options?: CurrencyOptions): number | null

Parameter	Type	Default	Description
`value`	`number`	—	The amount to round
`code`	`string`	—	ISO 4217 currency code (case-insensitive)
`options.method`	`CurrencyRoundingMethod`	`"halfUp"`	Rounding algorithm to use

Returns null if value is invalid or if code is not a recognised currency.

rounded.currency(10.1265, "USD")                         // → 10.13   (2dp)
rounded.currency(10.1265, "usd")                         // → 10.13   (case-insensitive)
rounded.currency(1500.5,  "JPY")                         // → 1501    (0dp)
rounded.currency(10.1265, "KWD")                         // → 10.127  (3dp)
rounded.currency(10.125,  "USD", { method: "bankers" })  // → 10.12
rounded.currency(10.135,  "USD", { method: "bankers" })  // → 10.14
rounded.currency(10.5,    "XYZ")                         // → null    (unknown code)

Named exports — low-level functions

All core functions are also exported individually for direct use without the rounded wrapper.

import { halfUp, bankers, cash, currency, CURRENCY_PRECISION } from "@ekaone/rounded";

`halfUp(value, precision)`

halfUp(value: number, precision: number): number

Standard half-up rounding. Ties (x.5) always round toward positive infinity. Does not perform input validation — pass a clean number.

halfUp(2.345, 2)   // → 2.35
halfUp(2.344, 2)   // → 2.34
halfUp(1.005, 2)   // → 1.01  (float-safe)
halfUp(-2.345, 2)  // → -2.34 (toward +infinity)
halfUp(2.5, 0)     // → 3
halfUp(1.23456, 4) // → 1.2346

`bankers(value, precision)`

bankers(value: number, precision: number): number

Banker's rounding (round half to even). Ties round to whichever neighbour has an even last digit, eliminating upward bias across large transaction sets. Does not perform input validation.

bankers(2.345, 2)  // → 2.34  (4 is even — stay)
bankers(2.355, 2)  // → 2.36  (5 is odd  — round up to 6)
bankers(2.5, 0)    // → 2     (2 is even — stay)
bankers(3.5, 0)    // → 4     (4 is even — round up)
bankers(-2.5, 0)   // → -2    (-2 is even — stay)
bankers(-3.5, 0)   // → -4    (-4 is even — round up)

`cash(value, options?)`

See rounded.cash — this is the same function.

`currency(value, code, options?)`

See rounded.currency — this is the same function.

`CURRENCY_PRECISION`

A read-only record mapping uppercase ISO 4217 currency codes to their decimal precision.

import { CURRENCY_PRECISION } from "@ekaone/rounded";

CURRENCY_PRECISION["USD"]  // → 2
CURRENCY_PRECISION["JPY"]  // → 0
CURRENCY_PRECISION["KWD"]  // → 3

Types & Interfaces

All types are exported and fully available in TypeScript projects.

import type {
  RoundingMethod,
  RoundedOptions,
  CurrencyRoundingMethod,
  CurrencyOptions,
  CurrencyCode,
} from "@ekaone/rounded";

`RoundingMethod`

The rounding algorithm used by rounded().

type RoundingMethod = "halfUp" | "bankers";

Value	Behaviour
`"halfUp"`	Ties round toward positive infinity (default)
`"bankers"`	Ties round to nearest even digit (reduces bias)

`RoundedOptions`

Options accepted by the main rounded() function.

interface RoundedOptions {
  /** Number of decimal places to round to. Defaults to 2. */
  precision?: number;

  /** Rounding algorithm. Defaults to "halfUp". */
  method?: RoundingMethod;
}

`CurrencyRoundingMethod`

The rounding algorithm used by currency(). Identical in values to RoundingMethod.

type CurrencyRoundingMethod = "halfUp" | "bankers";

`CurrencyOptions`

Options accepted by rounded.currency() and the named currency() export.

interface CurrencyOptions {
  /** Rounding algorithm. Defaults to "halfUp". */
  method?: CurrencyRoundingMethod;
}

`CashOptions`

Options accepted by rounded.cash() and the named cash() export.

interface CashOptions {
  /** The denomination to round toward. Must be a positive number. Defaults to 0.05. */
  nearest?: number;
}

`CurrencyCode`

A union type of all supported ISO 4217 currency code strings, derived directly from the CURRENCY_PRECISION map.

type CurrencyCode = keyof typeof CURRENCY_PRECISION;
// → "USD" | "EUR" | "JPY" | "KWD" | ... (30+ codes)

Use this to constrain function arguments in your own code:

import type { CurrencyCode } from "@ekaone/rounded";
import { currency } from "@ekaone/rounded";

function formatAmount(value: number, code: CurrencyCode): string {
  const result = currency(value, code);
  return result !== null ? `${code} ${result.toFixed(2)}` : "—";
}

Null-safety contract

Every public function that accepts user-facing input returns number | null. The library never throws. A null return always means the input was invalid.

Input	Returns
`NaN`	`null`
`null`	`null`
`undefined`	`null`
`Infinity`	`null`
`-Infinity`	`null`
Unknown currency	`null`
`nearest <= 0`	`null`
Valid `number`	`number`

The low-level named exports (halfUp, bankers) skip the null guard for performance. Only use them when you have already validated the input.

Supported currencies

Decimals	Currencies
2	AED, AUD, BRL, CAD, CHF, CNY, EUR, GBP, HKD, ILS, INR, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY, USD, ZAR
0	BIF, CLP, DJF, GNF, IDR, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF
3	BHD, IQD, JOD, KWD, LYD, OMR, TND

Rounding methods explained

Method	Tie behaviour	Best for
`halfUp`	0.5 always rounds toward +∞	Receipts, POS, customer-facing totals
`bankers`	0.5 rounds to nearest even digit	High-volume batch transactions, accounting

Why Banker's Rounding? With halfUp, every tie rounds the same direction, introducing a small but consistent upward bias. Over thousands of transactions this accumulates. bankers distributes ties evenly between up and down, keeping running totals statistically neutral.

Float-safety

JavaScript's IEEE 754 floats produce surprising results like 1.005 * 100 = 100.49999..., which would cause 1.005 to incorrectly round down to 1.00. This library uses a string-based decimal shift strategy — converting via toPrecision(15) and manipulating digit positions as strings before any arithmetic — so tie values are always exact.

rounded(1.005)  // → 1.01  ✓  (naive Math.round(1.005 * 100) / 100 → 1.00 ✗)
rounded(1.045)  // → 1.05  ✓
rounded(1.055)  // → 1.06  ✓

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

@ekaone/rounded

Features

Installation

Quick Start

Core rounding

Cash rounding

Currency-aware rounding

API

rounded(value, options?) — default export

rounded.cash(value, options?) — cash rounding

rounded.currency(value, code, options?) — currency-aware rounding

Named exports — low-level functions

halfUp(value, precision)

bankers(value, precision)

cash(value, options?)

currency(value, code, options?)

CURRENCY_PRECISION

Types & Interfaces

RoundingMethod

RoundedOptions

CurrencyRoundingMethod

CurrencyOptions

CashOptions

CurrencyCode

Null-safety contract

Supported currencies

Rounding methods explained

Float-safety

License

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`rounded(value, options?)` — default export

`rounded.cash(value, options?)` — cash rounding

`rounded.currency(value, code, options?)` — currency-aware rounding

`halfUp(value, precision)`

`bankers(value, precision)`

`cash(value, options?)`

`currency(value, code, options?)`

`CURRENCY_PRECISION`

`RoundingMethod`

`RoundedOptions`

`CurrencyRoundingMethod`

`CurrencyOptions`

`CashOptions`

`CurrencyCode`

Packages