@indodev/toolkit 0.4.2 → 0.6.0

package/dist/nik/index.d.cts

@@ -1,353 +1,47 @@
-/**
- * Validates a NIK (Nomor Induk Kependudukan) format.
- *
- * A valid NIK must:
- * - Be exactly 16 digits
- * - Have a valid province code (positions 1-2)
- * - Have a valid date (positions 7-12)
- * - Not be in the future
- * - Not be before 1900
- *
- * For female NIKs, the day is encoded as (actual day + 40).
- * For example, a female born on the 15th would have day = 55.
- *
- * @param nik - The 16-digit NIK string to validate
- * @returns `true` if the NIK is valid, `false` otherwise
- *
- * @example
- * ```typescript
- * validateNIK('3201234567890123'); // true - valid NIK
- * validateNIK('1234'); // false - wrong length
- * validateNIK('9912345678901234'); // false - invalid province
- * ```
- *
- * @public
- */
-declare function validateNIK(nik: string): boolean;
-
-/**
- * Information extracted from a valid NIK.
- *
- * Contains parsed data including location codes, birth date, gender,
- * and serial number from a 16-digit NIK string.
- *
- * @public
- */
-interface NIKInfo {
-    /**
-     * Province information extracted from positions 1-2 of the NIK.
-     *
-     * @example
-     * ```typescript
-     * { code: '32', name: 'Jawa Barat' }
-     * ```
-     */
-    province: {
-        /** Two-digit province code (e.g., '32') */
-        code: string;
-        /** Full province name (e.g., 'Jawa Barat') */
-        name: string;
-    };
-    /**
-     * Regency (Kabupaten/Kota) information extracted from positions 3-4 of the NIK.
-     *
-     * @example
-     * ```typescript
-     * { code: '01', name: 'Kab. Bogor' }
-     * ```
-     */
-    regency: {
-        /** Two-digit regency code (e.g., '01') */
-        code: string;
-        /** Full regency name (e.g., 'Kab. Bogor') */
-        name: string;
-    };
-    /**
-     * District (Kecamatan) information extracted from positions 5-6 of the NIK.
-     * May be `null` if district data is not available.
-     *
-     * @example
-     * ```typescript
-     * { code: '23', name: 'Ciawi' }
-     * ```
-     */
-    district: {
-        /** Two-digit district code (e.g., '23') */
-        code: string;
-        /** Full district name, or `null` if data unavailable */
-        name: string | null;
-    };
-    /**
-     * Birth date extracted from positions 7-12 of the NIK.
-     * For females, the day is encoded as (actual day + 40).
-     * Returns `null` if the date is invalid.
-     *
-     * @example
-     * ```typescript
-     * new Date(1989, 0, 31) // January 31, 1989
-     * ```
-     */
-    birthDate: Date | null;
-    /**
-     * Gender derived from the day encoding in the NIK.
-     * - 'male': day is 1-31
-     * - 'female': day is 41-71 (actual day + 40)
-     * - `null`: if unable to determine
-     */
-    gender: 'male' | 'female' | null;
-    /**
-     * Serial number from positions 13-16 of the NIK.
-     * Uniquely identifies individuals with the same location and birth date.
-     * Returns `null` if unable to extract.
-     *
-     * @example
-     * ```typescript
-     * '0123'
-     * ```
-     */
-    serialNumber: string | null;
-    /**
-     * Whether the NIK passed validation checks.
-     * If `false`, other fields may be `null` or contain partial data.
-     */
-    isValid: boolean;
-}
-/**
- * Options for masking a NIK to protect privacy.
- *
- * Controls how many characters to show at the start and end,
- * what character to use for masking, and optional separators.
- *
- * @example
- * ```typescript
- * // Default: shows first 4 and last 4 digits
- * { start: 4, end: 4, char: '*' }
- * // Result: '3201********0123'
- *
- * // With separator
- * { start: 4, end: 4, char: '*', separator: '-' }
- * // Result: '3201-****-****-0123'
- * ```
- *
- * @public
- */
-interface MaskOptions {
-    /**
-     * Number of characters to show at the start.
-     *
-     * @defaultValue 4
-     */
-    start?: number;
-    /**
-     * Number of characters to show at the end.
-     *
-     * @defaultValue 4
-     */
-    end?: number;
-    /**
-     * Character to use for masking hidden digits.
-     *
-     * @defaultValue '*'
-     */
-    char?: string;
-    /**
-     * Optional separator to add between groups of digits.
-     * If provided, the NIK will be formatted with separators.
-     *
-     * @defaultValue undefined (no separator)
-     *
-     * @example
-     * ```typescript
-     * '-' // Results in format: '3201-****-****-0123'
-     * ' ' // Results in format: '3201 **** **** 0123'
-     * ```
-     */
-    separator?: string;
-}
-/**
- * Error thrown when an invalid NIK is provided to a function.
- * Extends native Error with a `code` property for programmatic error handling.
- *
- * @example
- * ```typescript
- * try {
- *   requireNIK('invalid');
- * } catch (error) {
- *   if (error instanceof InvalidNIKError) {
- *     console.log(error.code); // 'INVALID_NIK'
- *   }
- * }
- * ```
- *
- * @public
- */
-declare class InvalidNIKError extends Error {
-    /** Error code for programmatic identification */
-    readonly code: "INVALID_NIK";
-    constructor(message?: string);
-}
+import { c as NIKValidationResult } from '../utils-DT8-jt63.cjs';
+export { A as Age, G as GetAgeOptions, I as InvalidNIKError, M as MaskOptions, j as NIKErrorCode, N as NIKInfo, h as NIKValidationError, d as compareNIK, a as formatBirthDate, f as formatNIK, g as getAge, e as isAdult, b as isValidForBirthDate, i as isValidForGender, m as maskNIK, p as parseNIK, v as validateNIK } from '../utils-DT8-jt63.cjs';
 
 /**
- * Parses a NIK and extracts all embedded information.
+ * Cleans a NIK by removing all non-digit characters.
  *
- * Extracts province, regency, district codes, birth date, gender,
- * and serial number from a 16-digit NIK string.
+ * Accepts NIK in any format (with separators like `.`, `-`, ` `) and
+ * returns a clean 16-digit string. Returns empty string for invalid inputs.
  *
- * @param nik - The 16-digit NIK string to parse
- * @returns Parsed NIK information, or `null` if the NIK format is invalid
+ * @param nik - NIK in any format
+ * @returns Clean 16-digit NIK or empty string if invalid
  *
  * @example
- * Parse a valid male NIK:
  * ```typescript
- * const info = parseNIK('3201018901310123');
- * console.log(info);
- * // {
- * //   province: { code: '32', name: 'Jawa Barat' },
- * //   regency: { code: '01', name: 'Kab. Bogor' },
- * //   district: { code: '01', name: null },
- * //   birthDate: Date(1989, 0, 31), // Jan 31, 1989
- * //   gender: 'male',
- * //   serialNumber: '0123',
- * //   isValid: true
- * // }
- * ```
- *
- * @example
- * Parse a female NIK (day + 40):
- * ```typescript
- * const info = parseNIK('3201019508550123');
- * console.log(info.gender); // 'female'
- * console.log(info.birthDate); // Date(1995, 7, 15) - Aug 15, 1995
- * ```
- *
- * @example
- * Invalid NIK returns null:
- * ```typescript
- * const info = parseNIK('invalid');
- * console.log(info); // null
+ * cleanNIK('32-01-01-89-01-31-0123'); // '3201018901310123'
+ * cleanNIK('3201.8901.3101.23'); // '32018901310123' (only 14 digits - invalid)
+ * cleanNIK('invalid'); // ''
  * ```
  *
  * @public
  */
