docxmlater 10.0.2 → 10.0.4

package/src/utils/logger.ts

@@ -0,0 +1,404 @@
+/**
+ * Logging interface for docXMLater
+ * Allows library consumers to control logging behavior
+ */
+
+/**
+ * Log severity levels
+ */
+export enum LogLevel {
+  /** Debugging information (most verbose) */
+  DEBUG = 'debug',
+  /** Informational messages */
+  INFO = 'info',
+  /** Warning messages - potential issues that don't prevent operation */
+  WARN = 'warn',
+  /** Error messages - serious issues that may cause failures */
+  ERROR = 'error',
+}
+
+/**
+ * Log entry structure
+ */
+export interface LogEntry {
+  /** Timestamp when log was created */
+  timestamp: Date;
+  /** Severity level */
+  level: LogLevel;
+  /** Log message */
+  message: string;
+  /** Optional context data */
+  context?: Record<string, any>;
+  /** Source component that generated the log */
+  source?: string;
+}
+
+/**
+ * Logger interface that consumers can implement
+ * Provides full control over how logs are handled
+ */
+export interface ILogger {
+  /**
+   * Log a debug message
+   * @param message - Debug message
+   * @param context - Optional context data
+   */
+  debug(message: string, context?: Record<string, any>): void;
+
+  /**
+   * Log an informational message
+   * @param message - Info message
+   * @param context - Optional context data
+   */
+  info(message: string, context?: Record<string, any>): void;
+
+  /**
+   * Log a warning message
+   * @param message - Warning message
+   * @param context - Optional context data
+   */
+  warn(message: string, context?: Record<string, any>): void;
+
+  /**
+   * Log an error message
+   * @param message - Error message
+   * @param context - Optional context data
+   */
+  error(message: string, context?: Record<string, any>): void;
+}
+
+/**
+ * Console-based logger implementation
+ * Uses standard console methods for output with timestamps and source prefixes
+ */
+export class ConsoleLogger implements ILogger {
+  private showTimestamp: boolean;
+
+  constructor(private minLevel: LogLevel = LogLevel.WARN, options?: { showTimestamp?: boolean }) {
+    this.showTimestamp = options?.showTimestamp ?? true;
+  }
+
+  debug(message: string, context?: Record<string, any>): void {
+    if (this.shouldLog(LogLevel.DEBUG)) {
+      console.debug(this.formatMessage(LogLevel.DEBUG, message, context));
+    }
+  }
+
+  info(message: string, context?: Record<string, any>): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      console.info(this.formatMessage(LogLevel.INFO, message, context));
+    }
+  }
+
+  warn(message: string, context?: Record<string, any>): void {
+    if (this.shouldLog(LogLevel.WARN)) {
+      console.warn(this.formatMessage(LogLevel.WARN, message, context));
+    }
+  }
+
+  error(message: string, context?: Record<string, any>): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      console.error(this.formatMessage(LogLevel.ERROR, message, context));
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];
+    const minIndex = levels.indexOf(this.minLevel);
+    const currentIndex = levels.indexOf(level);
+    return currentIndex >= minIndex;
+  }
+
+  private formatMessage(level: LogLevel, message: string, context?: Record<string, any>): string {
+    const parts: string[] = [];
+
+    // Add timestamp if enabled
+    if (this.showTimestamp) {
+      const timestamp = new Date().toISOString().slice(11, 23); // HH:mm:ss.SSS
+      parts.push(timestamp);
+    }
+
+    // Add level tag
+    parts.push(`[${level.toUpperCase().padEnd(5)}]`);
+
+    // Add source if present
+    if (context?.source) {
+      parts.push(`[${context.source}]`);
+    }
+
+    // Add message
+    parts.push(message);
+
+    // Add context (excluding source which is already shown)
+    if (context && Object.keys(context).length > 0) {
+      const contextWithoutSource = { ...context };
+      delete contextWithoutSource.source;
+      if (Object.keys(contextWithoutSource).length > 0) {
+        // Format context as key=value pairs for readability
+        const contextStr = this.formatContext(contextWithoutSource);
+        if (contextStr) {
+          parts.push(contextStr);
+        }
+      }
+    }
+
+    return parts.join(' ');
+  }
+
+  private formatContext(context: Record<string, any>): string {
+    const pairs: string[] = [];
+    for (const [key, value] of Object.entries(context)) {
+      if (value === undefined || value === null) continue;
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        // Nested object - use compact JSON
+        pairs.push(`${key}=${JSON.stringify(value)}`);
+      } else if (Array.isArray(value)) {
+        pairs.push(`${key}=[${value.length}]`);
+      } else {
+        pairs.push(`${key}=${value}`);
+      }
+    }
+    return pairs.length > 0 ? pairs.join(' ') : '';
+  }
+}
+
+/**
+ * Silent logger that discards all log messages
+ * Useful for testing or when logging is not desired
+ */
+export class SilentLogger implements ILogger {
+  debug(): void {
+    // No-op
+  }
+
+  info(): void {
+    // No-op
+  }
+
+  warn(): void {
+    // No-op
+  }
+
+  error(): void {
+    // No-op
+  }
+}
+
+/**
+ * Collecting logger that stores log entries in memory
+ * Useful for testing and diagnostics
+ */
+export class CollectingLogger implements ILogger {
+  private logs: LogEntry[] = [];
+
+  debug(message: string, context?: Record<string, any>): void {
+    this.addLog(LogLevel.DEBUG, message, context);
+  }
+
+  info(message: string, context?: Record<string, any>): void {
+    this.addLog(LogLevel.INFO, message, context);
+  }
+
+  warn(message: string, context?: Record<string, any>): void {
+    this.addLog(LogLevel.WARN, message, context);
+  }
+
+  error(message: string, context?: Record<string, any>): void {
+    this.addLog(LogLevel.ERROR, message, context);
+  }
+
+  private addLog(level: LogLevel, message: string, context?: Record<string, any>): void {
+    this.logs.push({
+      timestamp: new Date(),
+      level,
+      message,
+      context,
+    });
+  }
+
+  /**
+   * Get all collected log entries
+   */
+  getLogs(): readonly LogEntry[] {
+    return [...this.logs];
+  }
+
+  /**
+   * Get logs filtered by level
+   */
+  getLogsByLevel(level: LogLevel): readonly LogEntry[] {
+    return this.logs.filter(log => log.level === level);
+  }
+
+  /**
+   * Clear all collected logs
+   */
+  clear(): void {
+    this.logs = [];
+  }
+
+  /**
+   * Get count of logs by level
+   */
+  getCount(level?: LogLevel): number {
+    if (level) {
+      return this.logs.filter(log => log.level === level).length;
+    }
+    return this.logs.length;
+  }
+}
+
+/**
+ * Default logger instance
+ * Delegates to the global logger, respecting setGlobalLogger() and environment variables
+ */
+export const defaultLogger: ILogger = {
+  debug(message: string, context?: Record<string, any>): void {
+    getGlobalLogger().debug(message, context);
+  },
+  info(message: string, context?: Record<string, any>): void {
+    getGlobalLogger().info(message, context);
+  },
+  warn(message: string, context?: Record<string, any>): void {
+    getGlobalLogger().warn(message, context);
+  },
+  error(message: string, context?: Record<string, any>): void {
+    getGlobalLogger().error(message, context);
+  },
+};
+
+/**
+ * Creates a scoped logger that adds source information
+ * @param logger - Base logger
+ * @param source - Source component name
+ * @returns Scoped logger with source context
+ */
+export function createScopedLogger(logger: ILogger, source: string): ILogger {
+  return {
+    debug(message: string, context?: Record<string, any>): void {
+      logger.debug(message, { ...context, source });
+    },
+    info(message: string, context?: Record<string, any>): void {
+      logger.info(message, { ...context, source });
+    },
+    warn(message: string, context?: Record<string, any>): void {
+      logger.warn(message, { ...context, source });
+    },
+    error(message: string, context?: Record<string, any>): void {
+      logger.error(message, { ...context, source });
+    },
+  };
+}
+
+/**
+ * Parse log level from string
+ * @param level - Log level string (case-insensitive)
+ * @returns LogLevel or undefined if invalid
+ */
+function parseLogLevel(level: string | undefined): LogLevel | undefined {
+  if (!level) return undefined;
+  const normalized = level.toLowerCase();
+  switch (normalized) {
+    case 'debug': return LogLevel.DEBUG;
+    case 'info': return LogLevel.INFO;
+    case 'warn': return LogLevel.WARN;
+    case 'error': return LogLevel.ERROR;
+    default: return undefined;
+  }
+}
+
+/**
+ * Create a logger based on environment variables
+ *
+ * Environment variables (in order of precedence):
+ * - DEBUG=docxmlater or DEBUG=docxmlater:* - Enables DEBUG level
+ * - DOCXMLATER_LOG_LEVEL=debug|info|warn|error|silent - Sets specific level
+ *
+ * @returns Logger configured from environment, or SilentLogger if not configured
+ */
+function createLoggerFromEnv(): ILogger {
+  // Check DEBUG environment variable first (highest precedence for debug mode)
+  const debugEnv = process.env.DEBUG || '';
+  if (debugEnv.includes('docxmlater')) {
+    return new ConsoleLogger(LogLevel.DEBUG);
+  }
+
+  // Check DOCXMLATER_LOG_LEVEL environment variable
+  const envLevel = process.env.DOCXMLATER_LOG_LEVEL?.toLowerCase();
+  if (envLevel === 'silent') {
+    return new SilentLogger();
+  }
+
+  const parsedLevel = parseLogLevel(envLevel);
+  if (parsedLevel) {
+    return new ConsoleLogger(parsedLevel);
+  }
+
+  // Default: silent (no logging unless explicitly enabled)
+  return new SilentLogger();
+}
+
+// Global logger instance - initialized from environment
+let globalLogger: ILogger = createLoggerFromEnv();
+
+/**
+ * Set the global logger instance
+ * Use this to configure logging programmatically
+ *
+ * @example
+ * ```typescript
+ * import { setGlobalLogger, ConsoleLogger, LogLevel } from 'docxmlater';
+ *
+ * // Enable info-level logging
+ * setGlobalLogger(new ConsoleLogger(LogLevel.INFO));
+ * ```
+ *
+ * @param logger - Logger instance to use globally
+ */
+export function setGlobalLogger(logger: ILogger): void {
+  globalLogger = logger;
+}
+
+/**
+ * Get the global logger instance
+ * Used internally by framework components
+ *
+ * @returns Current global logger
+ */
+export function getGlobalLogger(): ILogger {
+  return globalLogger;
+}
+
+/**
+ * Reset the global logger to its default (environment-based) configuration
+ * Useful for testing cleanup
+ */
+export function resetGlobalLogger(): void {
+  globalLogger = createLoggerFromEnv();
+}
+
+/**
+ * Creates a component-scoped logger using the global logger.
+ * This is a convenience function that combines getGlobalLogger() and createScopedLogger()
+ * into a single call, reducing boilerplate in component files.
+ *
+ * @param componentName - Name of the component (appears in log output)
+ * @returns Scoped logger instance
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * function getLogger(): ILogger {
+ *   return createScopedLogger(getGlobalLogger(), 'MyComponent');
+ * }
+ *
+ * // You can use:
+ * const logger = createComponentLogger('MyComponent');
+ *
+ * // Or for lazy initialization:
+ * const getLogger = () => createComponentLogger('MyComponent');
+ * ```
+ */
+export function createComponentLogger(componentName: string): ILogger {
+  return createScopedLogger(getGlobalLogger(), componentName);
+}

