feat: add imagor library with filters and path builder

Author: soorq

libs/imagor/src/imagor.module-definition.ts

@@ -0,0 +1,16 @@
+import { ConfigurableModuleBuilder } from '@nestjs/common';
+import type { ImagorModuleOptions } from './interfaces';
+
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<ImagorModuleOptions>()
+        .setClassMethodName('forRoot')
+        .setExtras(
+            {
+                global: true,
+            },
+            (definition, extras) => ({
+                ...definition,
+                global: extras.global,
+            }),
+        )
+        .build();

libs/imagor/src/imagor.module.ts

@@ -0,0 +1,9 @@
+import { Module } from '@nestjs/common';
+import { ConfigurableModuleClass } from './imagor.module-definition';
+import { ImagorService } from './imagor.service';
+
+@Module({
+    providers: [ImagorService],
+    exports: [ImagorService],
+})
+export class ImagorModule extends ConfigurableModuleClass {}

libs/imagor/src/imagor.service.ts

@@ -0,0 +1,75 @@
+import { Inject, Injectable, StreamableFile } from '@nestjs/common';
+import { MODULE_OPTIONS_TOKEN } from './imagor.module-definition';
+import type { ImagorModuleOptions, Filters } from './interfaces';
+import { createHmac } from 'crypto';
+import { HttpService } from '@nestjs/axios';
+import { ImagorPathBuilder } from './utils';
+import { firstValueFrom } from 'rxjs';
+
+@Injectable()
+export class ImagorService {
+    constructor(
+        @Inject(MODULE_OPTIONS_TOKEN)
+        private options: ImagorModuleOptions,
+        private readonly http: HttpService,
+    ) {}
+
+    prepare(path: string): ImagorPathBuilder {
+        const builder = new ImagorPathBuilder(path, this.options.storageRoot);
+        if (this.options.filters) builder.applyFilters(this.options.filters);
+        return builder;
+    }
+
+    async buffer(path: string, preset?: string): Promise<Buffer> {
+        const url = this.buildUrl(path, preset);
+        const { data } = await firstValueFrom(this.http.get(url, { responseType: 'arraybuffer' }));
+        return Buffer.from(data);
+    }
+
+    async response(path: string, preset?: string): Promise<StreamableFile> {
+        const url = this.buildUrl(path, preset);
+        const { data, headers } = await firstValueFrom(
+            this.http.get(url, { responseType: 'stream' }),
+        );
+
+        return new StreamableFile(data, {
+            type: headers['content-type'] as string,
+            length: headers['content-length'] ? Number(headers['content-length']) : undefined,
+        });
+    }
+
+    private buildUrl(path: string, presetOrFilters?: string | any): string {
+        const builder = new ImagorPathBuilder(path, this.options.storageRoot);
+
+        if (this.options.filters) builder.applyFilters(this.options.filters);
+
+        if (typeof presetOrFilters === 'string') {
+            builder.applyFilters(this.options.presets?.[presetOrFilters] || {});
+        } else if (presetOrFilters) {
+            builder.applyFilters(presetOrFilters);
+        }
+
+        const transformPath = builder.build();
+        const signature = this.sign(transformPath);
+        const host = this.options.url.replace(/\/+$/, '');
+
+        return `${host}/${signature}/${transformPath}`;
+    }
+
+    private sign(path: string): string {
+        if (!this.options.secret) return 'unsafe';
+
+        return createHmac('sha1', this.options.secret)
+            .update(path)
+            .digest('base64')
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_');
+    }
+
+    private resolveFilters(localFilters?: Filters): Filters {
+        return {
+            ...this.options.filters,
+            ...localFilters,
+        };
+    }
+}

libs/imagor/src/index.ts

@@ -0,0 +1,2 @@
+export { ImagorModule } from './imagor.module';
+export { ImagorService } from './imagor.service';

libs/imagor/src/interfaces/filters.interface.ts

