houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
313 lines (312 loc) • 12.2 kB
TypeScript
/**
* @module ImageUtils
* @description A comprehensive collection of utility functions for image manipulation, processing, and analysis.
* Supports image format conversion, resizing, cropping, compression, metadata extraction, and various image effects.
* @example
* ```typescript
* import { ImageUtils } from 'houser-js-utils';
*
* // Convert base64 to file
* const file = await ImageUtils.convertBase64ToFile(base64String, 'image.jpg');
*
* // Resize image with quality settings
* const resized = await ImageUtils.resizeImage(file, { maxWidth: 800, quality: 0.8 });
*
* // Get image metadata
* const metadata = await ImageUtils.getImageMetadata(file);
* ```
*/
/**
* Supported image formats for conversion and processing
*/
type ImageFormat = "jpeg" | "png" | "webp" | "gif";
/**
* Options for image resizing operations
*/
interface ImageResizeOptions {
/** Maximum width of the resized image */
maxWidth?: number;
/** Maximum height of the resized image */
maxHeight?: number;
/** Quality of the output image (0-1) */
quality?: number;
/** Output format of the resized image */
format?: ImageFormat;
}
/**
* Metadata about an image file
*/
interface ImageMetadata {
/** Width of the image in pixels */
width: number;
/** Height of the image in pixels */
height: number;
/** MIME type of the image */
type: string;
/** Size of the image file in bytes */
size: number;
}
/**
* Dimensions for a scaled image
*/
interface ScaledDimensions {
/** Scaled width in pixels */
width: number;
/** Scaled height in pixels */
height: number;
}
export declare const ImageUtils: {
/**
* Applies a grayscale filter to an image by converting all pixels to their average RGB value.
* @param file - The image file to convert to grayscale
* @returns Promise resolving to the grayscale image as a Blob
* @example
* ```typescript
* const grayscaleImage = await ImageUtils.applyGrayscale(imageFile);
* // Use the grayscale blob as needed
* ```
*/
applyGrayscale(file: File): Promise<Blob>;
/**
* Calculates the aspect ratio of an image from its dimensions.
* @param width - The width of the image in pixels
* @param height - The height of the image in pixels
* @returns The aspect ratio as a decimal number (width/height)
* @example
* ```typescript
* const ratio = ImageUtils.calculateAspectRatio(1920, 1080); // Returns 1.777...
* const isWidescreen = ratio > 1.5; // true for 16:9 ratio
* ```
*/
calculateAspectRatio(width: number, height: number): number;
/**
* Converts a base64 string to a Blob object.
* @param base64 - The base64 string to convert (without data URL prefix)
* @param type - The MIME type of the image (default: "image/jpeg")
* @returns Promise resolving to a Blob object
* @example
* ```typescript
* const blob = await ImageUtils.base64ToBlob(base64String, 'image/png');
* const url = URL.createObjectURL(blob);
* ```
*/
base64ToBlob(base64: string, type?: string): Promise<Blob>;
/**
* Converts a Blob to a base64 string (without data URL prefix).
* @param blob - The Blob to convert
* @returns Promise resolving to base64 string
* @example
* ```typescript
* const base64 = await ImageUtils.blobToBase64(imageBlob);
* console.log('data:image/jpeg;base64,' + base64); // Full data URL
* ```
*/
blobToBase64(blob: Blob): Promise<string>;
/**
* Compresses an image file by reducing its quality while maintaining dimensions.
* @param file - The image file to compress
* @param quality - Compression quality from 0 (lowest) to 1 (highest, default: 0.7)
* @returns Promise resolving to the compressed image as a Blob
* @example
* ```typescript
* const compressed = await ImageUtils.compressImage(largeImage, 0.5);
* console.log(`Original: ${largeImage.size} bytes, Compressed: ${compressed.size} bytes`);
* ```
*/
compressImage(file: File, quality?: number): Promise<Blob>;
/**
* Converts a base64 data URL string to a File object.
* @param base64 - The base64 data URL string (must include data:image/... prefix)
* @param filename - The name for the resulting file
* @returns Promise resolving to File object, or null if base64 is invalid
* @example
* ```typescript
* const file = await ImageUtils.convertBase64ToFile(
* 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==',
* 'pixel.png'
* );
* ```
*/
convertBase64ToFile(base64: string, filename: string): Promise<File> | null;
/**
* Creates a thumbnail image with specified maximum dimensions.
* @param file - The image file to create a thumbnail from
* @param maxSize - Maximum size in pixels for the longest dimension (default: 200)
* @returns Promise resolving to thumbnail as base64 data URL string
* @example
* ```typescript
* const thumbnail = await ImageUtils.createThumbnail(imageFile, 150);
* document.getElementById('preview').src = thumbnail;
* ```
*/
createThumbnail(file: File, maxSize?: number): Promise<string>;
/**
* Crops an image to specified rectangular dimensions.
* @param file - The image file to crop
* @param x - Starting x coordinate for the crop (pixels from left)
* @param y - Starting y coordinate for the crop (pixels from top)
* @param width - Width of the crop area in pixels
* @param height - Height of the crop area in pixels
* @returns Promise resolving to the cropped image as a Blob
* @example
* ```typescript
* // Crop a 200x200 square from the center of the image
* const cropped = await ImageUtils.cropImage(imageFile, 100, 100, 200, 200);
* ```
*/
cropImage(file: File, x: number, y: number, width: number, height: number): Promise<Blob>;
/**
* Extracts metadata information from an image file.
* @param file - The image file to analyze
* @returns Promise resolving to object containing width, height, type, and size
* @example
* ```typescript
* const metadata = await ImageUtils.getImageMetadata(imageFile);
* console.log(`Image: ${metadata.width}x${metadata.height}, ${metadata.type}, ${metadata.size} bytes`);
* ```
*/
getImageMetadata(file: File): Promise<ImageMetadata>;
/**
* Analyzes an image to determine its most dominant color.
* @param file - The image file to analyze
* @returns Promise resolving to the dominant color as a hex string
* @example
* ```typescript
* const dominantColor = await ImageUtils.getDominantColor(imageFile);
* console.log(`Dominant color: ${dominantColor}`); // e.g., "#ff5733"
* document.body.style.backgroundColor = dominantColor;
* ```
*/
getDominantColor(file: File): Promise<string>;
/**
* Calculates scaled dimensions for an image while maintaining aspect ratio.
* @param img - The HTML image element to scale
* @param maxWidth - Optional maximum width constraint
* @param maxHeight - Optional maximum height constraint
* @returns Object containing the calculated scaled width and height
* @example
* ```typescript
* const scaled = ImageUtils.getScaledDimensions(imageElement, 800, 600);
* console.log(`Scaled dimensions: ${scaled.width}x${scaled.height}`);
* ```
*/
getScaledDimensions(img: HTMLImageElement, maxWidth?: number, maxHeight?: number): ScaledDimensions;
/**
* Checks if an image exists and is accessible at the given URL.
* @param url - The URL to check for image availability
* @returns Promise resolving to true if the image exists and is accessible
* @example
* ```typescript
* const exists = await ImageUtils.imageExists('https://example.com/image.jpg');
* if (exists) {
* console.log('Image is available');
* }
* ```
*/
imageExists(url: string): Promise<boolean>;
/**
* Validates whether a file is an image based on its MIME type.
* @param file - The file to check
* @returns True if the file is an image, false otherwise
* @example
* ```typescript
* const isImage = ImageUtils.isImageFile(selectedFile);
* if (!isImage) {
* alert('Please select an image file');
* }
* ```
*/
isImageFile(file: File): boolean;
/**
* Loads an image from a URL and returns the HTMLImageElement.
* @param url - The URL of the image to load
* @returns Promise resolving to HTMLImageElement when image loads successfully
* @throws {Error} If the image fails to load
* @example
* ```typescript
* try {
* const img = await ImageUtils.loadImage('https://example.com/image.jpg');
* console.log(`Loaded image: ${img.width}x${img.height}`);
* } catch (error) {
* console.error('Failed to load image:', error);
* }
* ```
*/
loadImage(url: string): Promise<HTMLImageElement>;
/**
* Loads and decodes an image from a URL with error handling.
* @param url - The URL of the image to load
* @returns Promise resolving to HTMLImageElement or null if loading fails
* @example
* ```typescript
* const img = await ImageUtils.loadImageElement('https://example.com/image.jpg');
* if (img) {
* document.body.appendChild(img);
* } else {
* console.log('Failed to load image');
* }
* ```
*/
loadImageElement(url: string): Promise<HTMLImageElement | null>;
/**
* Resizes an image file to fit within specified dimensions while maintaining aspect ratio.
* @param file - The image file to resize
* @param options - Resize options including max dimensions, quality, and output format
* @returns Promise resolving to the resized image as a Blob
* @example
* ```typescript
* const resized = await ImageUtils.resizeImage(originalFile, {
* maxWidth: 800,
* maxHeight: 600,
* quality: 0.9,
* format: 'jpeg'
* });
* ```
*/
resizeImage(file: File, options?: ImageResizeOptions): Promise<Blob>;
/**
* Rotates an image by the specified number of degrees around its center.
* @param file - The image file to rotate
* @param degrees - Degrees to rotate (0-360, positive for clockwise)
* @returns Promise resolving to the rotated image as a Blob
* @example
* ```typescript
* const rotated90 = await ImageUtils.rotateImage(imageFile, 90);
* const rotatedMinus45 = await ImageUtils.rotateImage(imageFile, -45);
* ```
*/
rotateImage(file: File, degrees: number): Promise<Blob>;
/**
* Converts a URL to a File object by downloading the content.
* @param url - The URL to convert to a file
* @param filename - The name for the resulting file
* @param mimeType - The MIME type for the file
* @returns Promise resolving to a File object
* @example
* ```typescript
* const file = await ImageUtils.urlToFile(
* 'https://example.com/image.jpg',
* 'downloaded-image.jpg',
* 'image/jpeg'
* );
* ```
*/
urlToFile(url: string, filename: string, mimeType: string): Promise<File>;
/**
* Validates that image dimensions are within specified limits.
* @param width - The width to validate
* @param height - The height to validate
* @param maxWidth - The maximum allowed width
* @param maxHeight - The maximum allowed height
* @returns True if dimensions are within limits, false otherwise
* @example
* ```typescript
* const isValid = ImageUtils.validateImageDimensions(1920, 1080, 2000, 2000);
* if (!isValid) {
* console.log('Image is too large');
* }
* ```
*/
validateImageDimensions(width: number, height: number, maxWidth: number, maxHeight: number): boolean;
};
export {};