docxmlater 10.1.3 → 10.1.5

package/src/utils/dateFormatting.ts

@@ -1,20 +1,20 @@
-/**
- * Date formatting utilities for OOXML XML generation
- *
- * ECMA-376 requires dates in ISO 8601 format WITHOUT milliseconds:
- *   Valid:   "2024-01-01T12:00:00Z"
- *   Invalid: "2024-01-01T12:00:00.000Z" (Word rejects milliseconds in w:date attributes)
- *
- * JavaScript's Date.toISOString() always includes milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ),
- * so we must strip the .sss portion for all w:date attributes in tracked changes.
- */
-
-/**
- * Formats a Date to ISO 8601 without milliseconds for OOXML w:date attributes.
- *
- * @param date - Date to format
- * @returns ISO 8601 date string without milliseconds (e.g., "2024-01-01T12:00:00Z")
- */
-export function formatDateForXml(date: Date): string {
-  return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
-}
+/**
+ * Date formatting utilities for OOXML XML generation
+ *
+ * ECMA-376 requires dates in ISO 8601 format WITHOUT milliseconds:
+ *   Valid:   "2024-01-01T12:00:00Z"
+ *   Invalid: "2024-01-01T12:00:00.000Z" (Word rejects milliseconds in w:date attributes)
+ *
+ * JavaScript's Date.toISOString() always includes milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ),
+ * so we must strip the .sss portion for all w:date attributes in tracked changes.
+ */
+
+/**
+ * Formats a Date to ISO 8601 without milliseconds for OOXML w:date attributes.
+ *
+ * @param date - Date to format
+ * @returns ISO 8601 date string without milliseconds (e.g., "2024-01-01T12:00:00Z")
+ */
+export function formatDateForXml(date: Date): string {
+  return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
+}

package/src/utils/deepClone.ts

@@ -1,78 +1,77 @@
-/**
- * Deep clone utility for safely cloning objects
- * More efficient and type-safe than JSON.parse(JSON.stringify())
- */
-
-/**
- * Deep clone an object using structured cloning
- * Preserves most object types including Date, RegExp, Map, Set, etc.
- *
- * For simple objects (like formatting options), this is more efficient
- * than JSON.parse(JSON.stringify()) and doesn't lose non-serializable values.
- *
- * @param obj - Object to clone
- * @returns Deep cloned copy of the object
- *
- * @example
- * ```typescript
- * const original = { bold: true, color: "FF0000", date: new Date() };
- * const cloned = deepClone(original);
- * cloned.bold = false;
- * console.log(original.bold); // true (unchanged)
- * console.log(cloned.date instanceof Date); // true (preserved)
- * ```
- */
-export function deepClone<T>(obj: T): T {
-  // Handle primitive types and null
-  if (obj === null || typeof obj !== 'object') {
-    return obj;
-  }
-
-  // Handle Date
-  if (obj instanceof Date) {
-    return new Date(obj.getTime()) as T;
-  }
-
-  // Handle Array
-  if (Array.isArray(obj)) {
-    const arrCopy: unknown[] = [];
-    for (let i = 0; i < obj.length; i++) {
-      arrCopy[i] = deepClone(obj[i]);
-    }
-    return arrCopy as T;
-  }
-
-  // Handle Map
-  if (obj instanceof Map) {
-    const mapCopy = new Map();
-    obj.forEach((value, key) => {
-      mapCopy.set(deepClone(key), deepClone(value));
-    });
-    return mapCopy as T;
-  }
-
-  // Handle Set
-  if (obj instanceof Set) {
-    const setCopy = new Set();
-    obj.forEach(value => {
-      setCopy.add(deepClone(value));
-    });
-    return setCopy as T;
-  }
-
-  // Handle RegExp
-  if (obj instanceof RegExp) {
-    return new RegExp(obj.source, obj.flags) as T;
-  }
-
-  // Handle plain objects
-  const objCopy = Object.create(Object.getPrototypeOf(obj)) as Record<string, unknown>;
-  for (const key in obj) {
-    if (obj.hasOwnProperty(key)) {
-      objCopy[key] = deepClone((obj as Record<string, unknown>)[key]);
-    }
-  }
-
-  return objCopy as T;
-}
-
+/**
+ * Deep clone utility for safely cloning objects
+ * More efficient and type-safe than JSON.parse(JSON.stringify())
+ */
+
+/**
+ * Deep clone an object using structured cloning
+ * Preserves most object types including Date, RegExp, Map, Set, etc.
+ *
+ * For simple objects (like formatting options), this is more efficient
+ * than JSON.parse(JSON.stringify()) and doesn't lose non-serializable values.
+ *
+ * @param obj - Object to clone
+ * @returns Deep cloned copy of the object
+ *
+ * @example
+ * ```typescript
+ * const original = { bold: true, color: "FF0000", date: new Date() };
+ * const cloned = deepClone(original);
+ * cloned.bold = false;
+ * console.log(original.bold); // true (unchanged)
+ * console.log(cloned.date instanceof Date); // true (preserved)
+ * ```
+ */
+export function deepClone<T>(obj: T): T {
+  // Handle primitive types and null
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  // Handle Date
+  if (obj instanceof Date) {
+    return new Date(obj.getTime()) as T;
+  }
+
+  // Handle Array
+  if (Array.isArray(obj)) {
+    const arrCopy: unknown[] = [];
+    for (let i = 0; i < obj.length; i++) {
+      arrCopy[i] = deepClone(obj[i]);
+    }
+    return arrCopy as T;
+  }
+
+  // Handle Map
+  if (obj instanceof Map) {
+    const mapCopy = new Map();
+    obj.forEach((value, key) => {
+      mapCopy.set(deepClone(key), deepClone(value));
+    });
+    return mapCopy as T;
+  }
+
+  // Handle Set
+  if (obj instanceof Set) {
+    const setCopy = new Set();
+    obj.forEach((value) => {
+      setCopy.add(deepClone(value));
+    });
+    return setCopy as T;
+  }
+
+  // Handle RegExp
+  if (obj instanceof RegExp) {
+    return new RegExp(obj.source, obj.flags) as T;
+  }
+
+  // Handle plain objects
+  const objCopy = Object.create(Object.getPrototypeOf(obj)) as Record<string, unknown>;
+  for (const key in obj) {
+    if (obj.hasOwnProperty(key)) {
+      objCopy[key] = deepClone((obj as Record<string, unknown>)[key]);
+    }
+  }
+
+  return objCopy as T;
+}

