tessl/npm-tinify

Node.js client for the Tinify API that intelligently compresses, resizes, converts, and stores images in AVIF, WebP, JPEG, and PNG formats.

—

Pending

Overview

Eval results

Files

Image Transformations

Name: tessl/npm-tinify
Author: tessl

Comprehensive image processing operations including resizing, format conversion, metadata preservation, and custom transformations.

Capabilities

Image Resizing

Resize images using various methods including fit and cover modes.

/**
 * Resize image with specified options
 * @param options - Resize configuration object
 * @returns New Source instance with resize transformation
 */
resize(options: ResizeOptions): Source;

interface ResizeOptions {
  /** Resize method determining how the image is fitted */
  method: "fit" | "cover";
  /** Target width in pixels */
  width?: number;
  /** Target height in pixels */
  height?: number;
}

Resize Methods:

fit: Scale image to fit within dimensions (maintains aspect ratio, may leave empty space)
cover: Scale and crop to cover entire area (maintains aspect ratio, may crop parts)

Usage Examples:

const tinify = require("tinify");

tinify.key = "your-api-key";

// Fit within dimensions (no cropping)
await tinify.fromFile("large-image.jpg")
  .resize({ method: "fit", width: 800, height: 600 })
  .toFile("fitted.jpg");

// Cover area (may crop)  
await tinify.fromFile("photo.jpg")
  .resize({ method: "cover", width: 400, height: 400 })
  .toFile("square-thumbnail.jpg");

// Width only (maintain aspect ratio)
await tinify.fromFile("portrait.jpg")
  .resize({ method: "fit", width: 300 })
  .toFile("mobile-portrait.jpg");

Format Conversion

Convert images between supported formats including AVIF, WebP, JPEG, and PNG.

/**
 * Convert image to different format(s)
 * @param options - Conversion configuration object
 * @returns New Source instance with format conversion
 */
convert(options: ConvertOptions): Source;

interface ConvertOptions {
  /** Target format(s) - API will choose the most efficient */
  type: SupportedImageTypes | SupportedImageTypes[] | "*/*";
}

type SupportedImageTypes = 
  | "image/webp" 
  | "image/png" 
  | "image/jpg" 
  | "image/jpeg" 
  | "image/avif";

Usage Examples:

const tinify = require("tinify");

tinify.key = "your-api-key";

// Convert to specific format
await tinify.fromFile("photo.jpg")
  .convert({ type: "image/webp" })
  .toFile("photo.webp");

// Let API choose best format from options
const source = tinify.fromFile("image.png")
  .convert({ type: ["image/webp", "image/avif", "image/png"] });

// Get the chosen format
const result = source.result();
const extension = await result.extension();
await source.toFile(`optimized.${extension}`);

// Use wildcard for automatic format selection
await tinify.fromFile("large-file.png")
  .convert({ type: "*/*" })
  .toFile("smallest-format");

Metadata Preservation

Preserve specific metadata fields including copyright, GPS location, and creation time.

/**
 * Preserve metadata fields (array version)
 * @param options - Array of metadata fields to preserve
 * @returns New Source instance with metadata preservation
 */
preserve(options: string[]): Source;

/**
 * Preserve metadata fields (variadic version)
 * @param options - Metadata fields to preserve as separate arguments
 * @returns New Source instance with metadata preservation
 */
preserve(...options: string[]): Source;

Supported Metadata Fields:

copyright: Copyright information
creation: Creation date and time
location: GPS coordinates and location data

Usage Examples:

const tinify = require("tinify");

tinify.key = "your-api-key";

// Preserve specific metadata (array syntax)
await tinify.fromFile("photo-with-metadata.jpg")
  .preserve(["copyright", "location"])
  .toFile("compressed-with-metadata.jpg");

// Preserve metadata (variadic syntax)
await tinify.fromFile("photo.jpg")
  .preserve("copyright", "creation", "location")
  .toFile("preserved.jpg");

// Combine with other transformations
await tinify.fromFile("original.jpg")
  .resize({ method: "fit", width: 1200 })
  .preserve("copyright")
  .convert({ type: "image/webp" })
  .toFile("optimized.webp");

Custom Transformations

Apply custom transformation options using the generic transform method.

/**
 * Apply custom transformation options
 * @param options - Custom transformation configuration object
 * @returns New Source instance with custom transformation
 */
transform(options: object): Source;

Usage Example:

const tinify = require("tinify");

tinify.key = "your-api-key";

// Custom transformation (API-specific options)
await tinify.fromFile("image.jpg")
  .transform({
    // Custom API options would go here
    // Refer to Tinify API documentation for available options
  })
  .toFile("custom-transformed.jpg");

Chaining Transformations

All transformation methods return a new Source instance, allowing for fluent chaining of multiple operations.

Usage Examples:

const tinify = require("tinify");

tinify.key = "your-api-key";

// Complex transformation chain
await tinify.fromFile("large-photo.jpg")
  .resize({ method: "cover", width: 800, height: 600 })
  .preserve("copyright", "location")
  .convert({ type: ["image/webp", "image/jpg"] })
  .toFile("processed-photo");

// Conditional transformations
let source = tinify.fromFile("image.png");

if (needsResize) {
  source = source.resize({ method: "fit", width: 1000 });
}

if (preserveMetadata) {
  source = source.preserve("copyright", "creation");
}

await source.toFile("final-image.png");

Error Handling

Transformation methods can throw the following errors:

ClientError: Invalid transformation options or unsupported format
AccountError: Monthly compression limit exceeded
ServerError: Temporary API processing issues

Error Handling Example:

const tinify = require("tinify");

tinify.key = "your-api-key";

try {
  await tinify.fromFile("image.jpg")
    .resize({ method: "fit", width: 2000, height: 2000 })
    .convert({ type: "image/webp" })
    .toFile("processed.webp");
} catch (error) {
  if (error instanceof tinify.ClientError) {
    console.error("Invalid transformation options:", error.message);
  } else if (error instanceof tinify.AccountError) {
    console.error("Account limit exceeded:", error.message);
  }
}

Install with Tessl CLI