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 `Date`e ç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.