Node.js 26 Yenilikleri: v26 Sürümünde Neler Değişti?

Önce sürümünüzü doğrulayın

Bir özelliği denemeden önce hangi Node.js ile çalıştığınızı bilmeniz gerekir; v26 içinde bile bir özellik v26.1.0 ile, bir diğeri v26.11.0 ile gelmiş olabilir. Komut satırında node -v yeterlidir; kod içinden ise process.version ve process.versions nesnesini kullanabilirsiniz. Birden fazla sürümü yan yana kurmak için Node.js kurulumu ve sürüm yöneticileri yazısına bakın.

// surum.mjs
console.log(process.version);
console.log(process.versions.node.split('.')[0]);
// çıktı: v26.13.0
// çıktı: 26

Belgelerdeki her başlığın altında bir YAML bloğu bulunur. added satırı API'nin hangi sürümde eklendiğini, changes listesi ise sonraki davranış değişikliklerini gösterir. Bir değişiklik birden çok sürüm hattına geri taşındıysa liste birden fazla sürüm içerir. Bu yazıdaki "v26.x ile geldi" ifadelerinin hepsi bu kayıtlara dayanır. Bunun yanında her modülün ve bazı tekil API'lerin başında Stability etiketi vardır: 0 kullanımdan kaldırılmış, 1 deneysel (1.0 erken geliştirme, 1.1 etkin geliştirme, 1.2 sürüm adayı), 2 kararlı, 3 eski (legacy) anlamına gelir.

util modülüne gelen yardımcılar

v26.10.0 ile node:util içine iki zamanlama yardımcısı eklendi. util.debounce(fn, wait), art arda gelen çağrıları toplar ve son çağrıdan wait milisaniye sonra fn fonksiyonunu bir kez, en son verilen argümanlarla çalıştırır. Döndürdüğü fonksiyon bir Promise verir; varsayılan olarak o pencerede yapılan tüm çağrıların Promise'leri aynı sonuçla çözülür. rejectOnCancel seçeneği açıksa yerini yenisine bırakan çağrılar AbortError ile reddedilir. signal seçeneğiyle bir AbortSignal vererek bekleyen ve gelecekteki çağrıları iptal edebilirsiniz.

// debounce.mjs
import { debounce } from 'node:util';

let calisma = 0;
const kaydet = debounce((metin) => {
  calisma++;
  return `kaydedildi: ${metin}`;
}, 50);

const sonuclar = await Promise.all([kaydet('a'), kaydet('ab'), kaydet('abc')]);
console.log(sonuclar);
console.log('fn çağrı sayısı:', calisma);
// çıktı: [ 'kaydedildi: abc', 'kaydedildi: abc', 'kaydedildi: abc' ]
// çıktı: fn çağrı sayısı: 1

Aynı sürümde gelen util.throttle(fn, limit, interval) ise bir aralık içinde fn en fazla limit kez çalışsın diye çağrıları sınırlar. Varsayılan davranışta sınırı aşan çağrılar atılmaz, geliş sırasıyla kuyruğa alınır; overflow: 'drop' verirseniz kuyruğa alınmadan hemen reddedilir. concurrency aynı anda sonuçlanmamış kaç çağrıya izin verileceğini, strict ise kayan herhangi bir aralıkta sınırın aşılmamasını belirler. Dış servislere giden istekleri yavaşlatmak bu fonksiyonun tipik kullanımıdır.

v26.11.0 ile gelen util.isPartialDeepStrictEqual(a, b), ikinci değerde bulunan özellikleri birinci değerde arar ve yalnızca onları derin ve katı biçimde karşılaştırır. Büyük bir nesnenin belirli alanlarını kontrol etmek istediğinizde işe yarar; assert.partialDeepStrictEqual() ile aynı karşılaştırma kurallarını kullanır, fark olarak hata fırlatmak yerine boolean döndürür.

// kismi.mjs
import { isPartialDeepStrictEqual } from 'node:util';

