check encoder and decoder options

Author: matmen

CHANGELOG.md

@@ -22,6 +22,21 @@
   the same, except for rare coefficients the new transforms round differently (2 of 108 test encodes, both the same
   size).
 
+### Fixes
+
+- Invalid options throw a `RangeError` naming them before any work, instead of failing inside an encoder or being
+  ignored:
+  - `encodeAVIF()`: `effort` other than 0, 1 or 2 failed with a `TypeError` deep in the encoder, `quality` and
+    `alphaQuality` outside 0-100 were accepted, and an unknown `subsampling` silently meant 4:4:4 (now a
+    `TypeError`).
+  - `encodeWebP()`, `Animation.encodeWebP()` and `Animation.webpEncoder()` check `effort` for lossless images too
+    (which don't use it).
+  - `NaN` is refused as GIF `quality` and APNG `compression` (out of range values are still clamped, like PNG's), as
+    `dominantColor()`'s `threshold` and as `renderSVG()`'s size (which threw about the image's width); negative font
+    sizes in `renderText()` (which rendered an empty image); `maxPixels` that isn't positive in `Image.decode()` and
+    `Animation.decode()` (which reported every image as too large); fractional loop counts in `new Animation()`.
+- `Animation.decode()` reports invalid `threads` and `maxPixels` as such, not as damaged image data.
+
 ## 3.13.2
 
 ### Fixes

src/animation-encoder.ts

@@ -6,7 +6,7 @@ import { Frame, FrameOptions } from './frame.ts';
 import { Optimizer, Compositor, InputFrame, OptimizeOptions, OptimizedFrame, coverCanvas, fillUnchanged } from './util/optimize.ts';
 import { compressAsync, decompressAsync } from './codecs/zlib.ts';
 import { Metadata, resolveMetadata, pngText, exifData, gifComments } from './metadata.ts';
-import { finite } from './util/options.ts';
+import { finite, compressionLevel } from './util/options.ts';
 
 // (ImageScript, like GIF, counts repetitions: -1 forever, 0 play once; APNG and WebP count plays, 0 forever)
 const toPlays = (loopCount: number): number => loopCount < 0 ? 0 : loopCount + 1;
@@ -151,7 +151,8 @@ export class AnimationEncoder {
     }
 
     /** @internal */
-    static __gif__(width: number, height: number, { loopCount = -1, metadata = {}, optimize = true, quality = 95 }: GIFAnimationEncoderOptions): AnimationEncoder {
+    static __gif__(width: number, height: number, { loopCount = -1, metadata = {}, optimize = true, quality: qualityOption = 95 }: GIFAnimationEncoderOptions): AnimationEncoder {
+        const quality = finite(qualityOption, 'quality');
         canvas(width, height, loopCount);
         const comments = gifComments(resolveMetadata(metadata));
         // (the first frame is encoded last: it needs a transparent index if any frame restores the background)
@@ -177,7 +178,8 @@ export class AnimationEncoder {
     }
 
     /** @internal */
-    static __apng__(width: number, height: number, { loopCount = -1, metadata = {}, optimize = true, compression = 4 }: APNGAnimationEncoderOptions): AnimationEncoder {
+    static __apng__(width: number, height: number, { loopCount = -1, metadata = {}, optimize = true, compression: compressionOption = 4 }: APNGAnimationEncoderOptions): AnimationEncoder {
+        const compression = compressionLevel(compressionOption);
         canvas(width, height, loopCount);
         const text = pngText(resolveMetadata(metadata));
         // the frames are kept compressed (quickly): the pixel format, and whether opaque animations are stored without

src/animation.ts

@@ -10,7 +10,7 @@ import { Frame } from './frame.ts';
 import { ImageType } from './image-type.ts';
 import { optimize, OptimizeOptions, OptimizedFrame } from './util/optimize.ts';
 import { Metadata, resolveMetadata, pngText, exifData, gifComments } from './metadata.ts';
-import { isOptions, finite } from './util/options.ts';
+import { isOptions, finite, compressionLevel } from './util/options.ts';
 import { MAX_PIXELS, decoding } from './util/limits.ts';
 import { AnimationEncoder, WebPAnimationEncoderOptions, GIFAnimationEncoderOptions, APNGAnimationEncoderOptions } from './animation-encoder.ts';
 
@@ -123,8 +123,8 @@ export class Animation extends Array<Frame> {
             if (!(this[i] instanceof Frame))
                 throw new TypeError(`Frame ${i} is not an instance of Frame`);
 
-        if (finite(loopCount, 'loop count') < -1)
-            throw new RangeError('Invalid loop count');
+        if (finite(loopCount, 'loop count') < -1 || !Number.isInteger(Number(loopCount)))
+            throw new RangeError(`Invalid loop count: ${loopCount}`);
 
         this.loopCount = loopCount;
     }
@@ -263,7 +263,7 @@ export class Animation extends Array<Frame> {
         // gifs store centiseconds; rounding keeps e.g. 16 ms (60 fps) from becoming 10 ms
         const gifFrames = frames.map(({ duration, ...f }) => ({ ...f, delay: Math.round(duration / 10) }));
 
-        return gifCodec.encode({ width: this.width, height: this.height, loopCount: this.loopCount, frames: gifFrames }, quality, gifComments(resolveMetadata(metadata)));
+        return gifCodec.encode({ width: this.width, height: this.height, loopCount: this.loopCount, frames: gifFrames }, finite(quality, 'quality'), gifComments(resolveMetadata(metadata)));
     }
 
     /**
@@ -290,7 +290,7 @@ export class Animation extends Array<Frame> {
         const frames = optimize
             ? this.__optimized__({ replace: true, even: false, alpha: frames => png.alphaCost(frames.map(f => f.pixels)) }).map(f => ({ ...f, dispose: f.dispose ? 1 : 0 }))
             : this.__apngFrames__().map(({ blend: _, ...f }) => f); // blended, the encoder's default
-        return png.encodeAnimation(frames, this.width, this.height, toPlays(this.loopCount), compression, pngText(resolveMetadata(metadata)));
+        return png.encodeAnimation(frames, this.width, this.height, toPlays(this.loopCount), compressionLevel(compression), pngText(resolveMetadata(metadata)));
     }
 
     /**
@@ -412,6 +412,12 @@ export class Animation extends Array<Frame> {
      */
     static decode(input: BinaryData, onlyExtractFirstFrame?: boolean): Promise<Animation>;
     static async decode(input: BinaryData, onlyFirstFrameOrOptions: boolean | AnimationDecodeOptions = false): Promise<Animation> {
+        // (checked outside of decoding(), which reports RangeErrors as damaged data)
+        if (isOptions(onlyFirstFrameOrOptions)) {
+            const { maxPixels = MAX_PIXELS, threads = 1 } = onlyFirstFrameOrOptions;
+            if (!Number.isInteger(threads) || threads < 1) throw new RangeError(`threads must be a positive integer, not ${threads}`);
+            if (!(Number(maxPixels) > 0)) throw new RangeError(`maxPixels must be a positive number, not ${maxPixels}`);
+        }
         return decoding(() => Animation.__decode__(input, onlyFirstFrameOrOptions));
     }
 
@@ -421,7 +427,6 @@ export class Animation extends Array<Frame> {
      */
     private static async __decode__(input: BinaryData, onlyFirstFrameOrOptions: boolean | AnimationDecodeOptions): Promise<Animation> {
         const { onlyFirstFrame: onlyExtractFirstFrame = false, maxPixels = MAX_PIXELS, applyColorProfile = true, threads = Math.max(1, Math.min(availableThreads(), 8)) } = isOptions(onlyFirstFrameOrOptions) ? onlyFirstFrameOrOptions : { onlyFirstFrame: onlyFirstFrameOrOptions };
-        if (!Number.isInteger(threads) || threads < 1) throw new RangeError(`threads must be a positive integer, not ${threads}`);
         const profile = (frames: Frame[], icc: Uint8Array | undefined, space?: jxl.ColorSpace): Frame[] => {
             const transform = !applyColorProfile ? null : icc ? profileTransform(icc) : space ? colorSpaceTransform(space.xy, space.curve) : null;
             if (transform) for (const frame of frames) transform(frame.bitmap);

src/codecs/webp.ts

@@ -10,7 +10,7 @@ import { encodeVP8, encodeAlpha } from './vp8-enc.ts';
 import { rgbaToYUV } from './vp8-enc-dsp.ts';
 import { orientation as exifOrientation } from './exif.ts';
 import { MAX_PIXELS, checkPixels } from '../util/limits.ts';
-import { finite } from '../util/options.ts';
+import { effort as checkEffort, quality as checkQuality } from '../util/options.ts';
 import { startThreads } from '../util/threads.ts';
 
 const fourCC = (s: string): number => s.charCodeAt(0) | s.charCodeAt(1) << 8 | s.charCodeAt(2) << 16 | s.charCodeAt(3) << 24;
@@ -371,11 +371,10 @@ export interface LossyOptions {
  * @returns undefined without a quality: lossless
  */
 export function lossyOptions(quality: number | undefined, effort: number, sharp: boolean, alphaQuality: number): LossyOptions | undefined {
+    // (checked for lossless images too, which don't use it)
+    checkEffort(effort, 6);
     if (quality === undefined) return undefined;
-    const q = finite(quality, 'quality'), a = finite(alphaQuality, 'alphaQuality');
-    if (q < 0 || q > 100) throw new RangeError(`quality must be 0-100, not ${q}`);
-    if (a < 0 || a > 100) throw new RangeError(`alphaQuality must be 0-100, not ${a}`);
-    if (!Number.isInteger(effort) || effort < 0 || effort > 6) throw new RangeError(`effort must be an integer 0-6, not ${effort}`);
+    const q = checkQuality(quality), a = checkQuality(alphaQuality, 'alphaQuality');
     return { quality: q, method: effort, sharp, alphaQuality: Math.round(a) };
 }
 

src/image.ts

@@ -32,7 +32,7 @@ import { encode as utf8 } from './util/utf8.ts';
 import { resample, BOX, TRIANGLE, CUBIC } from './util/resample.ts';
 import { rotateBilinear } from './util/rotate.ts';
 import { gaussianBlur, boxBlurRGBA, premultiply, unpremultiply } from './util/blur.ts';
-import { isOptions, finite, color as checkColor } from './util/options.ts';
+import { isOptions, finite, color as checkColor, quality as checkQuality, effort as checkEffort, compressionLevel } from './util/options.ts';
 import { MAX_PIXELS, decoding } from './util/limits.ts';
 
 /** A color as a 32-bit RGBA integer (`0xRRGGBBAA`) */
@@ -1797,7 +1797,7 @@ export class Image {
     dominantColor(ignoreBlackOrOptions: boolean | DominantColorOptions = true, ignoreWhiteArgument = true, thresholdArgument = 0xf): Color {
         const { ignoreBlack = true, ignoreWhite = true, threshold: bwThreshold = 0xf } = typeof ignoreBlackOrOptions === 'object' && ignoreBlackOrOptions !== null
             ? ignoreBlackOrOptions : { ignoreBlack: ignoreBlackOrOptions, ignoreWhite: ignoreWhiteArgument, threshold: thresholdArgument };
-        const threshold = Math.min(64, Math.max(0, bwThreshold)) * 4;
+        const threshold = Math.min(64, Math.max(0, finite(bwThreshold, 'threshold'))) * 4;
         const pixels = this.__bytes__();
 
         const color = quantize.dominantColor(pixels, (r, g, b) =>
@@ -2137,8 +2137,7 @@ export class Image {
             ({ compression = 4, metadata = {} } = compressionOrOptions);
         else metadata = compressionOrOptions as Metadata;
 
-        const level = Math.min(9, Math.max(0, ~~finite(compression, 'compression level')));
-        return png.encodeRGBA(this.__bytes__(), this.width, this.height, level, pngText(resolveMetadata(metadata)));
+        return png.encodeRGBA(this.__bytes__(), this.width, this.height, compressionLevel(compression), pngText(resolveMetadata(metadata)));
     }
 
     /**
@@ -2218,9 +2217,11 @@ export class Image {
      * @param options See {@link AVIFEncodeOptions}
      */
     async encodeAVIF({ quality = 60, alphaQuality = 100, subsampling = '4:4:4', effort = 1, threads = defaultThreads(), metadata = {} }: AVIFEncodeOptions = {}): Promise<Uint8Array> {
+        checkEffort(effort, 2);
         checkThreads(threads);
+        if (subsampling !== '4:4:4' && subsampling !== '4:2:0') throw new TypeError(`subsampling must be '4:4:4' or '4:2:0', not ${String(subsampling)}`);
         const exif = exifData(resolveMetadata(metadata));
-        return avifEnc.encode(this.__bytes__(), this.width, this.height, { quality: finite(quality, 'quality'), alphaQuality: finite(alphaQuality, 'alphaQuality'), subsampling, effort, exif, threads });
+        return avifEnc.encode(this.__bytes__(), this.width, this.height, { quality: checkQuality(quality), alphaQuality: checkQuality(alphaQuality, 'alphaQuality'), subsampling, effort, exif, threads });
     }
 
     /**
@@ -2234,12 +2235,11 @@ export class Image {
      * @param options See {@link JXLEncodeOptions}
      */
     async encodeJXL({ quality, effort = 1, threads = defaultThreads(), metadata = {} }: JXLEncodeOptions = {}): Promise<Uint8Array> {
-        if (!Number.isInteger(effort) || effort < 0 || effort > 2) throw new RangeError(`effort must be an integer 0-2, not ${effort}`);
+        checkEffort(effort, 2);
         checkThreads(threads);
         let distance = 0;
         if (quality !== undefined) {
-            const q = finite(quality, 'quality');
-            if (q < 0 || q > 100) throw new RangeError(`quality must be 0-100, not ${q}`);
+            const q = checkQuality(quality);
             // (cjxl's distance of a quality)
             distance = q >= 100 ? 0 : q >= 30 ? 0.1 + (100 - q) * 0.09 : 53 / 3000 * q * q - 23 / 20 * q + 25;
         }
@@ -2267,6 +2267,7 @@ export class Image {
     static async decode(input: BinaryData, options: DecodeOptions = {}): Promise<Image> {
         const { applyOrientation = true, applyColorProfile = true, maxPixels = MAX_PIXELS, toneMapping = 'reinhard', threads = defaultThreads() } = options;
         checkThreads(threads);
+        if (!(Number(maxPixels) > 0)) throw new RangeError(`maxPixels must be a positive number, not ${maxPixels}`);
         if (toneMapping !== 'reinhard' && toneMapping !== 'clamp') throw new TypeError(`toneMapping must be 'reinhard' or 'clamp', not ${String(toneMapping)}`);
         const data = view(input);
         const dataView = new DataView(data.buffer, data.byteOffset, data.byteLength);
@@ -2386,6 +2387,7 @@ export class Image {
         if (![1, 2, 3].includes(mode))
             throw new Error('Invalid SVG scaling mode');
 
+        finite(size, 'SVG size');
         if (mode === Image.SVG_MODE_SCALE && size <= 0)
             throw new RangeError('SVG scale must be > 0');
         if (mode !== Image.SVG_MODE_SCALE && size < 1)
@@ -2451,6 +2453,7 @@ export class Image {
         const { color = 0xffffffff, layout = new TextLayout(), strokeWidth = 0, strokeColor = 0x000000ff, hinting = true, features = {}, variations = {} } = options;
         const axes = textRenderer.axisValues(variations);
         size = finite(size, 'font size');
+        if (size < 0) throw new RangeError(`Invalid font size: ${size}`);
         if (finite(strokeWidth, 'stroke width') < 0)
             throw new RangeError('Invalid stroke width');
         const fonts = Array.isArray(font) ? font : [font];

src/util/options.ts

@@ -13,5 +13,21 @@ export function finite(value: number, name: string): number {
     return number;
 }
 
+/** A quality argument (0-100) of the encoders that take one, finite and in range */
+export function quality(value: number, name = 'quality'): number {
+    const q = finite(value, name);
+    if (q < 0 || q > 100) throw new RangeError(`${name} must be 0-100, not ${q}`);
+    return q;
+}
+
+/** An effort argument: an integer from 0 to max */
+export function effort(value: number, max: number): number {
+    if (!Number.isInteger(value) || value < 0 || value > max) throw new RangeError(`effort must be an integer 0-${max}, not ${value}`);
+    return value;
+}
+
+/** A zlib compression level: finite, clamped to 0-9 and truncated (PNG's and APNG's) */
+export const compressionLevel = (value: number): number => Math.min(9, Math.max(0, ~~finite(value, 'compression level')));
+
 /** A color argument: a finite number (as RGBA, 0xrrggbbaa) */
 export const color = (value: number, name = 'color'): number => finite(value, name);

tests/option-checks.js

@@ -0,0 +1,69 @@
+const {Image, Frame, Animation} = require('..');
+
+const panic = message => {
+    console.error(message);
+    process.exit(1);
+};
+
+// invalid options throw a RangeError (or TypeError) naming them, before any work, instead of failing somewhere inside
+// an encoder or being ignored
+const rejects = async (name, fn, Type, pattern) => {
+    try {
+        await fn();
+    } catch (error) {
+        if (!(error instanceof Type) || !pattern.test(error.message)) panic(`${name}: wrong error ${error?.constructor?.name}: ${error?.message}`);
+        return;
+    }
+    panic(`${name}: accepted`);
+};
+
+(async () => {
+    const image = new Image(8, 8).fill(0x336699ff);
+    const animation = () => new Animation([new Frame(8, 8, {duration: 100}).fill(0xff0000ff), new Frame(8, 8, {duration: 100}).fill(0x00ff00ff)]);
+    const encoded = async (encoder) => {
+        await encoder.add(new Frame(8, 8).fill(0xff0000ff));
+        return encoder.finish();
+    };
+
+    for (const effort of [-1, 3, 1.5, NaN, '1', null]) {
+        await rejects(`encodeAVIF effort ${effort}`, () => image.encodeAVIF({effort}), RangeError, /effort must be an integer 0-2/);
+        await rejects(`encodeJXL effort ${effort}`, () => image.encodeJXL({effort}), RangeError, /effort must be an integer 0-2/);
+    }
+    for (const effort of [-1, 7, 1.5, NaN]) {
+        // (lossless WebP doesn't use it, but checks it)
+        await rejects(`encodeWebP lossless effort ${effort}`, () => image.encodeWebP({effort}), RangeError, /effort must be an integer 0-6/);
+        await rejects(`encodeWebP effort ${effort}`, () => image.encodeWebP({quality: 80, effort}), RangeError, /effort must be an integer 0-6/);
+        await rejects(`Animation.encodeWebP effort ${effort}`, () => animation().encodeWebP({effort}), RangeError, /effort must be an integer 0-6/);
+        await rejects(`webpEncoder effort ${effort}`, () => encoded(Animation.webpEncoder(8, 8, {effort})), RangeError, /effort must be an integer 0-6/);
+    }
+    for (const quality of [-1, 101, NaN]) {
+        await rejects(`encodeAVIF quality ${quality}`, () => image.encodeAVIF({quality}), RangeError, /quality/);
+        await rejects(`encodeAVIF alphaQuality ${quality}`, () => image.encodeAVIF({alphaQuality: quality}), RangeError, /alphaQuality/);
+    }
+    for (const subsampling of ['4:2:2', '', null])
+        await rejects(`encodeAVIF subsampling ${subsampling}`, () => image.encodeAVIF({subsampling}), TypeError, /subsampling must be/);
+
+    // GIF quality and APNG compression are clamped (like PNG's), but have to be numbers
+    await rejects('encodeGIF quality NaN', () => animation().encodeGIF({quality: NaN}), RangeError, /quality/);
+    await rejects('gifEncoder quality NaN', () => encoded(Animation.gifEncoder(8, 8, {quality: NaN})), RangeError, /quality/);
+    await rejects('encodeAPNG compression NaN', () => animation().encodeAPNG({compression: NaN}), RangeError, /compression level/);
+    await rejects('apngEncoder compression NaN', () => encoded(Animation.apngEncoder(8, 8, {compression: NaN})), RangeError, /compression level/);
+    if (!(await animation().encodeGIF({quality: 1000})).length || !(await animation().encodeAPNG({compression: 12})).length) panic('clamped values rejected');
+
+    await rejects('Animation loopCount 1.5', () => new Animation([new Frame(8, 8)], {loopCount: 1.5}), RangeError, /loop count/);
+    await rejects('dominantColor threshold NaN', () => image.dominantColor({threshold: NaN}), RangeError, /threshold/);
+    await rejects('renderSVG size NaN', () => Image.renderSVG('<svg xmlns="http://www.w3.org/2000/svg" width="4" height="4"/>', {size: NaN}), RangeError, /SVG size/);
+    await rejects('renderText size -1', () => Image.renderText(new Uint8Array(0), -1, 'x'), RangeError, /font size/);
+    const png = await image.encode();
+    for (const maxPixels of [NaN, -1, 0]) {
+        await rejects(`Image.decode maxPixels ${maxPixels}`, () => Image.decode(png, {maxPixels}), RangeError, /maxPixels/);
+        await rejects(`Animation.decode maxPixels ${maxPixels}`, () => Animation.decode(png, {maxPixels}), RangeError, /maxPixels/);
+    }
+    await rejects('Animation.decode threads 0', () => Animation.decode(png, {threads: 0}), RangeError, /threads must be/);
+
+    // valid values keep working
+    for (const effort of [0, 1, 2]) await image.encodeAVIF({effort});
+    for (const subsampling of ['4:4:4', '4:2:0']) await image.encodeAVIF({quality: 50, subsampling});
+    await image.encodeWebP({effort: 6});
+    await Image.decode(png, {maxPixels: Infinity});
+})();