@indodev/toolkit 0.5.0 → 0.7.0

package/dist/nik/index.d.ts

@@ -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-D4A4ro8M.js';
+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-D4A4ro8M.js';
 
 /**
- * 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 };

package/dist/nik/index.js

@@ -179,8 +179,17 @@ function maskNIK(nik, options = {}) {
   if (!/^\d{16}$/.test(nik)) {
     return nik;
   }
-  const { start = 4, end = 4, char = "*", separator } = options;
-  if (start + end >= 16) {
+  const { visibleStart, visibleEnd, maskChar, separator, start, end, char } = options;
+  const hasLegacyOptions = start !== void 0 || end !== void 0 || char !== void 0;
+  if (hasLegacyOptions) {
+    console.warn(
+      "[DEPRECATED] Mask options start/end/char are deprecated. Use visibleStart/visibleEnd/maskChar instead. These old names will be removed in v1.0.0."
+    );
+  }
+  const effectiveStart = visibleStart !== void 0 ? visibleStart : start !== void 0 ? start : 4;
+  const effectiveEnd = visibleEnd !== void 0 ? visibleEnd : end !== void 0 ? end : 4;
+  const effectiveChar = maskChar !== void 0 ? maskChar : char !== void 0 ? char : "*";
+  if (effectiveStart + effectiveEnd >= 16) {
     return nik;
   }
   if (separator) {
@@ -191,54 +200,194 @@ function maskNIK(nik, options = {}) {
       const partStart = charCount;
       const partEnd = charCount + part.length;
       charCount += part.length;
-      if (partEnd <= start) {
+      if (partEnd <= effectiveStart) {
         return part;
-      } else if (partStart >= 16 - end) {
+      } else if (partStart >= 16 - effectiveEnd) {
         return part;
-      } else if (partStart >= start && partEnd <= 16 - end) {
-        return char.repeat(part.length);
+      } else if (partStart >= effectiveStart && partEnd <= 16 - effectiveEnd) {
+        return effectiveChar.repeat(part.length);
       } else {
         return part.split("").map((ch, idx) => {
           const pos = partStart + idx;
-          if (pos < start || pos >= 16 - end) {
+          if (pos < effectiveStart || pos >= 16 - effectiveEnd) {
             return ch;
           }
-          return char;
+          return effectiveChar;
         }).join("");
       }
     });
     return maskedParts.join(separator);
   }
-  const startPart = nik.substring(0, start);
-  const endPart = nik.substring(16 - end);
-  const maskLength = 16 - start - end;
-  return startPart + char.repeat(maskLength) + endPart;
+  const startPart = nik.substring(0, effectiveStart);
+  const endPart = nik.substring(16 - effectiveEnd);
+  const maskLength = 16 - effectiveStart - effectiveEnd;
+  return startPart + effectiveChar.repeat(maskLength) + endPart;
+}
+
+// src/nik/clean.ts
+function cleanNIK(nik) {
+  if (typeof nik !== "string") {
+    return "";
+  }
+  const cleaned = nik.replace(/\D/g, "");
+  if (cleaned.length !== 16) {
+    return "";
+  }
+  return cleaned;
+}
+
+// src/nik/validate-detailed.ts
+function createError(code, message) {
+  return { code, message };
+}
+function validateNIKDetailed(nik) {
+  const cleaned = cleanNIK(nik);
+  if (cleaned === "") {
+    return {
+      isValid: false,
+      errors: [createError("INVALID_FORMAT", "NIK must be exactly 16 digits")],
+      nik: null
+    };
+  }
+  const provinceCode = cleaned.substring(0, 2);
+  if (!PROVINCES[provinceCode]) {
+    return {
+      isValid: false,
+      errors: [
+        createError(
+          "INVALID_PROVINCE",
+          `Province code ${provinceCode} not found`
+        )
+      ],
+      nik: null
+    };
+  }
+  const info = parseNIK(cleaned);
+  if (!info) {
+    return {
+      isValid: false,
+      errors: [createError("INVALID_DATE", "Invalid date components")],
+      nik: null
+    };
+  }
+  const birthDate = info.birthDate;
+  if (!birthDate) {
+    return {
+      isValid: false,
+      errors: [createError("INVALID_DATE", "Invalid birth date")],
+      nik: null
+    };
+  }
+  const now = /* @__PURE__ */ new Date();
+  if (birthDate > now) {
+    return {
+      isValid: false,
+      errors: [
+        createError("FUTURE_DATE", "Birth date cannot be in the future")
+      ],
+      nik: null
+    };
+  }
+  return {
+    isValid: true,
+    errors: [],
+    nik: cleaned
+  };
 }
 
 // src/nik/utils.ts
