Moment.js Alternatifleri: Node.js Geçiş Rehberi ve Karşılaştırması

Production sistemlerde zaman yönetimi, varsayılanların (yerel sistem saati, örtük timezone, new Date() ayrıştırması) düğümler, diller ve katmanlar arasında farklılaşması nedeniyle sessiz bir hata kaynağıdır. İstek güncel yerel bir tarih taşımasına rağmen “geçmiş tarihli işlem” hatası veren bir ödeme, genellikle istemcinin duvar saati, uygulama sunucusunun yorumu ve veritabanının saklama formatı arasında bir timezone-offset hatasıdır. Her yerde UTC kullanmak ve ofset dönüşümünü yalnızca görüntüleme sınırında yapmak bu hata sınıfını tamamen ortadan kaldırır; ancak her API, log, şema ve test fikstürü sınırında disiplin gerektirir.

Bu kuraldan çıkan varsayılan, çoğu ekibin beklediğinden daha küçüktür: biçimlendirmeyi yerleşik Intl.DateTimeFormat ile, saklamayı Date.prototype.toISOString() ile yapın. Kütüphaneye ancak platformun karşılamadığı bir ayrıştırma, takvim aritmetiği veya token biçimlendirmesi gerektiğinde uzanın. Moment.js’den çıkıp en küçük diff’i istiyorsanız tercih Day.js; tree-shaking ve tipli fonksiyon import’ları API alışkanlığından önemliyse date-fns.

Production’a Ulaşan İki Zaman Hatası#

Tarih Aralığı Hesabında Mutation#

Yaygın bir hata şekli: Moment.js’in mutable Date object’lerini kullanan bir timezone işlemi orijinal girdiyi bozar; sonraki query’ler yanlış başlangıç tarihiyle çalışır ve UI Invalid Date hatalarıyla dolar. Sorunu doğuran şekil:

// Felakete yol açan kod
const moment = require('moment');

const generateReport = (startDate) => {
  const reportStart = moment(startDate);
  const reportEnd = reportStart.add(7, 'days'); // MUTABLE! startDate'i bozdu
  
  // startDate artık 7 gün ileride
  return getTransactionsBetween(startDate, reportEnd);
};

Çözüm, Moment.js’in hangi metotlarının mutasyona yol açtığını akılda tutmak değil. Date object’leri hiç değiştirilemeyen bir kütüphane seçmek; böylece bu hata şekline ulaşmak mümkün olmaktan çıkar.

Ödeme Doğrulamasında Tarih Sınırı#

İkinci şekil doğrulama kodunda yaşar. Gece yarısından hemen sonra gönderilen ödemeler “geçmiş tarihli işlem” hatasıyla reddedilir, business logic ise incelendiğinde hâlâ doğru görünür. Uyuşmazlık, aynı anın iki farklı zaman dilimine göre iki kez biçimlendirilmesindedir.

// Sorunlu kod: Timezone karışıklığı
const processPayment = (paymentDate: string) => {
  const localDate = moment(paymentDate).format('YYYY-MM-DD');
  const utcDate = moment.utc(paymentDate).format('YYYY-MM-DD');
  
  if (localDate !== utcDate) {
    throw new Error('Geçmiş tarihli işlem');
  }
  
  return processPaymentLogic();
};

İstanbul timezone’ında saat 00:30’da yapılan bir ödeme, zaman dilimi UTC’nin üç saat ilerisinde olduğu için UTC’de bir önceki günün 21:30’una denk gelir. Bu fark yüzünden localDate ile utcDate farklı çıkar ve ödeme reddedilir.

Moment.js’i Bırakma Nedenleri#

Moment.js uzun yıllar boyunca JavaScript zaman işlemlerinin kralıydı, ama zamanla sorunlar birikti:

1. Bundle Size Problemi#

Moment.js varsayılan olarak tüm locale’leri paketler; ağırlığının büyük kısmı buradan gelir. Kendi belgeleri sonucu açıkça yazıyor: kütüphane “modern ‘tree shaking’ algoritmalarıyla iyi çalışmıyor, bu yüzden web uygulaması bundle’larının boyutunu artırma eğiliminde.” Onlarca kilobayt ile ölçülen bir bundle bütçesinde, UI runtime’ından daha pahalı bir tarih biçimlendiricisini savunmak zor.

