chore(release): 3.6.0-rc.1

# [3.6.0-rc.1](v3.5.1...v3.6.0-rc.1) (2022-03-02) ### Features * add _buildSrcSet static method ([402a227](402a227)) * create static buildURL method ([1dbd9ef](1dbd9ef)) [skip ci]
imgix · Mar 2, 2022 · 26df3be · 26df3be
1 parent 697775e
commit 26df3be
Show file tree

Hide file tree

Showing 6 changed files with 296 additions and 9 deletions.
diff --git a/dist/imgix-js-core.umd.js b/dist/imgix-js-core.umd.js
diff --git a/dist/index.cjs.js b/dist/index.cjs.js
@@ -1,7 +1,8 @@
 'use strict';
 
-var md5 = require('md5');
 var jsBase64 = require('js-base64');
+var md5 = require('md5');
+var ufo = require('ufo');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -159,7 +160,7 @@ function _nonIterableRest() {
 }
 
 // package version used in the ix-lib parameter
-var VERSION = '3.5.0'; // regex pattern used to determine if a domain is valid
+var VERSION = '3.5.1'; // 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; // minimum generated srcset width
 
@@ -185,6 +186,43 @@ var DEFAULT_OPTIONS = {
   secureURLToken: null
 };
 
+/**
+ * `extractUrl()` extracts URL components from a source URL string.
+ * It does this by matching the URL against regular expressions. The irrelevant
+ * (entire URL) matches are removed and the rest stored as their corresponding
+ * URL components.
+ *
+ * `url` can be a partial, full URL, or full proxy URL. `useHttps` boolean
+ * defaults to false.
+ *
+ * @returns {Object} `{ protocol, auth, host, pathname, search, hash }`
+ * extracted from the URL.
+ */
+
+function extractUrl(_ref) {
+  var _ref$url = _ref.url,
+      url = _ref$url === void 0 ? '' : _ref$url,
+      _ref$useHttps = _ref.useHttps,
+      useHttps = _ref$useHttps === void 0 ? false : _ref$useHttps;
+  var defaultProto = useHttps ? 'https://' : 'http://';
+
+  if (!ufo.hasProtocol(url, true)) {
+    return extractUrl({
+      url: defaultProto + url
+    });
+  }
+  /**
+   * Regex are hard to parse. Leaving this breakdown here for reference.
+   * - `protocol`: ([^:/]+:)? - all not `:` or `/` & preceded by `:`, 0-1 times
+   * - `auth`: ([^/@]+@)? - all not `/` or `@` & preceded by `@`, 0-1 times
+   * - `domainAndPath`: (.*) /) -  all except line breaks
+   * - `domain`: `([^/]*)` - all before a `/` token
+   */
+
+
+  return ufo.parseURL(url);
+}
+
 function validateAndDestructureOptions(options) {
   var widthTolerance;
 
@@ -295,6 +333,30 @@ var ImgixClient = /*#__PURE__*/function () {
 
       return this.settings.urlPrefix + this.settings.domain + path + finalParams;
     }
+    /**
+     *`_buildURL` static method allows full URLs to be formatted for use with
+     * imgix.
+     *
+     * - If the source URL has included parameters, they are merged with
+     * the `params` passed in as an argument.
+     * - URL must match `{host}/{pathname}?{query}` otherwise an error is thrown.
+     *
+     * @param {String} url - full source URL path string, required
+     * @param {Object} params - imgix params object, optional
+     * @param {Object} options - imgix client options, optional
+     *
+     * @returns URL string formatted to imgix specifications.
+     *
+     * @example
+     * const client = ImgixClient
+     * const params = { w: 100 }
+     * const opts = { useHttps: true }
+     * const src = "sdk-test.imgix.net/amsterdam.jpg?h=100"
+     * const url = client._buildURL(src, params, opts)
+     * console.log(url)
+     * // => "https://sdk-test.imgix.net/amsterdam.jpg?h=100&w=100"
+     */
+
   }, {
     key: "_buildParams",
     value: function _buildParams() {
@@ -368,7 +430,21 @@ var ImgixClient = /*#__PURE__*/function () {
       } else {
         return this._buildSrcSetPairs(path, params, options);
       }
-    } // returns an array of width values used during srcset generation
+    }
+    /**
+     * _buildSrcSet static method allows full URLs to be used when generating
+     * imgix formatted `srcset` string values.
+     *
+     * - If the source URL has included parameters, they are merged with
+     * the `params` passed in as an argument.
+     * - URL must match `{host}/{pathname}?{query}` otherwise an error is thrown.
+     *
+     * @param {String} url - full source URL path string, required
+     * @param {Object} params - imgix params object, optional
+     * @param {Object} srcsetModifiers - srcset modifiers, optional
+     * @param {Object} clientOptions - imgix client options, optional
+     * @returns imgix `srcset` for full URLs.
+     */
 
   }, {
     key: "_buildSrcSetPairs",
@@ -452,6 +528,70 @@ var ImgixClient = /*#__PURE__*/function () {
     value: function version() {
       return VERSION;
     }
+  }, {
+    key: "_buildURL",
+    value: function _buildURL(url) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+
+      if (url == null) {
+        return '';
+      }
+
+      var _extractUrl = extractUrl({
+        url: url,
+        useHTTPS: options.useHTTPS
+      }),
+          host = _extractUrl.host,
+          pathname = _extractUrl.pathname,
+          search = _extractUrl.search; // merge source URL parameters with options parameters
+
+
+      var combinedParams = _objectSpread2(_objectSpread2({}, ufo.getQuery(search)), params); // throw error if no host or no pathname present
+
+
+      if (!host.length || !pathname.length) {
+        throw new Error('_buildURL: URL must match {host}/{pathname}?{query}');
+      }
+
+      var client = new ImgixClient(_objectSpread2({
+        domain: host
+      }, options));
+      return client.buildURL(pathname, combinedParams);
+    }
+  }, {
+    key: "_buildSrcSet",
+    value: function _buildSrcSet(url) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      var srcsetModifiers = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+      var clientOptions = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+
+      if (url == null) {
+        return '';
+      }
+
+      var _extractUrl2 = extractUrl({
+        url: url,
+        useHTTPS: clientOptions.useHTTPS
+      }),
+          host = _extractUrl2.host,
+          pathname = _extractUrl2.pathname,
+          search = _extractUrl2.search; // merge source URL parameters with options parameters
+
+
+      var combinedParams = _objectSpread2(_objectSpread2({}, ufo.getQuery(search)), params); // throw error if no host or no pathname present
+
+
+      if (!host.length || !pathname.length) {
+        throw new Error('_buildOneStepURL: URL must match {host}/{pathname}?{query}');
+      }
+
+      var client = new ImgixClient(_objectSpread2({
+        domain: host
+      }, clientOptions));
+      return client.buildSrcSet(pathname, combinedParams, srcsetModifiers);
+    } // returns an array of width values used during srcset generation
+
   }, {
     key: "targetWidths",
     value: function targetWidths() {

diff --git a/dist/index.d.ts b/dist/index.d.ts
@@ -28,6 +28,13 @@ declare class ImgixClient {
     widthTolerance?: number,
     cache?: {},
   ): number[];
+  static _buildURL(path: string, params?: {}, options?: {}): string;
+  static _buildSrcSet(
+    path: string,
+    params?: {},
+    srcSetOptions?: {},
+    clientOptions?: {},
+  ): string;
 }
 
 export type DevicePixelRatio = 1 | 2 | 3 | 4 | 5 | number;

diff --git a/dist/index.esm.js b/dist/index.esm.js
@@ -1,5 +1,6 @@
-import md5 from 'md5';
 import { Base64 } from 'js-base64';
+import md5 from 'md5';
+import { hasProtocol, parseURL, getQuery } from 'ufo';
 
 function ownKeys(object, enumerableOnly) {
   var keys = Object.keys(object);
@@ -153,7 +154,7 @@ function _nonIterableRest() {
 }
 
 // package version used in the ix-lib parameter
-var VERSION = '3.5.0'; // regex pattern used to determine if a domain is valid
+var VERSION = '3.5.1'; // 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; // minimum generated srcset width
 
@@ -179,6 +180,43 @@ var DEFAULT_OPTIONS = {
   secureURLToken: null
 };
 
+/**
+ * `extractUrl()` extracts URL components from a source URL string.
+ * It does this by matching the URL against regular expressions. The irrelevant
+ * (entire URL) matches are removed and the rest stored as their corresponding
+ * URL components.
+ *
+ * `url` can be a partial, full URL, or full proxy URL. `useHttps` boolean
+ * defaults to false.
+ *
+ * @returns {Object} `{ protocol, auth, host, pathname, search, hash }`
+ * extracted from the URL.
+ */
+
+function extractUrl(_ref) {
+  var _ref$url = _ref.url,
+      url = _ref$url === void 0 ? '' : _ref$url,
+      _ref$useHttps = _ref.useHttps,
+      useHttps = _ref$useHttps === void 0 ? false : _ref$useHttps;
+  var defaultProto = useHttps ? 'https://' : 'http://';
+
+  if (!hasProtocol(url, true)) {
+    return extractUrl({
+      url: defaultProto + url
+    });
+  }
+  /**
+   * Regex are hard to parse. Leaving this breakdown here for reference.
+   * - `protocol`: ([^:/]+:)? - all not `:` or `/` & preceded by `:`, 0-1 times
+   * - `auth`: ([^/@]+@)? - all not `/` or `@` & preceded by `@`, 0-1 times
+   * - `domainAndPath`: (.*) /) -  all except line breaks
+   * - `domain`: `([^/]*)` - all before a `/` token
+   */
+
+
+  return parseURL(url);
+}
+
 function validateAndDestructureOptions(options) {
   var widthTolerance;
 
@@ -289,6 +327,30 @@ var ImgixClient = /*#__PURE__*/function () {
 
       return this.settings.urlPrefix + this.settings.domain + path + finalParams;
     }
+    /**
+     *`_buildURL` static method allows full URLs to be formatted for use with
+     * imgix.
+     *
+     * - If the source URL has included parameters, they are merged with
+     * the `params` passed in as an argument.
+     * - URL must match `{host}/{pathname}?{query}` otherwise an error is thrown.
+     *
+     * @param {String} url - full source URL path string, required
+     * @param {Object} params - imgix params object, optional
+     * @param {Object} options - imgix client options, optional
+     *
+     * @returns URL string formatted to imgix specifications.
+     *
+     * @example
+     * const client = ImgixClient
+     * const params = { w: 100 }
+     * const opts = { useHttps: true }
+     * const src = "sdk-test.imgix.net/amsterdam.jpg?h=100"
+     * const url = client._buildURL(src, params, opts)
+     * console.log(url)
+     * // => "https://sdk-test.imgix.net/amsterdam.jpg?h=100&w=100"
+     */
+
   }, {
     key: "_buildParams",
     value: function _buildParams() {
@@ -362,7 +424,21 @@ var ImgixClient = /*#__PURE__*/function () {
       } else {
         return this._buildSrcSetPairs(path, params, options);
       }
-    } // returns an array of width values used during srcset generation
+    }
+    /**
+     * _buildSrcSet static method allows full URLs to be used when generating
+     * imgix formatted `srcset` string values.
+     *
+     * - If the source URL has included parameters, they are merged with
+     * the `params` passed in as an argument.
+     * - URL must match `{host}/{pathname}?{query}` otherwise an error is thrown.
+     *
+     * @param {String} url - full source URL path string, required
+     * @param {Object} params - imgix params object, optional
+     * @param {Object} srcsetModifiers - srcset modifiers, optional
+     * @param {Object} clientOptions - imgix client options, optional
+     * @returns imgix `srcset` for full URLs.
+     */
 
   }, {
     key: "_buildSrcSetPairs",
@@ -446,6 +522,70 @@ var ImgixClient = /*#__PURE__*/function () {
     value: function version() {
       return VERSION;
     }
+  }, {
+    key: "_buildURL",
+    value: function _buildURL(url) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      var options = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+
+      if (url == null) {
+        return '';
+      }
+
+      var _extractUrl = extractUrl({
+        url: url,
+        useHTTPS: options.useHTTPS
+      }),
+          host = _extractUrl.host,
+          pathname = _extractUrl.pathname,
+          search = _extractUrl.search; // merge source URL parameters with options parameters
+
+
+      var combinedParams = _objectSpread2(_objectSpread2({}, getQuery(search)), params); // throw error if no host or no pathname present
+
+
+      if (!host.length || !pathname.length) {
+        throw new Error('_buildURL: URL must match {host}/{pathname}?{query}');
+      }
+
+      var client = new ImgixClient(_objectSpread2({
+        domain: host
+      }, options));
+      return client.buildURL(pathname, combinedParams);
+    }
+  }, {
+    key: "_buildSrcSet",
+    value: function _buildSrcSet(url) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      var srcsetModifiers = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+      var clientOptions = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+
+      if (url == null) {
+        return '';
+      }
+
+      var _extractUrl2 = extractUrl({
+        url: url,
+        useHTTPS: clientOptions.useHTTPS
+      }),
+          host = _extractUrl2.host,
+          pathname = _extractUrl2.pathname,
+          search = _extractUrl2.search; // merge source URL parameters with options parameters
+
+
+      var combinedParams = _objectSpread2(_objectSpread2({}, getQuery(search)), params); // throw error if no host or no pathname present
+
+
+      if (!host.length || !pathname.length) {
+        throw new Error('_buildOneStepURL: URL must match {host}/{pathname}?{query}');
+      }
+
+      var client = new ImgixClient(_objectSpread2({
+        domain: host
+      }, clientOptions));
+      return client.buildSrcSet(pathname, combinedParams, srcsetModifiers);
+    } // returns an array of width values used during srcset generation
+
   }, {
     key: "targetWidths",
     value: function targetWidths() {

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@imgix/js-core",
   "description": "A JavaScript client library for generating image URLs with imgix",
-  "version": "3.5.1",
+  "version": "3.6.0-rc.1",
   "repository": "https://github.com/imgix/js-core",
   "license": "BSD-2-Clause",
   "main": "dist/index.cjs.js",