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

package/README.md

@@ -20,6 +20,8 @@ A high-performance Node.js Native Addon for processing RAW image files using the
 - ✅ **AI-Powered Settings** - 🆕 Automatic quality optimization based on image analysis
 - ✅ **Memory Operations** - Process images entirely in memory
 - ✅ **Multiple Output Formats** - PPM, TIFF, JPEG with advanced compression options
+- ✅ **Buffer Creation API** - 🆕 Create image buffers directly in memory (JPEG, PNG, WebP, AVIF, TIFF, PPM, Thumbnails)
+- ✅ **Stream-based Processing** - 🆕 Return data streams instead of writing to files
 - ✅ **Buffer Support** - Load RAW data from memory buffers
 - ✅ **Configuration Control** - Gamma, brightness, color space settings
 - ✅ **High Performance** - Native C++ processing with JavaScript convenience
@@ -55,7 +57,7 @@ LibRaw supports 100+ RAW formats including:
 npm install lightdrift-libraw
 ```
 
-**Version 1.0.0-alpha.1** is now available on [npmjs.com](https://www.npmjs.com/package/lightdrift-libraw)! 🎉
+**Version 1.0.0-alpha.3** is now available on [npmjs.com](https://www.npmjs.com/package/lightdrift-libraw)! 🎉
 
 ### 🛠️ Build Requirements
 
@@ -96,7 +98,34 @@ async function processRAW() {
     // Load RAW file
     await processor.loadFile("photo.cr2");
 
-    // 🆕 NEW: High-Performance JPEG Conversion
+    // 🆕 NEW: Buffer Creation API - Create images directly in memory
+    // Process the RAW data first
+    await processor.processImage();
+
+    // Create JPEG buffer without writing to file
+    const jpegBuffer = await processor.createJPEGBuffer({
+      quality: 85,
+      width: 1920,
+      progressive: true,
+    });
+
+    console.log(`JPEG buffer created: ${jpegBuffer.buffer.length} bytes`);
+
+    // Create multiple formats in parallel
+    const [pngResult, webpResult, thumbResult] = await Promise.all([
+      processor.createPNGBuffer({ width: 1200, compressionLevel: 6 }),
+      processor.createWebPBuffer({ quality: 80, width: 1200 }),
+      processor.createThumbnailJPEGBuffer({ maxSize: 300 }),
+    ]);
+
+    // Use buffers directly (e.g., send via HTTP, store in database, etc.)
+    // No temporary files needed!
+
+    console.log(`PNG: ${pngResult.buffer.length} bytes`);
+    console.log(`WebP: ${webpResult.buffer.length} bytes`);
+    console.log(`Thumbnail: ${thumbResult.buffer.length} bytes`);
+
+    // 🆕 NEW: High-Performance JPEG Conversion (Legacy method still available)
     // Convert RAW to JPEG with advanced options
     const jpegResult = await processor.convertToJPEG("output.jpg", {
       quality: 85, // JPEG quality (1-100)
@@ -226,7 +255,228 @@ This wrapper provides comprehensive LibRaw functionality with **50+ methods** ac
 
 **All methods are thoroughly tested and production-ready!**
 
-## 🆕 JPEG Conversion (New Feature)
+## 🆕 Buffer Creation API (New Feature)
+
+### Direct Memory Buffer Creation
+
+Create image buffers directly in memory without writing to files. Perfect for web applications, APIs, and streaming workflows.
+
+#### Available Buffer Methods
+
+```javascript
+const processor = new LibRaw();
+await processor.loadFile("photo.cr2");
+await processor.processImage();
+
+// Create different format buffers
+const jpegBuffer = await processor.createJPEGBuffer(options);
+const pngBuffer = await processor.createPNGBuffer(options);
+const webpBuffer = await processor.createWebPBuffer(options);
+const avifBuffer = await processor.createAVIFBuffer(options);
+const tiffBuffer = await processor.createTIFFBuffer(options);
+const ppmBuffer = await processor.createPPMBuffer();
+
+// Extract thumbnail buffer without full processing
+const processor2 = new LibRaw();
+await processor2.loadFile("photo.cr2");
+const thumbBuffer = await processor2.createThumbnailJPEGBuffer(options);
+```
+
+#### Buffer Creation Options
+
+##### JPEG Buffer Options
+
+```javascript
+{
+  quality: 85,          // 1-100 (default: 85)
+  width: 1200,         // Target width
+  height: 800,         // Target height
+  progressive: true,   // Progressive JPEG
+  fastMode: false,     // Speed vs quality trade-off
+  effort: 4           // Encoding effort 1-8
+}
+```
+
+##### PNG Buffer Options
+
+```javascript
+{
+  width: 1200,           // Target width
+  height: 800,          // Target height
+  compressionLevel: 6,  // 0-9 (default: 6)
+  fastMode: false       // Speed vs size trade-off
+}
+```
+
+##### WebP Buffer Options
+
+```javascript
+{
+  quality: 80,         // 1-100 (default: 80)
+  width: 1200,        // Target width
+  height: 800,        // Target height
+  lossless: false,    // Lossless mode
+  effort: 4,          // Encoding effort 0-6
+  fastMode: false     // Speed optimization
+}
+```
+
+##### AVIF Buffer Options
+
+```javascript
+{
+  quality: 50,         // 1-100 (default: 50)
+  width: 1200,        // Target width
+  height: 800,        // Target height
+  lossless: false,    // Lossless mode
+  effort: 4           // Encoding effort 0-9
+}
+```
+
+##### TIFF Buffer Options
+
+```javascript
+{
+  width: 1200,              // Target width
+  height: 800,             // Target height
+  compression: 'lzw',      // 'none', 'lzw', 'zip'
+  predictor: 'horizontal'  // Compression predictor
+}
+```
+
+##### Thumbnail Buffer Options
+
+```javascript
+{
+  maxSize: 300,       // Maximum dimension
+  quality: 85,        // JPEG quality 1-100
+  fastMode: false     // Speed optimization
+}
+```
+
+#### Usage Examples
+
+##### Web API Response
+
+```javascript
+app.get("/api/photo/:id/thumbnail", async (req, res) => {
+  const processor = new LibRaw();
+  try {
+    await processor.loadFile(`photos/${req.params.id}.cr2`);
+
+    const result = await processor.createThumbnailJPEGBuffer({
+      maxSize: 300,
+      quality: 85,
+    });
+
+    res.set({
+      "Content-Type": "image/jpeg",
+      "Content-Length": result.buffer.length,
+      "Cache-Control": "public, max-age=86400",
+    });
+
+    res.send(result.buffer);
+  } finally {
+    await processor.close();
+  }
+});
+```
+
+##### Multiple Format Generation
+
+```javascript
+async function generateFormats(rawFile, outputDir) {
+  const processor = new LibRaw();
+  await processor.loadFile(rawFile);
+  await processor.processImage();
+
+  // Generate all formats in parallel
+  const [jpeg, png, webp, avif] = await Promise.all([
+    processor.createJPEGBuffer({ quality: 85, width: 1920 }),
+    processor.createPNGBuffer({ width: 1200, compressionLevel: 6 }),
+    processor.createWebPBuffer({ quality: 80, width: 1920 }),
+    processor.createAVIFBuffer({ quality: 50, width: 1200 }),
+  ]);
+
+  // Save or process buffers as needed
+  fs.writeFileSync(`${outputDir}/image.jpg`, jpeg.buffer);
+  fs.writeFileSync(`${outputDir}/image.png`, png.buffer);
+  fs.writeFileSync(`${outputDir}/image.webp`, webp.buffer);
+  fs.writeFileSync(`${outputDir}/image.avif`, avif.buffer);
+
+  await processor.close();
+}
+```
+
+##### Streaming Upload
+
+```javascript
+async function uploadToCloud(rawFile) {
+  const processor = new LibRaw();
+  await processor.loadFile(rawFile);
+  await processor.processImage();
+
+  const webpResult = await processor.createWebPBuffer({
+    quality: 80,
+    width: 1600,
+  });
+
+  // Upload buffer directly to cloud storage
+  const uploadResult = await cloudStorage.upload(webpResult.buffer, {
+    contentType: "image/webp",
+    fileName: "processed-image.webp",
+  });
+
+  await processor.close();
+  return uploadResult;
+}
+```
+
+#### Buffer Result Structure
+
+All buffer creation methods return a consistent result structure:
+
+```javascript
+{
+  success: true,
+  buffer: Buffer,              // The created image buffer
+  metadata: {
+    format: "JPEG",            // Output format
+    outputDimensions: {        // Final image dimensions
+      width: 1920,
+      height: 1280
+    },
+    fileSize: {
+      original: 50331648,      // Original processed image size
+      compressed: 245760,      // Buffer size
+      compressionRatio: "204.8" // Compression ratio
+    },
+    processing: {
+      timeMs: "45.23",         // Processing time
+      throughputMBps: "15.4"   // Processing throughput
+    },
+    options: {                 // Applied options
+      quality: 85,
+      width: 1920,
+      // ... other options
+    }
+  }
+}
+```
+
+#### Performance Characteristics
+
+| Format     | Typical Size (1920px) | Creation Time | Compression Ratio |
+| ---------- | --------------------- | ------------- | ----------------- |
+| JPEG       | 80-400KB              | 200-500ms     | 50-200x           |
+| PNG        | 1-4MB                 | 400-800ms     | 12-50x            |
+| WebP       | 50-300KB              | 100-300ms     | 60-300x           |
+| AVIF       | 30-150KB              | 300-800ms     | 100-500x          |
+| TIFF (LZW) | 2-8MB                 | 100-200ms     | 6-25x             |
+| PPM        | 11-45MB               | 50-100ms      | 1x (uncompressed) |
+| Thumbnail  | 5-50KB                | 50-150ms      | 200-1000x         |
+
+## 🆕 JPEG Conversion (Enhanced Feature)
 
 ### High-Performance RAW to JPEG Conversion
 
@@ -698,6 +948,9 @@ npm run test:quick
 # Comprehensive API coverage test
 npm run test:comprehensive
 
+# New buffer creation methods test
+npm run test:buffer-creation
+
 # Individual test suites
 npm run test:image-processing    # Image conversion and processing
 npm run test:format-conversion   # Output formats and color spaces
@@ -717,6 +970,9 @@ npm run test:performance
 # Test all supported formats
 npm run test:formats
 
+# Buffer creation test suites
+npm run test:buffer-creation     # Comprehensive buffer method testing
+
 # Test with your own RAW file
 npm test path/to/your/photo.cr2
 ```
