kazakhstan-utils

Утилиты на TypeScript для казахстанских данных: валидация ИИН и IBAN, нормализация телефонов и адресов, сверка ФИО в кириллице и латинице.

Код извлечён из production-сервиса электронных договоров, где эти функции работают с реальным пользовательским вводом. Все данные в тестах вымышленные.

Read in English

Установка

npm install kazakhstan-utils

Нужен Node.js 18 или новее. Сборка ESM, типы TypeScript в комплекте.

Быстрый старт

import { validateKzIin, validateKzIban, formatKzPhoneInput } from "kazakhstan-utils"

validateKzIin("850101123458")          // true
validateKzIban("KZ971234567890123456") // true
formatKzPhoneInput("87001234567")      // "+7 (700) 123-45-67"

Работающие примеры — в папке examples/.

API

Идентификаторы

validateKzIin(iin: string): boolean

Проверяет 12-значный ИИН по контрольной сумме, включая второй набор весов — он применяется, когда первый проход даёт остаток 10.

validateKzBin(bin: string): boolean
binEntityType(bin: string): "resident" | "non-resident" | "personal" | null

Проверяет БИН — бизнес-аналог ИИН. Оба формата состоят из 12 цифр и используют одну и ту же контрольную сумму, поэтому validateKzBin не отличает одно от другого: валидный ИИН её проходит, и наоборот.

binEntityType читает пятую цифру — она кодирует, юрлицо это резидент, нерезидент или ИП. У ИИН в этой позиции цифры частично пересекаются, поэтому результат стоит считать сильной подсказкой, а не доказательством.

validateKzIban(iban: string): boolean
formatKzIban(raw: string | null | undefined): string

Проверяет казахстанский IBAN по ISO 13616 (mod-97, контрольные цифры 02–98) и форматирует группами по четыре. Пробелы во вводе игнорируются.

Данные для тестов

generateTestIin(opts: { year, month, day, sequence }): string | null
completeIin(prefix: string): string | null
iinCheckDigit(prefix: string): number | null

Собирает валидные по структуре ИИН для тестов. Придуманный вручную ИИН почти никогда не проходит проверку, потому что двенадцатая цифра — контрольная сумма. Возвращает null для редких префиксов, у которых валидной цифры не существует.

Полученные номера корректны структурно, но не принадлежат никому. Не используй их как замену настоящих идентификационных данных.

Телефоны

normalizeKzPhoneDigits(input: string): string | null
coerceKzPhonePartialDigits(input: string): string
formatKzPhoneInput(input: string): string

normalizeKzPhoneDigits даёт форму для хранения — 11 цифр, начиная с 7 — или null, если ввод не может быть казахстанским номером. Переваривает вставку из Word, WhatsApp и Excel.

formatKzPhoneInput даёт форму для показа, +7 (700) 123-45-67, форматируя прогрессивно по мере набора.

Адреса

normalizeCity(raw: string | null | undefined): string
normalizeAddress(raw: string | null | undefined): string

Приводит к единому виду названия городов и адреса: варианты префикса (город, г., дублирование) и регистр.

ФИО

isStrongNameMismatch(a: string, b: string): boolean
nameTokens(name: string): Set<string>

Определяет, что два написания имени точно относятся к разным людям. Терпимо к порядку слов, инициалам, отсутствию отчества и кириллице против латиницы; транслитерация следует паспортным правилам (х → kh, й → y).

Возвращает true только при явном расхождении, поэтому подходит как блокирующая проверка и не отсекает легитимных пользователей.

Оверлеи в PDF

resolveOverlayRect(placement, page): OverlayRect

Переводит «куда пользователь поставил элемент в превью» в координаты PDF: переворачивает ось Y, ограничивает размер, удерживает элемент в границах страницы.

Границы применимости

Прочти до того, как полагаться на библиотеку в проверках, от которых что-то зависит.

validateKzIin проверяет только контрольную сумму. Она не подтверждает, что номер кому-то выдан: двенадцать нулей проверку проходят. Дата рождения в первых шести цифрах тоже не валидируется. Для подтверждения личности нужна сверка по государственной базе.

Телефонные функции расходятся на десятизначном вводе. normalizeKzPhoneDigits("7001234567") достраивает код страны и даёт 77001234567, а formatKzPhoneInput трактует ведущую семёрку как код страны и выдаёт +7 (001) 234-56-7. Поведение зафиксировано тестами; исправление ломает совместимость и отложено до 1.0.0.

Лишние цифры отбрасываются молча. Ввод из двенадцати цифр обрезается до одиннадцати, а не отвергается — получается правдоподобный, но другой номер. Если важно поймать опечатку, проверяй длину сам.

Разработка

npm install
npm test        # 99 тестов
npm run build   # сборка в dist/
npm run typecheck

CI прогоняет тесты на Node 18, 20 и 22.

Лицензия

Apache 2.0