const kullanici = { ad: 'Ayşe', rol: 'admin', ayarlar: { tema: 'koyu', dil: 'tr' } };
console.log(isPartialDeepStrictEqual(kullanici, { rol: 'admin' }));
console.log(isPartialDeepStrictEqual(kullanici, { ayarlar: { dil: 'tr' } }));
console.log(isPartialDeepStrictEqual(kullanici, { rol: 'editor' }));
// çıktı: true
// çıktı: true
// çıktı: false

Son olarak v26.10.0 ile gelen util.markPromiseAsHandled(promise), bir Promise'i işlenmiş olarak işaretler; böylece o Promise reddedildiğinde işlenmemiş ret olarak raporlanmaz. Bu, reddin bilerek göz ardı edildiği nadir durumlar içindir; hataları gizlemek için kullanmayın. İşlenmemiş retlerin Node.js'te nasıl ele alındığını uncaughtException ve unhandledRejection yazısında ayrıntılı anlattık. util modülünün geri kalanı için util.promisify ve util.inspect yazısına bakabilirsiniz.

Kriptografi: UUIDv7, Mac sınıfı ve CryptoKey uyarıları

v26.1.0 ile gelen crypto.randomUUIDv7(), RFC 9562'de tanımlanan sürüm 7 UUID üretir. Bu biçimde en anlamlı 48 bit milisaniye hassasiyetli bir Unix zaman damgasıdır, kalan alanlar kriptografik olarak güvenli rastgele bitlerdir. Bu sayede üretilen değerler aşağı yukarı zaman sırasına göre dizilir ve veritabanı anahtarı olarak kullanışlıdır. Belge önemli bir sınır da çiziyor: zaman damgası monoton olmayan bir saate dayandığı için değerlerin kesin olarak artan sırada olacağı garanti edilmez.

// uuid7.mjs
import { randomUUID, randomUUIDv7 } from 'node:crypto';

const v4 = randomUUID();
const v7 = randomUUIDv7();
console.log(v4.length, v4[14]);
console.log(v7.length, v7[14]);

// İlk 48 bit milisaniye cinsinden zaman damgası
const ms = parseInt(v7.replaceAll('-', '').slice(0, 12), 16);
console.log(Math.abs(Date.now() - ms) < 1000);
// çıktı: 36 4
// çıktı: 36 7
// çıktı: true

Örnekteki 15. karakter (indeks 14) UUID'nin sürüm hanesidir: randomUUID() için 4, randomUUIDv7() için 7 çıkar. Zaman damgasını geri çözmek mümkün olduğundan, UUIDv7 değerinin ne zaman üretildiği dışarıdan anlaşılabilir; kimlikte oluşturulma zamanının görünmesini istemediğiniz yerlerde v4 kullanmaya devam edin. Hash, HMAC ve randomUUID ayrıntıları crypto ile hash, HMAC ve randomUUID yazısında yer alıyor.

v26.9.0 ile crypto.createMac() ve Mac sınıfı geldi (kararlılık: 1.2 sürüm adayı). Bu API, OpenSSL sağlayıcılarının sunduğu HMAC, CMAC, GMAC, KMAC gibi MAC algoritmalarına tek bir arayüzden erişim sağlar; mevcut algoritmaları crypto.getMacs() listeler. Aynı sürümde createHash() ve createCipheriv() tarafında da OpenSSL sağlayıcılarından gelen ek algoritmalar kullanılabilir oldu.

v26.0.0 ile iki uyarı daha geldi. Birincisi, Web Crypto nesnesi olan CryptoKey değerini node:crypto fonksiyonlarına (örneğin createHmac, createCipheriv) vermek DEP0203 koduyla çalışma zamanı uyarısı üretir; createPrivateKey() için bu kullanım v26.7.0 itibarıyla artık desteklenmiyor. İkincisi, GCM şifre çözmede 128 bit dışındaki etiket uzunluklarını authTagLength belirtmeden kullanmak (DEP0182) artık End-of-Life durumunda. AES-GCM kullanımı için AES-256-GCM şifreleme yazısına bakın.

