Make heif compression option mandatory #3740

docs/api-output.md

@@ -485,9 +485,6 @@ sharp('input.svg')
 
 Use these AVIF options for output image.
 
-Whilst it is possible to create AVIF images smaller than 16x16 pixels,
-most web browsers do not display these properly.
-
 AVIF image sequences are not supported.
 
 
@@ -520,7 +517,7 @@ const data = await sharp(input)
 
 
 ## heif
-> heif([options]) ⇒ <code>Sharp</code>
+> heif(options) ⇒ <code>Sharp</code>
 
 Use these HEIF options for output image.
 
@@ -536,9 +533,9 @@ globally-installed libvips compiled with support for libheif, libde265 and x265.
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| [options] | <code>Object</code> |  | output options |
+| options | <code>Object</code> |  | output options |
+| options.compression | <code>string</code> |  | compression format: av1, hevc |
 | [options.quality] | <code>number</code> | <code>50</code> | quality, integer 1-100 |
-| [options.compression] | <code>string</code> | <code>&quot;&#x27;av1&#x27;&quot;</code> | compression format: av1, hevc |
 | [options.lossless] | <code>boolean</code> | <code>false</code> | use lossless compression |
 | [options.effort] | <code>number</code> | <code>4</code> | CPU effort, between 0 (fastest) and 9 (slowest) |
 | [options.chromaSubsampling] | <code>string</code> | <code>&quot;&#x27;4:4:4&#x27;&quot;</code> | set to '4:2:0' to use chroma subsampling |

docs/api-utility.md

