By default images are now prerendered to serve request much faster

Author: luca-vogels

ImageConverter.d.ts

@@ -0,0 +1,57 @@
+/// <reference types="node" />
+import { ImageStorage } from "./ImageStorage";
+export type ImageInfo = {
+    imageData: Buffer;
+    format: string;
+    mimeType: string;
+};
+export type PrerenderOptions = {
+    /** Subdirectories to prerender (relative to srcDir) [Defaults to '.' to render all whole srcDir] */
+    subDirs?: string | string[];
+    /** Factor to scale images by (multiplier applied to width and height for each step) [Defaults to 1.5] */
+    scaleFactor?: number;
+    /** If subdirectories should be recursively prerendered too (Defaults to true) */
+    recursive?: boolean;
+    /** List of relative path prefixes starting inside srcDir that should not be optimized.
+     * Subdirectories starting with underscore '_' won't be optimized.
+     * Defaults to ["./favicons"].
+     */
+    exlucePrefixes?: string[];
+    /** If true, the start and end of the pre-rendering process will be logged (because takes up high hardware utilization).
+     * Defaults to true.
+     */
+    message?: boolean;
+};
+export type ImageConverterOptions = {
+    /** Minimum pixel width of image to generate / cache.
+     * Defaults to 32.
+     */
+    minImageWidth?: number;
+    /** Maxmimum pixel width of image to generate / cache.
+     * Defaults to 4096 (4K).
+     */
+    maxImageWidth?: number;
+};
+export declare class ImageConverter {
+    readonly minImageWidth: number;
+    readonly maxImageWidth: number;
+    constructor(options?: ImageConverterOptions);
+    /**
+     * Loads an image from the given file path, resizes it to the given width and converts it to the given format.
+     * @param filePath Path to image file.
+     * @param width Width in pixels of available space for image.
+     * @param format Format of returned image.
+     * @returns Promise that resolves to an object containing the image data, format and mime type.
+     */
+    convertImage(filePath: string, width: number, format: 'avif' | 'webp' | 'jpg' | 'png' | 'gif' | 'heif' | 'tiff' | 'tif'): Promise<ImageInfo>;
+    private _collectImagesToConvert;
+    private _prerender;
+    /**
+     * Pre-renders images in the given directory in all sizes and formats,
+     * and stores them in the given storage.
+     * @param storage Storage to store images in.
+     * @param srcDir Path to directory that contains the images.
+     * @param options Options for pre-rendering.
+     */
+    prerender(storage: ImageStorage, srcDir: string, options?: PrerenderOptions): Promise<void>;
+}

ImageConverter.js

