chore(release): 2.3.0

CHANGELOG.md

@@ -2,44 +2,50 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-<a name="2.2.1"></a>
+## [2.3.0](https://github.com/imgix/imgix-core-js/compare/2.2.1...2.3.0) (2019-03-04)
+
+* feat: add srcset option parameter to buildSrcSet() method signature (#118)
+* perf(srcset): memoize generated srcset width-pairs (#115)
+* fix: throw error when certain srcset modifiers are passed zero (#114)
+* feat: append variable qualities to dpr srcsets (#111)
+* feat: add support for defining a custom srcset width array (#110)
+* feat: add support for defining a custom srcset width tolerance (#109)
+* feat: add support for defining a min and max srcset width (#108)
+
+## [2.2.1](https://github.com/imgix/imgix-core-js/compare/2.2.0...2.2.1) (2019-11-27)
+
+* build(deps): remove typescript as runtime dependency ([#77](https://github.com/imgix/imgix-core-js/pull/77))
+
 ## [2.2.1](https://github.com/imgix/imgix-core-js/compare/2.2.0...2.2.1) (2019-11-27)
 
 * build(deps): remove typescript as runtime dependency ([#77](https://github.com/imgix/imgix-core-js/pull/77))
 
-<a name="2.2.0"></a>
 ## [2.2.0](https://github.com/imgix/imgix-core-js/compare/2.1.2...2.2.0) (2019-10-22)
 
 * feat: add typescript declaration file for `ImgixClient` ([#64](https://github.com/imgix/imgix-core-js/pull/64))
 
-<a name="2.1.2"></a>
 ## [2.1.2](https://github.com/imgix/imgix-core-js/compare/2.1.1...2.1.2) (2019-09-17)
 
 * fix: ensure URL-legal, path-illegal characters are encoded ([#61](https://github.com/imgix/imgix-core-js/pull/61))
 
-<a name="2.1.1"></a>
 ## [2.1.1](https://github.com/imgix/imgix-core-js/compare/2.1.0...2.1.1) (2019-07-28)
 
 * fix: include dpr parameter when generating fixed-width srcset ([#59](https://github.com/imgix/imgix-core-js/pull/59))
 
-<a name="2.1.0"></a>
 ## [2.1.0](https://github.com/imgix/imgix-core-js/compare/1.2.1...2.1.0) (2019-07-28)
 
 * feat: add srcset generation ([#53](https://github.com/imgix/imgix-core-js/pull/53))
 
-<a name="2.0.0"></a>
 # [2.0.0](https://github.com/imgix/imgix-core-js/compare/1.4.0...2.0.0) (2019-06-06)
 
 * fix: remove deprecated domain sharding functionality ([#42](https://github.com/imgix/imgix-core-js/pull/42))
 * fix: remove deprecated settings.host ([#45](https://github.com/imgix/imgix-core-js/pull/45))
 
-<a name="1.4.0"></a>
 ## [1.4.0](https://github.com/imgix/imgix-core-js/compare/1.3.0...1.4.0) (2019-06-05)
 
 * docs: deprecate settings.domains ([#43](https://github.com/imgix/imgix-core-js/pull/43))
 * feat: add settings.domain argument ([#44](https://github.com/imgix/imgix-core-js/pull/44))
 
-<a name="1.3.0"></a>
 ## [1.3.0](https://github.com/imgix/imgix-core-js/compare/1.2.1...1.3.0) (2019-05-07)
 
 *   deprecate domain sharding ([#39](https://github.com/imgix/imgix-core-js/pull/39))

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "imgix-core-js",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "homepage": "https://github.com/imgix/imgix-core-js",
   "authors": [
     "Kelly Sutton <[email protected]>",

dist/imgix-core-js.d.ts

@@ -8,13 +8,22 @@ declare class ImgixClient {
 
     constructor(opts: {domain: string; secureURLToken?: string; useHTTPS?: boolean; includeLibraryParam?: boolean;});
 
-
     buildURL(path: string, params?: {}): string;
     _sanitizePath(path: string): string;
     _buildParams(params: {}): string;
     _signParams(path: string, queryParams?: {}): string;
-    buildSrcSet(path: string, params?: {}): string;
-    _buildSrcSetPairs(path: string, params?: {}): string;
-    _buildDPRSrcSet(path: string, params?: {}): string;
+    buildSrcSet(path: string, params?: {}, options?: SrcSetOptions): string;
+    _buildSrcSetPairs(path: string, params?: {}, options?: SrcSetOptions): string;
+    _buildDPRSrcSet(path: string, params?: {}, options?: SrcSetOptions): string;
+
+}    
+
+interface SrcSetOptions {
+    widths?: number[];
+    widthTolerance?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    disableVariableQuality?: boolean;
 }
+
 export = ImgixClient;

dist/imgix-core-js.js

@@ -14,28 +14,25 @@
   var Base64 = _jsBase64.Base64 || _jsBase64;
 
   // package version used in the ix-lib parameter
-  var VERSION = '2.2.1';
+  var VERSION = '2.3.0';
   // regex pattern used to determine if a domain is valid
   var DOMAIN_REGEX = /^(?:[a-z\d\-_]{1,62}\.){0,125}(?:[a-z\d](?:\-(?=\-*[a-z\d])|[a-z]|\d){0,62}\.)[a-z\d]{1,63}$/i;
-  // returns an array of width values used during scrset generation
-  var TARGET_WIDTHS = (function() {
-    var resolutions = [];
-    var prev = 100;
-    var INCREMENT_PERCENTAGE = 8;
-    var MAX_SIZE = 8192;
-
-    var ensureEven = function(n){
-      return 2 * Math.round(n / 2);
-    };
-
-    while (prev <= MAX_SIZE) {
-      resolutions.push(ensureEven(prev));
-      prev *= 1 + (INCREMENT_PERCENTAGE / 100) * 2;
-    }
-
-    resolutions.push(MAX_SIZE);
-    return resolutions;
-  })();
+  // minimum generated srcset width
+  var MIN_SRCSET_WIDTH = 100;
+  // maximum generated srcset width
+  var MAX_SRCSET_WIDTH = 8192;
+  // default tolerable percent difference between srcset pair widths
+  var DEFAULT_SRCSET_WIDTH_TOLERANCE = .08;
+
+  // default quality parameter values mapped by each dpr srcset entry
+  var DPR_QUALITIES = {
+    1: 75,
+    2: 50,
+    3: 35,
+    4: 23,
+    5: 20
+  };
+
   // default ImgixClient settings passed in during instantiation
   var DEFAULTS = {
     domain: null,
@@ -75,7 +72,7 @@
       }
 
       this.settings.urlPrefix = this.settings.useHTTPS ? 'https://' : 'http://'
-    }
+    };
 
     ImgixClient.prototype.buildURL = function(path, params) {
       path = this._sanitizePath(path);
@@ -146,47 +143,155 @@
       }
     };
 
-    ImgixClient.prototype.buildSrcSet = function (path, params) {
+    ImgixClient.prototype.buildSrcSet = function (path, params, options) {
       var params = params || {};
       var width = params.w;
       var height = params.h;
       var aspectRatio = params.ar;
+      var options = options || {};
 
       if ((width) || (height && aspectRatio)) {
-        return this._buildDPRSrcSet(path, params);
-      }
-      else {
-        return this._buildSrcSetPairs(path, params);
+        return this._buildDPRSrcSet(path, params, options);
+      } else {
+        return this._buildSrcSetPairs(path, params, options);
       }
     };
 
-    ImgixClient.prototype._buildSrcSetPairs = function(path, params) {
+    ImgixClient.prototype._buildSrcSetPairs = function(path, params, options) {
       var srcset = '';
       var currentWidth;
+      var targetWidths;
+      var customWidths = options.widths;
+      var srcsetOptions = validateAndDestructureOptions(options);
+      var widthTolerance = srcsetOptions[0], minWidth = srcsetOptions[1], maxWidth = srcsetOptions[2];
+
+      if (customWidths) {
+        validateWidths(customWidths);
+        targetWidths = customWidths;
+      } else {
+        validateRange(minWidth, maxWidth);
+        validateWidthTolerance(widthTolerance);
+        targetWidths = this._generateTargetWidths(widthTolerance, minWidth, maxWidth);
+      }
 
-      for(var i = 0; i < TARGET_WIDTHS.length; i++) {
-        currentWidth = TARGET_WIDTHS[i];
+      for (var i = 0; i < targetWidths.length; i++) {
+        currentWidth = targetWidths[i];
         params.w = currentWidth;
         srcset += this.buildURL(path, params) + ' ' + currentWidth + 'w,\n';
       }
 
       return srcset.slice(0,-2);
     };
 
-    ImgixClient.prototype._buildDPRSrcSet = function(path, params) {
+    ImgixClient.prototype._buildDPRSrcSet = function(path, params, options) {
         var srcset = '';
         var targetRatios = [1, 2, 3, 4, 5];
         var currentRatio;
+        var disableVariableQuality = options.disableVariableQuality || false;
+        var quality = params.q;
 
-        for(var i = 0; i < targetRatios.length; i++) {
+        if (!disableVariableQuality) {
+          validateVariableQuality(disableVariableQuality);
+        }
+
+        for (var i = 0; i < targetRatios.length; i++) {
           currentRatio = targetRatios[i];
           params.dpr = currentRatio;
+
+          if (!disableVariableQuality) {
+            params.q = quality || DPR_QUALITIES[currentRatio];
+          }
+
           srcset += this.buildURL(path, params) + ' ' + currentRatio + 'x,\n'
         }
 
         return srcset.slice(0,-2);
     };
 
+    // a cache to store memoized srcset width-pairs
+    ImgixClient.prototype.targetWidthsCache = {};
+
+    // returns an array of width values used during scrset generation
+    ImgixClient.prototype._generateTargetWidths = function(widthTolerance, minWidth, maxWidth) {
+      var resolutions = [];
+      var INCREMENT_PERCENTAGE = widthTolerance;
+      var minWidth = Math.floor(minWidth);
+      var maxWidth = Math.floor(maxWidth);
+      var cacheKey = INCREMENT_PERCENTAGE + '/' + minWidth + '/' + maxWidth;
+
+      if (cacheKey in this.targetWidthsCache) {
+        return this.targetWidthsCache[cacheKey];
+      }
+
+      var ensureEven = function(n){
+        return 2 * Math.round(n / 2);
+      };
+
+      var prev = minWidth;
+      while (prev < maxWidth) {
+        resolutions.push(ensureEven(prev));
+        prev *= 1 + (INCREMENT_PERCENTAGE * 2);
+      }
+
+      resolutions.push(maxWidth);
+
+      this.targetWidthsCache[cacheKey] = resolutions;
+
+      return resolutions;
+    };
+
+    function validateAndDestructureOptions(options) {
+      if (options.widthTolerance !== undefined) {
+        validateWidthTolerance(options.widthTolerance);
+        widthTolerance = options.widthTolerance;
+      } else {
+        widthTolerance = DEFAULT_SRCSET_WIDTH_TOLERANCE;
+      }
+
+      minWidth = options.minWidth === undefined ? MIN_SRCSET_WIDTH : options.minWidth;
+      maxWidth = options.maxWidth === undefined ? MAX_SRCSET_WIDTH : options.maxWidth;
+
+      // Validate the range unless we're using defaults for both
+      if (minWidth != MIN_SRCSET_WIDTH || maxWidth != MAX_SRCSET_WIDTH) {
+        validateRange(minWidth, maxWidth);
+      }
+
+      return [widthTolerance, minWidth, maxWidth];
+    };
+
+    function validateRange(min, max) {
+      if (!(Number.isInteger(min) && Number.isInteger(max)) || (min <= 0 || max <= 0) || (min > max)) {
+          throw new Error('The min and max srcset widths can only be passed positive Number values');
+      }
+    };
+
+    function validateWidthTolerance(widthTolerance) {
+      if (typeof widthTolerance != 'number' || widthTolerance <= 0) {
+        throw new Error('The srcset widthTolerance argument can only be passed a positive scalar number');
+      }
+    };
+
+    function validateWidths(customWidths) {
+      if (!Array.isArray(customWidths) || !customWidths.length) {
+        throw new Error('The widths argument can only be passed a valid non-empty array of integers');
+      } else {
+        allPositiveIntegers = customWidths.every(
+          function(width) {
+            return Number.isInteger(width) && width > 0
+          }
+        );
+        if (!allPositiveIntegers) {
+          throw new Error('A custom widths argument can only contain positive integer values');
+        }
+      }
+    };
+
+    function validateVariableQuality(disableVariableQuality) {
+      if (typeof disableVariableQuality != 'boolean') {
+        throw new Error('The disableVariableQuality argument can only be passed a Boolean value');
+      }
+    };
+
     ImgixClient.VERSION = VERSION;
 
     return ImgixClient;