@lacussoft/cpf-gen/dist/index.d.cts

Utility to generate CPF (Brazilian Individual's Taxpayer ID)

/**
 * Lacus Solutions :: cpf-gen v3.0.0
 *
 * @author Julio L. Muller.
 * @license MIT - 2021-2026
 */

import { Nullable } from '@lacussoft/utils';

/**
 * Class to store the options for the CPF generator. This class provides a
 * centralized way to configure how CPF digits are generated, including partial
 * start string and formatting.
 */
declare class CpfGeneratorOptions {
    /**
     * Default value for the `format` option. When `true`, the generated CPF
     * string will have the standard formatting (`000.000.000-00`).
     */
    static readonly DEFAULT_FORMAT = false;
    /**
     * Default string used as the initial string of the generated CPF.
     */
    static readonly DEFAULT_PREFIX = "";
    private _options;
    /**
     * Creates a new instance of `CpfGeneratorOptions`.
     *
     * Options can be provided in multiple ways:
     *
     * 1. As a single options object or another `CpfGeneratorOptions` instance.
     * 2. As multiple override objects that are merged in order (later overrides take
     *    precedence)
     *
     * All options are optional and will default to their predefined values if not
     * provided.
     *
     * @throws {CpfGeneratorOptionPrefixInvalidException} If the `prefix` option
     *   contains an invalid combination of digits.
     */
    constructor(defaultOptions?: CpfGeneratorOptionsInput, ...overrides: CpfGeneratorOptionsInput[]);
    /**
     * Returns a shallow copy of all current options, frozen to prevent
     * modification. This is useful for creating immutable snapshots of the
     * current configuration.
     */
    get all(): CpfGeneratorOptionsType;
    /**
     * Gets whether the generated CPF string will have the standard formatting
     * (`000.000.000-00`).
     */
    get format(): boolean;
    /**
     * Sets whether the generated CPF string will have the standard formatting
     * (`000.000.000-00`). The value is converted to a boolean using `Boolean()`,
     * so truthy/falsy values are handled appropriately.
     */
    set format(value: Nullable<boolean>);
    /**
     * Gets the string used as the initial string of the generated CPF.
     *
     * Note: If the evaluated prefix (after stripping non-digit characters) is
     * longer than 9 digits, the extra digits are ignored, because a CPF has 9
     * base digits followed by 2 calculated check digits.
     */
    get prefix(): string;
    /**
     * Sets the string used as the initial string of the generated CPF. Only
     * digits are kept and the rest is stripped. If provided, only the missing
     * digits are generated randomly. For example, if the prefix `123456` (6
     * digits) is given, only the next 3 digits are randomly generated and
     * concatenated to the prefix.
     *
     * Note: If the evaluated prefix (after stripping non-digit characters) is
     * longer than 9 digits, the extra digits are ignored, because a CPF has 9
     * base digits followed by 2 calculated check digits.
     *
     * @throws {CpfGeneratorOptionsTypeError} If the value is not a string.
     * @throws {CpfGeneratorOptionPrefixInvalidException} If the `prefix` option
     *   contains an invalid combination of digits or is too long.
     */
    set prefix(value: Nullable<string>);
    /**
     * Sets multiple options at once. This method allows you to update multiple
     * options in a single call. Only the provided options are updated; options
     * not included in the object retain their current values. You can pass either
     * a partial options object or another `CpfGeneratorOptions` instance.
     *
     * @throws {CpfGeneratorOptionsTypeError} If any option has an invalid type.
     * @throws {CpfGeneratorOptionPrefixInvalidException} If the `prefix` option
     *   contains an invalid combination of digits or is too long.
     */
    set(options: CpfGeneratorOptionsInput): this;
    /**
     * Throws if the prefix's digits are all zeros.
     *
     * @throws {CpfGeneratorOptionPrefixInvalidException} If the prefix's first 8
     *   digits are all zeros.
     */
    private _validatePrefixBaseId;
    /**
     * Throws if the prefix has 9 digits and they are all the same number.
     *
     * @throws {CpfGeneratorOptionPrefixInvalidException} If the prefix has 12
     *   digits that are all the same digit.
     */
    private _validatePrefixNonRepeatedDigits;
}

/**
 * Configuration type for CPF (Cadastro de Pessoa Física) generation options.
 * Defines the resolved options used internally: format (standard formatting)
 * and prefix (partial start string). All properties have default values when
 * creating a `CpfGeneratorOptions` instance.
 */
interface CpfGeneratorOptionsType {
    /**
     * Whether to format the generated CPF string with the standard formatting
     * (`000.000.000-00`).
     *
     * @default false
     */
    format: boolean;
    /**
     * A partial string containing 0 to 9 digits to use as the start of the
     * generated CPF. Only digits are kept; the rest is stripped. If provided,
     * only the missing digits are generated randomly. For example, if the prefix
     * `123456` (6 digits) is given, only the next 3 digits are randomly generated
     * and concatenated to the prefix.
     *
     * Note: If the evaluated prefix (after stripping non-digit characters) is
     * longer than 9 digits, the extra digits are ignored, because a CPF has 9
     * base digits followed by 2 calculated check digits.
     *
     * @default ''
     */
    prefix: string;
}
type CpfGeneratorOptionsInput = CpfGeneratorOptions | Partial<CpfGeneratorOptionsType>;

/**
 * Helper function to simplify the usage of the {@link CpfGenerator} class.
 *
 * If no options are provided, it generates an 11-digit unformatted numeric CPF
 * (e.g., `12345678901`) using default settings. If options are provided, they
 * control prefix and whether the result is formatted.
 *
 * @throws {CpfGeneratorOptionsTypeError} If any option has an invalid type.
 * @throws {CpfGeneratorOptionPrefixInvalidException} If the `prefix` option
 *   contains an invalid combination of digits.
 * @see CpfGenerator for detailed option descriptions.
 */
declare function cpfGen(options?: CpfGeneratorOptionsInput): string;

/**
 * Generator for CPF (Cadastro de Pessoa Física) identifiers. Builds valid
 * 11-digit CPF values by combining an optional prefix with a randomly generated
 * sequence and computed check digits. Options control prefix and whether the
 * result is formatted (`000.000.000-00`).
 */
declare class CpfGenerator {
    private _options;
    /**
     * Creates a new `CpfGenerator` with optional default options.
     *
     * Default options apply to every call to `generate` unless overridden by the
     * per-call `options` argument. Options control prefix and whether the
     * generated CPF is formatted.
     *
     * When `defaultOptions` is a `CpfGeneratorOptions` instance, that instance is
     * used directly (no copy is created). Mutating it later (e.g. via the
     * `options` getter or the original reference) affects future `generate` calls
     * that do not pass per-call options. When a plain object or nothing is
     * passed, a new `CpfGeneratorOptions` instance is created from it.
     *
     * @throws {CpfGeneratorOptionsTypeError} If any option has an invalid type.
     * @throws {CpfGeneratorOptionPrefixInvalidException} If the `prefix` option
     *   contains an invalid combination of digits.
     */
    constructor(defaultOptions?: CpfGeneratorOptionsInput);
    /**
     * Returns the default options used by this generator when per-call options
     * are not provided.
     *
     * The returned object is the same instance used internally; mutating it (e.g.
     * via setters on `CpfGeneratorOptions`) affects future `generate` calls that
     * do not pass `options`.
     */
    get options(): CpfGeneratorOptions;
    /**
     * Generates a valid CPF value.
     *
     * Builds a 9-digit CPF from the configured prefix (if any), a random sequence
     * of digits, and two computed check digits. If formatting is enabled, the
     * result is returned as `000.000.000-00`.
     *
     * Per-call `options` are merged over the instance default options for this
     * call only; the instance defaults are unchanged.
     *
     * @throws {CpfGeneratorOptionsTypeError} If any option has an invalid type.
     * @throws {CpfGeneratorOptionPrefixInvalidException} If the `prefix` option
     *   contains an invalid combination of digits.
     */
    generate(options?: CpfGeneratorOptionsInput): string;
}

/**
 * Base error class for all `cpf-gen` type-related errors.
 *
 * This abstract class extends the native `TypeError` and serves as the base for
 * all type validation errors in the CPF generator. It ensures proper prototype
 * chain setup and automatically sets the error name from the constructor.
 */
declare abstract class CpfGeneratorTypeError extends TypeError {
    readonly name: string;
    readonly actualInput: unknown;
    readonly actualType: string;
    readonly expectedType: string;
    constructor(actualInput: unknown, actualType: string, expectedType: string, message: string);
}
/**
 * Error raised when a specific option in the generator configuration has an
 * invalid type. The error message includes the option name, the actual input
 * type and the expected type.
 */
declare class CpfGeneratorOptionsTypeError extends CpfGeneratorTypeError {
    readonly optionName: keyof CpfGeneratorOptionsType;
    constructor(optionName: keyof CpfGeneratorOptionsType, actualInput: unknown, expectedType: string);
}
/**
 * Base exception for all `cpf-gen` rules-related errors.
 *
 * This abstract class extends the native `Error` and serves as the base for all
 * non-type-related errors in the `CpfGenerator` and its dependencies. It is
 * suitable for validation errors, range errors, and other business logic
 * exceptions that are not strictly type-related. It ensures proper prototype
 * chain setup and automatically sets the error name from the constructor.
 */
declare abstract class CpfGeneratorException extends Error {
    readonly name: string;
    constructor(message: string);
}
/**
 * Exception raised when the CPF option `prefix` is invalid. This is a business
 * logic exception and it is highly recommended that users of the library catch
 * it and handle it appropriately.
 */
declare class CpfGeneratorOptionPrefixInvalidException extends CpfGeneratorException {
    readonly actualInput: string;
    readonly reason: string;
    constructor(actualInput: string, reason: string);
}

declare const _default: typeof cpfGen & {
    CpfGenerator: typeof CpfGenerator;
    CPF_LENGTH: 11;
    CPF_PREFIX_MAX_LENGTH: number;
    CpfGeneratorOptions: typeof CpfGeneratorOptions;
    CpfGeneratorTypeError: typeof CpfGeneratorTypeError;
    CpfGeneratorOptionsTypeError: typeof CpfGeneratorOptionsTypeError;
    CpfGeneratorException: typeof CpfGeneratorException;
    CpfGeneratorOptionPrefixInvalidException: typeof CpfGeneratorOptionPrefixInvalidException;
};

export = _default;