vakit

Türkçe tarih ve zaman yardımcıları. Gün/ay adları, biçimlendirme, göreli zaman ("3 saat önce") ve tarih hesaplamaları için sıfır bağımlılıklı, tam tip destekli küçük bir kütüphane.

📖 Dokümantasyon: https://emrekayik.github.io/vakit/

• Bağımlılık yok — sadece yerleşik Date.
• ESM + CommonJS — import ve require birlikte desteklenir.
• TypeScript — tipler pakete dahil.
• Saf fonksiyonlar — girdi tarihleri asla değiştirilmez.
• Test edilmiş — %90+ kapsam eşiği CI'da zorunlu.

Kurulum

npm install vakit

Hızlı başlangıç

import { bicimle, gorece, gunAdi, ekle } from 'vakit';

gunAdi(); // 'Cumartesi'
bicimle(new Date(), 'DD MMMM YYYY, DDDD'); // '09 Mart 2024, Cumartesi'
gorece(Date.now() - 3600_000); // '1 saat önce'
ekle(new Date(), 3, 'gun'); // 3 gün sonrası (yeni Date)

CommonJS:

const { gunAdi } = require('vakit');

Tüm fonksiyonlar tarih girdisi olarak Date, zaman damgası (ms) veya ayrıştırılabilir bir metin kabul eder. Girdi verilmezse şu an kullanılır. Geçersiz tarihlerde TypeError fırlatılır.

API

Takvim bilgileri

| Fonksiyon | Açıklama | Örnek | | --------------------- | -------------------------------------------- | ------------- | | gunAdi(t?) | Günün Türkçe adı | 'Cumartesi' | | gunAdiKisa(t?) | Kısaltılmış gün adı | 'Cmt' | | ayAdi(t?) | Ayın Türkçe adı | 'Mart' | | ayAdiKisa(t?) | Kısaltılmış ay adı | 'Mar' | | haftaninGunu(t?) | Haftanın günü, Pazar = 0 | 6 | | haftaninGunuTR(t?) | Haftanın günü, Pazartesi = 1 … Pazar = 7 | 6 | | ayinKaci(t?) | Ayın kaçıncı günü | 9 | | ayNo(t?) | Ay numarası (1-12) | 3 | | yil(t?) | Dört haneli yıl | 2024 | | ceyrek(t?) | Yılın çeyreği (1-4) | 1 | | haftaNo(t?) | ISO 8601 hafta numarası | 10 | | yilinGunu(t?) | Yılın kaçıncı günü (1-366) | 69 | | ayinGunSayisi(t?) | Ayın çektiği gün sayısı | 31 | | artikYilMi(t? \| y) | Artık yıl mı (tarih ya da doğrudan yıl alır) | true | | haftaSonuMu(t?) | Cumartesi/Pazar mı | true | | haftaIciMi(t?) | Hafta içi mi | false |

Biçimlendirme

bicimle(new Date(2024, 2, 9, 14, 5), 'DD MMMM YYYY, DDDD HH:mm');
// '09 Mart 2024, Cumartesi 14:05'

| Fonksiyon | Açıklama | Örnek | | --------------------- | ------------------------------- | ------------------------- | | bicimle(t?, kalip?) | Kalıba göre biçimlendirir | '09.03.2024 14:05' | | tarihMetni(t?) | GG.AA.YYYY | '09.03.2024' | | saat(t?, saniyeli?) | SS:DD (veya SS:DD:ss) | '14:05' | | uzunTarih(t?) | Uzun Türkçe tarih | '9 Mart 2024 Cumartesi' | | isoGun(t?) | Yerel saatte YYYY-AA-GG | '2024-03-09' | | gorece(t, olcum?) | Göreli zaman metni | '3 saat önce' | | sure(ms) | Süreyi okunabilir metne çevirir | '2 saat 5 dakika' |

Biçim jetonları

