@neoware_inc/neozipkit 0.5.0

package/examples/copy-zip-append.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+/**
+ * Copy ZIP and Append Example
+ *
+ * Copies entry data from example.zip into copied.zip, appends append-data.json
+ * in a single pass using ZipCopyNode: copyZipEntriesOnly, append the new file,
+ * then writeCentralDirectoryAndEOCD.
+ */
+
+import { ZipCopyNode, ZipkitNode, crc32, CMP_METHOD } from '../src/node';
+import ZipEntry from '../src/core/ZipEntry';
+import * as fs from 'fs';
+import * as path from 'path';
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return (bytes / Math.pow(k, i)).toFixed(1) + ' ' + sizes[i];
+}
+
+function padRight(str: string, length: number): string {
+  return (str + ' '.repeat(length)).slice(0, length);
+}
+
+function padLeft(str: string, length: number): string {
+  return (' '.repeat(length) + str).slice(-length);
+}
+
+async function main() {
+  console.log('Copy ZIP and append file example...\n');
+
+  const sourceZip = path.join(__dirname, 'output', 'example.zip');
+  let actualSourceZip = sourceZip;
+  if (!fs.existsSync(sourceZip)) {
+    const outputDir = path.dirname(sourceZip);
+    if (fs.existsSync(outputDir)) {
+      const files = fs.readdirSync(outputDir).filter((f) => f.endsWith('.zip'));
+      if (files.length > 0) {
+        actualSourceZip = path.join(outputDir, files[0]);
+        console.log(`⚠️  example.zip not found, using: ${files[0]}\n`);
+      }
+    }
+  }
+
+  if (!fs.existsSync(actualSourceZip)) {
+    console.error(`❌ Error: Source ZIP not found: ${actualSourceZip}`);
+    console.error('   Run create-zip.ts first, or point sourceZip to an existing ZIP.');
+    process.exit(1);
+  }
+
+  const appendFilePath = path.join(__dirname, 'append-data.json');
+  if (!fs.existsSync(appendFilePath)) {
+    console.error(`❌ Error: File to append not found: ${appendFilePath}`);
+    process.exit(1);
+  }
+
+  const destZip = path.join(__dirname, 'output', 'copied.zip');
+  const outputDir = path.dirname(destZip);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  const zipkitNode = new ZipkitNode();
+  const zipCopy = new ZipCopyNode(zipkitNode);
+
+  try {
+    // 1. Copy only entry data (no central directory or EOCD yet)
+    console.log('1. Copying entry data from source ZIP...');
+    const { destPath, dataEndOffset, copiedEntries } = await zipCopy.copyZipEntriesOnly(
+      actualSourceZip,
+      destZip
+    );
+    console.log(`   Copied ${copiedEntries.length} entries; data ends at offset ${dataEndOffset}\n`);
+
+    // 2. Append append-data.json as a stored entry
+    const entryName = 'append-data.json';
+    const fileData = fs.readFileSync(appendFilePath);
+    const fileCrc = crc32(fileData) >>> 0;
+    const fileSize = fileData.length;
+
+    const entry = new ZipEntry(entryName, null, false);
+    entry.localHdrOffset = dataEndOffset;
+    entry.cmpMethod = CMP_METHOD.STORED;
+    entry.crc = fileCrc;
+    entry.compressedSize = fileSize;
+    entry.uncompressedSize = fileSize;
+    entry.timeDateDOS = entry.setDateTime(new Date());
+
+    const localHeaderBuf = entry.createLocalHdr();
+    const destFd = fs.openSync(destPath, 'r+');
+    try {
+      fs.writeSync(destFd, localHeaderBuf, 0, localHeaderBuf.length, dataEndOffset);
+      fs.writeSync(destFd, fileData, 0, fileData.length, dataEndOffset + localHeaderBuf.length);
+    } finally {
+      fs.closeSync(destFd);
+    }
+    console.log(`2. Appended "${entryName}" (${formatBytes(fileSize)} stored)\n`);
+
+    // 3. Write central directory and EOCD for all entries (copied + appended)
+    const allEntries = [...copiedEntries, entry];
+    zipCopy.writeCentralDirectoryAndEOCD(destPath, allEntries, { zipComment: '' });
+    console.log('3. Wrote central directory and EOCD.\n');
+
+    console.log(`✅ Done: ${destZip}\n`);
+
+    console.log('Entries in final ZIP:');
+    console.log('─'.repeat(80));
+    console.log(
+      padRight('Filename', 50) + padLeft('Compressed', 14) + padLeft('Offset', 14)
+    );
+    console.log('─'.repeat(80));
+    allEntries.forEach((e) => {
+      console.log(
+        padRight(e.filename.length > 48 ? e.filename.slice(0, 45) + '...' : e.filename, 50) +
+          padLeft(formatBytes(e.compressedSize), 14) +
+          padLeft(`0x${e.localHdrOffset.toString(16)}`, 14)
+      );
+    });
+    console.log('─'.repeat(80));
+    console.log(`Total: ${allEntries.length} entries`);
+
+    if (fs.existsSync(destZip)) {
+      const destStats = fs.statSync(destZip);
+      console.log(`\nArchive size: ${formatBytes(destStats.size)}`);
+    }
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error('Fatal:', e);
+  process.exit(1);
+});

