expo-numerator
v0.1.6
Published
Production-grade numeric infrastructure for Expo and React Native.
Maintainers
Readme
expo-numerator
Production-grade numeric infrastructure for Expo and React Native.
expo-numerator provides string-first decimal, money, percent, unit, phone,
IBAN, payment-card display/entry, formatting, parsing, and React Native input APIs
without silent floating-point precision loss.
Install
For Expo apps, use Expo CLI:
npx expo install expo-numeratorFor non-Expo npm workflows:
npm install expo-numeratorQuick Start
Use createNumerator when an app wants one locale-bound facade:
import { createNumerator } from "expo-numerator";
const n = createNumerator({ locale: "tr-TR" });
n.money.format("1234.56", "TRY"); // "₺1.234,56"
n.money.safeParse("₺1.234,56", "TRY").ok; // true
n.decimal.add("999.99", "0.01").value; // "1000.00"
n.unit.formatBestFit("1500", "meter", { scale: 1 }); // "1,5 km"
n.phone.parse("0501 234 56 78").e164; // "+905012345678"Use domain subpaths when a bundle only needs one surface:
import { formatMoney } from "expo-numerator/format";
import { money, toMinorUnits } from "expo-numerator/money";
import { MoneyInput } from "expo-numerator/input";
import { formatPaymentCardSummary } from "expo-numerator/payment-card";
import { parseIban } from "expo-numerator/iban";
import { parsePhone } from "expo-numerator/phone";
formatMoney(money("1234.56", "TRY"), { locale: "tr-TR" });
toMinorUnits("12.34", "USD"); // 1234n
parsePhone("+905012345678").region; // "TR"
formatPaymentCardSummary({ brand: "Visa", last4: "4242" });
parseIban("TR33 0006 1005 1978 6457 8413 26").countryCode; // "TR"For React Native money input, start with the ready-made component:
import { MoneyInput } from "expo-numerator";
<MoneyInput
locale="tr-TR"
currency="TRY"
entryMode="liveGroupedEndLocked"
onValueChange={(value) => {
value?.kind === "money" ? value.amount : null;
}}
/>;For card-on-file display and native entry, use the provider-neutral payment card subpath. Prefer provider-owned native fields for production collection; the custom input does not tokenize, charge, store card data, or make an app PCI compliant.
import {
PaymentCardInput,
formatPaymentCardSummary,
} from "expo-numerator/payment-card";
formatPaymentCardSummary({ brand: "Visa", last4: "4242" });
<PaymentCardInput />;For international bank-account entry and safe display, use the registry-backed IBAN domain. Checksum success validates syntax only; it does not prove account existence or ownership.
import { IbanInput, maskIban } from "expo-numerator/iban";
maskIban("TR330006100519786457841326");
<IbanInput maskOnBlur />;Documentation
The official consumer documentation lives in docs/:
- Documentation Index
- API Reference
- Usage Guide
- Expo and React Native Integration
- Error Contract
- Currency Registry
- Input Acceptance Matrix
- Payment Card Security
- IBAN
Maintainer and release documentation:
Core Rules
- Pass decimal values as strings for exact precision.
- JavaScript numbers are accepted only for safe integer convenience.
- Use throwing constructors when the call site owns validation.
- Use
safe*APIs for forms, paste handling, API boundaries, and user input. - Import only from
expo-numeratoror public domain subpaths.
Public Subpaths
import { decimal } from "expo-numerator/core";
import { money } from "expo-numerator/money";
import { roundDecimal } from "expo-numerator/rounding";
import { resolveLocale } from "expo-numerator/locale";
import { formatNumber } from "expo-numerator/format";
import { safeParseNumber } from "expo-numerator/parse";
import { convertUnit } from "expo-numerator/unit";
import { parsePhone } from "expo-numerator/phone";
import { NumberInput } from "expo-numerator/input";
import { PaymentCardInput } from "expo-numerator/payment-card";
import { IbanInput } from "expo-numerator/iban";
import { createExpoNumerator } from "expo-numerator/expo";Status
0.1.6 adds provider-neutral payment-card entry and redacted display plus a
registry-backed IBAN domain with parsing, masking, checksum validation,
caret-safe native input, and dedicated release gates while preserving the
existing numeric, phone, and Expo surfaces.
Development
npm run typecheck
npm test -- --runInBand
npm run docs:check
npm run hardeningRepo-local agent guidance lives in AGENTS.md, CLAUDE.md,
.agent/, and skills/README.md. The skills tree is split
into skills/common, skills/consumer, and skills/maintainer.
See docs/RELEASE_CHECKLIST.md for the full release-candidate gate.