package/src/utils/parsingHelpers.ts

@@ -0,0 +1,190 @@
+/**
+ * Parsing Helper Functions
+ *
+ * Utility functions for safely parsing OOXML values from XML attributes.
+ * These helpers address common parsing issues:
+ * - Zero-value handling (0 should not be treated as falsy)
+ * - NaN validation (malformed values should fall back to defaults)
+ * - ECMA-376 boolean parsing (self-closing tags, val="1", val="true")
+ *
+ * @see https://ecma-international.org/publications-and-standards/standards/ecma-376/
+ */
+
+/**
+ * Safely parse an integer value with NaN handling.
+ *
+ * Addresses the issue where parseInt() can return NaN for malformed input,
+ * which then propagates through the document model causing issues.
+ *
+ * @param value - The value to parse (string, number, or any)
+ * @param defaultValue - Default value if parsing fails (default: 0)
+ * @returns Parsed integer or default value
+ *
+ * @example
+ * safeParseInt("42")      // 42
+ * safeParseInt("invalid") // 0
+ * safeParseInt(undefined) // 0
+ * safeParseInt("", 100)   // 100
+ */
+export function safeParseInt(value: unknown, defaultValue = 0): number {
+  if (value === undefined || value === null) {
+    return defaultValue;
+  }
+
+  // If already a number, return it (handle NaN case)
+  if (typeof value === 'number') {
+    return isNaN(value) ? defaultValue : Math.floor(value);
+  }
+
+  const parsed = parseInt(String(value), 10);
+  return isNaN(parsed) ? defaultValue : parsed;
+}
+
+/**
+ * Parse OOXML boolean value per ECMA-376 specification.
+ *
+ * OOXML boolean properties follow these rules:
+ * - Self-closing tag `<w:bold/>` (no w:val attribute) = true
+ * - `<w:bold w:val="1"/>` = true
+ * - `<w:bold w:val="true"/>` = true
+ * - `<w:bold w:val="on"/>` = true
+ * - `<w:bold w:val="0"/>` = false
+ * - `<w:bold w:val="false"/>` = false
+ * - `<w:bold w:val="off"/>` = false
+ * - Absent element = false (handled by caller checking for property existence)
+ *
+ * @param prop - The parsed XML property object (e.g., pPrObj["w:bold"])
+ * @returns Boolean value
+ *
+ * @example
+ * // For XML: <w:bold/>
+ * parseOoxmlBoolean({}) // true (self-closing, no @_w:val)
+ *
+ * // For XML: <w:bold w:val="1"/>
+ * parseOoxmlBoolean({ "@_w:val": "1" }) // true
+ *
+ * // For XML: <w:bold w:val="0"/>
+ * parseOoxmlBoolean({ "@_w:val": "0" }) // false
+ *
+ * // For absent element
+ * parseOoxmlBoolean(undefined) // false
+ */
+export function parseOoxmlBoolean(prop: unknown): boolean {
+  // Absent element = false
+  if (!prop) {
+    return false;
+  }
+
+  // Get the w:val attribute value
+  const val = (prop as Record<string, unknown>)['@_w:val'];
+
+  // Self-closing tag without w:val attribute = true
+  // Per ECMA-376, presence of element without val means "on"
+  if (val === undefined) {
+    return true;
+  }
+
+  // Handle string values
+  if (typeof val === 'string') {
+    const lowerVal = val.toLowerCase();
+    return lowerVal === '1' || lowerVal === 'true' || lowerVal === 'on';
+  }
+
+  // Handle numeric values
+  if (typeof val === 'number') {
+    return val === 1;
+  }
+
+  // Handle boolean values (already parsed by XML parser)
+  if (typeof val === 'boolean') {
+    return val;
+  }
+
+  // Unknown type - default to false
+  return false;
+}
+
+/**
+ * Check if a value is explicitly set (not undefined or null).
+ *
+ * This helper addresses the zero-value handling bug where truthy checks
+ * incorrectly treat 0 as falsy:
+ *
+ * ```typescript
+ * // WRONG - treats 0 as falsy
+ * const width = val ? parseInt(val) : defaultWidth;
+ *
+ * // CORRECT - only checks for undefined/null
+ * const width = isExplicitlySet(val) ? parseInt(val) : defaultWidth;
+ * ```
+ *
+ * @param value - The value to check
+ * @returns true if value is not undefined and not null
+ *
+ * @example
+ * isExplicitlySet(0)         // true
+ * isExplicitlySet("")        // true
+ * isExplicitlySet(false)     // true
+ * isExplicitlySet(undefined) // false
+ * isExplicitlySet(null)      // false
+ */
+export function isExplicitlySet(value: unknown): boolean {
+  return value !== undefined && value !== null;
+}
+
+/**
+ * Parse an OOXML numeric attribute with proper handling of zero values.
+ *
+ * Combines isExplicitlySet() and safeParseInt() for common use case
+ * of parsing numeric attributes from XML.
+ *
+ * @param value - The attribute value to parse
+ * @param defaultValue - Default value if attribute is not set
+ * @returns Parsed integer or default value
+ *
+ * @example
+ * parseNumericAttribute("100", 50)    // 100
+ * parseNumericAttribute("0", 50)      // 0 (not 50!)
+ * parseNumericAttribute(undefined, 50) // 50
+ * parseNumericAttribute("invalid", 50) // 50
+ */
+export function parseNumericAttribute(value: unknown, defaultValue: number): number {
+  if (!isExplicitlySet(value)) {
+    return defaultValue;
+  }
+  return safeParseInt(value, defaultValue);
+}
+
+/**
+ * Parse OOXML "on/off" attribute (ST_OnOff type).
+ *
+ * Some OOXML attributes use the ST_OnOff simple type which can be:
+ * - "on", "1", "true" = true
+ * - "off", "0", "false" = false
+ *
+ * This is similar to parseOoxmlBoolean but works on attribute values directly.
+ *
+ * @param value - The attribute value
+ * @param defaultValue - Default if value is not set
+ * @returns Boolean value
+ */
+export function parseOnOffAttribute(value: unknown, defaultValue = false): boolean {
+  if (!isExplicitlySet(value)) {
+    return defaultValue;
+  }
+
+  if (typeof value === 'string') {
+    const lowerVal = value.toLowerCase();
+    return lowerVal === '1' || lowerVal === 'true' || lowerVal === 'on';
+  }
+
+  if (typeof value === 'number') {
+    return value === 1;
+  }
+
+  if (typeof value === 'boolean') {
+    return value;
+  }
+
+  return defaultValue;
+}