@travetto/image 5.0.0-rc.9 → 5.0.1

package/README.md

@@ -13,20 +13,28 @@ npm install @travetto/image
 yarn add @travetto/image
 ```
 
-This module provides functionality for image resizing, and png optimization. This is primarily meant to be used in conjunction with other modules, like the [Asset](https://github.com/travetto/travetto/tree/main/module/asset#readme "Modular library for storing and retrieving binary assets") module or the [Email Compilation Support](https://github.com/travetto/travetto/tree/main/module/email-compiler#readme "Email compiling module") module. It can also be invoked directly as needed (as it can be very handy for batch processing images on the command line). 
+This module provides functionality for image resizing, and png optimization. This is primarily meant to be used in conjunction with other modules, like the [Email Compilation Support](https://github.com/travetto/travetto/tree/main/module/email-compiler#readme "Email compiling module") module. It can also be invoked directly as needed (as it can be very handy for batch processing images on the command line). 
 
-The utility's primary structure revolves around the [CommandOperation](https://github.com/travetto/travetto/tree/main/module/command/src/command.ts#L12) from the [Command](https://github.com/travetto/travetto/tree/main/module/command#readme "Support for executing complex commands at runtime.") module.  The [CommandOperation](https://github.com/travetto/travetto/tree/main/module/command/src/command.ts#L12)  allows for declaration of a local executable, and a fall-back docker container (mainly meant for development).  The [ImageConverter](https://github.com/travetto/travetto/tree/main/module/image/src/convert.ts#L38) utilizes [ImageMagick](https://imagemagick.org/index.php), [pngquant](https://pngquant.org/), and  [Jpegoptim](https://github.com/tjko/jpegoptim) as the backing for image resizing and png compression, respectively.
+The [ImageUtil](https://github.com/travetto/travetto/tree/main/module/image/src/util.ts#L55) functionality supports two operation modes:
+   *  In-process operations using [sharp](https://sharp.pixelplumbing.com/)
+   *  Out-of-process operations using [ImageMagick](https://imagemagick.org/index.php),[pngquant](https://pngquant.org/) and [Jpegoptim](https://github.com/tjko/jpegoptim).
+
+## In-Process
+The in process operations leverage [sharp](https://sharp.pixelplumbing.com/) and will perform within expectations, and will execute substantially faster than invoking a subprocess.  The primary caveats here being that [Jpegoptim](https://github.com/tjko/jpegoptim) and [pngquant](https://pngquant.org/) are better geared for image optimization.  Additionally, by running these processes in-memory, there will be shared contention within the process.
+
+## Out-of-Process
+The out-of-process executions will leverage external tools ([ImageMagick](https://imagemagick.org/index.php),[pngquant](https://pngquant.org/) and [Jpegoptim](https://github.com/tjko/jpegoptim)) via [CommandOperation](https://github.com/travetto/travetto/tree/main/module/command/src/command.ts#L12)s.  These tools are tried and tested, but come with the overhead of invoking a separate process to operate.  The benefit here is externalized memory usage, and a more robust optimization flow.
 
 **Code: Simple Image Resize**
 ```typescript
 import { createReadStream, createWriteStream } from 'node:fs';
 import { pipeline } from 'node:stream/promises';
 
-import { ImageConverter } from '@travetto/image';
+import { ImageUtil } from '@travetto/image';
 
 export class ResizeService {
   async resizeImage(imgPath: string, width: number, height: number): Promise<string> {
-    const stream = await ImageConverter.resize(createReadStream(imgPath), { w: width, h: height });
+    const stream = await ImageUtil.resize(createReadStream(imgPath), { w: width, h: height });
     const out = imgPath.replace(/[.][^.]+$/, (ext) => `.resized${ext}`);
     await pipeline(stream, createWriteStream(out));
     return out;

package/__index__.ts

@@ -1,2 +1 @@
-/// <reference path="./src/trv.d.ts" />
-export * from './src/convert';
+export * from './src/util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/image",
-  "version": "5.0.0-rc.9",
+  "version": "5.0.1",
   "description": "Image support, resizing, and optimization",
   "keywords": [
     "images",
@@ -23,8 +23,9 @@
     "directory": "module/image"
   },
   "dependencies": {
-    "@travetto/runtime": "^5.0.0-rc.9",
-    "@travetto/command": "^5.0.0-rc.9"
+    "@travetto/command": "^5.0.1",
+    "@travetto/runtime": "^5.0.1",
+    "sharp": "^0.33.5"
   },
   "travetto": {
     "displayName": "Image"

package/src/util.ts

@@ -0,0 +1,155 @@
+import { Readable } from 'node:stream';
+import { ReadableStream } from 'node:stream/web';
+import { pipeline } from 'node:stream/promises';
+import { buffer as toBuffer } from 'node:stream/consumers';
+import { ChildProcess } from 'node:child_process';
+
+import type { Sharp } from 'sharp';
+
+import { CommandOperation } from '@travetto/command';
+import { castTo } from '@travetto/runtime';
+
+/**
+ * Image resize options
+ */
+export interface ResizeOptions {
+  /**
+   * New height
+   */
+  h?: number;
+  /**
+   * New width
+   */
+  w?: number;
+  /**
+   * Should the image be optimized?
+   */
+  optimize?: boolean;
+  /**
+   * Strict resolution
+   */
+  strictResolution?: boolean;
+  /**
+   * Sub process, allows for externalization of memory
+   */
+  asSubprocess?: boolean;
+}
+
+/**
+ * Image optimize options
+ */
+export interface OptimizeOptions {
+  format?: 'png' | 'jpeg';
+  /**
+   * Sub process, allows for externalization of memory
+   */
+  asSubprocess?: boolean;
+}
+
+
+type ImageType = Readable | Buffer | ReadableStream;
+
+/**
+ * Simple support for image manipulation.
+ */
+export class ImageUtil {
+
+  /**
+   * Resize/conversion util
+   */
+  static CONVERTER = new CommandOperation({
+    containerImage: 'jameskyburz/graphicsmagick-alpine:v1.0.0',
+    localCheck: ['gm', ['-version']]
+  });
+
+  /**
+   * Compressor
+   */
+  static PNG_COMPRESSOR = new CommandOperation({
+    containerImage: 'agregad/pngquant:latest',
+    localCheck: ['pngquant', ['-h']]
+  });
+
+  /**
+   * Compressor
+   */
+  static JPEG_COMPRESSOR = new CommandOperation({
+    containerImage: 'shomatan/jpegoptim:1.4.4',
+    localCheck: ['jpegoptim', ['-h']]
+  });
+
+  static async #subprocessReturn<T extends ImageType>(proc: ChildProcess, input: T): Promise<T> {
+    if (Buffer.isBuffer(input)) {
+      const [, buffer] = await Promise.all([
+        pipeline(Readable.from(input), proc.stdin!),
+        toBuffer(proc.stdout!)
+      ]);
+      return castTo(buffer);
+    } else {
+      pipeline(castTo<Readable>(input), proc.stdin!);
+      return castTo('pipeThrough' in input ? ReadableStream.from(proc.stdout!) : proc.stdout);
+    }
+  }
+
+  static async #sharpReturn<T extends ImageType>(output: Sharp, input: T, optimize?: boolean, format?: 'jpeg' | 'png'): Promise<T> {
+    if (optimize) {
+      output = output
+        .jpeg({ quality: 80, progressive: true, force: format === 'jpeg' })
+        .png({ compressionLevel: 9, quality: 80, adaptiveFiltering: true, force: format === 'png' });
+    }
+    const stream = Buffer.isBuffer(input) ? Readable.from(input) : input;
+    pipeline(stream, output);
+    return castTo('pipeThrough' in input ? ReadableStream.from(output) : Buffer.isBuffer(input) ? output.toBuffer() : output);
+  }
+
+  /**
+   * Resize image
+   */
+  static async resize<T extends ImageType>(image: T, options: ResizeOptions = {}): Promise<T> {
+    const dims = [options.w, options.h].map(d => (!d && options.strictResolution === false) ? undefined : d);
+    if (options.asSubprocess) {
+      return this.#subprocessReturn(
+        await this.CONVERTER.exec('gm', 'convert', '-resize', dims.join('x'), '-auto-orient',
+          ...(options.optimize ? ['-strip', '-quality', '86'] : []), '-', '-'),
+        image);
+    } else {
+      const { default: sharp } = await import('sharp');
+
+      return this.#sharpReturn(
+        sharp().resize({
+          width: dims[0],
+          height: dims[1],
+          fit: options.strictResolution !== false ? 'fill' : 'inside'
+        }),
+        image,
+        options.optimize,
+      );
+    }
+  }
+
+  /**
+   * Optimize an image
+   */
+  static async optimize<T extends ImageType>(image: T, options: OptimizeOptions = {}): Promise<T> {
+    if (options.asSubprocess) {
+      switch (options.format) {
+        case 'png': return this.#subprocessReturn(
+          await this.PNG_COMPRESSOR.exec('pngquant', '--quality', '40-80', '--speed', '1', '--force', '-'), image);
+        default:
+        case 'jpeg': return this.#subprocessReturn(
+          await this.JPEG_COMPRESSOR.exec('jpegoptim', '-m70', '-s', '--stdin', '--stdout', '-'), image);
+      }
+    } else {
+      const { default: sharp } = await import('sharp');
+      return this.#sharpReturn(sharp(), image, true, options.format);
+    }
+  }
+
+  /**
+   * Get Image Dimensions
+   */
+  static async getDimensions(image: Buffer | string): Promise<{ width: number, height: number }> {
+    const { default: sharp } = await import('sharp');
+    return sharp(image).metadata().then(v => ({ width: v.width!, height: v.height! }));
+  }
+}

