ted-crushinator-helpers - npm Package Compare versions

Comparing version 2.0.1 to 2.1.0

package.json

 {
   "name": "ted-crushinator-helpers",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "JS methods to produce crushinator'd image URLs.",
   "license": "MIT",
-  "main": "lib/crushinator.js",
+  "main": "dist/crushinator.js",
   "repository": {
@@ -12,17 +12,18 @@ "type": "git",
   "scripts": {
-    "build": "babel -d lib/ src/",
+    "build": "rollup -c",
     "lint": "jshint . && jscs .",
     "pretest": "npm run lint",
-    "test": "mocha --compilers js:babel-register"
+    "test": "mocha"
   },
   "dependencies": {},
   "devDependencies": {
-    "babel-cli": "^6.5.1",
-    "babel-plugin-transform-es2015-modules-umd": "^6.5.0",
     "babel-preset-es2015": "^6.5.0",
+    "babel-preset-es2015-rollup": "^1.1.1",
     "babel-register": "^6.5.2",
     "jscs": "^2.10.1",
     "jshint": "^2.9.1",
-    "mocha": "^2.4.5"
+    "mocha": "^2.4.5",
+    "rollup": "^0.25.4",
+    "rollup-plugin-babel": "^2.4.0"
   }
 }

README.md

 # JS Crushinator Helpers [![NPM Version](https://img.shields.io/npm/v/ted-crushinator-helpers.svg?style=flat)](https://npmjs.org/package/ted-crushinator-helpers) [![Build Status](https://travis-ci.org/tedconf/js-crushinator-helpers.svg?branch=master)](https://travis-ci.org/tedconf/js-crushinator-helpers)
 
-JavaScript methods to produce [Crushinator'd](https://github.com/tedconf/crushinator) image URLs.
+JavaScript methods to produce [Crushinator](https://github.com/tedconf/crushinator)-optimized image URLs.
 
 ```javascript
-crushinator.crush('http://images.ted.com/image.jpg', 'w=320')
+crushinator.crush('http://images.ted.com/image.jpg', { width: 320 })
   // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?w=320'
@@ -12,4 +12,6 @@ ```
 
-### With NPM
+The Crushinator helpers are distributed in [UMD](https://github.com/umdjs/umd) and have no other dependencies, so they can be imported as an AMD or as a CommonJS (Node) module. If no module system is available, the library will occupy the `crushinator` namespace in your app's global (e.g. `window.crushinator`).
 
+### Install with NPM
+
 ```
@@ -19,3 +21,3 @@ npm install ted-crushinator-helpers
 
-### With Bower
+### Install with Bower
 
@@ -26,8 +28,6 @@ ```
 
-### Manual
+### Manual installation
 
-Code in `lib/crushinator.js` can be copied to your application.
+Code in `dist/crushinator.js` can be copied to your application.
 
-This file is in UMD and has no other dependencies, so you can import it as an AMD/CommonJS module or simply let it occupy the `crushinator` namespace in your app's global.
-
 ## API
@@ -37,42 +37,146 @@
 
-### crush ( url , [ options ] )
+* [`crush(url, options)`](#crush) whose options can include:
+	* [width](#width)
+	* [height](#height)
+	* [quality](#quality)
+	* [crop](#crop)
+* [`uncrush(url)`](#uncrush)
+* [`crushable(url)`](#crushable)
 
-* url: (string, required) - URL of the image you would like to be crushed.
-* options: (string, optional) - String of query params corresponding to [crushinator's query params](https://github.com/tedconf/crushinator#image-resize-get-values)
+### crush
 
-For images on whitelisted domains, this method will return the URL for a crushed version of the specified image:
+Create a Crushinator-optimized image URL.
 
+**Method signature:**
+
 ```javascript
-crushinator.crush('http://images.ted.com/image.jpg', 'w=320')
+crushinator.crush ( url , [ options = {} ] )
+```
+
+**Parameters:**
+
+* `url` (string, required) - URL of the image you would like to be crushed.
+* `options` (object, optional) - Crushinator image options as a Plain Old JavaScript Object. Available options:
+	* `width` (number) - Target image width in pixels.
+	* `height` (number) - Target image height in pixels.
+	* `quality` (number) - Image quality as a percentage (0-100).
+	* `crop` (object) - Crop configuration. (See details below.)
+
+Example use:
+
+```javascript
+crushinator.crush('http://images.ted.com/image.jpg', { width:  320 })
   // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?w=320'
 ```
 
-For images hosted outside Crushinator's whitelisted domains, it will simply return the original URL:
+Crushinator only operates on images hosted on whiteslisted domains. If you use the `crush` method on an image outside of that whitelist, it will simply return the original URL:
 
 ```javascript
-crushinator.crush('http://celly.xxx/waffles.jpg', 'w=320')
+crushinator.crush('http://celly.xxx/waffles.jpg', { width: 320 })
   // => 'http://celly.xxx/waffles.jpg'
 ```
 
-It will also avoid double-crushing images, and will update old Crushinator URLs to the new host:
+This is helpful for dealing with dynamic image URLs.
 
+#### crush options
+
+Some more detail and examples for individual Crushinator helper options:
+
+##### width
+
+Number; target image width in pixels.
+
+If the original image is wider than this value, Crushinator's version will be resized to match it.
+
+Width and height are treated as a maximum. If width and height are both specified, Crushinator will resize the image to fit into a space of those dimensions while respecting its original aspect ratio.
+
+If neither the width nor the height are specified, the original image dimensions will be used.
+
+If the height is specified but not the width, the width of the resized image will respect the original aspect ratio as the image is resized by height.
+
+Example:
+
 ```javascript
-crushinator.crush('https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?w=320', 'w=640')
-  // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?w=640'
+crushinator.crush('http://images.ted.com/image.jpg', { width: 320 })
+  // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?w=320'
 ```
 
+##### height
+
+Number; target image height in pixels.
+
+If the original image is taller than this value, Crushinator's version will be resized to match it.
+
+Height and width are treated as a maximum. If height and width are both specified, Crushinator will resize the image to fit into a space of those dimensions while respecting its original aspect ratio.
+
+If neither the height nor the width are specified, the original image dimensions will be used.
+
+If the width is specified but not the height, the height of the resized image will respect the original aspect ratio as the image is resized by width.
+
+Example:
+
 ```javascript
-crushinator.crush('https://img-ssl.tedcdn.com/r/images.ted.com/image.jpg', 'w=320')
-  // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?w=320'
+crushinator.crush('http://images.ted.com/image.jpg', { height: 240 })
+  // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?h=240'
 ```
 
-### uncrush ( url )
+##### quality
 
-* url: (string, required) - URL of previously crushed image.
+Number; image quality as a percentage (`0`-`100`).
 
+If this value is omitted, a default image quality of 75% is used.
+
+Example:
+
+```javascript
+crushinator.crush('http://images.ted.com/image.jpg', { quality: 93 })
+  // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?quality=93'
+```
+
+##### crop
+
+Crop configuration options are passed in as an object with the following properties:
+
+* `width` (number) - Width of cropped section (in pixels).
+* `height` (number) - Height of cropped section (in pixels).
+* `x` (number) - Coordinate at which to start crop (pixels from left).
+* `y` (number) - Coordinate at which to start crop (pixels from top).
+* `afterResize` (boolean) - `true` if you want to crop the resized image rather than the original, `false` or omitted otherwise.
+
+By default, crop configuration will be applied to the original image, which will then be resized in accord with the `height` and `width` options. The `afterResize` option allows you to configure Crushinator to instead apply the crop _after_ resizing the image.
+
+Example:
+
+```javascript
+crushinator.crush('http://images.ted.com/image.jpg', {
+    width: 640,
+    height: 480,
+    crop: {
+      width: 200, height: 100,
+      x: 50, y: 25,
+      afterResize: true
+    }
+  })
+  // => 'https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?quality=93'
+```
+
+The above example would resize the original image to 640x480 and then take a 200x100 crop of the resized image, starting at 50x25.
+
+### uncrush
+
 Restore a previously crushed URL to its original form.
 
-Note that the protocol must be borrowed from the crushed URL regardless of whether or not the host actually supports HTTPS.
+**Method signature:**
 
 ```javascript
+crushinator.uncrush ( url )
+```
+
+**Parameters:**
+
+* `url` (string, required) - URL of previously crushed image.
+
+Example:
+
+```javascript
 crushinator.uncrush('https://tedcdnpi-a.akamaihd.net/r/images.ted.com/image.jpg?w=320')
@@ -82,8 +186,20 @@ // => 'https://images.ted.com/image.jpg'
 
-### crushable ( url )
+### crushable
 
-* url: (string, required) - URL of image to check.
+Test to see if an image URL is allowed by Crushinator's whitelist.
 
+**Method signature:**
+
+```javascript
+crushinator.crushable ( url )
+```
+
+**Parameters:**
+
+* `url` (string, required) - URL of image to check.
+
 Returns `true` if the image's host is in Crushinator's whitelist, `false` otherwise.
 
+Examples:
+
 ```javascript
@@ -107,3 +223,2 @@ crushinator.crushable('http://images.ted.com/image.jpg')
 * Change into the new directory
-* `nvm use` and if the required Node version is not installed on your system, `nvm install <version>`
 * `npm install`
@@ -117,5 +232,6 @@
 
-1. `npm run build` to produce a new `lib/crushinator.js`
+1. `npm run build` to produce a new `dist/crushinator.js`
 2. Update "version" in `package.json` and commit
 3. `git tag` the new semver
-4. Push master and the new tag upstream
+4. Push the master branch and new tag upstream to GitHub
+5. [`npm publish`](https://docs.npmjs.com/getting-started/publishing-npm-packages) the updated node module

src/crushinator.js

@@ -9,2 +9,6 @@ /**
 
+import * as cropOption from './lib/crop-option';
+import {ParamBuilder} from './lib/param-builder';
+import {prepNumber} from './lib/preppers';
+
 /**
@@ -35,4 +39,15 @@ A list of strings and regular expressions
 /**
+Possible options parameters for Crushinator.
+*/
+const params = new ParamBuilder({
+  width: { param: 'w', filter: prepNumber },
+  height: { param: 'h', filter: prepNumber },
+  quality: { param: 'quality', filter: prepNumber },
+  crop: cropOption,
+});
+
+/**
 Returns the portion of input URL that corresponds to the host name.
 
+@private
 @param {string} url
@@ -48,3 +63,3 @@ @returns {string}
 
-@param {string} url
+@param {string} url - URL of image to check.
 @returns {boolean}
@@ -59,3 +74,3 @@ */
 
-@param {string} url
+@param {string} url - Previously optimized image URL.
 @returns {string}
@@ -84,7 +99,22 @@ */
 @public
-@param {string} url
-@param {string} options
+@param {string} url - URL of image to be optimized.
+@param {Object} [options]
+@param {number} [options.width] - Target image width in pixels.
+@param {number} [options.height] - Target image height in pixels.
+@param {number} [options.quality] - Image quality as a percentage
+    (0-100).
+@param {Object} [options.crop] - Image crop configuration.
+@param {number} [options.crop.width] - Width of cropped section
+    in pixels.
+@param {number} [options.crop.height] - Height of cropped section
+    in pixels.
+@param {number} [options.crop.x] - Coordinate at which to start crop
+    (pixels from left.)
+@param {number} [options.crop.y] - Coordinate at which to start crop
+    (pixels from top.)
+@param {boolean} [options.crop.afterResize] - If true, crop will
+    take place after the image has been resized.
 @returns {string}
 */
-export function crush(url, options) {
+export function crush(url, options={}) {
   // Avoid double-crushing the image
@@ -98,2 +128,7 @@ url = uncrush(url);
 
+  // Stringify object options
+  if (typeof options === 'object') { // or: everything is a duck
+    options = params.serialize(options);
+  }
+
   return 'https://tedcdnpi-a.akamaihd.net/r/' +
@@ -100,0 +135,0 @@ url.replace(/.*\/\//, '') +

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

23359

increased by160.59%

Number of package files

10

increased by150%

Lines of code

456

increased by183.23%

Number of lines in readme file

231

increased by100.87%

Worsened metrics

Dev dependency count

8

increased by14.29%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes