blob-util

What is blob-util?

The blob-util npm package is a collection of utilities for working with Blob objects in JavaScript. It simplifies common tasks such as converting blobs to base64 strings, creating blobs from various data types, and more. This package is particularly useful when dealing with binary data in web applications, making it easier to handle file uploads, image processing, and other blob-related operations.

What are blob-util's main functionalities?

Convert Blob to Base64 String

This feature allows you to convert a Blob object into a base64 encoded string. This is useful for uploading files as base64 encoded strings or displaying images directly in the browser using the base64 string.

blobUtil.blobToBase64String(blob).then(function (base64String) {
  // use your base64 string here
}).catch(function (err) {
  // handle any errors
});

Create Blob from Base64 String

This feature enables the creation of a Blob object from a base64 encoded string. It's useful for retrieving images or files that are stored as base64 strings and converting them back into a usable Blob format.

blobUtil.base64StringToBlob(base64String).then(function (blob) {
  // use your blob here
}).catch(function (err) {
  // handle any errors
});

Convert Blob to Binary String

This functionality converts a Blob into a binary string. This can be useful for processing or analyzing the binary data of files directly in JavaScript.

blobUtil.blobToBinaryString(blob).then(function (binaryString) {
  // use your binary string here
}).catch(function (err) {
  // handle any errors
});

Other packages similar to blob-util

filepond

FilePond is a flexible and fun JavaScript file upload library that can handle multiple files and has extensive options for image preview, file validation, and drag and drop. It's more focused on the UI aspect of file handling compared to blob-util, but it also deals with Blob objects when processing files.

pica

Pica is a library designed for resizing images in the browser with high quality and performance. While it primarily focuses on image processing, it works with Blob objects for loading and saving images. Compared to blob-util, Pica is more specialized in image manipulation.

README

blob-util

blob-util is a Blob library for busy people.

It offers a small set of cross-browser utilities for translating Blobs to and from different formats:

• <img/> tags
• base 64 strings
• binary strings
• ArrayBuffers
• data URLs
• canvas

It's also a good pairing with the attachment API in PouchDB.

Note: this is a browser library. For Node.js, see Buffers.

Topics:

• Install
• Browser support
• Tutorial
• Playground
• API

Install

Download it from the dist/ folder above, or use NPM:

$ npm install blob-util

or Bower:

$ bower install blob-util

Then stick it in your HTML:

<script src="blob-util.js"></script>

Now you have a window.blobUtil object. Or if you don't like globals, you can use Browserify.

Browser support

• Firefox
• Chrome
• IE 10+
• Safari 6+
• iOS 6+
• Android 4+
• Any browser with either Blob or the older BlobBuilder; see caniuse for details.

Tutorial

Blobs (binary large objects) are the modern way of working with binary data in the browser. The browser support is very good.

Once you have a Blob, you can make it available offline by storing it in IndexedDB, PouchDB, LocalForage, or other in-browser databases. So it's the perfect format for working with offline images, sound, and video.

A File is also a Blob. So if you have an <input type="file"> in your page, you can let your users upload any file and then work with it as a Blob.

Example

Here's Kirby. He's a famous little Blob.

So let's fulfill his destiny, and convert him to a real Blob object.

var img = document.getElementById('kirby');

blobUtil.imgSrcToBlob(img.src).then(function (blob) {
  // ladies and gents, we have a blob
}).catch(function (err) {
  // image failed to load
});

(Don't worry, this won't download the image twice, because browsers are smart.)

Now that we have a Blob, we can convert it to a URL and use that as the source for another <img/> tag:

var blobURL = blobUtil.createObjectURL(blob);

var newImg = document.createElement('img');
newImg.src = blobURL;

document.body.appendChild(newImg);

So now we have two Kirbys - one with a normal URL, and the other with a blob URL. You can try this out yourself in the blob-util playground. Super fun!

API

Warning: this API uses Promises, because it's not 2009 anymore.

Overview

• createBlob(parts, options)
• createObjectURL(blob)
• revokeObjectURL(url)
• blobToBinaryString(blob)
• base64StringToBlob(base64, type)
• binaryStringToBlob(binary, type)
• blobToBase64String(blob)
• dataURLToBlob(dataURL)
• blobToDataURL(blob)
• imgSrcToDataURL(src, type, crossOrigin, quality)
• canvasToBlob(canvas, type, quality)
• imgSrcToBlob(src, type, crossOrigin, quality)
• arrayBufferToBlob(buffer, type)
• blobToArrayBuffer(blob)

createBlob(parts, options)

Shim for new Blob() to support older browsers that use the deprecated BlobBuilder API.

Params

• parts Array - content of the Blob
• options Object - usually just {type: myContentType}

Returns: Blob

Example:

var myBlob = blobUtil.createBlob(['hello world'], {type: 'text/plain'});

createObjectURL(blob)

Shim for URL.createObjectURL() to support browsers that only have the prefixed webkitURL (e.g. Android <4.4).

Params

• blob Blob

Returns: string - url

Example:

var myUrl = blobUtil.createObjectURL(blob);

revokeObjectURL(url)

Shim for URL.revokeObjectURL() to support browsers that only have the prefixed webkitURL (e.g. Android <4.4).

Params

• url string

Example:

blobUtil.revokeObjectURL(myUrl);

blobToBinaryString(blob)

Convert a Blob to a binary string. Returns a Promise.

Params

• blob Blob

Returns: Promise - Promise that resolves with the binary string

Example:

blobUtil.blobToBinaryString(blob).then(function (binaryString) {
  // success
}).catch(function (err) {
  // error
});