Buffer tarafındaki değişiklikler

v26.3.0 ile Buffer.poolSize varsayılanı 8192 bayttan 65536 bayta yükseltildi. Bu değer, küçük Buffer nesneleri için önceden ayrılan iç havuzun boyutudur ve isterseniz değiştirebilirsiniz. v26.11.0 ile gelen Buffer.stringLength(), bir bayt dizisi çözülseydi ortaya çıkacak dizenin UTF-16 kod birimi cinsinden uzunluğunu, çözmeden hesaplar; Buffer.byteLength() fonksiyonunun tersi gibi düşünebilirsiniz. Aynı sürümde gelen buffer.isLatin1() bir dizenin kayıpsız olarak latin1 kodlamasıyla yazılıp yazılamayacağını söyler.

// buffer26.mjs
import { Buffer, isLatin1 } from 'node:buffer';

console.log(Buffer.poolSize);

const buf = Buffer.from('ğüş', 'utf8');
console.log(buf.length, Buffer.stringLength(buf));

const satir = Buffer.from('a,b,c,d');
console.log(satir.indexOf(','), satir.indexOf(',', 4), satir.indexOf(',', 4, 5));

console.log(isLatin1('çöü'), isLatin1('ğış'));
// çıktı: 65536
// çıktı: 6 3
// çıktı: 1 5 -1
// çıktı: true false

Çıktıyı yorumlayalım: üç Türkçe harf UTF-8 ile altı bayt tutar, ama çözüldüğünde üç karakterlik bir dize olur. indexOf, includes ve lastIndexOf fonksiyonlarına v26.1.0 ile bir end parametresi eklendi; üçüncü çağrı aramayı 4. ve 5. indeks arasıyla sınırladığı için 5. indeksteki virgülü görmez ve -1 döner. isLatin1 tarafında ç, ö, ü U+00FF altında kaldığı için latin1 sayılır; ğ, ı, ş ise bu aralığın dışındadır. Buffer temelleri için Buffer kullanımı yazısına göz atın.

Dosya sistemi

node:fs modülündeki yenilikler daha çok seçenek düzeyinde. fs.glob, fs.globSync ve fsPromises.glob fonksiyonlarına v26.1.0 ile followSymlinks, v26.9.0 ile maxDepth seçeneği eklendi; cwd klasörünün derinliği 0 kabul edilir. readFile ailesine v26.4.0 ile buffer seçeneği geldi: dosya hazır verdiğiniz bir bellek alanına okunur, alan küçük kalırsa işlem hatayla sonuçlanır. fsPromises.stat ve fsPromises.lstat v26.8.0 ile signal kabul ediyor. fs.watch v26.1.0 ile throwIfNoEntry seçeneği aldı (varsayılan true), v26.10.0 ile de fs.openAsBlobSync() eklendi.

Bu seçeneklerin günlük kullanımını mkdir, readdir, rm ve fs.glob, readFile ile dosya okuma ve fs.watch ile dosya izleme yazılarında örnekledik.

HTTP ve ağ

v26.11.0 ile http.isValidHeaderName() ve http.isValidHeaderValue() geldi. İkisi de var olan doğrulama kurallarını kullanır ama hata fırlatmak yerine true veya false döndürür; geçersiz girdinin sık beklendiği yerlerde try/catch maliyetinden kurtarır. HTTP metotları da token kuralına uyduğu için isValidHeaderName ile metot adlarını da kontrol edebilirsiniz.

// baslik.mjs
import { isValidHeaderName, isValidHeaderValue } from 'node:http';

console.log(isValidHeaderName('X-Istek-Kimligi'));
console.log(isValidHeaderName('kötü başlık'));
console.log(isValidHeaderValue('text/html; charset=utf-8'));
console.log(isValidHeaderValue('satır\nsonu'));
// çıktı: true
// çıktı: false
// çıktı: true
// çıktı: false