@@ -0,0 +1,53 @@
+import { NextFunction, Request, Response } from "express";
+import { ImageConverterOptions } from "./ImageConverter";
+export type ImageRequestHandlerOptions = ImageConverterOptions & {
+    /** Path relative to project root where images are located (subdirectories starting with underscore '_' won't be optimized) */
+    srcDir: string;
+    /** URI prefix */
+    uriPrefix: string;
+    /** Factor to scale images by (multiplier applied to width and height for each step) [Defaults to 1.5] */
+    scaleFactor?: number;
+    /** Pulblic HTTP cache time in seconds.
+     * Can be undefined or null to disable public HTTP caching.
+     * Defaults to 3600 (1 hour).
+     */
+    httpCacheTime?: number | null;
+    /** Path to directory relative to project root where images should be cached.
+     * Leave empty to disable caching.
+     * Defaults to "./cache"
+     */
+    cacheDir?: string;
+    /** Maximum cache size in MB.
+     * Defaults to 1000 MB.
+     */
+    cacheSize?: number;
+    /** If true, images will be pre-rendered on startup
+     * which can take a while and uses more storage but will speed up requests.
+     * (subdirectories starting with underscore '_' won't be optimized)
+     * Defaults to true.
+     */
+    prerender?: boolean;
+    /** Path relative to project root where pre-rendered images should be stored.
+     * If empty, images will be pre-rendered in place where original image is locaded (uses a subdirectory per original image).
+     * Defaults to "./.prerendered"
+     */
+    prerenderOutputDir?: string;
+    /** If true, the start and end of the pre-rendering process will be logged (because takes up high hardware utilization).
+     * Defaults to true.
+     */
+    prerenderMessage?: boolean;
+    /** List of path prefixes starting inside srcDir that should not be optimized.
+     * Subdirectories starting with underscore '_' won't be optimized.
+     * Defaults to ["./favicons"].
+     */
+    exludePrefix?: string[];
+};
+/**
+ * Returns a request handler (req, res, next) => void that will serve optimized images.
+ * It supports different search parameters:
+ * - w: width in pixels of available space for image (default: 1024)
+ * - f: format of returned image (jpg, png, webp, etc.)
+ * @param options Options for image optimization
+ * @returns Request handler that can be passed e.g. to express
+ */
+export declare function ImageRequestHandler(options: ImageRequestHandlerOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;

ImageRequestHandler.d.ts

@@ -0,0 +1,137 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageRequestHandler = void 0;
+var path_1 = __importDefault(require("path"));
+var lup_root_1 = require("lup-root");
+var ImageConverter_1 = require("./ImageConverter");
+var index_1 = require("./index");
+var ImageStorage_1 = require("./ImageStorage");
+/**
+ * Returns a request handler (req, res, next) => void that will serve optimized images.
+ * It supports different search parameters:
+ * - w: width in pixels of available space for image (default: 1024)
+ * - f: format of returned image (jpg, png, webp, etc.)
+ * @param options Options for image optimization
+ * @returns Request handler that can be passed e.g. to express
+ */
+function ImageRequestHandler(options) {
+    var _this = this;
+    var scaleFactor = options.scaleFactor || index_1.OptimizerSettings.DEFAULT_SCALE_FACTOR;
+    scaleFactor = scaleFactor > 1.0 ? scaleFactor : ((scaleFactor == 1.0 || scaleFactor == 0.0) ? 1.5 : 1.0 / scaleFactor); // same as in OptimizedImage
+    var httpCacheSec = options.httpCacheTime != null ? options.httpCacheTime || index_1.OptimizerSettings.DEFAULT_HTTP_CACHE_SEC : null;
+    var optimizer = new ImageConverter_1.ImageConverter(options);
+    // storage for caching images
+    var cacheStorage = options.cacheDir !== '' ? new ImageStorage_1.ImageCacheStorage({
+        cacheDir: options.cacheDir,
+        cacheSize: options.cacheSize,
+    }) : null;
+    // storage for pre-rendered images
+    var prerenderStorage = !options.prerender ? null : (options.prerenderOutputDir !== '' ? new ImageStorage_1.ImageDirectoryStorage({
+        dirPath: options.prerenderOutputDir || index_1.OptimizerSettings.DEFAULT_PREDENDER_OUTPUT_DIRECTORY,
+    }) : new ImageStorage_1.ImageInPlaceStorage());
+    // prerender images
+    if (prerenderStorage) {
+        optimizer.prerender(prerenderStorage, options.srcDir, {
+            recursive: options.prerender,
+            scaleFactor: scaleFactor,
+            message: options.prerenderMessage,
+        });
+    }
+    return function (req, res, next) { return __awaiter(_this, void 0, void 0, function () {
+        var fileName, searchIdx, filePath, width, idx, format, imageInfo;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!req.query.f || !req.query.w) {
+                        next();
+                        return [2 /*return*/];
+                    }
+                    fileName = req.url.substring((options.uriPrefix || '').length + 1);
+                    searchIdx = fileName.indexOf('?');
+                    fileName = searchIdx >= 0 ? fileName.substring(0, searchIdx) : fileName;
+                    filePath = path_1.default.resolve(lup_root_1.ROOT, options.srcDir, fileName);
+                    width = parseInt(req.query.w || '', 10) || 1024;
+                    idx = fileName.lastIndexOf(".");
+                    format = (req.query.f.length > 0) ? req.query.f :
+                        ((idx >= 0 && idx < fileName.length - 1) ? fileName.substring(idx + 1) : 'jpg');
+                    if (!index_1.OptimizerSettings.FILE_EXTENSION_TO_MIME_TYPE[format]) {
+                        next();
+                        return [2 /*return*/];
+                    }
+                    imageInfo = null;
+                    if (!prerenderStorage) return [3 /*break*/, 2];
+                    return [4 /*yield*/, prerenderStorage.getImage(filePath, width, format)];
+                case 1:
+                    imageInfo = _a.sent();
+                    _a.label = 2;
+                case 2:
+                    if (!(!imageInfo && cacheStorage)) return [3 /*break*/, 4];
+                    return [4 /*yield*/, cacheStorage.getImage(filePath, width, format)];
+                case 3:
+                    imageInfo = _a.sent();
+                    _a.label = 4;
+                case 4:
+                    if (!!imageInfo) return [3 /*break*/, 6];
+                    return [4 /*yield*/, optimizer.convertImage(filePath, width, format)];
+                case 5:
+                    imageInfo = _a.sent();
+                    if (imageInfo && cacheStorage)
+                        cacheStorage.putImage(filePath, width, format, imageInfo.imageData);
+                    _a.label = 6;
+                case 6:
+                    // send image
+                    if (imageInfo) {
+                        if (httpCacheSec && httpCacheSec > 0)
+                            res.set('Cache-control', 'public, max-age=' + httpCacheSec);
+                        res.set('Content-type', imageInfo.mimeType);
+                        res.send(imageInfo.imageData);
+                    }
+                    else {
+                        next();
+                    }
+                    return [2 /*return*/];
+            }
+        });
+    }); };
+}
+exports.ImageRequestHandler = ImageRequestHandler;
+;

ImageRequestHandler.js

@@ -0,0 +1,75 @@
+/// <reference types="node" />
+import { ImageInfo } from ".";
+export interface ImageStorage {
+    /**
+     * Returns the last modified time of the file.
+     * @param filePath File path to original image.
+     * @return Promise that resolves to last modified time or null if file could not be found.
+     */
+    getLastModified(filePath: string, width: number, format: string): Promise<number | null>;
+    /**
+     * Loads an image from storage.
+     * @param filePath File path to original image.
+     * @param width Width to scale image to.
+     * @param format Format to convert image to.
+     * @return Promise that resolves to image info or null if image with specified parameters could not be found.
+     */
+    getImage(filePath: string, width: number, format: string): Promise<ImageInfo | null>;
+    /**
+     * Stores an image in storage.
+     * @param filePath File path to original image.
+     * @param width Width to scale image to.
+     * @param format Format to convert image to.
+     * @param imageData Image data to store.
+     * @return Promise that resolves when image has been stored.
+     */
+    putImage(filePath: string, width: number, format: string, imageData: Buffer): Promise<void>;
+}
+export type ImageCacheStorageProps = {
+    /** Path relative to project root where scaled images should be stored.
+     * If null scaled images won't be cached.
+     * Defaults to './cache'
+     */
+    cacheDir?: string | null;
+    /**
+     * Maximum size of the cache directory in MB.
+     * If max size is reached and a new image is about to be stored, the longest unused image will be deleted.
+     * Defaults to 1000 (1GB), zero or negative numbers disable the cache size limit.
+     */
+    cacheSize?: number;
+};
+/** Creates a directory with limited size containing the latest used formats. */
+export declare class ImageCacheStorage implements ImageStorage {
+    private readonly cacheDir;
+    private readonly cacheSize;
+    constructor(options: ImageCacheStorageProps);
+    /**
+     * Manually enforces cache cleanup.
+     * In particular, this is useful if cache was manipulated manually.
+     * By default this is called automatically when a new image is stored in the cache.
+     */
+    private cleanUpCache;
+    private getCacheFilePath;
+    getLastModified(filePath: string, width: number, format: string): Promise<number | null>;
+    getImage(filePath: string, width: number, format: string): Promise<ImageInfo | null>;
+    putImage(filePath: string, width: number, format: string, imageData: Buffer): Promise<void>;
+}
+export type ImageDirectoryStorageProps = {
+    /** Path relative to project root where scaled images should be stored.*/
+    dirPath: string;
+};
+export declare class ImageDirectoryStorage implements ImageStorage {
+    private dirPath;
+    constructor(options: ImageDirectoryStorageProps);
+    private getStoreFilePath;
+    getLastModified(filePath: string, width: number, format: string): Promise<number | null>;
+    getImage(filePath: string, width: number, format: string): Promise<ImageInfo | null>;
+    putImage(filePath: string, width: number, format: string, imageData: Buffer): Promise<void>;
+}
+/** For each image creates a subdirectory in place that will contain all the different formats. */
+export declare class ImageInPlaceStorage implements ImageStorage {
+    private _getStorageFilePath;
+    getLastModified(filePath: string, width: number, format: string): Promise<number | null>;
+    getImage(filePath: string, width: number, format: string): Promise<ImageInfo | null>;
+    putImage(filePath: string, width: number, format: string, imageData: Buffer): Promise<void>;
+}