peasy-image 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peasy Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# peasy-image
+
+[![npm](https://img.shields.io/npm/v/peasy-image)](https://www.npmjs.com/package/peasy-image)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Image processing library for Node.js powered by [sharp](https://sharp.pixelplumbing.com/) -- resize, crop, convert, compress, rotate, blur, sharpen, and 8 more operations. TypeScript-first with full type definitions.
+
+All functions accept a `Buffer` and return a `Promise<ImageResult>` with the processed image data, dimensions, format, and byte size.
+
+> **Try the interactive tools at [peasyimage.com](https://peasyimage.com)** -- [Image Resizer](https://peasyimage.com/tools/resize/), [Image Converter](https://peasyimage.com/tools/convert/), [Image Compressor](https://peasyimage.com/tools/compress/)
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [What You Can Do](#what-you-can-do)
+  - [Resize and Crop](#resize-and-crop)
+  - [Format Conversion](#format-conversion)
+  - [Compression](#compression)
+  - [Rotation and Flipping](#rotation-and-flipping)
+  - [Filters and Effects](#filters-and-effects)
+  - [Compositing](#compositing)
+  - [Thumbnails](#thumbnails)
+- [API Reference](#api-reference)
+- [TypeScript Types](#typescript-types)
+- [Also Available for Python](#also-available-for-python)
+- [Peasy Developer Tools](#peasy-developer-tools)
+- [License](#license)
+
+## Install
+
+```bash
+npm install peasy-image
+```
+
+Requires Node.js 18+ and includes [sharp](https://sharp.pixelplumbing.com/) as a dependency for high-performance, native image processing.
+
+## Quick Start
+
+```typescript
+import { readFileSync, writeFileSync } from "fs";
+import { info, resize, compress, convert } from "peasy-image";
+
+const source = readFileSync("photo.jpg");
+
+// Get image metadata
+const meta = await info(source);
+console.log(`${meta.width}x${meta.height} ${meta.format} (${meta.size} bytes)`);
+
+// Resize to 800px wide, maintaining aspect ratio
+const resized = await resize(source, { width: 800, fit: "contain" });
+writeFileSync("resized.jpg", resized.data);
+
+// Compress to WebP at quality 60
+const compressed = await compress(source, { quality: 60, format: "webp" });
+writeFileSync("compressed.webp", compressed.data);
+
+// Convert PNG to AVIF
+const avif = await convert(readFileSync("image.png"), "avif");
+writeFileSync("image.avif", avif.data);
+```
+
+## What You Can Do
+
+### Resize and Crop
+
+Resize images to exact dimensions or proportionally by width/height. Sharp supports 5 fit modes that control how the image fills the target area: `cover` (crop to fill), `contain` (letterbox), `fill` (stretch), `inside`, and `outside`.
+
+| Fit Mode | Behavior |
+|----------|----------|
+| `cover` | Crop to fill the target dimensions (default) |
+| `contain` | Resize to fit within bounds, preserving aspect ratio |
+| `fill` | Stretch to exact dimensions, ignoring aspect ratio |
+| `inside` | Resize to fit inside, never enlarging |
+| `outside` | Resize to cover, never shrinking |
+
+```typescript
+import { resize, crop } from "peasy-image";
+
+// Resize to fit within 800x600, preserving aspect ratio
+const fitted = await resize(source, { width: 800, height: 600, fit: "contain" });
+
+// Resize by width only — height calculated automatically
+const wide = await resize(source, { width: 1200, fit: "contain" });
+
+// Crop a 300x300 region starting at (50, 100)
+const cropped = await crop(source, { left: 50, top: 100, width: 300, height: 300 });
+```
+
+Learn more: [Image Resizer Tool](https://peasyimage.com/tools/resize/) -- [Image Cropper Tool](https://peasyimage.com/tools/crop/)
+
+### Format Conversion
+
+Convert between 6 image formats. Modern formats like WebP and AVIF provide significantly better compression than JPEG and PNG while maintaining visual quality.
+
+| Format | Best For | Alpha Support |
+|--------|----------|---------------|
+| `png` | Lossless graphics, screenshots | Yes |
+| `jpeg` | Photos, continuous tones | No |
+| `webp` | Web images (25-35% smaller than JPEG) | Yes |
+| `avif` | Next-gen web (50% smaller than JPEG) | Yes |
+| `tiff` | Print, archival | Yes |
+| `gif` | Simple animations | Limited |
+
+```typescript
+import { convert } from "peasy-image";
+
+// Convert to WebP for smaller web assets
+const webp = await convert(source, "webp");
+
+// Convert to AVIF for maximum compression
+const avif = await convert(source, "avif");
+```
+
+Learn more: [Image Converter Tool](https://peasyimage.com/tools/convert/) -- [WebP vs AVIF Guide](https://peasyimage.com/blog/webp-vs-avif/)
+
+### Compression
+
+Reduce file size by adjusting quality. The `compress` function defaults to JPEG at quality 60, which typically reduces file size by 70-80% with acceptable visual quality.
+
+```typescript
+import { compress } from "peasy-image";
+
+// Compress to JPEG at quality 60 (default)
+const small = await compress(source);
+
+// Compress to WebP at quality 80 for higher fidelity
+const webp = await compress(source, { quality: 80, format: "webp" });
+```
+
+Learn more: [Image Compressor Tool](https://peasyimage.com/tools/compress/)
+
+### Rotation and Flipping
+
+Rotate images by any angle (90, 180, 270 for lossless, or arbitrary degrees). Flip vertically or mirror horizontally.
+
+```typescript
+import { rotate, flip, flop } from "peasy-image";
+
+// Rotate 90 degrees clockwise
+const rotated = await rotate(source, 90);
+
+// Flip vertically (top to bottom)
+const flipped = await flip(source);
+
+// Mirror horizontally (left to right)
+const mirrored = await flop(source);
+```
+
+### Filters and Effects
+
+Apply visual effects: grayscale conversion, Gaussian blur, Laplacian sharpening, color inversion, and color tinting.
+
+| Filter | Description | Key Parameter |
+|--------|-------------|---------------|
+| `grayscale` | Convert to grayscale | -- |
+| `blur` | Gaussian blur | `sigma` (0.3-1000, default 2.0) |
+| `sharpen` | Laplacian sharpening | `sigma` (default 1.0) |
+| `negate` | Invert all colors | -- |
+| `tint` | Apply RGB color tint | `{ r, g, b }` values |
+
+```typescript
+import { grayscale, blur, sharpen, negate, tint } from "peasy-image";
+
+// Convert to black and white
+const bw = await grayscale(source);
+
+// Apply soft Gaussian blur (sigma 3.0)
+const blurred = await blur(source, 3.0);
+
+// Sharpen a slightly out-of-focus image
+const sharp = await sharpen(source, 1.5);
+
+// Invert colors for a negative effect
+const inverted = await negate(source);
+
+// Apply a warm sepia-like tint
+const warm = await tint(source, { r: 180, g: 130, b: 80 });
+```
+
+### Compositing
+
+Overlay one image on top of another with position control and opacity. Useful for watermarks, badges, and image collages.
+
+```typescript
+import { composite } from "peasy-image";
+
+// Place a watermark at position (10, 10)
+const watermarked = await composite(photo, watermarkPng, { left: 10, top: 10 });
+
+// Overlay with 50% opacity
+const blended = await composite(background, foreground, {
+  left: 100,
+  top: 50,
+  opacity: 0.5,
+});
+```
+
+### Thumbnails
+
+Create square thumbnails by center-cropping and resizing in a single operation. Ideal for profile pictures, gallery previews, and social media icons.
+
+```typescript
+import { thumbnail } from "peasy-image";
+
+// 64x64 square thumbnail for avatars
+const avatar = await thumbnail(source, 64);
+
+// 256x256 thumbnail for gallery grid
+const preview = await thumbnail(source, 256);
+```
+
+## API Reference
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `info` | `(source: Buffer) => Promise<ImageInfo>` | Get image metadata (dimensions, format, channels) |
+| `resize` | `(source: Buffer, options: ResizeOptions) => Promise<ImageResult>` | Resize with fit mode control |
+| `crop` | `(source: Buffer, options: CropOptions) => Promise<ImageResult>` | Extract a rectangular region |
+| `convert` | `(source: Buffer, format: ImageFormat) => Promise<ImageResult>` | Convert between 6 formats |
+| `compress` | `(source: Buffer, options?: CompressOptions) => Promise<ImageResult>` | Reduce file size via quality |
+| `rotate` | `(source: Buffer, angle: number) => Promise<ImageResult>` | Rotate by degrees |
+| `flip` | `(source: Buffer) => Promise<ImageResult>` | Flip vertically |
+| `flop` | `(source: Buffer) => Promise<ImageResult>` | Mirror horizontally |
+| `grayscale` | `(source: Buffer) => Promise<ImageResult>` | Convert to grayscale |
+| `blur` | `(source: Buffer, sigma?: number) => Promise<ImageResult>` | Gaussian blur |
+| `sharpen` | `(source: Buffer, sigma?: number) => Promise<ImageResult>` | Laplacian sharpening |
+| `negate` | `(source: Buffer) => Promise<ImageResult>` | Invert colors |
+| `tint` | `(source: Buffer, color: {r,g,b}) => Promise<ImageResult>` | Apply color tint |
+| `composite` | `(base: Buffer, overlay: Buffer, options?) => Promise<ImageResult>` | Overlay images |
+| `thumbnail` | `(source: Buffer, size: number) => Promise<ImageResult>` | Square center-crop thumbnail |
+
+## TypeScript Types
+
+```typescript
+interface ImageInfo {
+  width: number;
+  height: number;
+  format: string;
+  channels: number;
+  size: number;
+  hasAlpha: boolean;
+  space: string;
+}
+
+interface ImageResult {
+  data: Buffer;
+  width: number;
+  height: number;
+  format: string;
+  size: number;
+}
+
+type ImageFormat = "png" | "jpeg" | "webp" | "avif" | "tiff" | "gif";
+type FitMode = "cover" | "contain" | "fill" | "inside" | "outside";
+
+interface ResizeOptions { width?: number; height?: number; fit?: FitMode; }
+interface CropOptions { left: number; top: number; width: number; height: number; }
+interface CompressOptions { quality?: number; format?: ImageFormat; }
+```
+
+## Also Available for Python
+
+| Platform | Package | Install |
+|----------|---------|---------|
+| **PyPI** | [peasy-image](https://pypi.org/project/peasy-image/) | `pip install peasy-image` |
+
+The Python version provides 20 operations powered by Pillow, including watermark, border, round corners, pad, and EXIF extraction.
+
+## Peasy Developer Tools
+
+| Package | npm | PyPI | Description |
+|---------|-----|------|-------------|
+| **peasy-image** | **[npm](https://www.npmjs.com/package/peasy-image)** | [PyPI](https://pypi.org/project/peasy-image/) | **Image processing — resize, crop, convert, compress** |
+| peasy-pdf | [npm](https://www.npmjs.com/package/peasy-pdf) | [PyPI](https://pypi.org/project/peasy-pdf/) | PDF manipulation -- merge, split, rotate, extract |
+| peasy-css | [npm](https://www.npmjs.com/package/peasy-css) | [PyPI](https://pypi.org/project/peasy-css/) | CSS processing -- minify, format, analyze |
+| peasy-compress | -- | [PyPI](https://pypi.org/project/peasy-compress/) | File compression -- gzip, brotli, zstd |
+| peasy-audio | -- | [PyPI](https://pypi.org/project/peasy-audio/) | Audio processing -- convert, trim, metadata |
+| peasy-video | -- | [PyPI](https://pypi.org/project/peasy-video/) | Video processing -- convert, trim, thumbnail |
+| peasy-document | [npm](https://www.npmjs.com/package/peasy-document) | [PyPI](https://pypi.org/project/peasy-document/) | Document conversion -- DOCX, HTML, Markdown |
+
+Part of the [Peasy Tools](https://peasytools.com) developer tools ecosystem.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+/**
+ * peasy-image types — interfaces for image processing operations.
+ */
+/** Basic image metadata returned by `info()`. */
+interface ImageInfo {
+    width: number;
+    height: number;
+    format: string;
+    channels: number;
+    size: number;
+    hasAlpha: boolean;
+    space: string;
+}
+/** Result of an image processing operation. */
+interface ImageResult {
+    data: Buffer;
+    width: number;
+    height: number;
+    format: string;
+    size: number;
+}
+/** Supported output image formats. */
+type ImageFormat = "png" | "jpeg" | "webp" | "avif" | "tiff" | "gif";
+/** Resize fit mode — how the image should fit within the target dimensions. */
+type FitMode = "cover" | "contain" | "fill" | "inside" | "outside";
+/** Options for resizing an image. */
+interface ResizeOptions {
+    width?: number;
+    height?: number;
+    fit?: FitMode;
+}
+/** Options for cropping a region from an image. */
+interface CropOptions {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Options for compressing an image. */
+interface CompressOptions {
+    quality?: number;
+    format?: ImageFormat;
+}
+
+/**
+ * peasy-image engine — image processing functions powered by sharp.
+ *
+ * 15 operations: info, resize, crop, convert, compress, rotate, flip, flop,
+ * grayscale, blur, sharpen, negate, tint, composite, thumbnail.
+ */
+
+/**
+ * Get image metadata — dimensions, format, channels, color space.
+ *
+ * @param source - Image data as a Buffer
+ * @returns Image metadata
+ */
+declare function info(source: Buffer): Promise<ImageInfo>;
+/**
+ * Resize an image to the given dimensions.
+ *
+ * If only width or height is provided, the other dimension is
+ * calculated to maintain aspect ratio (default fit: "cover").
+ *
+ * @param source - Image data as a Buffer
+ * @param options - Resize options (width, height, fit)
+ * @returns Resized image result
+ */
+declare function resize(source: Buffer, options: ResizeOptions): Promise<ImageResult>;
+/**
+ * Crop a rectangular region from an image.
+ *
+ * @param source - Image data as a Buffer
+ * @param options - Crop region (left, top, width, height)
+ * @returns Cropped image result
+ */
+declare function crop(source: Buffer, options: CropOptions): Promise<ImageResult>;
+/**
+ * Convert an image to a different format.
+ *
+ * @param source - Image data as a Buffer
+ * @param format - Target format (png, jpeg, webp, avif, tiff, gif)
+ * @returns Converted image result
+ */
+declare function convert(source: Buffer, format: ImageFormat): Promise<ImageResult>;
+/**
+ * Compress an image by reducing quality.
+ *
+ * Defaults to JPEG format at quality 60 for maximum compression.
+ *
+ * @param source - Image data as a Buffer
+ * @param options - Compression options (quality, format)
+ * @returns Compressed image result
+ */
+declare function compress(source: Buffer, options?: CompressOptions): Promise<ImageResult>;
+/**
+ * Rotate an image by the given angle in degrees.
+ *
+ * Common angles (90, 180, 270) produce lossless rotation.
+ * Arbitrary angles expand the canvas to fit the rotated image.
+ *
+ * @param source - Image data as a Buffer
+ * @param angle - Rotation angle in degrees (clockwise)
+ * @returns Rotated image result
+ */
+declare function rotate(source: Buffer, angle: number): Promise<ImageResult>;
+/**
+ * Flip an image vertically (top to bottom).
+ *
+ * @param source - Image data as a Buffer
+ * @returns Flipped image result
+ */
+declare function flip(source: Buffer): Promise<ImageResult>;
+/**
+ * Flop an image horizontally (mirror, left to right).
+ *
+ * @param source - Image data as a Buffer
+ * @returns Flopped image result
+ */
+declare function flop(source: Buffer): Promise<ImageResult>;
+/**
+ * Convert an image to grayscale.
+ *
+ * @param source - Image data as a Buffer
+ * @returns Grayscale image result
+ */
+declare function grayscale(source: Buffer): Promise<ImageResult>;
+/**
+ * Apply Gaussian blur to an image.
+ *
+ * @param source - Image data as a Buffer
+ * @param sigma - Blur intensity (0.3 to 1000, default 2.0)
+ * @returns Blurred image result
+ */
+declare function blur(source: Buffer, sigma?: number): Promise<ImageResult>;
+/**
+ * Sharpen an image using Laplacian sharpening.
+ *
+ * @param source - Image data as a Buffer
+ * @param sigma - Sharpening intensity (default 1.0)
+ * @returns Sharpened image result
+ */
+declare function sharpen(source: Buffer, sigma?: number): Promise<ImageResult>;
+/**
+ * Negate (invert) the colors of an image.
+ *
+ * @param source - Image data as a Buffer
+ * @returns Negated image result
+ */
+declare function negate(source: Buffer): Promise<ImageResult>;
+/**
+ * Apply a color tint to an image.
+ *
+ * @param source - Image data as a Buffer
+ * @param color - RGB color to tint with
+ * @returns Tinted image result
+ */
+declare function tint(source: Buffer, color: {
+    r: number;
+    g: number;
+    b: number;
+}): Promise<ImageResult>;
+/**
+ * Overlay one image on top of another (composite).
+ *
+ * @param base - Base image data as a Buffer
+ * @param overlay - Overlay image data as a Buffer
+ * @param options - Position and opacity options
+ * @returns Composited image result
+ */
+declare function composite(base: Buffer, overlay: Buffer, options?: {
+    left?: number;
+    top?: number;
+    opacity?: number;
+}): Promise<ImageResult>;
+/**
+ * Create a square thumbnail by center-cropping and resizing.
+ *
+ * The image is resized to cover the target size, then center-cropped
+ * to produce a square output.
+ *
+ * @param source - Image data as a Buffer
+ * @param size - Target thumbnail size in pixels (width = height)
+ * @returns Square thumbnail image result
+ */
+declare function thumbnail(source: Buffer, size: number): Promise<ImageResult>;
+
+export { type CompressOptions, type CropOptions, type FitMode, type ImageFormat, type ImageInfo, type ImageResult, type ResizeOptions, blur, composite, compress, convert, crop, flip, flop, grayscale, info, negate, resize, rotate, sharpen, thumbnail, tint };

package/dist/index.js

@@ -0,0 +1,121 @@
+// src/engine.ts
+import sharp from "sharp";
+async function toResult(pipeline, format) {
+  const { data, info: info2 } = await pipeline.toBuffer({ resolveWithObject: true });
+  return {
+    data,
+    width: info2.width,
+    height: info2.height,
+    format: info2.format || format || "unknown",
+    size: data.length
+  };
+}
+async function info(source) {
+  const meta = await sharp(source).metadata();
+  return {
+    width: meta.width ?? 0,
+    height: meta.height ?? 0,
+    format: meta.format ?? "unknown",
+    channels: meta.channels ?? 0,
+    size: source.length,
+    hasAlpha: meta.hasAlpha ?? false,
+    space: meta.space ?? "unknown"
+  };
+}
+async function resize(source, options) {
+  const pipeline = sharp(source).resize({
+    width: options.width,
+    height: options.height,
+    fit: options.fit ?? "cover"
+  });
+  return toResult(pipeline);
+}
+async function crop(source, options) {
+  const pipeline = sharp(source).extract({
+    left: options.left,
+    top: options.top,
+    width: options.width,
+    height: options.height
+  });
+  return toResult(pipeline);
+}
+async function convert(source, format) {
+  const pipeline = sharp(source).toFormat(format);
+  return toResult(pipeline, format);
+}
+async function compress(source, options) {
+  const quality = options?.quality ?? 60;
+  const format = options?.format ?? "jpeg";
+  const pipeline = sharp(source).toFormat(format, { quality });
+  return toResult(pipeline, format);
+}
+async function rotate(source, angle) {
+  const pipeline = sharp(source).rotate(angle);
+  return toResult(pipeline);
+}
+async function flip(source) {
+  const pipeline = sharp(source).flip();
+  return toResult(pipeline);
+}
+async function flop(source) {
+  const pipeline = sharp(source).flop();
+  return toResult(pipeline);
+}
+async function grayscale(source) {
+  const pipeline = sharp(source).grayscale();
+  return toResult(pipeline);
+}
+async function blur(source, sigma = 2) {
+  const pipeline = sharp(source).blur(sigma);
+  return toResult(pipeline);
+}
+async function sharpen(source, sigma = 1) {
+  const pipeline = sharp(source).sharpen(sigma);
+  return toResult(pipeline);
+}
+async function negate(source) {
+  const pipeline = sharp(source).negate();
+  return toResult(pipeline);
+}
+async function tint(source, color) {
+  const pipeline = sharp(source).tint(color);
+  return toResult(pipeline);
+}
+async function composite(base, overlay, options) {
+  let overlayInput = overlay;
+  if (options?.opacity !== void 0 && options.opacity < 1) {
+    overlayInput = await sharp(overlay).ensureAlpha(options.opacity).toBuffer();
+  }
+  const pipeline = sharp(base).composite([
+    {
+      input: overlayInput,
+      left: options?.left ?? 0,
+      top: options?.top ?? 0
+    }
+  ]);
+  return toResult(pipeline);
+}
+async function thumbnail(source, size) {
+  const pipeline = sharp(source).resize(size, size, {
+    fit: "cover",
+    position: "centre"
+  });
+  return toResult(pipeline);
+}
+export {
+  blur,
+  composite,
+  compress,
+  convert,
+  crop,
+  flip,
+  flop,
+  grayscale,
+  info,
+  negate,
+  resize,
+  rotate,
+  sharpen,
+  thumbnail,
+  tint
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "peasy-image",
+  "version": "0.1.0",
+  "description": "Image processing library for Node.js — resize, crop, convert, compress, filter. Powered by sharp.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "image",
+    "resize",
+    "crop",
+    "convert",
+    "compress",
+    "sharp",
+    "peasy"
+  ],
+  "author": "Peasy Tools",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/peasytools/peasy-image-js.git"
+  },
+  "homepage": "https://peasyimage.com",
+  "dependencies": {
+    "sharp": "^0.33"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsup": "^8.0",
+    "typescript": "^5.7",
+    "vitest": "^3.0"
+  }
+}