# Minified, tüm locale'ler paketlenmiş halde (moment'in varsayılanı)
moment.js:     >200KB
dayjs:         ~7KB çekirdek, eklentiler istendiğinde yüklenir
date-fns:      import edilen fonksiyon başına, tree-shaken
vanilla Date:  0KB, runtime'ın içinde

2. Mutable Object Tuzağı#

Moment.js’in en büyük tasarım kusuru mutability. Bir date object’i değiştirdiğinizde, orijinal referans da değişir:

const moment = require('moment');

const originalDate = moment('2025-01-01');
const nextWeek = originalDate.add(7, 'days');

console.log(originalDate.format()); // 2025-01-08 (!)
console.log(nextWeek.format());  // 2025-01-08

Bu, özellikle React component’larında beklenmedik re-render’lara yol açar.

3. Tree-shaking Yokluğu#

Moment.js monolitik bir yapıda. Sadece format() metodunu kullansanız bile tüm kütüphane bundle’a dahil olur. Modern bundler’lar bunu optimize edemez.

Modern Alternatifler: Karşılaştırma#

Neredeyse her geçişi üç seçenek karşılar: Day.js, date-fns ve platformun kendisi.

Day.js: En Kolay Geçiş#

Artıları:

• Moment.js API’sine neredeyse birebir
• Küçük çekirdek, eklentiler öncesinde yaklaşık 7KB
• Immutable objects
• Plugin sistemi ile genişletilebilir

Eksileri:

• Temel özellikler için plugin yüklemek gerekiyor
• Dokümantasyon bazen eksik
• Daha küçük topluluk

// Moment.js'den Day.js'e geçiş - çağrı şekli neredeyse aynı
const dayjs = require('dayjs');
dayjs.extend(require('dayjs/plugin/utc'));
dayjs.extend(require('dayjs/plugin/timezone'));

// Moment.js: .tz() moment core'da değil, moment-timezone'da
const moment = require('moment-timezone');
const withMoment = moment.utc('2025-01-01').tz('Europe/Istanbul');

// Day.js: aynı şekil, eklentiler yukarıda kaydedildi
const withDayjs = dayjs.utc('2025-01-01').tz('Europe/Istanbul');

Geçişin tek gerçek tuzağı bu eklenti ayrımı. Eksik bir dayjs.extend(timezone) çağrısı build sırasında hata vermez; ilk .tz() çağrısına hangi request yolu önce ulaşırsa orada patlar.

date-fns: Fonksiyonel Programlama Yaklaşımı#

Artıları:

• Mükemmel tree-shaking (sadece kullandığınız fonksiyonlar bundle’a dahil)
• Tasarımı gereği immutable
• TypeScript desteği harika
• Lodash tarzı API

Eksileri:

• Öğrenme eğrisi var
• Timezone desteği için date-fns-tz paketi gerekiyor
• Söz dizimi daha uzun

import { format, addDays, parseISO } from 'date-fns';

// Fonksiyonel yaklaşım - her fonksiyon immutable
const originalDate = parseISO('2025-01-01');
const nextWeek = addDays(originalDate, 7);

console.log(format(originalDate, 'yyyy-MM-dd')); // 2025-01-01 (unchanged!)
console.log(format(nextWeek, 'yyyy-MM-dd'));  // 2025-01-08

Vanilla JavaScript: Modern API Değerlendirmesi#

ES2015’ten bu yana JavaScript’in tarih yetenekleri belirgin şekilde gelişti. Özellikle Intl API’si modern tarayıcılarda çok güçlü.

// Modern JavaScript ile timezone handling
const date = new Date('2025-01-01T12:00:00Z');

// Intl API ile locale-aware formatting
const istanbulTime = new Intl.DateTimeFormat('tr-TR', {
  timeZone: 'Europe/Istanbul',
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit'
}).format(date);

console.log(istanbulTime); // 01.01.2025 15:00

Production’da UTC Stratejisi#

Kuralın tamamını iki sınır taşır: veritabanının sakladığı değer ve response’un render ettiği değer.

Veritabanı Katmanı: Sadece UTC#