package/src/convert.ts

@@ -1,130 +0,0 @@
-import { Readable } from 'node:stream';
-import { buffer as toBuffer } from 'node:stream/consumers';
-import { createReadStream } from 'node:fs';
-import { ChildProcess } from 'node:child_process';
-import { pipeline } from 'node:stream/promises';
-
-import { CommandOperation } from '@travetto/command';
-import { castTo } from '@travetto/runtime';
-
-/**
- * Image output options
- */
-export interface ImageOptions {
-  /**
-   * New height
-   */
-  h?: number;
-  /**
-   * New width
-   */
-  w?: number;
-  /**
-   * Should the image be optimized?
-   */
-  optimize?: boolean;
-  /**
-   * Strict resolution
-   */
-  strictResolution?: boolean;
-}
-
-type ImageType = Readable | Buffer;
-
-/**
- * Simple support for image manipulation.  Built upon @travetto/command, it can
- * run imagemagick and pngquant locally or via docker as needed.
- */
-export class ImageConverter {
-
-  /**
-   * Resize/conversion util
-   */
-  static CONVERTER = new CommandOperation({
-    containerImage: 'jameskyburz/graphicsmagick-alpine:v1.0.0',
-    localCheck: ['gm', ['-version']]
-  });
-
-  /**
-   * Compressor
-   */
-  static PNG_COMPRESSOR = new CommandOperation({
-    containerImage: 'agregad/pngquant:latest',
-    localCheck: ['pngquant', ['-h']]
-  });
-
-  /**
-   * Compressor
-   */
-  static JPEG_COMPRESSOR = new CommandOperation({
-    containerImage: 'shomatan/jpegoptim:1.4.4',
-    localCheck: ['jpegoptim', ['-h']]
-  });
-
-  static async #stream<T extends ImageType>(proc: ChildProcess, input: T): Promise<T> {
-    if (Buffer.isBuffer(input)) {
-      Readable.from(input).pipe(proc.stdin!);
-      return castTo(toBuffer(proc.stdout!));
-    } else {
-      input.pipe(proc.stdin!); // Start the process
-      return castTo(proc.stdout);
-    }
-  }
-
-  /**
-   * Resize image using imagemagick
-   */
-  static async resize<T extends ImageType>(image: T, options: ImageOptions): Promise<T> {
-    const dims = [options.w, options.h].map(d => (d && options.strictResolution !== false) ? `${d}!` : d).join('x');
-
-    const proc = await this.CONVERTER.exec(
-      'gm', 'convert', '-resize', dims, '-auto-orient',
-      ...(options.optimize ? ['-strip', '-quality', '86'] : []),
-      '-', '-');
-
-    return this.#stream(proc, image);
-  }
-
-  /**
-   * Optimize image
-   */
-  static async optimize<T extends ImageType>(format: 'png' | 'jpeg', image: T): Promise<T> {
-    let proc: ChildProcess;
-    switch (format) {
-      case 'png': {
-        proc = await this.PNG_COMPRESSOR.exec(
-          'pngquant', '--quality', '40-80', '--speed', '1', '--force', '-');
-        break;
-      }
-      case 'jpeg': {
-        proc = await this.JPEG_COMPRESSOR.exec('jpegoptim', '-m70', '-s', '--stdin', '--stdout');
-        break;
-      }
-    }
-    return this.#stream(proc, image);
-  }
-
-  /**
-   * Get Image Dimensions
-   * @param image
-   */
-  static async getDimensions(image: Readable | Buffer | string): Promise<{ width: number, height: number }> {
-    const proc = await this.CONVERTER.exec(
-      'gm', 'identify', '-format', '%wX%h', '-',
-    );
-
-    if (typeof image === 'string') {
-      image = createReadStream(image);
-    }
-
-    const [_, output] = await Promise.all([
-      pipeline(image, proc.stdin!),
-      toBuffer(proc.stdout!)
-    ]);
-
-    const text = output.toString('utf8');
-    const [w, h] = text.split('X').map(x => parseFloat(x));
-
-    return { width: w, height: h };
-  }
-}

