From d0534719bced1c23eae8693770bd100a99fcbbea Mon Sep 17 00:00:00 2001 From: Nolan Lawson Date: Mon, 21 May 2018 13:47:44 -0700 Subject: [PATCH] gen docs --- README.md | 771 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 457 insertions(+), 314 deletions(-) diff --git a/README.md b/README.md index 17cc725..8a3323f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -blob-util [![Build Status](https://travis-ci.org/nolanlawson/blob-util.svg)](https://travis-ci.org/nolanlawson/blob-util) +blob-util [![Build Status](https://travis-ci.org/nolanlawson/blob-util.svg)](https://travis-ci.org/nolanlawson/blob-util) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-typescript-blue.svg)](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. @@ -117,328 +117,161 @@ API -### Overview +## Index -* [createBlob(parts, options)](#createBlob) -* [createObjectURL(blob)](#createObjectURL) -* [revokeObjectURL(url)](#revokeObjectURL) -* [blobToBinaryString(blob)](#blobToBinaryString) -* [base64StringToBlob(base64, type)](#base64StringToBlob) -* [binaryStringToBlob(binary, type)](#binaryStringToBlob) -* [blobToBase64String(blob)](#blobToBase64String) -* [dataURLToBlob(dataURL)](#dataURLToBlob) -* [blobToDataURL(blob)](#blobToDataURL) -* [imgSrcToDataURL(src, type, crossOrigin, quality)](#imgSrcToDataURL) -* [canvasToBlob(canvas, type, quality)](#canvasToBlob) -* [imgSrcToBlob(src, type, crossOrigin, quality)](#imgSrcToBlob) -* [arrayBufferToBlob(buffer, type)](#arrayBufferToBlob) -* [blobToArrayBuffer(blob)](#blobToArrayBuffer) -* [arrayBufferToBinaryString(buffer)](#arrayBufferToBinaryString) -* [binaryStringToArrayBuffer(binary)](#binaryStringToArrayBuffer) - - -### createBlob(parts, options) -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). +### Functions -**Params** +* [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) -- parts `Array` - content of the Blob -- options `Object` - usually just {type: myContentType}, you can also pass a string for the content type +--- -**Returns**: `Blob` +## Functions -**Example**: + + +### arrayBufferToBinaryString + +▸ **arrayBufferToBinaryString**(buffer: *`ArrayBuffer`*): `string` + +Convert an `ArrayBuffer` to a binary string. + +Example: ```js -var myBlob = blobUtil.createBlob(['hello world'], {type: 'text/plain'}); +var myString = blobUtil.arrayBufferToBinaryString(arrayBuff) ``` - -### createObjectURL(blob) -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). +**Parameters:** -**Params** +| Param | Type | Description | +| ------ | ------ | ------ | +| buffer | `ArrayBuffer` | array buffer | -- blob `Blob` +**Returns:** `string` +binary string -**Returns**: `string` - url +___ + -**Example**: +### arrayBufferToBlob -```js -var myUrl = blobUtil.createObjectURL(blob); -``` +▸ **arrayBufferToBlob**(buffer: *`ArrayBuffer`*, type?: *`string`*): `Blob` - -### revokeObjectURL(url) -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). +Convert an `ArrayBuffer` to a `Blob`. -**Params** - -- url `string` - -**Example**: - -```js -blobUtil.revokeObjectURL(myUrl); -``` - - -### blobToBinaryString(blob) -Convert a Blob to a binary string. - -**Params** - -- blob `Blob` - -**Returns**: `Promise` - Promise that resolves with the binary string - -**Example**: - -```js -blobUtil.blobToBinaryString(blob).then(function (binaryString) { - // success -}).catch(function (err) { - // error -}); -``` - - -### base64StringToBlob(base64, type) -Convert a base64-encoded string to a Blob. - -**Params** - -- base64 `string` -- type `string` | `undefined` - the content type (optional) - -**Returns**: Blob - -**Example**: - -```js -var blob = blobUtil.base64StringToBlob(base64String); -``` - - -### binaryStringToBlob(binary, type) -Convert a binary string to a Blob. - -**Params** - -- binary `string` -- type `string` | `undefined` - the content type (optional) - -**Returns**: `Blob` - -**Example**: - -```js -var blob = blobUtil.binaryStringToBlob(binaryString); -``` - - -### blobToBase64String(blob) -Convert a Blob to a binary string. - -**Params** - -- blob `Blob` - -**Returns**: `Promise` - Promise that resolves with the binary string - - -**Example**: - -```js -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. - -**Params** - -- dataURL `string` - -**Returns**: `Blob` - -**Example**: - -```js -var blob = blobUtil.dataURLToBlob(dataURL); -``` - -### blobToDataURL(blob) -Convert a Blob to a data URL string -(e.g. 'data:image/png;base64,iVBORw0KG...'). - -**Params** - -- blob `Blob` - -**Returns**: `string` - data URL string - -**Example**: - -```js -var dataURL = blobUtil.blobToDataURL(blob); -``` - -### 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. - -

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**: - -```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 -}); -``` - - -### canvasToBlob(canvas, type, quality) -Convert a canvas to a Blob. - -**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**: - -```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 -}); -``` - - -### imgSrcToBlob(src, type, crossOrigin, quality) -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. - -**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**: - -```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 -}); -``` - - -### arrayBufferToBlob(buffer, type) -Convert an ArrayBuffer to a Blob. - -**Params** - -- buffer `ArrayBuffer` -- type `string` | `undefined` - the content type (optional) - -**Returns**: `Blob` - -**Example**: +Example: ```js var blob = blobUtil.arrayBufferToBlob(arrayBuff, 'audio/mpeg'); ``` - -### blobToArrayBuffer(blob) -Convert a Blob to an ArrayBuffer. +**Parameters:** -**Params** +| Param | Type | Description | +| ------ | ------ | ------ | +| buffer | `ArrayBuffer` | - | +| `Optional` type | `string` | the content type (optional) | -- blob `Blob` +**Returns:** `Blob` +Blob -**Returns**: `Promise` - Promise that resolves with the ArrayBuffer +___ + -**Example**: +### 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 + +___ + + +### 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 + +___ + + +### 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 + +___ + + +### blobToArrayBuffer + +▸ **blobToArrayBuffer**(blob: *`Blob`*): `Promise`<`ArrayBuffer`> + +Convert a `Blob` to an `ArrayBuffer`. + +Example: ```js blobUtil.blobToArrayBuffer(blob).then(function (arrayBuff) { @@ -448,38 +281,348 @@ blobUtil.blobToArrayBuffer(blob).then(function (arrayBuff) { }); ``` - -### arrayBufferToBinaryString(buffer) -Convert an ArrayBuffer to a binary string. Returns the binary string. +**Parameters:** -**Params** +| Param | Type | Description | +| ------ | ------ | ------ | +| blob | `Blob` | - | -- buffer `ArrayBuffer` +**Returns:** `Promise`<`ArrayBuffer`> +Promise that resolves with the ArrayBuffer -**Returns**: `string` - binary string +___ + -**Example**: +### blobToBase64String + +▸ **blobToBase64String**(blob: *`Blob`*): `Promise`<`string`> + +Convert a `Blob` to a binary string. + +Example: ```js -var myString = blobUtil.arrayBufferToBinaryString(arrayBuff) +blobUtil.blobToBase64String(blob).then(function (base64String) { + // success +}).catch(function (err) { + // error +}); ``` - -### binaryStringToArrayBuffer(binary) -Convert a binary string to an ArrayBuffer to a binary string. Returns the ArrayBuffer +**Parameters:** -**Params** +| Param | Type | Description | +| ------ | ------ | ------ | +| blob | `Blob` | - | -- binary string +**Returns:** `Promise`<`string`> +Promise that resolves with the binary string -**Returns**: `ArrayBuffer` +___ + -**Example**: +### blobToBinaryString + +▸ **blobToBinaryString**(blob: *`Blob`*): `Promise`<`string`> + +Convert a `Blob` to a binary string. + +Example: ```js -var myBuffer = blobUtil.binaryStringToArrayBuffer(binaryString) +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 + +___ + + +### 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 + +___ + + +### 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 + +___ + + +### 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 + +___ + + +### 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 + +___ + + +### 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 + +___ + + +### 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 + +___ + + +### 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 + +___ + + +### `` imgToCanvas + +▸ **imgToCanvas**(img: *`any`*): `HTMLCanvasElement` + +**Parameters:** + +| Param | Type | +| ------ | ------ | +| img | `any` | + +**Returns:** `HTMLCanvasElement` + +___ + + +### `` loadImage + +▸ **loadImage**(src: *`any`*, crossOrigin: *`any`*): `Promise`<`Object`> + +**Parameters:** + +| Param | Type | +| ------ | ------ | +| src | `any` | +| crossOrigin | `any` | + +**Returns:** `Promise`<`Object`> + +___ + + +### 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` + +___ + + + Credits