| Jeton | Anlam | Örnek | | ------- | ------------------- | ----------- | | YYYY | Yıl (4 hane) | 2024 | | YY | Yıl (2 hane) | 24 | | MMMM | Ay adı | Mart | | MMM | Kısa ay adı | Mar | | MM | Ay (2 hane) | 03 | | M | Ay | 3 | | DDDD | Gün adı | Cumartesi | | DDD | Kısa gün adı | Cmt | | DD | Gün (2 hane) | 09 | | D | Gün | 9 | | DDDDD | Yılın günü | 69 | | HH | Saat (2 hane, 0-23) | 14 | | H | Saat | 14 | | mm | Dakika (2 hane) | 05 | | m | Dakika | 5 | | ss | Saniye (2 hane) | 03 | | s | Saniye | 3 | | SSS | Milisaniye (3 hane) | 042 | | W | ISO hafta numarası | 10 | | Q | Çeyrek | 1 |

Köşeli parantez içindeki metin olduğu gibi bırakılır: bicimle(t, '[Bugün] DDDD') → 'Bugün Cumartesi'.

Hesaplama ve karşılaştırma

| Fonksiyon | Açıklama | | --------------------------------------- | ------------------------------------------ | | ekle(t, miktar, birim) | Zaman ekler, yeni Date döndürür | | cikar(t, miktar, birim) | Zaman çıkarır | | fark(a, b?) | a - b farkı (ms) | | gunFarki(a, b?) | Tam gün farkı (saat bilgisi yok sayılır) | | ayniGunMu(a, b) | Aynı güne mi denk geliyor | | bugunMu(t?) dunMu(t?) yarinMu(t?) | Gün kontrolleri | | gecmisMi(t?) gelecekMi(t?) | Geçmiş/gelecek kontrolü | | arasindaMi(t, bas, bit) | Aralıkta mı (sınırlar dahil, sıra önemsiz) | | yas(dogum, olcum?) | Tamamlanmış yaş | | gunBasi(t?) gunSonu(t?) | Günün 00:00:00.000 / 23:59:59.999 anı | | tarihe(t?) | Girdiyi doğrulayıp Datee çevirir |

Birimler: 'saniye' | 'dakika' | 'saat' | 'gun' | 'hafta' | 'ay' | 'yil'.

Ay eklemesi ay sonu taşmasını önler:

ekle('2024-01-31', 1, 'ay'); // 29 Şubat 2024 (1 Mart değil)

Sabitler

import { GUNLER, GUNLER_KISA, AYLAR, AYLAR_KISA, MS } from 'vakit';

GUNLER; // ['Pazar', 'Pazartesi', ...] — Date#getDay sırasıyla
AYLAR; // ['Ocak', 'Şubat', ...]
MS.gun; // 86400000

vakit kısayol nesnesi

Eski sürümlerle uyumluluk için korunur. v0.x'ten farklı olarak değerler modül yüklenirken değil, çağrı anında hesaplanır.

import { vakit } from 'vakit';

vakit.bugun(); // 'Cumartesi'
vakit.bugunR(); // 6
vakit.ayinKaci(); // 9
vakit.buay(); // 'Mart'
vakit.buyil(); // 2024

v0.x'ten geçiş

| v0.x | v1.x | | ---------------------------------------------------- | ----------------------------------- | | Tarih modül yüklenirken sabitleniyordu | Her çağrıda güncel tarih kullanılır | | buay() ayları bir kaydırıyordu (Ocak yerine Şubat) | Ay adları doğru döner | | Pazar için undefined dönüyordu | Tüm günler doğru döner | | Modül yüklenince console.log çalışıyordu | Yan etki yok | | Sadece CommonJS | ESM + CJS + TypeScript tipleri |

vakit.* çağrıları aynı şekilde çalışmaya devam eder.

Geliştirme

npm install
npm test          # vitest
npm run lint      # eslint
npm run typecheck # tsc --noEmit
npm run build     # tsup (dist/)
npm run docs      # docs sitesini üretir (site/)

Sürüm yayınlamak için: package.json içindeki sürümü yükseltin, vX.Y.Z biçiminde bir etiket atın ve GitHub'da bir release yayımlayın — .github/workflows/publish.yml paketi npm'e provenance ile yükler.

Lisans

MIT © emrekayik