base64StringToBlob(base64, type)

Convert a base64-encoded string to a Blob. Returns a Promise.

Params

• base64 string
• type string | undefined - the content type (optional)

Returns: Promise - Promise that resolves with the Blob

Example:

blobUtil.base64StringToBlob(base64String).then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

binaryStringToBlob(binary, type)

Convert a binary string to a Blob. Returns a Promise.

Params

• binary string
• type string | undefined - the content type (optional)

Returns: Promise - Promise that resolves with the Blob

Example:

blobUtil.binaryStringToBlob(binaryString).then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

blobToBase64String(blob)

Convert a Blob to a binary string. Returns a Promise.

Params

• blob Blob

Returns: Promise - Promise that resolves with the binary string

Example:

blobUtil.blobToBase64String(blob).then(function (base64String) {
  // success
}).catch(function (err) {
  // error
});

dataURLToBlob(dataURL)

Convert a data URL string (e.g. 'data:image/png;base64,iVBORw0KG...') to a Blob. Returns a Promise.

Params

• dataURL string

Returns: Promise - Promise that resolves with the Blob

Example:

blobUtil.dataURLToBlob(dataURL).then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

###blobToDataURL(blob) Convert a Blob to a data URL string (e.g. 'data:image/png;base64,iVBORw0KG...'). Returns a Promise.

Params

• blob Blob

Returns: Promise - Promise that resolves with the data URL string

Example:

blobUtil.blobToDataURL(blob).then(function (dataURL) {
  // success
}).catch(function (err) {
  // error
});

imgSrcToDataURL(src, type, crossOrigin, quality)

Convert an image's src URL to a data URL by loading the image and painting it to a canvas. Returns a Promise.

Note: this will coerce the image to the desired content type, and it will only paint the first frame of an animated GIF.

Params

• src string
• type string | undefined - the content type (optional, defaults to 'image/png')
• crossOrigin string | undefined - for CORS-enabled images, set this to 'Anonymous' to avoid "tainted canvas" errors
• quality number | undefined - a number between 0 and 1 indicating image quality if the requested type is 'image/jpeg' or 'image/webp'

Returns: Promise - Promise that resolves with the data URL string

Examples:

blobUtil.imgSrcToDataURL('http://mysite.com/img.png').then(function (dataURL) {
  // success
}).catch(function (err) {
  // error
});

blobUtil.imgSrcToDataURL('http://some-other-site.com/img.jpg', 'image/jpeg', 
                         'Anonymous', 1.0).then(function (dataURL) {
  // success
}).catch(function (err) {
  // error
});

canvasToBlob(canvas, type, quality)

Convert a canvas to a Blob. Returns a Promise.

Params

• canvas string
• type string | undefined - the content type (optional, defaults to 'image/png')
• quality number | undefined - a number between 0 and 1 indicating image quality if the requested type is 'image/jpeg' or 'image/webp'

Returns: Promise - Promise that resolves with the Blob

Examples:

blobUtil.canvasToBlob(canvas).then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

Most browsers support converting a canvas to both 'image/png' and 'image/jpeg'. You may also want to try 'image/webp', which will work in some browsers like Chrome (and in other browsers, will just fall back to 'image/png'):

blobUtil.canvasToBlob(canvas, 'image/webp').then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

imgSrcToBlob(src, type, crossOrigin, quality)

Convert an image's src URL to a Blob by loading the image and painting it to a canvas. Returns a Promise.

Note: this will coerce the image to the desired content type, and it will only paint the first frame of an animated GIF.

Params

• src string
• type string | undefined - the content type (optional, defaults to 'image/png')
• crossOrigin string | undefined - for CORS-enabled images, set this to 'Anonymous' to avoid "tainted canvas" errors
• quality number | undefined - a number between 0 and 1 indicating image quality if the requested type is 'image/jpeg' or 'image/webp'

Returns: Promise - Promise that resolves with the Blob

Examples:

blobUtil.imgSrcToBlob('http://mysite.com/img.png').then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

blobUtil.imgSrcToBlob('http://some-other-site.com/img.jpg', 'image/jpeg', 
                         'Anonymous', 1.0).then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

arrayBufferToBlob(buffer, type)

Convert an ArrayBuffer to a Blob. Returns a Promise.

Params

• buffer ArrayBuffer
• type string | undefined - the content type (optional)

Returns: Promise - Promise that resolves with the Blob

Example:

blobUtil.arrayBufferToBlob(arrayBuff, 'audio/mpeg').then(function (blob) {
  // success
}).catch(function (err) {
  // error
});

blobToArrayBuffer(blob)

Convert a Blob to an ArrayBuffer. Returns a Promise.

Params

• blob Blob

Returns: Promise - Promise that resolves with the ArrayBuffer

Example:

blobUtil.blobToArrayBuffer(blob).then(function (arrayBuff) {
  // success
}).catch(function (err) {
  // error
});

Credits

Thanks to webmodules/blob for the Blob constructor shim, and to the rest of the PouchDB team for figuring most of this crazy stuff out.

Building the library

npm install
npm run build

To generate documentation in doc/:

npm run jsdoc

or in markdown format as api.md

npm run jsdoc2md

The playground is just jsdoc with some extra text containing Kirby and the code samples and such.

So unfortunately you will need to do a manual diff to get the docs up to date. You'll need to diff:

• README.md to its previous version (make sure to keep the code samples, which were manually added)
• docs to its previous version

Testing the library

npm install

Then to test in the browser using Saucelabs:

npm test

Or to test locally in your browser of choice:

npm run test-local