Node.js ile Zip Dosyalarıyla Çalışma: Kapsamlı Bir Rehber

Node.js ile Zip Dosyalarıyla Çalışma: Kapsamlı Bir Rehber

Node.js, modern web uygulamaları, API’ler ve arka uç servisleri geliştirmek için güçlü ve popüler bir çalışma zamanı ortamıdır. Dosya işlemleri, bu tür uygulamaların önemli bir parçasıdır ve çoğu zaman birden fazla dosyanın veya bir dizinin tek bir sıkıştırılmış arşivde paketlenmesi veya arşivlenmiş bir dosyanın içeriğinin çıkarılması gerekebilir. İşte bu noktada Zip dosyaları devreye girer. Zip, dosyaları ve klasörleri sıkıştırmak ve arşivlemek için yaygın olarak kullanılan bir formattır. Node.js ortamında zip dosyalarıyla çalışmak, veri transferini optimize etmek, depolama alanından tasarruf etmek ve dosya yönetimini kolaylaştırmak için hayati öneme sahiptir.

Bu makalede, Node.js kullanarak zip dosyalarını nasıl oluşturacağınızı, mevcut zip dosyalarının içeriğini nasıl okuyacağınızı ve nasıl çıkaracağınızı detaylı bir şekilde inceleyeceğiz. Çeşitli senaryolar için en uygun kütüphaneleri tanıtacak, adım adım kod örnekleri sunacak ve performans, güvenlik ve hata yönetimi gibi önemli konulara değineceğiz. Bu rehberin sonunda, Node.js uygulamalarınızda zip işlemlerini güvenle ve verimli bir şekilde uygulayabilecek bilgiye sahip olacaksınız.

Node.js’te Zip İşlemleri İçin Temel Yaklaşımlar

Node.js’te zip dosyalarıyla çalışmak için iki ana yaklaşım bulunmaktadır: yerel Node.js modüllerini kullanmak veya üçüncü taraf kütüphanelerden yararlanmak.

Yerel Node.js Modülleri ve Sınırlılıkları

Node.js’in çekirdek modülleri, temel dosya sistemi (fs) ve akış (stream) işlemleri için güçlü yetenekler sunar. Ancak, doğrudan zip formatını işlemek için yerleşik bir modülü yoktur. Zip formatı, sıkıştırma algoritmaları (Deflate, LZMA vb.) ve dosya yapısı (merkezi dizin, yerel dosya başlıkları) gibi karmaşık detayları içerir. Bu nedenle, sıfırdan bir zip işleyici yazmak oldukça zaman alıcı ve hataya açık bir süreç olacaktır.

Yerel modüllerle doğrudan zip formatını işlemek yerine, genellikle üçüncü taraf kütüphaneleri kullanmak çok daha pratik ve güvenilir bir çözümdür. Bu kütüphaneler, zip formatının tüm karmaşıklığını soyutlayarak geliştiricilere kullanımı kolay API’ler sunar.

Üçüncü Taraf Kütüphaneler

Node.js ekosistemi, zip işlemleri için birçok güçlü ve bakımlı üçüncü taraf kütüphane sunar. Bu kütüphaneler, farklı kullanım senaryolarına ve performans gereksinimlerine göre optimize edilmiştir. En popüler ve yaygın olarak kullanılan kütüphaneler şunlardır:

* archiver: Özellikle zip dosyaları oluşturma ve sıkıştırma işlemleri için tasarlanmış, akış tabanlı ve oldukça esnek bir kütüphanedir. Büyük dosyalar ve klasörlerle çalışırken bellek verimliliği sunar.
* yauzl (Yet Another Unzip Library): Zip dosyalarını açma ve içeriğini okuma konusunda uzmanlaşmış, akış tabanlı ve performans odaklı bir kütüphanedir. Özellikle büyük zip dosyalarının içeriğini bellek dostu bir şekilde işlemek için idealdir.
* adm-zip: Hem zip oluşturma hem de açma işlemlerini destekleyen, daha basit ve kullanımı kolay bir API sunan bir kütüphanedir. Küçük ve orta ölçekli zip işlemleri için hızlı bir çözüm sunar, ancak çok büyük dosyalarla çalışırken performans sorunları yaşayabilir.
* jszip: Hem tarayıcı hem de Node.js ortamlarında çalışabilen, popüler bir JavaScript zip kütüphanesidir. Özellikle tarayıcı tabanlı zip işlemleri için tercih edilse de, Node.js’te de kullanılabilir. Bellek tabanlı çalışır, bu da çok büyük dosyalar için dikkatli kullanım gerektirir.

Bu makalede, archiver ile sıkıştırma, yauzl ile açma ve adm-zip ile basit hem sıkıştırma hem açma işlemlerine odaklanacağız. Bu üç kütüphane, Node.js’teki çoğu zip ihtiyacını karşılayacaktır.

Zip Dosyası Oluşturma ve Sıkıştırma (archiver ile)