Sunucu tarafında v26.1.0 ile message.signal eklendi: istek nesnesi tamamlanmadan yok edilirse ya da istemci bağlantıyı koparırsa bu AbortSignal tetiklenir. v26.7.0'dan beri mesaj normal biçimde tamamlandığında sinyal tetiklenmez. Bunu veritabanı sorgusu veya fetch gibi alt işlere geçirerek terk edilen isteklerin işini iptal edebilirsiniz; iptal mantığını AbortController ile iptal ve zaman aşımı yazısında anlattık. v26.2.0 ile gelen response.writeInformation() 100 ile 199 arasındaki bilgilendirme yanıtlarını (101 hariç) genel bir yolla göndermeye yarar. node:net tarafında ise v26.8.0 ile BlockList sınıfına addCIDR(), removeAddress() gibi metotlar ve özel ağ aralıklarını içeren BlockList.PRIVATE_RANGES eklendi.

Test çalıştırıcısı ve assert

v26.0.0 ile node:assert fonksiyonlarının message parametresi printf tarzı bir biçim dizesi ya da fonksiyon olabiliyor. Biçim dizesi kullandığınızda değerler yalnızca doğrulama başarısız olursa metne yerleştirilir; belge bunun performans açısından da yararlı olduğunu belirtiyor.

// assertfmt.mjs
import assert from 'node:assert/strict';

const beklenen = 3;
const gelen = 5;
try {
  assert.strictEqual(gelen, beklenen, 'sepet adedi %d olmalıydı, %d geldi', beklenen, gelen);
} catch (err) {
  console.log(err.code);
  console.log(err.message.split('\n')[0]);
}
// çıktı: ERR_ASSERTION
// çıktı: sepet adedi 3 olmalıydı, 5 geldi

node:test tarafında v26.12.0 ile test bağlamına sahte fonksiyonlar için doğrulamalar eklendi: t.assert.called(fn), t.assert.callCount(fn, n), t.assert.lastCalledWith(fn, ...args) ve t.assert.nthCalledWith(fn, n, ...args). v26.1.0 ile --test-randomize ve --test-random-seed bayraklarıyla test sırasını karıştırma, v26.2.0 ile de testlere etiket verme özelliği geldi; ikisi de 1.0 erken geliştirme aşamasında ve etiket filtresi --experimental-test-tag-filter bayrağını gerektiriyor. v26.7.0 ile gelen --test-coverage-include-all (deneysel) hiç yüklenmeyen dosyaları da kapsama raporuna sıfır kapsamla ekler. Test çalıştırıcısının temelleri node:test rehberi, sahte fonksiyonlar ve kapsama mock ve coverage yazısında.

Komut satırı: kararlı hâle gelen bayraklar

v26.12.0 ile --experimental-config-file bayrağının adı --config-file olarak değişti ve kararlı oldu; eski adlar takma ad olarak korunuyor. Bu bayrak, komut satırı seçeneklerini node.config.json dosyasından okumanızı sağlar. v26.7.0 ile --disable-warning bayrağı kararlı oldu; belirli bir uyarı kodunu veya türünü susturmak için kullanılır. İkisinin ayrıntılı kullanımı NODE_OPTIONS ve CLI bayrakları ile deprecation uyarıları yazılarında.

v26.9.0 ile node --run komutu, betik adı verilmeden çalıştırıldığında package.json içindeki betikleri listeler ve sıfırdan farklı bir çıkış koduyla biter. Denememizde çıkış kodu 9 oldu.

$ node --run
Available scripts are:
  test: node --test
  basla: node surum.mjs
$ echo $?
9

v26.11.0 ile gelen --process-timeout (kararlılık 1.1, etkin geliştirme) süreç belirtilen süreden uzun çalışırsa onu 124 koduyla sonlandırır ve çıkmadan önce olay döngüsünü açık tutan kaynakları stderr'e yazar. Takılı kalan betikleri ve CI işlerini teşhis ederken kullanışlıdır. Belgeye göre bu durumda 'beforeExit' ve 'exit' olayları tetiklenmez.