@@ -727,12 +983,14 @@ The test suites provide comprehensive validation across:
 
 - ✅ **21 RAW files tested** (Canon CR3, Nikon NEF, Sony ARW, Fujifilm RAF, Panasonic RW2, Leica DNG)
 - ✅ **100% thumbnail extraction success rate**
+- ✅ **100% buffer creation success rate** (7 new buffer methods)
 - ✅ **6 camera brands validated** (Canon, Nikon, Sony, Fujifilm, Panasonic, Leica)
-- ✅ **Multiple output formats tested** (PPM, TIFF, JPEG thumbnails)
+- ✅ **Multiple output formats tested** (PPM, TIFF, JPEG, PNG, WebP, AVIF buffers)
 - ✅ **Color space conversion** (sRGB, Adobe RGB, Wide Gamut, ProPhoto, XYZ)
 - ✅ **Bit depth variations** (8-bit, 16-bit processing)
-- ✅ **Memory operations** (buffer management, image copying)
-- ✅ **Error handling** (invalid files, corrupted data)
+- ✅ **Memory operations** (buffer management, image copying, direct buffer creation)
+- ✅ **Error handling** (invalid files, corrupted data, parameter validation)
+- ✅ **Performance benchmarking** (buffer creation speed and compression ratios)
 
 ## Thumbnail Extraction
 
@@ -984,8 +1242,8 @@ npm run build  # Rebuilds and copies DLL
 
 **✅ Published to NPM Registry!**
 
-- **Package**: [`lightdrift-libraw@1.0.0-alpha.1`](https://www.npmjs.com/package/lightdrift-libraw)
-- **Published**: August 23, 2025
+- **Package**: [`lightdrift-libraw@1.0.0-alpha.3`](https://www.npmjs.com/package/lightdrift-libraw)
+- **Published**: August 30, 2025
 - **Total Files**: 487 files (4.0 MB package, 18.1 MB unpacked)
 - **Registry**: [npmjs.com](https://www.npmjs.com/package/lightdrift-libraw)
 

package/lib/index.d.ts

@@ -197,6 +197,103 @@ declare module 'libraw' {
     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;
@@ -416,6 +513,48 @@ 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