archiver, Node.js’te zip dosyaları oluşturmak için en esnek ve güçlü kütüphanelerden biridir. Akış tabanlı yapısı sayesinde, büyük dosyaları bile bellek tüketimini minimumda tutarak işleyebilir.

archiver Kurulumu

Öncelikle projenize archiver kütüphanesini kurmanız gerekir:

npm install archiver

Temel Sıkıştırma Adımları

archiver ile bir zip dosyası oluşturmak için genel adımlar şunlardır:

1. Çıkış Akışı Oluşturma: Sıkıştırılmış verinin yazılacağı bir dosya akışı (fs.createWriteStream) veya başka bir akış (HTTP yanıtı gibi) oluşturulur.
2. archiver Örneği Oluşturma: archiver modülü çağrılarak bir arşivleyici örneği oluşturulur ve sıkıştırma formatı (örneğin, ‘zip’) belirtilir.
3. Akışları Birleştirme: Arşivleyici akışı, çıkış akışına yönlendirilir (archive.pipe(output)).
4. Dosya/Klasör Ekleme: archive.file(), archive.directory() veya archive.append() gibi yöntemlerle sıkıştırılacak dosyalar ve klasörler arşive eklenir.
5. Olay Dinleyicileri: İşlemin durumunu izlemek ve hataları yakalamak için end, warning, error gibi olay dinleyicileri eklenir.
6. Sıkıştırma İşlemini Başlatma: archive.finalize() çağrısı ile sıkıştırma işlemi başlatılır.

Örnek Kod: Tek Dosya Sıkıştırma

Aşağıdaki örnek, mevcut bir example.txt dosyasını archive.zip adında yeni bir zip dosyasına sıkıştırır.

const fs = require('fs');
const archiver = require('archiver');
const path = require('path');

async function compressSingleFile(sourceFilePath, outputZipPath) {
    const output = fs.createWriteStream(outputZipPath);
    const archive = archiver('zip', {
        zlib: { level: 9 } // Sıkıştırma seviyesi (0-9 arası, 9 en yüksek)
    });

    // Çıkış akışı kapandığında veya bittiğinde
    output.on('close', () => {
        console.log(Zip dosyası başarıyla oluşturuldu: ${archive.pointer()} toplam bayt);
        console.log('Archiver işlemi tamamlandı.');
    });

    // Arşivleyici akışında bir uyarı veya hata oluştuğunda
    archive.on('warning', (err) => {
        if (err.code === 'ENOENT') {
            console.warn('Arşivleyici uyarısı:', err.message);
        } else {
            throw err;
        }
    });

    archive.on('error', (err) => {
        console.error('Arşivleyici hatası:', err);
        throw err;
    });

    // Arşivleyici akışını çıkış akışına yönlendir
    archive.pipe(output);

    // Sıkıştırılacak dosyayı ekle
    // 'example.txt' dosyasını 'example-in-zip.txt' adıyla zipe ekler
    archive.file(sourceFilePath, { name: path.basename(sourceFilePath) });

    // Sıkıştırma işlemini başlat
    await archive.finalize();
}

// Kullanım örneği:
// Önce örnek bir dosya oluşturalım
fs.writeFileSync('example.txt', 'Bu bir örnek metin dosyasıdır. Zip içine sıkıştırılacak.');

compressSingleFile('example.txt', 'single_file_archive.zip')
    .then(() => console.log('Tek dosya sıkıştırma işlemi tamamlandı.'))
    .catch((err) => console.error('Tek dosya sıkıştırma hatası:', err));

Örnek Kod: Klasör Sıkıştırma

Bir klasörün tüm içeriğini (alt klasörler dahil) sıkıştırmak için archive.directory() metodunu kullanırız.

const fs = require('fs');
const archiver = require('archiver');
const path = require('path');

async function compressFolder(sourceFolderPath, outputZipPath) {
    const output = fs.createWriteStream(outputZipPath);
    const archive = archiver('zip', {
        zlib: { level: 9 }
    });

    output.on('close', () => {
        console.log(Zip dosyası başarıyla oluşturuldu: ${archive.pointer()} toplam bayt);
        console.log('Archiver işlemi tamamlandı.');
    });

    archive.on('warning', (err) => {
        if (err.code === 'ENOENT') {
            console.warn('Arşivleyici uyarısı:', err.message);
        } else {
            throw err;
        }
    });

    archive.on('error', (err) => {
        console.error('Arşivleyici hatası:', err);
        throw err;
    });

    archive.pipe(output);

    // Sıkıştırılacak klasörü ekle
    // 'my_folder' klasörünü 'my_folder' adıyla zipe ekler
    archive.directory(sourceFolderPath, false); // false: klasör adını zipin köküne eklemez
                                            // true: klasör adını zipin köküne ekler (örn: my_folder/file.txt)

    // Eğer klasörün içeriğini zipin köküne değil de belirli bir alt klasöre eklemek isterseniz:
    // archive.directory(sourceFolderPath, 'inside_zip_folder');

    await archive.finalize();
}