// Database'e her zaman UTC olarak kaydet
const saveUserAction = async (userId: number, action: string) => {
  const timestamp = new Date().toISOString(); // UTC ISO string
  
  await db.query(
    'INSERT INTO user_actions (user_id, action, created_at) VALUES (?, ?, ?)',
    [userId, action, timestamp]
  );
};

API Katmanı: UTC’den Yerel Saate Dönüşüm#

// API response'unda client timezone'ına göre convert et
const getUserActions = async (userId: number, clientTimezone: string) => {
  const actions = await db.query(
    'SELECT * FROM user_actions WHERE user_id = ? ORDER BY created_at DESC',
    [userId]
  );
  
  return actions.map(action => ({
    ...action,
    created_at: action.created_at, // UTC olarak bırak
    local_time: new Intl.DateTimeFormat('en-US', {
      timeZone: clientTimezone,
      year: 'numeric',
      month: '2-digit', 
      day: '2-digit',
      hour: '2-digit',
      minute: '2-digit'
    }).format(new Date(action.created_at))
  }));
};

Ayrıştırma ve Biçimlendirme Maliyetini Ölçmek#

Bundle boyutunu kütüphaneler arasında karşılaştırmak kolay. Çalışma zamanı maliyeti değil; çünkü Node.js sürümüne, kullanılan format token’larına ve çağrının timezone veritabanına dokunup dokunmadığına bağlı. Başkasının dizüstü bilgisayarından çıkan bir sayıya güvenmek yerine döngüyü kendi hedef sürümünüzde çalıştırın:

// Benchmark setup
const iterations = 100000;
const testDate = '2025-01-01T12:00:00Z';

// Test 1: Date parsing
console.time('Moment.js parsing');
for (let i = 0; i < iterations; i++) {
  moment(testDate).format('YYYY-MM-DD');
}
console.timeEnd('Moment.js parsing');

console.time('Day.js parsing');  
for (let i = 0; i < iterations; i++) {
  dayjs(testDate).format('YYYY-MM-DD');
}
console.timeEnd('Day.js parsing');

console.time('date-fns parsing');
for (let i = 0; i < iterations; i++) {
  format(parseISO(testDate), 'yyyy-MM-dd');
}
console.timeEnd('date-fns parsing');

console.time('Vanilla JS parsing');
for (let i = 0; i < iterations; i++) {
  new Date(testDate).toISOString().split('T')[0];
}
console.timeEnd('Vanilla JS parsing');

Mutlak sayılar değişse de sıralama sabit kalır. Yerleşik Date yolu önde; çünkü bir sarmalayıcı nesneyi ve bir token ayrıştırıcısını atlar. date-fns ile Day.js onun hemen üstünde birbirine yakın konumlanır. Moment.js ayrıştırma ağırlıklı döngülerde belirgin şekilde geride kalır, çünkü her çağrı mutable bir sarmalayıcı ayırır ve kendi format ayrıştırıcısını yeniden çalıştırır.

Bu fark yalnızca tarih işlemleri sıcak yolda olduğunda önem taşır: toplu işler, rapor üretimi, büyük sonuç kümelerinin serialize edilmesi. İstek başına birkaç biçimlendirme için gürültüden ibarettir; orada bundle boyutu daha iyi bir ayırt edicidir.

DST ve Timezone Uç Durumları#

DST Geçiş Problemi#

Daylight Saving Time geçişlerinde saatler ya geri ya ileri alınır ve yerel bir gün 24 saat olmaktan çıkar. Hata, geçen süre ile duvar saati aynı soruymuş gibi ele alındığında ortaya çıkar.

import { addDays } from 'date-fns';
import { fromZonedTime, toZonedTime } from 'date-fns-tz';

// Tehlikeli: "yarın aynı saat"i sabit milisaniye eklemesiyle bulmak
const sameTimeTomorrow = (start: Date) =>
  new Date(start.getTime() + 24 * 60 * 60 * 1000);
// DST sınırında bu, bir saat erkene ya da geçe düşer

// Güvenli: geçen süre mutlaktır, epoch milisaniyesinden ölçün
const elapsedHours = (start: Date, end: Date) =>
  (end.getTime() - start.getTime()) / 3600000;

// Güvenli: duvar saati bir takvim sorusudur; yerel saati timezone
// farkında bir yardımcıyla yeniden kurup UTC'ye geri çevirin
const sameLocalTimeTomorrow = (start: Date, timeZone: string) =>
  fromZonedTime(addDays(toZonedTime(start, timeZone), 1), timeZone);

