Image Utilities

Meloqui provides utilities for working with images in multi-modal contexts.

Constants

SUPPORTED_IMAGE_EXTENSIONS

Supported image file extensions.

const SUPPORTED_IMAGE_EXTENSIONS = ['jpg', 'jpeg', 'png', 'gif', 'webp'] as const;

DEFAULT_MAX_IMAGE_SIZE

Default maximum image file size (20MB).

const DEFAULT_MAX_IMAGE_SIZE = 20 * 1024 * 1024; // 20MB

Configurable via MELOQUI_MAX_IMAGE_SIZE environment variable (in MB).

MAX_RAW_FILE_SIZE

Maximum raw file size for processing (100MB).

const MAX_RAW_FILE_SIZE = 100 * 1024 * 1024; // 100MB

Files larger than this are rejected before loading into memory. Configurable via MELOQUI_MAX_RAW_IMAGE_SIZE environment variable (in MB).

Functions

isLocalPath

Check if a string is a local file path (not a URL or data URL).

import { isLocalPath } from 'meloqui';

isLocalPath('./image.png');           // true
isLocalPath('/absolute/path.jpg');    // true
isLocalPath('https://example.com/img.png'); // false
isLocalPath('data:image/png;base64,...');   // false

getMimeType

Get MIME type for an image file path.

import { getMimeType } from 'meloqui';

getMimeType('photo.jpg');   // 'image/jpeg'
getMimeType('image.png');   // 'image/png'
getMimeType('doc.pdf');     // null (unsupported)

Returns null for unsupported extensions.

loadImageAsDataUrl

Load an image file and return as a data URL.

import { loadImageAsDataUrl } from 'meloqui';

const dataUrl = await loadImageAsDataUrl('./photo.jpg');
// 'data:image/jpeg;base64,/9j/4AAQSkZJRg...'

// With options
const dataUrl = await loadImageAsDataUrl('./photo.jpg', {
  maxSize: 10 * 1024 * 1024, // 10MB limit
  optimization: {
    maxWidth: 1024,
    maxHeight: 1024,
    quality: 80
  }
});

LoadImageOptions

interface LoadImageOptions {
  /** Maximum file size in bytes (default: 20MB) */
  maxSize?: number;
  /** Image optimization settings (requires sharp) */
  optimization?: ImageOptimizationOptions;
  /** Logger for warnings */
  logger?: ILogger;
}

Backward Compatibility

You can also pass just a number for maxSize:

await loadImageAsDataUrl('./photo.jpg', 10 * 1024 * 1024); // 10MB limit

Errors

• Error: Image file not found: <path> - File doesn't exist
• Error: Unsupported image type: .<ext> - Extension not supported
• Error: Image file too large: <size> - Exceeds size limit

formatBytes

Format bytes as human-readable string.

import { formatBytes } from 'meloqui';

formatBytes(0);           // '0 bytes'
formatBytes(1);           // '1 byte'
formatBytes(1024);        // '1.0 KB'
formatBytes(1536);        // '1.5 KB'
formatBytes(1048576);     // '1.0 MB'
formatBytes(1073741824);  // '1.0 GB'

ImageOptimizationOptions

Options for optimizing images before encoding. Requires the optional sharp package.

interface ImageOptimizationOptions {
  /** Maximum width in pixels (default: 2048) */
  maxWidth?: number;
  /** Maximum height in pixels (default: 2048) */
  maxHeight?: number;
  /** Quality for JPEG/WebP output, 1-100 (default: 85) */
  quality?: number;
  /** Convert all images to this format */
  format?: 'jpeg' | 'png' | 'webp';
}

See Vision & Multimodal for usage with ChatClient.

Environment Variables

Variable	Default	Description
MELOQUI_MAX_IMAGE_SIZE	20	Maximum encoded image size in MB
MELOQUI_MAX_RAW_IMAGE_SIZE	100	Maximum raw file size in MB

Example: Processing User Uploads

import {
  isLocalPath,
  getMimeType,
  loadImageAsDataUrl,
  formatBytes,
  SUPPORTED_IMAGE_EXTENSIONS
} from 'meloqui';

async function processUpload(imagePath: string) {
  // Validate it's a local file
  if (!isLocalPath(imagePath)) {
    throw new Error('Expected local file path');
  }

  // Check extension
  const mimeType = getMimeType(imagePath);
  if (!mimeType) {
    throw new Error(
      `Unsupported format. Use: ${SUPPORTED_IMAGE_EXTENSIONS.join(', ')}`
    );
  }

  // Load with optimization
  const dataUrl = await loadImageAsDataUrl(imagePath, {
    maxSize: 5 * 1024 * 1024, // 5MB limit
    optimization: {
      maxWidth: 1920,
      maxHeight: 1080,
      quality: 85
    }
  });

  return dataUrl;
}