rntrc/dist/index.d.ts

Library for decoding and generating Ukrainian taxpayer identification numbers

/**
 * The type for gender values in RNTRC.
 */
export type Gender = 'male' | 'female';
/**
 * The type for age values in RNTRC.
 * */
export type Age = {
    /** Years that have passed since a person's birth */
    years: number;
    /** Months that have passed since a person's birth */
    months: number;
    /** Days that have passed since a person's birth */
    days: number;
};
/**
 * Parameters for generating a RNTRC number.
 */
export interface GenerateParams {
    /** @param {string | number} [day] - Day of birth */
    day?: string | number;
    /** @param {string | number} [month] - Month of birth */
    month?: string | number;
    /** @param {string | number} [year] - Year of birth */
    year?: string | number;
    /** @param {Gender} [gender] - Gender of the person */
    gender?: Gender;
}
/**
 * Represents an RNTRC (Ukrainian personal tax identifier with embedded information about birthdate and gender).
 *
 * @see {@link https://uk.wikipedia.org/wiki/Реєстраційний_номер_облікової_картки_платника_податків|RNTRC on Ukrainian Wikipedia}
 * @see {@link https://zakon.rada.gov.ua/laws/show/z1306-17#n230|RNTRC number structure}
 */
export default class Rntrc {
    private static readonly WEIGHTS;
    private static readonly BASE_DATE_MS;
    private static readonly MIN_DATE;
    private static readonly MAX_DATE;
    private static readonly MILLIS_PER_DAY;
    private readonly value;
    private readonly ignoreInvalid;
    /**
     * Creates a new RNTRC instance
     *
     * @param {string | number} rntrc - The RNTRC number
     * @param {boolean} [ignoreInvalid = false] - Whether to skip validation of the RNTRC number
     *
     * @throws {Error} If the RNTRC is invalid and ignoreInvalid is false, or RNTRC isn't 10 digits.
     *
     * @see {@link https://uk.wikipedia.org/wiki/Реєстраційний_номер_облікової_картки_платника_податків|RNTRC on Ukrainian Wikipedia}
     * @see {@link https://zakon.rada.gov.ua/laws/show/z1306-17#n230|RNTRC number structure}
     */
    constructor(rntrc: string | number, ignoreInvalid?: boolean);
    /**
     * Gets the RNTRC number string.
     *
     * @returns {string} RNTRC number string
     * */
    toString(): string;
    /**
     * Defines how the object should be converted to a primitive value
     * Called automatically during type coercion operations like string
     * concatenation, mathematical operations, and equality comparisons
     *
     * @returns {string} The primitive string representation of the TIN
     * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive}
     */
    [Symbol.toPrimitive](): string;
    /**
     * Gets the birthdate encoded in the RNTRC
     *
     * @returns {Date} The birthdate
     */
    birthdate(): Date;
    age(): Age;
    /**
     * Gets the gender encoded in the RNTRC
     *
     * @returns {Gender} The gender ('male' or 'female')
     */
    gender(): Gender;
    /**
     * Checks if the RNTRC belongs to a male person
     *
     * @returns {boolean} True if male, false otherwise
     */
    male(): boolean;
    /**
     * Checks if the RNTRC belongs to a female person
     *
     * @returns {boolean} True if female, false otherwise
     */
    female(): boolean;
    /**
     * Gets sequential number of the Облікова картка № 1ДР
     *
     * @returns {string} The sequential number from RNTRC
     */
    accountingCardNumber(): string;
    private static checksum;
    /**
     * Validates the RNTRC number
     *
     * @returns {boolean} True if the RNTRC is valid, false otherwise
     */
    valid(): boolean;
    /**
     * Generate a random RNTRC instance.
     *
     * Generates a valid RNTRC based on the provided parameters. If parameters are not provided,
     * random valid values will be used. The generated RNTRC will include a birthdate between
     * 1900-01-01 and 2173-10-14, a random record number and a gender digit based on the
     * specified or random gender.
     *
     * @param {GenerateParams} params - Configuration object for RNTRC generation
     * @param {string | number} [params.day] - Day of birth
     * @param {string | number} [params.month] - Month of birth
     * @param {string | number} [params.year] - Year of birth
     * @param {Gender} [params.gender] - Gender of the person
     *
     * @returns {Rntrc} A new valid RNTRC instance
     *
     * @throws {Error} If date is invalid or outside allowed range
     * @throws {Error} If gender value is invalid
     */
    static generate({ day, month, year, gender }?: GenerateParams): Rntrc;
}