legal-markdown-js/dist/extensions/batch-processor.d.ts

Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version

/**
 * Batch Processing Module for Legal Markdown Documents
 *
 * This module provides functionality for processing multiple Legal Markdown files
 * in batch operations. It supports recursive directory processing, concurrent
 * file operations, progress tracking, and error handling.
 *
 * Features:
 * - Batch processing of multiple Legal Markdown files
 * - Recursive directory traversal with pattern matching
 * - Concurrent processing with configurable concurrency limits
 * - Progress tracking and error reporting callbacks
 * - Directory structure preservation in output
 * - File extension filtering and exclusion patterns
 * - Metadata export support for batch operations
 * - Statistics and performance tracking
 *
 * @example
 * ```typescript
 * import { processBatch } from './batch-processor';
 *
 * // Basic batch processing
 * const result = await processBatch({
 *   inputDir: './legal-docs',
 *   outputDir: './output',
 *   extensions: ['.md'],
 *   recursive: true
 * });
 *
 * // Advanced batch processing with callbacks
 * const result = await processBatch({
 *   inputDir: './contracts',
 *   outputDir: './processed-contracts',
 *   extensions: ['.md', '.txt'],
 *   recursive: true,
 *   concurrency: 3,
 *   exclude: ['temp', 'backup'],
 *   onProgress: (processed, total, currentFile) => {
 *     console.log(`Progress: ${processed}/${total} - ${currentFile}`);
 *   },
 *   onError: (file, error) => {
 *     console.error(`Error processing ${file}:`, error.message);
 *   }
 * });
 * ```
 *
 * @module
 */
import { LegalMarkdownOptions } from '../types';
/**
 * Configuration options for batch processing operations
 *
 * Extends LegalMarkdownOptions to include batch-specific settings like
 * directory paths, concurrency control, and progress callbacks.
 *
 * @interface BatchProcessingOptions
 * @extends {LegalMarkdownOptions}
 * @example
 * ```typescript
 * const options: BatchProcessingOptions = {
 *   inputDir: './legal-documents',
 *   outputDir: './processed-documents',
 *   extensions: ['.md', '.txt'],
 *   recursive: true,
 *   preserveStructure: true,
 *   exclude: ['temp', 'backup'],
 *   concurrency: 5,
 *   onProgress: (processed, total, currentFile) => {
 *     console.log(`Processing: ${currentFile} (${processed}/${total})`);
 *   }
 * };
 * ```
 */
export interface BatchProcessingOptions extends LegalMarkdownOptions {
    /** Input directory containing files to process */
    inputDir: string;
    /** Output directory for processed files */
    outputDir: string;
    /** File extensions to process (defaults to ['.md', '.txt']) */
    extensions?: string[];
    /** Whether to process subdirectories recursively */
    recursive?: boolean;
    /** Whether to preserve directory structure in output */
    preserveStructure?: boolean;
    /** Pattern to exclude files/directories */
    exclude?: string[];
    /** Maximum number of concurrent file processing operations */
    concurrency?: number;
    /** Callback for progress updates during batch processing */
    onProgress?: (processed: number, total: number, currentFile: string) => void;
    /** Callback for handling errors during file processing */
    onError?: (file: string, error: Error) => void;
}
/**
 * Result of batch processing operation
 *
 * Contains statistics and details about the batch processing operation,
 * including success/failure counts, file lists, and timing information.
 *
 * @interface BatchProcessingResult
 * @example
 * ```typescript
 * const result = await processBatch(options);
 *
 * console.log(`Successfully processed: ${result.totalProcessed} files`);
 * console.log(`Failed: ${result.totalErrors} files`);
 * console.log(`Processing time: ${result.processingTime}ms`);
 *
 * // List failed files
 * result.failedFiles.forEach(({ file, error }) => {
 *   console.error(`Failed to process ${file}: ${error}`);
 * });
 * ```
 */
export interface BatchProcessingResult {
    /** Total number of files successfully processed */
    totalProcessed: number;
    /** Number of files that failed processing */
    totalErrors: number;
    /** List of successfully processed file paths */
    successfulFiles: string[];
    /** List of failed files with error messages */
    failedFiles: Array<{
        file: string;
        error: string;
    }>;
    /** Total processing time in milliseconds */
    processingTime: number;
}
/**
 * Processes multiple legal markdown files in batch
 *
 * This function performs batch processing of Legal Markdown files with support
 * for recursive directory traversal, concurrent processing, and progress tracking.
 * It automatically handles file discovery, directory creation, and error management.
 *
 * @function processBatch
 * @param {BatchProcessingOptions} options - Configuration options for batch processing
 * @returns {Promise<BatchProcessingResult>} A promise that resolves to the processing result
 * @throws {Error} When input directory doesn't exist or other setup errors occur
 * @example
 * ```typescript
 * import { processBatch } from './batch-processor';
 *
 * // Process all .md files in a directory
 * const result = await processBatch({
 *   inputDir: './legal-documents',
 *   outputDir: './processed-documents',
 *   extensions: ['.md'],
 *   recursive: true,
 *   preserveStructure: true,
 *   concurrency: 3,
 *   onProgress: (processed, total, currentFile) => {
 *     console.log(`Progress: ${processed}/${total} - ${path.basename(currentFile)}`);
 *   },
 *   onError: (file, error) => {
 *     console.error(`Error processing ${file}:`, error.message);
 *   }
 * });
 *
 * console.log(`Processed ${result.totalProcessed} files successfully`);
 * console.log(`${result.totalErrors} files failed processing`);
 * ```
 */
export declare function processBatch(options: BatchProcessingOptions): Promise<BatchProcessingResult>;
/**
 * Utility function to get processing statistics from batch processing results
 *
 * Calculates useful statistics about the batch processing operation including
 * success rate, average processing time per file, and throughput metrics.
 *
 * @function getProcessingStats
 * @param {BatchProcessingResult} result - The batch processing result to analyze
 * @returns {Object} Object containing processing statistics
 * @returns {number} returns.successRate - Success rate as a percentage (0-100)
 * @returns {number} returns.averageTimePerFile - Average processing time per file in milliseconds
 * @returns {number} returns.filesPerSecond - Processing throughput in files per second
 * @example
 * ```typescript
 * import { processBatch, getProcessingStats } from './batch-processor';
 *
 * const result = await processBatch({
 *   inputDir: './documents',
 *   outputDir: './output'
 * });
 *
 * const stats = getProcessingStats(result);
 * console.log(`Success rate: ${stats.successRate.toFixed(2)}%`);
 * console.log(`Average time per file: ${stats.averageTimePerFile.toFixed(2)}ms`);
 * console.log(`Throughput: ${stats.filesPerSecond.toFixed(2)} files/second`);
 * ```
 */
export declare function getProcessingStats(result: BatchProcessingResult): {
    successRate: number;
    averageTimePerFile: number;
    filesPerSecond: number;
};
//# sourceMappingURL=batch-processor.d.ts.map