@platformatic/image-optimizer 0.0.1 → 0.1.0

package/README.md

@@ -1,10 +1,70 @@
-# @platformatic/skeleton
+# @platformatic/image-optimizer
+
+Detect, fetch, and optimize images with [`sharp`](https://sharp.pixelplumbing.com/), with optional queue-backed processing via [`@platformatic/job-queue`](https://github.com/platformatic/job-queue).
 
 ## Features
 
+- Detects image type from file signatures (magic bytes)
+- Optimizes raster images (`jpeg`, `png`, `webp`, `avif`)
+- Prevents animated image optimization
+- Supports optional SVG passthrough
+- Provides `fetchAndOptimize()` for URL-based workflows (via `undici.request()`)
+- Provides queue APIs (`Queue`, `createQueue`) powered by [`@platformatic/job-queue`](https://www.npmjs.com/package/@platformatic/job-queue) for distributed work
+- Throws structured `ImageError` objects
+
 ## Installation
 
-## Getting Started
+```bash
+npm i @platformatic/image-optimizer
+```
+
+## API
+
+### `optimize(buffer, width, quality, allowSVG = false)`
+
+Optimizes an input image buffer.
+
+- `width`: target max width (`withoutEnlargement` is enabled)
+- `quality`: output quality used by format-specific encoders
+- `allowSVG`: when `false` (default), SVG images are not optimized and it throws an error
+
+### `fetchAndOptimize(url, width, quality, allowSVG = false)`
+
+Fetches an image and then runs `optimize()`.
+Returns:
+
+- `buffer`: optimized image buffer
+- `contentType`: upstream `content-type` response header (or `null`)
+- `cacheControl`: upstream `cache-control` response header (or `null`)
+
+### `detectImageType(buffer)`
+
+Returns the detected image type (for example `jpeg`, `png`, `webp`) or `null`.
+
+### `Queue`
+
+Queue-backed optimizer powered by [`@platformatic/job-queue`](https://www.npmjs.com/package/@platformatic/job-queue).
+
+Methods:
+
+- `start()`
+- `stop()`
+- `optimize(buffer, width, quality, allowSVG?)` (auto-starts on first use)
+- `fetchAndOptimize(url, width, quality, allowSVG?)` (auto-starts on first use)
+
+### `createQueue(options?)`
+
+Creates and starts a `Queue` instance.
+
+## Example
+
+```ts
+import { createQueue, fetchAndOptimize } from '@platformatic/image-optimizer'
+
+const queue = await createQueue({ concurrency: 2 })
+const { buffer } = await fetchAndOptimize('https://example.com/image.jpg', 800, 75)
+await queue.stop()
+```
 
 ## License
 

package/dist/definitions.d.ts

@@ -1,4 +1,5 @@
 export declare const imageTypes: [string, number[]][];
+export declare const imageMimeTypes: Record<string, string>;
 export declare const animatableTypes: string[];
 export declare const bypassTypes: string[];
 export declare const maxImageSize = 268402689;

package/dist/definitions.js

@@ -16,6 +16,18 @@ export const imageTypes = [
     ['svg_2', [0x3c, 0x73, 0x76, 0x67]],
     ['jxl_1', [0xff, 0x0a]]
 ];
+export const imageMimeTypes = {
+    avif: 'image/avif',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    ico: 'image/x-icon',
+    icns: 'image/icns',
+    bmp: 'image/bmp',
+    heic: 'image/heic',
+    jxl: 'image/jxl'
+};
 export const animatableTypes = ['webp', 'png', 'gif'];
 export const bypassTypes = ['svg', 'ico', 'icns', 'bmp', 'jxl', 'heic'];
 export const maxImageSize = 268_402_689;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export declare function detectImageType(buffer: Buffer): string | null;
-export declare function optimize(buffer: Buffer, width: number, quality: number, allowSVG?: boolean): Promise<Buffer>;
-export declare function fetchAndOptimize(url: string, width: number, quality: number, allowSVG?: boolean): Promise<Buffer>;
+export * from './definitions.ts';
+export * from './operations.ts';
+export * from './queue.ts';
+export * from './types.ts';

package/dist/index.js

@@ -1,66 +1,4 @@
-import isAnimated from 'is-animated';
-import sharp from 'sharp';
-import { animatableTypes, bypassTypes, imageTypes, maxImageSize } from "./definitions.js";
-import { ImageError } from "./errors.js";
-export function detectImageType(buffer) {
-    for (let e = 0; e < imageTypes.length; e++) {
-        const [key, bytes] = imageTypes[e];
-        if (buffer.length < bytes.length) {
-            continue;
-        }
-        let match = true;
-        for (let i = 0; i < bytes.length; i++) {
-            const s = bytes[i];
-            if (s !== -1 && buffer[i] !== s) {
-                match = false;
-                break;
-            }
-        }
-        if (!match) {
-            continue;
-        }
-        const index = key.indexOf('_');
-        return index === -1 ? key : key.slice(0, index);
-    }
-    return null;
-}
-export async function optimize(buffer, width, quality, allowSVG = false) {
-    const upstreamType = detectImageType(buffer);
-    if (!upstreamType) {
-        throw new ImageError(400, 'Invalid input image');
-    }
-    if (animatableTypes.includes(upstreamType) && isAnimated(buffer)) {
-        throw new ImageError(400, 'Unable to optimize and animated image');
-    }
-    if (upstreamType === 'svg' && !allowSVG) {
-        throw new ImageError(400, 'Optimization of SVG images is not allowed');
-    }
-    if (bypassTypes.includes(upstreamType)) {
-        return buffer;
-    }
-    const transformer = sharp(buffer, { limitInputPixels: maxImageSize }).rotate();
-    transformer.resize({ width, withoutEnlargement: true });
-    if (upstreamType === 'avif') {
-        transformer.avif({ quality: Math.max(quality - 20, 1), effort: 3 });
-    }
-    else if (upstreamType === 'webp') {
-        transformer.webp({ quality });
-    }
-    else if (upstreamType === 'png') {
-        transformer.png({ quality });
-    }
-    else if (upstreamType === 'jpeg') {
-        transformer.jpeg({ quality, mozjpeg: true });
-    }
-    return transformer.toBuffer();
-}
-export async function fetchAndOptimize(url, width, quality, allowSVG = false) {
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw new ImageError(response.statusText, `Unable to fetch the image. [HTTP ${response.statusText}]`, {
-            response: await response.text()
-        });
-    }
-    const buffer = Buffer.from(await response.arrayBuffer());
-    return optimize(buffer, width, quality, allowSVG);
-}
+export * from "./definitions.js";
+export * from "./operations.js";
+export * from "./queue.js";
+export * from "./types.js";

package/dist/operations.d.ts

@@ -0,0 +1,4 @@
+import type { Image } from './types.ts';
+export declare function detectImageType(buffer: Buffer): string | null;
+export declare function optimize(buffer: Buffer, width: number, quality: number, allowSVG?: boolean): Promise<Buffer>;
+export declare function fetchAndOptimize(url: string, width: number, quality: number, allowSVG?: boolean): Promise<Image<Buffer>>;

package/dist/operations.js

@@ -0,0 +1,72 @@
+import { BadGatewayError, BadRequestError } from 'http-errors-enhanced';
+import isAnimated from 'is-animated';
+import sharp from 'sharp';
+import { request } from 'undici';
+import { animatableTypes, bypassTypes, imageTypes, maxImageSize } from "./definitions.js";
+export function detectImageType(buffer) {
+    for (let e = 0; e < imageTypes.length; e++) {
+        const [key, bytes] = imageTypes[e];
+        if (buffer.length < bytes.length) {
+            continue;
+        }
+        let match = true;
+        for (let i = 0; i < bytes.length; i++) {
+            const s = bytes[i];
+            if (s !== -1 && buffer[i] !== s) {
+                match = false;
+                break;
+            }
+        }
+        if (!match) {
+            continue;
+        }
+        const index = key.indexOf('_');
+        return index === -1 ? key : key.slice(0, index);
+    }
+    return null;
+}
+export async function optimize(buffer, width, quality, allowSVG = false) {
+    const upstreamType = detectImageType(buffer);
+    if (!upstreamType) {
+        throw new BadRequestError('Invalid input image');
+    }
+    if (animatableTypes.includes(upstreamType) && isAnimated(buffer)) {
+        throw new BadRequestError('Unable to optimize and animated image');
+    }
+    if (upstreamType === 'svg' && !allowSVG) {
+        throw new BadRequestError('SVG images are not allowed');
+    }
+    if (bypassTypes.includes(upstreamType)) {
+        return buffer;
+    }
+    const transformer = sharp(buffer, { limitInputPixels: maxImageSize }).rotate();
+    transformer.resize({ width, withoutEnlargement: true });
+    if (upstreamType === 'avif') {
+        transformer.avif({ quality: Math.max(quality - 20, 1), effort: 3 });
+    }
+    else if (upstreamType === 'webp') {
+        transformer.webp({ quality });
+    }
+    else if (upstreamType === 'png') {
+        transformer.png({ quality });
+    }
+    else if (upstreamType === 'jpeg') {
+        transformer.jpeg({ quality, mozjpeg: true });
+    }
+    return transformer.toBuffer();
+}
+export async function fetchAndOptimize(url, width, quality, allowSVG = false) {
+    const response = await request(url);
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+        throw new BadGatewayError(`Unable to fetch the image. [HTTP ${response.statusCode}]`, {
+            response: await response.body.text()
+        });
+    }
+    const contentType = response.headers['content-type'];
+    const cacheControl = response.headers['cache-control'];
+    return {
+        buffer: await optimize(Buffer.from(await response.body.arrayBuffer()), width, quality, allowSVG),
+        contentType: typeof contentType === 'string' ? contentType : null,
+        cacheControl: typeof cacheControl === 'string' ? cacheControl : null
+    };
+}

package/dist/queue.d.ts

@@ -0,0 +1,18 @@
+import type { Queue as JobQueue, MemoryStorage } from '@platformatic/job-queue';
+import type { Image, QueueOptions } from './types.ts';
+interface JobQueueModule {
+    Queue: typeof JobQueue;
+    MemoryStorage: typeof MemoryStorage;
+}
+export declare class Queue {
+    #private;
+    protected static jobQueueModulePromise: Promise<JobQueueModule> | null;
+    constructor(options?: QueueOptions);
+    protected static loadJobQueueModule(): Promise<JobQueueModule>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    optimize(buffer: Buffer, width: number, quality: number, allowSVG?: boolean): Promise<Buffer>;
+    fetchAndOptimize(url: string, width: number, quality: number, allowSVG?: boolean): Promise<Image<Buffer>>;
+}
+export declare function createQueue(options?: QueueOptions): Promise<Queue>;
+export {};

package/dist/queue.js

@@ -0,0 +1,111 @@
+import { InternalServerError } from 'http-errors-enhanced';
+import { randomUUID } from 'node:crypto';
+import { fetchAndOptimize, optimize } from "./operations.js";
+export class Queue {
+    static jobQueueModulePromise = null;
+    #queue = null;
+    #started = false;
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    static async loadJobQueueModule() {
+        if (this.jobQueueModulePromise) {
+            return this.jobQueueModulePromise;
+        }
+        this.jobQueueModulePromise = import('@platformatic/job-queue');
+        return this.jobQueueModulePromise;
+    }
+    async start() {
+        if (this.#started) {
+            return;
+        }
+        const queueClass = this.constructor;
+        let jobQueueModule;
+        try {
+            jobQueueModule = await queueClass.loadJobQueueModule();
+        }
+        catch (error) {
+            if (error.code === 'ERR_MODULE_NOT_FOUND' &&
+                error.message.includes("'@platformatic/job-queue'")) {
+                throw new InternalServerError('The Queue requires @platformatic/job-queue to be installed', {
+                    cause: error
+                });
+            }
+            throw error;
+        }
+        const { Queue: JobQueue, MemoryStorage } = jobQueueModule;
+        const storage = (this.#options.storage ?? new MemoryStorage());
+        const queue = new JobQueue({
+            storage,
+            workerId: this.#options.workerId,
+            concurrency: this.#options.concurrency,
+            blockTimeout: this.#options.blockTimeout,
+            maxRetries: this.#options.maxRetries,
+            visibilityTimeout: this.#options.visibilityTimeout,
+            processingQueueTTL: this.#options.processingQueueTTL,
+            resultTTL: this.#options.resultTTL
+        });
+        queue.execute(this.#execute.bind(this));
+        await queue.start();
+        this.#queue = queue;
+        this.#started = true;
+    }
+    async stop() {
+        if (!this.#queue || !this.#started) {
+            return;
+        }
+        await this.#queue.stop();
+        this.#queue = null;
+        this.#started = false;
+    }
+    async optimize(buffer, width, quality, allowSVG = false) {
+        const result = await this.#enqueueAndWait({
+            type: 'optimize',
+            buffer: buffer.toString('base64'),
+            width,
+            quality,
+            allowSVG
+        });
+        return Buffer.from(result.buffer, 'base64');
+    }
+    async fetchAndOptimize(url, width, quality, allowSVG = false) {
+        const result = await this.#enqueueAndWait({
+            type: 'fetchAndOptimize',
+            url,
+            width,
+            quality,
+            allowSVG
+        });
+        return {
+            buffer: Buffer.from(result.buffer, 'base64'),
+            contentType: result.contentType ?? null,
+            cacheControl: result.cacheControl ?? null
+        };
+    }
+    async #enqueueAndWait(payload) {
+        if (!this.#queue || !this.#started) {
+            await this.start();
+        }
+        return this.#queue.enqueueAndWait(randomUUID(), payload);
+    }
+    async #execute({ payload }) {
+        if (payload.type === 'optimize') {
+            const optimizedBuffer = await optimize(Buffer.from(payload.buffer, 'base64'), payload.width, payload.quality, payload.allowSVG);
+            return {
+                buffer: optimizedBuffer.toString('base64')
+            };
+        }
+        const optimizedImage = await fetchAndOptimize(payload.url, payload.width, payload.quality, payload.allowSVG);
+        return {
+            buffer: optimizedImage.buffer.toString('base64'),
+            contentType: optimizedImage.contentType,
+            cacheControl: optimizedImage.cacheControl
+        };
+    }
+}
+export async function createQueue(options = {}) {
+    const queue = new Queue(options);
+    await queue.start();
+    return queue;
+}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export type ErrorProperties = {
+    cause?: Error;
+} & Record<string, any>;
+export interface OptimizeJobPayload {
+    type: 'optimize';
+    buffer: string;
+    width: number;
+    quality: number;
+    allowSVG: boolean;
+}
+export interface FetchAndOptimizeJobPayload {
+    type: 'fetchAndOptimize';
+    url: string;
+    width: number;
+    quality: number;
+    allowSVG: boolean;
+}
+export type QueuePayload = OptimizeJobPayload | FetchAndOptimizeJobPayload;
+export interface QueueOptions {
+    storage?: unknown;
+    workerId?: string;
+    concurrency?: number;
+    blockTimeout?: number;
+    maxRetries?: number;
+    visibilityTimeout?: number;
+    processingQueueTTL?: number;
+    resultTTL?: number;
+}
+export interface Job {
+    payload: QueuePayload;
+}
+export interface Image<T = Buffer | string> {
+    buffer: T;
+    contentType?: string | null;
+    cacheControl?: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -1,2 +1,2 @@
-export const name = "image-optimizer";
-export const version = "0.0.1";
+export const name = "@platformatic/image-optimizer";
+export const version = "0.1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformatic/image-optimizer",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Detect, fetch, and optimize images with sharp, with optional queue-backed processing via @platformatic/job-queue.",
   "homepage": "https://github.com/platformatic/image-optimizer",
   "author": "Platformatic Inc. <oss@platformatic.dev> (https://platformatic.dev)",
@@ -22,7 +22,42 @@
   "type": "module",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "dependencies": {
+    "http-errors-enhanced": "^4.0.2",
+    "is-animated": "^2.0.2",
+    "sharp": "^0.34.5",
+    "undici": "^7.22.0"
+  },
+  "optionalDependencies": {
+    "@platformatic/job-queue": "^0.3.0",
+    "iovalkey": "^0.3.3"
+  },
+  "devDependencies": {
+    "@platformatic/tsconfig": "^0.2.0",
+    "@types/node": "^25.3.0",
+    "@types/semver": "^7.7.1",
+    "c8": "^10.1.3",
+    "cleaner-spec-reporter": "^1.0.3",
+    "eslint": "^9.39.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "neostandard": "^0.12.2",
+    "prettier": "^3.8.1",
+    "prettier-plugin-space-before-function-paren": "^0.0.10",
+    "semver": "^7.7.4",
+    "typescript": "^5.9.3"
+  },
   "engines": {
     "node": ">= 22.19.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.base.json",
+    "postbuild": "node scripts/postbuild.ts",
+    "lint": "eslint --cache",
+    "typecheck": "tsc -p . --noEmit",
+    "format": "prettier -w src test scripts",
+    "fixtures": "node scripts/generate-fixtures.ts",
+    "test": "c8 -c test/config/c8-local.json node  --test --test-reporter=cleaner-spec-reporter --test-timeout=60000 'test/**/*.test.ts'",
+    "test:ci": "c8 -c test/config/c8-ci.json node  --test --test-reporter=cleaner-spec-reporter --test-timeout=60000 'test/**/*.test.ts'",
+    "ci": "npm run build && npm run lint && npm run test:ci"
   }
 }

package/dist/errors.d.ts

@@ -1,7 +0,0 @@
-export type ErrorProperties = {
-    cause?: Error;
-} & Record<string, any>;
-export declare class ImageError extends Error {
-    code: string | number;
-    constructor(code: string | number, message: string, { cause, ...rest }?: ErrorProperties);
-}

package/dist/errors.js

@@ -1,17 +0,0 @@
-export class ImageError extends Error {
-    code;
-    constructor(code, message, { cause, ...rest } = {}) {
-        super(message, cause ? { cause } : {});
-        this.name = 'ImageError';
-        this.code = code;
-        Reflect.defineProperty(this, 'message', { enumerable: true });
-        Reflect.defineProperty(this, 'code', { enumerable: true });
-        if ('stack' in this) {
-            Reflect.defineProperty(this, 'stack', { enumerable: true });
-        }
-        for (const [key, value] of Object.entries(rest)) {
-            Reflect.defineProperty(this, key, { value, enumerable: true });
-        }
-        Error.captureStackTrace(this, this.constructor);
-    }
-}