// Kullanım örneği:
// Önce örnek bir klasör ve dosyalar oluşturalım
const folderToCompress = 'my_folder';
if (!fs.existsSync(folderToCompress)) {
    fs.mkdirSync(folderToCompress);
    fs.writeFileSync(path.join(folderToCompress, 'file1.txt'), 'Bu ilk dosya.');
    fs.writeFileSync(path.join(folderToCompress, 'file2.txt'), 'Bu ikinci dosya.');
    const subFolder = path.join(folderToCompress, 'sub_folder');
    fs.mkdirSync(subFolder);
    fs.writeFileSync(path.join(subFolder, 'subfile.txt'), 'Bu alt klasördeki dosya.');
}

compressFolder(folderToCompress, 'folder_archive.zip')
    .then(() => console.log('Klasör sıkıştırma işlemi tamamlandı.'))
    .catch((err) => console.error('Klasör sıkıştırma hatası:', err));

archive.directory(sourceFolderPath, false) kullanımı, my_folder içindeki tüm dosyaları ve alt klasörleri zip dosyasının köküne yerleştirir. Eğer true olsaydı, zip dosyasının içinde my_folder adında bir klasör oluşacak ve içerik onun altında olacaktı.

Örnek Kod: Birden Fazla Dosya ve Klasörü Sıkıştırma

Farklı kaynaklardan gelen dosyaları ve klasörleri tek bir zip dosyasında birleştirebilirsiniz.

const fs = require('fs');
const archiver = require('archiver');
const path = require('path');

async function compressMultiple(outputZipPath) {
    const output = fs.createWriteStream(outputZipPath);
    const archive = archiver('zip', {
        zlib: { level: 9 }
    });

    output.on('close', () => {
        console.log(Zip dosyası başarıyla oluşturuldu: ${archive.pointer()} toplam bayt);
        console.log('Archiver işlemi tamamlandı.');
    });

    archive.on('warning', (err) => {
        if (err.code === 'ENOENT') {
            console.warn('Arşivleyici uyarısı:', err.message);
        } else {
            throw err;
        }
    });

    archive.on('error', (err) => {
        console.error('Arşivleyici hatası:', err);
        throw err;
    });

    archive.pipe(output);

    // İlk dosya: 'example.txt' dosyasını 'root_file.txt' adıyla ekle
    archive.file('example.txt', { name: 'root_file.txt' });

    // İkinci dosya: 'another.txt' adında yeni bir dosya oluşturalım
    fs.writeFileSync('another.txt', 'Bu başka bir örnek dosya.');
    archive.file('another.txt', { name: 'subfolder/another_file.txt' }); // Alt klasöre ekle

    // Klasör ekle: 'my_folder' klasörünü 'my_data' adıyla zipe ekle
    archive.directory('my_folder', 'my_data');

    await archive.finalize();
}

// Kullanım örneği:
compressMultiple('multiple_items_archive.zip')
    .then(() => console.log('Çoklu öğe sıkıştırma işlemi tamamlandı.'))
    .catch((err) => console.error('Çoklu öğe sıkıştırma hatası:', err));

Bu örnekte, example.txt dosyası zip’in köküne root_file.txt olarak eklenirken, another.txt dosyası subfolder/another_file.txt olarak bir alt klasöre ekleniyor ve my_folder klasörü de my_data adıyla zip’e dahil ediliyor. Bu, archiver‘ın esnekliğini göstermektedir.

Gelişmiş Seçenekler

archiver‘ın archiver(format, options) metodundaki options nesnesi ile sıkıştırma davranışını özelleştirebilirsiniz:

* zlib.level: Deflate sıkıştırma seviyesi (0-9 arası). 0 sıkıştırma yok, 9 en yüksek sıkıştırma (ancak daha yavaş). Varsayılan 6’dır.
* comment: Zip dosyasına eklenecek genel bir yorum dizesi.
* forceUTC: Zip girişleri için tarihleri UTC olarak kaydetmeyi zorlar.

archiver kütüphanesi doğrudan parola korumalı zip dosyaları oluşturma özelliğini desteklemez. Bu tür bir işlevsellik için farklı bir kütüphane veya harici bir araç kullanmanız gerekebilir.

Zip Dosyalarını Açma ve İçeriğini Okuma (yauzl ile)

yauzl, Node.js’te zip dosyalarının içeriğini açmak ve okumak için tasarlanmış, akış tabanlı ve oldukça verimli bir kütüphanedir. Özellikle büyük zip dosyalarıyla çalışırken bellek verimliliği ve performans açısından tercih edilir.

yauzl Kurulumu

yauzl kütüphanesini projenize kurun:

npm install yauzl

Temel Açma Adımları

yauzl ile bir zip dosyasını açmak için genel adımlar şunlardır:

