Deprecate background, add op-specific prop to resize/extend/flatten #1392

lib/colour.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const deprecate = require('util').deprecate;
+
 const color = require('color');
 const is = require('./is');
 
@@ -16,25 +18,20 @@ const colourspace = {
 };
 
 /**
- * Set the background for the `embed`, `flatten` and `extend` operations.
- * The default background is `{r: 0, g: 0, b: 0, alpha: 1}`, black without transparency.
- *
- * Delegates to the _color_ module, which can throw an Error
- * but is liberal in what it accepts, clipping values to sensible min/max.
- * The alpha value is a float between `0` (transparent) and `1` (opaque).
- *
- * @param {String|Object} rgba - parsed by the [color](https://www.npmjs.org/package/color) module to extract values for red, green, blue and alpha.
- * @returns {Sharp}
- * @throws {Error} Invalid parameter
+ * @deprecated
+ * @private
  */
 function background (rgba) {
   const colour = color(rgba);
-  this.options.background = [
+  const background = [
     colour.red(),
     colour.green(),
     colour.blue(),
     Math.round(colour.alpha() * 255)
   ];
+  this.options.resizeBackground = background;
+  this.options.extendBackground = background;
+  this.options.flattenBackground = background.slice(0, 3);
   return this;
 }
 
@@ -102,23 +99,45 @@ function toColorspace (colorspace) {
   return this.toColourspace(colorspace);
 }
 
+/**
+ * Update a colour attribute of the this.options Object.
+ * @private
+ * @param {String} key
+ * @param {String|Object} val
+ * @throws {Error} Invalid key
+ */
+function _setColourOption (key, val) {
+  if (is.object(val) || is.string(val)) {
+    const colour = color(val);
+    this.options[key] = [
+      colour.red(),
+      colour.green(),
+      colour.blue(),
+      Math.round(colour.alpha() * 255)
+    ];
+  }
+}
+
 /**
  * Decorate the Sharp prototype with colour-related functions.
  * @private
  */
 module.exports = function (Sharp) {
-  // Public instance functions
   [
-    background,
+    // Public
     tint,
     greyscale,
     grayscale,
     toColourspace,
-    toColorspace
+    toColorspace,
+    // Private
+    _setColourOption
   ].forEach(function (f) {
     Sharp.prototype[f.name] = f;
   });
   // Class attributes
   Sharp.colourspace = colourspace;
   Sharp.colorspace = colourspace;
+  // Deprecated
+  Sharp.prototype.background = deprecate(background, 'background(background) is deprecated, use resize({ background }), extend({ background }) or flatten({ background }) instead');
 };