initial status
This commit is contained in:
Simon Priet
623
node_modules/blob-util/README.md
generated
vendored
Normal file
623
node_modules/blob-util/README.md
generated
vendored
Normal file
@@ -0,0 +1,623 @@
|
||||
blob-util [](https://travis-ci.org/nolanlawson/blob-util) [](http://www.typescriptlang.org/)
|
||||
=====
|
||||
|
||||
`blob-util` is a [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob?redirectlocale=en-US&redirectslug=DOM%2FBlob) 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](http://pouchdb.com).
|
||||
|
||||
**Note**: this is a browser library. For Node.js, see [Buffers](http://nodejs.org/api/buffer.html).
|
||||
|
||||
**Topics**:
|
||||
|
||||
* [Install](#usage)
|
||||
* [Browser support](#browser-support)
|
||||
* [Tutorial](#tutorial)
|
||||
* [Playground](http://nolanlawson.github.io/blob-util)
|
||||
* [API](#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
|
||||
<script src="https://unpkg.com/blob-util/dist/blob-util.min.js"></script>
|
||||
```
|
||||
|
||||
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](http://caniuse.com/#search=blob) for details.
|
||||
|
||||
Tutorial
|
||||
--------
|
||||
|
||||
Blobs (<strong>b</strong>inary <strong>l</strong>arge <strong>ob</strong>jects) are the modern way of working with binary data in the browser. The browser support is [very good](http://caniuse.com/#search=blob).
|
||||
|
||||
Once you have a Blob, you can make it available offline by storing it in [IndexedDB](http://www.w3.org/TR/IndexedDB/), [PouchDB](http://pouchdb.com/), [LocalForage](https://mozilla.github.io/localForage/), or other in-browser databases. So it's the perfect format for working with offline images, sound, and video.
|
||||
|
||||
A [File](https://developer.mozilla.org/en-US/docs/Web/API/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.
|
||||
|
||||
<img id="kirby" alt="Kirby" src="./test/kirby.gif"/>
|
||||
|
||||
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 `<img/>` 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](http://nolanlawson.github.io/blob-util). Super fun!
|
||||
|
||||
<img src="blob-util.gif"/>
|
||||
|
||||
|
||||
API
|
||||
-------
|
||||
|
||||
<!-- begin insert API -->
|
||||
|
||||
## Index
|
||||
|
||||
### Functions
|
||||
|
||||
* [arrayBufferToBinaryString](#arraybuffertobinarystring)
|
||||
* [arrayBufferToBlob](#arraybuffertoblob)
|
||||
* [base64StringToBlob](#base64stringtoblob)
|
||||
* [binaryStringToArrayBuffer](#binarystringtoarraybuffer)
|
||||
* [binaryStringToBlob](#binarystringtoblob)
|
||||
* [blobToArrayBuffer](#blobtoarraybuffer)
|
||||
* [blobToBase64String](#blobtobase64string)
|
||||
* [blobToBinaryString](#blobtobinarystring)
|
||||
* [blobToDataURL](#blobtodataurl)
|
||||
* [canvasToBlob](#canvastoblob)
|
||||
* [createBlob](#createblob)
|
||||
* [createObjectURL](#createobjecturl)
|
||||
* [dataURLToBlob](#dataurltoblob)
|
||||
* [imgSrcToBlob](#imgsrctoblob)
|
||||
* [imgSrcToDataURL](#imgsrctodataurl)
|
||||
* [revokeObjectURL](#revokeobjecturl)
|
||||
|
||||
---
|
||||
|
||||
## Functions
|
||||
|
||||
<a id="arraybuffertobinarystring"></a>
|
||||
|
||||
### arrayBufferToBinaryString
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="arraybuffertoblob"></a>
|
||||
|
||||
### arrayBufferToBlob
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="base64stringtoblob"></a>
|
||||
|
||||
### base64StringToBlob
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="binarystringtoarraybuffer"></a>
|
||||
|
||||
### binaryStringToArrayBuffer
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="binarystringtoblob"></a>
|
||||
|
||||
### binaryStringToBlob
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="blobtoarraybuffer"></a>
|
||||
|
||||
### blobToArrayBuffer
|
||||
|
||||
▸ **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`
|
||||
|
||||
___
|
||||
<a id="blobtobase64string"></a>
|
||||
|
||||
### blobToBase64String
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="blobtobinarystring"></a>
|
||||
|
||||
### blobToBinaryString
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="blobtodataurl"></a>
|
||||
|
||||
### blobToDataURL
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="canvastoblob"></a>
|
||||
|
||||
### canvasToBlob
|
||||
|
||||
▸ **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`
|
||||
|
||||
___
|
||||
<a id="createblob"></a>
|
||||
|
||||
### createBlob
|
||||
|
||||
▸ **createBlob**(parts: *`Array`<`any`>*, properties?: * `BlobPropertyBag` | `string`*): `Blob`
|
||||
|
||||
Shim for [`new Blob()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob.Blob) to support [older browsers that use the deprecated `BlobBuilder` API](http://caniuse.com/blob).
|
||||
|
||||
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
|
||||
|
||||
___
|
||||
<a id="createobjecturl"></a>
|
||||
|
||||
### createObjectURL
|
||||
|
||||
▸ **createObjectURL**(blob: *`Blob`*): `string`
|
||||
|
||||
Shim for [`URL.createObjectURL()`](https://developer.mozilla.org/en-US/docs/Web/API/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
|
||||
|
||||
___
|
||||
<a id="dataurltoblob"></a>
|
||||
|
||||
### dataURLToBlob
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="imgsrctoblob"></a>
|
||||
|
||||
### imgSrcToBlob
|
||||
|
||||
▸ **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`
|
||||
|
||||
___
|
||||
<a id="imgsrctodataurl"></a>
|
||||
|
||||
### imgSrcToDataURL
|
||||
|
||||
▸ **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
|
||||
|
||||
___
|
||||
<a id="revokeobjecturl"></a>
|
||||
|
||||
### revokeObjectURL
|
||||
|
||||
▸ **revokeObjectURL**(url: *`string`*): `void`
|
||||
|
||||
Shim for [`URL.revokeObjectURL()`](https://developer.mozilla.org/en-US/docs/Web/API/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`
|
||||
|
||||
___
|
||||
|
||||
|
||||
|
||||
<!-- end insert API -->
|
||||
|
||||
Credits
|
||||
----
|
||||
|
||||
Thanks to the rest of [the PouchDB team](https://github.com/pouchdb/pouchdb/graphs/contributors) 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
|
||||
Reference in New Issue
Block a user