1. Zip Dosyasını Açma: yauzl.open() metodu ile zip dosyası açılır. Bu metod, bir ZipFile nesnesi döndürür.
2. Girişleri Listeleme: ZipFile nesnesi, zip dosyasındaki her bir girişi (dosya veya klasör) temsil eden entry olayını yayar. Bu olay dinlenerek zip içeriği üzerinde döngü yapılabilir.
3. Dosya İçeriğini Okuma: Bir dosya girişi için zipfile.openReadStream() metodu çağrılarak dosyanın içeriğini okuyacak bir akış elde edilir.
4. Çıkarma İşlemi: Okunan akış, bir hedef dosyaya (fs.createWriteStream) yönlendirilerek dosya çıkarılır.
5. Hata Yönetimi: İşlem sırasında oluşabilecek hataları yakalamak için uygun hata dinleyicileri eklenir.

Örnek Kod: Zip Dosyasının İçeriğini Listeleme

Bu örnek, bir zip dosyasının içindeki tüm dosyaları ve klasörleri listeler.

const yauzl = require('yauzl');
const path = require('path');

async function listZipContents(zipFilePath) {
    return new Promise((resolve, reject) => {
        yauzl.open(zipFilePath, { lazyEntries: true }, (err, zipfile) => {
            if (err) {
                return reject(err);
            }

            console.log(Zip dosyasının içeriği: ${zipFilePath});

            zipfile.on('entry', (entry) => {
                // Klasör girişleri genellikle '/' ile biter
                if (/\/$/.test(entry.fileName)) {
                    console.log(  Klasör: ${entry.fileName});
                } else {
                    console.log(  Dosya: ${entry.fileName} (${entry.uncompressedSize} bayt));
                }
                zipfile.readEntry(); // Bir sonraki girişi oku
            });

            zipfile.on('end', () => {
                console.log('Zip içeriği listeleme tamamlandı.');
                resolve();
            });

            zipfile.on('error', (err) => {
                reject(err);
            });

            // İlk girişi okumayı başlat
            zipfile.readEntry();
        });
    });
}

// Kullanım örneği:
// Yukarıdaki 'multiple_items_archive.zip' dosyasını varsayarak
listZipContents('multiple_items_archive.zip')
    .then(() => console.log('Zip içeriği listeleme başarılı.'))
    .catch((err) => console.error('Zip içeriği listeleme hatası:', err));

lazyEntries: true seçeneği, yauzl‘ın tüm girişleri belleğe yüklemeden teker teker okumasını sağlar, bu da büyük zip dosyaları için bellek verimliliği açısından önemlidir. Her entry olayından sonra zipfile.readEntry() çağrısı, bir sonraki girişi okumak için gereklidir.

Örnek Kod: Zip Dosyasını Belirli Bir Klasöre Açma

Bu örnek, bir zip dosyasının tüm içeriğini belirtilen bir hedef klasöre çıkarır.

const fs = require('fs');
const yauzl = require('yauzl');
const path = require('path');
const { promisify } = require('util');

const mkdir = promisify(fs.mkdir);
const createWriteStream = fs.createWriteStream;

async function extractZip(zipFilePath, destinationPath) {
    await mkdir(destinationPath, { recursive: true }); // Hedef klasörü oluştur

    return new Promise((resolve, reject) => {
        yauzl.open(zipFilePath, { lazyEntries: true }, (err, zipfile) => {
            if (err) {
                return reject(err);
            }

            zipfile.on('entry', (entry) => {
                const entryPath = path.join(destinationPath, entry.fileName);

                // Klasör girişlerini oluştur
                if (/\/$/.test(entry.fileName)) {
                    mkdir(entryPath, { recursive: true })
                        .then(() => zipfile.readEntry())
                        .catch(reject);
                } else {
                    // Dosya girişlerini çıkar
                    zipfile.openReadStream(entry, (err, readStream) => {
                        if (err) {
                            return reject(err);
                        }

                        // Dosyanın üst klasörünü oluştur (eğer yoksa)
                        mkdir(path.dirname(entryPath), { recursive: true })
                            .then(() => {
                                const writeStream = createWriteStream(entryPath);
                                writeStream.on('finish', () => zipfile.readEntry());
                                writeStream.on('error', reject);
                                readStream.pipe(writeStream);
                            })
                            .catch(reject);
                    });
                }
            });

            zipfile.on('end', () => {
                console.log(Zip dosyası başarıyla çıkarıldı: ${destinationPath});
                resolve();
            });

            zipfile.on('error', (err) => {
                reject(err);
            });

            zipfile.readEntry();
        });
    });
}

// Kullanım örneği:
const outputExtractionFolder = 'extracted_content';
extractZip('multiple_items_archive.zip', outputExtractionFolder)
    .then(() => console.log('Zip çıkarma işlemi tamamlandı.'))
    .catch((err) => console.error('Zip çıkarma hatası:', err));

