number-suffix/dist/index.d.cts

Turns a number to a fixed string with a metric or abbreviation suffix

type Unit = 'thousand' | 'million' | 'billion' | 'trillion' | 'quadrillion' | 'quintillion';
type SuffixStyle = string[];

interface Style$1 {
    getSymbol(unit: Unit): string;
}
interface StyleCollection$1 {
    add(name: string, symbols: string[]): StyleCollection$1;
    get(name: string): Style$1;
    getSymbol(unit: Unit, style?: string): string;
    setDefault(name: string): StyleCollection$1;
    getDefault(): string;
}
type FormatOptions = {
    measurement: Unit;
    precision: number;
    collection: StyleCollection$1;
    style: string;
};
type RuntimeOptions = Pick<FormatOptions, 'precision' | 'measurement' | 'style'>;

/**
 * @class Style
 * @description A class to represent a style as an object
 */
declare class Style implements Style$1 {
    symbols: SuffixStyle;
    symbolsMap: Record<Unit, string>;
    constructor(symbols: SuffixStyle);
    /**
     * Returns a symbol by a group
     * @param {String} group - a group ('thousand', 'million', etc)
     * @returns {String}
     */
    getSymbol(unit: Unit): string;
}

/**
 * StyleCollection data model
 */
declare class StyleCollection implements StyleCollection$1 {
    styles: Record<string, Style>;
    default: keyof typeof this.styles;
    constructor();
    /**
     * adds a style to the collection by an array
     * @param {Array<String>} style - an array with four or more strings
     * @example
     * add('metric', ['k', 'M', 'G', 'T'])
     * add('abbreviation', ['K', 'M', 'B', 'T'])
     */
    add(name: string, symbols: string[]): this;
    /**
     * Returns a style by name
     * @param {String} name - the style name
     * @returns {Style} - the style
     */
    get(name: string): Style;
    /**
     * Returns the symbol of a number by a style
     * @param {String} group - the number group - thousand, million, billion etc.
     * @param {String} style - a style name for formatting
     * @returns {String}
     */
    getSymbol(unit: Unit, style?: string): string;
    /**
     * Sets the default style name
     * @param {String} name - the style's name
     * @returns {Object} - return the collection object (chainable)
     */
    setDefault(name: string): this;
    /**
     * Returns the default style name
     */
    getDefault(): string;
    static Style: typeof Style;
}

declare class NumberSuffix {
    styleCollection: StyleCollection;
    precision: number;
    measurement: Unit | undefined;
    /**
     * @constructor
     */
    constructor(options?: Partial<RuntimeOptions>);
    /**
     * Formats a number by the definitions
     * @param {Number} number - a number
     * @param {Object} options - extra options if needed
     * @returns {String}
     */
    format(number: number, options?: Partial<FormatOptions>): string;
    /**
     * Adds a style to the collection by an array
     * @param {Array<String>} style - an array with four or more strings
     * @example
     * addStyle('metric', ['k', 'M', 'G', 'T'])
     * addStyle('abbreviation', ['K', 'M', 'B', 'T'])
     */
    addStyle(...args: Parameters<StyleCollection['add']>): this;
    setDefaultStyle(name: string): this;
    setOptions(options?: Partial<RuntimeOptions>): void;
    static addStyle: (name: string, symbols: string[]) => void;
    static getStyle: (name: string) => Style;
    static getDivider: (num: Unit | Uppercase<Unit> | number) => number;
    static format: (number: number, options?: Partial<FormatOptions>) => string;
    static styles: StyleCollection;
    static toFixed: (num: number, precision?: number) => string;
}

/**
 * Formats a number
 * @param {Number} number - a number
 * @param {Object} options - options object
 * @param {String} options.measurement - a fixed number group (like formatting a million with a thousands format)
 * @param {Number} options.precision - a precision after the dot (the difference between 2K and 2.56K)
 * @param {Object} options.collection - a style collection to use instead of the global one
 * @param {String} options.style - a specific style to use
 * @returns {String} - the formatted number
 */
declare const format: (number: number, options?: Partial<FormatOptions>) => string;

/**
 * Returns a divider by either a number or a string
 * @param {String|Number} num - either a number or a string of thousand, million, billion or trillion. Case insensitive.
 * @returns {Number}
 */
declare const getDivider: (num: Unit | Uppercase<Unit> | number) => number;

/**
 * Returns a fixed number without rounding
 * (native function rounds the value)
 * @param {Number} num - a number
 * @param {Number} decimals - the number of digits after the dot
 * @returns {String}
 */
declare const toFixed: (num: number, precision?: number) => string;

/**
 * Global style collection object
 */
declare const styles: StyleCollection;
/**
 * Adds a style
 * @param {Array<String>} style - an array with four or more strings
 * @example
 * addStyle('metric', ['k', 'M', 'G', 'T'])
 * addStyle('abbreviation', ['K', 'M', 'B', 'T'])
 */
declare const addStyle: (name: string, symbols: string[]) => void;
declare const getStyle: (name: string) => Style;

export { type FormatOptions, type RuntimeOptions, type SuffixStyle, type Unit, addStyle, NumberSuffix as default, format, getDivider, getStyle, styles, toFixed };