Zip Service

Modul Node.js sederhana namun tangguh untuk kebutuhan kompresi (zip) dan ekstraksi file. Dirancang menggunakan metode asynchronous stream, sehingga aman untuk memproses file berukuran besar atau menangani ribuan file tanpa menyebabkan hambatan pada server (event-loop blocking).

Instalasi

npm install zip-service

Cara Penggunaan

Modul ini mendukung format impor modern (ES Modules/TypeScript) maupun format lama (CommonJS). Dapat memilih sesuai dengan preferensi atau kebutuhan proyek.

Menggunakan import (TypeScript / ES Modules)

import { ZipService } from 'zip-service';

const zip = new ZipService();

Menggunakan require (CommonJS / Javascript)

const { ZipService } = require('zip-service');

const zip = new ZipService();

Menjalankan Demo

Repositori ini menyertakan skrip demo untuk menguji fungsionalitas kompresi, ekstraksi, dan pemrosesan massal batch secara langsung.

Untuk menjalankan simulasi, gunakan perintah berikut di terminal:

npm run demo

Perintah ini akan mengeksekusi example.ts, yang memproses contoh data pada direktori all-file/. Hasil proses (output) akan disimpan ke dalam direktori all-file-output/.

Fitur Utama

1. Pemrosesan Massal Otomatis (Batch Processing)

Fungsi ini sangat berguna jika memiliki satu direktori utama yang berisi banyak sub-direktori dan file .zip. Fitur ini akan mencari semua sub-direktori untuk dikompresi, dan mencari semua file .zip untuk diekstraksi secara otomatis. Seluruh hasil pemrosesan akan ditempatkan di dalam direktori output yang ditentukan.

// Memproses semua sub-direktori dan file zip yang ada di dalam 'all-file'
// Seluruh hasil akan disimpan ke dalam 'output-folder'
await zip.processBatchDirectory('./all-file', './output-folder');

2. Kompresi Folder atau File Spesifik

Dapat melakukan kompresi pada direktori atau file tunggal dengan mudah.

// Mengompresi satu direktori utuh
await zip.zip('./folder-sumber', './hasil-kompresi.zip');

// Mengompresi satu file spesifik saja
await zip.zipFile('./file.pdf', './arsip-file.zip');

// Mengompresi beberapa file spesifik menjadi satu file zip
await zip.zipMultiple([
  './file1.txt',
  './file2.jpg'
], './berkas.zip');

// Jika ingin mempertahankan nama direktori sumber sebagai pembungkus di dalam file zip 
// (sehingga isi folder tidak langsung ditempatkan di root zip), atur opsi flattenRoot menjadi false:
await zip.zip('./folder-sumber', './hasil-kompresi.zip', { flattenRoot: false });

3. Ekstrak (Unzip) Keseluruhan

Mengekstrak seluruh isi file zip ke dalam suatu direktori tujuan dengan cepat. Jika direktori tujuan belum ada, modul ini akan membuatnya secara otomatis.

// Mengekstrak file zip ke folder tujuan
await zip.extract('./arsip-file.zip', './folder-ekstrak');

4. Fitur Lanjutan (Advanced Features)

A. Mendapatkan Metadata File ZIP (Tanpa Mengekstrak)

Dapat melihat daftar seluruh file dan folder di dalam ZIP secara instan berserta informasi ukurannya (tanpa membebani disk untuk mengekstraknya). Sangat cocok untuk ZIP berukuran sangat besar.

const entries = await zip.getEntries('./arsip-file.zip');
console.log(`Ditemukan ${entries.length} file/folder`);

for (const entry of entries) {
    const tipe = entry.isDirectory ? 'Folder' : `${entry.size} bytes`;
    console.log(`- ${entry.name} (${tipe})`);
}

B. Mengekstrak Hanya Satu Folder Tertentu

Jika ZIP berisi ratusan folder tapi hanya butuh satu folder spesifik, gunakan extractFolder.

// Mengekstrak semua isi dari folder 'assets/images/' di dalam ZIP ke folder './gambar'
await zip.extractFolder('./arsip-file.zip', 'assets/images/', './gambar');

C. Streaming Satu File Spesifik

Mengambil satu file teks/gambar langsung dari dalam ZIP dan mengalirkannya (Stream) ke output, tanpa menyimpannya ke hard disk.

// Mengalirkan isi file 'logs/error.log' dari dalam ZIP langsung ke console/terminal
const stream = await zip.streamFile('./arsip-file.zip', 'logs/error.log');
stream.pipe(process.stdout);

D. Event Listeners (Real-Time Monitoring)

Dapat memantau proses secara real-time:

// Dipanggil seketika saat header file terbaca dari dalam ZIP (sangat cepat)
zip.on('entry', (entry) => {
    console.log(`Ditemukan: ${entry.name}`);
});

// Dipanggil setelah satu file berhasil selesai ditulis ke hard disk
zip.on('extract', (entry, targetPath) => {
    console.log(`Sukses mengekstrak ${entry.name} ke ${targetPath}`);
});

await zip.extract('./arsip-file.zip', './folder-ekstrak');

5. Membaca Teks Langsung dari Zip

Membaca isi file berbasis teks (seperti .txt, .json, .md) langsung dari dalam zip ke dalam memori (string), tanpa perlu menyimpannya ke disk.

// Membaca isi 'data.json' langsung dari dalam zip
const isiTeks = await zip.readFileAsText('./arsip.zip', 'data.json');
console.log(isiTeks);

6. Melihat Daftar Isi Zip

Menampilkan daftar seluruh file dan folder yang ada di dalam zip tanpa mengekstraksinya.

const daftarFile = await zip.listContents('./arsip.zip');
console.log(daftarFile); // Output: ['folder1/', 'folder1/file.txt', 'file2.jpg']

Opsi Tambahan (Options)

Beberapa metode mendukung parameter options di argumen terakhir. Misalnya untuk menangani file ZIP yang dipassword saat ekstraksi:

// Mengekstraksi file ZIP yang memiliki password
await zip.extract('./rahasia.zip', './folder-tujuan', { 
  password: 'password-rahasia-123' 
});

Selain password, terdapat opsi lain seperti overwrite: false (untuk mencegah penimpaan file) dan compressionLevel (untuk mengatur tingkat kompresi saat membuat ZIP).

Penanganan Masalah (Error Handling)

Apabila terjadi kesalahan operasional, modul akan menghasilkan error berjenis ZipServiceError. Dapat memeriksa kode error tersebut untuk mempermudah proses pelacakan masalah (debugging):

• SOURCE_NOT_FOUND - Direktori atau file sumber tidak ditemukan.
• INVALID_ZIP - Format file zip rusak atau tidak valid.
• TARGET_EXISTS - File atau direktori output sudah ada (jika opsi overwrite dimatikan).
• UNKNOWN - Kesalahan sistem lainnya yang tidak teridentifikasi.

Pengujian (Testing)

Proyek ini dilengkapi dengan rangkaian pengujian unit (unit testing) menggunakan Jest untuk menjamin stabilitas dan kualitas kode sumber.

Bagi pengembang yang hendak berkontribusi atau memodifikasi kode, pastikan untuk memverifikasi kualitas program dengan menjalankan perintah berikut sebelum mengajukan perubahan:

npm run test

Untuk menampilkan laporan cakupan pengujian (test coverage), jalankan perintah berikut:

npm run test:coverage