Takvim Aritmetiği Uç Durumları#

// Örtük: hafta sonu kontrolü, container'ın devraldığı TZ'ye uyar
const addBusinessDays = (date: Date, days: number) => {
  const result = new Date(date);
  let addedDays = 0;
  
  while (addedDays < days) {
    result.setDate(result.getDate() + 1);
    // getDay() kimsenin bilerek seçmediği process timezone'ını okur
    if (result.getDay() !== 0 && result.getDay() !== 6) {
      addedDays++;
    }
  }
  return result;
};

// Açık: takvim UTC, çünkü bu bilinçli olarak verilmiş bir karar
const addBusinessDaysUTC = (date: Date, days: number) => {
  const result = new Date(date);
  let addedDays = 0;
  
  while (addedDays < days) {
    result.setUTCDate(result.getUTCDate() + 1);
    // UTC day check
    if (result.getUTCDay() !== 0 && result.getUTCDay() !== 6) {
      addedDays++;
    }
  }
  return result;
};

UTC, ancak iş UTC üzerinden yürüyorsa doğru iş takvimidir. İstanbul’da pazartesi gece yarısından hemen sonra verilen bir sipariş UTC’de hâlâ pazardır; dolayısıyla UTC’ye göre yapılan bir hafta sonu kontrolü, operasyon ekibinin iş günü saydığı bir günü atlar. İkinci sürümün asıl kazancı açıklıktır: zaman dilimi, devralınan bir ortam değişkeni olmaktan çıkıp bilinçli bir tercihe dönüşür. Takvim belirli bir pazara aitse, o pazarın IANA tanımlayıcısını parametre olarak geçirin ve gün kontrolünü orada yapın.

Geçiş Stratejisi: Adım Adım#

1. Envanter Çıkarma#

# Kod tabanındaki Moment.js kullanımını bul
grep -r "moment\|\.format\|\.add\|\.subtract" src/
rg "require.*moment|import.*moment" --type ts --type js

2. Kademeli Geçiş#

// 1. Adım: Utility functions oluştur
const dateUtils = {
  format: (date: Date | string, format: string) => {
    // İlk başta Moment.js wrapper
    return moment(date).format(format);
  },
  
  addDays: (date: Date | string, days: number) => {
    return moment(date).add(days, 'days').toDate();
  }
};

// 2. Adım: Moment.js'i utility functions'a replace et
// Before:
const formatted = moment(date).format('YYYY-MM-DD');
// After:
const formatted = dateUtils.format(date, 'YYYY-MM-DD');

// 3. Adım: Utility functions'ın implementation'ını değiştir
// (aynı modül, aynı export; fonksiyon başına tek satırlık takas)
const dateUtils = {
  format: (date: Date | string, format: string) => {
    // Artık Day.js kullan
    return dayjs(date).format(format);
  },
  
  addDays: (date: Date | string, days: number) => {
    return dayjs(date).add(days, 'day').toDate();
  }
};

3. Test Stratejisi#

Bir timezone testinin anlam taşıması için iki şeyin sabitlenmesi gerekir: saat ve zaman dilimi. Sadece Date.now’u stub’lamak yetmez, çünkü new Date() sistem saatini doğrudan okur. Zaman dilimi ise süreç başlamadan önce verilmelidir; çalışma sırasında process.env.TZ’ye yapılan atama güvenilir şekilde dikkate alınmaz. Seçilen an da zaman dilimi kadar önemli. 21:30 UTC’de İstanbul takvimi çoktan ertesi güne geçmiştir; yukarıdaki sürüm geçerli bir ödemeyi tam burada reddeder. Akşamın erken saatlerine denk gelen bir an ise testi sınıra hiç dokunmadan geçirir.

// Testleri sabit bir zaman diliminde çalıştırın: TZ=Europe/Istanbul npx jest
describe('Payment processing', () => {
  beforeEach(() => {
    jest.useFakeTimers();
    // İstanbul'da 00:30, UTC'de hâlâ bir önceki gün
    jest.setSystemTime(new Date('2025-01-01T21:30:00.000Z'));
  });

  afterEach(() => {
    jest.useRealTimers();
  });

  it('yerel gece yarısından hemen sonraki ödemeyi kabul eder', () => {
    const result = processPayment(new Date().toISOString());
    expect(result).toBeTruthy();
  });
});

