cross-image 0.1.2 → 0.1.5

package/esm/mod.d.ts

@@ -2,21 +2,21 @@
  * @module @cross/image
  *
  * A pure JavaScript, dependency-free, cross-runtime image processing library.
- * Supports reading, resizing, and saving common image formats (PNG, JPEG, WebP, GIF, TIFF, BMP, RAW).
+ * Supports decoding, resizing, and encoding common image formats (PNG, JPEG, WebP, GIF, TIFF, BMP, RAW).
  *
  * @example
  * ```ts
  * import { Image } from "@cross/image";
  *
- * // Read an image
+ * // Decode an image
  * const data = await Deno.readFile("input.png");
- * const image = await Image.read(data);
+ * const image = await Image.decode(data);
  *
  * // Resize it
  * image.resize({ width: 200, height: 200 });
  *
- * // Save as different format
- * const output = await image.save("jpeg");
+ * // Encode as different format
+ * const output = await image.encode("jpeg");
  * await Deno.writeFile("output.jpg", output);
  * ```
  */

package/esm/mod.js

@@ -2,21 +2,21 @@
  * @module @cross/image
  *
  * A pure JavaScript, dependency-free, cross-runtime image processing library.
- * Supports reading, resizing, and saving common image formats (PNG, JPEG, WebP, GIF, TIFF, BMP, RAW).
+ * Supports decoding, resizing, and encoding common image formats (PNG, JPEG, WebP, GIF, TIFF, BMP, RAW).
  *
  * @example
  * ```ts
  * import { Image } from "@cross/image";
  *
- * // Read an image
+ * // Decode an image
  * const data = await Deno.readFile("input.png");
- * const image = await Image.read(data);
+ * const image = await Image.decode(data);
  *
  * // Resize it
  * image.resize({ width: 200, height: 200 });
  *
- * // Save as different format
- * const output = await image.save("jpeg");
+ * // Encode as different format
+ * const output = await image.encode("jpeg");
  * await Deno.writeFile("output.jpg", output);
  * ```
  */

package/esm/src/formats/ascii.d.ts

@@ -17,7 +17,18 @@ export declare class ASCIIFormat implements ImageFormat {
     private readonly MAGIC_BYTES;
     private readonly CHARSETS;
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode ASCII art to a basic grayscale RGBA image
+     * @param data Raw ASCII art data
+     * @returns Decoded image data with grayscale RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to ASCII art
+     * @param imageData Image data to encode
+     * @param options Optional ASCII encoding options
+     * @returns Encoded ASCII art as UTF-8 bytes
+     */
     encode(imageData: ImageData, options?: ASCIIOptions): Promise<Uint8Array>;
     /**
      * Parse options from the options line

package/esm/src/formats/ascii.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 /**
  * ASCII format handler
  * Converts images to ASCII art text representation
@@ -62,6 +63,11 @@ export class ASCIIFormat {
             data[4] === this.MAGIC_BYTES[4] &&
             data[5] === this.MAGIC_BYTES[5];
     }
+    /**
+     * Decode ASCII art to a basic grayscale RGBA image
+     * @param data Raw ASCII art data
+     * @returns Decoded image data with grayscale RGBA pixels
+     */
     decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid ASCII art signature");
@@ -83,6 +89,8 @@ export class ASCIIFormat {
         // Calculate dimensions
         const height = artLines.length;
         const width = Math.max(...artLines.map((line) => line.length));
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         // Convert ASCII art back to image data
         const imageData = new Uint8Array(width * height * 4);
         const charset = this.CHARSETS[options.charset] || this.CHARSETS.simple;
@@ -111,6 +119,12 @@ export class ASCIIFormat {
         }
         return Promise.resolve({ width, height, data: imageData });
     }
+    /**
+     * Encode RGBA image data to ASCII art
+     * @param imageData Image data to encode
+     * @param options Optional ASCII encoding options
+     * @returns Encoded ASCII art as UTF-8 bytes
+     */
     encode(imageData, options = {}) {
         const { width: targetWidth = 80, charset = "simple", aspectRatio = 0.5, invert = false, } = options;
         // Get character set

package/esm/src/formats/bmp.d.ts

@@ -4,10 +4,27 @@ import type { ImageData, ImageFormat } from "../types.js";
  * Implements a pure JavaScript BMP decoder and encoder
  */
 export declare class BMPFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "bmp";
+    /** MIME type for BMP images */
     readonly mimeType = "image/bmp";
+    /**
+     * Check if the given data is a BMP image
+     * @param data Raw image data to check
+     * @returns true if data has BMP signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode BMP image data to RGBA
+     * @param data Raw BMP image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to BMP format
+     * @param imageData Image data to encode
+     * @returns Encoded BMP image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     private readUint16LE;
     private readUint32LE;

package/esm/src/formats/bmp.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 // Constants for unit conversions
 const INCHES_PER_METER = 39.3701;
 /**
@@ -6,12 +7,14 @@ const INCHES_PER_METER = 39.3701;
  */
 export class BMPFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "bmp"
         });
