@indodev/toolkit 0.3.2 → 0.3.4

package/dist/utils-OG1yMaAa.d.cts

@@ -0,0 +1,485 @@
+/**
+ * Currency module types for Indonesian Rupiah utilities.
+ *
+ * @module currency/types
+ * @packageDocumentation
+ */
+/**
+ * Options for formatting Rupiah currency.
+ *
+ * @example
+ * Default formatting:
+ * ```typescript
+ * const options: RupiahOptions = {
+ *   symbol: true,
+ *   decimal: false,
+ *   separator: '.',
+ * };
+ * formatRupiah(1500000, options); // 'Rp 1.500.000'
+ * ```
+ *
+ * @example
+ * With decimals:
+ * ```typescript
+ * const options: RupiahOptions = {
+ *   symbol: true,
+ *   decimal: true,
+ *   precision: 2,
+ * };
+ * formatRupiah(1500000.50, options); // 'Rp 1.500.000,50'
+ * ```
+ *
+ * @public
+ */
+interface RupiahOptions {
+    /**
+     * Whether to show 'Rp' symbol.
+     *
+     * @defaultValue true
+     */
+    symbol?: boolean;
+    /**
+     * Whether to show decimal places.
+     *
+     * @defaultValue false
+     */
+    decimal?: boolean;
+    /**
+     * Thousands separator character.
+     *
+     * @defaultValue '.'
+     *
+     * @example
+     * ```typescript
+     * '.' // Indonesian standard
+     * ',' // International standard
+     * ' ' // Space separator
+     * ```
+     */
+    separator?: string;
+    /**
+     * Decimal separator character.
+     *
+     * @defaultValue ','
+     *
+     * @example
+     * ```typescript
+     * ',' // Indonesian standard
+     * '.' // International standard
+     * ```
+     */
+    decimalSeparator?: string;
+    /**
+     * Number of decimal places to show.
+     *
+     * @defaultValue 0
+     */
+    precision?: number;
+    /**
+     * Whether to add space after 'Rp' symbol.
+     *
+     * @defaultValue true
+     *
+     * @example
+     * ```typescript
+     * true  // 'Rp 1.500.000'
+     * false // 'Rp1.500.000'
+     * ```
+     */
+    spaceAfterSymbol?: boolean;
+}
+/**
+ * Options for converting numbers to Indonesian words (terbilang).
+ *
+ * @example
+ * Default:
+ * ```typescript
+ * toWords(1500000); // 'satu juta lima ratus ribu rupiah'
+ * ```
+ *
+ * @example
+ * Uppercase:
+ * ```typescript
+ * toWords(1500000, { uppercase: true });
+ * // 'Satu juta lima ratus ribu rupiah'
+ * ```
+ *
+ * @example
+ * Without currency suffix:
+ * ```typescript
+ * toWords(1500000, { withCurrency: false });
+ * // 'satu juta lima ratus ribu'
+ * ```
+ *
+ * @public
+ */
+interface WordOptions {
+    /**
+     * Whether to capitalize the first letter.
+     *
+     * @defaultValue false
+     *
+     * @example
+     * ```typescript
+     * false // 'satu juta'
+     * true  // 'Satu juta'
+     * ```
+     */
+    uppercase?: boolean;
+    /**
+     * Whether to add 'rupiah' at the end.
+     *
+     * @defaultValue true
+     *
+     * @example
+     * ```typescript
+     * true  // 'satu juta rupiah'
+     * false // 'satu juta'
+     * ```
+     */
+    withCurrency?: boolean;
+    /**
+     * Whether to include decimal words with 'koma' separator.
+     *
+     * @defaultValue false
+     *
+     * @example
+     * ```typescript
+     * false // 'satu juta lima ratus ribu rupiah'
+     * true  // 'satu juta lima ratus ribu rupiah koma lima puluh'
+     * ```
+     */
+    withDecimals?: boolean;
+}
+/**
+ * Unit for rounding currency amounts.
+ *
+ * Common Indonesian currency rounding units:
+ * - `'ribu'`: Round to thousands (1.000)
+ * - `'ratus-ribu'`: Round to hundred thousands (100.000)
+ * - `'juta'`: Round to millions (1.000.000)
+ *
+ * @example
+ * ```typescript
+ * roundToClean(1234567, 'ribu');      // 1235000
+ * roundToClean(1234567, 'ratus-ribu'); // 1200000
+ * roundToClean(1234567, 'juta');       // 1000000
+ * ```
+ *
+ * @public
+ */
+type RoundUnit = 'ribu' | 'ratus-ribu' | 'juta';
+/**
+ * Options for compact currency formatting.
+ *
+ * @example
+ * Default:
+ * ```typescript
+ * formatCompact(1500000); // 'Rp 1,5 juta'
+ * ```
+ *
+ * @example
+ * Without symbol:
+ * ```typescript
+ * formatCompact(1500000, { symbol: false }); // '1,5 juta'
+ * ```
+ *
+ * @public
+ */
+interface CompactOptions {
+    /**
+     * Whether to show 'Rp' symbol.
+     *
+     * @defaultValue true
+     */
+    symbol?: boolean;
+    /**
+     * Whether to add space after 'Rp' symbol.
+     *
+     * @defaultValue true
+     */
+    spaceAfterSymbol?: boolean;
+}
+/**
+ * Options for splitting an amount into parts.
+ *
+ * @example
+ * Equal split:
+ * ```typescript
+ * splitAmount(1500000, 3); // [500000, 500000, 500000]
+ * ```
+ *
+ * @example
+ * Custom ratios:
+ * ```typescript
+ * splitAmount(1000000, 2, { ratios: [70, 30] }); // [700000, 300000]
+ * ```
+ *
+ * @public
+ */
+interface SplitOptions {
+    /**
+     * Custom percentage ratios (must sum to 100).
+     * Length must match `parts` count.
+     */
+    ratios?: number[];
+    /**
+     * Round each part to a clean amount.
+     */
+    roundTo?: RoundUnit;
+}
+
+/**
+ * Currency formatting utilities for Indonesian Rupiah.
+ *
+ * @module currency/format
+ * @packageDocumentation
+ */
+
+/**
+ * Formats a number as Indonesian Rupiah currency.
+ *
+ * Provides flexible formatting options including symbol display,
+ * decimal places, and custom separators.
+ *
+ * @param amount - The amount to format
+ * @param options - Formatting options
+ * @returns Formatted Rupiah string
+ *
+ * @example
+ * Basic formatting:
+ * ```typescript
+ * formatRupiah(1500000); // 'Rp 1.500.000'
+ * ```
+ *
+ * @example
+ * With decimals:
+ * ```typescript
+ * formatRupiah(1500000.50, { decimal: true }); // 'Rp 1.500.000,50'
+ * ```
+ *
+ * @example
+ * Without symbol:
+ * ```typescript
+ * formatRupiah(1500000, { symbol: false }); // '1.500.000'
+ * ```
+ *
+ * @example
+ * Custom separators:
+ * ```typescript
+ * formatRupiah(1500000, { separator: ',' }); // 'Rp 1,500,000'
+ * ```
+ *
+ * @public
+ */
+declare function formatRupiah(amount: number, options?: RupiahOptions): string;
+/**
+ * Formats a number in compact Indonesian format.
+ *
+ * Uses Indonesian units: ribu, juta, miliar, triliun.
+ * Follows Indonesian grammar rules (e.g., "1 juta" not "1,0 juta").
+ *
+ * @param amount - The amount to format
+ * @param options - Compact formatting options
+ * @returns Compact formatted string
+ *
+ * @example
+ * Millions:
+ * ```typescript
+ * formatCompact(1500000); // 'Rp 1,5 juta'
+ * formatCompact(1000000); // 'Rp 1 juta'
+ * ```
+ *
+ * @example
+ * Thousands:
+ * ```typescript
+ * formatCompact(500000); // 'Rp 500 ribu'
+ * ```
+ *
+ * @example
+ * Small numbers:
+ * ```typescript
+ * formatCompact(1500); // 'Rp 1.500'
+ * ```
+ *
+ * @example
+ * Without symbol:
+ * ```typescript
+ * formatCompact(1500000, { symbol: false }); // '1,5 juta'
+ * ```
+ *
+ * @public
+ */
+declare function formatCompact(amount: number, options?: CompactOptions): string;
+
+/**
+ * Currency parsing utilities for Indonesian Rupiah.
+ *
+ * @module currency/parse
+ * @packageDocumentation
+ */
+/**
+ * Parses a formatted Rupiah string back to a number.
+ *
+ * Handles multiple formats:
+ * - Standard: "Rp 1.500.000"
+ * - No symbol: "1.500.000"
+ * - With decimals: "Rp 1.500.000,50"
+ * - Compact: "Rp 1,5 juta", "Rp 500 ribu"
+ *
+ * @param formatted - The formatted Rupiah string to parse
+ * @returns Parsed number, or null if invalid
+ *
+ * @example
+ * Standard format:
+ * ```typescript
+ * parseRupiah('Rp 1.500.000'); // 1500000
+ * ```
+ *
+ * @example
+ * With decimals:
+ * ```typescript
+ * parseRupiah('Rp 1.500.000,50'); // 1500000.50
+ * ```
+ *
+ * @example
+ * Compact format:
+ * ```typescript
+ * parseRupiah('Rp 1,5 juta'); // 1500000
+ * parseRupiah('Rp 500 ribu'); // 500000
+ * ```
+ *
+ * @example
+ * Invalid input:
+ * ```typescript
+ * parseRupiah('invalid'); // null
+ * ```
+ *
+ * @public
+ */
+declare function parseRupiah(formatted: string): number | null;
+
+/**
+ * Convert numbers to Indonesian words (terbilang).
+ *
+ * @module currency/words
+ * @packageDocumentation
+ */
+
+/**
+ * Converts a number to Indonesian words (terbilang).
+ *
+ * Supports numbers up to trillions (triliun).
+ * Follows Indonesian language rules for number pronunciation.
+ *
+ * Special rules:
+ * - 1 = "satu" in most cases, but "se-" for 100, 1000
+ * - 11 = "sebelas" (not "satu belas")
+ * - 100 = "seratus" (not "satu ratus")
+ * - 1000 = "seribu" (not "satu ribu")
+ *
+ * @param amount - The number to convert
+ * @param options - Conversion options
+ * @returns Indonesian words representation
+ *
+ * @example
+ * Basic numbers:
+ * ```typescript
+ * toWords(123); // 'seratus dua puluh tiga rupiah'
+ * ```
+ *
+ * @example
+ * Large numbers:
+ * ```typescript
+ * toWords(1500000); // 'satu juta lima ratus ribu rupiah'
+ * ```
+ *
+ * @example
+ * With options:
+ * ```typescript
+ * toWords(1500000, { uppercase: true });
+ * // 'Satu juta lima ratus ribu rupiah'
+ *
+ * toWords(1500000, { withCurrency: false });
+ * // 'satu juta lima ratus ribu'
+ * ```
+ *
+ * @public
+ */
+declare function toWords(amount: number, options?: WordOptions): string;
+
+/**
+ * Currency utility functions.
+ *
+ * @module currency/utils
+ * @packageDocumentation
+ */
+
+/**
+ * Rounds a number to a clean currency amount.
+ *
+ * Common use case: displaying approximate prices or budgets
+ * in clean, rounded numbers.
+ *
+ * @param amount - The amount to round
+ * @param unit - The unit to round to (default: 'ribu')
+ * @returns Rounded amount
+ *
+ * @example
+ * Round to thousands:
+ * ```typescript
+ * roundToClean(1234567, 'ribu'); // 1235000
+ * ```
+ *
+ * @example
+ * Round to hundred thousands:
+ * ```typescript
+ * roundToClean(1234567, 'ratus-ribu'); // 1200000
+ * ```
+ *
+ * @example
+ * Round to millions:
+ * ```typescript
+ * roundToClean(1234567, 'juta'); // 1000000
+ * ```
+ *
+ * @public
+ */
+declare function roundToClean(amount: number, unit?: RoundUnit): number;
+/**
+ * Formats a number as Indonesian Rupiah in accounting style.
+ * Negative numbers are wrapped in parentheses.
+ *
+ * @param amount - The amount to format
+ * @param options - Formatting options
+ * @returns Formatted accounting string
+ *
+ * @example
+ * ```typescript
+ * formatAccounting(-1500000); // '(Rp 1.500.000)'
+ * ```
+ */
+declare function formatAccounting(amount: number, options?: RupiahOptions): string;
+/**
+ * Calculates tax (PPN) for a given amount.
+ *
+ * @param amount - The base amount
+ * @param rate - The tax rate (e.g., 0.11 for 11% PPN)
+ * @returns The calculated tax amount
+ *
+ * @example
+ * ```typescript
+ * calculateTax(1000000, 0.11); // 110000
+ * ```
+ */
+declare function calculateTax(amount: number, rate: number): number;
+/**
+ * Helper to ensure a string or number has the 'Rp ' prefix.
+ * If already prefixed, it returns the input as is.
+ *
+ * @param amount - The amount or formatted string
+ * @returns String with Rupiah prefix
+ */
+declare function addRupiahSymbol(amount: string | number): string;
+
+export { type CompactOptions as C, type RupiahOptions as R, type SplitOptions as S, type WordOptions as W, formatCompact as a, formatAccounting as b, calculateTax as c, addRupiahSymbol as d, type RoundUnit as e, formatRupiah as f, parseRupiah as p, roundToClean as r, toWords as t };