-declare function parseNIK(nik: string): NIKInfo | null;
+declare function cleanNIK(nik: string): string;
 
 /**
- * Formats a NIK with separators for better readability.
- *
- * Groups the NIK into logical segments: province, regency, district,
- * year, month, day, and serial number.
- *
- * @param nik - The 16-digit NIK string to format
- * @param separator - Character to use as separator
- * @returns Formatted NIK string, or original string if invalid format
- *
- * @example
- * Default separator (dash):
- * ```typescript
- * formatNIK('3201234567890123');
- * // '32-01-23-45-67-89-0123'
- * ```
- *
- * @example
- * Custom separator:
- * ```typescript
- * formatNIK('3201234567890123', ' ');
- * // '32 01 23 45 67 89 0123'
- * ```
- *
- * @example
- * Invalid NIK returns as-is:
- * ```typescript
- * formatNIK('1234');
- * // '1234'
- * ```
- *
- * @public
- */
-declare function formatNIK(nik: string, separator?: string): string;
-/**
- * Masks a NIK to protect privacy while keeping partial visibility.
- *
- * By default, shows the first 4 and last 4 digits, masking the middle 8.
- * Optionally formats the masked NIK with separators.
- *
- * @param nik - The 16-digit NIK string to mask
- * @param options - Masking configuration options
- * @returns Masked NIK string, or original string if invalid format
- *
- * @example
- * Default masking (first 4, last 4):
- * ```typescript
- * maskNIK('3201234567890123');
- * // '3201********0123'
- * ```
+ * Validates a NIK and returns detailed error information.
  *
- * @example
- * Custom mask character:
- * ```typescript
- * maskNIK('3201234567890123', { char: 'X' });
- * // '3201XXXXXXXX0123'
- * ```
+ * Unlike `validateNIK` which returns a boolean, this function provides
+ * structured error reporting for form validation use cases.
  *
- * @example
- * With separator:
- * ```typescript
- * maskNIK('3201234567890123', { separator: '-' });
- * // '32-01-**-**-**-**-0123'
- * ```
+ * @param nik - The NIK string to validate (accepts any format with separators)
+ * @returns Detailed validation result with errors array
  *
  * @example
- * Custom start and end:
  * ```typescript
- * maskNIK('3201234567890123', { start: 6, end: 4 });
- * // '320123******0123'
+ * const result = validateNIKDetailed('3201018901310123');
+ * if (!result.isValid) {
+ *   result.errors.forEach(err => {
+ *     console.log(`${err.code}: ${err.message}`);
+ *   });
+ * }
  * ```
  *
  * @public
  */
