@investo/invform/dist/index.d.ts

A versatile library of investment formulas...

/**
 * Calculates a future value using a simple interest rate.
 * @param {number} principal  P — initial capital
 * @param {number} rate       r — annual rate (0.08 = 8 %)
 * @param {number} years      t — term in years
 * @returns number
 */
export declare const calcSimpleInterest: (principal: number, rate: number, years: number) => number;

/**
 * Calculates simple profit using a simple interest rate.
 * @param {number} principal  P — initial capital
 * @param {number} rate       r — annual rate (0.08 = 8 %)
 * @param {number} years      t — term in years
 * @returns number
 */
export declare const calcSimpleProfit: (principal: number, rate: number, years: number) => number;

/**
 * Calculates how many coins can be purchased with a given investment, price per asset, and optional fee.
 *
 * Formula:
 * coins = (investment - fee) / pricePerAsset
 *
 * @param {number} investment - The total amount of money available (must be ≥ 0).
 * @param {number} pricePerAsset - The price of a single asset (must be > 0).
 * @param {number} [fee=0] - Optional transaction fee (must be ≥ 0).
 * @returns {number} - The number of coins that can be purchased.
 *
 * @throws {Error} If pricePerAsset <= 0 or any input is negative.
 *
 * @example
 * // Returns 9.5
 * calculateAssetsFromInvestment(1000, 100, 50);
 */
export declare const calculateAssetsFromInvestment: (investment: number, pricePerAsset: number, fee?: number) => number;

/**
 * Calculates the total investment based on the number of assets, price per asset, and optional fee.
 *
 * @param {number} amount - The number of assets purchased (must be ≥ 0).
 * @param {number} pricePerAsset - The price of one asset (must be ≥ 0).
 * @param {number} [fee=0] - Optional transaction fee (can be 0, must be ≥ 0).
 * @returns {number} - The total investment amount.
 *
 * @throws {Error} If any of the inputs are negative.
 *
 * @example
 * // Returns 1005
 * calculateInvestment(10, 100, 5);
 *
 * @example
 * // Returns 1000 (no fee)
 * calculateInvestment(10, 100);
 */
export declare const calculateInvestment: (amount: number, pricePerAsset: number, fee?: number) => number;

/**
 * Calculates the net proceeds from selling assets after deducting transaction fees.
 *
 * Formula:
 * netProceeds = (amount * price) - fee
 *
 * @param {number} amount - Number of assets sold (must be ≥ 0)
 * @param {number} price - Selling price per unit (must be ≥ 0)
 * @param {number} [fee=0] - Transaction fee (must be ≥ 0)
 * @returns {number} - Net amount received after the fee
 *
 * @throws {Error} If any input is negative
 *
 * @example
 * // Returns 480
 * calculateNetSaleProceeds(10, 50, 20);
 */
export declare function calculateNetSaleProceeds(amount: number, price: number, fee?: number): number;

/**
 * Calculates the target return amount based on the desired percentage of the original investment.
 *
 * @param {number} investment - The initial investment amount (must be ≥ 0).
 * @param {number} targetPercentage - The desired percentage of return (from 0 to 100).
 * @returns {number} - The target return amount the investor wants to recover.
 *
 * @throws {Error} If investment is negative or targetPercentage is out of range [0–100].
 *
 * @example
 * // Returns 6000
 * calculatePartialReturn(10000, 60);
 */
export declare const calculatePartialReturn: (investment: number, targetPercentage: number) => number;

/**
 * Calculates the effective price per coin based on total investment, number of coins received, and optional fee.
 *
 * Formula:
 * pricePerAsset = (investment - fee) / amount
 *
 * @param {number} investment - Total investment amount (must be ≥ 0).
 * @param {number} amount - Number of coins received (must be > 0).
 * @param {number} [fee=0] - Optional fee (must be ≥ 0).
 * @returns {number} - The price paid per coin.
 *
 * @throws {Error} If amount <= 0 or any input is negative.
 *
 * @example
 * // Returns 100
 * calculatePricePerAsset(1050, 10, 50);
 */
export declare const calculatePricePerAsset: (investment: number, amount: number, fee?: number) => number;

/**
 * Calculates the profit (or loss) from selling an asset.
 *
 * Formula:
 * profit = saleProceeds - investment
 *
 * @param {number} saleProceeds - The amount received from selling the asset (must be ≥ 0)
 * @param {number} investment - The total amount originally invested (must be ≥ 0)
 * @returns {number} - The profit (can be negative if there’s a loss)
 *
 * @throws {Error} If any input is negative
 *
 * @example
 * // Returns 200
 * calculateProfit(1100, 900);
 */
export declare function calculateProfit(saleProceeds: number, investment: number): number;

/**
 * Calculates the remaining investment after a partial withdrawal.
 *
 * Formula:
 * remaining = initialInvestment - withdrawnAmount
 *
 * @param {number} initialInvestment - The total original investment (must be ≥ 0)
 * @param {number} withdrawnAmount - The amount withdrawn (must be ≥ 0)
 * @returns {number} - The remaining investment (never less than 0)
 *
 * @throws {Error} If any input is negative
 *
 * @example
 * // Returns 6000
 * calculateRemainingInvestment(10000, 4000);
 */
export declare function calculateRemainingInvestment(initialInvestment: number, withdrawnAmount: number): number;

/**
 * Calculates what percentage of the original investment a given return amount represents.
 *
 * Formula:
 * percentage = (desiredReturn / investment) * 100
 *
 * @param {number} investment - The original investment amount (must be > 0).
 * @param {number} desiredReturn - The amount the investor wants to recover.
 * @returns {number} - Percentage of the investment represented by the desired return.
 *
 * @throws {Error} If investment is 0 or less.
 *
 * @example
 * // Returns 60
 * calculateReturnPercentage(10000, 6000);
 */
export declare function calculateReturnPercentage(investment: number, desiredReturn: number): number;

/**
 * Calculates the Return on Investment (ROI) as a percentage.
 *
 * Formula:
 * ROI = ((Return - Investment) / Investment) * 100
 *
 * @param {number} investment - The initial investment amount (must be > 0).
 * @param {number} actualReturn - The actual return gained from the investment.
 * @returns {number} - ROI as a percentage (can be negative if return is lower than investment).
 *
 * @throws {Error} If investment is less than or equal to 0.
 *
 * @example
 * // Returns 30
 * calculateROI(10000, 13000);
 *
 * @example
 * // Returns -20
 * calculateROI(10000, 8000);
 */
export declare const calculateROI: (investment: number, actualReturn: number) => number;

export { }