@indodev/toolkit 0.5.0 → 0.6.0

package/dist/utils-DT8-jt63.d.ts

@@ -0,0 +1,495 @@
+/**
+ * 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);
+}
+/**
+ * Error codes for detailed NIK validation.
+ *
+ * @public
+ */
+type NIKErrorCode = 'INVALID_FORMAT' | 'INVALID_PROVINCE' | 'INVALID_MONTH' | 'INVALID_DAY' | 'INVALID_DATE' | 'FUTURE_DATE';
+/**
+ * A single validation error with code and message.
+ *
+ * @public
+ */
+interface NIKValidationError {
+    /** Error code for programmatic handling */
+    code: NIKErrorCode;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Detailed validation result for NIK with structured error reporting.
+ *
+ * Use this for form validation where you need to show specific error
+ * messages per field.
+ *
+ * @example
+ * ```typescript
+ * const result = validateNIKDetailed('1234');
+ * if (!result.isValid) {
+ *   result.errors.forEach(err => {
+ *     console.log(err.code, err.message);
+ *   });
+ * }
+ * ```
+ *
+ * @public
+ */
+interface NIKValidationResult {
+    /** Whether the NIK is valid */
+    isValid: boolean;
+    /** List of validation errors (empty if valid) */
+    errors: NIKValidationError[];
+    /** Cleaned 16-digit NIK if valid, null otherwise */
+    nik: string | null;
+}
+/**
+ * Options for getAge function.
+ *
+ * @public
+ */
+interface GetAgeOptions {
+    /** Date to calculate age from (default: current date) */
+    referenceDate?: Date;
+    /** Return formatted Indonesian string instead of object */
+    asString?: boolean;
+}
+/**
+ * Age result object with years, months, and days.
+ *
+ * @public
+ */
+interface Age {
+    /** Full years */
+    years: number;
+    /** Remaining months after full years */
+    months: number;
+    /** Remaining days after full months */
+    days: number;
+}
+
+/**
+ * Parses a NIK and extracts all embedded information.
+ *
+ * Extracts province, regency, district codes, birth date, gender,
+ * and serial number from a 16-digit NIK string.
+ *
+ * @param nik - The 16-digit NIK string to parse
+ * @returns Parsed NIK information, or `null` if the NIK format is 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
+ * ```
+ *
+ * @public
+ */
+declare function parseNIK(nik: string): NIKInfo | null;
+
+/**
+ * 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'
+ * ```
+ *
+ * @example
+ * Custom mask character:
+ * ```typescript
+ * maskNIK('3201234567890123', { char: 'X' });
+ * // '3201XXXXXXXX0123'
+ * ```
+ *
+ * @example
+ * With separator:
+ * ```typescript
+ * maskNIK('3201234567890123', { separator: '-' });
+ * // '32-01-**-**-**-**-0123'
+ * ```
+ *
+ * @example
+ * Custom start and end:
+ * ```typescript
+ * maskNIK('3201234567890123', { start: 6, end: 4 });
+ * // '320123******0123'
+ * ```
+ *
+ * @public
+ */
+declare function maskNIK(nik: string, options?: MaskOptions): string;
+
+/**
+ * Calculates the age of a person based on their NIK.
+ *
+ * Returns detailed age breakdown with years, months, and days, or a
+ * formatted Indonesian string. This is consistent with `datetime.getAge()`.
+ *
+ * @param nik - The 16-digit NIK string
+ * @param options - Options object with `referenceDate` and `asString`
+ * @returns Age object `{ years, months, days }`, formatted string, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * // Returns object by default
+ * getAge('3201018901310123');
+ * // { years: 35, months: 2, days: 6 } (as of 2026-04-06)
+ *
+ * // Returns formatted string
+ * getAge('3201018901310123', { asString: true });
+ * // '35 Tahun 2 Bulan 6 Hari'
+ *
+ * // Custom reference date
+ * getAge('3201018901310123', { referenceDate: new Date('2025-01-01') });
+ * // { years: 35, months: 11, days: 1 }
+ * ```
+ *
+ * @public
+ */
+declare function getAge(nik: string, options?: GetAgeOptions): Age | string | null;
+/**
+ * Compares two NIKs to check if they belong to the same person.
+ *
+ * Two NIKs are considered the same person if they have identical:
+ * - Province code (positions 1-2)
+ * - Regency code (positions 3-4)
+ * - District code (positions 5-6)
+ * - Birth date (year + month + day)
+ * - Gender (derived from day encoding)
+ * - Serial number (positions 13-16)
+ *
+ * @param nik1 - First NIK (accepts any format)
+ * @param nik2 - Second NIK (accepts any format)
+ * @returns True if both NIKs belong to the same person, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Same person, same format
+ * compareNIK('3201018901310123', '3201018901310123'); // true
+ *
+ * // Same person, different format
+ * compareNIK('3201018901310123', '3201-01-89-01-31-0123'); // true
+ *
+ * // Different serial number
+ * compareNIK('3201018901310123', '3201018901310124'); // false
+ *
+ * // Invalid NIK
+ * compareNIK('invalid', '3201018901310123'); // false
+ * ```
+ *
+ * @public
+ */
+declare function compareNIK(nik1: string, nik2: string): boolean;
+/**
+ * Checks if a person is an adult based on their NIK.
+ *
+ * By default, uses 17 years as the threshold (Indonesian KTP eligibility age).
+ * Indonesian law allows KTP at age 17, or upon marriage, or already married.
+ *
+ * @param nik - The 16-digit NIK string
+ * @param minAge - Minimum age threshold (default: 17)
+ * @returns True if the person is at least minAge years old, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Born 1995-01-01, reference 2026-04-06 (age 31)
+ * isAdult('3201950101950123'); // true (31 >= 17)
+ * isAdult('3201950101950123', 21); // true (31 >= 21)
+ *
+ * // Born 2010-01-01, reference 2026-04-06 (age 16)
+ * isAdult('3210010101950123'); // false (16 < 17)
+ * isAdult('3210010101950123', 16); // true (16 >= 16)
+ *
+ * // Invalid NIK
+ * isAdult('invalid'); // false
+ * ```
+ *
+ * @public
+ */
+declare function isAdult(nik: string, minAge?: number): boolean;
+/**
+ * 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): 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;
+
+export { type Age as A, type GetAgeOptions as G, InvalidNIKError as I, type MaskOptions as M, type NIKInfo as N, formatBirthDate as a, isValidForBirthDate as b, type NIKValidationResult as c, compareNIK as d, isAdult as e, formatNIK as f, getAge as g, type NIKValidationError as h, isValidForGender as i, type NIKErrorCode as j, maskNIK as m, parseNIK as p, validateNIK as v };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indodev/toolkit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Indonesian developer utilities for validation, formatting, and more",
   "type": "module",
   "main": "./dist/index.cjs",