reslib 2.5.0 → 2.6.0

package/build/currency/index.d.ts

@@ -1,31 +1,26 @@
 import 'reflect-metadata';
 import { Currency, CurrencySymbol } from './types';
-/**
- *
- * Extends the default options with the provided Currency object to initialize default values.
-   it sets up default values for currency formatting, merging them with any user-provided options. This ensures that all necessary settings are available for the formatting process.
- *
- * @param options The Currency object to merge with the default options.
- * @returns The merged Currency object with default values.
- */
-declare function prepareOptions(options?: Currency): Currency;
-/**
- *
- * @description
- * Description of the format for displaying numeric values.
- *
- * The format is a string consisting of the letters %v and %s, where:
- *   - %v represents the value of the amount,
- *   - %s represents the currency.
- * For example, %s%v => $10 and %v %s => 10 $.
- *
- * To define the decimal places, use the pattern [.][#{0,n}], for example:
- *   - .### for display with 3 decimal places,
- *   - . for no decimal places in the display.
- * For example, the format %v %s .## returns: 12.35 $ for the value 12.357777 converted to dollars.
- */
 export declare const CurrencyFormatter: {
-    parse: (value: any, decimalSeparator?: string) => number;
+    /**
+   *
+   * Takes a string or array of strings, removes all formatting/cruft, and returns the raw float value.
+      The unformat function takes a formatted currency string and converts it back to a raw number. This is useful when you need to perform calculations on currency values that may have been stored or input as formatted strings.
+   *
+   * Alias: `accounting.unformat(string)`
+   *
+   * Decimal must be included in the regular expression to match floats (default options to
+   * accounting.settings.number.decimalSeparator), so if the number uses a non-standard decimalSeparator
+   * separator, provide it as the second argument.
+   *
+   * Also matches bracketed negatives (eg. "$ (1.99)" => -1.99)
+   *
+   * Doesn't throw any errors (`NaN`s become 0) but this may change in future
+   *
+   * @param {string | string[]} value The string or array of strings to unformat.
+   * @param {string} [decimalSeparator] The decimal separator to use (defaults to accounting.settings.number.decimalSeparator).
+   * @returns {number} The unformatted float value.
+   */
+    unformat: (value: any, decimalSeparator?: string) => number;
     session: {
         getFormat: (force?: boolean) => string;
         setFormat: (format: string) => void | Promise<void>;
@@ -33,19 +28,152 @@ export declare const CurrencyFormatter: {
         getCurrency: () => Currency;
         defaultCurrencyFormat: string;
     };
+    /**
+     *
+     * Format a number into currency.
+     *
+     * The symbol can be an object, in which case the other properties can be null.
+     * Usage: accounting.formatMoney(number, symbol, decimalDigits, thousandsSep, decimalSep, format)
+     * prepareOptions: (0, "$", 2, ",", ".", "%s%v")
+     *
+     * Localise by overriding the symbol, decimalDigits, thousandSeparator / decimalSeparator separators and format
+     * Second param can be an object matching `settings.currency` which is the easiest way.
+     *
+     * To do: tidy up the parameters
+     *
+     * @param {number} [number] The number to format.
+     * @param {Currency | CurrencySymbol} [symbol] The symbol or options object.
+     * @param {number} [decimalDigits] The decimal digits to use.
+     * @param {string} [thousandSeparator] The thousand separator to use.
+     * @param {string} [decimalSeparator] The decimal separator to use.
+     * @param {string} [format] The format to use.
+     * @returns {string} The formatted number as a string.
+     */
     formatMoney: (number?: number, symbol?: Currency | CurrencySymbol, decimalDigits?: number, thousandSeparator?: string, decimalSeparator?: string, format?: string) => string;
     currencies: import("./types").Currencies;
     isCurrency: (obj: unknown) => obj is Currency;
+    /**
+     *
+     * Format a number, with comma-separated thousands and custom decimalDigits/decimalSeparator places.
+     * The formatNumber function takes a number and formats it with the appropriate thousand separators and decimal places, based on the provided options.
+     *
+     * Alias: `accounting.format()`
+     *
+     * Localise by overriding the decimalDigits and thousandSeparator / decimalSeparator separators
+     * 2nd parameter `decimalDigits` can be an object matching `settings.number`
+     *
+     * @param {number} number The number to format.
+     * @param {Currency | number} [optionsOrDecimalDigits] The options object or decimal digits to use.
+     * @param {string} [thousandSeparator] The thousand separator to use.
+     * @param {string} [decimalSeparator] The decimal separator to use.
+     * @returns {string} The formatted number as a string.
+     */
     formatNumber: (number: number, optionsOrDecimalDigits?: Currency | number, thousandSeparator?: string, decimalSeparator?: string) => string;
+    /**
+     *
+     * Format a number into currency.
+     * The formatMoney and formatMoneyAsObject functions are the main workhorses of the module. They take a number and format it as a currency string, applying the appropriate symbol, decimal places, and formatting style. The formatMoneyAsObject version provides more detailed information about the formatting process.
+     *
+     * The symbol can be an object, in which case the other properties can be null.
+     * Usage: accounting.formatMoney(number, symbol, decimalDigits, thousandsSep, decimalSep, format)
+     * prepareOptions: (0, "$", 2, ",", ".", "%s%v")
+     *
+     * Localise by overriding the symbol, decimalDigits, thousandSeparator / decimalSeparator separators and format
+     * Second param can be an object matching `settings.currency` which is the easiest way.
+     *
+     * To do: tidy up the parameters
+     *
+     * @param {number} [number] The number to format.
+     * @param {Currency | CurrencySymbol} [symbol] The symbol or options object.
+     * @param {number} [decimalDigits] The decimal digits to use.
+     * @param {string} [thousandSeparator] The thousand separator to use.
+     * @param {string} [decimalSeparator] The decimal separator to use.
+     * @param {string} [format] The format to use.
+     * @returns {Currency & {
+     *   formattedValue: string,
+     *   formattedNumber: string,
+     *   usedFormat: string,
+     *   result: string,
+     * }}
+     */
     formatMoneyAsObject: (number?: number, symbol?: Currency | CurrencySymbol, decimalDigits?: number, thousandSeparator?: string, decimalSeparator?: string, format?: string) => Currency & {
         formattedValue: string;
         formattedNumber: string;
         usedFormat: string;
         result: string;
     };
-    unformat: (value: any, decimalSeparator?: string) => number;
+    /**
+   *
+   * Implementation of toFixed() that treats floats more like decimals.
+      The toFixed function addresses issues with floating-point precision in JavaScript, ensuring that decimal places are rounded correctly for currency display.
+   *
+   * Fixes binary rounding issues (eg. (0.615).toFixed(2) === "0.61") that present
+   * problems for accounting- and finance-related software.
+   *
+   * @param {number} value The number to format.
+   * @param {number} [decimalDigits] The number of decimal digits to round to (defaults to accounting.settings.decimalDigits).
+   * @returns {string} The formatted number as a string.
+   */
     toFixed: (value: number, decimalDigits?: number) => string;
-    prepareOptions: typeof prepareOptions;
+    /**
+   *
+   * Extends the default options with the provided Currency object to initialize default values.
+     it sets up default values for currency formatting, merging them with any user-provided options. This ensures that all necessary settings are available for the formatting process.
+   *
+   * @param options The Currency object to merge with the default options.
+   * @returns The merged Currency object with default values.
+   */
+    prepareOptions: (options?: Currency) => Currency;
+    /**
+     *
+     * Parse the currency format and return an object containing the parsed format and decimal digits.
+     * The parseFormat function helps interpret custom format strings, allowing users to specify how they want their currency displayed (e.g., where the symbol should appear, how many decimal places to show).
+     *
+     * @param {string} [format] The currency format, a string combining the characters %s, %v, and .#{0,n}, where:
+     *   - %s represents the currency symbol,
+     *   - %v represents the value to be formatted,
+     *   - .#{0,n} represents the number of decimal digits to use, with n being the number of decimal digits.
+     * For example, the format %v %s .### formats the number 12555.6893300244 as $12555.689, with 3 decimal digits.
+     * If no decimal digits are desired, simply omit the # characters after the dot (e.g., %s %v .).
+     *
+     * @returns {Currency} An object containing the parsed format and decimal digits.
+     */
     parseFormat: (format?: string) => Currency;
+    /**
+     *
+     * Parses a format string or object and returns a format object for use in rendering.
+     *
+     * @param {string | { pos: string, neg?: string, zero?: string } | (() => string | { pos: string, neg?: string, zero?: string })} format
+     *   Either a string with the default (positive) format, or an object containing `pos` (required), `neg` and `zero` values (or a function returning either a string or object)
+     * @returns {{ pos: string, neg: string, zero: string }} A format object containing positive, negative, and zero formats.
+     */
+    checkCurrencyFormat: (format: string | {
+        pos: string;
+        neg?: string;
+        zero?: string;
+    } | (() => string | {
+        pos: string;
+        neg?: string;
+        zero?: string;
+    })) => {
+        pos: string;
+        neg: string;
+        zero: string;
+    };
 };
+/**
+ *
+ * @description
+ * Description of the format for displaying numeric values.
+ *
+ * The format is a string consisting of the letters %v and %s, where:
+ *   - %v represents the value of the amount,
+ *   - %s represents the currency.
+ * For example, %s%v => $10 and %v %s => 10 $.
+ *
+ * To define the decimal places, use the pattern [.][#{0,n}], for example:
+ *   - .### for display with 3 decimal places,
+ *   - . for no decimal places in the display.
+ * For example, the format %v %s .## returns: 12.35 $ for the value 12.357777 converted to dollars.
+ */
 export * from './types';