@@ -42,19 +42,6 @@ console.log(sharp.format);
 ```
 
 
-## vendor
-> vendor
-
-An Object containing the platform and architecture
-of the current and installed vendored binaries.
-
-
-**Example**  
-```js
-console.log(sharp.vendor);
-```
-
-
 ## queue
 > queue
 

docs/changelog.md

@@ -10,6 +10,9 @@ Requires libvips v8.14.5
 
 * Remove `sharp.vendor`.
 
+* Make `compression` option of `heif` mandatory to help reduce HEIF vs HEIC confusion.
+  [#3740](https://github.com/lovell/sharp/issues/3740)
+
 ## v0.32 - *flow*
 
 Requires libvips v8.14.5

lib/index.d.ts

@@ -699,7 +699,6 @@ declare namespace sharp {
 
         /**
          * Use these AVIF options for output image.
-         * Whilst it is possible to create AVIF images smaller than 16x16 pixels, most web browsers do not display these properly.
          * @param options Output options.
          * @throws {Error} Invalid options
          * @returns A sharp instance that can be used to chain operations

lib/output.js

@@ -867,9 +867,6 @@ function tiff (options) {
 /**
  * Use these AVIF options for output image.
  *
- * Whilst it is possible to create AVIF images smaller than 16x16 pixels,
- * most web browsers do not display these properly.
- *
  * AVIF image sequences are not supported.
  *
  * @example
@@ -909,9 +906,9 @@ function avif (options) {
  *
  * @since 0.23.0
  *
- * @param {Object} [options] - output options
+ * @param {Object} options - output options
+ * @param {string} options.compression - compression format: av1, hevc
  * @param {number} [options.quality=50] - quality, integer 1-100
- * @param {string} [options.compression='av1'] - compression format: av1, hevc
  * @param {boolean} [options.lossless=false] - use lossless compression
  * @param {number} [options.effort=4] - CPU effort, between 0 (fastest) and 9 (slowest)
  * @param {string} [options.chromaSubsampling='4:4:4'] - set to '4:2:0' to use chroma subsampling
@@ -920,6 +917,11 @@ function avif (options) {
  */
 function heif (options) {
   if (is.object(options)) {
+    if (is.string(options.compression) && is.inArray(options.compression, ['av1', 'hevc'])) {
+      this.options.heifCompression = options.compression;
+    } else {
+      throw is.invalidParameterError('compression', 'one of: av1, hevc', options.compression);
+    }
     if (is.defined(options.quality)) {
       if (is.integer(options.quality) && is.inRange(options.quality, 1, 100)) {
         this.options.heifQuality = options.quality;
@@ -934,13 +936,6 @@ function heif (options) {
         throw is.invalidParameterError('lossless', 'boolean', options.lossless);
       }
     }
-    if (is.defined(options.compression)) {
-      if (is.string(options.compression) && is.inArray(options.compression, ['av1', 'hevc'])) {
-        this.options.heifCompression = options.compression;
-      } else {
-        throw is.invalidParameterError('compression', 'one of: av1, hevc', options.compression);
-      }
-    }
     if (is.defined(options.effort)) {
       if (is.integer(options.effort) && is.inRange(options.effort, 0, 9)) {
         this.options.heifEffort = options.effort;
@@ -955,6 +950,8 @@ function heif (options) {
         throw is.invalidParameterError('chromaSubsampling', 'one of: 4:2:0, 4:4:4', options.chromaSubsampling);
       }
     }
+  } else {
+    throw is.invalidParameterError('options', 'Object', options);
   }
   return this._updateFormatOut('heif', options);
 }

test/unit/heif.js

@@ -8,34 +8,34 @@ const assert = require('assert');
 const sharp = require('../../');
 
 describe('HEIF', () => {
-  it('called without options does not throw an error', () => {
+  it('called without options throws an error', () => {
-    assert.doesNotThrow(() => {
+    assert.throws(() => {
       sharp().heif();
     });
   });
   it('valid quality does not throw an error', () => {
     assert.doesNotThrow(() => {
-      sharp().heif({ quality: 80 });
+      sharp().heif({ compression: 'av1', quality: 80 });
     });
   });
   it('invalid quality should throw an error', () => {
     assert.throws(() => {
-      sharp().heif({ quality: 101 });
+      sharp().heif({ compression: 'av1', quality: 101 });
     });
   });
   it('non-numeric quality should throw an error', () => {
     assert.throws(() => {
-      sharp().heif({ quality: 'fail' });
+      sharp().heif({ compression: 'av1', quality: 'fail' });
     });
   });
   it('valid lossless does not throw an error', () => {
     assert.doesNotThrow(() => {
-      sharp().heif({ lossless: true });
+      sharp().heif({ compression: 'av1', lossless: true });
     });
   });
   it('non-boolean lossless should throw an error', () => {
     assert.throws(() => {
-      sharp().heif({ lossless: 'fail' });
+      sharp().heif({ compression: 'av1', lossless: 'fail' });
     });
   });
   it('valid compression does not throw an error', () => {
@@ -55,27 +55,27 @@ describe('HEIF', () => {
   });
   it('valid effort does not throw an error', () => {
     assert.doesNotThrow(() => {
-      sharp().heif({ effort: 6 });
+      sharp().heif({ compression: 'av1', effort: 6 });
     });
   });
   it('out of range effort should throw an error', () => {
     assert.throws(() => {
-      sharp().heif({ effort: 10 });
+      sharp().heif({ compression: 'av1', effort: 10 });
     });
   });
   it('invalid effort should throw an error', () => {
     assert.throws(() => {
-      sharp().heif({ effort: 'fail' });
+      sharp().heif({ compression: 'av1', effort: 'fail' });
     });
   });
   it('invalid chromaSubsampling should throw an error', () => {
     assert.throws(() => {
-      sharp().heif({ chromaSubsampling: 'fail' });
+      sharp().heif({ compression: 'av1', chromaSubsampling: 'fail' });
     });
   });
   it('valid chromaSubsampling does not throw an error', () => {
     assert.doesNotThrow(() => {
-      sharp().heif({ chromaSubsampling: '4:4:4' });
+      sharp().heif({ compression: 'av1', chromaSubsampling: '4:4:4' });
     });
   });
 });