There have been a couple of cases where people expressed confusion with the current resize API.

The original "fluent" API was partly influenced by that of the gm module, the idea being that having a similar-ish API would make migration between the two modules easier. (The gm module builds an ordered list of flags to pass to the the underlying convert command line utility so it was always a bit of a leaky abstraction anyway.)

That was almost five years ago and I've wanted to improve this API for a while, especially as there is now a generation of developers who have never had to work with command line image processing tools.

The resize function currently has three signatures (that will remain):

resize(width)
resize(width, height) // supports null width for auto-scaling
resize(width, height, options)

This proposal is for an additional signature:

resize(options)

where options is an object with one or more of these properties:

• canvas
• crop
• embed
• fastShrinkOnLoad (existing property)
• height
• kernel (existing property)
• width
• withoutEnlargement

The following example usage of the proposed API would become possible.

NOTE: this proposed API has been updated - see #1135 (comment)

resize({ width }) // equivalent to resize(width)
resize({ height }) // equivalent to resize(null, height)
resize({ height, width }) // resize(width, height)
resize({ crop: 'east', height, width }) // resize(width, height).crop('east')
resize({ embed: 'west', height, width }) // resize(width, height).embed('west')
resize({ canvas: 'max', height, width }) // resize(width, height).max()
resize({ canvas: 'min', height, width }) // resize(width, height).min()
resize({ canvas: 'ignoreAspectRatio', height, width }) // resize(width, height).ignoreAspectRatio()
resize({ height, width, withoutEnlargement: true }) // resize(width, height).withoutEnlargement()
resize({ canvas: 'max', height, width, withoutEnlargement: true }) // resize(width, height).max().withoutEnlargement()

REPEATED NOTE: this proposed API has been updated - see #1135 (comment)

The max(), withoutEnlargement() etc. options-as-functions would be deprecated and (eventually) removed. This was the approach previously taken to move the no-longer-present progressive() function to become options of the jpeg() and png() output-selecting functions.

Constructive thoughts and feedback, as always, welcome.

Update: mention existing fastShrinkOnLoad and kernel options that will remain.

Update: consider moving operations that can result in an image of a different size, e.g. extend and trim, to the resize.js file (and therefore the resize docs).