Bu örnek, çıkarılacak her dosya veya klasör için hedef yolları dinamik olarak oluşturur ve klasörlerin mevcut olduğundan emin olmak için fs.mkdir({ recursive: true }) kullanır. yauzl da archiver gibi doğrudan parola korumalı zip dosyalarını açma özelliği sunmaz. Bu tür dosyalar için özel bir kütüphane veya araç kullanmanız gerekebilir.

Basit Kullanım İçin: adm-zip

adm-zip, hem zip dosyaları oluşturma hem de açma işlemleri için daha basit ve senkronize bir API sunar. Küçük ve orta ölçekli zip işlemleri için hızlı bir çözüm olabilir, ancak akış tabanlı olmadığı için çok büyük dosyalarla çalışırken bellek sorunlarına yol açabilir.

adm-zip Kurulumu

adm-zip kütüphanesini projenize kurun:

npm install adm-zip

Sıkıştırma (adm-zip ile)

adm-zip ile bir zip dosyası oluşturmak oldukça basittir:

const AdmZip = require('adm-zip');
const fs = require('fs');
const path = require('path');

function createZipWithAdmZip(sourceFilesAndFolders, outputZipPath) {
    const zip = new AdmZip();

    sourceFilesAndFolders.forEach(item => {
        const stats = fs.statSync(item.path);
        if (stats.isFile()) {
            zip.addLocalFile(item.path, item.zipPath); // zipPath: zip içindeki yolu
        } else if (stats.isDirectory()) {
            zip.addLocalFolder(item.path, item.zipPath);
        }
    });

    zip.writeZip(outputZipPath);
    console.log(Adm-zip ile ${outputZipPath} dosyası oluşturuldu.);
}

// Kullanım örneği:
// Önce örnek dosyaları/klasörleri oluşturalım (önceki örneklerden kalanlar)
// fs.writeFileSync('example.txt', 'Bu bir örnek metin dosyasıdır. Zip içine sıkıştırılacak.');
// const folderToCompress = 'my_folder';
// if (!fs.existsSync(folderToCompress)) {
//     fs.mkdirSync(folderToCompress);
//     fs.writeFileSync(path.join(folderToCompress, 'file1.txt'), 'Bu ilk dosya.');
// }

const itemsToZip = [
    { path: 'example.txt', zipPath: '' }, // Zip'in köküne ekle
    { path: 'my_folder', zipPath: 'my_data_adm' } // my_folder'ı my_data_adm adıyla ekle
];

createZipWithAdmZip(itemsToZip, 'adm_zip_archive.zip');

addLocalFile(filePath, zipEntryPath) ve addLocalFolder(folderPath, zipEntryPath) metodları, yerel dosya ve klasörleri zip dosyasına eklemek için kullanılır. zipEntryPath parametresi, dosya veya klasörün zip içindeki yolunu belirtir.

Açma (adm-zip ile)

adm-zip ile bir zip dosyasını açmak da aynı derecede kolaydır:

const AdmZip = require('adm-zip');

function extractZipWithAdmZip(zipFilePath, destinationPath) {
    const zip = new AdmZip(zipFilePath);
    zip.extractAllTo(destinationPath, true); // true: üzerine yaz (overwrite)

    console.log(Adm-zip ile ${zipFilePath} dosyası ${destinationPath} konumuna çıkarıldı.);
}

// Kullanım örneği:
extractZipWithAdmZip('adm_zip_archive.zip', 'extracted_content_adm');

// Zip dosyasının içeriğini listeleme
function listZipContentsAdmZip(zipFilePath) {
    const zip = new AdmZip(zipFilePath);
    const zipEntries = zip.getEntries(); // ZipEntry nesneleri dizisi

    console.log(Adm-zip ile ${zipFilePath} dosyasının içeriği:);
    zipEntries.forEach(zipEntry => {
        console.log(  - ${zipEntry.entryName} (boyut: ${zipEntry.header.size}));
    });
}

listZipContentsAdmZip('adm_zip_archive.zip');

extractAllTo(destinationPath, overwrite) metodu, zip dosyasının tüm içeriğini belirtilen klasöre çıkarır. İkinci parametre true ise, hedef yolda zaten mevcut olan dosyaların üzerine yazılır. getEntries() metodu ise zip dosyasındaki tüm girişleri içeren bir dizi döndürür, bu da içeriği listelemek için kullanılabilir.

adm-zip‘in Avantajları ve Dezavantajları

Avantajları:

* Basit API: Kullanımı son derece kolaydır, hızlı prototipleme ve küçük işler için idealdir.
* Hem sıkıştırma hem açma: Tek bir kütüphane ile her iki işlemi de yapabilirsiniz.
* Senkronize işlemler: Kod akışını takip etmek daha kolaydır (ancak bu aynı zamanda bir dezavantaj olabilir).

Dezavantajları:

