feat: Image.scale — resize images without cropping

The `scale` function can be used to scale images to a `width` and
`height` using several different `fit` modes:

* `Image.fit.contain` (default): Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to the `width` and `height` specified.
* `Image.fit.cover`: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to the `width` and `height` specified.
* `Image.fit.fill`: Ignoring the aspect ratio of the input, stretch the image to the exact `width` and/or `height` provided.

`scale` will not expand images by default, the `allowEnlargement` option
tells it to expand to fill the provided `width` and `height`.

Author: mrkurt

examples/watermark-image/index.js

@@ -1,24 +1,31 @@
 import { Image } from '@fly/image'
 
-const pictureURL = "https://raw.githubusercontent.com/superfly/fly/147f2a327dc76ce6cf10c46b7ea1c19a9d8f2d87/v8env/test/fixtures/picture.jpg"
-const logoURL = "https://raw.githubusercontent.com/superfly/fly/147f2a327dc76ce6cf10c46b7ea1c19a9d8f2d87/v8env/test/fixtures/overlay.png"
+const pictureURL = "https://raw.githubusercontent.com/superfly/fly/075939824c66c3db38f94d552138a4802e0c3838/tests/v8env/tests/fixtures/picture.jpg"
+const logoURL = "https://raw.githubusercontent.com/superfly/fly/075939824c66c3db38f94d552138a4802e0c3838/tests/v8env/tests/fixtures/overlay.png"
 
 fly.http.respondWith(async function (req) {
   const url = new URL(req.url)
 
   if (url.pathname == "/picture.jpg") {
-    return watermarkPicture(req.headers.get("accept"))
+    return watermarkPicture(url.searchParams.get('width'), url.searchParams.get('height'))
   }
 
   return new Response("not found", { status: 404 })
 })
 