-function getAge(nik, referenceDate = /* @__PURE__ */ new Date()) {
+function getAge(nik, options = {}) {
+  const { referenceDate = /* @__PURE__ */ new Date(), asString = false } = options;
   const info = parseNIK(nik);
   if (!info || !info.birthDate) {
     return null;
   }
   const birthDate = info.birthDate;
-  let age = referenceDate.getFullYear() - birthDate.getFullYear();
-  const m = referenceDate.getMonth() - birthDate.getMonth();
-  if (m < 0 || m === 0 && referenceDate.getDate() < birthDate.getDate()) {
-    age--;
+  let years = referenceDate.getFullYear() - birthDate.getFullYear();
+  let months = referenceDate.getMonth() - birthDate.getMonth();
+  let days = referenceDate.getDate() - birthDate.getDate();
+  if (days < 0) {
+    months--;
+    const prevMonth = new Date(
+      referenceDate.getFullYear(),
+      referenceDate.getMonth(),
+      0
+    );
+    days += prevMonth.getDate();
+  }
+  if (months < 0) {
+    years--;
+    months += 12;
+  }
+  if (asString) {
+    const parts = [];
+    if (years > 0) parts.push(`${years} Tahun`);
+    if (months > 0) parts.push(`${months} Bulan`);
+    if (days > 0 || parts.length === 0) parts.push(`${days} Hari`);
+    return parts.join(" ");
+  }
+  return { years, months, days };
+}
+function compareNIK(nik1, nik2) {
+  const cleaned1 = cleanNIK(nik1);
+  const cleaned2 = cleanNIK(nik2);
+  if (cleaned1 === "" || cleaned2 === "" || cleaned1.length !== 16 || cleaned2.length !== 16) {
+    return false;
+  }
+  if (cleaned1 === cleaned2) {
+    return true;
+  }
+  const pos1_6_1 = cleaned1.substring(0, 6);
+  const pos1_6_2 = cleaned2.substring(0, 6);
+  if (pos1_6_1 !== pos1_6_2) {
+    return false;
+  }
+  const birthDate1 = cleaned1.substring(6, 12);
+  const birthDate2 = cleaned2.substring(6, 12);
+  if (birthDate1 !== birthDate2) {
+    return false;
+  }
+  const serial1 = cleaned1.substring(12, 16);
+  const serial2 = cleaned2.substring(12, 16);
+  return serial1 === serial2;
+}
+function isAdult(nik, minAge = 17) {
+  const age = getAge(nik);
+  if (age === null) {
+    return false;
+  }
+  if (typeof age === "string") {
+    const yearsMatch = age.match(/^(\d+)/);
+    if (yearsMatch) {
+      return parseInt(yearsMatch[1], 10) >= minAge;
+    }
+    return false;
   }
-  return age;
+  return age.years >= minAge;
 }
-function formatBirthDate(nik, options = {
-  day: "numeric",
-  month: "long",
-  year: "numeric"
-}, locale = "id-ID") {
+function formatBirthDate(nik) {
   const info = parseNIK(nik);
   if (!info || !info.birthDate) {
     return null;
   }
-  return new Intl.DateTimeFormat(locale, options).format(info.birthDate);
+  const day = info.birthDate.getDate();
+  const month = info.birthDate.getMonth();
+  const year = info.birthDate.getFullYear();
+  const monthNames = [
+    "Januari",
+    "Februari",
+    "Maret",
+    "April",
+    "Mei",
+    "Juni",
+    "Juli",
+    "Agustus",
+    "September",
+    "Oktober",
+    "November",
+    "Desember"
+  ];
+  return `${day} ${monthNames[month]} ${year}`;
 }
 function isValidForGender(nik, gender) {
   const info = parseNIK(nik);
@@ -265,6 +414,6 @@ var InvalidNIKError = class extends Error {
   }
 };
 
-export { InvalidNIKError, formatBirthDate, formatNIK, getAge, isValidForBirthDate, isValidForGender, maskNIK, parseNIK, validateNIK };
+export { InvalidNIKError, cleanNIK, compareNIK, formatBirthDate, formatNIK, getAge, isAdult, isValidForBirthDate, isValidForGender, maskNIK, parseNIK, validateNIK, validateNIKDetailed };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map