monetra 2.0.0 → 2.2.0

package/dist/format/parser.d.ts

@@ -0,0 +1,53 @@
+import { Currency } from "../currency/Currency";
+/**
+ * Options for locale-aware parsing.
+ */
+export interface LocaleParseOptions {
+    /**
+     * The locale to use for parsing (e.g., "en-US", "de-DE").
+     * Used to detect decimal and grouping separators.
+     */
+    locale: string;
+}
+/**
+ * Parses a locale-formatted string into a normalized decimal string.
+ *
+ * Handles locale-specific decimal separators (e.g., comma in German "1.234,56")
+ * and grouping separators (e.g., period in German "1.234").
+ *
+ * @param amount - The locale-formatted amount string (e.g., "1,234.56" or "1.234,56").
+ * @param options - The locale options.
+ * @returns A normalized decimal string (e.g., "1234.56").
+ * @example
+ * parseLocaleString("1.234,56", { locale: "de-DE" }); // "1234.56"
+ * parseLocaleString("1,234.56", { locale: "en-US" }); // "1234.56"
+ */
+export declare function parseLocaleString(amount: string, options: LocaleParseOptions): string;
+/**
+ * Parses a locale-formatted amount string and converts it to Money minor units.
+ *
+ * This is a convenience function that combines locale parsing with currency validation.
+ *
+ * @param amount - The locale-formatted amount string.
+ * @param currency - The currency to validate against.
+ * @param options - The locale options.
+ * @returns The amount in minor units as a BigInt.
+ * @throws {InvalidPrecisionError} If the precision exceeds the currency's decimals.
+ * @example
+ * parseLocaleToMinor("1.234,56", EUR, { locale: "de-DE" }); // 123456n
+ */
+export declare function parseLocaleToMinor(amount: string, currency: Currency, options: LocaleParseOptions): bigint;
+/**
+ * Parses a string representation of a major unit amount into minor units.
+ *
+ * Validates the input format to ensure it is a valid decimal number without
+ * scientific notation or ambiguous characters. Checks that the precision
+ * does not exceed the currency's allowed decimals.
+ *
+ * @param amount - The amount string (e.g., "10.50").
+ * @param currency - The currency to validate against.
+ * @returns The amount in minor units as a BigInt.
+ * @throws {Error} If the format is invalid (scientific notation, non-numeric chars).
+ * @throws {InvalidPrecisionError} If the precision exceeds the currency's decimals.
+ */
+export declare function parseToMinor(amount: string, currency: Currency): bigint;