-declare function maskNIK(nik: string, options?: MaskOptions): string;
-
-/**
- * Calculates the age of a person based on their NIK.
- *
- * @param nik - The 16-digit NIK string
- * @param referenceDate - The date to calculate age from (default: current date)
- * @returns The age in years, or null if the NIK is invalid or birth date cannot be parsed
- *
- * @example
- * ```typescript
- * getAge('3201018901310123'); // 35 (as of 2024)
- * ```
- */
-declare function getAge(nik: string, referenceDate?: Date): number | null;
-/**
- * Formats the birth date from a NIK into a human-readable string.
- *
- * @param nik - The 16-digit NIK string
- * @param locale - The locale to use for formatting (default: 'id-ID')
- * @returns Formatted birth date string, or null if invalid
- *
- * @example
- * ```typescript
- * formatBirthDate('3201018901310123'); // '31 Januari 1989'
- * ```
- */
-declare function formatBirthDate(nik: string, options?: Intl.DateTimeFormatOptions, locale?: string): string | null;
-/**
- * Checks if a NIK matches a specific gender.
- *
- * @param nik - The 16-digit NIK string
- * @param gender - The gender to check ('male' | 'female')
- * @returns True if the NIK matches the gender, false otherwise
- */
-declare function isValidForGender(nik: string, gender: 'male' | 'female'): boolean;
-/**
- * Checks if a NIK matches a specific birth date.
- *
- * @param nik - The 16-digit NIK string
- * @param birthDate - The birth date to check
- * @returns True if the NIK matches the birth date, false otherwise
- */
-declare function isValidForBirthDate(nik: string, birthDate: Date): boolean;
+declare function validateNIKDetailed(nik: string): NIKValidationResult;
 
-export { InvalidNIKError, type MaskOptions, type NIKInfo, formatBirthDate, formatNIK, getAge, isValidForBirthDate, isValidForGender, maskNIK, parseNIK, validateNIK };
+export { NIKValidationResult, cleanNIK, validateNIKDetailed };