{"_id":"@aerane/zip-service","name":"@aerane/zip-service","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aerane/zip-service","version":"1.0.0","description":"Enterprise-grade zip service module for creating, extracting, and batch processing ZIP archives in Node.js","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"demo":"ts-node example.ts","build":"tsc","test":"jest","test:coverage":"jest --coverage","format":"prettier --write \"src/**/*.ts\"","prepare":"npm run build"},"keywords":["zip","unzip","archive","compress","extract","stream"],"author":{"name":"Aerane"},"license":"MIT","engines":{"node":">=18.0.0"},"devDependencies":{"@types/archiver":"^8.0.0","@types/jest":"^30.0.0","@types/node":"^26.1.1","@types/unzipper":"^0.10.11","@typescript-eslint/eslint-plugin":"^8.64.0","@typescript-eslint/parser":"^8.64.0","eslint":"^10.7.0","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.6","jest":"^30.4.2","prettier":"^3.9.5","ts-jest":"^29.4.11","ts-node":"^10.9.2","typescript":"^5.9.3"},"dependencies":{"archiver":"^5.3.2","unzipper":"^0.12.5"},"prettier":{"semi":true,"trailingComma":"all","singleQuote":true,"printWidth":100,"tabWidth":2},"jest":{"preset":"ts-jest","testEnvironment":"node","testMatch":["**/test/**/*.test.ts"],"collectCoverageFrom":["src/**/*.ts","!src/types/index.ts"],"coverageDirectory":"coverage","coverageReporters":["text","lcov"],"moduleFileExtensions":["ts","js","json","node"]},"eslintConfig":{"parser":"@typescript-eslint/parser","extends":["eslint:recommended","plugin:@typescript-eslint/recommended","plugin:prettier/recommended"],"parserOptions":{"ecmaVersion":2020,"sourceType":"module"},"env":{"node":true,"jest":true},"rules":{"@typescript-eslint/no-explicit-any":"warn","@typescript-eslint/no-unused-vars":["warn",{"argsIgnorePattern":"^_"}]}},"gitHead":"c5fa28ff1f28ff0f2332c0130202e1e6933cc90a","_id":"@aerane/zip-service@1.0.0","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-5GuoSHq+MUZruPzLohhe68bI6ogQK63MtRb0IFTXC+Oq0U3REPnYCSClcMefVHjwQUqFEYjyHA2JKE1h2FZKDg==","shasum":"bee5a05bc52de1a82c48890d0492f604bbb67488","tarball":"https://registry.npmjs.org/@aerane/zip-service/-/zip-service-1.0.0.tgz","fileCount":14,"unpackedSize":39863,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCcA+KHRjWSnWxsWvJ2ltSatJk8YB2mJoN0bCNrLw08lAIgYwN9bUisep1268AroEF49z0Y6/f40B5mmzuelnQLfUM="}]},"_npmUser":{"name":"aerane","email":"geshan0810@gmail.com"},"directories":{},"maintainers":[{"name":"aerane","email":"geshan0810@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zip-service_1.0.0_1784535848890_0.4501465594089604"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-20T08:24:08.625Z","1.0.0":"2026-07-20T08:24:09.026Z","modified":"2026-07-20T08:24:09.319Z"},"maintainers":[{"name":"aerane","email":"geshan0810@gmail.com"}],"description":"Enterprise-grade zip service module for creating, extracting, and batch processing ZIP archives in Node.js","keywords":["zip","unzip","archive","compress","extract","stream"],"author":{"name":"Aerane"},"license":"MIT","readme":"# Zip Service\n\nModul 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). \n\n## Instalasi\n\n```bash\nnpm install zip-service\n```\n\n## Cara Penggunaan\n\nModul ini mendukung format impor modern (ES Modules/TypeScript) maupun format lama (CommonJS). Dapat memilih sesuai dengan preferensi atau kebutuhan proyek.\n\n### Menggunakan `import` (TypeScript / ES Modules)\n```typescript\nimport { ZipService } from 'zip-service';\n\nconst zip = new ZipService();\n```\n\n### Menggunakan `require` (CommonJS / Javascript)\n```javascript\nconst { ZipService } = require('zip-service');\n\nconst zip = new ZipService();\n```\n\n## Menjalankan Demo\n\nRepositori ini menyertakan skrip demo untuk menguji fungsionalitas kompresi, ekstraksi, dan pemrosesan massal batch secara langsung.\n\nUntuk menjalankan simulasi, gunakan perintah berikut di terminal:\n\n```bash\nnpm run demo\n```\n\nPerintah ini akan mengeksekusi `example.ts`, yang memproses contoh data pada direktori `all-file/`. Hasil proses (output) akan disimpan ke dalam direktori `all-file-output/`.\n\n## Fitur Utama\n\n### 1. Pemrosesan Massal Otomatis (Batch Processing)\nFungsi 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.\n\n```javascript\n// Memproses semua sub-direktori dan file zip yang ada di dalam 'all-file'\n// Seluruh hasil akan disimpan ke dalam 'output-folder'\nawait zip.processBatchDirectory('./all-file', './output-folder');\n```\n\n### 2. Kompresi Folder atau File Spesifik\nDapat melakukan kompresi pada direktori atau file tunggal dengan mudah. \n\n```javascript\n// Mengompresi satu direktori utuh\nawait zip.zip('./folder-sumber', './hasil-kompresi.zip');\n\n// Mengompresi satu file spesifik saja\nawait zip.zipFile('./file.pdf', './arsip-file.zip');\n\n// Mengompresi beberapa file spesifik menjadi satu file zip\nawait zip.zipMultiple([\n  './file1.txt',\n  './file2.jpg'\n], './berkas.zip');\n\n// Jika ingin mempertahankan nama direktori sumber sebagai pembungkus di dalam file zip \n// (sehingga isi folder tidak langsung ditempatkan di root zip), atur opsi flattenRoot menjadi false:\nawait zip.zip('./folder-sumber', './hasil-kompresi.zip', { flattenRoot: false });\n```\n\n### 3. Ekstrak (Unzip) Keseluruhan\nMengekstrak seluruh isi file zip ke dalam suatu direktori tujuan dengan cepat. Jika direktori tujuan belum ada, modul ini akan membuatnya secara otomatis.\n\n```javascript\n// Mengekstrak file zip ke folder tujuan\nawait zip.extract('./arsip-file.zip', './folder-ekstrak');\n```\n\n### 4. Fitur Lanjutan (Advanced Features)\n\n#### A. Mendapatkan Metadata File ZIP (Tanpa Mengekstrak)\nDapat 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.\n\n```javascript\nconst entries = await zip.getEntries('./arsip-file.zip');\nconsole.log(`Ditemukan ${entries.length} file/folder`);\n\nfor (const entry of entries) {\n    const tipe = entry.isDirectory ? 'Folder' : `${entry.size} bytes`;\n    console.log(`- ${entry.name} (${tipe})`);\n}\n```\n\n#### B. Mengekstrak Hanya Satu Folder Tertentu\nJika ZIP berisi ratusan folder tapi hanya butuh satu folder spesifik, gunakan `extractFolder`.\n\n```javascript\n// Mengekstrak semua isi dari folder 'assets/images/' di dalam ZIP ke folder './gambar'\nawait zip.extractFolder('./arsip-file.zip', 'assets/images/', './gambar');\n```\n\n#### C. Streaming Satu File Spesifik\nMengambil satu file teks/gambar langsung dari dalam ZIP dan mengalirkannya (Stream) ke output, tanpa menyimpannya ke *hard disk*.\n\n```javascript\n// Mengalirkan isi file 'logs/error.log' dari dalam ZIP langsung ke console/terminal\nconst stream = await zip.streamFile('./arsip-file.zip', 'logs/error.log');\nstream.pipe(process.stdout);\n```\n\n#### D. Event Listeners (Real-Time Monitoring)\nDapat memantau proses secara *real-time*:\n\n```javascript\n// Dipanggil seketika saat header file terbaca dari dalam ZIP (sangat cepat)\nzip.on('entry', (entry) => {\n    console.log(`Ditemukan: ${entry.name}`);\n});\n\n// Dipanggil setelah satu file berhasil selesai ditulis ke hard disk\nzip.on('extract', (entry, targetPath) => {\n    console.log(`Sukses mengekstrak ${entry.name} ke ${targetPath}`);\n});\n\nawait zip.extract('./arsip-file.zip', './folder-ekstrak');\n```\n\n### 5. Membaca Teks Langsung dari Zip\nMembaca isi file berbasis teks (seperti `.txt`, `.json`, `.md`) langsung dari dalam zip ke dalam memori (string), tanpa perlu menyimpannya ke disk.\n\n```javascript\n// Membaca isi 'data.json' langsung dari dalam zip\nconst isiTeks = await zip.readFileAsText('./arsip.zip', 'data.json');\nconsole.log(isiTeks);\n```\n\n### 6. Melihat Daftar Isi Zip\nMenampilkan daftar seluruh file dan folder yang ada di dalam zip tanpa mengekstraksinya.\n\n```javascript\nconst daftarFile = await zip.listContents('./arsip.zip');\nconsole.log(daftarFile); // Output: ['folder1/', 'folder1/file.txt', 'file2.jpg']\n```\n\n## Opsi Tambahan (Options)\n\nBeberapa metode mendukung parameter `options` di argumen terakhir. Misalnya untuk menangani file ZIP yang dipassword saat ekstraksi:\n\n```javascript\n// Mengekstraksi file ZIP yang memiliki password\nawait zip.extract('./rahasia.zip', './folder-tujuan', { \n  password: 'password-rahasia-123' \n});\n```\n\nSelain `password`, terdapat opsi lain seperti `overwrite: false` (untuk mencegah penimpaan file) dan `compressionLevel` (untuk mengatur tingkat kompresi saat membuat ZIP).\n\n## Penanganan Masalah (Error Handling)\n\nApabila terjadi kesalahan operasional, modul akan menghasilkan error berjenis `ZipServiceError`. Dapat memeriksa kode error tersebut untuk mempermudah proses pelacakan masalah (debugging):\n\n- `SOURCE_NOT_FOUND` - Direktori atau file sumber tidak ditemukan.\n- `INVALID_ZIP` - Format file zip rusak atau tidak valid.\n- `TARGET_EXISTS` - File atau direktori output sudah ada (jika opsi overwrite dimatikan).\n- `UNKNOWN` - Kesalahan sistem lainnya yang tidak teridentifikasi.\n\n## Pengujian (Testing)\n\nProyek ini dilengkapi dengan rangkaian pengujian unit (*unit testing*) menggunakan **Jest** untuk menjamin stabilitas dan kualitas kode sumber.\n\nBagi pengembang yang hendak berkontribusi atau memodifikasi kode, pastikan untuk memverifikasi kualitas program dengan menjalankan perintah berikut sebelum mengajukan perubahan:\n\n```bash\nnpm run test\n```\n\nUntuk menampilkan laporan cakupan pengujian (*test coverage*), jalankan perintah berikut:\n\n```bash\nnpm run test:coverage\n```\n","readmeFilename":"README.md","_rev":"1-0e0511e33357f22d88097d9d8763de9d"}