@indodev/toolkit 0.3.2 → 0.3.4

package/dist/currency/index.d.cts

@@ -1,407 +1,103 @@
-/**
- * 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;
-}
-/**
- * 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';
-
-/**
- * Currency formatting utilities for Indonesian Rupiah.
- *
- * @module currency/format
- * @packageDocumentation
- */
+import { S as SplitOptions } from '../utils-OG1yMaAa.cjs';
+export { C as CompactOptions, e as RoundUnit, R as RupiahOptions, W as WordOptions, d as addRupiahSymbol, c as calculateTax, b as formatAccounting, a as formatCompact, f as formatRupiah, p as parseRupiah, r as roundToClean, t as toWords } from '../utils-OG1yMaAa.cjs';
 
 /**
- * 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'
- * ```
+ * Invalid split error thrown when split parameters are invalid.
  *
  * @public
  */
-declare function formatRupiah(amount: number, options?: RupiahOptions): string;
+declare class InvalidSplitError extends Error {
+    constructor(message: 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").
+ * Splits an amount into equal or custom-ratio parts.
  *
- * @param amount - The amount to format
- * @returns Compact formatted string
+ * @param amount - The amount to split
+ * @param parts - Number of parts to split into
+ * @param options - Split options (ratios, rounding)
+ * @returns Array of split amounts
  *
  * @example
- * Millions:
+ * Equal split:
  * ```typescript
- * formatCompact(1500000); // 'Rp 1,5 juta'
- * formatCompact(1000000); // 'Rp 1 juta'
+ * splitAmount(1500000, 3); // [500000, 500000, 500000]
  * ```
  *
  * @example
- * Thousands:
+ * Custom ratios:
  * ```typescript
- * formatCompact(500000); // 'Rp 500 ribu'
+ * splitAmount(1000000, 2, { ratios: [70, 30] }); // [700000, 300000]
  * ```
  *
  * @example
- * Small numbers:
+ * With rounding:
  * ```typescript
- * formatCompact(1500); // 'Rp 1.500'
+ * splitAmount(1234567, 3, { roundTo: 'ribu' }); // [412000, 411000, 411000]
  * ```
  *
  * @public
  */
-declare function formatCompact(amount: number): string;
-
-/**
- * Currency parsing utilities for Indonesian Rupiah.
- *
- * @module currency/parse
- * @packageDocumentation
- */
+declare function splitAmount(amount: number, parts: number, options?: SplitOptions): number[];
 /**
- * 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
- * ```
+ * Calculates what percentage a part is of a total.
  *
- * @example
- * Compact format:
- * ```typescript
- * parseRupiah('Rp 1,5 juta'); // 1500000
- * parseRupiah('Rp 500 ribu'); // 500000
- * ```
+ * @param part - The part value
+ * @param total - The total value
+ * @returns Percentage as number (e.g., 15 for 15%)
  *
  * @example
- * Invalid input:
  * ```typescript
- * parseRupiah('invalid'); // null
+ * percentageOf(150000, 1000000); // 15
+ * percentageOf(0, 1000000); // 0
+ * percentageOf(100, 0); // 0 (not NaN)
  * ```
  *
  * @public
  */
-declare function parseRupiah(formatted: string): number | null;
-
-/**
- * Convert numbers to Indonesian words (terbilang).
- *
- * @module currency/words
- * @packageDocumentation
- */
-
+declare function percentageOf(part: number, total: number): number;
 /**
- * Converts a number to Indonesian words (terbilang).
+ * Calculates absolute and percentage difference between two amounts.
  *
- * 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
+ * @param amount1 - The new/current amount
+ * @param amount2 - The original/reference amount
+ * @returns Object with absolute difference, percentage, and direction
  *
  * @example
- * Basic numbers:
  * ```typescript
- * toWords(123); // 'seratus dua puluh tiga rupiah'
- * ```
+ * difference(1200000, 1000000);
+ * // { absolute: 200000, percentage: 20, direction: 'increase' }
  *
- * @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'
+ * difference(0, 1000000);
+ * // { absolute: -1000000, percentage: null, direction: 'decrease' }
  * ```
  *
  * @public
  */
-declare function toWords(amount: number, options?: WordOptions): string;
-
-/**
- * Currency utility functions.
- *
- * @module currency/utils
- * @packageDocumentation
- */
+declare function difference(amount1: number, amount2: number): {
+    absolute: number;
+    percentage: number | null;
+    direction: 'increase' | 'decrease' | 'same';
+};
 
 /**
- * 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
+ * Validates whether a string is a valid Rupiah format.
  *
- * @example
- * Round to thousands:
- * ```typescript
- * roundToClean(1234567, 'ribu'); // 1235000
- * ```
+ * Accepts standard, compact, and negative formats.
  *
- * @example
- * Round to hundred thousands:
- * ```typescript
- * roundToClean(1234567, 'ratus-ribu'); // 1200000
- * ```
+ * @param formatted - The string to validate
+ * @returns `true` if valid Rupiah format, `false` otherwise
  *
  * @example
- * Round to millions:
  * ```typescript
- * roundToClean(1234567, 'juta'); // 1000000
+ * validateRupiah('Rp 1.500.000'); // true
+ * validateRupiah('1.500.000'); // true
+ * validateRupiah('Rp 1,5 juta'); // true
+ * validateRupiah('abc'); // false
+ * validateRupiah(''); // false
  * ```
  *
  * @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 (default: 0.11 for 11%)
- * @returns The calculated tax amount
- *
- * @example
- * ```typescript
- * calculateTax(1000000); // 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;
+declare function validateRupiah(formatted: string): boolean;
 
-export { type RoundUnit, type RupiahOptions, type WordOptions, addRupiahSymbol, calculateTax, formatAccounting, formatCompact, formatRupiah, parseRupiah, roundToClean, toWords };
+export { InvalidSplitError, SplitOptions, difference, percentageOf, splitAmount, validateRupiah };