Türkiye'ye özgü işlerde her projede yeniden yazılan yardımcılar. Para, kimlik numarası, IBAN, telefon, Türkçe metin, Excel'in doğru açtığı CSV ve tarihe göre geçerli KDV oranları.
Bağımlılığı yoktur. TypeScript ile yazılmıştır, ESM olarak dağıtılır.
Bu beş konu Türkiye'de yazılan hemen her üründe çıkıyor ve her seferinde aynı hatalarla yeniden yazılıyor:
"istanbul".toUpperCase()ISTANBUL verir, İSTANBUL değil- Kuruş hesabını kayan noktayla yapınca gün sonunda hesap tutmaz
- Hesabı üçe bölünce toplam bir kuruş eksik veya fazla çıkar
"1.234"bin iki yüz otuz dört müdür, bir tam iki yüz otuz dört mü- TCKN kontrol hanesi doğrulanmadan kabul edilir
npm install github:pmwdigital/pmw-trnpm, GitHub'dan kurarken paketi prepare betiğiyle derler. Ayarlarınızda
ignore-scripts açıksa bu adım atlanır ve dist eksik kalır; o makinede
kurulumu npm install --ignore-scripts=false github:pmwdigital/pmw-tr ile yapın.
Bütün tutarlar tam sayı kuruş olarak tutulur. Kayan nokta hiç kullanılmaz.
import { para } from "@pmwdigital/tr";
para.parseKurus("1.234,56"); // 123456
para.parseKurus("1.234"); // 123400, nokta binlik ayracı
para.parseKurus("1234.56"); // 123456, nokta ondalık
para.format(123456); // "₺1.234,56"
para.addVat(10000, 0.2); // { net: 10000, vat: 2000, gross: 12000 }
para.extractVat(12000, 0.2); // { net: 10000, vat: 2000, gross: 12000 }Hesap bölmede toplam korunur, artık kuruş kaybolmaz:
para.splitEvenly(10000, 3); // [3334, 3333, 3333], toplam 10000
para.splitByShares(171050, [2,3,5]); // toplamı yine 171050extractVat yuvarlama artığını brütte bırakır, yani net + vat her zaman
gross değerine eşittir. Bu, mali fişin kendi içinde tutarlı kalması için önemlidir.
import { metin } from "@pmwdigital/tr";
metin.trUpper("istanbul"); // "İSTANBUL"
metin.trLower("ISPARTA"); // "ısparta"
metin.slug("Adı Şanlı İşkembe"); // "adi-sanli-iskembe"
metin.searchKey("ŞALGAM") === metin.searchKey("salgam"); // trueBüyük küçük harf dönüşümü ICU'ya bağlı değildir, i ve ı eşlemesi elle yapılır, her ortamda aynı sonucu verir.
Sıralama Intl.Collator("tr") kullanır, yani c ile ç, s ile ş ve i ile ı doğru
sırada gelir:
["zeytin", "çorba", "cacık", "şalgam", "salata"].sort(metin.compare);
metin.sort(urunler, (u) => u.ad);import { kimlik } from "@pmwdigital/tr";
kimlik.isValidTckn("10000000146"); // true
kimlik.isValidVkn("1234567890"); // true
kimlik.isValidTaxId(deger); // uzunluğa göre TCKN veya VKN
kimlik.maskTckn("10000000146"); // "100*****146"Bilinmesi gerekenler. TCKN doğrulaması kontrol hanesi algoritmasıdır, numaranın
gerçekten birine ait olup olmadığını söylemez. 11111111110 gibi tekrarlı diziler
checksum'dan geçer, gerçek kayıt kontrolü için NVİ servisi gerekir. VKN doğrulaması
yayımlanan GİB algoritmasını uygular ve kendi içinde tutarlıdır; bir kaydı
reddetmek için kullanmadan önce elinizdeki gerçek veriyle teyit edin.
import { iban } from "@pmwdigital/tr";
iban.isValidIban("TR33 0006 1005 1978 6457 8413 26"); // true
iban.isValidTrIban(deger); // yalnızca 26 haneli TR
iban.formatIban(deger); // dörtlü gruplar
iban.ibanBankCode(deger); // "00061"Doğrulama ISO 13616 mod 97 kuralıdır, boşluk ve küçük harf tolere edilir.
import { telefon } from "@pmwdigital/tr";
telefon.normalize("0532 123 45 67"); // "+905321234567"
telefon.normalize("(0532) 123-45-67"); // "+905321234567"
telefon.isValidMobile("0212 123 45 67"); // false
telefon.format("+905321234567"); // "0532 123 45 67"Türkçe Excel, virgülü ondalık ayracı sayar ve BOM olmadan UTF-8 dosyayı yanlış kod sayfasıyla açar. Bu yüzden varsayılanlar noktalı virgül ayraç, başta BOM ve CRLF satır sonudur.
import { csv } from "@pmwdigital/tr";
csv.build(["Ad", "Tutar"], [["Ayşe Yılmaz", csv.formatNumber(1234.5)]]);
// BOM + "Ad;Tutar\r\nAyşe Yılmaz;1234,50"
csv.escapeField("=1+1"); // "'=1+1", tablo formül diye çalıştırmaz
csv.escapeField("Yılmaz; Ayşe"); // "\"Yılmaz; Ayşe\""
csv.build(["a"], [["x"]], { bom: false, delimiter: "," }); // "a\r\nx"=, +, - ve @ ile başlayan değerlerin başına tek tırnak eklenir; adı
=cmd olan bir kayıt tabloda komut olarak çalışmaz, metin olarak görünür.
Oranlar tarihe bağlıdır: 10 Temmuz 2023'te genel oran %18'den %20'ye, indirimli oran %8'den %10'a çıktı (7346 sayılı Cumhurbaşkanı Kararı, 7 Temmuz 2023 tarihli ve 32241 sayılı Resmî Gazete). Geçmiş bir faturayı kendi gününün oranıyla göstermek için oranlar yürürlük aralığıyla tutulur.
import { kdv } from "@pmwdigital/tr";
kdv.ratesOn("2026-11-04"); // [1, 10, 20]
kdv.ratesOn("2023-07-09"); // [], paket 10 Temmuz 2023 öncesini içermez
const benimDonemlerim = [
{ rate: 1, validFrom: "2020-01-01", validUntil: null },
{ rate: 8, validFrom: "2020-01-01", validUntil: "2023-07-09" },
{ rate: 18, validFrom: "2020-01-01", validUntil: "2023-07-09" },
{ rate: 10, validFrom: "2023-07-10", validUntil: null },
{ rate: 20, validFrom: "2023-07-10", validUntil: null },
];
kdv.ratesOn("2023-07-09", benimDonemlerim); // [1, 8, 18]
kdv.withStoredRate([1, 10, 20], 18); // [1, 10, 18, 20], eski kaydı düzenlerkenBaşlangıç ve bitiş günleri dahildir. Gün YYYY-AA-GG biçiminde değilse
RangeError fırlatılır. Hangi ürünün hangi orana girdiği bu paketin işi değildir;
o karar mevzuata ve mali müşavire aittir.
npm install
npm test
npm run typecheck
npm run buildKapsam 39 testtir. Test vektörleri uydurulmamıştır: TCKN 10000000146 ve IBAN
TR330006100519786457841326 yayımlanmış örneklerdir, mod 97 sonucu bağımsız olarak
hesaplanarak doğrulanmıştır.
MIT