package/src/resource.ts

@@ -1,51 +0,0 @@
-import fs from 'node:fs/promises';
-import { Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import path from 'node:path';
-
-import { Env, FileLoader, Runtime } from '@travetto/runtime';
-
-import { ImageConverter } from './convert';
-
-/**
- * Resource provider for images that allows for real-time optimization
- */
-export class ImageOptimizingResourceLoader extends FileLoader {
-
-  #cacheRoot: string;
-
-  constructor(paths: string[] = [], cacheRoot?: string) {
-    super(Runtime.resourcePaths(paths));
-
-    this.#cacheRoot = cacheRoot ?? path.resolve(Env.TRV_IMAGE_CACHE.val || Runtime.toolPath('image_cache'));
-  }
-
-  async #openFile(pth: string): Promise<fs.FileHandle> {
-    return fs.open(path.join(this.#cacheRoot, pth.replace(/[\\/]/g, '__')));
-  }
-
-  /**
-   * Fetch image, compress and return as buffer
-   */
-  async readOptimized(rel: string): Promise<Buffer> {
-    const cachedOutput = path.resolve(this.#cacheRoot, rel);
-    await fs.mkdir(path.dirname(cachedOutput), { recursive: true });
-
-    const handle = await this.#openFile(cachedOutput);
-    const exists = !!(await handle.stat().catch(() => false));
-
-    if (!exists) {
-      let stream: Buffer | Readable = await this.readStream(rel);
-      if (/[.]png$/.test(rel)) {
-        stream = await ImageConverter.optimize('png', stream);
-      } else if (/[.]jpe?g$/i.test(rel)) {
-        stream = await ImageConverter.optimize('jpeg', stream);
-      }
-      await pipeline(stream, handle.createWriteStream());
-    }
-
-    const buffer = await handle.readFile();
-    await handle.close();
-    return buffer;
-  }
-}

package/src/trv.d.ts

@@ -1,11 +0,0 @@
-import '@travetto/runtime';
-
-declare global {
-  interface TravettoEnv {
-    /** 
-     * Where should optimized images be stored by default
-     * @default undefined
-     */
-    TRV_IMAGE_CACHE: string;
-  }
-}