@indodev/toolkit 0.0.1

package/dist/nik/index.d.cts

@@ -0,0 +1,288 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+export { type MaskOptions, type NIKInfo, formatNIK, maskNIK, parseNIK, validateNIK };

package/dist/nik/index.d.ts

@@ -0,0 +1,288 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+export { type MaskOptions, type NIKInfo, formatNIK, maskNIK, parseNIK, validateNIK };