+        /** MIME type for BMP images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -19,11 +22,21 @@ export class BMPFormat {
             value: "image/bmp"
         });
     }
+    /**
+     * Check if the given data is a BMP image
+     * @param data Raw image data to check
+     * @returns true if data has BMP signature
+     */
     canDecode(data) {
         // BMP signature: 'BM' (0x42 0x4D)
         return data.length >= 2 &&
             data[0] === 0x42 && data[1] === 0x4d;
     }
+    /**
+     * Decode BMP image data to RGBA
+     * @param data Raw BMP image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid BMP signature");
@@ -61,6 +74,8 @@ export class BMPFormat {
         // Handle negative height (top-down bitmap)
         const isTopDown = height < 0;
         const absHeight = Math.abs(height);
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, absHeight);
         // Only support uncompressed BMPs for now
         if (compression !== 0) {
             throw new Error(`Compressed BMP not supported (compression type: ${compression})`);
@@ -94,6 +109,11 @@ export class BMPFormat {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         });
     }
+    /**
+     * Encode RGBA image data to BMP format
+     * @param imageData Image data to encode
+     * @returns Encoded BMP image bytes
+     */
     encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Calculate sizes

package/esm/src/formats/gif.d.ts

@@ -12,12 +12,33 @@ import type { ImageData, ImageFormat, MultiFrameImageData } from "../types.js";
  * - Falls back to runtime APIs when pure-JS fails
  */
 export declare class GIFFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "gif";
+    /** MIME type for GIF images */
     readonly mimeType = "image/gif";
+    /**
+     * Check if this format supports multiple frames (animations)
+     * @returns true for GIF format
+     */
     supportsMultipleFrames(): boolean;
+    /**
+     * Check if the given data is a GIF image
+     * @param data Raw image data to check
+     * @returns true if data has GIF signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode GIF image data to RGBA (first frame only)
+     * @param data Raw GIF image data
+     * @returns Decoded image data with RGBA pixels of first frame
+     */
     decode(data: Uint8Array): Promise<ImageData>;
     private extractMetadata;
+    /**
+     * Encode RGBA image data to GIF format (single frame)
+     * @param imageData Image data to encode
+     * @returns Encoded GIF image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     /**
      * Decode all frames from an animated GIF

package/esm/src/formats/gif.js

@@ -1,5 +1,6 @@
 import { GIFDecoder } from "../utils/gif_decoder.js";
 import { GIFEncoder } from "../utils/gif_encoder.js";
+import { validateImageDimensions } from "../utils/security.js";
 /**
  * GIF format handler
  * Now includes pure-JS implementation with custom LZW compression/decompression
@@ -14,12 +15,14 @@ import { GIFEncoder } from "../utils/gif_encoder.js";
  */
 export class GIFFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "gif"
         });
+        /** MIME type for GIF images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -27,9 +30,18 @@ export class GIFFormat {
             value: "image/gif"
         });
     }
+    /**
+     * Check if this format supports multiple frames (animations)
+     * @returns true for GIF format
+     */
     supportsMultipleFrames() {
         return true;
     }