package/src/utils/diagnostics.ts

@@ -1,129 +1,125 @@
-/**
- * Diagnostic logging utilities for debugging document processing
- * @module diagnostics
- */
-
-export interface DiagnosticConfig {
-  enabled: boolean;
-  logParsing: boolean;
-  logSerialization: boolean;
-  logTextDirection: boolean;
-  verbose: boolean;
-}
-
-const defaultConfig: DiagnosticConfig = {
-  enabled: false,
-  logParsing: false,
-  logSerialization: false,
-  logTextDirection: false,
-  verbose: false,
-};
-
-let config: DiagnosticConfig = { ...defaultConfig };
-
-/**
- * Enable diagnostic logging
- */
-export function enableDiagnostics(options: Partial<DiagnosticConfig> = {}): void {
-  config = {
-    ...defaultConfig,
-    enabled: true,
-    ...options,
-  };
-}
-
-/**
- * Disable diagnostic logging
- */
-export function disableDiagnostics(): void {
-  config = { ...defaultConfig };
-}
-
-/**
- * Get current diagnostic configuration
- */
-export function getDiagnosticConfig(): DiagnosticConfig {
-  return { ...config };
-}
-
-/**
- * Log parsing activity
- */
-export function logParsing(message: string, data?: unknown): void {
-  if (config.enabled && config.logParsing) {
-    console.log(`[PARSE] ${message}`, data !== undefined ? data : '');
-  }
-}
-
-/**
- * Log serialization activity
- */
-export function logSerialization(message: string, data?: unknown): void {
-  if (config.enabled && config.logSerialization) {
-    console.log(`[SERIALIZE] ${message}`, data !== undefined ? data : '');
-  }
-}
-
-/**
- * Log text direction properties
- */
-export function logTextDirection(message: string, data?: unknown): void {
-  if (config.enabled && config.logTextDirection) {
-    console.log(`[TEXT-DIR] ${message}`, data !== undefined ? data : '');
-  }
-}
-
-/**
- * Log verbose details
- */
-export function logVerbose(message: string, data?: unknown): void {
-  if (config.enabled && config.verbose) {
-    console.log(`[VERBOSE] ${message}`, data !== undefined ? data : '');
-  }
-}
-
-/**
- * Log paragraph content summary
- */
-export function logParagraphContent(
-  source: 'parsing' | 'serialization',
-  paraIndex: number,
-  runs: { text: string; rtl?: boolean }[],
-  bidi?: boolean
-): void {
-  if (!config.enabled) return;
-
-  const logger = source === 'parsing' ? logParsing : logSerialization;
-
-  logger(`Paragraph ${paraIndex}:`);
-  logger(`  BiDi: ${bidi !== undefined ? bidi : 'not set'}`);
-  logger(`  Runs (${runs.length}):`);
-
-  runs.forEach((run, idx) => {
-    const rtlStatus = run.rtl ? ' [RTL]' : '';
-    logger(`    ${idx + 1}. "${run.text}"${rtlStatus}`);
-  });
-
-  const fullText = runs.map(r => r.text).join('');
-  logger(`  Combined text: "${fullText}"`);
-}
-
-/**
- * Compare text before and after processing
- */
-export function logTextComparison(
-  label: string,
-  before: string,
-  after: string
-): void {
-  if (!config.enabled) return;
-
-  if (before !== after) {
-    console.log(`[TEXT-CHANGE] ${label}:`);
-    console.log(`  Before: "${before}"`);
-    console.log(`  After:  "${after}"`);
-    console.log(`  MISMATCH DETECTED!`);
-  } else if (config.verbose) {
-    logVerbose(`${label}: Text preserved correctly`);
-  }
-}
+/**
+ * Diagnostic logging utilities for debugging document processing
+ * @module diagnostics
+ */
+
+export interface DiagnosticConfig {
+  enabled: boolean;
+  logParsing: boolean;
+  logSerialization: boolean;
+  logTextDirection: boolean;
+  verbose: boolean;
+}
+
+const defaultConfig: DiagnosticConfig = {
+  enabled: false,
+  logParsing: false,
+  logSerialization: false,
+  logTextDirection: false,
+  verbose: false,
+};
+
+let config: DiagnosticConfig = { ...defaultConfig };
+
+/**
+ * Enable diagnostic logging
+ */
+export function enableDiagnostics(options: Partial<DiagnosticConfig> = {}): void {
+  config = {
+    ...defaultConfig,
+    enabled: true,
+    ...options,
+  };
+}
+
+/**
+ * Disable diagnostic logging
+ */
+export function disableDiagnostics(): void {
+  config = { ...defaultConfig };
+}
+
+/**
+ * Get current diagnostic configuration
+ */
+export function getDiagnosticConfig(): DiagnosticConfig {
+  return { ...config };
+}
+
+/**
+ * Log parsing activity
+ */
+export function logParsing(message: string, data?: unknown): void {
+  if (config.enabled && config.logParsing) {
+    console.log(`[PARSE] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log serialization activity
+ */
+export function logSerialization(message: string, data?: unknown): void {
+  if (config.enabled && config.logSerialization) {
+    console.log(`[SERIALIZE] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log text direction properties
+ */
+export function logTextDirection(message: string, data?: unknown): void {
+  if (config.enabled && config.logTextDirection) {
+    console.log(`[TEXT-DIR] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log verbose details
+ */
+export function logVerbose(message: string, data?: unknown): void {
+  if (config.enabled && config.verbose) {
+    console.log(`[VERBOSE] ${message}`, data !== undefined ? data : '');
+  }
+}
+
+/**
+ * Log paragraph content summary
+ */
+export function logParagraphContent(
+  source: 'parsing' | 'serialization',
+  paraIndex: number,
+  runs: { text: string; rtl?: boolean }[],
+  bidi?: boolean
+): void {
+  if (!config.enabled) return;
+
+  const logger = source === 'parsing' ? logParsing : logSerialization;
+
+  logger(`Paragraph ${paraIndex}:`);
+  logger(`  BiDi: ${bidi !== undefined ? bidi : 'not set'}`);
+  logger(`  Runs (${runs.length}):`);
+
+  runs.forEach((run, idx) => {
+    const rtlStatus = run.rtl ? ' [RTL]' : '';
+    logger(`    ${idx + 1}. "${run.text}"${rtlStatus}`);
+  });
+
+  const fullText = runs.map((r) => r.text).join('');
+  logger(`  Combined text: "${fullText}"`);
+}
+
+/**
+ * Compare text before and after processing
+ */
+export function logTextComparison(label: string, before: string, after: string): void {
+  if (!config.enabled) return;
+
+  if (before !== after) {
+    console.log(`[TEXT-CHANGE] ${label}:`);
+    console.log(`  Before: "${before}"`);
+    console.log(`  After:  "${after}"`);
+    console.log(`  MISMATCH DETECTED!`);
+  } else if (config.verbose) {
+    logVerbose(`${label}: Text preserved correctly`);
+  }
+}

package/src/utils/errorHandling.ts

@@ -1,80 +1,80 @@
-/**
- * Error handling utilities for consistent error processing
- * Ensures all caught errors are properly typed and handled
- */
-
-/**
- * Type guard to check if a value is an Error object
- * @param error - The value to check
- * @returns True if the value is an Error instance
- */
-export function isError(error: unknown): error is Error {
-  return error instanceof Error;
-}
-
-/**
- * Converts unknown error to Error object
- * Ensures we always have a proper Error with message property
- * @param error - The error to normalize (can be anything)
- * @returns Normalized Error object
- */
-export function toError(error: unknown): Error {
-  if (isError(error)) {
-    return error;
-  }
-
-  // Handle string errors
-  if (typeof error === 'string') {
-    return new Error(error);
-  }
-
-  // Handle objects with message property
-  if (error && typeof error === 'object' && 'message' in error) {
-    return new Error(String(error.message));
-  }
-
-  // Fallback for any other type
-  return new Error(String(error));
-}
-
-/**
- * Wraps an error with additional context
- * Useful for adding file paths, operation names, etc.
- * @param error - The original error
- * @param context - Additional context to prepend to error message
- * @returns New Error with combined message and original stack
- */
-export function wrapError(error: unknown, context: string): Error {
-  const originalError = toError(error);
-  const wrappedError = new Error(`${context}: ${originalError.message}`);
-
-  // Preserve original stack trace if available
-  if (originalError.stack) {
-    wrappedError.stack = `${wrappedError.message}\nCaused by: ${originalError.stack}`;
-  }
-
-  return wrappedError;
-}
-
-/**
- * Safe error message extraction
- * Returns error message or generic fallback
- * @param error - The error to extract message from
- * @param fallback - Fallback message if extraction fails
- * @returns Error message string
- */
-export function getErrorMessage(error: unknown, fallback = 'Unknown error occurred'): string {
-  if (isError(error)) {
-    return error.message;
-  }
-
-  if (typeof error === 'string') {
-    return error;
-  }
-
-  if (error && typeof error === 'object' && 'message' in error) {
-    return String(error.message);
-  }
-
-  return fallback;
-}
+/**
+ * Error handling utilities for consistent error processing
+ * Ensures all caught errors are properly typed and handled
+ */
+
+/**
+ * Type guard to check if a value is an Error object
+ * @param error - The value to check
+ * @returns True if the value is an Error instance
+ */
+export function isError(error: unknown): error is Error {
+  return error instanceof Error;
+}
+
+/**
+ * Converts unknown error to Error object
+ * Ensures we always have a proper Error with message property
+ * @param error - The error to normalize (can be anything)
+ * @returns Normalized Error object
+ */
+export function toError(error: unknown): Error {
+  if (isError(error)) {
+    return error;
+  }
+
+  // Handle string errors
+  if (typeof error === 'string') {
+    return new Error(error);
+  }
+
+  // Handle objects with message property
+  if (error && typeof error === 'object' && 'message' in error) {
+    return new Error(String(error.message));
+  }
+
+  // Fallback for any other type
+  return new Error(String(error));
+}
+
+/**
+ * Wraps an error with additional context
+ * Useful for adding file paths, operation names, etc.
+ * @param error - The original error
+ * @param context - Additional context to prepend to error message
+ * @returns New Error with combined message and original stack
+ */
+export function wrapError(error: unknown, context: string): Error {
+  const originalError = toError(error);
+  const wrappedError = new Error(`${context}: ${originalError.message}`);
+
+  // Preserve original stack trace if available
+  if (originalError.stack) {
+    wrappedError.stack = `${wrappedError.message}\nCaused by: ${originalError.stack}`;
+  }
+
+  return wrappedError;
+}
+
+/**
+ * Safe error message extraction
+ * Returns error message or generic fallback
+ * @param error - The error to extract message from
+ * @param fallback - Fallback message if extraction fails
+ * @returns Error message string
+ */
+export function getErrorMessage(error: unknown, fallback = 'Unknown error occurred'): string {
+  if (isError(error)) {
+    return error.message;
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String(error.message);
+  }
+
+  return fallback;
+}