@@ -0,0 +1,141 @@
+import type { Format } from './formats.interface';
+
+/**
+ * Набор фильтров и трансформаций Imagor.
+ * Порядок применения фильтров в URL обычно соответствует порядку их перечисления.
+ * @see https://github.com/cshum/imagor#filters
+ */
+export interface Filters {
+    /**
+     * Устанавливает качество выходного изображения.
+     * @param {number} quality Число от 0 до 100.
+     */
+    quality?: number;
+
+    /**
+     * Принудительно устанавливает формат выходного изображения.
+     * WebP и AVIF рекомендуются для лучшего сжатия.
+     */
+    format?: Format;
+
+    /**
+     * Если true, автоматически конвертирует изображения с прозрачностью в JPEG,
+     * заменяя прозрачные области фоном (белым по умолчанию).
+     */
+    autojpg?: boolean;
+
+    /** Удаляет EXIF метаданные из выходного изображения. Полезно для приватности и уменьшения размера. */
+    strip_exif?: boolean;
+
+    /** Удаляет ICC профили цвета. */
+    strip_icc?: boolean;
+
+    /**
+     * Регулирует яркость изображения.
+     * @param {number} brightness Число от -100 до 100. Положительные — ярче, отрицательные — темнее.
+     */
+    brightness?: number;
+
+    /**
+     * Регулирует контрастность изображения.
+     * @param {number} contrast Число от -100 до 100.
+     */
+    contrast?: number;
+
+    /** Преобразует изображение в черно-белое (grayscale). */
+    grayscale?: boolean;
+
+    /**
+     * Настройка цветовых каналов RGB.
+     * @property {number} r Красный (-100 до 100)
+     * @property {number} g Зеленый (-100 до 100)
+     * @property {number} b Синий (-100 до 100)
+     */
+    rgb?: { r: number; g: number; b: number };
+
+    /**
+     * Изменяет общую насыщенность цветов.
+     * @param {number} proportion Число от 0 до 100.
+     */
+    proportion?: number;
+
+    /**
+     * Применяет размытие Гаусса.
+     * Можно передать число (радиус) или объект для более точной настройки сигмы.
+     */
+    blur?: number | { radius: number; sigma?: number };
+
+    /**
+     * Повышает резкость изображения.
+     * @property {number} amount Степень резкости.
+     * @property {number} radius Радиус фильтра.
+     * @property {number} threshold Порог срабатывания.
+     */
+    sharpen?: {
+        amount: number;
+        radius: number;
+        threshold: number;
+    };
+
+    /**
+     * Добавляет шум на изображение.
+     * @param {number} noise Уровень шума от 0 до 100.
+     */
+    noise?: number;
+
+    /** Поворачивает изображение на заданный угол по часовой стрелке. */
+    rotate?: 90 | 180 | 270;
+
+    /**
+     * Определяет цвет заполнения пустых областей при использовании режима 'fit-in'.
+     * @example 'ff0000' (hex), 'white' (name) или 'auto' (главный цвет изображения).
+     */
+    fill?: string;
+
+    /** Устанавливает цвет фона для прозрачных изображений (например, PNG). */
+    background_color?: string;
+
+    /**
+     * Наложение водяного знака поверх основного изображения.
+     */
+    watermark?: {
+        /** Путь к файлу водяного знака в хранилище. */
+        image: string;
+        /** Позиция по горизонтали или смещение в пикселях. */
+        x?: number | 'center' | 'left' | 'right';
+        /** Позиция по вертикали или смещение в пикселях. */
+        y?: number | 'center' | 'top' | 'bottom';
+        /** Прозрачность водяного знака (0 - прозрачный, 100 - непрозрачный). */
+        alpha?: number;
+        /** Относительная ширина знака в процентах (0.0 - 1.0) от основного изображения. */
+        w_ratio?: number;
+        /** Относительная высота знака в процентах (0.0 - 1.0). */
+        h_ratio?: number;
+    };
+
+    /**
+     * Указывает точку фокуса для кропа.
+     * Полезно, если вы знаете координаты лица или важного объекта.
+     */
+    focal?: { x: number; y: number };
+
+    /**
+     * Скругление углов изображения.
+     * @property {number} radius Радиус скругления в пикселях.
+     * @property {string} color Цвет заливки углов (например, 'transparent' или 'ffffff').
+     */
+    round_corner?: {
+        radius: number;
+        color?: string;
+    };
+
+    /**
+     * Ограничивает размер файла (в байтах). Imagor будет снижать качество, пока не впишется в лимит.
+     */
+    max_bytes?: number;
+
+    /**
+     * Запрещает увеличивать изображение, если его исходные размеры меньше запрошенных (width/height).
+     */
+    no_upscale?: boolean;
+}

libs/imagor/src/interfaces/formats.interface.ts

@@ -0,0 +1,10 @@
+export const FORMATS = {
+    JPEG: 'jpeg',
+    PNG: 'png',
+    WEBP: 'webp',
+    AVIF: 'avif',
+    JP2: 'jp2',
+    GIF: 'gif',
+} as const;
+
+export type Format = (typeof FORMATS)[keyof typeof FORMATS];

libs/imagor/src/interfaces/index.ts

@@ -0,0 +1,2 @@
+export type * from './module.interface';
+export type * from './filters.interface';

libs/imagor/src/interfaces/module.interface.ts

@@ -0,0 +1,27 @@
+import type { Filters } from './filters.interface';
+
+/**
+ * Опции конфигурации модуля Imagor
+ */
+export interface ImagorModuleOptions {
+    /** Базовый URL вашего инстанса Imagor (например, https://imagor.example.com) */
+    url: string;
+
+    /** Секретный ключ для генерации HMAC подписи (безопасные URL) */
+    secret?: string;
+
+    /** Глобальные фильтры, которые будут применяться ко всем изображениям по умолчанию */
+    filters?: Filters;
+
+    /** Базовый путь в S3/хранилище (например, 'products/') */
+    storageRoot?: string;
+
+    /**
+     * Именованные пресеты для часто используемых трансформаций.
+     * @example { 'thumb': { width: 150, height: 150, smart: true } }
+     */
+    presets?: Record<string, Filters>;
+
+    /** Включает логирование процесса генерации URL для отладки */
+    debug?: boolean;
+}