* Bellek tüketimi: Akış tabanlı olmadığı için, tüm zip dosyasını veya sıkıştırılacak/açılacak tüm içeriği belleğe yükleyebilir. Bu, çok büyük dosyalarla çalışırken bellek yetersizliği sorunlarına yol açabilir.
* Performans: Büyük dosyalar için archiver veya yauzl gibi akış tabanlı kütüphanelere göre daha yavaş olabilir.
* Esneklik eksikliği: archiver veya yauzl‘ın sunduğu detaylı kontrol ve gelişmiş seçeneklerden yoksundur.

Özetle, küçük ve orta ölçekli zip işlemleri için adm-zip pratik bir seçimken, büyük dosyalar veya performans kritik uygulamalar için archiver ve yauzl ikilisi tercih edilmelidir.

Gelişmiş Senaryolar ve En İyi Uygulamalar

Zip dosyalarıyla çalışırken sadece temel sıkıştırma ve açma işlemlerini bilmek yeterli değildir. Daha sağlam, performanslı ve güvenli uygulamalar geliştirmek için bazı gelişmiş senaryoları ve en iyi uygulamaları göz önünde bulundurmak önemlidir.

Büyük Dosyalarla Çalışma ve Bellek Yönetimi

Node.js, akış (stream) tabanlı işlemleri desteklediği için büyük dosyalarla çalışırken bellek verimliliğini korumak mümkündür. archiver ve yauzl gibi kütüphaneler bu akış paradigmasını benimser:

* Sıkıştırma: archiver, dosyaları okurken ve sıkıştırırken bellek yerine doğrudan çıkış akışına yazar. Bu, gigabaytlarca büyüklükteki dosyaları bile rahatlıkla sıkıştırabilmenizi sağlar. archive.file(readStream, options) şeklinde bir okuma akışını doğrudan arşive ekleyebilirsiniz.
* Açma: yauzl, zip dosyasının içeriğini okurken de akışları kullanır. zipfile.openReadStream(entry) ile elde edilen akışı doğrudan bir yazma akışına yönlendirerek, dosya içeriğini belleğe yüklemeden diske yazabilirsiniz.

Bu yaklaşım, uygulamanızın bellek ayak izini düşük tutar ve performans sorunlarını önler. adm-zip gibi bellek tabanlı kütüphaneler, büyük dosyalarla çalışırken JavaScript heap out of memory hatalarına neden olabilir.

Hata Yönetimi ve İstisna Yakalama

Dosya işlemleri, izin sorunları, dosya bulunamadı hataları, disk doluluğu gibi birçok hataya açıktır. Sağlam bir uygulama için kapsamlı hata yönetimi şarttır.

* Asenkron Hatalar: archiver ve yauzl gibi akış tabanlı kütüphaneler, hataları olaylar aracılığıyla ('error') veya Promise rejection’ları (async/await ile) bildirir. Bu olayları dinlemeli ve uygun şekilde ele almalısınız.
* Dosya Sistemi Hataları: fs modülünün işlemleri (dosya okuma/yazma, klasör oluşturma) de Promise tabanlı veya callback tabanlı hata parametreleri döndürür. Bu hataları try...catch blokları veya .catch() zincirleri ile yakalamalısınız.
* Kaynak Temizliği: Bir hata durumunda, açık dosya tanıtıcılarını veya akışları kapatmayı unutmayın. output.on('close') veya finally blokları bu tür temizlik işlemleri için kullanılabilir.

// Hata yönetimi örneği (archiver için)
archive.on('error', (err) => {
    console.error('Arşivleme sırasında kritik bir hata oluştu:', err);
    // Hatanın türüne göre farklı işlemler yapabilirsiniz
    // Örneğin, kısmen oluşturulmuş zip dosyasını silmek
    fs.unlink(outputZipPath, () => console.log('Kısmi zip dosyası silindi.'));
    process.exit(1); // Uygulamayı sonlandır
});

Güvenlik (Kötü Niyetli Zip Dosyaları, Path Traversal)

Kullanıcı tarafından yüklenen veya güvenilmeyen kaynaklardan gelen zip dosyalarını işlerken güvenlik çok önemlidir. Kötü niyetli zip dosyaları “path traversal” (dizin atlama) saldırılarına yol açabilir. Bu saldırılarda, zip dosyasının içindeki bir dosya ../../../../etc/passwd gibi bir yola sahip olabilir ve bu dosya çıkarıldığında sistem dosyalarının üzerine yazılmasına neden olabilir.

yauzl gibi kütüphaneler, bu tür saldırılara karşı varsayılan olarak bir miktar koruma sağlar, ancak yine de dikkatli olmalısınız:

* Giriş Yollarını Doğrulama: Zip dosyasından çıkarılacak her bir girişin (entry.fileName) hedef klasörün dışına çıkmadığından emin olun.
* path.resolve() ve path.join(): Çıkarılacak dosyanın tam yolunu oluştururken path.join() kullanın ve ardından path.resolve() ile yolun normalize edilmiş halini kontrol edin. Hedef klasörün dışına çıkan yolları reddedin.

