blob-util

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:

* 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
------

Via npm:

``bash
npm install blob-util
`

ES modules are supported:

`js
import { canvasToBlob } from 'blob-util'
canvasToBlob(canvas, 'image/png').then(/ ... /)
`

Or as a script tag:

`html

`

Then it's available as a global blobUtil object:

`js
blobUtil.canvasToBlob(canvas, 'image/png').then(/ ... /)
`

Browser support
-----

As of v2.0.0, a built-in Promise polyfill is no longer provided. Assuming you provide a Promise
polyfill, the supported browsers are:

* Firefox
* Chrome
* Edge
* 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 in your page, you can let your users upload any file and then work with it as a Blob.

$3

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

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

`js
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 tag:

`js
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
-------

Index

$3

* arrayBufferToBinaryString
* arrayBufferToBlob
* base64StringToBlob
* binaryStringToArrayBuffer
* binaryStringToBlob
* blobToArrayBuffer
* blobToBase64String
* blobToBinaryString
* blobToDataURL
* canvasToBlob
* createBlob
* createObjectURL
* dataURLToBlob
* imgSrcToBlob
* imgSrcToDataURL
* revokeObjectURL

---

Functions

$3

▸ arrayBufferToBinaryString(buffer: ArrayBuffer): string

Convert an ArrayBuffer to a binary string.

Example:

`js
var myString = blobUtil.arrayBufferToBinaryString(arrayBuff)
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| buffer | ArrayBuffer | array buffer |

Returns: string
binary string

___


$3

▸ arrayBufferToBlob(buffer: ArrayBuffer, type?: string): Blob

Convert an ArrayBuffer to a Blob.

Example:

`js
var blob = blobUtil.arrayBufferToBlob(arrayBuff, 'audio/mpeg');
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| buffer | ArrayBuffer | - |
| Optional type | string | the content type (optional) |

Returns: Blob
Blob

___


$3

▸ base64StringToBlob(base64: string, type?: string): Blob

Convert a base64-encoded string to a Blob.

Example:

`js
var blob = blobUtil.base64StringToBlob(base64String);
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| base64 | string | base64-encoded string |
| Optional type | string | the content type (optional) |

Returns: Blob
Blob

___


$3

▸ binaryStringToArrayBuffer(binary: string): ArrayBuffer

Convert a binary string to an ArrayBuffer.

`js
var myBuffer = blobUtil.binaryStringToArrayBuffer(binaryString)
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| binary | string | binary string |

Returns: ArrayBuffer
array buffer

___


$3

▸ binaryStringToBlob(binary: string, type?: string): Blob

Convert a binary string to a Blob.

Example:

`js
var blob = blobUtil.binaryStringToBlob(binaryString);
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| binary | string | binary string |
| Optional type | string | the content type (optional) |

Returns: Blob
Blob

___


$3

▸ blobToArrayBuffer(blob: Blob): Promise<ArrayBuffer>

Convert a Blob to an ArrayBuffer.

Example:

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

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| blob | Blob | - |

Returns: Promise<ArrayBuffer>
Promise that resolves with the ArrayBuffer

___


$3

▸ blobToBase64String(blob: Blob): Promise<string>

Convert a Blob to a binary string.

Example:

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

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| blob | Blob | - |

Returns: Promise<string>
Promise that resolves with the binary string

___


$3

▸ blobToBinaryString(blob: Blob): Promise<string>

Convert a Blob to a binary string.

Example:

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

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| blob | Blob | - |

Returns: Promise<string>
Promise that resolves with the binary string

___


$3

▸ blobToDataURL(blob: Blob): Promise<string>

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

Example:

`js
var dataURL = blobUtil.blobToDataURL(blob);
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| blob | Blob | - |

Returns: Promise<string>
Promise that resolves with the data URL string

___


$3

▸ canvasToBlob(canvas: HTMLCanvasElement, type?: string, quality?: number): Promise<Blob>

Convert a canvas to a Blob.

Examples:

`js
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'):

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

Parameters:

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

Returns: Promise<Blob>
Promise that resolves with the Blob

___


$3

▸ createBlob(parts: Array<any>, properties?: BlobPropertyBag | string): Blob

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

Example:

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

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| parts | Array<any> | content of the Blob |
| Optional properties | BlobPropertyBag | string| usually {type: myContentType}, you can also pass a string for the content type |

Returns: Blob
Blob

___


$3

▸ createObjectURL(blob: Blob): string

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

Example:

`js
var myUrl = blobUtil.createObjectURL(blob);
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| blob | Blob | - |

Returns: string
url

___


$3

▸ dataURLToBlob(dataURL: string): Blob

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

Example:

`js
var blob = blobUtil.dataURLToBlob(dataURL);
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| dataURL | string | dataURL-encoded string |

Returns: Blob
Blob

___


$3

▸ imgSrcToBlob(src: string, type?: string, crossOrigin?: string, quality?: number): Promise<Blob>

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

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

Examples:

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

Parameters:

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

Returns: Promise<Blob>
Promise that resolves with the Blob

___


$3

▸ imgSrcToDataURL(src: string, type?: string, crossOrigin?: string, quality?: number): Promise<string>

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

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

Examples:

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

Parameters:

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

Returns: Promise<string>
Promise that resolves with the data URL string

___


$3

▸ revokeObjectURL(url: string): void

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

Example:

`js
blobUtil.revokeObjectURL(myUrl);
`

Parameters:

| Param | Type | Description |
| ------ | ------ | ------ |
| url | string | |

Returns: void`

___

Credits
----

Thanks to the rest of the PouchDB team for figuring most of this crazy stuff out.

Building the library
----

npm install
npm run build

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

To build the API docs and insert them in the README:

npm run doc