JSONL (JSON Lines)

Kısaca: Her satırın kendi başına eksiksiz, geçerli bir JSON nesnesi olduğu bir dosya biçimi – bütünüyle tek bir nesne veya dizi olması gereken normal bir JSON dosyasının aksine.

Biraz daha ayrıntılı: Günlükler ve akışlar için kullanışlıdır, çünkü tüm dosyayı ayrıştırmadan satır satır okuyup yazabilirsiniz ve yeni girdiler basitçe eklenebilir.

Bizim bağlamımız: Claude Code, oturum dökümlerini ~/.claude/projects/<proje>/<oturum-kimliği>.jsonl altında JSONL olarak saklar (olay başına bir satır: kullanıcı mesajı, asistan cevabı, araç çağrısı, …). Şimdi yeniden kaldırılmış olan Stop hook’u bu dosyalara eriştirdi.

Ayrıntılı

Yeniden yazmak yerine eklemek

JSONL’nin tek bir büyük JSON dosyasına karşı avantajı, özellikle çok uzun veya büyüyen veri akışlarında belli olur: bir günlük yazıcısı, mevcut dosyanın tamamını okumak, ayrıştırmak, değiştirmek ve yeniden yazmak zorunda kalmadan her yeni satırı dosyanın sonuna basitçe ekleyebilir (fs.appendFile) — normal bir JSON dosyasında (bütünüyle geçerli bir dizi/nesne olması gereken) bu gerekirdi, örneğin bir dizinin sonuna yeni bir öğe eklemek için. Birkaç gigabaytlık bir günlük dosyasında bu fark yalnızca can sıkıcı değil, pratikte de önemlidir: her yeni girdi için eksiksiz bir yeniden yazma, dosya büyüdükçe giderek yavaşlardı; eklemek ise mevcut dosya boyutundan bağımsız olarak sürekli hızlı kalır.

Her şeyi yüklemeden satır satır işleme

Satır satır işlemek (her şeyi bir seferde belleğe yüklemek yerine) de daha basittir:

const readline = require("readline");
const stream = readline.createInterface({ input: fs.createReadStream("session.jsonl") });
for await (const line of stream) {
  const event = JSON.parse(line);
  // ... tüm dosyayı bellekte tutmadan satır satır işle
}

Bu, kullanılabilir bellekten büyük olabilecek dosyalar için özellikle önemlidir — birkaç gigabaytlık bir dosyanın tamamına JSON.parse() uygulamak ya çok uzun sürerdi ya da hemen bellek yetersizliği hatasıyla çökerdi; satır satır işleme ise dosyanın toplam boyutundan bağımsız olarak sürekli küçük bir bellek miktarı gerektirir.

Hata toleransı

Bu bağlamda klasik JSON dosyalarının bir dezavantajı: JSONL’de tek bir bozuk satır (örneğin kesintiye uğramış bir yazmadan, diyelim ki süreç yazmanın ortasında çöktüğü için) tüm dosyayı okunmaz kılmadan tek başına atlanabilir — klasik bir JSON dosyasında ise ortada bir yerde tek bir bozuk karakter, içeriğin %99’u aslında sağlam olsa bile tüm dosyanın ayrıştırılmasını başarısız kılar. Bu özellik, JSONL’yi yazmaların kesintiye uğrayabileceği kullanım durumları (örneğin bir sistem çökmesi veya sürecin ani sonlanması) için özellikle dayanıklı kılar.

Yaygın kullanım alanları

Oturum dökümlerinin yanı sıra JSONL, makine öğrenmesinde eğitim verileri için (her satır bir eğitim örneği), günlük toplama için (her satır bir günlük olayı, çoğunlukla zaman damgası ve günlük düzeyi gibi tek tip alanlarla) ve kayıtların tek tek ve birbirinden bağımsız işleneceği sistemler arası veri alışverişi için sıkça kullanılır — örneğin her satırın tek bir kaydı temsil ettiği veritabanı dışa aktarımlarını akıtırken.

Ayrıca bak: Claude Code Hooks, JSON