// Path Traversal kontrolü örneği
const destinationPath = 'extracted_content';
const entryPath = path.join(destinationPath, entry.fileName);
const resolvedEntryPath = path.resolve(entryPath);

// Hedef klasörün dışına çıkmadığından emin ol
if (!resolvedEntryPath.startsWith(path.resolve(destinationPath))) {
    console.warn(Güvenlik uyarısı: Dizin atlama girişimi algılandı: ${entry.fileName});
    // Bu girişi atla veya hata fırlat
    zipfile.readEntry();
    return;
}

Asenkron İşlemlerin Yönetimi (async/await)

Node.js’te dosya işlemleri doğası gereği asenkrondur. Modern JavaScript’te async/await sözdizimi, asenkron kodları daha okunabilir ve yönetilebilir hale getirir. Yukarıdaki örneklerde de görüldüğü gibi, kütüphanelerin Promise tabanlı API’lerini kullanmak veya callback tabanlı API’leri util.promisify ile Promise’e dönüştürmek, async/await ile kolayca entegre edilebilir. Bu, kodunuzun daha temiz ve hata yönetiminin daha kolay olmasını sağlar.

Geçici Dosyalarla Çalışma (tmp kütüphanesi)

Bazen zip işlemleri sırasında geçici dosyalara veya klasörlere ihtiyaç duyulur (örneğin, bir zip dosyasını indirdikten sonra açmak, işlemek ve sonra silmek). tmp gibi kütüphaneler, güvenli bir şekilde geçici dosya ve klasörler oluşturmanıza ve işiniz bittiğinde bunları otomatik olarak temizlemenize olanak tanır.

npm install tmp

const tmp = require('tmp');
const fs = require('fs');
const path = require('path');

async function processZipInTempDir(zipBuffer) {
    const tmpdir = tmp.dirSync({ unsafeCleanup: true }); // Geçici klasör oluştur
    const tempZipPath = path.join(tmpdir.name, 'temp.zip');

    try {
        fs.writeFileSync(tempZipPath, zipBuffer); // Zip içeriğini geçici dosyaya yaz

        // Burada zip dosyasını açma, işleme vb. işlemler yapabilirsiniz
        console.log(Zip dosyası geçici klasöre yazıldı: ${tempZipPath});
        await extractZip(tempZipPath, path.join(tmpdir.name, 'extracted'));
        console.log(İçerik geçici klasöre çıkarıldı: ${path.join(tmpdir.name, 'extracted')});

    } catch (error) {
        console.error('Geçici dizin işlem hatası:', error);
    } finally {
        tmpdir.removeCallback(); // Geçici klasörü ve içeriğini temizle
        console.log('Geçici klasör temizlendi.');
    }
}

// Kullanım örneği (varsayımsal bir zip buffer'ı ile)
// const someZipBuffer = fs.readFileSync('some_downloaded_zip.zip');
// processZipInTempDir(someZipBuffer);

Parola Korumalı Zip Dosyaları

Yukarıda bahsedilen kütüphanelerden archiver ve yauzl doğrudan parola korumalı zip dosyaları oluşturma veya açma özelliğini desteklemez. adm-zip ise bazı durumlarda AES şifrelemesini desteklemese de, standart ZipCrypto şifrelemesini açma konusunda sınırlı desteğe sahip olabilir. Ancak, bu tür kütüphanelerin parola desteği genellikle sınırlıdır ve güvenilir değildir.

Parola korumalı zip dosyalarıyla çalışmanız gerekiyorsa, genellikle aşağıdaki yaklaşımlardan birini tercih etmeniz gerekir:

* Harici Araçlar/Komut Satırı: 7-zip veya unzip gibi komut satırı araçlarını Node.js’ten child_process modülü ile çağırmak. Bu, daha güçlü şifreleme algoritmalarını destekler ancak platform bağımlılığı yaratır.
* Özel Kütüphaneler: Daha gelişmiş şifreleme desteği sunan özel Node.js kütüphaneleri aramak (ancak bunlar genellikle daha az popüler veya bakımlı olabilir).

Genel olarak, hassas veriler için zip şifrelemesi yerine daha modern ve güvenli şifreleme yöntemleri (örneğin, dosyanın kendisini şifreleyip sonra zip’lemek) tercih edilmelidir.

Sıkça Sorulan Sorular (SSS)

Hangi kütüphaneyi ne zaman kullanmalıyım?

* archiver (sıkıştırma) ve yauzl (açma): Büyük dosyalarla çalışırken, yüksek performans ve düşük bellek tüketimi gerektiren durumlarda bu ikiliyi tercih edin. Akış tabanlı oldukları için en verimli çözümü sunarlar.
* adm-zip: Küçük ve orta ölçekli zip işlemleri için, basit ve hızlı bir API arıyorsanız kullanabilirsiniz. Hem sıkıştırma hem de açma yapar, ancak büyük dosyalar için uygun değildir.
* jszip: Node.js’ten ziyade tarayıcı tabanlı uygulamalar için daha popülerdir, ancak Node.js’te de bellek tabanlı zip işlemleri için kullanılabilir.

