blob-util

blob-util is a Blob library for busy people.

If you want an easy way to work with binary data in the browser, or you don't even know what a Blob is, then this is the library for you.

blob-util offers cross-browser utilities for translating Blobs to and from different formats:

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

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

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

Usage

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

npm install blob-util
# or:
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.

Quick Start

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. Neato!

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)
• imgSrcToDataURL(src, type)
• canvasToBlob(canvas, type)
• imgSrcToBlob(src, type)
• 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
###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
###revokeObjectURL(url) Shim for URL.revokeObjectURL() to support browsers that only have the prefixed webkitURL (e.g. Android <4.4).

Params

• url string

###blobToBinaryString(blob) Convert a Blob to a binary string. Returns a Promise.

Params

• blob Blob

Returns: Promise - Promise that resolves with the binary string
###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
###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
###blobToBase64String(blob) Convert a Blob to a binary string. Returns a Promise.

Params

• blob Blob

Returns: Promise - Promise that resolves with the binary string
###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
###imgSrcToDataURL(src, type) 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')

Returns: Promise - Promise that resolves with the data URL string
###canvasToBlob(canvas, type) Convert a canvas to a Blob. Returns a Promise.

Params

• canvas string
• type string | undefined - the content type (optional, defaults to 'image/png')

Returns: Promise - Promise that resolves with the Blob
###imgSrcToBlob(src, type) 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')

Returns: Promise - Promise that resolves with the Blob
###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
###blobToArrayBuffer(blob) Convert a Blob to an ArrayBuffer. Returns a Promise.

Params

• blob Blob

Returns: Promise - Promise that resolves with the ArrayBuffer

Building the library

npm install
npm run build

Your plugin is now located at dist/pouchdb.mypluginname.js and dist/pouchdb.mypluginname.min.js and is ready for distribution.

To generate documentation in doc/:

npm run jsdoc

or in markdown format as api.md

npm run jsdoc2md

Testing the library

In the browser

Run npm run dev and then point your favorite browser to http://127.0.0.1:8001/test/index.html.

The query param ?grep=mysearch will search for tests matching mysearch.

Automated browser tests

You can run e.g.

CLIENT=selenium:firefox npm test
CLIENT=selenium:phantomjs npm test

This will run the tests automatically and the process will exit with a 0 or a 1 when it's done. Firefox uses IndexedDB, and PhantomJS uses WebSQL.