İzleme ve Alarm#

Zaman hataları sessizdir; işe yarayan sinyal iki saat arasındaki uyuşmazlıktır. Monotonik bir sayaç ile duvar saati aynı aralığı ölçmelidir; ayrıştıklarında host saati sıçramış demektir.

// Time-related metrics tracking
const trackTimeOperation = async (operation: string, fn: () => Promise<any>) => {
  const start = process.hrtime.bigint();
  const startDate = new Date();
  
  try {
    const result = await fn();
    
    const duration = Number(process.hrtime.bigint() - start) / 1000000;
    
    // Metrics'e gönder
    metrics.histogram('time_operation_duration', duration, {
      operation,
      success: 'true'
    });
    
    // Duvar saati - monotonik saat: fark, host saatinin oynadığını gösterir
    const endDate = new Date();
    const expectedDuration = endDate.getTime() - startDate.getTime();
    
    if (Math.abs(duration - expectedDuration) > 1000) { // 1 saniye threshold
      logger.warn('Time drift detected', {
        operation,
        measured: duration,
        expected: expectedDuration,
        drift: Math.abs(duration - expectedDuration)
      });
    }
    
    return result;
  } catch (error) {
    metrics.histogram('time_operation_duration', 0, {
      operation,
      success: 'false'
    });
    throw error;
  }
};

Kütüphane Seçimi#

Seçim, ekibin büyüklüğünden değil, kodun tarihlerle ne yaptığından çıkar:

Sadece Biçimlendirme: Vanilla JavaScript + Intl#

Gereksinim, saklanmış bir timestamp’i kullanıcının zaman diliminde göstermekten ibaretse Intl.DateTimeFormat bunu sıfır bundle maliyeti, native performans ve runtime’ın kendi timezone veritabanıyla karşılar.

Denge: ISO-8601 dışındaki her ayrıştırma ve takvim aritmetiği elde kalır; yukarıdaki mutation ve tarih sınırı hataları da tam olarak elle yazılmış yardımcılardan doğar. Kendi addMonths fonksiyonunuzu yazdığınız anda sıfır bağımlılık argümanı tükenmiş olur.

// Basit ama güçlü
const formatDate = (date: Date, locale: string, timeZone: string) => {
  return new Intl.DateTimeFormat(locale, {
    timeZone,
    year: 'numeric',
    month: 'long', 
    day: 'numeric'
  }).format(date);
};

Moment.js’den Geçiş: Day.js#

Mevcut kod tabanı moment() çağrılarıyla doluysa en küçük diff’i Day.js verir. Çağrı şekli korunur, nesneler immutable olur ve bundle bir büyüklük mertebesi küçülür.

Denge: çekirdek küçüktür, çünkü büyük kısmı isteğe bağlıdır. utc, timezone, customParseFormat ve duration ayrı birer plugin olarak gelir ve kaydedilmeleri gerekir; eksik bir extend çağrısı build sırasında değil, çalışma zamanında ortaya çıkar.

import dayjs from 'dayjs';
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';

dayjs.extend(utc);
dayjs.extend(timezone);

const formatForTimezone = (date: string, tz: string) => {
  return dayjs.utc(date).tz(tz).format('MMM DD, YYYY HH:mm');
};

Yoğun Tarih Mantığı: date-fns#

Tarihler bir görüntüleme ayrıntısı değil de alan modelinin parçasıysa fonksiyonel API kendini amorti eder: her import bağımsızdır, tree-shaking yalnızca çağırdığınızı bırakır ve tipler her işlemi net biçimde tarif eder.

Denge: zincirlenebilir bir API’ye göre daha uzun yazılır ve timezone işleri, ana sürümü çekirdeği takip etmek zorunda olan ayrı date-fns-tz paketinde yaşar.

import { parseISO } from 'date-fns';
import { formatInTimeZone } from 'date-fns-tz';