-async function watermarkPicture() {
-  const [picture, logo] = await Promise.all([
+async function watermarkPicture(width, height) {
+  let [picture, logo] = await Promise.all([
     loadImage(pictureURL),
     loadImage(logoURL)
   ])
 
+  if(width || height){
+    width = width ? parseInt(width) : width
+    height = height ? parseInt(height) : height
+
+    picture = await picture.scale(width, height, { allowEnlargement: true}).toImage()
+  }
+
   const meta = picture.metadata()
 
   const padPct = 0.1

packages/core/src/bridge/fly/image.ts

@@ -16,6 +16,7 @@ type imageOperation = (...args: any[]) => sharp.SharpInstance
 
 const allowedOperations: Map<string, imageOperation> = new Map([
   ["resize", sharp.prototype.resize],
+  ["scale", scale],
   ["crop", sharp.prototype.crop],
   ["embed", sharp.prototype.embed],
   ["background", sharp.prototype.background],
@@ -172,3 +173,49 @@ function refToImage(ref: ivm.Reference<sharp.SharpInstance>) {
 
   return img
 }
+
+async function scale(this: sharp.SharpInstance, ...args: any[]) {
+  const opts = typeof args[args.length - 1] === "object" ? args[args.length - 1] : undefined
+  const sharpOpts = {
+    kernel: sharp.kernel.lanczos3,
+    fastShrinkOnLoad: true
+  }
+
+  if (opts) {
+    sharpOpts.kernel = opts.kernel
+    sharpOpts.fastShrinkOnLoad = opts.fastShrinkOnLoad
+  }
+
+  let width = typeof args[0] === "number" ? args[0] : undefined
+  let height = typeof args[1] === "number" ? args[1] : undefined
+  const ignoreAspectRatio = typeof opts === "object" && opts.ignoreAspectRatio === true
+  const withoutEnlargement = typeof opts === "object" && opts.allowEnlargement === false
+
+
+  if (!width || !height) {
+    const meta = await this.metadata()
+    width = relativeDimension(width, meta.width || 0, height, meta.height || 0)
+    height = relativeDimension(height, meta.height || 0, width, meta.width || 0)
+  }
+
+  this.resize(width, height, sharpOpts)
+
+  if (ignoreAspectRatio === true) {
+    this.ignoreAspectRatio()
+  } else {
+    this.max()
+  }
+  if (withoutEnlargement) {
+    this.withoutEnlargement()
+  }
+
+  return this
+}
+
+function relativeDimension(x: number | undefined, original: number, other: number, basis: number) {
+  if (x && typeof x === "number") return x
+
+  const scale = other / basis
+
+  return Math.ceil(scale * original)
+}

packages/core/src/v8env.ts

@@ -37,7 +37,7 @@ export class V8Environment extends EventEmitter {
   constructor() {
     super()
     this.bootstrapped = false
-    if (!v8EnvCode) { throw new Error("v8env not found, please run npm build to generate it") }
+    if (!v8EnvCode) { throw new Error("v8env not found, please run `yarn bundle` to generate it") }
   }
 
   get isReady() {

packages/v8env/src/fly/image/index.ts

@@ -49,13 +49,27 @@ export class Image {
    * Pass `undefined` or `null` to auto-scale the width to match the height.
    * @param height Height in pixels of the resulting image.
    * Pass `undefind` or `null` to auto-scale the height to match the width.
-   * @param options Resize options}
+   * @param options Resize options
    */
   public resize(width?: number, height?: number, options?: Image.ResizeOptions) {
     this._imageOperation("resize", width, height, options)
     return this
   }
 
+  /**
+   * Scale image to `width` x `height`. This does not crop the image, it scales it to fit 
+   * the specified width and height, and keeps the aspect ratio by default.
+   * @param width Width in pixels of the resulting image.
+   * Pass `undefined` or `null` to auto-scale the width to match the height.
+   * @param height Height in pixels of the resulting image.
+   * Pass `undefind` or `null` to auto-scale the height to match the width.
+   * @param options Scale options
+   */
+  public scale(width?: number, height?: number, options?: Image.ScaleOptions) {
+    this._imageOperation('scale', width, height, options)
+    return this
+  }
+
   /**
    * Overlay (composite) an image over the processed (resized, extracted etc.) image.
    *
@@ -373,6 +387,9 @@ export namespace Image {
     force?: boolean
   }
 
+  /**
+   * Options for resizing an image
+   */
   export interface ResizeOptions {
     /**
      * the kernel to use for image reduction.
@@ -384,7 +401,26 @@ export namespace Image {
      * and WebP shrink-on-load feature, which can lead to a slight moiré pattern on
      * some images. (optional, default `true`)
      */
-    fastShrinkOnLoad?: boolean
+    fastShrinkOnLoad?: boolean,
+  }
+
+  /**
+   * Options for scaling an image (see crop for cropping)
+   */
+  export interface ScaleOptions extends ResizeOptions {
+    /**
+     * Stretch image if resize dimensions are larger than the source image.
+     * 
+     * Defaults to `true`
+     */
+    allowEnlargement?: boolean,
+
+    /**
+     * Resize to exactly the width specified, changing aspect ratio if necessary
+     * 
+     * Defaults to `false`
+     */
+    ignoreAspectRatio?: boolean
   }
 
   export interface OverlayOptions {

tests/v8env/tests/image.spec.js

@@ -35,6 +35,31 @@ describe("Image", () => {
     expect(img2.info.format).to.eq("webp")
   })
 
+  describe("scale()", () => {
+    it("shrinks to fit, maintains aspect ratio", async () =>{
+      const img = new Image(logo)
+      const meta = img.metadata()
+
+      const scaled = await img.scale(500, 1000).toImage()
+      const scaledMeta = scaled.metadata()
+
+      expect(scaledMeta.width).to.eq(500)
+      expect(scaledMeta.height).to.eq(500)
+
+      expect(meta.width / scaledMeta.width).to.eq(meta.height / scaledMeta.height)
+    })
+
+    it('fills dimensions, ignores aspect ratio', async () => {
+      const img = new Image(logo)
+
+      const scaled = await img.scale(500, 1000, { ignoreAspectRatio: true }).toImage()
+      const scaledMeta = scaled.metadata()
+
+      expect(scaledMeta.width).to.eq(500)
+      expect(scaledMeta.height).to.eq(1000)
+    })
+  })
+
   it("flatten()", async () => {
     const img = new Image(logo)
     const img2 = await img