@hivellm/transmutation-lite
Version:
Simplified document converter for common formats (PDF, DOCX, XLSX, PPTX) to Markdown
383 lines (377 loc) • 8.93 kB
TypeScript
/**
* Metrics and monitoring for production use
*/
interface ConversionMetrics {
totalConversions: number;
successfulConversions: number;
failedConversions: number;
totalBytesProcessed: number;
totalTimeMs: number;
cacheHits: number;
cacheMisses: number;
errorsByType: Map<string, number>;
conversionsByFormat: Map<string, number>;
}
/**
* Metrics collector for monitoring converter performance
*/
declare class MetricsCollector {
private metrics;
private startTime;
constructor();
/**
* Record a successful conversion
*/
recordSuccess(format: string, bytes: number, timeMs: number, fromCache: boolean): void;
/**
* Record a failed conversion
*/
recordFailure(format: string, errorType: string): void;
/**
* Get current metrics
*/
getMetrics(): ConversionMetrics;
/**
* Get metrics summary
*/
getSummary(): {
uptime: number;
successRate: number;
cacheHitRate: number;
avgConversionTime: number;
avgThroughput: number;
};
/**
* Reset all metrics
*/
reset(): void;
/**
* Export metrics as JSON
*/
toJSON(): any;
}
/**
* Supported document formats
*/
declare enum DocumentFormat {
PDF = "pdf",
DOCX = "docx",
XLSX = "xlsx",
PPTX = "pptx",
TXT = "txt",
HTML = "html",
UNKNOWN = "unknown"
}
/**
* Conversion options
*/
interface ConversionOptions {
/**
* Preserve original formatting where possible
* @default true
*/
preserveFormatting?: boolean;
/**
* Extract images (not implemented in lite version)
* @default false
*/
extractImages?: boolean;
/**
* Maximum page/sheet to process (0 = all)
* @default 0
*/
maxPages?: number;
/**
* Custom output format options
*/
formatOptions?: Record<string, any>;
}
/**
* Metadata about the converted document
*/
interface DocumentMetadata {
/**
* Original file format
*/
format: DocumentFormat;
/**
* File size in bytes
*/
fileSize: number;
/**
* Number of pages/sheets/slides
*/
pageCount?: number;
/**
* Document title (if available)
*/
title?: string;
/**
* Document author (if available)
*/
author?: string;
/**
* Creation date (if available)
*/
createdAt?: Date;
/**
* Additional format-specific metadata
*/
extra?: Record<string, any>;
}
/**
* Result of a document conversion
*/
interface ConversionResult {
/**
* Converted markdown content
*/
markdown: string;
/**
* Document metadata
*/
metadata: DocumentMetadata;
/**
* Conversion time in milliseconds
*/
conversionTimeMs: number;
/**
* Any warnings during conversion
*/
warnings?: string[];
}
/**
* Converter error class
*/
declare class ConversionError extends Error {
format?: DocumentFormat | undefined;
cause?: Error | undefined;
constructor(message: string, format?: DocumentFormat | undefined, cause?: Error | undefined);
}
/**
* Simple logging utility for Transmutation Lite
*/
declare enum LogLevel {
DEBUG = 0,
INFO = 1,
WARN = 2,
ERROR = 3,
NONE = 4
}
interface LoggerOptions {
level?: LogLevel;
prefix?: string;
timestamps?: boolean;
}
/**
* Logger class for debugging and monitoring
*/
declare class Logger {
private level;
private prefix;
private timestamps;
constructor(options?: LoggerOptions);
/**
* Set logging level
*/
setLevel(level: LogLevel): void;
/**
* Get current logging level
*/
getLevel(): LogLevel;
/**
* Format log message with prefix and timestamp
*/
private format;
/**
* Log debug message
*/
debug(message: string, ...args: any[]): void;
/**
* Log info message
*/
info(message: string, ...args: any[]): void;
/**
* Log warning message
*/
warn(message: string, ...args: any[]): void;
/**
* Log error message
*/
error(message: string, error?: Error, ...args: any[]): void;
/**
* Create a child logger with a different prefix
*/
child(prefix: string): Logger;
}
/**
* LRU Cache for conversion results
*
* Caches conversion results to avoid re-processing identical documents.
* Uses content hash as key to ensure cache validity.
*/
declare class ConversionCache {
private cache;
private maxSize;
private maxAge;
/**
* Create a new conversion cache
*
* @param maxSize Maximum number of entries (default: 100)
* @param maxAge Maximum age in milliseconds (default: 1 hour)
*/
constructor(maxSize?: number, maxAge?: number);
/**
* Generate a cache key from buffer content
*/
private generateKey;
/**
* Get cached result
*/
get(buffer: Buffer, format: string): ConversionResult | null;
/**
* Store result in cache
*/
set(buffer: Buffer, format: string, result: ConversionResult): void;
/**
* Check if result is cached
*/
has(buffer: Buffer, format: string): boolean;
/**
* Clear all cache entries
*/
clear(): void;
/**
* Clear expired entries
*/
clearExpired(): void;
/**
* Get cache statistics
*/
getStats(): {
size: number;
maxSize: number;
hitRate: number;
totalHits: number;
};
/**
* Get cache size in bytes (approximate)
*/
getMemoryUsage(): number;
}
/**
* Configuration options for the Converter
*/
interface ConverterConfig {
/**
* Enable caching of conversion results (default: false)
*/
enableCache?: boolean;
/**
* Maximum number of cached results (default: 100)
*/
cacheSize?: number;
/**
* Maximum age of cached results in milliseconds (default: 1 hour)
*/
cacheMaxAge?: number;
/**
* Logger instance for debugging (optional)
*/
logger?: Logger;
/**
* Enable input validation (default: true)
*/
validateInput?: boolean;
/**
* Enable metrics collection (default: false)
*/
collectMetrics?: boolean;
}
/**
* Main converter class that manages all format converters
*/
declare class Converter {
private converters;
private cache?;
private logger;
private validateInput;
private metrics?;
constructor(config?: ConverterConfig);
/**
* Register a converter
*/
private registerConverter;
/**
* Detect file format from extension
*/
detectFormat(filePath: string): DocumentFormat;
/**
* Get converter for a specific format
*/
private getConverter;
/**
* Convert a file buffer to markdown
*/
convertBuffer(buffer: Buffer, format: DocumentFormat, options?: ConversionOptions): Promise<ConversionResult>;
/**
* Convert a file to markdown
*/
convertFile(filePath: string, options?: ConversionOptions): Promise<ConversionResult>;
/**
* Get list of supported formats
*/
getSupportedFormats(): DocumentFormat[];
/**
* Check if a file format is supported
*/
isSupported(filePath: string): boolean;
/**
* Clear the conversion cache
*/
clearCache(): void;
/**
* Get cache statistics (if caching is enabled)
*/
getCacheStats(): {
size: number;
maxSize: number;
hitRate: number;
totalHits: number;
} | undefined;
/**
* Get cache memory usage in bytes (if caching is enabled)
*/
getCacheMemoryUsage(): number;
/**
* Get conversion metrics (if metrics collection is enabled)
*/
getMetrics(): ConversionMetrics | undefined;
/**
* Get metrics summary (if metrics collection is enabled)
*/
getMetricsSummary(): {
uptime: number;
successRate: number;
cacheHitRate: number;
avgConversionTime: number;
avgThroughput: number;
} | undefined;
/**
* Reset metrics (if metrics collection is enabled)
*/
resetMetrics(): void;
/**
* Export metrics as JSON (if metrics collection is enabled)
*/
exportMetrics(): any;
}
/**
* Convenience function to convert a file
*/
declare function convert(filePath: string, options?: ConversionOptions): Promise<ConversionResult>;
/**
* Convenience function to convert a buffer
*/
declare function convertBuffer(buffer: Buffer, format: DocumentFormat, options?: ConversionOptions): Promise<ConversionResult>;
export { ConversionCache, ConversionError, type ConversionMetrics, type ConversionOptions, type ConversionResult, Converter, type ConverterConfig, DocumentFormat, type DocumentMetadata, LogLevel, Logger, MetricsCollector, convert, convertBuffer };