Zip dosyasını bellekte sıkıştırma/açma mümkün mü?

Evet, mümkündür.

* Sıkıştırma: archiver ile çıkış akışı olarak bir Buffer veya Stream yerine bir memory-stream kütüphanesi kullanabilir veya archive.pipe(res) ile doğrudan bir HTTP yanıtına yazabilirsiniz.
* Açma: yauzl.fromBuffer() veya yauzl.fromFd() gibi metotlarla zip dosyasını bir Buffer‘dan veya dosya tanımlayıcısından açabilirsiniz. adm-zip zaten bellekte çalıştığı için doğrudan bir Buffer‘dan da başlatılabilir (new AdmZip(buffer)).

Ancak, bellekteki işlemlerin bellek tüketimi açısından dikkatli yönetilmesi gerekir, özellikle büyük dosyalar için.

Sıkıştırma oranını nasıl optimize edebilirim?

Sıkıştırma oranını artırmak için:

* zlib.level: archiver kütüphanesinde zlib: { level: 9 } seçeneğini kullanarak en yüksek sıkıştırma seviyesini ayarlayabilirsiniz. Ancak bu, sıkıştırma süresini artıracaktır.
* Dosya Türleri: Zaten sıkıştırılmış olan dosya türleri (JPEG, MP3, MP4 vb.) genellikle daha fazla sıkıştırılamaz. Metin dosyaları, kod dosyaları gibi metin tabanlı veriler daha iyi sıkıştırma oranları sunar.
* Tekrar Eden Veri: Zip dosyasına eklenen dosyalarda tekrar eden veri varsa, sıkıştırma algoritmaları bu tekrarı kullanarak daha iyi sıkıştırma oranları elde edebilir.

Parola korumalı zip dosyalarıyla nasıl çalışılır?

Yukarıda da belirtildiği gibi, Node.js’teki popüler zip kütüphanelerinin çoğu doğrudan parola korumalı zip dosyalarını desteklemez. Bu tür bir gereksiniminiz varsa, child_process modülü aracılığıyla 7-zip veya unzip gibi harici komut satırı araçlarını kullanmayı düşünebilirsiniz. Bu, platform bağımlılığına neden olsa da, genellikle daha güvenilir ve kapsamlı bir çözüm sunar. Örneğin:

const { exec } = require('child_process');

function extractPasswordProtectedZip(zipPath, destination, password) {
    // Linux/macOS için:
    const command = unzip -P "${password}" "${zipPath}" -d "${destination}";
    // Windows için 7-zip kullanmak gerekebilir:
    // const command = 7z x "${zipPath}" -o"${destination}" -p"${password}";

    exec(command, (error, stdout, stderr) => {
        if (error) {
            console.error(Zip çıkarma hatası: ${error.message});
            return;
        }
        if (stderr) {
            console.error(Zip çıkarma stderr: ${stderr});
            return;
        }
        console.log(Zip başarıyla çıkarıldı: ${stdout});
    });
}

// extractPasswordProtectedZip('protected.zip', 'output_folder', 'mysecretpassword');

Bu yaklaşım, Node.js uygulamanızın çalıştığı sunucuda ilgili komut satırı aracının kurulu olmasını gerektirir.

Sonuç

Node.js, zip dosyalarıyla çalışmak için zengin bir kütüphane ekosistemine sahiptir. Bu makalede, archiver ile sıkıştırma, yauzl ile açma ve adm-zip ile daha basit işlemler olmak üzere üç temel kütüphaneyi detaylı olarak inceledik. Her bir kütüphanenin kendine özgü avantajları ve kullanım senaryoları bulunmaktadır:

* archiver ve yauzl: Büyük ölçekli, performans odaklı ve akış tabanlı işlemler için idealdir. Bellek verimliliği ve esneklik sunar.
* adm-zip: Küçük ve orta ölçekli işler için hızlı ve basit bir çözüm sunar, ancak büyük dosyalar için bellek kısıtlamaları olabilir.

Ayrıca, büyük dosyalarla çalışma, hata yönetimi, güvenlik (özellikle dizin atlama saldırılarına karşı koruma), asenkron programlama ve geçici dosya kullanımı gibi gelişmiş konulara da değindik. Bu en iyi uygulamaları takip etmek, Node.js uygulamalarınızda zip işlemlerini daha sağlam, güvenli ve verimli hale getirecektir.

Node.js’in gücü ve esnekliği sayesinde, dosya sıkıştırma ve açma ihtiyaçlarınızı kolayca karşılayabilir, uygulamalarınızın dosya yönetimi yeteneklerini önemli ölçüde artırabilirsiniz. Uygulamanızın özel gereksinimlerine göre doğru kütüphaneyi seçmek ve bu rehberdeki bilgileri uygulamak, başarılı bir entegrasyon için anahtar olacaktır.