@apideposu/tr-validation

@apideposu/tr-validation, Turkiye'ye ozgu form verileri icin local-only calisan bir dogrulama ve normalizasyon paketidir.

English documentation: README.md

Local-Only ve Gizlilik

• Paket tamamen kullanicinin kendi projesi icinde calisir.
• API Deposu backend'ine istek atmaz.
• Veriyi disari gondermez.
• Registry lookup yapmaz.
• Telemetry, analytics veya network call icermez.
• Resmi kisi, sirket, vergi veya banka hesabi dogrulamasi yapmaz.
• Sadece yapisal kontrol, bilinen kontrol algoritmalari ve normalizasyon saglar.

Sinirlar

• validateIban yalnizca TR IBAN icin calisir.
• normalizePhone guncel operatoru dogrulamaz ve numara tasima kayitlarini sorgulamaz.
• possibleOriginalOperator alani sadece prefix tabanli bir ipucudur.
• normalizeProvince ve normalizeDistrict, canli resmi kayitlar yerine paketle gelen statik veri setini kullanir.
• Merkez gibi belirsiz ilce adlarinda province context gerekebilir.
• Basarili sonuc, resmi dogrulama yapildigi anlamina gelmez.

Kurulum

npm install @apideposu/tr-validation

Hizli Baslangic

import {
  normalizePhone,
  validateIban,
  validateTckn,
} from "@apideposu/tr-validation";

const tckn = validateTckn("100 000 001-46");
const iban = validateIban("tr62 0001 0012 3456 7890 1234 56");
const phone = normalizePhone("0532 123 45 67");

Mevcut Kapsam

Export edilen fonksiyonlar:

• validateTckn
• validateVkn
• validateIban
• formatIban
• normalizeTurkishText
• slugifyTurkish
• normalizePhone
• getProvinces
• getDistrictsByProvince
• normalizeProvince
• normalizeDistrict
• validateBatch
• getReasonMessage

API Ozeti

Temel validation result yapisi:

{
  ok: boolean;
  input: string;
  normalized: string;
  reasons: string[];
  mode: "structural_validation" | "number_plan_parse" | "static_dataset";
  localOnly: true;
  officialVerification: false;
  registryLookup: false;
}

Fonksiyon ozeti:

| Fonksiyon | Amac | Not | | --- | --- | --- | | validateTckn(input) | TCKN icin yapisal kontrol | Sadece format + bilinen kontrol algoritmasi | | validateVkn(input) | VKN icin yapisal kontrol | Sadece format + bilinen kontrol algoritmasi | | validateIban(input) | TR IBAN icin yapisal kontrol | TR-only, MOD-97 checksum | | formatIban(input) | IBAN'i 4'lu gruplar halinde formatlar | Separator ve casing normalize edilir | | normalizeTurkishText(input) | Turkce odakli text normalization | trimmed, normalized, ascii, slug, searchKey doner | | slugifyTurkish(input) | Turkce slug helper | normalizeTurkishText(input).slug ile tutarlidir | | normalizePhone(input, options?) | Turk telefon numarasini local normalize eder | e164, national, country, type ve prefix tabanli operator hint ekler | | getProvinces() | Paket icindeki il listesini doner | Sadece statik dataset | | getDistrictsByProvince(provinceCodeOrSlug) | Bir ile ait ilceleri doner | Sadece statik dataset | | normalizeProvince(input) | Il kodu, adi veya slug ile eslesme yapar | Basariliysa province doner | | normalizeDistrict(input, options?) | Ilce eslesmesi yapar, gerekirse province context kullanir | Basariliysa district ve province doner | | validateBatch(items) | Karisik validator/parser islemlerini sirayla calistirir | Input sirasini korur ve mevcut core fonksiyonlara delege eder | | getReasonMessage(code, locale?) | Reason code'lari UI dostu metne cevirir | Form ve import akislari icin tr / en mesajlar saglar |

Genis Kullanim

import {
  formatIban,
  getDistrictsByProvince,
  getProvinces,
  normalizeDistrict,
  normalizePhone,
  normalizeProvince,
  normalizeTurkishText,
  slugifyTurkish,
  getReasonMessage,
  validateBatch,
  validateIban,
  validateTckn,
  validateVkn,
} from "@apideposu/tr-validation";

const tckn = validateTckn("100 000 001-46");
const vkn = validateVkn("734.033.4753");
const iban = validateIban("tr62 0001 0012 3456 7890 1234 56");
const formattedIban = formatIban("tr620001001234567890123456");
const text = normalizeTurkishText("  ISTANBUL / Kadikoy  ");
const slug = slugifyTurkish("Cekmekoy Belediyesi");

