Clean Up API, Break Backwards Compatibility

[hipstersmoothie]

It seems like there is a lot of work being done to ensure that the package is backward compatible. This seems a little odd to me and has led to weird API decisions. Some methods are chain-able via this, some return promises, and some use a node style callback. I believe we should decide on a consistent way of doing things and bump to the version to 1.0.0 since we will probably be breaking some things along the way.

Another thing we should look at is how we pass arguments. Currently it can be variable and leads to many situation where we would have to make a major release(SemVer). Some other PRs and Issues discuss passing an options object instead. I think this would be the better way to go and would allow us to iterate quicker without breaking the API.

[hipstersmoothie]

@edi9999

[edi9999]

yes I agree with you.

The API should be coherent.

I think all methods returning something asynchronously should use Promises.

For option parameters, at least for boolean parameters, and probably for all, we should use an options object to set the parameters, makes sense.

[hipstersmoothie]

I propose every function now takes a options object even if they only have 1 arg.

• supports adding more options to any function in the future without breaking changes
• when done will be a breaking change
• simplifies the code a lot

We should also continue to support chaining as much as possible. So code like this should work.

Jimp.read('some-image.png')
	.resize(100, 100)
	.write('some-image-medium.png')
	.resize(25, 25)
	.write('some-image-small.png');

Functions that take node-style-callbacks that should return promises:

• Jimp.contructor(options) => Promise Jimp.create instead of new Jimp for clearer syntax [Feature request] [Breaking change] #308 new Jimp as promise #445
  • each if branch can resolve to keys on the object
• Jimp.loadFont
• Jimp.prototype.write The write promise callback is called before file exists #232 Promise based write/getBuffer #90 write, getBuffer, getBase64 can be Promised #374

Take callback but don't need to (nothing async is done). So we can just remove the callback. They will either return a value or this depending on current implmentation:

• Jimp.rgbaToInt
• Jimp.intToRGBA
• Jimp.prototype.deflateLevel
• Jimp.prototype.deflateStrategy
• Jimp.prototype.filterType
• Jimp.prototype.rgba
• Jimp.prototype.getPixelIndex
• Jimp.prototype.getPixelColor
• Jimp.prototype.setPixelColor
• Jimp.prototype.hash
• Jimp.prototype.blit
• Jimp.prototype.mask
• Jimp.prototype.composite
• Jimp.prototype.brightness
• Jimp.prototype.contrast
• Jimp.prototype.posterize
• Jimp.prototype.flip
• Jimp.prototype.gaussian
• Jimp.prototype.blur
• Jimp.prototype.convolution
• Jimp.prototype.opacity
• Jimp.prototype.fade
• Jimp.prototype.resize
• Jimp.prototype.cover
• Jimp.prototype.contain
• Jimp.prototype.scale
• Jimp.prototype.scaleToFit
• Jimp.prototype.pixelate
• Jimp.prototype.convolute
• Jimp.prototype.rotate
• Jimp.prototype.displace
• Jimp.prototype.color
• Jimp.prototype.print
• Jimp.prototype.getBuffer (used to have async stuff but now is totally sync) Promise based write/getBuffer #90 write, getBuffer, getBase64 can be Promised #374
• Jimp.prototype.getBase64 (see above, can be sync now) write, getBuffer, getBase64 can be Promised #374

Related Issues to be closed:

• Image processing Synchronously #220 Synchronous fallback. we should export sync versions of async function like read and write.
• Jimp allocates 200 MB memory on reading a 3.3 MB jpg #153 Look at switching image processing libraries to async
• Reading a non-image buffer prints weird error into console but returns a resolved promise #408 Jimp.read never resolves or rejects #347 Cannot read some PNG images but OK with all JPEG and BMP #286 Proper error reject

[hipstersmoothie]

@edi9999 thoughts?

[hipstersmoothie]

Should every method just return a promise? might make the desired syntax hard