diff --git a/README.md b/README.md index f241b50..17cc725 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,8 @@ So now we have two Kirbys - one with a normal URL, and the other with a blob URL API ------- + + ### Overview * [createBlob(parts, options)](#createBlob) @@ -478,6 +480,8 @@ Convert a binary string to an ArrayBuffer to a binary string. Retur var myBuffer = blobUtil.binaryStringToArrayBuffer(binaryString) ``` + + Credits ---- @@ -501,3 +505,7 @@ Then to test in the browser using Saucelabs: 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 \ No newline at end of file diff --git a/bin/write-docs-to-readme.js b/bin/write-docs-to-readme.js new file mode 100644 index 0000000..787cb27 --- /dev/null +++ b/bin/write-docs-to-readme.js @@ -0,0 +1,26 @@ +const pify = require('pify') +const fs = require('fs') +const writeFile = pify(fs.writeFile.bind(fs)) +const readFile = pify(fs.readFile.bind(fs)) +const path = require('path') + +async function main () { + let inputMd = await readFile(path.join(__dirname, '../docs-tmp/modules/_blob_util_.md'), 'utf8') + + inputMd = inputMd.substring(inputMd.indexOf('## Index')) + inputMd = inputMd.replace(/_blob_util_\.md#/g, '#') + + let outputMdFile = path.join(__dirname, '../README.md') + let outputMd = await readFile(outputMdFile, 'utf8') + + outputMd = outputMd.replace( + /[\s\S]+/, + `\n\n${inputMd}\n\n` + ) + await writeFile(outputMdFile, outputMd, 'utf8') +} + +main().catch(e => { + console.error(e) + process.exit(1) +}) diff --git a/package.json b/package.json index 3a2080c..254d475 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "url": "https://github.com/nolanlawson/blob-util/issues" }, "scripts": { - "lint": "standard test/*js && tslint src/*ts", + "lint": "standard test/*js bin/*js && tslint src/*ts", "test": "npm run build && npm run lint && zuul --no-coverage ./test/test.js", "test-local": "npm run build && zuul ./test/test.js --local 9000 --no-coverage", "clean": "rimraf dist lib && mkdirp dist lib", @@ -33,7 +33,10 @@ "build-cjs": "rollup -i lib/blob-util.js -f cjs -o dist/blob-util.cjs.js", "build-umd": "rollup -i lib/blob-util.js -f umd -n blobUtil -o dist/blob-util.js", "min": "uglifyjs dist/blob-util.js -mc > dist/blob-util.min.js", - "doc": "typedoc --out docs-tmp --target ES6 --theme markdown --mdHideSources src" + "doc": "run-s cleanup-doc gen-doc gen-readme cleanup-doc", + "gen-doc": "typedoc --out docs-tmp --target ES6 --theme markdown --mdHideSources --excludePrivate src", + "gen-readme": "node bin/write-docs-to-readme.js", + "cleanup-doc": "rimraf docs-tmp" }, "devDependencies": { "bundle-collapser": "^1.1.4", @@ -45,6 +48,7 @@ "mocha": "~1.18", "native-or-lie": "1.0.2", "npm-run-all": "^4.1.3", + "pify": "^3.0.0", "request": "^2.36.0", "rimraf": "^2.6.2", "rollup": "^0.59.1", diff --git a/src/blob-util.ts b/src/blob-util.ts index 8485bd8..9ba861a 100644 --- a/src/blob-util.ts +++ b/src/blob-util.ts @@ -3,12 +3,18 @@ /* exported createObjectURL, revokeObjectURL, binaryStringToBlob, blobToDataURL, imgSrcToDataURL, imgSrcToBlob, arrayBufferToBlob, blobToArrayBuffer */ +/** @private */ declare var BlobBuilder: any +/** @private */ declare var MozBlobBuilder: any +/** @private */ declare var MSBlobBuilder: any +/** @private */ declare var WebKitBlobBuilder: any +/** @private */ declare var webkitURL: any +/** @private */ function loadImage (src, crossOrigin) { return new Promise(function (resolve, reject) { var img = new Image() @@ -23,6 +29,7 @@ function loadImage (src, crossOrigin) { }) } +/** @private */ function imgToCanvas (img) { var canvas = document.createElement('canvas') @@ -41,44 +48,18 @@ function imgToCanvas (img) { return canvas } -/** - * Convert a binary string to an ArrayBuffer. - * @param binary - binary string - * @returns array buffer - */ -export function binaryStringToArrayBuffer (binary: string): ArrayBuffer { - var length = binary.length - var buf = new ArrayBuffer(length) - var arr = new Uint8Array(buf) - var i = -1 - while (++i < length) { - arr[i] = binary.charCodeAt(i) - } - return buf -} - -/** - * Convert an ArrayBuffer to a binary string. - * @param buffer - array buffer - * @returns binary string - */ -export function arrayBufferToBinaryString (buffer: ArrayBuffer): string { - var binary = '' - var bytes = new Uint8Array(buffer) - var length = bytes.byteLength - var i = -1 - while (++i < length) { - binary += String.fromCharCode(bytes[i]) - } - return binary -} - /** * Shim for * {@link https://developer.mozilla.org/en-US/docs/Web/API/Blob.Blob | new Blob()} * to support * {@link http://caniuse.com/blob | older browsers that use the deprecated BlobBuilder API}. * + * Example: + * + * ```js + * var myBlob = blobUtil.createBlob(['hello world'], {type: 'text/plain'}); + * ``` + * * @param parts - content of the Blob * @param properties - usually {type: myContentType}, * you can also pass a string for the content type @@ -113,6 +94,13 @@ export function createBlob (parts: Array, properties?: BlobPropertyBag | st * {@link https://developer.mozilla.org/en-US/docs/Web/API/URL.createObjectURL | URL.createObjectURL()} * to support browsers that only have the prefixed * webkitURL (e.g. Android <4.4). + * + * Example: + * + * ```js + * var myUrl = blobUtil.createObjectURL(blob); + * ``` + * * @param blob * @returns url */ @@ -125,6 +113,13 @@ export function createObjectURL (blob: Blob): string { * {@link https://developer.mozilla.org/en-US/docs/Web/API/URL.revokeObjectURL | URL.revokeObjectURL()} * to support browsers that only have the prefixed * webkitURL (e.g. Android <4.4). + * + * Example: + * + * ```js + * blobUtil.revokeObjectURL(myUrl); + * ``` + * * @param url */ export function revokeObjectURL (url: string): void { @@ -134,6 +129,16 @@ export function revokeObjectURL (url: string): void { /** * Convert a Blob to a binary string. * + * Example: + * + * ```js + * blobUtil.blobToBinaryString(blob).then(function (binaryString) { + * // success + * }).catch(function (err) { + * // error + * }); + * ``` + * * @param blob * @returns Promise that resolves with the binary string */ @@ -159,6 +164,12 @@ export function blobToBinaryString (blob: Blob): Promise { /** * Convert a base64-encoded string to a Blob. + * + * Example: + * + * ```js + * var blob = blobUtil.base64StringToBlob(base64String); + * ``` * @param base64 - base64-encoded string * @param type - the content type (optional) * @returns Blob @@ -170,6 +181,13 @@ export function base64StringToBlob (base64: string, type?: string): Blob { /** * Convert a binary string to a Blob. + * + * Example: + * + * ```js + * var blob = blobUtil.binaryStringToBlob(binaryString); + * ``` + * * @param binary - binary string * @param type - the content type (optional) * @returns Blob @@ -180,6 +198,17 @@ export function binaryStringToBlob (binary: string, type?: string): Blob { /** * Convert a Blob to a binary string. + * + * Example: + * + * ```js + * blobUtil.blobToBase64String(blob).then(function (base64String) { + * // success + * }).catch(function (err) { + * // error + * }); + * ``` + * * @param blob * @returns Promise that resolves with the binary string */ @@ -191,6 +220,13 @@ export function blobToBase64String (blob: Blob): Promise { * Convert a data URL string * (e.g. 'data:image/png;base64,iVBORw0KG...') * to a Blob. + * + * Example: + * + * ```js + * var blob = blobUtil.dataURLToBlob(dataURL); + * ``` + * * @param dataURL - dataURL-encoded string * @returns Blob */ @@ -205,6 +241,13 @@ export function dataURLToBlob (dataURL: string): Blob { /** * Convert a Blob to a data URL string * (e.g. 'data:image/png;base64,iVBORw0KG...'). + * + * Example: + * + * ```js + * var dataURL = blobUtil.blobToDataURL(blob); + * ``` + * * @param blob * @returns Promise that resolves with the data URL string */ @@ -218,9 +261,28 @@ export function blobToDataURL (blob: Blob): Promise { * 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 + * 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 + * }); + * ``` + * * @param src - image src * @param type - the content type (optional, defaults to 'image/png') * @param crossOrigin - for CORS-enabled images, set this to @@ -239,7 +301,29 @@ export function imgSrcToDataURL (src: string, type?: string, crossOrigin?: strin /** * Convert a canvas to a Blob. - * @param canvas + * + * 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 + * }); + * ``` + * + * @param canvas - HTMLCanvasElement * @param type - the content type (optional, defaults to 'image/png') * @param quality - a number between 0 and 1 indicating image quality * if the requested type is 'image/jpeg' or 'image/webp' @@ -258,9 +342,28 @@ export function canvasToBlob (canvas: HTMLCanvasElement, type?: string, 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 + * 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 + * }); + * ``` + * * @param src - image src * @param type - the content type (optional, defaults to 'image/png') * @param crossOrigin - for CORS-enabled images, set this to @@ -280,6 +383,12 @@ export function imgSrcToBlob (src: string, type?: string, crossOrigin?: string, /** * Convert an ArrayBuffer to a Blob. * + * Example: + * + * ```js + * var blob = blobUtil.arrayBufferToBlob(arrayBuff, 'audio/mpeg'); + * ``` + * * @param buffer * @param type - the content type (optional) * @returns Blob @@ -290,6 +399,17 @@ export function arrayBufferToBlob (buffer: ArrayBuffer, type?: string): Blob { /** * Convert a Blob to an ArrayBuffer. + * + * Example: + * + * ```js + * blobUtil.blobToArrayBuffer(blob).then(function (arrayBuff) { + * // success + * }).catch(function (err) { + * // error + * }); + * ``` + * * @param blob * @returns Promise that resolves with the ArrayBuffer */ @@ -304,3 +424,47 @@ export function blobToArrayBuffer (blob: Blob): Promise { reader.readAsArrayBuffer(blob) }) } + +/** + * Convert an ArrayBuffer to a binary string. + * + * Example: + * + * ```js + * var myString = blobUtil.arrayBufferToBinaryString(arrayBuff) + * ``` + * + * @param buffer - array buffer + * @returns binary string + */ +export function arrayBufferToBinaryString (buffer: ArrayBuffer): string { + var binary = '' + var bytes = new Uint8Array(buffer) + var length = bytes.byteLength + var i = -1 + while (++i < length) { + binary += String.fromCharCode(bytes[i]) + } + return binary +} + +/** + * Convert a binary string to an ArrayBuffer. + * + * ```js + * var myBuffer = blobUtil.binaryStringToArrayBuffer(binaryString) + * ``` + * + * @param binary - binary string + * @returns array buffer + */ +export function binaryStringToArrayBuffer (binary: string): ArrayBuffer { + var length = binary.length + var buf = new ArrayBuffer(length) + var arr = new Uint8Array(buf) + var i = -1 + while (++i < length) { + arr[i] = binary.charCodeAt(i) + } + return buf +}