const phone = normalizePhone("0532 123 45 67");
const provinces = getProvinces();
const districts = getDistrictsByProvince("34");
const province = normalizeProvince("Istanbul");
const district = normalizeDistrict("Kadikoy", { province: "34" });
const batch = validateBatch([
  { type: "tckn", value: "10000000146" },
  { type: "iban", value: "TR62 0001 0012 3456 7890 1234 56" },
  { type: "phone", value: "0532 123 45 67" },
]);
const message = getReasonMessage("INVALID_CHECKSUM", "tr");

CommonJS:

const {
  normalizePhone,
  validateIban,
  validateTckn,
} = require("@apideposu/tr-validation");

const result = normalizePhone("0532 123 45 67");

Ornek Sonuclar

normalizePhone("0532 123 45 67");
// {
//   ok: true,
//   input: "0532 123 45 67",
//   normalized: "+905321234567",
//   reasons: [],
//   mode: "number_plan_parse",
//   localOnly: true,
//   officialVerification: false,
//   registryLookup: false,
//   e164: "+905321234567",
//   national: "0532 123 45 67",
//   extension: null,
//   country: "TR",
//   type: "mobile",
//   possibleOriginalOperator: "Turkcell",
//   operatorConfidence: "prefix_based"
// }

normalizeProvince("34");
// {
//   ok: true,
//   input: "34",
//   normalized: "istanbul",
//   reasons: [],
//   mode: "static_dataset",
//   localOnly: true,
//   officialVerification: false,
//   registryLookup: false,
//   province: {
//     code: "34",
//     name: "Istanbul",
//     normalized: "istanbul",
//     phoneAreaCodes: ["212", "216"],
//     districtCount: 39
//   }
// }

normalizeDistrict("Merkez");
// {
//   ok: false,
//   input: "Merkez",
//   normalized: "merkez",
//   reasons: ["AMBIGUOUS_DISTRICT"],
//   mode: "static_dataset",
//   localOnly: true,
//   officialVerification: false,
//   registryLookup: false,
//   district: null,
//   province: null
// }

Reason Codes

Ortak reason code'lar:

| Kod | Anlami | | --- | --- | | EMPTY_INPUT | Normalizasyondan sonra input bos kaldi | | UNSUPPORTED_CHARACTERS | Input desteklenmeyen karakterler iceriyor | | INVALID_LENGTH | Uzunluk beklenen yapisal uzunluga uymuyor | | INVALID_CHECKSUM | Bilinen kontrol algoritmasini gecemedi |

TCKN'ye ozel:

| Kod | Anlami | | --- | --- | | LEADING_ZERO | Ilk hane 0 | | REPEATED_DIGITS | Tum haneler ayni |

VKN'ye ozel:

| Kod | Anlami | | --- | --- | | REPEATED_DIGITS | Tum haneler ayni |

IBAN'a ozel:

| Kod | Anlami | | --- | --- | | NON_TR_IBAN | IBAN TR ile baslamiyor |

Phone'a ozel:

| Kod | Anlami | | --- | --- | | INVALID_PHONE | Input gecerli bir telefon numarasi olarak parse edilemedi | | NON_TR_PHONE | Numara gecerli ama Turk numarasi degil |

Location'a ozel:

| Kod | Anlami | | --- | --- | | PROVINCE_NOT_FOUND | Il eslesmesi cozulemedi | | DISTRICT_NOT_FOUND | Ilce eslesmesi cozulemedi | | AMBIGUOUS_DISTRICT | Ilce adi birden fazla ilde bulunuyor |

Notlar

• normalizePhone, libphonenumber-js paketini local olarak kullanir.
• possibleOriginalOperator, sadece numara prefix'inden turetilir ve numara tasima nedeniyle guncel olmayabilir.
• getProvinces ve getDistrictsByProvince, paketle gelen statik JSON verisini kullanir.
• normalizeProvince ve normalizeDistrict, statik dataset ile Turkce text normalization yaklasimini birlikte kullanir.
• validateIban, sadece TR IBAN icin yapisal kontrol ve MOD-97 checksum uygular.

Opsiyonel Adapter Paketleri

Yayindaki ekosistem paketleri:

• @apideposu/tr-validation-zod
  • npm: https://www.npmjs.com/package/@apideposu/tr-validation-zod
  • GitHub: https://github.com/apideposu/tr-validation-zod
  • amac: stabil core validator'lar icin opsiyonel Zod schema ve helper wrapper'lari

Dokumanlar

• Katki rehberi: CONTRIBUTING.md
• Dataset maintenance: DATASETS.md
• Ekosistem yol haritasi: ECOSYSTEM_ROADMAP.md
• Ornekler: examples/README.md
• Release notes: RELEASE_NOTES.md
• Roadmap: ROADMAP.md

Gelistirme

npm run datasets:check
npm test
npm run build
npm run smoke:runtime
npm run size:check
npm run benchmark