@vizzly-testing/honeydiff 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project 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).
 
+## [0.7.0] - 2025-12-11
+
+## What's Changed
+
+### Added
+- **Image Metadata API** - New functions to extract image dimensions, file size, and format without performing comparison
+  - `getImageMetadata(buffer)` / `getImageMetadataSync(buffer)` - Extract metadata from Buffer
+  - `getImageMetadataFromFile(path)` / `getImageMetadataFromFileSync(path)` - Extract metadata from file path
+  - Returns `ImageMetadata` with `width`, `height`, `fileSizeBytes`, and `format` properties
+  - Useful for storage tracking and billing purposes without needing to scan cloud storage buckets
+
+**Full Changelog**: https://github.com/vizzly-testing/honeydiff/compare/v0.6.0...v0.7.0
+
 ## [0.6.0] - 2025-12-10
 
 ## What's Changed

package/README.md

@@ -263,6 +263,28 @@ let buffer = fs.readFileSync('image.png');
 let dims = await getDimensions(buffer);
 ```
 
+### 10. Image Metadata
+
+Get image dimensions, file size, and format detection - useful for storage tracking and billing.
+
+```javascript
+const { getImageMetadata, getImageMetadataFromFile } = require('@vizzly-testing/honeydiff');
+
+// From buffer
+let buffer = fs.readFileSync('screenshot.png');
+let metadata = await getImageMetadata(buffer);
+console.log(`Image: ${metadata.width}x${metadata.height}`);
+console.log(`Size: ${metadata.fileSizeBytes} bytes`);
+console.log(`Format: ${metadata.format}`);
+// Output: Image: 1920x1080
+//         Size: 245760 bytes
+//         Format: png
+
+// From file (gets accurate file size from disk)
+let metadata = await getImageMetadataFromFile('screenshot.png');
+console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
+```
+
 ## Accessibility Features
 
 Built-in WCAG color contrast analysis and color blindness simulation to catch accessibility violations in screenshots and UI designs.
@@ -418,6 +440,14 @@ Fast boolean check - returns true if different, false if identical.
 
 Get image dimensions without loading full image data.
 
+**`getImageMetadata(buffer): Promise<ImageMetadata>`**
+
+Get image metadata (dimensions, file size, format) from a buffer.
+
+**`getImageMetadataFromFile(path): Promise<ImageMetadata>`**
+
+Get image metadata from a file path. File size is read from disk for accuracy.
+
 ### Sync Functions (Blocks Event Loop)
 
 **`compareSync(img1, img2, options?): DiffResult`**
@@ -432,6 +462,14 @@ Synchronous boolean check.
 
 Synchronous dimension retrieval.
 
+**`getImageMetadataSync(buffer): ImageMetadata`**
+
+Synchronous metadata retrieval from buffer.
+
+**`getImageMetadataFromFileSync(path): ImageMetadata`**
+
+Synchronous metadata retrieval from file.
+
 ### Input Types
 
 All functions accept:

package/index.d.ts

@@ -294,6 +294,17 @@ export interface ImageDimensions {
   height: number;
 }
 
+export interface ImageMetadata {
+  /** Image width in pixels */
+  width: number;
+  /** Image height in pixels */
+  height: number;
+  /** Size of the image data in bytes */
+  fileSizeBytes: number;
+  /** Detected image format (e.g., "png", "jpeg", "webp") or null if unknown */
+  format: string | null;
+}
+
 /**
  * Get image dimensions asynchronously (recommended)
  *
@@ -330,6 +341,87 @@ export function getDimensions(img: ImageInput): Promise<ImageDimensions>;
  */
 export function getDimensionsSync(img: ImageInput): ImageDimensions;
 
+// ============================================================================
+// Image Metadata API
+// ============================================================================
+
+/**
+ * Get image metadata asynchronously (recommended)
+ *
+ * Retrieves image dimensions, file size, and format detection.
+ * Useful for storage tracking and billing purposes.
+ *
+ * @param img - Image Buffer
+ * @returns Promise resolving to ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const buffer = fs.readFileSync('screenshot.png');
+ * const metadata = await getImageMetadata(buffer);
+ * console.log(`Image: ${metadata.width}x${metadata.height}`);
+ * console.log(`Size: ${metadata.fileSizeBytes} bytes`);
+ * console.log(`Format: ${metadata.format}`);
+ * // Output: Image: 1920x1080
+ * //         Size: 245760 bytes
+ * //         Format: png
+ * ```
+ */
+export function getImageMetadata(img: Buffer): Promise<ImageMetadata>;
+
+/**
+ * Get image metadata synchronously (blocks event loop)
+ *
+ * Retrieves image dimensions, file size, and format detection.
+ * Use this only when you need blocking behavior.
+ *
+ * @param img - Image Buffer
+ * @returns ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const buffer = fs.readFileSync('screenshot.png');
+ * const metadata = getImageMetadataSync(buffer);
+ * console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
+ * ```
+ */
+export function getImageMetadataSync(img: Buffer): ImageMetadata;
+
+/**
+ * Get image metadata from file asynchronously (recommended)
+ *
+ * Retrieves image dimensions, file size (from disk), and format detection.
+ * The file size is read from filesystem metadata for accuracy.
+ *
+ * @param path - Path to the image file
+ * @returns Promise resolving to ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const metadata = await getImageMetadataFromFile('screenshot.png');
+ * console.log(`Image: ${metadata.width}x${metadata.height}`);
+ * console.log(`Size: ${metadata.fileSizeBytes} bytes`);
+ * console.log(`Format: ${metadata.format}`);
+ * ```
+ */
+export function getImageMetadataFromFile(path: string): Promise<ImageMetadata>;
+
+/**
+ * Get image metadata from file synchronously (blocks event loop)
+ *
+ * Retrieves image dimensions, file size (from disk), and format detection.
+ * Use this only when you need blocking behavior.
+ *
+ * @param path - Path to the image file
+ * @returns ImageMetadata
+ *
+ * @example
+ * ```typescript
+ * const metadata = getImageMetadataFromFileSync('screenshot.png');
+ * console.log(`${metadata.width}x${metadata.height}, ${metadata.fileSizeBytes} bytes`);
+ * ```
+ */
+export function getImageMetadataFromFileSync(path: string): ImageMetadata;
+
 // ============================================================================
 // WCAG Accessibility API
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/honeydiff",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "High-performance image diffing for Node.js - Native bindings to Honeydiff Rust library",
   "type": "module",
   "main": "index.js",
@@ -75,6 +75,12 @@
     "load-platform.cjs",
     "platforms/*.node",
     "README.md",
+    "CHANGELOG.md",
+    "index.js",
+    "index.d.ts",
+    "load-platform.cjs",
+    "platforms/*.node",
+    "README.md",
     "CHANGELOG.md"
   ],
   "engines": {