lightdrift-libraw 1.0.0-alpha.1 → 1.0.0-alpha.3

package/lib/index.d.ts

@@ -157,6 +157,221 @@ declare module 'libraw' {
     data: Buffer;
   }
 
+  export interface LibRawJPEGOptions {
+    /** JPEG quality (1-100) */
+    quality?: number;
+    /** Target width (maintains aspect ratio if height not specified) */
+    width?: number;
+    /** Target height (maintains aspect ratio if width not specified) */
+    height?: number;
+    /** Use progressive JPEG */
+    progressive?: boolean;
+    /** Use mozjpeg encoder for better compression */
+    mozjpeg?: boolean;
+    /** Chroma subsampling ('4:4:4', '4:2:0') - Note: 4:2:2 maps to 4:4:4 */
+    chromaSubsampling?: '4:4:4' | '4:2:2' | '4:2:0';
+    /** Enable trellis quantisation */
+    trellisQuantisation?: boolean;
+    /** Optimize scan order */
+    optimizeScans?: boolean;
+    /** Overshoot deringing */
+    overshootDeringing?: boolean;
+    /** Optimize Huffman coding */
+    optimizeCoding?: boolean;
+    /** Output color space */
+    colorSpace?: 'srgb' | 'rec2020' | 'p3' | 'cmyk';
+    /** Enable fast mode for better performance */
+    fastMode?: boolean;
+    /** Encoding effort (1=fastest, 9=slowest) */
+    effort?: number;
+    /** Maximum concurrency for batch operations */
+    maxConcurrency?: number;
+  }
+
+  export interface LibRawOptimalSettings {
+    quality: number;
+    progressive: boolean;
+    mozjpeg: boolean;
+    chromaSubsampling: string;
+    effort: number;
+    reasoning: string;
+  }
+
+  export interface LibRawBufferResult {
+    /** Buffer creation success status */
+    success: boolean;
+    /** Raw binary data buffer */
+    buffer: Buffer;
+    /** Buffer metadata */
+    metadata: {
+      /** Original image dimensions */
+      originalDimensions?: {
+        width: number;
+        height: number;
+      };
+      /** Output image dimensions */
+      outputDimensions?: {
+        width: number;
+        height: number;
+      };
+      /** Processed dimensions */
+      dimensions?: {
+        width: number;
+        height: number;
+      };
+      /** File size information */
+      fileSize: {
+        original?: number;
+        compressed: number;
+        compressionRatio?: string;
+      };
+      /** Processing performance */
+      processing: {
+        timeMs: string;
+        throughputMBps?: string;
+        fromCache?: boolean;
+      };
+      /** Format-specific options */
+      jpegOptions?: object;
+      pngOptions?: object;
+      tiffOptions?: object;
+      webpOptions?: object;
+      avifOptions?: object;
+      /** Format type */
+      format?: string;
+    };
+  }
+
+  export interface LibRawImageConversionOptions {
+    /** Target width (maintains aspect ratio if height not specified) */
+    width?: number;
+    /** Target height (maintains aspect ratio if width not specified) */
+    height?: number;
+    /** Output color space */
+    colorSpace?: 'srgb' | 'rec2020' | 'p3' | 'cmyk';
+    /** Enable fast mode for better performance */
+    fastMode?: boolean;
+  }
+
+  export interface LibRawPNGOptions extends LibRawImageConversionOptions {
+    /** PNG compression level (0-9) */
+    compressionLevel?: number;
+    /** Use progressive PNG */
+    progressive?: boolean;
+  }
+
+  export interface LibRawTIFFOptions extends LibRawImageConversionOptions {
+    /** TIFF compression type */
+    compression?: 'none' | 'lzw' | 'jpeg' | 'zip';
+    /** JPEG quality when using JPEG compression */
+    quality?: number;
+    /** Create pyramidal TIFF */
+    pyramid?: boolean;
+  }
+
+  export interface LibRawWebPOptions extends LibRawImageConversionOptions {
+    /** WebP quality (1-100) */
+    quality?: number;
+    /** Use lossless WebP */
+    lossless?: boolean;
+    /** Encoding effort (0-6) */
+    effort?: number;
+  }
+
+  export interface LibRawAVIFOptions extends LibRawImageConversionOptions {
+    /** AVIF quality (1-100) */
+    quality?: number;
+    /** Use lossless AVIF */
+    lossless?: boolean;
+    /** Encoding effort (0-9) */
+    effort?: number;
+  }
+
+  export interface LibRawThumbnailJPEGOptions {
+    /** JPEG quality (1-100) */
+    quality?: number;
+    /** Maximum dimension size */
+    maxSize?: number;
+  }
+
+  export interface LibRawJPEGResult {
+    /** Conversion success status */
+    success: boolean;
+    /** Output file path */
+    outputPath: string;
+    /** Conversion metadata */
+    metadata: {
+      /** Original image dimensions */
+      originalDimensions: {
+        width: number;
+        height: number;
+      };
+      /** Output image dimensions */
+      outputDimensions: {
+        width: number;
+        height: number;
+      };
+      /** File size information */
+      fileSize: {
+        original: number;
+        compressed: number;
+        compressionRatio: string;
+      };
+      /** Processing performance */
+      processing: {
+        timeMs: string;
+        throughputMBps: string;
+      };
+      /** Applied JPEG options */
+      jpegOptions: object;
+    };
+  }
+
+  export interface LibRawBatchResult {
+    /** Successfully processed files */
+    successful: Array<{
+      input: string;
+      output: string;
+      result: LibRawJPEGResult;
+    }>;
+    /** Failed files */
+    failed: Array<{
+      input: string;
+      error: string;
+    }>;
+    /** Processing summary */
+    summary: {
+      total: number;
+      processed: number;
+      errors: number;
+      totalProcessingTime: number;
+      averageCompressionRatio: string;
+      totalOriginalSize: number;
+      totalCompressedSize: number;
+      averageProcessingTimePerFile: string;
+    };
+  }
+
+  export interface LibRawOptimalSettings {
+    /** Recommended JPEG settings */
+    recommended: LibRawJPEGOptions & {
+      reasoning: string[];
+    };
+    /** Image analysis results */
+    imageAnalysis: {
+      dimensions: {
+        width: number;
+        height: number;
+        area: number;
+      };
+      category: 'high-resolution' | 'medium-resolution' | 'low-resolution';
+      camera: {
+        make?: string;
+        model?: string;
+      };
+    };
+  }
+
   export class LibRaw {
     constructor();
 
@@ -298,6 +513,108 @@ declare module 'libraw' {
      */
     errorCount(): Promise<number>;
 
+    // ============== MEMORY STREAM OPERATIONS (NEW FEATURE) ==============
+    /**
+     * Create processed image as JPEG buffer in memory
+     * @param options JPEG conversion options
+     */
+    createJPEGBuffer(options?: LibRawJPEGOptions): Promise<LibRawBufferResult>;
+
+    /**
+     * Create processed image as PNG buffer in memory
+     * @param options PNG conversion options
+     */
+    createPNGBuffer(options?: LibRawPNGOptions): Promise<LibRawBufferResult>;
+
+    /**
+     * Create processed image as TIFF buffer in memory
+     * @param options TIFF conversion options
+     */
+    createTIFFBuffer(options?: LibRawTIFFOptions): Promise<LibRawBufferResult>;
+
+    /**
+     * Create processed image as WebP buffer in memory
+     * @param options WebP conversion options
+     */
+    createWebPBuffer(options?: LibRawWebPOptions): Promise<LibRawBufferResult>;
+
+    /**
+     * Create processed image as AVIF buffer in memory
+     * @param options AVIF conversion options
+     */
+    createAVIFBuffer(options?: LibRawAVIFOptions): Promise<LibRawBufferResult>;
+
+    /**
+     * Create raw PPM buffer from processed image data
+     */
+    createPPMBuffer(): Promise<LibRawBufferResult>;
+
+    /**
+     * Create thumbnail as JPEG buffer in memory
+     * @param options JPEG options for thumbnail
+     */
+    createThumbnailJPEGBuffer(options?: LibRawThumbnailJPEGOptions): Promise<LibRawBufferResult>;
+
+    // ============== JPEG CONVERSION (NEW FEATURE) ==============
+    /**
+     * Convert RAW to JPEG with advanced options
+     * @param outputPath Output JPEG file path
+     * @param options JPEG conversion options
+     */
+    convertToJPEG(outputPath: string, options?: LibRawJPEGOptions): Promise<LibRawJPEGResult>;
+
+    /**
+     * Batch convert multiple RAW files to JPEG
+     * @param inputPaths Array of input RAW file paths
+     * @param outputDir Output directory for JPEG files
+     * @param options JPEG conversion options
+     */
+    batchConvertToJPEG(inputPaths: string[], outputDir: string, options?: LibRawJPEGOptions): Promise<LibRawBatchResult>;
+
+    /**
+     * Get optimal JPEG conversion settings based on image analysis
+     * @param analysisOptions Options for image analysis
+     */
+    getOptimalJPEGSettings(analysisOptions?: { usage?: 'web' | 'print' | 'archive' }): Promise<LibRawOptimalSettings>;
+
+    /**
+     * High-performance JPEG conversion with minimal processing for speed
+     * @param outputPath Output JPEG file path
+     * @param options Speed-optimized JPEG options
+     */
+    convertToJPEGFast(outputPath: string, options?: LibRawJPEGOptions): Promise<LibRawJPEGResult>;
+
+    /**
+     * Create multiple JPEG sizes from single RAW (thumbnail, web, full)
+     * @param baseOutputPath Base output path (without extension)
+     * @param options Multi-size options
+     */
+    convertToJPEGMultiSize(baseOutputPath: string, options?: {
+      sizes?: Array<{
+        name: string;
+        width?: number;
+        height?: number;
+        quality?: number;
+        progressive?: boolean;
+        mozjpeg?: boolean;
+        chromaSubsampling?: string;
+        effort?: number;
+      }>;
+    }): Promise<{
+      success: boolean;
+      sizes: Record<string, {
+        name: string;
+        outputPath: string;
+        dimensions: { width: number; height: number };
+        fileSize: number;
+        processingTime: number;
+        config: any;
+      }>;
+      originalDimensions: { width: number; height: number };
+      totalProcessingTime: number;
+      averageTimePerSize: string;
+    }>;
+
     // ============== STATIC METHODS ==============
     /**
      * Get LibRaw library version