@lacussoft/cnpj-gen

/** * Lacus Solutions :: cnpj-gen v3.0.0 * * @author Julio L. Muller. * @license MIT - 2021-2026 */ import { Nullable, SequenceType } from '@lacussoft/utils'; /** * Class to store the options for the CNPJ generator. This class provides a * centralized way to configure how CNPJ characters are generated, including * partial start string, formatting, and the type of characters to be generated * (numeric, alphabetic, or alphanumeric). */ declare class CnpjGeneratorOptions { /** * Default value for the `format` option. When `true`, the generated CNPJ * string will have the standard formatting (`00.000.000/0000-00`). */ static readonly DEFAULT_FORMAT = false; /** * Default string used as the initial string of the generated CNPJ. */ static readonly DEFAULT_PREFIX = ""; /** * Default type of characters to generate for the CNPJ. */ static readonly DEFAULT_TYPE: CnpjType; private _options; /** * Creates a new instance of `CnpjGeneratorOptions`. * * Options can be provided in multiple ways: * * 1. As a single options object or another `CnpjGeneratorOptions` 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 {CnpjGeneratorOptionsTypeError} If any option has an invalid type. * @throws {CnpjGeneratorOptionPrefixInvalidException} If the `prefix` option * contains invalid combination of characters. * @throws {CnpjGeneratorOptionTypeInvalidException} If the `type` option is * not one of the allowed values. */ constructor(defaultOptions?: CnpjGeneratorOptionsInput, ...overrides: CnpjGeneratorOptionsInput[]); /** * 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(): CnpjGeneratorOptionsType; /** * Gets whether the generated CNPJ string will have the standard formatting * (`00.000.000/0000-00`). */ get format(): boolean; /** * Sets whether the generated CNPJ string will have the standard formatting * (`00.000.000/0000-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 CNPJ. * * Note: If the evaluated prefix (after stripping non-alphanumeric characters) * is longer than 12 characters, the extra characters are ignored, because a * CNPJ has 12 base characters followed by 2 calculated check digits. */ get prefix(): string; /** * Sets the string used as the initial string of the generated CNPJ. Only * alphanumeric characters are kept and the rest is stripped. If provided, * only the missing characters are generated randomly. For example, if the * prefix `AAABBB` (6 characters) is given, only the next 8 characters are * randomly generated and concatenated to the prefix. * * Note: If the evaluated prefix (after stripping non-alphanumeric characters) * is longer than 12 characters, the extra characters are ignored, because a * CNPJ has 12 base characters followed by 2 calculated check digits. * * @throws {CnpjGeneratorOptionsTypeError} If the value is not a string. * @throws {CnpjGeneratorOptionPrefixInvalidException} If the `prefix` option * contains invalid combination of characters or is too long. */ set prefix(value: Nullable<string>); /** * Gets the type of characters to generate for the CNPJ. */ get type(): CnpjType; /** * Sets the type of characters to generate for the CNPJ. * * The options are: * * - `alphabetic`: Generates a sequence of alphabetic characters (`A-Z`). * - `alphanumeric`: Generates a sequence of alphanumeric characters (`0-9A-Z`). * - `numeric`: Generates a sequence of numbers-only characters (`0-9`). * * @throws {CnpjGeneratorOptionsTypeError} If the value is not a string. * @throws {CnpjGeneratorOptionTypeInvalidException} If the value is not a * valid type. */ set type(value: Nullable<CnpjType>); /** * 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 `CnpjGeneratorOptions` instance. * * @throws {CnpjGeneratorOptionsTypeError} If any option has an invalid type. * @throws {CnpjGeneratorOptionPrefixInvalidException} If the `prefix` option * contains invalid combination of characters or is too long. * @throws {CnpjGeneratorOptionTypeInvalidException} If the `type` option is * not one of the allowed values. */ set(options: CnpjGeneratorOptionsInput): this; /** * Throws if the prefix's first 8 characters (base ID) are all zeros. * * @throws {CnpjGeneratorOptionPrefixInvalidException} If the prefix's first 8 * characters are all zeros. */ private _validatePrefixBaseId; /** * Throws if the prefix's characters at positions 9–12 (branch ID) are all * zeros. * * @throws {CnpjGeneratorOptionPrefixInvalidException} If the prefix's * characters at positions 9–12 are all zeros. */ private _validatePrefixBranchId; /** * Throws if the prefix has 12 characters and they are all the same digit. * * @throws {CnpjGeneratorOptionPrefixInvalidException} If the prefix has 12 * characters that are all the same digit. */ private _validatePrefixNonRepeatedDigits; } /** * Character type for the generated CNPJ sequence. * * - `alphanumeric` (default): Generates a sequence of alphanumeric characters * (`0-9A-Z`). * - `numeric`: Generates a sequence of numbers-only characters (`0-9`). * - `alphabetic`: Generates a sequence of alphabetic characters (`A-Z`). */ type CnpjType = SequenceType; /** * Configuration type for CNPJ (Cadastro Nacional da Pessoa Jurídica) generation * options. Defines the resolved options used internally: format (standard * formatting), prefix (partial start string), and type (character set). All * properties have default values when creating a `CnpjGeneratorOptions` * instance. */ interface CnpjGeneratorOptionsType { /** * Whether to format the generated CNPJ string with the standard formatting * (`00.000.000/0000-00`). * * @default false */ format: boolean; /** * A partial string containing 0 to 12 alphanumeric characters to use as the * start of the generated CNPJ. Only alphanumeric characters are kept; the * rest is stripped. If provided, only the missing characters are generated * randomly. For example, if the prefix `AAABBB` (6 characters) is given, only * the next 8 characters are randomly generated and concatenated to the * prefix. * * A common use case is to provide a base ID (first 8 characters) and let the * library generate the branch ID (characters 9 to 12) for multiple runs. This * way you can gen multiple CNPJ's under the same "business umbrella". * * Note: If the evaluated prefix (after stripping non-alphanumeric characters) * is longer than 12 characters, the extra characters are ignored, because a * CNPJ has 12 base characters followed by 2 calculated check digits. * * @default '' */ prefix: string; /** * The type of characters to generate for the CNPJ. If a `prefix` is provided, * only the remaining characters (those generated randomly) use this type. * * The options are: * * - `alphabetic`: Generates a sequence of alphabetic characters (`A-Z`). * - `alphanumeric`: Generates a sequence of alphanumeric characters (`0-9A-Z`). * - `numeric`: Generates a sequence of numbers-only characters (`0-9`). * * @default 'alphanumeric' */ type: CnpjType; } type CnpjGeneratorOptionsInput = CnpjGeneratorOptions | Partial<CnpjGeneratorOptionsType>; /** * Helper function to simplify the usage of the {@link CnpjGenerator} class. * * If no options are provided, it generates a 14-character unformatted * alphanumeric CNPJ (e.g., `AB123CDE000155`). using default settings. If * options are provided, they control prefix, type, and whether the result is * formatted. * * @throws {CnpjGeneratorOptionsTypeError} If any option has an invalid type. * @throws {CnpjGeneratorOptionPrefixInvalidException} If the `prefix` option * contains an invalid combination of characters. * @throws {CnpjGeneratorOptionTypeInvalidException} If the `type` option is not * one of the allowed values. * @see CnpjGenerator for detailed option descriptions. */ declare function cnpjGen(options?: CnpjGeneratorOptionsInput): string; /** * Generator for CNPJ (Cadastro Nacional da Pessoa Jurídica) identifiers. Builds * valid 14-character CNPJ values by combining an optional prefix with a * randomly generated sequence and computed check digits. Options control * prefix, character type (numeric, alphabetic, or alphanumeric), and whether * the result is formatted (`00.000.000/0000-00`). */ declare class CnpjGenerator { private _options; /** * Creates a new `CnpjGenerator` with optional default options. * * Default options apply to every call to `generate` unless overridden by the * per-call `options` argument. Options control prefix, character type, and * whether the generated CNPJ is formatted. * * When `defaultOptions` is a `CnpjGeneratorOptions` 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 `CnpjGeneratorOptions` instance is created from it. * * @throws {CnpjGeneratorOptionsTypeError} If any option has an invalid type. * @throws {CnpjGeneratorOptionPrefixInvalidException} If the `prefix` option * contains an invalid combination of characters. * @throws {CnpjGeneratorOptionTypeInvalidException} If the `type` option is * not one of the allowed values. */ constructor(defaultOptions?: CnpjGeneratorOptionsInput); /** * 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 `CnpjGeneratorOptions`) affects future `generate` calls that * do not pass `options`. */ get options(): CnpjGeneratorOptions; /** * Generates a valid CNPJ value. * * Builds a 14-character CNPJ from the configured prefix (if any), a random * sequence of the configured character type, and two computed check digits. * If formatting is enabled, the result is returned as `00.000.000/0000-00`. * * Per-call `options` are merged over the instance default options for this * call only; the instance defaults are unchanged. * * @throws {CnpjGeneratorOptionsTypeError} If any option has an invalid type. * @throws {CnpjGeneratorOptionPrefixInvalidException} If the `prefix` option * contains an invalid combination of characters. * @throws {CnpjGeneratorOptionTypeInvalidException} If the `type` option is * not one of the allowed values. */ generate(options?: CnpjGeneratorOptionsInput): string; } /** * Base error class for all `cnpj-gen` type-related errors. * * This abstract class extends the native `TypeError` and serves as the base for * all type validation errors in the CNPJ generator. It ensures proper prototype * chain setup and automatically sets the error name from the constructor. */ declare abstract class CnpjGeneratorTypeError 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 CnpjGeneratorOptionsTypeError extends CnpjGeneratorTypeError { readonly optionName: keyof CnpjGeneratorOptionsType; constructor(optionName: keyof CnpjGeneratorOptionsType, actualInput: unknown, expectedType: string); } /** * Base exception for all `cnpj-gen` rules-related errors. * * This abstract class extends the native `Error` and serves as the base for all * non-type-related errors in the `CnpjGenerator` 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 CnpjGeneratorException extends Error { readonly name: string; constructor(message: string); } /** * Exception raised when the CNPJ 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 CnpjGeneratorOptionPrefixInvalidException extends CnpjGeneratorException { readonly actualInput: string; readonly reason: string; constructor(actualInput: string, reason: string); } /** * Exception raised when the CNPJ option `type` is given a value that is not one * of the allowed values. The option must be one of the enumerated values of * {@link CnpjType}. This is a business logic exception and it is highly * recommended that users of the library catch it and handle it appropriately. */ declare class CnpjGeneratorOptionTypeInvalidException extends CnpjGeneratorException { readonly actualInput: string; readonly expectedValues: readonly string[]; constructor(actualInput: string, expectedValues: readonly string[]); } declare const _default: typeof cnpjGen & { CnpjGenerator: typeof CnpjGenerator; CNPJ_LENGTH: 14; CNPJ_PREFIX_MAX_LENGTH: number; CnpjGeneratorOptions: typeof CnpjGeneratorOptions; CnpjGeneratorTypeError: typeof CnpjGeneratorTypeError; CnpjGeneratorOptionsTypeError: typeof CnpjGeneratorOptionsTypeError; CnpjGeneratorException: typeof CnpjGeneratorException; CnpjGeneratorOptionPrefixInvalidException: typeof CnpjGeneratorOptionPrefixInvalidException; CnpjGeneratorOptionTypeInvalidException: typeof CnpjGeneratorOptionTypeInvalidException; }; export = _default;