+    /**
+     * Check if the given data is a GIF image
+     * @param data Raw image data to check
+     * @returns true if data has GIF signature
+     */
     canDecode(data) {
         // GIF signature: "GIF87a" or "GIF89a"
         return data.length >= 6 &&
@@ -38,6 +50,11 @@ export class GIFFormat {
             (data[4] === 0x37 || data[4] === 0x39) && // "7" or "9"
             data[5] === 0x61; // "a"
     }
+    /**
+     * Decode GIF image data to RGBA (first frame only)
+     * @param data Raw GIF image data
+     * @returns Decoded image data with RGBA pixels of first frame
+     */
     async decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid GIF signature");
@@ -46,6 +63,8 @@ export class GIFFormat {
         try {
             const decoder = new GIFDecoder(data);
             const result = decoder.decode();
+            // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+            validateImageDimensions(result.width, result.height);
             // Extract metadata from comment extensions
             const metadata = this.extractMetadata(data);
             return {
@@ -62,6 +81,8 @@ export class GIFFormat {
             const width = this.readUint16LE(data, pos);
             pos += 2;
             const height = this.readUint16LE(data, pos);
+            // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+            validateImageDimensions(width, height);
             const rgba = await this.decodeUsingRuntime(data, width, height);
             const metadata = this.extractMetadata(data);
             return {
@@ -124,6 +145,11 @@ export class GIFFormat {
         }
         return metadata;
     }
+    /**
+     * Encode RGBA image data to GIF format (single frame)
+     * @param imageData Image data to encode
+     * @returns Encoded GIF image bytes
+     */
     async encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Try pure-JS encoder first

package/esm/src/formats/jpeg.d.ts

@@ -4,10 +4,27 @@ import type { ImageData, ImageFormat } from "../types.js";
  * Implements a basic JPEG decoder and encoder
  */
 export declare class JPEGFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "jpeg";
+    /** MIME type for JPEG images */
     readonly mimeType = "image/jpeg";
+    /**
+     * Check if the given data is a JPEG image
+     * @param data Raw image data to check
+     * @returns true if data has JPEG signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode JPEG image data to RGBA
+     * @param data Raw JPEG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to JPEG format
+     * @param imageData Image data to encode
+     * @returns Encoded JPEG image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     private injectMetadata;
     private decodeUsingRuntime;

package/esm/src/formats/jpeg.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 // Constants for unit conversions
 const CM_PER_INCH = 2.54;
 /**
@@ -6,12 +7,14 @@ const CM_PER_INCH = 2.54;
  */
 export class JPEGFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "jpeg"
         });
+        /** MIME type for JPEG images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -19,11 +22,21 @@ export class JPEGFormat {
             value: "image/jpeg"
         });
     }
+    /**
+     * Check if the given data is a JPEG image
+     * @param data Raw image data to check
+     * @returns true if data has JPEG signature
+     */
     canDecode(data) {
         // JPEG signature: FF D8 FF
         return data.length >= 3 &&
             data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff;
     }
+    /**
+     * Decode JPEG image data to RGBA
+     * @param data Raw JPEG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     async decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid JPEG signature");
@@ -78,6 +91,8 @@ export class JPEGFormat {
         if (width === 0 || height === 0) {
             throw new Error("Could not determine JPEG dimensions");
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         // For a pure JS implementation, we'd need to implement full JPEG decoding
         // which is very complex. Instead, we'll use the browser/runtime's decoder.
         const rgba = await this.decodeUsingRuntime(data, width, height);
@@ -88,6 +103,11 @@ export class JPEGFormat {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         };
     }
+    /**
+     * Encode RGBA image data to JPEG format
+     * @param imageData Image data to encode
+     * @returns Encoded JPEG image bytes
+     */
     async encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Try to use runtime encoding if available (better quality)

package/esm/src/formats/png.d.ts

@@ -4,10 +4,27 @@ import type { ImageData, ImageFormat } from "../types.js";
  * Implements a pure JavaScript PNG decoder and encoder
  */
 export declare class PNGFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "png";
+    /** MIME type for PNG images */
     readonly mimeType = "image/png";
+    /**
+     * Check if the given data is a PNG image
+     * @param data Raw image data to check
+     * @returns true if data has PNG signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode PNG image data to RGBA
+     * @param data Raw PNG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to PNG format
+     * @param imageData Image data to encode
+     * @returns Encoded PNG image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     private readUint32;
     private writeUint32;

package/esm/src/formats/png.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 // Constants for unit conversions
 const INCHES_PER_METER = 39.3701;
 /**
@@ -6,12 +7,14 @@ const INCHES_PER_METER = 39.3701;
  */
 export class PNGFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "png"
         });
+        /** MIME type for PNG images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -19,6 +22,11 @@ export class PNGFormat {
             value: "image/png"
         });
     }
+    /**
+     * Check if the given data is a PNG image
+     * @param data Raw image data to check
+     * @returns true if data has PNG signature
+     */
     canDecode(data) {
         // PNG signature: 137 80 78 71 13 10 26 10
         return data.length >= 8 &&
@@ -27,6 +35,11 @@ export class PNGFormat {
             data[4] === 13 && data[5] === 10 &&
             data[6] === 26 && data[7] === 10;
     }
+    /**
+     * Decode PNG image data to RGBA
+     * @param data Raw PNG image data
+     * @returns Decoded image data with RGBA pixels
+     */
     async decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid PNG signature");
@@ -79,6 +92,8 @@ export class PNGFormat {
         if (width === 0 || height === 0) {
             throw new Error("Invalid PNG: missing IHDR chunk");
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         // Concatenate IDAT chunks
         const idatData = this.concatenateChunks(chunks);
         // Decompress data
@@ -92,6 +107,11 @@ export class PNGFormat {
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
         };
     }
+    /**
+     * Encode RGBA image data to PNG format
+     * @param imageData Image data to encode
+     * @returns Encoded PNG image bytes
+     */
     async encode(imageData) {
         const { width, height, data, metadata } = imageData;
         // Prepare IHDR chunk

package/esm/src/formats/raw.d.ts

@@ -10,12 +10,29 @@ import type { ImageData, ImageFormat } from "../types.js";
  * - RGBA pixel data (width * height * 4 bytes)
  */
 export declare class RAWFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "raw";
+    /** MIME type for RAW images */
     readonly mimeType = "image/raw";
     private readonly MAGIC_BYTES;
     private readonly HEADER_SIZE;
+    /**
+     * Check if the given data is a RAW image
+     * @param data Raw image data to check
+     * @returns true if data has RAW signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode RAW image data to RGBA
+     * @param data Raw RAW image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode RGBA image data to RAW format
+     * @param imageData Image data to encode
+     * @returns Encoded RAW image bytes
+     */
     encode(imageData: ImageData): Promise<Uint8Array>;
     private readUint32;
     private writeUint32;

package/esm/src/formats/raw.js

@@ -1,3 +1,4 @@
+import { validateImageDimensions } from "../utils/security.js";
 /**
  * RAW format handler
  * Implements a simple uncompressed RGBA format with a minimal header
@@ -10,12 +11,14 @@
  */
 export class RAWFormat {
     constructor() {
+        /** Format name identifier */
         Object.defineProperty(this, "name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: "raw"
         });
+        /** MIME type for RAW images */
         Object.defineProperty(this, "mimeType", {
             enumerable: true,
             configurable: true,
@@ -35,6 +38,11 @@ export class RAWFormat {
             value: 12
         }); // 4 bytes magic + 4 bytes width + 4 bytes height
     }
+    /**
+     * Check if the given data is a RAW image
+     * @param data Raw image data to check
+     * @returns true if data has RAW signature
+     */
     canDecode(data) {
         // Check if data has at least header size and matches magic bytes
         if (data.length < this.HEADER_SIZE) {
@@ -45,6 +53,11 @@ export class RAWFormat {
             data[2] === this.MAGIC_BYTES[2] &&
             data[3] === this.MAGIC_BYTES[3];
     }
+    /**
+     * Decode RAW image data to RGBA
+     * @param data Raw RAW image data
+     * @returns Decoded image data with RGBA pixels
+     */
     decode(data) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid RAW signature");
@@ -56,6 +69,8 @@ export class RAWFormat {
         if (width <= 0 || height <= 0) {
             throw new Error(`Invalid RAW dimensions: ${width}x${height}`);
         }
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        validateImageDimensions(width, height);
         const expectedDataLength = width * height * 4;
         const actualDataLength = data.length - this.HEADER_SIZE;
         if (actualDataLength !== expectedDataLength) {
@@ -66,6 +81,11 @@ export class RAWFormat {
         pixelData.set(data.subarray(this.HEADER_SIZE));
         return Promise.resolve({ width, height, data: pixelData });
     }
+    /**
+     * Encode RGBA image data to RAW format
+     * @param imageData Image data to encode
+     * @returns Encoded RAW image bytes
+     */
     encode(imageData) {
         const { width, height, data } = imageData;
         // Validate input

package/esm/src/formats/tiff.d.ts

@@ -14,10 +14,26 @@ export interface TIFFEncodeOptions {
  * Supports multi-page TIFF files.
  */
 export declare class TIFFFormat implements ImageFormat {
+    /** Format name identifier */
     readonly name = "tiff";
+    /** MIME type for TIFF images */
     readonly mimeType = "image/tiff";
+    /**
+     * Check if this format supports multiple frames (pages)
+     * @returns true for TIFF format
+     */
     supportsMultipleFrames(): boolean;
+    /**
+     * Check if the given data is a TIFF image
+     * @param data Raw image data to check
+     * @returns true if data has TIFF signature
+     */
     canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode TIFF image data to RGBA (first page only)
+     * @param data Raw TIFF image data
+     * @returns Decoded image data with RGBA pixels of first page
+     */
     decode(data: Uint8Array): Promise<ImageData>;
     encode(imageData: ImageData, options?: unknown): Promise<Uint8Array>;
     /**