react-native-format-currency 0.0.4 → 1.0.0

package/README.md

@@ -1,192 +1,143 @@
+<!-- NOTE: Keep this README concise and copy/paste-friendly. -->
+
 # react-native-format-currency
 
-[![version](https://img.shields.io/npm/v/react-native-format-currency.svg)](https://www.npmjs.com/package/react-native-format-currency)
-[![npm](https://img.shields.io/npm/dm/react-native-format-currency.svg)](https://www.npmjs.com/package/react-native-format-currency)
-[![twitter](https://img.shields.io/twitter/follow/AwesomeLabsLLC.svg?style=flat-square&label=Follow%20%40AwesomeLabsLLC&logo=TWITTER&logoColor=FFFFFF&labelColor=00aced&logoWidth=15&color=lightgray)](https://twitter.com/intent/follow?screen_name=AwesomeLabsLLC)
+[![npm version](https://img.shields.io/npm/v/react-native-format-currency.svg)](https://www.npmjs.com/package/react-native-format-currency)
+[![npm downloads](https://img.shields.io/npm/dm/react-native-format-currency.svg)](https://www.npmjs.com/package/react-native-format-currency)
+[![Follow @AwesomeLabsLLC on X](https://img.shields.io/badge/follow-%40AwesomeLabsLLC-00b4d8?logo=x&logoColor=white)](https://x.com/AwesomeLabsLLC)
+
+A lightweight currency formatter for **React Native** and **Expo**. Format amounts using ISO 4217 currency codes with correct symbol placement and common thousands/decimal separator styles.
 
+- **Zero runtime deps** (pure JS/TS)
+- **165+ currencies**
+- **Typed** (TypeScript declarations included)
+- **Fast** (memoized with a small LRU cache)
 
-A lightweight international currency formatter for React Native & Expo (iOS and Android). Check out the [example app](example/) for a working demo.
+## Install
 
-## Installation
 ```sh
-$ yarn add react-native-format-currency
+yarn add react-native-format-currency
 ```
-or
+
 ```sh
-$ npm install react-native-format-currency
+npm install react-native-format-currency
 ```
 
-## Usage
-
-Import library with 
-```js
-import { formatCurrency, getSupportedCurrencies } from "react-native-format-currency";
+```sh
+pnpm add react-native-format-currency
 ```
 
-## Methods
+## Quick start
 
-### `formatCurrency({ amount: _number_, code: _string_})`
+```ts
+import { formatCurrency } from "react-native-format-currency";
 
-```sh
-formatCurrency({ amount: 1234.56, code: "ARS" })
-```
-Formats a currency amount to specified currency code:
-```js
-const [valueFormattedWithSymbol, valueFormattedWithoutSymbol, symbol] = formatCurrency({ amount: 1234.56, code: "ARS" })
+const [withSymbol, withoutSymbol, symbol] = formatCurrency({
+  amount: 1234.56,
+  code: "USD",
+});
+
+// withSymbol: "$1,234.56"
+// withoutSymbol: "1,234.56"
+// symbol: "$"
 ```
 
-__Props__
+## API
+
+### `formatCurrency({ amount, code, returnType? })`
+
+Formats a numeric amount for a given ISO 4217 currency code.
+
+- **Params**
+  - `amount: number`: the numeric amount (negative supported)
+  - `code: string`: ISO 4217 currency code (e.g. `"USD"`, `"EUR"`, `"JPY"`)
+  - `returnType?: "array" | "object"`: optional return format (default: `"array"`)
+- **Returns**
+  - Array (default): `[formattedWithSymbol, formattedWithoutSymbol, symbol]`
+  - Object: `{ formatted, value, symbol }`
 
-| Prop | Type | Default | Note |
-|---|---|---|---|
-| `amount` | `Number` | null | currency amount
-| `code` | `String` | null | 3-letter [ISO 4217 Currency Code](https://en.wikipedia.org/wiki/ISO_4217)
+```ts
+import { formatCurrency } from "react-native-format-currency";
 
-__Returns:__
+// Array format (default)
+formatCurrency({ amount: 1234.56, code: "ARS" });
+// ["$ 1.234,56", "1.234,56", "$"]
 
-Array containing formatted currency string, formatted currency (without symbol), and currency symbol
+formatCurrency({ amount: -99.99, code: "GBP" });
+// ["-£99.99", "-99.99", "£"]
 
-```js
-["$ 1.234,56", "1.234,56", "$"]
+// Object format
+formatCurrency({ amount: 1234.56, code: "USD", returnType: "object" });
+// { formatted: "$1,234.56", value: "1,234.56", symbol: "$" }
 ```
 
+**Notes**
+- Formatting is based on this package's internal currency rules (symbol, separators, symbol position, decimals). It does **not** take a locale argument.
+- For floating-point sensitive values, consider passing integers (e.g. cents) and dividing/rounding prior to formatting.
 
 ### `getSupportedCurrencies()`
+
+Returns all supported currencies as `{ code, name }[]`.
+
+```ts
+import { getSupportedCurrencies } from "react-native-format-currency";
+
+const currencies = getSupportedCurrencies();
+// [{ code: "AED", name: "United Arab Emirates Dirham" }, ...]
 ```
-getSupportedCurrencies()
+
+### Cache helpers
+
+`formatCurrency` memoizes results (LRU, max 100 entries) for speed.
+
+```ts
+import { clearFormatCache, getFormatCacheSize } from "react-native-format-currency";
+
+console.log(getFormatCacheSize());
+clearFormatCache();
 ```
-Returns an array of currencies:
-
-```js
-[
-  { code: "ARS", name: "Argentina Peso" },
-  { code: "AUD", name: "Australia Dollar" },
-  { code: "BGN", name: "Bulgaria Lev" },
-  { code: "BRL", name: "Brazil Real" },
-  { code: "CAD", name: "Canada Dollar" },
-  { code: "CHF", name: "Switzerland Franc" },
-  { code: "CLP", name: "Chile Peso" },
-  { code: "CNY", name: "China Yuan Renminbi" },
-  { code: "COP", name: "Colombia Peso" },
-  { code: "CZK", name: "Czech Republic Koruna" },
-  { code: "DKK", name: "Denmark Krone" },
-  { code: "EUR", name: "Euro Member Countries" },
-  { code: "GBP", name: "United Kingdom Pound" },
-  { code: "HKD", name: "Hong Kong Dollar" },
-    ...
-]
+
+### Currency data and types
+
+```ts
+import type { CurrencyCode, CurrencyConfig, FormatResult, FormatResultObject, SupportedCurrency } from "react-native-format-currency";
+import { CURRENCIES } from "react-native-format-currency";
 ```
 
-## Example
-
-Check out the [example app](example/) for a working demo.
-
-```js
-import { StatusBar } from "expo-status-bar";
-import React, { useState } from "react";
-import {
-  FlatList,
-  SafeAreaView,
-  StyleSheet,
-  Text,
-  TextInput,
-  View,
-} from "react-native";
-import {
-  formatCurrency,
-  getSupportedCurrencies,
-} from "react-native-format-currency";
-
-export default function App() {
-  const [inputValue, setInputValue] = useState("1234.56");
-
-  // get all of the supported currency codes
-  const currencyCodes = getSupportedCurrencies();
-
-  // loop through each currency code and show formatted value
-  const renderItem = ({ item }) => {
-    const [valueFormattedWithSymbol, valueFormattedWithoutSymbol, symbol] =
-      formatCurrency({ amount: Number(inputValue), code: item.code });
-
-    return (
-      <View style={styles.currencyRow}>
-        <Text style={styles.currencyRowText}>
-          {item.code} {symbol}
-        </Text>
-        <Text style={styles.currencyRowText}>{item.name}</Text>
-        <Text style={styles.currencyRowText}>{valueFormattedWithSymbol}</Text>
-      </View>
-    );
-  };
-
-  return (
-    <SafeAreaView style={styles.container}>
-      <View style={styles.inputContainer}>
-        <TextInput
-          style={styles.input}
-          textAlign="center"
-          value={inputValue}
-          onChangeText={(value) => setInputValue(value)}
-          keyboardType="decimal-pad"
-        />
-      </View>
-
-      <FlatList
-        style={styles.scrollView}
-        data={currencyCodes}
-        renderItem={renderItem}
-        keyExtractor={(code) => code.code}
-      />
-      <StatusBar style="auto" />
-    </SafeAreaView>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: "#fff",
-    alignItems: "flex-start",
-  },
-  inputContainer: {
-    flex: 1,
-    alignSelf: "stretch",
-    marginTop: 10,
-    marginBottom: 15,
-  },
-  input: {
-    backgroundColor: "#eee",
-    height: 38,
-    fontSize: 30,
-    fontWeight: "bold",
-  },
-  scrollView: {
-    width: "100%",
-    paddingHorizontal: 5,
-    marginTop: 40,
-    marginBottom: 40,
-  },
-  currencyRow: {
-    flex: 1,
-    flexDirection: "row",
-    justifyContent: "space-between",
-  },
-  currencyRowText: {
-    alignContent: "flex-start",
-    color: "#000",
-    fontSize: 16,
-  },
-});
+- `CURRENCIES`: full currency config map (symbols, separators, etc.)
+- `CurrencyCode`: union of supported ISO currency codes
+- `FormatResult`: array return type `[string, string, string]`
+- `FormatResultObject`: object return type `{ formatted, value, symbol }`
+
+## Example app
+
+The repo includes an Expo example in [`example/`](example/).
+
+```sh
+cd example
+yarn install
+yarn start
 ```
 
+If Expo complains about your Node version, use an LTS-compatible Node version required by the Expo SDK you’re running (see Expo’s docs for the current requirement).
+
+## Development
 
-## Testing
 ```sh
+yarn install
 yarn build
 yarn test
 ```
 
-## Contribute
-Feel free to submit a PR if you'd like to help!
+## Contributing
+
+- Please open an issue (or a PR) for bugs/feature requests.
+- Keep changes small and add/adjust tests where relevant.
+
+## Security
+
+Please **do not** open public issues for security vulnerabilities. Prefer reporting privately via the project’s maintainer contact (see `package.json` / GitHub profile).
 
+## License
 
+MIT — see [`LICENSE`](LICENSE).