// asili.mjs
setInterval(() => {}, 1000); // olay döngüsünü sonsuza dek açık tutar
console.log('başladı');

// $ node --process-timeout=500ms asili.mjs
// çıktı: başladı
// çıktı (stderr): (node:PID) Process timed out after 500ms (--process-timeout). Exiting with code 124.
// çıktı (stderr): Main thread was not executing JavaScript.
// çıktı (stderr): Resources keeping the event loop alive:
// çıktı (stderr):     Timeout (next due in 506ms)

Çıktıdaki PID ve "next due in" süresi her çalıştırmada değişir. Bunların yanında v26.8.0 ile NODE_COMPILE_CACHE_READONLY=1 ortam değişkeni geldi: derleme önbelleği yalnızca okunur, dizine yazılmaz. v26.9.0 itibarıyla --use-largepages artık hiçbir şey yapmayan bir seçenek.

Kararlılık durumu değişen API'ler

Bazı API'ler v26 içinde yeni bir şey kazanmadı ama etiketleri değişti. Bu, üretimde kullanırken güvenebileceğiniz bir sinyaldir. Aşağıdaki tablo belgelerdeki changes kayıtlarından derlendi.

Kaldırılanlar ve kullanımdan kaldırmalar

Yükseltme yaparken en çok dikkat etmeniz gereken bölüm budur, çünkü burada çalışan kodu bozabilecek değişiklikler var. v26.0.0 ile TypeScript tarafında --experimental-transform-types bayrağı kaldırıldı; aynı sürümde module.stripTypeScriptTypes() fonksiyonunun transform ve sourceMap seçenekleri ile process.features.typescript içindeki transform değeri de kaldırıldı. Tip ayıklama (type stripping) ise kararlı olarak kalıyor; ayrıntılar TypeScript'i Node.js ile kullanma yazısında.

Tablodaki en etkili madde DEP0205. module.register() ile kaydedilen asenkron modül özelleştirme kancaları artık çalışma zamanı uyarısı veriyor; belge, ileride kaldırılacağını belirterek senkron ve aynı thread içinde çalışan module.registerHooks() fonksiyonuna geçmeyi öneriyor (bu API 1.2 sürüm adayı aşamasında). DEP0209 ise uzun ömürlü kaynakları kapatmak için AbortSignal kullanmak yerine using bildirimini öneriyor; iptal ve zaman aşımı için AbortSignal hâlâ doğru araç.

node:sqlite modülünde v26.11.0 ile sınıf adları sadeleşti: DatabaseSync artık Database, StatementSync ise Statement adını taşıyor. Eski adlar yalnızca belgede kullanımdan kaldırılmış takma adlar olarak duruyor, yani mevcut kodunuz uyarı vermeden çalışmaya devam eder. Modülün kendisi hâlâ 1.2 sürüm adayı aşamasında.

// sqliteadi.mjs
import { Database, DatabaseSync } from 'node:sqlite';

console.log(Database === DatabaseSync);
const db = new Database(':memory:');
console.log(db.prepare('SELECT 1 + 1 AS toplam').get());
db.close();
// çıktı: true
// çıktı: [Object: null prototype] { toplam: 2 }

Modülün tüm API'si için node:sqlite modülü yazısına bakın.

Henüz deneysel olanlar

v26 içinde birkaç yeni alt sistem de belgelere girdi, ancak hepsi deneysel. v26.9.0 ile gelen node:bench modülü (1.0 erken geliştirme) yalnızca --experimental-bench bayrağıyla kullanılabilir. v26.8.0 ile node:zlib içine ZIP arşivi okuma ve yazma API'si (ZipFile, ZipBuffer, ZipEntry) eklendi; belge bunu da 1.0 erken geliştirme olarak işaretliyor ve ilk kullanımda deneysel uyarı verildiğini söylüyor. v26.9.0 ile tarayıcıdaki Web Worker'a benzeyen global Worker sınıfı geldi, --experimental-web-worker bayrağı gerekiyor. v26.4.0 ile gelen package maps özelliği --experimental-package-map bayrağına bağlı. Sanal dosya sistemi, FFI ve QUIC de deneysel olduğundan bu serinin konusu değil.

