apexify.js 5.0.0 → 5.0.1

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to Apexify.js will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [5.0.0] - 2024-12-20
+
+### 🎉 Major Feature Release - Advanced Image & Canvas Features
+
+#### ✨ Added
+
+##### Background Enhancements
+- **Background Image Filters**: Apply filters directly to background images via `customBg.filters`
+- **Background Image Opacity**: Control background image transparency with `customBg.opacity`
+- **Video Backgrounds**: Support for video backgrounds with frame extraction via `videoBg` option
+  - Extract specific frames from videos
+  - Loop and autoplay support
+  - Opacity control for video backgrounds
+
+##### Image Processing Enhancements
+- **Image Masking**: Apply masks to images with multiple modes (`alpha`, `luminance`, `inverse`)
+- **Custom Clip Paths**: Define custom polygon clipping paths for images
+- **Image Distortion**: 
+  - Perspective distortion with 4-point control
+  - Bulge/pinch effects with intensity control
+  - Mesh warping with customizable grid control points
+- **Effects Stack**: Professional image effects
+  - Vignette effect with intensity and size control
+  - Lens flare with position and intensity
+  - Chromatic aberration effect
+  - Film grain effect
+- **Enhanced Filters**: 
+  - `filterIntensity` - Global intensity multiplier for all filters
+  - `filterOrder` - Control when filters are applied (`pre` or `post` transformation)
+
+##### Text Enhancements
+- **Text on Paths**: Render text along curves and paths
+  - Support for line, arc, bezier, and quadratic curve paths
+  - Offset control for text distance from path
+  - Automatic text distribution along path
+
+##### Custom Lines Enhancements
+- **Advanced Path Options**:
+  - Smooth path interpolation with tension control
+  - Bezier curve paths
+  - Catmull-Rom spline paths
+  - Closed path support
+- **Arrow Markers**: 
+  - Start and end arrows on lines
+  - Customizable arrow size and style (filled/outline)
+  - Color control for arrows
+- **Path Markers**: 
+  - Add markers at any position along a path (0-1)
+  - Multiple marker shapes: circle, square, diamond, arrow
+  - Customizable marker size and color
+- **Line Patterns**: 
+  - Built-in patterns: dots, dashes, custom segments
+  - Pattern offset control
+- **Line Textures**: Apply texture images to lines
+
+##### New Utility Methods
+- **Batch Operations**: `batch()` - Process multiple operations in parallel
+- **Chain Operations**: `chain()` - Chain operations sequentially
+- **Image Stitching**: `stitchImages()` - Stitch multiple images together
+  - Horizontal, vertical, and grid layouts
+  - Overlap and blend support
+  - Spacing control
+- **Collage Maker**: `createCollage()` - Create image collages
+  - Grid, masonry, carousel, and custom layouts
+  - Automatic spacing and alignment
+  - Background and border radius support
+- **Image Compression**: `compress()` - Compress images with quality control
+  - Support for JPEG, WebP, and AVIF formats
+  - Progressive JPEG support
+  - Max width/height constraints
+- **Color Palette Extraction**: `extractPalette()` - Extract color palettes from images
+  - Multiple algorithms: k-means, median-cut, octree
+  - Customizable color count
+  - Multiple output formats: hex, rgb, hsl
+- **Advanced Save Method**: `save()` - Save buffers to local files with extensive customization
+  - Multiple file formats: PNG, JPEG, WebP, AVIF, GIF
+  - Smart naming patterns: timestamp, counter, or custom
+  - Auto-create directories
+  - Quality control for JPEG/WebP
+  - Prefix/suffix support
+  - Overwrite protection with auto-renaming
+  - Batch saving with `saveMultiple()`
+  - Counter management with `resetSaveCounter()`
+
+#### 🔧 Technical Improvements
+- Added comprehensive TypeScript type definitions for all new features
+- Created utility modules for better code organization:
+  - `imageMasking.ts` - Image masking and distortion utilities
+  - `imageEffects.ts` - Image effects utilities
+  - `textPathRenderer.ts` - Text path rendering utilities
+  - `advancedLines.ts` - Advanced line drawing utilities
+  - `batchOperations.ts` - Batch and chain operation utilities
+  - `imageStitching.ts` - Image stitching and collage utilities
+  - `imageCompression.ts` - Image compression and palette extraction utilities
+- Enhanced error handling and validation
+- Improved type safety across all new features
+
+#### 📚 Documentation
+- Updated README with new features
+- Added comprehensive examples for all new features
+- Enhanced API documentation
+
+---
+
+## [4.9.28] - Previous Release
+
+### Features
+- Enhanced text renderer with decorations
+- Professional pattern system
+- Advanced gradient support
+- Comprehensive shape drawing
+- Chart generation capabilities
+- GIF creation support
+
+---
+
+## [4.9.0] - Initial Major Release
+
+### Features
+- Core canvas creation
+- Image and shape drawing
+- Text rendering
+- Basic filters and effects
+- Format conversion
+- Background removal
+
+---
+
+For a complete list of changes, please refer to the [GitHub repository](https://github.com/zenith-79/apexify.js).
+

package/README.md

@@ -6,7 +6,8 @@
 
 **The Ultimate TypeScript Canvas Library for Node.js**
 
-[![npm version](https://badge.fury.io/js/apexify.svg)](https://badge.fury.io/js/apexify)
+[![npm version](https://badge.fury.io/js/apexify.js.svg)](https://badge.fury.io/js/apexify.js)
+[![npm downloads](https://img.shields.io/npm/dt/apexify.js.svg)](https://www.npmjs.com/package/apexify.js)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
@@ -64,6 +65,7 @@
 - **Color Detection**: Extract and analyze colors from images
 - **Batch Operations**: Process multiple operations in parallel
 - **Chain Operations**: Chain operations sequentially for complex workflows
+- **Advanced File Saving**: Save buffers to local files with smart naming, format conversion, and batch support
 
 ---
 
@@ -168,10 +170,64 @@ const textImage = await painter.createText({
   }
 }, heartImage);
 
-// Save the result
-fs.writeFileSync('beautiful-artwork.png', textImage);
+// Save the result using the advanced save method
+const saveResult = await painter.save(textImage, {
+  directory: './output',
+  filename: 'beautiful-artwork',
+  format: 'png'
+});
+console.log(`Saved to: ${saveResult.path} (${saveResult.size} bytes)`);
+
+// Or use the simple approach (auto-generated filename)
+const autoSave = await painter.save(textImage);
+// Saves to: ./ApexPainter_output/20241220_143025_123.png
 ```
 
+### 💾 **Advanced Save Method**
+
+The `save()` method provides powerful file saving capabilities with extensive customization:
+
+```typescript
+// Simple save with auto-generated timestamp name
+const canvas = await painter.createCanvas({ width: 800, height: 600 });
+const result = await painter.save(canvas.buffer);
+// Saves to: ./ApexPainter_output/20241220_143025_123.png
+
+// Custom filename and directory
+await painter.save(canvas.buffer, {
+  directory: './my-images',
+  filename: 'my-canvas',
+  format: 'jpg',
+  quality: 95
+});
+
+// Save with counter naming
+await painter.save(canvas.buffer, {
+  naming: 'counter',
+  prefix: 'image-',
+  counterStart: 1
+});
+// Saves to: ./ApexPainter_output/image-1.png, image-2.png, etc.
+
+// Save multiple buffers in batch
+const buffers = [canvas1.buffer, canvas2.buffer, canvas3.buffer];
+const results = await painter.saveMultiple(buffers, {
+  prefix: 'batch-',
+  naming: 'counter'
+});
+// Saves: batch-1.png, batch-2.png, batch-3.png
+```
+
+**Save Options:**
+- `directory` - Output directory (default: `./ApexPainter_output`)
+- `filename` - Custom filename (auto-generated if not provided)
+- `format` - File format: `png`, `jpg`, `jpeg`, `webp`, `avif`, `gif` (default: `png`)
+- `quality` - Quality for JPEG/WebP (0-100, default: 90)
+- `naming` - Naming pattern: `timestamp`, `counter`, or `custom` (default: `timestamp`)
+- `prefix` / `suffix` - Add prefix/suffix to filenames
+- `overwrite` - Overwrite existing files (default: `false`, auto-renames if exists)
+- `createDirectory` - Auto-create directory if missing (default: `true`)
+
 ### 📝 **Flexible Array Support**
 
 Both `createImage()` and `createText()` methods accept **single objects** OR **arrays of objects**:
@@ -583,6 +639,9 @@ const buttonText = await painter.createText({
 | `createText()` | Add text to canvas | `TextProperties \| TextProperties[]` |
 | `createChart()` | Generate charts | `ChartConfig` |
 | `createGIF()` | Create animated GIFs | `GIFConfig` |
+| `save()` | Save buffer to local file with advanced options | `Buffer, SaveOptions?` |
+| `saveMultiple()` | Save multiple buffers in batch | `Buffer[], SaveOptions?` |
+| `resetSaveCounter()` | Reset the save counter for naming | `void` |
 
 ### 🔄 **Flexible Parameters**
 
@@ -652,6 +711,7 @@ This allows you to add multiple elements in one call for better performance and
 - 🎨 **Collage Maker**: Create beautiful image collages
 - 📦 **Image Compression**: Optimize images with quality control
 - 🎨 **Color Palette Extraction**: Extract color palettes from images
+- 💾 **Advanced Save Method**: Save buffers to files with smart naming, format conversion, and batch support
 
 See [CHANGELOG.md](CHANGELOG.md) for complete details.
 

package/dist/cjs/Canvas/ApexPainter.d.ts

@@ -1,5 +1,5 @@
 import { PathLike } from "fs";
-import { OutputFormat, CanvasConfig, TextProperties, ImageProperties, GIFOptions, GIFResults, CustomOptions, cropOptions, GradientConfig, Frame, ExtractFramesOptions, ResizeOptions, MaskOptions, BlendOptions, ImageFilter, BatchOperation, ChainOperation, StitchOptions, CollageLayout, CompressionOptions, PaletteOptions } from "./utils/utils";
+import { OutputFormat, CanvasConfig, TextProperties, ImageProperties, GIFOptions, GIFResults, CustomOptions, cropOptions, GradientConfig, Frame, ExtractFramesOptions, ResizeOptions, MaskOptions, BlendOptions, ImageFilter, BatchOperation, ChainOperation, StitchOptions, CollageLayout, CompressionOptions, PaletteOptions, SaveOptions, SaveResult } from "./utils/utils";
 interface CanvasResults {
     buffer: Buffer;
     canvas: CanvasConfig;
@@ -7,6 +7,7 @@ interface CanvasResults {
 export declare class ApexPainter {
     #private;
     private format?;
+    private saveCounter;
     constructor({ type }?: OutputFormat);
     createCanvas(canvas: CanvasConfig): Promise<CanvasResults>;
     createImage(images: ImageProperties | ImageProperties[], canvasBuffer: CanvasResults | Buffer): Promise<Buffer>;
@@ -135,6 +136,67 @@ export declare class ApexPainter {
      * ```
      */
     outPut(results: Buffer): Promise<Buffer | string | Blob | ArrayBuffer>;
+    /**
+     * Advanced save method to save buffers to local files with extensive customization options.
+     *
+     * @param buffer - Buffer to save (from createCanvas, createImage, createText, etc.)
+     * @param options - Save options for file path, format, naming, etc.
+     * @returns SaveResult with file path, name, size, and format
+     *
+     * @example
+     * ```typescript
+     * // Simple save with auto-generated name
+     * const canvas = await painter.createCanvas({ width: 800, height: 600 });
+     * const result = await painter.save(canvas.buffer);
+     * // Saves to: ./ApexPainter_output/20241220_143025_123.png
+     *
+     * // Custom filename and directory
+     * await painter.save(canvas.buffer, {
+     *   directory: './my-images',
+     *   filename: 'my-canvas',
+     *   format: 'jpg',
+     *   quality: 95
+     * });
+     *
+     * // Save with counter naming
+     * await painter.save(canvas.buffer, {
+     *   naming: 'counter',
+     *   prefix: 'image-',
+     *   counterStart: 1
+     * });
+     * // Saves to: ./ApexPainter_output/image-1.png, image-2.png, etc.
+     *
+     * // Save multiple buffers
+     * const buffers = [canvas1.buffer, canvas2.buffer, canvas3.buffer];
+     * const results = await painter.saveMultiple(buffers, {
+     *   prefix: 'batch-',
+     *   naming: 'counter'
+     * });
+     * ```
+     */
+    save(buffer: Buffer, options?: SaveOptions): Promise<SaveResult>;
+    /**
+     * Save multiple buffers at once with batch options.
+     *
+     * @param buffers - Array of buffers to save
+     * @param options - Save options (applied to all files)
+     * @returns Array of SaveResult objects
+     *
+     * @example
+     * ```typescript
+     * const canvas1 = await painter.createCanvas({ width: 800, height: 600 });
+     * const canvas2 = await painter.createCanvas({ width: 800, height: 600 });
+     * const results = await painter.saveMultiple([canvas1.buffer, canvas2.buffer], {
+     *   prefix: 'batch-',
+     *   naming: 'counter'
+     * });
+     * ```
+     */
+    saveMultiple(buffers: Buffer[], options?: SaveOptions): Promise<SaveResult[]>;
+    /**
+     * Reset the save counter (useful when using 'counter' naming).
+     */
+    resetSaveCounter(): void;
 }
 export {};
 //# sourceMappingURL=ApexPainter.d.ts.map

package/dist/cjs/Canvas/ApexPainter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApexPainter.d.ts","sourceRoot":"","sources":["../../../lib/Canvas/ApexPainter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ApexPainter.d.ts","sourceRoot":"","sources":["../../../lib/Canvas/ApexPainter.ts"],"names":[],"mappings":"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"}

package/dist/cjs/Canvas/ApexPainter.js

@@ -16,6 +16,7 @@ const enhancedTextRenderer_1 = require("./utils/Texts/enhancedTextRenderer");
 const enhancedPatternRenderer_1 = require("./utils/Patterns/enhancedPatternRenderer");
 class ApexPainter {
     format;
+    saveCounter = 1;
     constructor({ type } = { type: 'buffer' }) {
         this.format = { type: type || 'buffer' };
     }
@@ -1849,6 +1850,201 @@ class ApexPainter {
             throw new Error(`outPut failed: ${errorMessage}`);
         }
     }
+    /**
+     * Advanced save method to save buffers to local files with extensive customization options.
+     *
+     * @param buffer - Buffer to save (from createCanvas, createImage, createText, etc.)
+     * @param options - Save options for file path, format, naming, etc.
+     * @returns SaveResult with file path, name, size, and format
+     *
+     * @example
+     * ```typescript
+     * // Simple save with auto-generated name
+     * const canvas = await painter.createCanvas({ width: 800, height: 600 });
+     * const result = await painter.save(canvas.buffer);
+     * // Saves to: ./ApexPainter_output/20241220_143025_123.png
+     *
+     * // Custom filename and directory
+     * await painter.save(canvas.buffer, {
+     *   directory: './my-images',
+     *   filename: 'my-canvas',
+     *   format: 'jpg',
+     *   quality: 95
+     * });
+     *
+     * // Save with counter naming
+     * await painter.save(canvas.buffer, {
+     *   naming: 'counter',
+     *   prefix: 'image-',
+     *   counterStart: 1
+     * });
+     * // Saves to: ./ApexPainter_output/image-1.png, image-2.png, etc.
+     *
+     * // Save multiple buffers
+     * const buffers = [canvas1.buffer, canvas2.buffer, canvas3.buffer];
+     * const results = await painter.saveMultiple(buffers, {
+     *   prefix: 'batch-',
+     *   naming: 'counter'
+     * });
+     * ```
+     */
+    async save(buffer, options) {
+        try {
+            if (!Buffer.isBuffer(buffer)) {
+                throw new Error("save: buffer must be a Buffer.");
+            }
+            const opts = {
+                directory: options?.directory ?? './ApexPainter_output',
+                filename: options?.filename,
+                format: options?.format ?? 'png',
+                quality: options?.quality ?? 90,
+                createDirectory: options?.createDirectory ?? true,
+                naming: options?.naming ?? 'timestamp',
+                counterStart: options?.counterStart ?? 1,
+                prefix: options?.prefix ?? '',
+                suffix: options?.suffix ?? '',
+                overwrite: options?.overwrite ?? false
+            };
+            // Create directory if needed
+            if (opts.createDirectory && !fs_1.default.existsSync(opts.directory)) {
+                fs_1.default.mkdirSync(opts.directory, { recursive: true });
+            }
+            // Generate filename
+            let filename;
+            if (opts.filename) {
+                filename = opts.filename;
+                // Add extension if not present
+                if (!filename.includes('.')) {
+                    filename += `.${opts.format}`;
+                }
+            }
+            else {
+                // Auto-generate filename based on naming pattern
+                switch (opts.naming) {
+                    case 'timestamp':
+                        const now = new Date();
+                        const timestamp = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}_${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}_${String(now.getMilliseconds()).padStart(3, '0')}`;
+                        filename = `${opts.prefix}${timestamp}${opts.suffix}.${opts.format}`;
+                        break;
+                    case 'counter':
+                        filename = `${opts.prefix}${this.saveCounter}${opts.suffix}.${opts.format}`;
+                        this.saveCounter++;
+                        break;
+                    case 'custom':
+                        filename = `${opts.prefix}${opts.suffix}.${opts.format}`;
+                        break;
+                    default:
+                        filename = `${opts.prefix}${Date.now()}${opts.suffix}.${opts.format}`;
+                }
+            }
+            // Handle file overwrite
+            const filePath = path_1.default.join(opts.directory, filename);
+            if (!opts.overwrite && fs_1.default.existsSync(filePath)) {
+                // Add number suffix if file exists
+                let counter = 1;
+                let newPath = filePath;
+                const ext = path_1.default.extname(filePath);
+                const baseName = path_1.default.basename(filePath, ext);
+                const dir = path_1.default.dirname(filePath);
+                while (fs_1.default.existsSync(newPath)) {
+                    newPath = path_1.default.join(dir, `${baseName}_${counter}${ext}`);
+                    counter++;
+                }
+                filename = path_1.default.basename(newPath);
+            }
+            // Convert buffer format if needed
+            let finalBuffer = buffer;
+            if (opts.format !== 'png') {
+                // Use Sharp for format conversion
+                const sharp = require('sharp');
+                let sharpImage = sharp(buffer);
+                switch (opts.format) {
+                    case 'jpg':
+                    case 'jpeg':
+                        finalBuffer = await sharpImage
+                            .jpeg({ quality: opts.quality, progressive: false })
+                            .toBuffer();
+                        break;
+                    case 'webp':
+                        finalBuffer = await sharpImage
+                            .webp({ quality: opts.quality })
+                            .toBuffer();
+                        break;
+                    case 'avif':
+                        finalBuffer = await sharpImage
+                            .avif({ quality: opts.quality })
+                            .toBuffer();
+                        break;
+                    case 'gif':
+                        // GIF requires special handling - keep as PNG if not already GIF
+                        if (!buffer.toString('ascii', 0, 3).includes('GIF')) {
+                            console.warn('save: Converting to GIF may not preserve quality. Consider using PNG.');
+                            finalBuffer = buffer; // Keep original for now
+                        }
+                        break;
+                }
+            }
+            // Write file
+            const finalPath = path_1.default.join(opts.directory, filename);
+            fs_1.default.writeFileSync(finalPath, finalBuffer);
+            return {
+                path: finalPath,
+                filename: filename,
+                size: finalBuffer.length,
+                format: opts.format
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`save failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Save multiple buffers at once with batch options.
+     *
+     * @param buffers - Array of buffers to save
+     * @param options - Save options (applied to all files)
+     * @returns Array of SaveResult objects
+     *
+     * @example
+     * ```typescript
+     * const canvas1 = await painter.createCanvas({ width: 800, height: 600 });
+     * const canvas2 = await painter.createCanvas({ width: 800, height: 600 });
+     * const results = await painter.saveMultiple([canvas1.buffer, canvas2.buffer], {
+     *   prefix: 'batch-',
+     *   naming: 'counter'
+     * });
+     * ```
+     */
+    async saveMultiple(buffers, options) {
+        try {
+            if (!Array.isArray(buffers) || buffers.length === 0) {
+                throw new Error("saveMultiple: buffers must be a non-empty array.");
+            }
+            const results = [];
+            const baseCounter = options?.counterStart ?? this.saveCounter;
+            for (let i = 0; i < buffers.length; i++) {
+                const bufferOptions = {
+                    ...options,
+                    counterStart: baseCounter + i,
+                    naming: options?.naming === 'counter' ? 'counter' : options?.naming
+                };
+                const result = await this.save(buffers[i], bufferOptions);
+                results.push(result);
+            }
+            return results;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+            throw new Error(`saveMultiple failed: ${errorMessage}`);
+        }
+    }
+    /**
+     * Reset the save counter (useful when using 'counter' naming).
+     */
+    resetSaveCounter() {
+        this.saveCounter = 1;
+    }
     /**
      * Applies stroke style to shape context
      * @private