// Her fonksiyon bağımsız olarak import edilebilir
// formatInTimeZone date-fns-tz'den gelir: z/zzz token'ları
// çekirdek format() tarafından desteklenmez
const processDate = (dateString: string, timeZone: string) =>
  formatInTimeZone(parseISO(dateString), timeZone, 'yyyy-MM-dd HH:mm:ss zzz');

Production Checklist: Zaman Yönetimi#

• UTC standardı: Tüm timestamp’ler UTC’de saklanıyor
• Sınırda dönüşüm: Timezone dönüşümü görüntüleme katmanında yapılıyor
• DST testi: DST geçiş tarihleri için testler var
• Bundle boyutu: Tarih kütüphanesinin bundle etkisi kabul edilebilir
• Performans ölçümü: Sıcak yollardaki tarih işlemleri ölçüldü
• Timezone doğrulama: Kullanıcıdan gelen timezone değerleri doğrulanıyor
• Hata yönetimi: Geçersiz tarihler düzgün şekilde ele alınıyor
• İzleme: Zaman kaynaklı hatalar için alarm var

UTC Kuralı Nerede Geçerli, Nerede Değil#

UTC’de saklayıp dönüşümü görüntüleme sınırında yapın; bu ofset hatası sınıfının tamamı uygulama kodundan erişilemez hale gelir. Kural, bir timestamp’in olup bitmiş bir şeyi kaydettiği her yerde geçerlidir: audit log’ları, oluşturma ve güncelleme kolonları, event akışları, metrikler.

Gelecekteki duvar saati taahhütlerinde ise çöker. Gelecek mart ayında yerel saatle 09:00’daki bir toplantı, tekrarlayan bir bordro işi, bir mağazanın çalışma saatleri: bunların yerel saat artı IANA zaman dilimi tanımlayıcısı olarak saklanması gerekir, çünkü o zaman diliminin ofseti tarih gelmeden değişebilir. Bunları yazma anında tek bir UTC anına indirgemek, bir tzdata sürümünün geçersiz kılabileceği bir ofseti kalıcı hale getirir.

Kod tabanında hâlâ Moment.js varsa en ucuz geçiş sırası şudur: her çağrıyı küçük tek bir iç modülden geçirin, o modülün implementation’ını değiştirin, sonra bağımlılığı silin. Hangi kütüphanede karar kıldığınız, kütüphanenin değişebileceği tek bir yerin bulunmasından çok daha az önemlidir.

Kaynaklar#

• Moment.js Proje Durumu - momentjs.com (yeni sekmede açılır) - Bakımcıların Moment’i bakım modundaki bir legacy proje olarak tanımladığı açıklama; mutability ve tree-shaking gerekçeleriyle birlikte
• Day.js Timezone Eklentisi - day.js.org (yeni sekmede açılır) - .tz() desteği için eklenti referansı; utc eklentisi bağımlılığı ve gereken extend kaydı dahil
• date-fns Dokümantasyonu - date-fns.org (yeni sekmede açılır) - Tree-shaking’e uygun fonksiyonel API için fonksiyon referansı ve import rehberi
• date-fns-tz - github.com/marnusw (yeni sekmede açılır) - formatInTimeZone, fromZonedTime, toZonedTime ve çekirdek format()’ın desteklemediği z/zzz token’larını belgeleyen timezone paketi
• Intl.DateTimeFormat - MDN (yeni sekmede açılır) - timeZone ve timeZoneName seçenekleri dahil, yerleşik locale ve timezone farkında biçimlendirici referansı
• Date - MDN (yeni sekmede açılır) - toISOString, UTC erişim metotları ve ISO-8601 ile diğer girdiler arasında farklılaşan ayrıştırma kurallarını kapsayan platform referansı
• Temporal Önerisi - tc39.es (yeni sekmede açılır) - Date’in TC39 tarafından hazırlanan halefi; anlar, takvim tarihleri ve zaman dilimli tarih-saatler için ayrı tipler
• IANA Zaman Dilimi Veritabanı - iana.org (yeni sekmede açılır) - Timezone farkında her kütüphanenin dayandığı zaman dilimi tanımlayıcıları ve ofset geçmişi; ayrıca bunları değiştiren sürüm takvimi
• Node.js Sürümleri - LTS Programı (yeni sekmede açılır) - Tarih işlemlerinin hangi runtime üzerinde ölçüleceğine karar verirken işe yarayan resmi Node.js sürüm takvimi