Yükseltme öncesi kontrol listesi

• node --throw-deprecation ile test paketinizi çalıştırın; çalışma zamanı kullanımdan kaldırmaları hata olarak görünür.
• Kodunuzda module.register() geçiyorsa module.registerHooks() geçişini planlayın.
• --experimental-transform-types kullanan betik veya Dockerfile satırlarını temizleyin.
• node:crypto fonksiyonlarına CryptoKey geçiren kod varsa KeyObject kullanacak biçimde düzenleyin.
• --experimental-config-file kullanıyorsanız yeni adı --config-file ile değiştirin; eski ad şimdilik takma ad olarak çalışıyor.
• Yeni bir özelliği kullanmadan önce belgedeki added sürümünü projenizin en düşük Node.js sürümüyle karşılaştırın.

Sık yapılan hatalar

"v26" deyip alt sürümü atlamak. Bu yazıdaki özelliklerin çoğu v26.0.0 ile değil, sonraki alt sürümlerle geldi. util.debounce v26.10.0 öncesinde yoktur; package.json içindeki engines alanında ya da CI matrisinde en düşük alt sürümü doğru yazın.

Deneysel etiketi gözden kaçırmak. Yeni bir API'nin belgede yer alması kararlı olduğu anlamına gelmez. ZIP API'si ya da test etiketleri gibi 1.0 aşamasındaki özellikler bir sonraki alt sürümde imza değiştirebilir.

Belgede kullanımdan kaldırılmış adları sorun saymamak. DatabaseSync bugün uyarı vermiyor. Ancak listedeki birçok madde, örneğin DEP0063, önce Documentation-only, sonra Runtime, en sonunda End-of-Life aşamasından geçti. Yeni kodda Database adını kullanmak sonraki yükseltmeyi kolaylaştırır.

Uyarıları toptan susturmak. Yükseltme sonrası çıkan uyarıları --no-warnings ile kapatmak yerine --disable-warning=DEP0205 gibi kod bazlı susturma kullanın; böylece yeni uyarıları kaçırmazsınız.

Sık Sorulan Sorular

Node.js 26 LTS mi, ne zaman destek dışı kalacak?

Destek takvimi API belgelerinde yer almıyor, bu yüzden burada tarih vermiyoruz. Bir sürüm hattının LTS durumunu ve destek bitişini nodejs.org üzerindeki sürümler sayfasından kontrol edin.

Bu liste v26 ile gelen her şeyi kapsıyor mu?

Hayır. Yalnızca v26.13.0 API belgelerinde YAML kaydı v26 olan ve bu serinin kapsamına giren başlıkları özetledik. perf_hooks histogram metotları, HTTP/2 seçenekleri, Web Crypto'daki yeni algoritmalar gibi daha özel değişiklikler için ilgili modülün belgesine bakın.

Yükseltmeden önce hangi uyarılarla karşılaşacağımı nasıl görürüm?

Test paketinizi yeni sürümde --trace-deprecation ile çalıştırırsanız her kullanımdan kaldırma uyarısı yığın iziyle birlikte yazılır. --pending-deprecation ise yalnızca belgede bulunan bazı kullanımdan kaldırmaları da uyarıya dönüştürür.

Yeni util.debounce varken npm paketine ihtiyacım kalır mı?

Yerleşik fonksiyon Promise döndürür, AbortSignal ve leading seçeneklerini destekler. Projeniz v26.10.0 ve sonrasında çalışacaksa ek paket gerekmeyebilir; daha eski sürümleri de destekliyorsanız mevcut çözümünüzü koruyun.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Node.js öğrenme rehberi · Deprecation uyarıları · NODE_OPTIONS ve CLI bayrakları · Node.js kurulumu · Node.js nedir