Ensure op ordering is respected where possible #3319

Emit warnings when previous ops might be ignored
Flip and flop now occur before rotate, if any

docs/api-operation.md

@@ -16,8 +16,11 @@ Mirroring is supported and may infer the use of a flip operation.
 
 The use of `rotate` implies the removal of the EXIF `Orientation` tag, if any.
 
-Method order is important when both rotating and extracting regions,
-for example `rotate(x).extract(y)` will produce a different result to `extract(y).rotate(x)`.
+Only one rotation can occur per pipeline.
+Previous calls to `rotate` in the same pipeline will be ignored.
+
+Method order is important when rotating, resizing and/or extracting regions,
+for example `.rotate(x).extract(y)` will produce a different result to `.extract(y).rotate(x)`.
 
 ### Parameters
 
@@ -40,13 +43,24 @@ const pipeline = sharp()
 readableStream.pipe(pipeline);
 ```
 
+```javascript
+const rotateThenResize = await sharp(input)
+  .rotate(90)
+  .resize({ width: 16, height: 8, fit: 'fill' })
+  .toBuffer();
+const resizeThenRotate = await sharp(input)
+  .resize({ width: 16, height: 8, fit: 'fill' })
+  .rotate(90)
+  .toBuffer();
+```
+
 *   Throws **[Error][5]** Invalid parameters
 
 Returns **Sharp** 
 
 ## flip
 
-Flip the image about the vertical Y axis. This always occurs after rotation, if any.
+Flip the image about the vertical Y axis. This always occurs before rotation, if any.
 The use of `flip` implies the removal of the EXIF `Orientation` tag, if any.
 
 ### Parameters
@@ -63,7 +77,7 @@ Returns **Sharp**
 
 ## flop
 
-Flop the image about the horizontal X axis. This always occurs after rotation, if any.
+Flop the image about the horizontal X axis. This always occurs before rotation, if any.
 The use of `flop` implies the removal of the EXIF `Orientation` tag, if any.
 
 ### Parameters

docs/api-resize.md

@@ -36,6 +36,9 @@ Possible interpolation kernels are:
 *   `lanczos2`: Use a [Lanczos kernel][7] with `a=2`.
 *   `lanczos3`: Use a Lanczos kernel with `a=3` (the default).
 
+Only one resize can occur per pipeline.
+Previous calls to `resize` in the same pipeline will be ignored.
+
 ### Parameters
 
 *   `width` **[number][8]?** pixels wide the resultant image should be. Use `null` or `undefined` to auto-scale the width to match the height.

docs/changelog.md

@@ -14,6 +14,8 @@ Requires libvips v8.13.0
 
 * Remove previously-deprecated WebP `reductionEffort` and HEIF `speed` options. Use `effort` to control these.
 
+* The `flip` and `flop` operations will now occur before the `rotate` operation.
+
 * Use combined bounding box of alpha and non-alpha channels for `trim` operation.
   [#2166](https://github.com/lovell/sharp/issues/2166)
 
@@ -42,6 +44,10 @@ Requires libvips v8.13.0
 * Ensure only properties owned by the `withMetadata` EXIF Object are parsed.
   [#3292](https://github.com/lovell/sharp/issues/3292)
 
+* Ensure the order of `rotate`, `resize` and `extend` operations is respected where possible.
+  Emit warnings when previous calls in the same pipeline will be ignored.
+  [#3319](https://github.com/lovell/sharp/issues/3319)
+
 ## v0.30 - *dresser*
 
 Requires libvips v8.12.2