@neoware_inc/neozipkit 0.5.0

package/src/core/components/Logger.ts

@@ -0,0 +1,180 @@
+/**
+ * Global Logger Utility for NeoZipKit
+ * Provides centralized console control with configurable log levels
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+export interface LoggerConfig {
+  enabled: boolean;
+  level: LogLevel;
+}
+
+/**
+ * Global Logger class for controlling console output throughout NeoZipKit
+ */
+export class Logger {
+  private static config: LoggerConfig = {
+    enabled: true,
+    level: 'info'
+  };
+
+  private static originalConsole = {
+    log: console.log,
+    error: console.error,
+    warn: console.warn,
+    debug: console.debug,
+    info: console.info
+  };
+
+  /**
+   * Configure the logger
+   */
+  static configure(config: Partial<LoggerConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Get current logger configuration
+   */
+  static getConfig(): LoggerConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Enable logging
+   */
+  static enable(): void {
+    this.config.enabled = true;
+  }
+
+  /**
+   * Disable all logging
+   */
+  static disable(): void {
+    this.config.enabled = false;
+  }
+
+  /**
+   * Set log level
+   */
+  static setLevel(level: LogLevel): void {
+    this.config.level = level;
+  }
+
+
+  /**
+   * Check if a log level should be output
+   */
+  private static shouldLog(level: LogLevel): boolean {
+    if (!this.config.enabled) return false;
+    
+    const levels: LogLevel[] = ['debug', 'info', 'warn', 'error', 'silent'];
+    const currentLevelIndex = levels.indexOf(this.config.level);
+    const requestedLevelIndex = levels.indexOf(level);
+    
+    return requestedLevelIndex >= currentLevelIndex;
+  }
+
+  /**
+   * Log a message
+   */
+  static log(...args: any[]): void {
+    if (this.shouldLog('info')) {
+      this.originalConsole.log(...args);
+    }
+  }
+
+  /**
+   * Log an error message
+   */
+  static error(...args: any[]): void {
+    if (this.shouldLog('error')) {
+      this.originalConsole.error(...args);
+    }
+  }
+
+  /**
+   * Log a warning message
+   */
+  static warn(...args: any[]): void {
+    if (this.shouldLog('warn')) {
+      this.originalConsole.warn(...args);
+    }
+  }
+
+  /**
+   * Log a debug message
+   */
+  static debug(...args: any[]): void {
+    if (this.shouldLog('debug')) {
+      // Use console.log for debug messages to ensure they're visible
+      this.originalConsole.log(...args);
+    }
+  }
+
+  /**
+   * Log an info message
+   */
+  static info(...args: any[]): void {
+    if (this.shouldLog('info')) {
+      this.originalConsole.info(...args);
+    }
+  }
+
+
+  /**
+   * Override console methods globally (use with caution)
+   */
+  static overrideConsole(): void {
+    console.log = (...args: any[]) => this.log(...args);
+    console.error = (...args: any[]) => this.error(...args);
+    console.warn = (...args: any[]) => this.warn(...args);
+    console.debug = (...args: any[]) => this.debug(...args);
+    console.info = (...args: any[]) => this.info(...args);
+  }
+
+  /**
+   * Restore original console methods
+   */
+  static restoreConsole(): void {
+    console.log = this.originalConsole.log;
+    console.error = this.originalConsole.error;
+    console.warn = this.originalConsole.warn;
+    console.debug = this.originalConsole.debug;
+    console.info = this.originalConsole.info;
+  }
+
+}
+
+/**
+ * Environment-based configuration
+ */
+export function configureLoggerFromEnvironment(): void {
+  const env = typeof process !== 'undefined' ? process.env : {};
+  
+  // Check for NEOZIP_DEBUG environment variable
+  if (env.NEOZIP_DEBUG === 'false') {
+    Logger.disable();
+  } else if (env.NEOZIP_DEBUG === 'true') {
+    Logger.enable();
+    Logger.setLevel('debug');
+  }
+
+  // Check for NEOZIP_LOG_LEVEL
+  if (env.NEOZIP_LOG_LEVEL) {
+    const level = env.NEOZIP_LOG_LEVEL as LogLevel;
+    if (['debug', 'info', 'warn', 'error', 'silent'].includes(level)) {
+      Logger.setLevel(level);
+    }
+  }
+
+  // Check for NODE_ENV
+  if (env.NODE_ENV === 'production') {
+    Logger.setLevel('error');
+  }
+}
+
+// Auto-configure from environment on import
+// Only run in Node.js environment
+configureLoggerFromEnvironment();

package/src/core/components/ProgressTracker.ts

@@ -0,0 +1,134 @@
+/**
+ * Progress tracker for streaming operations
+ * Provides real-time progress updates and ETA calculations
+ */
+export class ProgressTracker {
+  private startTime: number;
+  private lastUpdateTime: number;
+  private totalBytes: number;
+  private processedBytes: number;
+  private fileName: string;
+  private lastReportedPercent: number = -1;
+
+  constructor(fileName: string, totalBytes: number) {
+    this.fileName = fileName;
+    this.totalBytes = totalBytes;
+    this.processedBytes = 0;
+    this.startTime = Date.now();
+    this.lastUpdateTime = this.startTime;
+  }
+
+  /**
+   * Update progress with bytes processed
+   * @param bytesProcessed - Number of bytes processed in this update
+   */
+  update(bytesProcessed: number): void {
+    this.processedBytes += bytesProcessed;
+    this.reportProgress();
+  }
+
+  /**
+   * Set total bytes (useful when file size changes)
+   */
+  setTotalBytes(totalBytes: number): void {
+    this.totalBytes = totalBytes;
+  }
+
+  /**
+   * Report progress if enough time has passed or significant progress made
+   */
+  private reportProgress(): void {
+    const now = Date.now();
+    const percent = Math.floor((this.processedBytes / this.totalBytes) * 100);
+    
+    // Report if:
+    // 1. 1% or more progress made, OR
+    // 2. 500ms have passed since last report
+    const shouldReport = 
+      percent > this.lastReportedPercent || 
+      (now - this.lastUpdateTime) > 500;
+
+    if (shouldReport) {
+      this.lastReportedPercent = percent;
+      this.lastUpdateTime = now;
+      this.printProgress();
+    }
+  }
+
+  /**
+   * Print progress information
+   */
+  private printProgress(): void {
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    const rate = this.processedBytes / elapsed;
+    const eta = this.totalBytes > this.processedBytes 
+      ? (this.totalBytes - this.processedBytes) / rate 
+      : 0;
+    const percent = Math.floor((this.processedBytes / this.totalBytes) * 100);
+
+    const formatBytes = (bytes: number): string => {
+      const units = ['B', 'KB', 'MB', 'GB'];
+      let size = bytes;
+      let unitIndex = 0;
+      
+      while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+      }
+      
+      return `${size.toFixed(1)}${units[unitIndex]}`;
+    };
+
+    const formatTime = (seconds: number): string => {
+      if (seconds < 60) return `${seconds.toFixed(0)}s`;
+      if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${(seconds % 60).toFixed(0)}s`;
+      return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
+    };
+
+    process.stdout.write(
+      `\r${this.fileName}: ${percent}% (${formatBytes(this.processedBytes)}/${formatBytes(this.totalBytes)}) ` +
+      `[${formatBytes(rate)}/s] ETA: ${formatTime(eta)}`
+    );
+  }
+
+  /**
+   * Complete progress tracking
+   */
+  complete(): void {
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    const rate = this.processedBytes / elapsed;
+    
+    const formatBytes = (bytes: number): string => {
+      const units = ['B', 'KB', 'MB', 'GB'];
+      let size = bytes;
+      let unitIndex = 0;
+      
+      while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+      }
+      
+      return `${size.toFixed(1)}${units[unitIndex]}`;
+    };
+
+    console.log(
+      `\r${this.fileName}: 100% (${formatBytes(this.processedBytes)}) ` +
+      `[${formatBytes(rate)}/s] completed in ${elapsed.toFixed(1)}s`
+    );
+  }
+
+  /**
+   * Get current progress percentage
+   */
+  getProgressPercent(): number {
+    return Math.floor((this.processedBytes / this.totalBytes) * 100);
+  }
+
+  /**
+   * Get processing rate in bytes per second
+   */
+  getProcessingRate(): number {
+    const elapsed = (Date.now() - this.startTime) / 1000;
+    return this.processedBytes / elapsed;
+  }
+}

package/src/core/components/Support.ts

@@ -0,0 +1,77 @@
+// ======================================
+//	Support.ts
+//  A utility module for detecting platform capabilities and features
+//  Copyright (c) 2024 NeoWare, Inc. All rights reserved.
+// ======================================
+
+/**
+ * Platform and environment feature detection utility
+ * Provides boolean flags indicating support for various features needed by NeoZip
+ * 
+ * @namespace Support
+ * @property {boolean} base64 - Always true, indicates base64 encoding support
+ * @property {boolean} array - Always true, indicates Array support
+ * @property {boolean} string - Always true, indicates String support
+ * @property {boolean} isNode - True if running in Node.js environment
+ * @property {boolean} buffer - True if Node.js Buffer is available
+ * @property {boolean} uint8array - True if Uint8Array is supported
+ * @property {boolean} arrayBuffer - True if both ArrayBuffer and Uint8Array are supported
+ * @property {boolean} blob - True if Blob creation with ArrayBuffer is supported
+ * @property {boolean} streams - True if ReadableStream and WritableStream are supported
+ * @property {boolean} fileReader - True if FileReader is supported
+ */
+const Support = {
+  /** Base64 encoding support (always true) */
+  base64: true,
+  /** Array support (always true) */
+  array: true,
+  /** String support (always true) */
+  string: true,
+
+  /** 
+   * Detects if code is running in Node.js environment
+   * True if process.versions.node exists, undefined in browser
+   */
+  isNode: true,
+  
+  /**
+   * Detects if Node.js Buffer is available
+   * True in Node.js, undefined in browser
+   */
+  buffer: true,
+
+  /**
+   * Detects support for Uint8Array typed array
+   * Used for binary data handling
+   */
+  uint8array: true,
+  
+  /**
+   * Detects support for both ArrayBuffer and Uint8Array
+   * Required for binary data operations
+   */
+  arrayBuffer: typeof ArrayBuffer !== "undefined" && typeof Uint8Array !== "undefined",
+
+  /**
+   * Detects support for Blob with ArrayBuffer
+   * Tests by attempting to create an empty ZIP Blob
+   * @returns {boolean} True if Blob creation succeeds
+   */
+  blob: true,
+
+  /**
+   * Detects support for Streams API
+   * Checks for ReadableStream/WritableStream in browser
+   * or 'stream' module in Node.js
+   * @returns {boolean} True if streams are supported in current environment
+   */
+  streams: true,
+  
+  /**
+   * Detects support for FileReader
+   * @returns {boolean} True if FileReader is supported
+   */
+  fileReader: false
+};
+
+export default Support;

package/src/core/components/Util.ts

@@ -0,0 +1,91 @@
+// ======================================
+//	Util.ts
+//  Copyright (c) 2024 NeoWare, Inc. All rights reserved.
+// ======================================
+// Utility functions
+
+import Support from "./Support";
+import Errors from "../constants/Errors";
+import { TIMESTAMP_SUBMITTED, TIMESTAMP_METADATA, TOKENIZED_METADATA } from "../constants/Headers";
+
+export const DATATYPE = {
+  STRING: "string",
+  BUFFER: "buffer",
+  ARRAY: "array",
+  ARRAYBUFFER: "arraybuffer",
+  U8ARRAY: "uint8array",
+  BLOB: "blob",
+  STREAM: "stream",
+};
+
+// Parse a 64-bit unsigned integer from a buffer
+export function readBigUInt64LE(buffer: Buffer, index: number): number {
+  var buf = Buffer.from(buffer.subarray(index, index + 8));
+  buf.swap64();
+
+  return parseInt(`0x${buf.toString("hex")}`);
+};
+
+// C-style uInt32 Multiply (discards higher bits, when JS multiply discards lower bits)
+export const uMul = (a: number, b: number) => Math.imul(a, b) >>> 0;
+
+interface StreamLike {
+  on: Function;
+  pause: Function;
+  resume: Function;
+}
+
+export function isStream(obj: unknown): obj is StreamLike {
+  if (!obj || typeof obj !== 'object') return false;
+  const streamLike = obj as StreamLike;
+  return typeof streamLike.on === "function" &&
+         typeof streamLike.pause === "function" &&
+         typeof streamLike.resume === "function";
+}
+
+// Return the type of the input.
+// The type will be in a format valid for JSZip.utils.transformTo : string, array, uint8array, arraybuffer.
+// If the type is not supported, throw an exception.
+export function getTypeOf(input: string|Buffer|Blob|Array<any>|ArrayBuffer|Uint8Array): string {
+  if (typeof input === "string") {
+    if (!Support.string)
+      throw new Error(Errors.DATATYPE_STRING_UNSUPPORTED);
+    return DATATYPE.STRING;
+  }
+  else if (Object.prototype.toString.call(input) === "[object Array]") {
+    if (!Support.array)
+      throw new Error(Errors.DATATYPE_ARRAY_UNSUPPORTED);
+    return DATATYPE.ARRAY;
+  }
+  else if (Buffer.isBuffer(input)) {
+    if (!Support.buffer)
+      throw new Error(Errors.DATATYPE_BUFFER_UNSUPPORTED);
+    return DATATYPE.BUFFER;
+  }  else if (input instanceof Blob) {
+    if (!Support.blob)
+      throw new Error(Errors.DATATYPE_BLOB_UNSUPPORTED);
+    return DATATYPE.BLOB;
+  } else if (input instanceof Uint8Array) {
+    if (!Support.uint8array)
+      throw new Error(Errors.DATATYPE_U8ARRAY_UNSUPPORTED);
+    return DATATYPE.U8ARRAY;
+  }
+  else if (input instanceof ArrayBuffer) {
+    if (!Support.arrayBuffer)
+      throw new Error(Errors.DATATYPE_ARRAYBUFFER_UNSUPPORTED);
+    return DATATYPE.ARRAYBUFFER;
+  } else {  // Add an else block to handle unsupported types
+    throw new Error(Errors.DATATYPE_UNSUPPORTED);
+  }
+};
+
+/**
+ * Check if a filename is a metadata file
+ * @param filename The filename to check
+ * @returns True if the file is a metadata file (META-INF)
+ */
+export const isMetadataFile = (filename: string): boolean => {
+  return filename === TIMESTAMP_SUBMITTED || 
+         filename === TIMESTAMP_METADATA || 
+         filename === TOKENIZED_METADATA;
+};

package/src/core/constants/Errors.ts

@@ -0,0 +1,78 @@
+// ======================================
+//	Errors.ts
+//  Copyright (c) 2024 NeoWare, Inc. All rights reserved.
+// ======================================
+// Error messages
+
+export default {
+    /* Header error messages */
+    INVALID_LOC: "Invalid LOC header (bad signature)",
+    INVALID_CEN: "Invalid CEN header (bad signature)",
+    INVALID_END: "Invalid END header (bad signature)",
+
+    /* ZipEntry error messages*/
+    NO_DATA: "Nothing to decompress",
+    FILE_IN_THE_WAY: "There is a file in the way: %s",
+    UNKNOWN_METHOD: "Invalid/unsupported compression method",
+
+    /* Encryption Errors */
+    STRONG_ENCRYPT_UNSUPPORTED: "Strong Encryption is not supported",
+
+    /* Timestamp error messages */
+    INVALID_TIMESTAMP: "Invalid timestamp",
+    TIMESTAMP_FAILED: "Failed to create the timestamp",
+
+    /* Inflater error messages */
+    AVAIL_DATA: "inflate::Available inflate data did not terminate",
+    INVALID_DISTANCE: "inflate::Invalid literal/length or distance code in fixed or dynamic block",
+    TO_MANY_CODES: "inflate::Dynamic block code description: too many length or distance codes",
+    INVALID_REPEAT_LEN: "inflate::Dynamic block code description: repeat more than specified lengths",
+    INVALID_REPEAT_FIRST: "inflate::Dynamic block code description: repeat lengths with no first length",
+    INCOMPLETE_CODES: "inflate::Dynamic block code description: code lengths codes incomplete",
+    INVALID_DYN_DISTANCE: "inflate::Dynamic block code description: invalid distance code lengths",
+    INVALID_CODES_LEN: "inflate::Dynamic block code description: invalid literal/length code lengths",
+    INVALID_STORE_BLOCK: "inflate::Stored block length did not match one's complement",
+    INVALID_BLOCK_TYPE: "inflate::Invalid block type (type == 3)",
+
+    /* Extract error messages */
+    INVALID_CMP_DATA_LENGTH: "Compressed data length does not match the expected length",
+    EXTRACT_FAILED: "Failed to extract file",
+    INVALID_CRC: "CRC32 checksum does not match the expected value",
+    UNKNOWN_SHA256: "The SHA-256 hash has not been saved",
+    INVALID_SHA256: "The SHA-256 hash does not match the expected value",
+
+    /* NEO-ZIP error messages */
+    CANT_EXTRACT_FILE: "Could not extract the file",
+    CANT_OVERRIDE: "Target file already exists",
+    NO_ZIP: "No zip file was loaded",
+    NO_ENTRY: "Entry doesn't exist",
+    DIRECTORY_CONTENT_ERROR: "A directory cannot have content",
+    FILE_NOT_FOUND: "File not found: %s",
+    NOT_IMPLEMENTED: "Not implemented",
+    INVALID_FILENAME: "Invalid filename",
+    INVALID_FORMAT: "Invalid or unsupported zip format. No END header found",
+
+    // NeoZipKit error messages
+    NO_STREAM_SUPPORT: "Streams are not supported in this environment",
+    NO_BLOB_SUPPORT: "Blobs are not supported in this environment",
+    NO_FILE_READER_SUPPORT: "FileReader is not supported in this environment",
+
+    // Create Zip error messages
+    NO_FILES: "No files added, Zip file not created",
+
+    DATATYPE_STRING_UNSUPPORTED: "The String type is not supported by this platform.",
+    DATATYPE_ARRAY_UNSUPPORTED: "The Array type is not supported by this platform.",
+    DATATYPE_BUFFER_UNSUPPORTED: "The Buffer type is not supported by this platform.",
+    DATATYPE_BLOB_UNSUPPORTED: "The Blob type is not supported by this platform.",
+    DATATYPE_U8ARRAY_UNSUPPORTED: "The uint8Array type is not supported by this platform.",
+    DATATYPE_ARRAYBUFFER_UNSUPPORTED: "The ArrayBuffer type is not supported by this platform.",
+    DATATYPE_UNSUPPORTED: "Unsupported input type.",
+
+    COMPRESS_FAILED: 'Failed to compress data',
+    COMPRESSION_ERROR: 'Error occurred during compression',
+    DECOMPRESSION_ERROR: 'Error occurred during decompression',
+
+    ENCRYPT_FAILED: 'Encryption failed',
+};
+
+