package/examples/copy-zip.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+/**
+ * Copy ZIP Example
+ * 
+ * Demonstrates copying entries from an existing ZIP file to a new ZIP file
+ * using the ZipCopyNode class. This preserves all original properties
+ * (compression, timestamps, etc.) without decompression/recompression.
+ */
+
+import { ZipCopyNode, ZipkitNode } from '../src/node';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Helper function to format bytes
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return (bytes / Math.pow(k, i)).toFixed(1) + ' ' + sizes[i];
+}
+
+/**
+ * Helper function to pad string to the right
+ */
+function padRight(str: string, length: number): string {
+  return (str + ' '.repeat(length)).slice(0, length);
+}
+
+/**
+ * Helper function to pad string to the left
+ */
+function padLeft(str: string, length: number): string {
+  return (' '.repeat(length) + str).slice(-length);
+}
+
+async function main() {
+  console.log('Copy ZIP file example...\n');
+
+  // Source ZIP file (use the example.zip created by create-zip.ts if it exists)
+  const sourceZip = path.join(__dirname, 'output', 'example.zip');
+  
+  // If example.zip doesn't exist, check for any ZIP file in the output directory
+  let actualSourceZip = sourceZip;
+  if (!fs.existsSync(sourceZip)) {
+    const outputDir = path.dirname(sourceZip);
+    if (fs.existsSync(outputDir)) {
+      const files = fs.readdirSync(outputDir).filter(f => f.endsWith('.zip'));
+      if (files.length > 0) {
+        actualSourceZip = path.join(outputDir, files[0]);
+        console.log(`⚠️  example.zip not found, using: ${files[0]}\n`);
+      }
+    }
+  }
+
+  // Verify source ZIP exists
+  if (!fs.existsSync(actualSourceZip)) {
+    console.error(`❌ Error: Source ZIP file not found: ${actualSourceZip}`);
+    console.error('   Please run create-zip.ts first to create a ZIP file, or');
+    console.error('   update the sourceZip path in this example to point to an existing ZIP file.');
+    process.exit(1);
+  }
+
+  const sourceStats = fs.statSync(actualSourceZip);
+  console.log(`Source ZIP: ${path.basename(actualSourceZip)}`);
+  console.log(`  Size: ${formatBytes(sourceStats.size)}`);
+  console.log();
+
+  // Destination ZIP file
+  const destZip = path.join(__dirname, 'output', 'copied.zip');
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(destZip);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  try {
+    console.log('Copying ZIP entries...');
+    
+    // Create ZipCopyNode instance
+    const zipkitNode = new ZipkitNode();
+    const zipCopy = new ZipCopyNode(zipkitNode);
+    
+    // Option 1: Copy all entries
+    console.log('  Copying all entries from source to destination...');
+    const result = await zipCopy.copyZipFile(actualSourceZip, destZip);
+
+    console.log(`✅ ZIP file copied successfully: ${destZip}\n`);
+
+    // Display summary of copied entries
+    console.log('Copied Entries Summary:');
+    console.log('─'.repeat(80));
+    console.log(
+      padRight('Filename', 50) +
+      padLeft('Compressed Size', 20) +
+      padLeft('Local Header Offset', 20)
+    );
+    console.log('─'.repeat(80));
+
+    result.entries.forEach((entry) => {
+      const filename = entry.filename || '(unnamed)';
+      console.log(
+        padRight(filename.length > 48 ? filename.substring(0, 45) + '...' : filename, 50) +
+        padLeft(formatBytes(entry.compressedSize), 20) +
+        padLeft(`0x${entry.localHeaderOffset.toString(16)}`, 20)
+      );
+    });
+
+    console.log('─'.repeat(80));
+    console.log(`Total entries copied: ${result.totalEntries}`);
+    console.log(`Central directory offset: 0x${result.centralDirOffset.toString(16)}`);
+
+    // Verify the copied ZIP was created
+    if (fs.existsSync(destZip)) {
+      const destStats = fs.statSync(destZip);
+      console.log(`\nDestination ZIP file size: ${formatBytes(destStats.size)}`);
+      
+      // Compare sizes (they should be very similar, possibly identical)
+      const sizeDiff = Math.abs(sourceStats.size - destStats.size);
+      if (sizeDiff === 0) {
+        console.log('✅ File sizes match exactly - perfect copy!');
+      } else {
+        console.log(`ℹ️  Size difference: ${formatBytes(sizeDiff)} (expected due to ZIP structure variations)`);
+      }
+    }
+
+    console.log('\n💡 Tip: You can also filter entries during copy:');
+    console.log('   const zipCopy = new ZipCopyNode(new ZipkitNode());');
+    console.log('   await zipCopy.copyZipFile(sourceZip, destZip, {');
+    console.log('     entryFilter: (entry) => entry.filename.endsWith(".txt")');
+    console.log('   });');
+
+  } catch (error) {
+    console.error('❌ Error copying ZIP file:');
+    console.error(error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run the example
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/examples/create-zip.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Create ZIP Example
+ * 
+ * Demonstrates creating a ZIP archive from multiple files using ZipkitNode.
+ * This is a minimal example showing the basic API usage.
+ */
+
+import ZipkitNode from '../src/node';
+import type { CompressOptions } from '../src/core';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Helper function to format bytes
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return (bytes / Math.pow(k, i)).toFixed(1) + ' ' + sizes[i];
+}
+
+/**
+ * Helper function to pad string to the right
+ */
+function padRight(str: string, length: number): string {
+  return (str + ' '.repeat(length)).slice(0, length);
+}
+
+/**
+ * Helper function to pad string to the left
+ */
+function padLeft(str: string, length: number): string {
+  return (' '.repeat(length) + str).slice(-length);
+}
+
+async function main() {
+  console.log('Creating ZIP archive example...\n');
+
+  // Test files to compress (located in test-files directory)
+  const testDir = path.join(__dirname, 'test-files');
+  const testFiles = [
+    path.join(testDir, 'file1.txt'),
+    path.join(testDir, 'file2.txt'),
+    path.join(testDir, 'document.md'),
+    path.join(testDir, 'data.json')
+  ];
+
+  // Verify all test files exist
+  for (const file of testFiles) {
+    if (!fs.existsSync(file)) {
+      console.error(`❌ Error: Test file not found: ${file}`);
+      console.error('   Make sure test-files directory contains the required files.');
+      process.exit(1);
+    }
+  }
+
+  console.log('Source files:');
+  testFiles.forEach(file => {
+    const stats = fs.statSync(file);
+    console.log(`  - ${path.basename(file)} (${stats.size} bytes)`);
+  });
+  console.log();
+
+  // Create ZipkitNode instance
+  const zip = new ZipkitNode();
+
+  // Define output ZIP file path
+  const outputZip = path.join(__dirname, 'output', 'example.zip');
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputZip);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Compression options
+  const options: CompressOptions = {
+    level: 6,        // Compression level (0-9, higher = better compression but slower)
+    useZstd: false,  // Use Deflate compression (standard ZIP)
+    useSHA256: false // Don't calculate SHA-256 hashes (faster, but needed for blockchain features)
+  };
+
+  try {
+    console.log('Creating ZIP archive...');
+    
+    // Method 1: Simple API - create ZIP from file paths
+    // This is the easiest way to create a ZIP file
+    await zip.createZipFromFiles(testFiles, outputZip, options);
+
+    console.log(`✅ ZIP archive created successfully: ${outputZip}\n`);
+
+    // Load the ZIP to get entry details
+    await zip.loadZipFile(outputZip);
+    const entries = zip.getDirectory();
+
+    // Display summary of compressed files
+    console.log('Compression Summary:');
+    console.log('─'.repeat(80));
+    console.log(
+      padRight('Filename', 30) +
+      padLeft('Original', 10) +
+      padLeft('Compressed', 12) +
+      padLeft('Ratio', 10) +
+      '   ' +
+      padRight('Method', 10)
+    );
+    console.log('─'.repeat(80));
+
+    let totalOriginal = 0;
+    let totalCompressed = 0;
+
+    entries.forEach((entry) => {
+      const filename = entry.filename || '(unnamed)';
+      const original = entry.uncompressedSize || 0;
+      const compressed = entry.compressedSize || 0;
+      const ratio = original > 0 ? ((1 - compressed / original) * 100).toFixed(1) : '0.0';
+      const method = entry.cmpMethodToString();
+
+      totalOriginal += original;
+      totalCompressed += compressed;
+
+      console.log(
+        padRight(filename.length > 28 ? filename.substring(0, 25) + '...' : filename, 30) +
+        padLeft(formatBytes(original), 10) +
+        padLeft(formatBytes(compressed), 12) +
+        padLeft(ratio + '%', 10) +
+        '   ' +
+        padRight(method, 10)
+      );
+    });
+
+    console.log('─'.repeat(80));
+    const totalRatio = totalOriginal > 0 ? ((1 - totalCompressed / totalOriginal) * 100).toFixed(1) : '0.0';
+    console.log(
+      padRight('Total', 30) +
+      padLeft(formatBytes(totalOriginal), 10) +
+      padLeft(formatBytes(totalCompressed), 12) +
+      padLeft(totalRatio + '%', 10) +
+      '   ' +
+      padRight('', 10)
+    );
+    console.log('─'.repeat(80));
+
+    // Verify the ZIP was created
+    if (fs.existsSync(outputZip)) {
+      const zipStats = fs.statSync(outputZip);
+      console.log(`\nArchive file size: ${formatBytes(zipStats.size)}`);
+    }
+
+    console.log('\n💡 Tip: You can also use addFileToZip() for more control:');
+    console.log('   const zip = new ZipkitNode();');
+    console.log('   await zip.addFileToZip("file.txt", "file.txt", options);');
+    console.log('   // ... add more files ...');
+    console.log('   // Then manually write ZIP structure');
+
+  } catch (error) {
+    console.error('❌ Error creating ZIP archive:');
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run the example
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+

package/examples/extract-zip.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Extract ZIP Example
+ * 
+ * Demonstrates extracting files from a ZIP archive using ZipkitNode.
+ * This is a minimal example showing the basic extraction API.
+ * 
+ * Note: CRC-32 and SHA-256 validation happens automatically during extraction.
+ * If extraction completes without errors, all files have been validated.
+ */
+
+import ZipkitNode from '../src/node';
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function main() {
+  console.log('Extracting ZIP archive example...\n');
+
+  // Example: Use the ZIP file created by create-zip.ts
+  // You can also specify your own ZIP file path here
+  const archivePath = path.join(__dirname, 'output', 'example.zip');
+  const destination = path.join(__dirname, 'extracted');
+
+  // Check if ZIP file exists
+  if (!fs.existsSync(archivePath)) {
+    console.error(`❌ ZIP file not found: ${archivePath}`);
+    console.error('💡 Tip: Run create-zip.ts first to create a test ZIP file,');
+    console.error('   or modify archivePath to point to your own ZIP file.');
+    process.exit(1);
+  }
+
+  console.log(`Archive: ${archivePath}`);
+  console.log(`Destination: ${destination}\n`);
+
+  // Create ZipkitNode instance
+  const zip = new ZipkitNode();
+
+  try {
+    // Load ZIP file - this reads the central directory and populates entries
+    console.log('Loading ZIP file...');
+    await zip.loadZipFile(archivePath);
+
+    // Get directory listing to show what will be extracted
+    const entries = zip.getDirectory();
+    console.log(`Found ${entries.length} file(s) in archive:\n`);
+    
+    entries.forEach((entry, index) => {
+      const size = entry.uncompressedSize || 0;
+      const compressed = entry.compressedSize || 0;
+      const method = entry.cmpMethodToString();
+      console.log(`  ${index + 1}. ${entry.filename}`);
+      console.log(`     Size: ${size} bytes (compressed: ${compressed} bytes, ${method})`);
+    });
+    console.log();
+
+    // Option: Test mode - validate integrity without extracting files
+    // Uncomment the following lines to test without extracting:
+    /*
+    console.log('Testing ZIP integrity (without extracting)...');
+    for (const entry of entries) {
+      const testResult = await zip.testEntry(entry, {
+        skipHashCheck: false  // Verify file integrity (CRC-32/SHA-256 checks)
+      });
+      console.log(`✅ ${entry.filename}: Validated`);
+      if (testResult.verifiedHash) {
+        console.log(`   Verified SHA-256: ${testResult.verifiedHash}`);
+      } else {
+        console.log(`   Verified CRC-32: ${entry.crc?.toString(16).toUpperCase().padStart(8, '0')}`);
+      }
+    }
+    console.log(`✅ All files validated successfully!`);
+    return;
+    */
+
+    // Extract all files to destination directory
+    // CRC-32 and SHA-256 validation happens automatically during extraction
+    // If extraction completes without errors, all files have been validated
+    console.log('Extracting files...');
+    const result = await zip.extractZipFile(archivePath, destination, {
+      overwrite: true,        // Overwrite existing files
+      preserveTimestamps: true, // Preserve file timestamps
+      skipHashCheck: false    // Verify file integrity (CRC-32/SHA-256 checks)
+      // Note: skipHashCheck: false is the default - validation happens automatically
+    });
+
+    console.log(`✅ Extraction completed successfully!`);
+    console.log(`   Files extracted: ${result.filesExtracted}`);
+    console.log(`   Total bytes: ${result.bytesExtracted}`);
+    console.log(`\n   All files validated (CRC-32/SHA-256 checks passed automatically)`);
+
+    console.log('\n💡 Tip: You can also extract individual entries:');
+    console.log('   await zip.loadZipFile("archive.zip");');
+    console.log('   const entries = zip.getDirectory();');
+    console.log('   await zip.extractToFile(entries[0], "output.txt");');
+    console.log('\n💡 Tip: Test integrity without extracting:');
+    console.log('   const result = await zip.testEntry(entry);');
+    console.log('   if (result.verifiedHash) {');
+    console.log('     console.log("SHA-256:", result.verifiedHash);');
+    console.log('   }');
+
+  } catch (error) {
+    console.error('❌ Error extracting ZIP archive:');
+    console.error(error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// Run the example
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+